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: sqlite.h.in,v 1.200 2007/03/28 13:07:41 drh Exp $ 16*/ 17#ifndef _SQLITE3_H_ 18#define _SQLITE3_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 25extern "C" { 26#endif 27 28/* 29** The version of the SQLite library. 30*/ 31#ifdef SQLITE_VERSION 32# undef SQLITE_VERSION 33#endif 34#define SQLITE_VERSION "--VERS--" 35 36/* 37** The format of the version string is "X.Y.Z<trailing string>", where 38** X is the major version number, Y is the minor version number and Z 39** is the release number. The trailing string is often "alpha" or "beta". 40** For example "3.1.1beta". 41** 42** The SQLITE_VERSION_NUMBER is an integer with the value 43** (X*100000 + Y*1000 + Z). For example, for version "3.1.1beta", 44** SQLITE_VERSION_NUMBER is set to 3001001. To detect if they are using 45** version 3.1.1 or greater at compile time, programs may use the test 46** (SQLITE_VERSION_NUMBER>=3001001). 47*/ 48#ifdef SQLITE_VERSION_NUMBER 49# undef SQLITE_VERSION_NUMBER 50#endif 51#define SQLITE_VERSION_NUMBER --VERSION-NUMBER-- 52 53/* 54** The version string is also compiled into the library so that a program 55** can check to make sure that the lib*.a file and the *.h file are from 56** the same version. The sqlite3_libversion() function returns a pointer 57** to the sqlite3_version variable - useful in DLLs which cannot access 58** global variables. 59*/ 60extern const char sqlite3_version[]; 61const char *sqlite3_libversion(void); 62 63/* 64** Return the value of the SQLITE_VERSION_NUMBER macro when the 65** library was compiled. 66*/ 67int sqlite3_libversion_number(void); 68 69/* 70** Each open sqlite database is represented by an instance of the 71** following opaque structure. 72*/ 73typedef struct sqlite3 sqlite3; 74 75 76/* 77** Some compilers do not support the "long long" datatype. So we have 78** to do a typedef that for 64-bit integers that depends on what compiler 79** is being used. 80*/ 81#ifdef SQLITE_INT64_TYPE 82 typedef SQLITE_INT64_TYPE sqlite_int64; 83 typedef unsigned SQLITE_INT64_TYPE sqlite_uint64; 84#elif defined(_MSC_VER) || defined(__BORLANDC__) 85 typedef __int64 sqlite_int64; 86 typedef unsigned __int64 sqlite_uint64; 87#else 88 typedef long long int sqlite_int64; 89 typedef unsigned long long int sqlite_uint64; 90#endif 91 92/* 93** If compiling for a processor that lacks floating point support, 94** substitute integer for floating-point 95*/ 96#ifdef SQLITE_OMIT_FLOATING_POINT 97# define double sqlite_int64 98#endif 99 100/* 101** A function to close the database. 102** 103** Call this function with a pointer to a structure that was previously 104** returned from sqlite3_open() and the corresponding database will by closed. 105** 106** All SQL statements prepared using sqlite3_prepare() or 107** sqlite3_prepare16() must be deallocated using sqlite3_finalize() before 108** this routine is called. Otherwise, SQLITE_BUSY is returned and the 109** database connection remains open. 110*/ 111int sqlite3_close(sqlite3 *); 112 113/* 114** The type for a callback function. 115*/ 116typedef int (*sqlite3_callback)(void*,int,char**, char**); 117 118/* 119** A function to executes one or more statements of SQL. 120** 121** If one or more of the SQL statements are queries, then 122** the callback function specified by the 3rd parameter is 123** invoked once for each row of the query result. This callback 124** should normally return 0. If the callback returns a non-zero 125** value then the query is aborted, all subsequent SQL statements 126** are skipped and the sqlite3_exec() function returns the SQLITE_ABORT. 127** 128** The 1st parameter is an arbitrary pointer that is passed 129** to the callback function as its first parameter. 130** 131** The 2nd parameter to the callback function is the number of 132** columns in the query result. The 3rd parameter to the callback 133** is an array of strings holding the values for each column. 134** The 4th parameter to the callback is an array of strings holding 135** the names of each column. 136** 137** The callback function may be NULL, even for queries. A NULL 138** callback is not an error. It just means that no callback 139** will be invoked. 140** 141** If an error occurs while parsing or evaluating the SQL (but 142** not while executing the callback) then an appropriate error 143** message is written into memory obtained from malloc() and 144** *errmsg is made to point to that message. The calling function 145** is responsible for freeing the memory that holds the error 146** message. Use sqlite3_free() for this. If errmsg==NULL, 147** then no error message is ever written. 148** 149** The return value is is SQLITE_OK if there are no errors and 150** some other return code if there is an error. The particular 151** return value depends on the type of error. 152** 153** If the query could not be executed because a database file is 154** locked or busy, then this function returns SQLITE_BUSY. (This 155** behavior can be modified somewhat using the sqlite3_busy_handler() 156** and sqlite3_busy_timeout() functions below.) 157*/ 158int sqlite3_exec( 159 sqlite3*, /* An open database */ 160 const char *sql, /* SQL to be executed */ 161 sqlite3_callback, /* Callback function */ 162 void *, /* 1st argument to callback function */ 163 char **errmsg /* Error msg written here */ 164); 165 166/* 167** Return values for sqlite3_exec() and sqlite3_step() 168*/ 169#define SQLITE_OK 0 /* Successful result */ 170/* beginning-of-error-codes */ 171#define SQLITE_ERROR 1 /* SQL error or missing database */ 172#define SQLITE_INTERNAL 2 /* NOT USED. Internal logic error in SQLite */ 173#define SQLITE_PERM 3 /* Access permission denied */ 174#define SQLITE_ABORT 4 /* Callback routine requested an abort */ 175#define SQLITE_BUSY 5 /* The database file is locked */ 176#define SQLITE_LOCKED 6 /* A table in the database is locked */ 177#define SQLITE_NOMEM 7 /* A malloc() failed */ 178#define SQLITE_READONLY 8 /* Attempt to write a readonly database */ 179#define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite3_interrupt()*/ 180#define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */ 181#define SQLITE_CORRUPT 11 /* The database disk image is malformed */ 182#define SQLITE_NOTFOUND 12 /* NOT USED. Table or record not found */ 183#define SQLITE_FULL 13 /* Insertion failed because database is full */ 184#define SQLITE_CANTOPEN 14 /* Unable to open the database file */ 185#define SQLITE_PROTOCOL 15 /* Database lock protocol error */ 186#define SQLITE_EMPTY 16 /* Database is empty */ 187#define SQLITE_SCHEMA 17 /* The database schema changed */ 188#define SQLITE_TOOBIG 18 /* NOT USED. Too much data for one row */ 189#define SQLITE_CONSTRAINT 19 /* Abort due to contraint violation */ 190#define SQLITE_MISMATCH 20 /* Data type mismatch */ 191#define SQLITE_MISUSE 21 /* Library used incorrectly */ 192#define SQLITE_NOLFS 22 /* Uses OS features not supported on host */ 193#define SQLITE_AUTH 23 /* Authorization denied */ 194#define SQLITE_FORMAT 24 /* Auxiliary database format error */ 195#define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */ 196#define SQLITE_NOTADB 26 /* File opened that is not a database file */ 197#define SQLITE_ROW 100 /* sqlite3_step() has another row ready */ 198#define SQLITE_DONE 101 /* sqlite3_step() has finished executing */ 199/* end-of-error-codes */ 200 201/* 202** Using the sqlite3_extended_result_codes() API, you can cause 203** SQLite to return result codes with additional information in 204** their upper bits. The lower 8 bits will be the same as the 205** primary result codes above. But the upper bits might contain 206** more specific error information. 207** 208** To extract the primary result code from an extended result code, 209** simply mask off the lower 8 bits. 210** 211** primary = extended & 0xff; 212** 213** New result error codes may be added from time to time. Software 214** that uses the extended result codes should plan accordingly and be 215** sure to always handle new unknown codes gracefully. 216** 217** The SQLITE_OK result code will never be extended. It will always 218** be exactly zero. 219** 220** The extended result codes always have the primary result code 221** as a prefix. Primary result codes only contain a single "_" 222** character. Extended result codes contain two or more "_" characters. 223*/ 224#define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8)) 225#define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8)) 226#define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8)) 227#define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4<<8)) 228#define SQLITE_IOERR_DIR_FSYNC (SQLITE_IOERR | (5<<8)) 229#define SQLITE_IOERR_TRUNCATE (SQLITE_IOERR | (6<<8)) 230#define SQLITE_IOERR_FSTAT (SQLITE_IOERR | (7<<8)) 231#define SQLITE_IOERR_UNLOCK (SQLITE_IOERR | (8<<8)) 232#define SQLITE_IOERR_RDLOCK (SQLITE_IOERR | (9<<8)) 233#define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8)) 234 235/* 236** Enable or disable the extended result codes. 237*/ 238int sqlite3_extended_result_codes(sqlite3*, int onoff); 239 240/* 241** Each entry in an SQLite table has a unique integer key. (The key is 242** the value of the INTEGER PRIMARY KEY column if there is such a column, 243** otherwise the key is generated automatically. The unique key is always 244** available as the ROWID, OID, or _ROWID_ column.) The following routine 245** returns the integer key of the most recent insert in the database. 246*/ 247sqlite_int64 sqlite3_last_insert_rowid(sqlite3*); 248 249/* 250** This function returns the number of database rows that were changed 251** (or inserted or deleted) by the most recent SQL statement. Only 252** changes that are directly specified by the INSERT, UPDATE, or 253** DELETE statement are counted. Auxiliary changes caused by 254** triggers are not counted. Within the body of a trigger, however, 255** the sqlite3_changes() API can be called to find the number of 256** changes in the most recently completed INSERT, UPDATE, or DELETE 257** statement within the body of the trigger. 258** 259** All changes are counted, even if they were later undone by a 260** ROLLBACK or ABORT. Except, changes associated with creating and 261** dropping tables are not counted. 262** 263** If a callback invokes sqlite3_exec() or sqlite3_step() recursively, 264** then the changes in the inner, recursive call are counted together 265** with the changes in the outer call. 266** 267** SQLite implements the command "DELETE FROM table" without a WHERE clause 268** by dropping and recreating the table. (This is much faster than going 269** through and deleting individual elements form the table.) Because of 270** this optimization, the change count for "DELETE FROM table" will be 271** zero regardless of the number of elements that were originally in the 272** table. To get an accurate count of the number of rows deleted, use 273** "DELETE FROM table WHERE 1" instead. 274*/ 275int sqlite3_changes(sqlite3*); 276 277/* 278** This function returns the number of database rows that have been 279** modified by INSERT, UPDATE or DELETE statements since the database handle 280** was opened. This includes UPDATE, INSERT and DELETE statements executed 281** as part of trigger programs. All changes are counted as soon as the 282** statement that makes them is completed (when the statement handle is 283** passed to sqlite3_reset() or sqlite_finalise()). 284** 285** SQLite implements the command "DELETE FROM table" without a WHERE clause 286** by dropping and recreating the table. (This is much faster than going 287** through and deleting individual elements form the table.) Because of 288** this optimization, the change count for "DELETE FROM table" will be 289** zero regardless of the number of elements that were originally in the 290** table. To get an accurate count of the number of rows deleted, use 291** "DELETE FROM table WHERE 1" instead. 292*/ 293int sqlite3_total_changes(sqlite3*); 294 295/* This function causes any pending database operation to abort and 296** return at its earliest opportunity. This routine is typically 297** called in response to a user action such as pressing "Cancel" 298** or Ctrl-C where the user wants a long query operation to halt 299** immediately. 300** 301** It is safe to call this routine from a different thread that the 302** thread that is currently running the database operation. 303*/ 304void sqlite3_interrupt(sqlite3*); 305 306 307/* These functions return true if the given input string comprises 308** one or more complete SQL statements. For the sqlite3_complete() call, 309** the parameter must be a nul-terminated UTF-8 string. For 310** sqlite3_complete16(), a nul-terminated machine byte order UTF-16 string 311** is required. 312** 313** This routine is useful for command-line input to see of the user has 314** entered a complete statement of SQL or if the current statement needs 315** to be continued on the next line. The algorithm is simple. If the 316** last token other than spaces and comments is a semicolon, then return 317** true. Actually, the algorithm is a little more complicated than that 318** in order to deal with triggers, but the basic idea is the same: the 319** statement is not complete unless it ends in a semicolon. 320*/ 321int sqlite3_complete(const char *sql); 322int sqlite3_complete16(const void *sql); 323 324/* 325** This routine identifies a callback function that is invoked 326** whenever an attempt is made to open a database table that is 327** currently locked by another process or thread. If the busy callback 328** is NULL, then sqlite3_exec() returns SQLITE_BUSY immediately if 329** it finds a locked table. If the busy callback is not NULL, then 330** sqlite3_exec() invokes the callback with two arguments. The 331** first argument to the handler is a copy of the void* pointer which 332** is the third argument to this routine. The second argument to 333** the handler is the number of times that the busy handler has 334** been invoked for this locking event. If the 335** busy callback returns 0, then sqlite3_exec() immediately returns 336** SQLITE_BUSY. If the callback returns non-zero, then sqlite3_exec() 337** tries to open the table again and the cycle repeats. 338** 339** The presence of a busy handler does not guarantee that 340** it will be invoked when there is lock contention. 341** If SQLite determines that invoking the busy handler could result in 342** a deadlock, it will return SQLITE_BUSY instead. 343** Consider a scenario where one process is holding a read lock that 344** it is trying to promote to a reserved lock and 345** a second process is holding a reserved lock that it is trying 346** to promote to an exclusive lock. The first process cannot proceed 347** because it is blocked by the second and the second process cannot 348** proceed because it is blocked by the first. If both processes 349** invoke the busy handlers, neither will make any progress. Therefore, 350** SQLite returns SQLITE_BUSY for the first process, hoping that this 351** will induce the first process to release its read lock and allow 352** the second process to proceed. 353** 354** The default busy callback is NULL. 355** 356** Sqlite is re-entrant, so the busy handler may start a new query. 357** (It is not clear why anyone would every want to do this, but it 358** is allowed, in theory.) But the busy handler may not close the 359** database. Closing the database from a busy handler will delete 360** data structures out from under the executing query and will 361** probably result in a coredump. 362*/ 363int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*); 364 365/* 366** This routine sets a busy handler that sleeps for a while when a 367** table is locked. The handler will sleep multiple times until 368** at least "ms" milleseconds of sleeping have been done. After 369** "ms" milleseconds of sleeping, the handler returns 0 which 370** causes sqlite3_exec() to return SQLITE_BUSY. 371** 372** Calling this routine with an argument less than or equal to zero 373** turns off all busy handlers. 374*/ 375int sqlite3_busy_timeout(sqlite3*, int ms); 376 377/* 378** This next routine is really just a wrapper around sqlite3_exec(). 379** Instead of invoking a user-supplied callback for each row of the 380** result, this routine remembers each row of the result in memory 381** obtained from malloc(), then returns all of the result after the 382** query has finished. 383** 384** As an example, suppose the query result where this table: 385** 386** Name | Age 387** ----------------------- 388** Alice | 43 389** Bob | 28 390** Cindy | 21 391** 392** If the 3rd argument were &azResult then after the function returns 393** azResult will contain the following data: 394** 395** azResult[0] = "Name"; 396** azResult[1] = "Age"; 397** azResult[2] = "Alice"; 398** azResult[3] = "43"; 399** azResult[4] = "Bob"; 400** azResult[5] = "28"; 401** azResult[6] = "Cindy"; 402** azResult[7] = "21"; 403** 404** Notice that there is an extra row of data containing the column 405** headers. But the *nrow return value is still 3. *ncolumn is 406** set to 2. In general, the number of values inserted into azResult 407** will be ((*nrow) + 1)*(*ncolumn). 408** 409** After the calling function has finished using the result, it should 410** pass the result data pointer to sqlite3_free_table() in order to 411** release the memory that was malloc-ed. Because of the way the 412** malloc() happens, the calling function must not try to call 413** free() directly. Only sqlite3_free_table() is able to release 414** the memory properly and safely. 415** 416** The return value of this routine is the same as from sqlite3_exec(). 417*/ 418int sqlite3_get_table( 419 sqlite3*, /* An open database */ 420 const char *sql, /* SQL to be executed */ 421 char ***resultp, /* Result written to a char *[] that this points to */ 422 int *nrow, /* Number of result rows written here */ 423 int *ncolumn, /* Number of result columns written here */ 424 char **errmsg /* Error msg written here */ 425); 426 427/* 428** Call this routine to free the memory that sqlite3_get_table() allocated. 429*/ 430void sqlite3_free_table(char **result); 431 432/* 433** The following routines are variants of the "sprintf()" from the 434** standard C library. The resulting string is written into memory 435** obtained from malloc() so that there is never a possiblity of buffer 436** overflow. These routines also implement some additional formatting 437** options that are useful for constructing SQL statements. 438** 439** The strings returned by these routines should be freed by calling 440** sqlite3_free(). 441** 442** All of the usual printf formatting options apply. In addition, there 443** is a "%q" option. %q works like %s in that it substitutes a null-terminated 444** string from the argument list. But %q also doubles every '\'' character. 445** %q is designed for use inside a string literal. By doubling each '\'' 446** character it escapes that character and allows it to be inserted into 447** the string. 448** 449** For example, so some string variable contains text as follows: 450** 451** char *zText = "It's a happy day!"; 452** 453** We can use this text in an SQL statement as follows: 454** 455** char *z = sqlite3_mprintf("INSERT INTO TABLES('%q')", zText); 456** sqlite3_exec(db, z, callback1, 0, 0); 457** sqlite3_free(z); 458** 459** Because the %q format string is used, the '\'' character in zText 460** is escaped and the SQL generated is as follows: 461** 462** INSERT INTO table1 VALUES('It''s a happy day!') 463** 464** This is correct. Had we used %s instead of %q, the generated SQL 465** would have looked like this: 466** 467** INSERT INTO table1 VALUES('It's a happy day!'); 468** 469** This second example is an SQL syntax error. As a general rule you 470** should always use %q instead of %s when inserting text into a string 471** literal. 472*/ 473char *sqlite3_mprintf(const char*,...); 474char *sqlite3_vmprintf(const char*, va_list); 475char *sqlite3_snprintf(int,char*,const char*, ...); 476 477/* 478** SQLite uses its own memory allocator. On many installations, this 479** memory allocator is identical to the standard malloc()/realloc()/free() 480** and can be used interchangable. On others, the implementations are 481** different. For maximum portability, it is best not to mix calls 482** to the standard malloc/realloc/free with the sqlite versions. 483*/ 484void *sqlite3_malloc(int); 485void *sqlite3_realloc(void*, int); 486void sqlite3_free(void*); 487 488#ifndef SQLITE_OMIT_AUTHORIZATION 489/* 490** This routine registers a callback with the SQLite library. The 491** callback is invoked (at compile-time, not at run-time) for each 492** attempt to access a column of a table in the database. The callback 493** returns SQLITE_OK if access is allowed, SQLITE_DENY if the entire 494** SQL statement should be aborted with an error and SQLITE_IGNORE 495** if the column should be treated as a NULL value. 496*/ 497int sqlite3_set_authorizer( 498 sqlite3*, 499 int (*xAuth)(void*,int,const char*,const char*,const char*,const char*), 500 void *pUserData 501); 502#endif 503 504/* 505** The second parameter to the access authorization function above will 506** be one of the values below. These values signify what kind of operation 507** is to be authorized. The 3rd and 4th parameters to the authorization 508** function will be parameters or NULL depending on which of the following 509** codes is used as the second parameter. The 5th parameter is the name 510** of the database ("main", "temp", etc.) if applicable. The 6th parameter 511** is the name of the inner-most trigger or view that is responsible for 512** the access attempt or NULL if this access attempt is directly from 513** input SQL code. 514** 515** Arg-3 Arg-4 516*/ 517#define SQLITE_COPY 0 /* Table Name File Name */ 518#define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */ 519#define SQLITE_CREATE_TABLE 2 /* Table Name NULL */ 520#define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */ 521#define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */ 522#define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */ 523#define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */ 524#define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */ 525#define SQLITE_CREATE_VIEW 8 /* View Name NULL */ 526#define SQLITE_DELETE 9 /* Table Name NULL */ 527#define SQLITE_DROP_INDEX 10 /* Index Name Table Name */ 528#define SQLITE_DROP_TABLE 11 /* Table Name NULL */ 529#define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */ 530#define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */ 531#define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */ 532#define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */ 533#define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */ 534#define SQLITE_DROP_VIEW 17 /* View Name NULL */ 535#define SQLITE_INSERT 18 /* Table Name NULL */ 536#define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */ 537#define SQLITE_READ 20 /* Table Name Column Name */ 538#define SQLITE_SELECT 21 /* NULL NULL */ 539#define SQLITE_TRANSACTION 22 /* NULL NULL */ 540#define SQLITE_UPDATE 23 /* Table Name Column Name */ 541#define SQLITE_ATTACH 24 /* Filename NULL */ 542#define SQLITE_DETACH 25 /* Database Name NULL */ 543#define SQLITE_ALTER_TABLE 26 /* Database Name Table Name */ 544#define SQLITE_REINDEX 27 /* Index Name NULL */ 545#define SQLITE_ANALYZE 28 /* Table Name NULL */ 546#define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */ 547#define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */ 548#define SQLITE_FUNCTION 31 /* Function Name NULL */ 549 550/* 551** The return value of the authorization function should be one of the 552** following constants: 553*/ 554/* #define SQLITE_OK 0 // Allow access (This is actually defined above) */ 555#define SQLITE_DENY 1 /* Abort the SQL statement with an error */ 556#define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */ 557 558/* 559** Register a function for tracing SQL command evaluation. The function 560** registered by sqlite3_trace() is invoked at the first sqlite3_step() 561** for the evaluation of an SQL statement. The function registered by 562** sqlite3_profile() runs at the end of each SQL statement and includes 563** information on how long that statement ran. 564** 565** The sqlite3_profile() API is currently considered experimental and 566** is subject to change. 567*/ 568void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*); 569void *sqlite3_profile(sqlite3*, 570 void(*xProfile)(void*,const char*,sqlite_uint64), void*); 571 572/* 573** This routine configures a callback function - the progress callback - that 574** is invoked periodically during long running calls to sqlite3_exec(), 575** sqlite3_step() and sqlite3_get_table(). An example use for this API is to 576** keep a GUI updated during a large query. 577** 578** The progress callback is invoked once for every N virtual machine opcodes, 579** where N is the second argument to this function. The progress callback 580** itself is identified by the third argument to this function. The fourth 581** argument to this function is a void pointer passed to the progress callback 582** function each time it is invoked. 583** 584** If a call to sqlite3_exec(), sqlite3_step() or sqlite3_get_table() results 585** in less than N opcodes being executed, then the progress callback is not 586** invoked. 587** 588** To remove the progress callback altogether, pass NULL as the third 589** argument to this function. 590** 591** If the progress callback returns a result other than 0, then the current 592** query is immediately terminated and any database changes rolled back. If the 593** query was part of a larger transaction, then the transaction is not rolled 594** back and remains active. The sqlite3_exec() call returns SQLITE_ABORT. 595** 596******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ****** 597*/ 598void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*); 599 600/* 601** Register a callback function to be invoked whenever a new transaction 602** is committed. The pArg argument is passed through to the callback. 603** callback. If the callback function returns non-zero, then the commit 604** is converted into a rollback. 605** 606** If another function was previously registered, its pArg value is returned. 607** Otherwise NULL is returned. 608** 609** Registering a NULL function disables the callback. 610** 611******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ****** 612*/ 613void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*); 614 615/* 616** Open the sqlite database file "filename". The "filename" is UTF-8 617** encoded for sqlite3_open() and UTF-16 encoded in the native byte order 618** for sqlite3_open16(). An sqlite3* handle is returned in *ppDb, even 619** if an error occurs. If the database is opened (or created) successfully, 620** then SQLITE_OK is returned. Otherwise an error code is returned. The 621** sqlite3_errmsg() or sqlite3_errmsg16() routines can be used to obtain 622** an English language description of the error. 623** 624** If the database file does not exist, then a new database is created. 625** The encoding for the database is UTF-8 if sqlite3_open() is called and 626** UTF-16 if sqlite3_open16 is used. 627** 628** Whether or not an error occurs when it is opened, resources associated 629** with the sqlite3* handle should be released by passing it to 630** sqlite3_close() when it is no longer required. 631*/ 632int sqlite3_open( 633 const char *filename, /* Database filename (UTF-8) */ 634 sqlite3 **ppDb /* OUT: SQLite db handle */ 635); 636int sqlite3_open16( 637 const void *filename, /* Database filename (UTF-16) */ 638 sqlite3 **ppDb /* OUT: SQLite db handle */ 639); 640 641/* 642** Return the error code for the most recent sqlite3_* API call associated 643** with sqlite3 handle 'db'. SQLITE_OK is returned if the most recent 644** API call was successful. 645** 646** Calls to many sqlite3_* functions set the error code and string returned 647** by sqlite3_errcode(), sqlite3_errmsg() and sqlite3_errmsg16() 648** (overwriting the previous values). Note that calls to sqlite3_errcode(), 649** sqlite3_errmsg() and sqlite3_errmsg16() themselves do not affect the 650** results of future invocations. 651** 652** Assuming no other intervening sqlite3_* API calls are made, the error 653** code returned by this function is associated with the same error as 654** the strings returned by sqlite3_errmsg() and sqlite3_errmsg16(). 655*/ 656int sqlite3_errcode(sqlite3 *db); 657 658/* 659** Return a pointer to a UTF-8 encoded string describing in english the 660** error condition for the most recent sqlite3_* API call. The returned 661** string is always terminated by an 0x00 byte. 662** 663** The string "not an error" is returned when the most recent API call was 664** successful. 665*/ 666const char *sqlite3_errmsg(sqlite3*); 667 668/* 669** Return a pointer to a UTF-16 native byte order encoded string describing 670** in english the error condition for the most recent sqlite3_* API call. 671** The returned string is always terminated by a pair of 0x00 bytes. 672** 673** The string "not an error" is returned when the most recent API call was 674** successful. 675*/ 676const void *sqlite3_errmsg16(sqlite3*); 677 678/* 679** An instance of the following opaque structure is used to represent 680** a compiled SQL statment. 681*/ 682typedef struct sqlite3_stmt sqlite3_stmt; 683 684/* 685** To execute an SQL query, it must first be compiled into a byte-code 686** program using one of the following routines. The only difference between 687** them is that the second argument, specifying the SQL statement to 688** compile, is assumed to be encoded in UTF-8 for the sqlite3_prepare() 689** function and UTF-16 for sqlite3_prepare16(). 690** 691** The first parameter "db" is an SQLite database handle. The second 692** parameter "zSql" is the statement to be compiled, encoded as either 693** UTF-8 or UTF-16 (see above). If the next parameter, "nBytes", is less 694** than zero, then zSql is read up to the first nul terminator. If 695** "nBytes" is not less than zero, then it is the length of the string zSql 696** in bytes (not characters). 697** 698** *pzTail is made to point to the first byte past the end of the first 699** SQL statement in zSql. This routine only compiles the first statement 700** in zSql, so *pzTail is left pointing to what remains uncompiled. 701** 702** *ppStmt is left pointing to a compiled SQL statement that can be 703** executed using sqlite3_step(). Or if there is an error, *ppStmt may be 704** set to NULL. If the input text contained no SQL (if the input is and 705** empty string or a comment) then *ppStmt is set to NULL. 706** 707** On success, SQLITE_OK is returned. Otherwise an error code is returned. 708*/ 709int sqlite3_prepare( 710 sqlite3 *db, /* Database handle */ 711 const char *zSql, /* SQL statement, UTF-8 encoded */ 712 int nBytes, /* Length of zSql in bytes. */ 713 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ 714 const char **pzTail /* OUT: Pointer to unused portion of zSql */ 715); 716int sqlite3_prepare16( 717 sqlite3 *db, /* Database handle */ 718 const void *zSql, /* SQL statement, UTF-16 encoded */ 719 int nBytes, /* Length of zSql in bytes. */ 720 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ 721 const void **pzTail /* OUT: Pointer to unused portion of zSql */ 722); 723 724/* 725** Newer versions of the prepare API work just like the legacy versions 726** but with one exception: The a copy of the SQL text is saved in the 727** sqlite3_stmt structure that is returned. If this copy exists, it 728** modifieds the behavior of sqlite3_step() slightly. First, sqlite3_step() 729** will no longer return an SQLITE_SCHEMA error but will instead automatically 730** rerun the compiler to rebuild the prepared statement. Secondly, 731** sqlite3_step() now turns a full result code - the result code that 732** use used to have to call sqlite3_reset() to get. 733*/ 734int sqlite3_prepare_v2( 735 sqlite3 *db, /* Database handle */ 736 const char *zSql, /* SQL statement, UTF-8 encoded */ 737 int nBytes, /* Length of zSql in bytes. */ 738 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ 739 const char **pzTail /* OUT: Pointer to unused portion of zSql */ 740); 741int sqlite3_prepare16_v2( 742 sqlite3 *db, /* Database handle */ 743 const void *zSql, /* SQL statement, UTF-16 encoded */ 744 int nBytes, /* Length of zSql in bytes. */ 745 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ 746 const void **pzTail /* OUT: Pointer to unused portion of zSql */ 747); 748 749/* 750** Pointers to the following two opaque structures are used to communicate 751** with the implementations of user-defined functions. 752*/ 753typedef struct sqlite3_context sqlite3_context; 754typedef struct Mem sqlite3_value; 755 756/* 757** In the SQL strings input to sqlite3_prepare() and sqlite3_prepare16(), 758** one or more literals can be replace by parameters "?" or "?NNN" or 759** ":AAA" or "@AAA" or "$VVV" where NNN is a integer, AAA is an identifer, 760** and VVV is a variable name according to the syntax rules of the 761** TCL programming language. The value of these parameters (also called 762** "host parameter names") can be set using the routines listed below. 763** 764** In every case, the first argument is a pointer to the sqlite3_stmt 765** structure returned from sqlite3_prepare(). The second argument is the 766** index of the host parameter name. The first host parameter as an index 767** of 1. For named host parameters (":AAA" or "$VVV") you can use 768** sqlite3_bind_parameter_index() to get the correct index value given 769** the parameter name. If the same named parameter occurs more than 770** once, it is assigned the same index each time. 771** 772** The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and 773** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or 774** text after SQLite has finished with it. If the fifth argument is the 775** special value SQLITE_STATIC, then the library assumes that the information 776** is in static, unmanaged space and does not need to be freed. If the 777** fifth argument has the value SQLITE_TRANSIENT, then SQLite makes its 778** own private copy of the data before the sqlite3_bind_* routine returns. 779** 780** The sqlite3_bind_* routine must be called before sqlite3_step() and after 781** an sqlite3_prepare() or sqlite3_reset(). Bindings persist across 782** multiple calls to sqlite3_reset() and sqlite3_step(). Unbound parameters 783** are interpreted as NULL. 784*/ 785int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*)); 786int sqlite3_bind_double(sqlite3_stmt*, int, double); 787int sqlite3_bind_int(sqlite3_stmt*, int, int); 788int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite_int64); 789int sqlite3_bind_null(sqlite3_stmt*, int); 790int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*)); 791int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*)); 792int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*); 793 794/* 795** Return the number of host parameters in a compiled SQL statement. This 796** routine was added to support DBD::SQLite. 797*/ 798int sqlite3_bind_parameter_count(sqlite3_stmt*); 799 800/* 801** Return the name of the i-th name parameter. Ordinary parameters "?" are 802** nameless and a NULL is returned. For parameters of the form :AAA or 803** $VVV the complete text of the parameter name is returned, including 804** the initial ":" or "$". NULL is returned if the index is out of range. 805*/ 806const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int); 807 808/* 809** Return the index of a parameter with the given name. The name 810** must match exactly. If no parameter with the given name is found, 811** return 0. 812*/ 813int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName); 814 815/* 816** Set all the parameters in the compiled SQL statement to NULL. 817*/ 818int sqlite3_clear_bindings(sqlite3_stmt*); 819 820/* 821** Return the number of columns in the result set returned by the compiled 822** SQL statement. This routine returns 0 if pStmt is an SQL statement 823** that does not return data (for example an UPDATE). 824*/ 825int sqlite3_column_count(sqlite3_stmt *pStmt); 826 827/* 828** The first parameter is a compiled SQL statement. This function returns 829** the column heading for the Nth column of that statement, where N is the 830** second function parameter. The string returned is UTF-8 for 831** sqlite3_column_name() and UTF-16 for sqlite3_column_name16(). 832*/ 833const char *sqlite3_column_name(sqlite3_stmt*,int); 834const void *sqlite3_column_name16(sqlite3_stmt*,int); 835 836/* 837** The first argument to the following calls is a compiled SQL statement. 838** These functions return information about the Nth column returned by 839** the statement, where N is the second function argument. 840** 841** If the Nth column returned by the statement is not a column value, 842** then all of the functions return NULL. Otherwise, the return the 843** name of the attached database, table and column that the expression 844** extracts a value from. 845** 846** As with all other SQLite APIs, those postfixed with "16" return UTF-16 847** encoded strings, the other functions return UTF-8. The memory containing 848** the returned strings is valid until the statement handle is finalized(). 849** 850** These APIs are only available if the library was compiled with the 851** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined. 852*/ 853const char *sqlite3_column_database_name(sqlite3_stmt*,int); 854const void *sqlite3_column_database_name16(sqlite3_stmt*,int); 855const char *sqlite3_column_table_name(sqlite3_stmt*,int); 856const void *sqlite3_column_table_name16(sqlite3_stmt*,int); 857const char *sqlite3_column_origin_name(sqlite3_stmt*,int); 858const void *sqlite3_column_origin_name16(sqlite3_stmt*,int); 859 860/* 861** The first parameter is a compiled SQL statement. If this statement 862** is a SELECT statement, the Nth column of the returned result set 863** of the SELECT is a table column then the declared type of the table 864** column is returned. If the Nth column of the result set is not at table 865** column, then a NULL pointer is returned. The returned string is always 866** UTF-8 encoded. For example, in the database schema: 867** 868** CREATE TABLE t1(c1 VARIANT); 869** 870** And the following statement compiled: 871** 872** SELECT c1 + 1, c1 FROM t1; 873** 874** Then this routine would return the string "VARIANT" for the second 875** result column (i==1), and a NULL pointer for the first result column 876** (i==0). 877*/ 878const char *sqlite3_column_decltype(sqlite3_stmt *, int i); 879 880/* 881** The first parameter is a compiled SQL statement. If this statement 882** is a SELECT statement, the Nth column of the returned result set 883** of the SELECT is a table column then the declared type of the table 884** column is returned. If the Nth column of the result set is not at table 885** column, then a NULL pointer is returned. The returned string is always 886** UTF-16 encoded. For example, in the database schema: 887** 888** CREATE TABLE t1(c1 INTEGER); 889** 890** And the following statement compiled: 891** 892** SELECT c1 + 1, c1 FROM t1; 893** 894** Then this routine would return the string "INTEGER" for the second 895** result column (i==1), and a NULL pointer for the first result column 896** (i==0). 897*/ 898const void *sqlite3_column_decltype16(sqlite3_stmt*,int); 899 900/* 901** After an SQL query has been compiled with a call to either 902** sqlite3_prepare() or sqlite3_prepare16(), then this function must be 903** called one or more times to execute the statement. 904** 905** The return value will be either SQLITE_BUSY, SQLITE_DONE, 906** SQLITE_ROW, SQLITE_ERROR, or SQLITE_MISUSE. 907** 908** SQLITE_BUSY means that the database engine attempted to open 909** a locked database and there is no busy callback registered. 910** Call sqlite3_step() again to retry the open. 911** 912** SQLITE_DONE means that the statement has finished executing 913** successfully. sqlite3_step() should not be called again on this virtual 914** machine. 915** 916** If the SQL statement being executed returns any data, then 917** SQLITE_ROW is returned each time a new row of data is ready 918** for processing by the caller. The values may be accessed using 919** the sqlite3_column_*() functions described below. sqlite3_step() 920** is called again to retrieve the next row of data. 921** 922** SQLITE_ERROR means that a run-time error (such as a constraint 923** violation) has occurred. sqlite3_step() should not be called again on 924** the VM. More information may be found by calling sqlite3_errmsg(). 925** 926** SQLITE_MISUSE means that the this routine was called inappropriately. 927** Perhaps it was called on a virtual machine that had already been 928** finalized or on one that had previously returned SQLITE_ERROR or 929** SQLITE_DONE. Or it could be the case the the same database connection 930** is being used simulataneously by two or more threads. 931*/ 932int sqlite3_step(sqlite3_stmt*); 933 934/* 935** Return the number of values in the current row of the result set. 936** 937** After a call to sqlite3_step() that returns SQLITE_ROW, this routine 938** will return the same value as the sqlite3_column_count() function. 939** After sqlite3_step() has returned an SQLITE_DONE, SQLITE_BUSY or 940** error code, or before sqlite3_step() has been called on a 941** compiled SQL statement, this routine returns zero. 942*/ 943int sqlite3_data_count(sqlite3_stmt *pStmt); 944 945/* 946** Values are stored in the database in one of the following fundamental 947** types. 948*/ 949#define SQLITE_INTEGER 1 950#define SQLITE_FLOAT 2 951/* #define SQLITE_TEXT 3 // See below */ 952#define SQLITE_BLOB 4 953#define SQLITE_NULL 5 954 955/* 956** SQLite version 2 defines SQLITE_TEXT differently. To allow both 957** version 2 and version 3 to be included, undefine them both if a 958** conflict is seen. Define SQLITE3_TEXT to be the version 3 value. 959*/ 960#ifdef SQLITE_TEXT 961# undef SQLITE_TEXT 962#else 963# define SQLITE_TEXT 3 964#endif 965#define SQLITE3_TEXT 3 966 967/* 968** The next group of routines returns information about the information 969** in a single column of the current result row of a query. In every 970** case the first parameter is a pointer to the SQL statement that is being 971** executed (the sqlite_stmt* that was returned from sqlite3_prepare()) and 972** the second argument is the index of the column for which information 973** should be returned. iCol is zero-indexed. The left-most column as an 974** index of 0. 975** 976** If the SQL statement is not currently point to a valid row, or if the 977** the colulmn index is out of range, the result is undefined. 978** 979** These routines attempt to convert the value where appropriate. For 980** example, if the internal representation is FLOAT and a text result 981** is requested, sprintf() is used internally to do the conversion 982** automatically. The following table details the conversions that 983** are applied: 984** 985** Internal Type Requested Type Conversion 986** ------------- -------------- -------------------------- 987** NULL INTEGER Result is 0 988** NULL FLOAT Result is 0.0 989** NULL TEXT Result is an empty string 990** NULL BLOB Result is a zero-length BLOB 991** INTEGER FLOAT Convert from integer to float 992** INTEGER TEXT ASCII rendering of the integer 993** INTEGER BLOB Same as for INTEGER->TEXT 994** FLOAT INTEGER Convert from float to integer 995** FLOAT TEXT ASCII rendering of the float 996** FLOAT BLOB Same as FLOAT->TEXT 997** TEXT INTEGER Use atoi() 998** TEXT FLOAT Use atof() 999** TEXT BLOB No change 1000** BLOB INTEGER Convert to TEXT then use atoi() 1001** BLOB FLOAT Convert to TEXT then use atof() 1002** BLOB TEXT Add a \000 terminator if needed 1003** 1004** The following access routines are provided: 1005** 1006** _type() Return the datatype of the result. This is one of 1007** SQLITE_INTEGER, SQLITE_FLOAT, SQLITE_TEXT, SQLITE_BLOB, 1008** or SQLITE_NULL. 1009** _blob() Return the value of a BLOB. 1010** _bytes() Return the number of bytes in a BLOB value or the number 1011** of bytes in a TEXT value represented as UTF-8. The \000 1012** terminator is included in the byte count for TEXT values. 1013** _bytes16() Return the number of bytes in a BLOB value or the number 1014** of bytes in a TEXT value represented as UTF-16. The \u0000 1015** terminator is included in the byte count for TEXT values. 1016** _double() Return a FLOAT value. 1017** _int() Return an INTEGER value in the host computer's native 1018** integer representation. This might be either a 32- or 64-bit 1019** integer depending on the host. 1020** _int64() Return an INTEGER value as a 64-bit signed integer. 1021** _text() Return the value as UTF-8 text. 1022** _text16() Return the value as UTF-16 text. 1023*/ 1024const void *sqlite3_column_blob(sqlite3_stmt*, int iCol); 1025int sqlite3_column_bytes(sqlite3_stmt*, int iCol); 1026int sqlite3_column_bytes16(sqlite3_stmt*, int iCol); 1027double sqlite3_column_double(sqlite3_stmt*, int iCol); 1028int sqlite3_column_int(sqlite3_stmt*, int iCol); 1029sqlite_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol); 1030const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol); 1031const void *sqlite3_column_text16(sqlite3_stmt*, int iCol); 1032int sqlite3_column_type(sqlite3_stmt*, int iCol); 1033int sqlite3_column_numeric_type(sqlite3_stmt*, int iCol); 1034sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol); 1035 1036/* 1037** The sqlite3_finalize() function is called to delete a compiled 1038** SQL statement obtained by a previous call to sqlite3_prepare() 1039** or sqlite3_prepare16(). If the statement was executed successfully, or 1040** not executed at all, then SQLITE_OK is returned. If execution of the 1041** statement failed then an error code is returned. 1042** 1043** This routine can be called at any point during the execution of the 1044** virtual machine. If the virtual machine has not completed execution 1045** when this routine is called, that is like encountering an error or 1046** an interrupt. (See sqlite3_interrupt().) Incomplete updates may be 1047** rolled back and transactions cancelled, depending on the circumstances, 1048** and the result code returned will be SQLITE_ABORT. 1049*/ 1050int sqlite3_finalize(sqlite3_stmt *pStmt); 1051 1052/* 1053** The sqlite3_reset() function is called to reset a compiled SQL 1054** statement obtained by a previous call to sqlite3_prepare() or 1055** sqlite3_prepare16() back to it's initial state, ready to be re-executed. 1056** Any SQL statement variables that had values bound to them using 1057** the sqlite3_bind_*() API retain their values. 1058*/ 1059int sqlite3_reset(sqlite3_stmt *pStmt); 1060 1061/* 1062** The following two functions are used to add user functions or aggregates 1063** implemented in C to the SQL langauge interpreted by SQLite. The 1064** difference only between the two is that the second parameter, the 1065** name of the (scalar) function or aggregate, is encoded in UTF-8 for 1066** sqlite3_create_function() and UTF-16 for sqlite3_create_function16(). 1067** 1068** The first argument is the database handle that the new function or 1069** aggregate is to be added to. If a single program uses more than one 1070** database handle internally, then user functions or aggregates must 1071** be added individually to each database handle with which they will be 1072** used. 1073** 1074** The third parameter is the number of arguments that the function or 1075** aggregate takes. If this parameter is negative, then the function or 1076** aggregate may take any number of arguments. 1077** 1078** The fourth parameter is one of SQLITE_UTF* values defined below, 1079** indicating the encoding that the function is most likely to handle 1080** values in. This does not change the behaviour of the programming 1081** interface. However, if two versions of the same function are registered 1082** with different encoding values, SQLite invokes the version likely to 1083** minimize conversions between text encodings. 1084** 1085** The seventh, eighth and ninth parameters, xFunc, xStep and xFinal, are 1086** pointers to user implemented C functions that implement the user 1087** function or aggregate. A scalar function requires an implementation of 1088** the xFunc callback only, NULL pointers should be passed as the xStep 1089** and xFinal parameters. An aggregate function requires an implementation 1090** of xStep and xFinal, but NULL should be passed for xFunc. To delete an 1091** existing user function or aggregate, pass NULL for all three function 1092** callback. Specifying an inconstent set of callback values, such as an 1093** xFunc and an xFinal, or an xStep but no xFinal, SQLITE_ERROR is 1094** returned. 1095*/ 1096int sqlite3_create_function( 1097 sqlite3 *, 1098 const char *zFunctionName, 1099 int nArg, 1100 int eTextRep, 1101 void*, 1102 void (*xFunc)(sqlite3_context*,int,sqlite3_value**), 1103 void (*xStep)(sqlite3_context*,int,sqlite3_value**), 1104 void (*xFinal)(sqlite3_context*) 1105); 1106int sqlite3_create_function16( 1107 sqlite3*, 1108 const void *zFunctionName, 1109 int nArg, 1110 int eTextRep, 1111 void*, 1112 void (*xFunc)(sqlite3_context*,int,sqlite3_value**), 1113 void (*xStep)(sqlite3_context*,int,sqlite3_value**), 1114 void (*xFinal)(sqlite3_context*) 1115); 1116 1117/* 1118** This function is deprecated. Do not use it. It continues to exist 1119** so as not to break legacy code. But new code should avoid using it. 1120*/ 1121int sqlite3_aggregate_count(sqlite3_context*); 1122 1123/* 1124** The next group of routines returns information about parameters to 1125** a user-defined function. Function implementations use these routines 1126** to access their parameters. These routines are the same as the 1127** sqlite3_column_* routines except that these routines take a single 1128** sqlite3_value* pointer instead of an sqlite3_stmt* and an integer 1129** column number. 1130*/ 1131const void *sqlite3_value_blob(sqlite3_value*); 1132int sqlite3_value_bytes(sqlite3_value*); 1133int sqlite3_value_bytes16(sqlite3_value*); 1134double sqlite3_value_double(sqlite3_value*); 1135int sqlite3_value_int(sqlite3_value*); 1136sqlite_int64 sqlite3_value_int64(sqlite3_value*); 1137const unsigned char *sqlite3_value_text(sqlite3_value*); 1138const void *sqlite3_value_text16(sqlite3_value*); 1139const void *sqlite3_value_text16le(sqlite3_value*); 1140const void *sqlite3_value_text16be(sqlite3_value*); 1141int sqlite3_value_type(sqlite3_value*); 1142int sqlite3_value_numeric_type(sqlite3_value*); 1143 1144/* 1145** Aggregate functions use the following routine to allocate 1146** a structure for storing their state. The first time this routine 1147** is called for a particular aggregate, a new structure of size nBytes 1148** is allocated, zeroed, and returned. On subsequent calls (for the 1149** same aggregate instance) the same buffer is returned. The implementation 1150** of the aggregate can use the returned buffer to accumulate data. 1151** 1152** The buffer allocated is freed automatically by SQLite. 1153*/ 1154void *sqlite3_aggregate_context(sqlite3_context*, int nBytes); 1155 1156/* 1157** The pUserData parameter to the sqlite3_create_function() 1158** routine used to register user functions is available to 1159** the implementation of the function using this call. 1160*/ 1161void *sqlite3_user_data(sqlite3_context*); 1162 1163/* 1164** The following two functions may be used by scalar user functions to 1165** associate meta-data with argument values. If the same value is passed to 1166** multiple invocations of the user-function during query execution, under 1167** some circumstances the associated meta-data may be preserved. This may 1168** be used, for example, to add a regular-expression matching scalar 1169** function. The compiled version of the regular expression is stored as 1170** meta-data associated with the SQL value passed as the regular expression 1171** pattern. 1172** 1173** Calling sqlite3_get_auxdata() returns a pointer to the meta data 1174** associated with the Nth argument value to the current user function 1175** call, where N is the second parameter. If no meta-data has been set for 1176** that value, then a NULL pointer is returned. 1177** 1178** The sqlite3_set_auxdata() is used to associate meta data with a user 1179** function argument. The third parameter is a pointer to the meta data 1180** to be associated with the Nth user function argument value. The fourth 1181** parameter specifies a 'delete function' that will be called on the meta 1182** data pointer to release it when it is no longer required. If the delete 1183** function pointer is NULL, it is not invoked. 1184** 1185** In practice, meta-data is preserved between function calls for 1186** expressions that are constant at compile time. This includes literal 1187** values and SQL variables. 1188*/ 1189void *sqlite3_get_auxdata(sqlite3_context*, int); 1190void sqlite3_set_auxdata(sqlite3_context*, int, void*, void (*)(void*)); 1191 1192 1193/* 1194** These are special value for the destructor that is passed in as the 1195** final argument to routines like sqlite3_result_blob(). If the destructor 1196** argument is SQLITE_STATIC, it means that the content pointer is constant 1197** and will never change. It does not need to be destroyed. The 1198** SQLITE_TRANSIENT value means that the content will likely change in 1199** the near future and that SQLite should make its own private copy of 1200** the content before returning. 1201** 1202** The typedef is necessary to work around problems in certain 1203** C++ compilers. See ticket #2191. 1204*/ 1205typedef void (*sqlite3_destructor_type)(void*); 1206#define SQLITE_STATIC ((sqlite3_destructor_type)0) 1207#define SQLITE_TRANSIENT ((sqlite3_destructor_type)-1) 1208 1209/* 1210** User-defined functions invoke the following routines in order to 1211** set their return value. 1212*/ 1213void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*)); 1214void sqlite3_result_double(sqlite3_context*, double); 1215void sqlite3_result_error(sqlite3_context*, const char*, int); 1216void sqlite3_result_error16(sqlite3_context*, const void*, int); 1217void sqlite3_result_int(sqlite3_context*, int); 1218void sqlite3_result_int64(sqlite3_context*, sqlite_int64); 1219void sqlite3_result_null(sqlite3_context*); 1220void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*)); 1221void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*)); 1222void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*)); 1223void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*)); 1224void sqlite3_result_value(sqlite3_context*, sqlite3_value*); 1225 1226/* 1227** These are the allowed values for the eTextRep argument to 1228** sqlite3_create_collation and sqlite3_create_function. 1229*/ 1230#define SQLITE_UTF8 1 1231#define SQLITE_UTF16LE 2 1232#define SQLITE_UTF16BE 3 1233#define SQLITE_UTF16 4 /* Use native byte order */ 1234#define SQLITE_ANY 5 /* sqlite3_create_function only */ 1235#define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */ 1236 1237/* 1238** These two functions are used to add new collation sequences to the 1239** sqlite3 handle specified as the first argument. 1240** 1241** The name of the new collation sequence is specified as a UTF-8 string 1242** for sqlite3_create_collation() and a UTF-16 string for 1243** sqlite3_create_collation16(). In both cases the name is passed as the 1244** second function argument. 1245** 1246** The third argument must be one of the constants SQLITE_UTF8, 1247** SQLITE_UTF16LE or SQLITE_UTF16BE, indicating that the user-supplied 1248** routine expects to be passed pointers to strings encoded using UTF-8, 1249** UTF-16 little-endian or UTF-16 big-endian respectively. 1250** 1251** A pointer to the user supplied routine must be passed as the fifth 1252** argument. If it is NULL, this is the same as deleting the collation 1253** sequence (so that SQLite cannot call it anymore). Each time the user 1254** supplied function is invoked, it is passed a copy of the void* passed as 1255** the fourth argument to sqlite3_create_collation() or 1256** sqlite3_create_collation16() as its first parameter. 1257** 1258** The remaining arguments to the user-supplied routine are two strings, 1259** each represented by a [length, data] pair and encoded in the encoding 1260** that was passed as the third argument when the collation sequence was 1261** registered. The user routine should return negative, zero or positive if 1262** the first string is less than, equal to, or greater than the second 1263** string. i.e. (STRING1 - STRING2). 1264*/ 1265int sqlite3_create_collation( 1266 sqlite3*, 1267 const char *zName, 1268 int eTextRep, 1269 void*, 1270 int(*xCompare)(void*,int,const void*,int,const void*) 1271); 1272int sqlite3_create_collation16( 1273 sqlite3*, 1274 const char *zName, 1275 int eTextRep, 1276 void*, 1277 int(*xCompare)(void*,int,const void*,int,const void*) 1278); 1279 1280/* 1281** To avoid having to register all collation sequences before a database 1282** can be used, a single callback function may be registered with the 1283** database handle to be called whenever an undefined collation sequence is 1284** required. 1285** 1286** If the function is registered using the sqlite3_collation_needed() API, 1287** then it is passed the names of undefined collation sequences as strings 1288** encoded in UTF-8. If sqlite3_collation_needed16() is used, the names 1289** are passed as UTF-16 in machine native byte order. A call to either 1290** function replaces any existing callback. 1291** 1292** When the user-function is invoked, the first argument passed is a copy 1293** of the second argument to sqlite3_collation_needed() or 1294** sqlite3_collation_needed16(). The second argument is the database 1295** handle. The third argument is one of SQLITE_UTF8, SQLITE_UTF16BE or 1296** SQLITE_UTF16LE, indicating the most desirable form of the collation 1297** sequence function required. The fourth parameter is the name of the 1298** required collation sequence. 1299** 1300** The collation sequence is returned to SQLite by a collation-needed 1301** callback using the sqlite3_create_collation() or 1302** sqlite3_create_collation16() APIs, described above. 1303*/ 1304int sqlite3_collation_needed( 1305 sqlite3*, 1306 void*, 1307 void(*)(void*,sqlite3*,int eTextRep,const char*) 1308); 1309int sqlite3_collation_needed16( 1310 sqlite3*, 1311 void*, 1312 void(*)(void*,sqlite3*,int eTextRep,const void*) 1313); 1314 1315/* 1316** Specify the key for an encrypted database. This routine should be 1317** called right after sqlite3_open(). 1318** 1319** The code to implement this API is not available in the public release 1320** of SQLite. 1321*/ 1322int sqlite3_key( 1323 sqlite3 *db, /* Database to be rekeyed */ 1324 const void *pKey, int nKey /* The key */ 1325); 1326 1327/* 1328** Change the key on an open database. If the current database is not 1329** encrypted, this routine will encrypt it. If pNew==0 or nNew==0, the 1330** database is decrypted. 1331** 1332** The code to implement this API is not available in the public release 1333** of SQLite. 1334*/ 1335int sqlite3_rekey( 1336 sqlite3 *db, /* Database to be rekeyed */ 1337 const void *pKey, int nKey /* The new key */ 1338); 1339 1340/* 1341** Sleep for a little while. The second parameter is the number of 1342** miliseconds to sleep for. 1343** 1344** If the operating system does not support sleep requests with 1345** milisecond time resolution, then the time will be rounded up to 1346** the nearest second. The number of miliseconds of sleep actually 1347** requested from the operating system is returned. 1348*/ 1349int sqlite3_sleep(int); 1350 1351/* 1352** Return TRUE (non-zero) if the statement supplied as an argument needs 1353** to be recompiled. A statement needs to be recompiled whenever the 1354** execution environment changes in a way that would alter the program 1355** that sqlite3_prepare() generates. For example, if new functions or 1356** collating sequences are registered or if an authorizer function is 1357** added or changed. 1358** 1359*/ 1360int sqlite3_expired(sqlite3_stmt*); 1361 1362/* 1363** Move all bindings from the first prepared statement over to the second. 1364** This routine is useful, for example, if the first prepared statement 1365** fails with an SQLITE_SCHEMA error. The same SQL can be prepared into 1366** the second prepared statement then all of the bindings transfered over 1367** to the second statement before the first statement is finalized. 1368*/ 1369int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*); 1370 1371/* 1372** If the following global variable is made to point to a 1373** string which is the name of a directory, then all temporary files 1374** created by SQLite will be placed in that directory. If this variable 1375** is NULL pointer, then SQLite does a search for an appropriate temporary 1376** file directory. 1377** 1378** Once sqlite3_open() has been called, changing this variable will invalidate 1379** the current temporary database, if any. 1380*/ 1381extern char *sqlite3_temp_directory; 1382 1383/* 1384** This function is called to recover from a malloc() failure that occured 1385** within the SQLite library. Normally, after a single malloc() fails the 1386** library refuses to function (all major calls return SQLITE_NOMEM). 1387** This function restores the library state so that it can be used again. 1388** 1389** All existing statements (sqlite3_stmt pointers) must be finalized or 1390** reset before this call is made. Otherwise, SQLITE_BUSY is returned. 1391** If any in-memory databases are in use, either as a main or TEMP 1392** database, SQLITE_ERROR is returned. In either of these cases, the 1393** library is not reset and remains unusable. 1394** 1395** This function is *not* threadsafe. Calling this from within a threaded 1396** application when threads other than the caller have used SQLite is 1397** dangerous and will almost certainly result in malfunctions. 1398** 1399** This functionality can be omitted from a build by defining the 1400** SQLITE_OMIT_GLOBALRECOVER at compile time. 1401*/ 1402int sqlite3_global_recover(void); 1403 1404/* 1405** Test to see whether or not the database connection is in autocommit 1406** mode. Return TRUE if it is and FALSE if not. Autocommit mode is on 1407** by default. Autocommit is disabled by a BEGIN statement and reenabled 1408** by the next COMMIT or ROLLBACK. 1409*/ 1410int sqlite3_get_autocommit(sqlite3*); 1411 1412/* 1413** Return the sqlite3* database handle to which the prepared statement given 1414** in the argument belongs. This is the same database handle that was 1415** the first argument to the sqlite3_prepare() that was used to create 1416** the statement in the first place. 1417*/ 1418sqlite3 *sqlite3_db_handle(sqlite3_stmt*); 1419 1420/* 1421** Register a callback function with the database connection identified by the 1422** first argument to be invoked whenever a row is updated, inserted or deleted. 1423** Any callback set by a previous call to this function for the same 1424** database connection is overridden. 1425** 1426** The second argument is a pointer to the function to invoke when a 1427** row is updated, inserted or deleted. The first argument to the callback is 1428** a copy of the third argument to sqlite3_update_hook. The second callback 1429** argument is one of SQLITE_INSERT, SQLITE_DELETE or SQLITE_UPDATE, depending 1430** on the operation that caused the callback to be invoked. The third and 1431** fourth arguments to the callback contain pointers to the database and 1432** table name containing the affected row. The final callback parameter is 1433** the rowid of the row. In the case of an update, this is the rowid after 1434** the update takes place. 1435** 1436** The update hook is not invoked when internal system tables are 1437** modified (i.e. sqlite_master and sqlite_sequence). 1438** 1439** If another function was previously registered, its pArg value is returned. 1440** Otherwise NULL is returned. 1441*/ 1442void *sqlite3_update_hook( 1443 sqlite3*, 1444 void(*)(void *,int ,char const *,char const *,sqlite_int64), 1445 void* 1446); 1447 1448/* 1449** Register a callback to be invoked whenever a transaction is rolled 1450** back. 1451** 1452** The new callback function overrides any existing rollback-hook 1453** callback. If there was an existing callback, then it's pArg value 1454** (the third argument to sqlite3_rollback_hook() when it was registered) 1455** is returned. Otherwise, NULL is returned. 1456** 1457** For the purposes of this API, a transaction is said to have been 1458** rolled back if an explicit "ROLLBACK" statement is executed, or 1459** an error or constraint causes an implicit rollback to occur. The 1460** callback is not invoked if a transaction is automatically rolled 1461** back because the database connection is closed. 1462*/ 1463void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*); 1464 1465/* 1466** This function is only available if the library is compiled without 1467** the SQLITE_OMIT_SHARED_CACHE macro defined. It is used to enable or 1468** disable (if the argument is true or false, respectively) the 1469** "shared pager" feature. 1470*/ 1471int sqlite3_enable_shared_cache(int); 1472 1473/* 1474** Attempt to free N bytes of heap memory by deallocating non-essential 1475** memory allocations held by the database library (example: memory 1476** used to cache database pages to improve performance). 1477** 1478** This function is not a part of standard builds. It is only created 1479** if SQLite is compiled with the SQLITE_ENABLE_MEMORY_MANAGEMENT macro. 1480*/ 1481int sqlite3_release_memory(int); 1482 1483/* 1484** Place a "soft" limit on the amount of heap memory that may be allocated by 1485** SQLite within the current thread. If an internal allocation is requested 1486** that would exceed the specified limit, sqlite3_release_memory() is invoked 1487** one or more times to free up some space before the allocation is made. 1488** 1489** The limit is called "soft", because if sqlite3_release_memory() cannot free 1490** sufficient memory to prevent the limit from being exceeded, the memory is 1491** allocated anyway and the current operation proceeds. 1492** 1493** This function is only available if the library was compiled with the 1494** SQLITE_ENABLE_MEMORY_MANAGEMENT option set. 1495** memory-management has been enabled. 1496*/ 1497void sqlite3_soft_heap_limit(int); 1498 1499/* 1500** This routine makes sure that all thread-local storage has been 1501** deallocated for the current thread. 1502** 1503** This routine is not technically necessary. All thread-local storage 1504** will be automatically deallocated once memory-management and 1505** shared-cache are disabled and the soft heap limit has been set 1506** to zero. This routine is provided as a convenience for users who 1507** want to make absolutely sure they have not forgotten something 1508** prior to killing off a thread. 1509*/ 1510void sqlite3_thread_cleanup(void); 1511 1512/* 1513** Return meta information about a specific column of a specific database 1514** table accessible using the connection handle passed as the first function 1515** argument. 1516** 1517** The column is identified by the second, third and fourth parameters to 1518** this function. The second parameter is either the name of the database 1519** (i.e. "main", "temp" or an attached database) containing the specified 1520** table or NULL. If it is NULL, then all attached databases are searched 1521** for the table using the same algorithm as the database engine uses to 1522** resolve unqualified table references. 1523** 1524** The third and fourth parameters to this function are the table and column 1525** name of the desired column, respectively. Neither of these parameters 1526** may be NULL. 1527** 1528** Meta information is returned by writing to the memory locations passed as 1529** the 5th and subsequent parameters to this function. Any of these 1530** arguments may be NULL, in which case the corresponding element of meta 1531** information is ommitted. 1532** 1533** Parameter Output Type Description 1534** ----------------------------------- 1535** 1536** 5th const char* Data type 1537** 6th const char* Name of the default collation sequence 1538** 7th int True if the column has a NOT NULL constraint 1539** 8th int True if the column is part of the PRIMARY KEY 1540** 9th int True if the column is AUTOINCREMENT 1541** 1542** 1543** The memory pointed to by the character pointers returned for the 1544** declaration type and collation sequence is valid only until the next 1545** call to any sqlite API function. 1546** 1547** If the specified table is actually a view, then an error is returned. 1548** 1549** If the specified column is "rowid", "oid" or "_rowid_" and an 1550** INTEGER PRIMARY KEY column has been explicitly declared, then the output 1551** parameters are set for the explicitly declared column. If there is no 1552** explicitly declared IPK column, then the output parameters are set as 1553** follows: 1554** 1555** data type: "INTEGER" 1556** collation sequence: "BINARY" 1557** not null: 0 1558** primary key: 1 1559** auto increment: 0 1560** 1561** This function may load one or more schemas from database files. If an 1562** error occurs during this process, or if the requested table or column 1563** cannot be found, an SQLITE error code is returned and an error message 1564** left in the database handle (to be retrieved using sqlite3_errmsg()). 1565** 1566** This API is only available if the library was compiled with the 1567** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined. 1568*/ 1569int sqlite3_table_column_metadata( 1570 sqlite3 *db, /* Connection handle */ 1571 const char *zDbName, /* Database name or NULL */ 1572 const char *zTableName, /* Table name */ 1573 const char *zColumnName, /* Column name */ 1574 char const **pzDataType, /* OUTPUT: Declared data type */ 1575 char const **pzCollSeq, /* OUTPUT: Collation sequence name */ 1576 int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */ 1577 int *pPrimaryKey, /* OUTPUT: True if column part of PK */ 1578 int *pAutoinc /* OUTPUT: True if colums is auto-increment */ 1579); 1580 1581/* 1582****** EXPERIMENTAL - subject to change without notice ************** 1583** 1584** Attempt to load an SQLite extension library contained in the file 1585** zFile. The entry point is zProc. zProc may be 0 in which case the 1586** name of the entry point defaults to "sqlite3_extension_init". 1587** 1588** Return SQLITE_OK on success and SQLITE_ERROR if something goes wrong. 1589** 1590** If an error occurs and pzErrMsg is not 0, then fill *pzErrMsg with 1591** error message text. The calling function should free this memory 1592** by calling sqlite3_free(). 1593** 1594** Extension loading must be enabled using sqlite3_enable_load_extension() 1595** prior to calling this API or an error will be returned. 1596** 1597****** EXPERIMENTAL - subject to change without notice ************** 1598*/ 1599int sqlite3_load_extension( 1600 sqlite3 *db, /* Load the extension into this database connection */ 1601 const char *zFile, /* Name of the shared library containing extension */ 1602 const char *zProc, /* Entry point. Derived from zFile if 0 */ 1603 char **pzErrMsg /* Put error message here if not 0 */ 1604); 1605 1606/* 1607** So as not to open security holes in older applications that are 1608** unprepared to deal with extension load, and as a means of disabling 1609** extension loading while executing user-entered SQL, the following 1610** API is provided to turn the extension loading mechanism on and 1611** off. It is off by default. See ticket #1863. 1612** 1613** Call this routine with onoff==1 to turn extension loading on 1614** and call it with onoff==0 to turn it back off again. 1615*/ 1616int sqlite3_enable_load_extension(sqlite3 *db, int onoff); 1617 1618/* 1619****** EXPERIMENTAL - subject to change without notice ************** 1620** 1621** Register an extension entry point that is automatically invoked 1622** whenever a new database connection is opened. 1623** 1624** This API can be invoked at program startup in order to register 1625** one or more statically linked extensions that will be available 1626** to all new database connections. 1627** 1628** Duplicate extensions are detected so calling this routine multiple 1629** times with the same extension is harmless. 1630** 1631** This routine stores a pointer to the extension in an array 1632** that is obtained from malloc(). If you run a memory leak 1633** checker on your program and it reports a leak because of this 1634** array, then invoke sqlite3_automatic_extension_reset() prior 1635** to shutdown to free the memory. 1636** 1637** Automatic extensions apply across all threads. 1638*/ 1639int sqlite3_auto_extension(void *xEntryPoint); 1640 1641 1642/* 1643****** EXPERIMENTAL - subject to change without notice ************** 1644** 1645** Disable all previously registered automatic extensions. This 1646** routine undoes the effect of all prior sqlite3_automatic_extension() 1647** calls. 1648** 1649** This call disabled automatic extensions in all threads. 1650*/ 1651void sqlite3_reset_auto_extension(void); 1652 1653 1654/* 1655****** EXPERIMENTAL - subject to change without notice ************** 1656** 1657** The interface to the virtual-table mechanism is currently considered 1658** to be experimental. The interface might change in incompatible ways. 1659** If this is a problem for you, do not use the interface at this time. 1660** 1661** When the virtual-table mechanism stablizes, we will declare the 1662** interface fixed, support it indefinitely, and remove this comment. 1663*/ 1664 1665/* 1666** Structures used by the virtual table interface 1667*/ 1668typedef struct sqlite3_vtab sqlite3_vtab; 1669typedef struct sqlite3_index_info sqlite3_index_info; 1670typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor; 1671typedef struct sqlite3_module sqlite3_module; 1672 1673/* 1674** A module is a class of virtual tables. Each module is defined 1675** by an instance of the following structure. This structure consists 1676** mostly of methods for the module. 1677*/ 1678struct sqlite3_module { 1679 int iVersion; 1680 int (*xCreate)(sqlite3*, void *pAux, 1681 int argc, const char *const*argv, 1682 sqlite3_vtab **ppVTab, char**); 1683 int (*xConnect)(sqlite3*, void *pAux, 1684 int argc, const char *const*argv, 1685 sqlite3_vtab **ppVTab, char**); 1686 int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*); 1687 int (*xDisconnect)(sqlite3_vtab *pVTab); 1688 int (*xDestroy)(sqlite3_vtab *pVTab); 1689 int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor); 1690 int (*xClose)(sqlite3_vtab_cursor*); 1691 int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr, 1692 int argc, sqlite3_value **argv); 1693 int (*xNext)(sqlite3_vtab_cursor*); 1694 int (*xEof)(sqlite3_vtab_cursor*); 1695 int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int); 1696 int (*xRowid)(sqlite3_vtab_cursor*, sqlite_int64 *pRowid); 1697 int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite_int64 *); 1698 int (*xBegin)(sqlite3_vtab *pVTab); 1699 int (*xSync)(sqlite3_vtab *pVTab); 1700 int (*xCommit)(sqlite3_vtab *pVTab); 1701 int (*xRollback)(sqlite3_vtab *pVTab); 1702 int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName, 1703 void (**pxFunc)(sqlite3_context*,int,sqlite3_value**), 1704 void **ppArg); 1705}; 1706 1707/* 1708** The sqlite3_index_info structure and its substructures is used to 1709** pass information into and receive the reply from the xBestIndex 1710** method of an sqlite3_module. The fields under **Inputs** are the 1711** inputs to xBestIndex and are read-only. xBestIndex inserts its 1712** results into the **Outputs** fields. 1713** 1714** The aConstraint[] array records WHERE clause constraints of the 1715** form: 1716** 1717** column OP expr 1718** 1719** Where OP is =, <, <=, >, or >=. The particular operator is stored 1720** in aConstraint[].op. The index of the column is stored in 1721** aConstraint[].iColumn. aConstraint[].usable is TRUE if the 1722** expr on the right-hand side can be evaluated (and thus the constraint 1723** is usable) and false if it cannot. 1724** 1725** The optimizer automatically inverts terms of the form "expr OP column" 1726** and makes other simplificatinos to the WHERE clause in an attempt to 1727** get as many WHERE clause terms into the form shown above as possible. 1728** The aConstraint[] array only reports WHERE clause terms in the correct 1729** form that refer to the particular virtual table being queried. 1730** 1731** Information about the ORDER BY clause is stored in aOrderBy[]. 1732** Each term of aOrderBy records a column of the ORDER BY clause. 1733** 1734** The xBestIndex method must fill aConstraintUsage[] with information 1735** about what parameters to pass to xFilter. If argvIndex>0 then 1736** the right-hand side of the corresponding aConstraint[] is evaluated 1737** and becomes the argvIndex-th entry in argv. If aConstraintUsage[].omit 1738** is true, then the constraint is assumed to be fully handled by the 1739** virtual table and is not checked again by SQLite. 1740** 1741** The idxNum and idxPtr values are recorded and passed into xFilter. 1742** sqlite3_free() is used to free idxPtr if needToFreeIdxPtr is true. 1743** 1744** The orderByConsumed means that output from xFilter will occur in 1745** the correct order to satisfy the ORDER BY clause so that no separate 1746** sorting step is required. 1747** 1748** The estimatedCost value is an estimate of the cost of doing the 1749** particular lookup. A full scan of a table with N entries should have 1750** a cost of N. A binary search of a table of N entries should have a 1751** cost of approximately log(N). 1752*/ 1753struct sqlite3_index_info { 1754 /* Inputs */ 1755 const int nConstraint; /* Number of entries in aConstraint */ 1756 const struct sqlite3_index_constraint { 1757 int iColumn; /* Column on left-hand side of constraint */ 1758 unsigned char op; /* Constraint operator */ 1759 unsigned char usable; /* True if this constraint is usable */ 1760 int iTermOffset; /* Used internally - xBestIndex should ignore */ 1761 } *const aConstraint; /* Table of WHERE clause constraints */ 1762 const int nOrderBy; /* Number of terms in the ORDER BY clause */ 1763 const struct sqlite3_index_orderby { 1764 int iColumn; /* Column number */ 1765 unsigned char desc; /* True for DESC. False for ASC. */ 1766 } *const aOrderBy; /* The ORDER BY clause */ 1767 1768 /* Outputs */ 1769 struct sqlite3_index_constraint_usage { 1770 int argvIndex; /* if >0, constraint is part of argv to xFilter */ 1771 unsigned char omit; /* Do not code a test for this constraint */ 1772 } *const aConstraintUsage; 1773 int idxNum; /* Number used to identify the index */ 1774 char *idxStr; /* String, possibly obtained from sqlite3_malloc */ 1775 int needToFreeIdxStr; /* Free idxStr using sqlite3_free() if true */ 1776 int orderByConsumed; /* True if output is already ordered */ 1777 double estimatedCost; /* Estimated cost of using this index */ 1778}; 1779#define SQLITE_INDEX_CONSTRAINT_EQ 2 1780#define SQLITE_INDEX_CONSTRAINT_GT 4 1781#define SQLITE_INDEX_CONSTRAINT_LE 8 1782#define SQLITE_INDEX_CONSTRAINT_LT 16 1783#define SQLITE_INDEX_CONSTRAINT_GE 32 1784#define SQLITE_INDEX_CONSTRAINT_MATCH 64 1785 1786/* 1787** This routine is used to register a new module name with an SQLite 1788** connection. Module names must be registered before creating new 1789** virtual tables on the module, or before using preexisting virtual 1790** tables of the module. 1791*/ 1792int sqlite3_create_module( 1793 sqlite3 *db, /* SQLite connection to register module with */ 1794 const char *zName, /* Name of the module */ 1795 const sqlite3_module *, /* Methods for the module */ 1796 void * /* Client data for xCreate/xConnect */ 1797); 1798 1799/* 1800** Every module implementation uses a subclass of the following structure 1801** to describe a particular instance of the module. Each subclass will 1802** be taylored to the specific needs of the module implementation. The 1803** purpose of this superclass is to define certain fields that are common 1804** to all module implementations. 1805** 1806** Virtual tables methods can set an error message by assigning a 1807** string obtained from sqlite3_mprintf() to zErrMsg. The method should 1808** take care that any prior string is freed by a call to sqlite3_free() 1809** prior to assigning a new string to zErrMsg. After the error message 1810** is delivered up to the client application, the string will be automatically 1811** freed by sqlite3_free() and the zErrMsg field will be zeroed. Note 1812** that sqlite3_mprintf() and sqlite3_free() are used on the zErrMsg field 1813** since virtual tables are commonly implemented in loadable extensions which 1814** do not have access to sqlite3MPrintf() or sqlite3Free(). 1815*/ 1816struct sqlite3_vtab { 1817 const sqlite3_module *pModule; /* The module for this virtual table */ 1818 int nRef; /* Used internally */ 1819 char *zErrMsg; /* Error message from sqlite3_mprintf() */ 1820 /* Virtual table implementations will typically add additional fields */ 1821}; 1822 1823/* Every module implementation uses a subclass of the following structure 1824** to describe cursors that point into the virtual table and are used 1825** to loop through the virtual table. Cursors are created using the 1826** xOpen method of the module. Each module implementation will define 1827** the content of a cursor structure to suit its own needs. 1828** 1829** This superclass exists in order to define fields of the cursor that 1830** are common to all implementations. 1831*/ 1832struct sqlite3_vtab_cursor { 1833 sqlite3_vtab *pVtab; /* Virtual table of this cursor */ 1834 /* Virtual table implementations will typically add additional fields */ 1835}; 1836 1837/* 1838** The xCreate and xConnect methods of a module use the following API 1839** to declare the format (the names and datatypes of the columns) of 1840** the virtual tables they implement. 1841*/ 1842int sqlite3_declare_vtab(sqlite3*, const char *zCreateTable); 1843 1844/* 1845** Virtual tables can provide alternative implementations of functions 1846** using the xFindFunction method. But global versions of those functions 1847** must exist in order to be overloaded. 1848** 1849** This API makes sure a global version of a function with a particular 1850** name and number of parameters exists. If no such function exists 1851** before this API is called, a new function is created. The implementation 1852** of the new function always causes an exception to be thrown. So 1853** the new function is not good for anything by itself. Its only 1854** purpose is to be a place-holder function that can be overloaded 1855** by virtual tables. 1856** 1857** This API should be considered part of the virtual table interface, 1858** which is experimental and subject to change. 1859*/ 1860int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg); 1861 1862/* 1863** The interface to the virtual-table mechanism defined above (back up 1864** to a comment remarkably similar to this one) is currently considered 1865** to be experimental. The interface might change in incompatible ways. 1866** If this is a problem for you, do not use the interface at this time. 1867** 1868** When the virtual-table mechanism stablizes, we will declare the 1869** interface fixed, support it indefinitely, and remove this comment. 1870** 1871****** EXPERIMENTAL - subject to change without notice ************** 1872*/ 1873 1874/* 1875** Undo the hack that converts floating point types to integer for 1876** builds on processors without floating point support. 1877*/ 1878#ifdef SQLITE_OMIT_FLOATING_POINT 1879# undef double 1880#endif 1881 1882#ifdef __cplusplus 1883} /* End of the 'extern "C"' block */ 1884#endif 1885#endif 1886