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