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