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.141 2005/09/08 10:58:52 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#if defined(_MSC_VER) || defined(__BORLANDC__) 82 typedef __int64 sqlite_int64; 83 typedef unsigned __int64 sqlite_uint64; 84#else 85 typedef long long int sqlite_int64; 86 typedef unsigned long long int sqlite_uint64; 87#endif 88 89 90/* 91** A function to close the database. 92** 93** Call this function with a pointer to a structure that was previously 94** returned from sqlite3_open() and the corresponding database will by closed. 95** 96** All SQL statements prepared using sqlite3_prepare() or 97** sqlite3_prepare16() must be deallocated using sqlite3_finalize() before 98** this routine is called. Otherwise, SQLITE_BUSY is returned and the 99** database connection remains open. 100*/ 101int sqlite3_close(sqlite3 *); 102 103/* 104** The type for a callback function. 105*/ 106typedef int (*sqlite3_callback)(void*,int,char**, char**); 107 108/* 109** A function to executes one or more statements of SQL. 110** 111** If one or more of the SQL statements are queries, then 112** the callback function specified by the 3rd parameter is 113** invoked once for each row of the query result. This callback 114** should normally return 0. If the callback returns a non-zero 115** value then the query is aborted, all subsequent SQL statements 116** are skipped and the sqlite3_exec() function returns the SQLITE_ABORT. 117** 118** The 4th parameter is an arbitrary pointer that is passed 119** to the callback function as its first parameter. 120** 121** The 2nd parameter to the callback function is the number of 122** columns in the query result. The 3rd parameter to the callback 123** is an array of strings holding the values for each column. 124** The 4th parameter to the callback is an array of strings holding 125** the names of each column. 126** 127** The callback function may be NULL, even for queries. A NULL 128** callback is not an error. It just means that no callback 129** will be invoked. 130** 131** If an error occurs while parsing or evaluating the SQL (but 132** not while executing the callback) then an appropriate error 133** message is written into memory obtained from malloc() and 134** *errmsg is made to point to that message. The calling function 135** is responsible for freeing the memory that holds the error 136** message. Use sqlite3_free() for this. If errmsg==NULL, 137** then no error message is ever written. 138** 139** The return value is is SQLITE_OK if there are no errors and 140** some other return code if there is an error. The particular 141** return value depends on the type of error. 142** 143** If the query could not be executed because a database file is 144** locked or busy, then this function returns SQLITE_BUSY. (This 145** behavior can be modified somewhat using the sqlite3_busy_handler() 146** and sqlite3_busy_timeout() functions below.) 147*/ 148int sqlite3_exec( 149 sqlite3*, /* An open database */ 150 const char *sql, /* SQL to be executed */ 151 sqlite3_callback, /* Callback function */ 152 void *, /* 1st argument to callback function */ 153 char **errmsg /* Error msg written here */ 154); 155 156/* 157** Return values for sqlite3_exec() and sqlite3_step() 158*/ 159#define SQLITE_OK 0 /* Successful result */ 160#define SQLITE_ERROR 1 /* SQL error or missing database */ 161#define SQLITE_INTERNAL 2 /* NOT USED. Internal logic error in SQLite */ 162#define SQLITE_PERM 3 /* Access permission denied */ 163#define SQLITE_ABORT 4 /* Callback routine requested an abort */ 164#define SQLITE_BUSY 5 /* The database file is locked */ 165#define SQLITE_LOCKED 6 /* A table in the database is locked */ 166#define SQLITE_NOMEM 7 /* A malloc() failed */ 167#define SQLITE_READONLY 8 /* Attempt to write a readonly database */ 168#define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite3_interrupt()*/ 169#define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */ 170#define SQLITE_CORRUPT 11 /* The database disk image is malformed */ 171#define SQLITE_NOTFOUND 12 /* NOT USED. Table or record not found */ 172#define SQLITE_FULL 13 /* Insertion failed because database is full */ 173#define SQLITE_CANTOPEN 14 /* Unable to open the database file */ 174#define SQLITE_PROTOCOL 15 /* Database lock protocol error */ 175#define SQLITE_EMPTY 16 /* Database is empty */ 176#define SQLITE_SCHEMA 17 /* The database schema changed */ 177#define SQLITE_TOOBIG 18 /* NOT USED. Too much data for one row */ 178#define SQLITE_CONSTRAINT 19 /* Abort due to contraint violation */ 179#define SQLITE_MISMATCH 20 /* Data type mismatch */ 180#define SQLITE_MISUSE 21 /* Library used incorrectly */ 181#define SQLITE_NOLFS 22 /* Uses OS features not supported on host */ 182#define SQLITE_AUTH 23 /* Authorization denied */ 183#define SQLITE_FORMAT 24 /* Auxiliary database format error */ 184#define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */ 185#define SQLITE_NOTADB 26 /* File opened that is not a database file */ 186#define SQLITE_ROW 100 /* sqlite3_step() has another row ready */ 187#define SQLITE_DONE 101 /* sqlite3_step() has finished executing */ 188 189/* 190** Each entry in an SQLite table has a unique integer key. (The key is 191** the value of the INTEGER PRIMARY KEY column if there is such a column, 192** otherwise the key is generated at random. The unique key is always 193** available as the ROWID, OID, or _ROWID_ column.) The following routine 194** returns the integer key of the most recent insert in the database. 195** 196** This function is similar to the mysql_insert_id() function from MySQL. 197*/ 198sqlite_int64 sqlite3_last_insert_rowid(sqlite3*); 199 200/* 201** This function returns the number of database rows that were changed 202** (or inserted or deleted) by the most recent called sqlite3_exec(). 203** 204** All changes are counted, even if they were later undone by a 205** ROLLBACK or ABORT. Except, changes associated with creating and 206** dropping tables are not counted. 207** 208** If a callback invokes sqlite3_exec() recursively, then the changes 209** in the inner, recursive call are counted together with the changes 210** in the outer call. 211** 212** SQLite implements the command "DELETE FROM table" without a WHERE clause 213** by dropping and recreating the table. (This is much faster than going 214** through and deleting individual elements form the table.) Because of 215** this optimization, the change count for "DELETE FROM table" will be 216** zero regardless of the number of elements that were originally in the 217** table. To get an accurate count of the number of rows deleted, use 218** "DELETE FROM table WHERE 1" instead. 219*/ 220int sqlite3_changes(sqlite3*); 221 222/* 223** This function returns the number of database rows that have been 224** modified by INSERT, UPDATE or DELETE statements since the database handle 225** was opened. This includes UPDATE, INSERT and DELETE statements executed 226** as part of trigger programs. All changes are counted as soon as the 227** statement that makes them is completed (when the statement handle is 228** passed to sqlite3_reset() or sqlite_finalise()). 229** 230** SQLite implements the command "DELETE FROM table" without a WHERE clause 231** by dropping and recreating the table. (This is much faster than going 232** through and deleting individual elements form the table.) Because of 233** this optimization, the change count for "DELETE FROM table" will be 234** zero regardless of the number of elements that were originally in the 235** table. To get an accurate count of the number of rows deleted, use 236** "DELETE FROM table WHERE 1" instead. 237*/ 238int sqlite3_total_changes(sqlite3*); 239 240/* This function causes any pending database operation to abort and 241** return at its earliest opportunity. This routine is typically 242** called in response to a user action such as pressing "Cancel" 243** or Ctrl-C where the user wants a long query operation to halt 244** immediately. 245*/ 246void sqlite3_interrupt(sqlite3*); 247 248 249/* These functions return true if the given input string comprises 250** one or more complete SQL statements. For the sqlite3_complete() call, 251** the parameter must be a nul-terminated UTF-8 string. For 252** sqlite3_complete16(), a nul-terminated machine byte order UTF-16 string 253** is required. 254** 255** The algorithm is simple. If the last token other than spaces 256** and comments is a semicolon, then return true. otherwise return 257** false. 258*/ 259int sqlite3_complete(const char *sql); 260int sqlite3_complete16(const void *sql); 261 262/* 263** This routine identifies a callback function that is invoked 264** whenever an attempt is made to open a database table that is 265** currently locked by another process or thread. If the busy callback 266** is NULL, then sqlite3_exec() returns SQLITE_BUSY immediately if 267** it finds a locked table. If the busy callback is not NULL, then 268** sqlite3_exec() invokes the callback with three arguments. The 269** second argument is the name of the locked table and the third 270** argument is the number of times the table has been busy. If the 271** busy callback returns 0, then sqlite3_exec() immediately returns 272** SQLITE_BUSY. If the callback returns non-zero, then sqlite3_exec() 273** tries to open the table again and the cycle repeats. 274** 275** The default busy callback is NULL. 276** 277** Sqlite is re-entrant, so the busy handler may start a new query. 278** (It is not clear why anyone would every want to do this, but it 279** is allowed, in theory.) But the busy handler may not close the 280** database. Closing the database from a busy handler will delete 281** data structures out from under the executing query and will 282** probably result in a coredump. 283*/ 284int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*); 285 286/* 287** This routine sets a busy handler that sleeps for a while when a 288** table is locked. The handler will sleep multiple times until 289** at least "ms" milleseconds of sleeping have been done. After 290** "ms" milleseconds of sleeping, the handler returns 0 which 291** causes sqlite3_exec() to return SQLITE_BUSY. 292** 293** Calling this routine with an argument less than or equal to zero 294** turns off all busy handlers. 295*/ 296int sqlite3_busy_timeout(sqlite3*, int ms); 297 298/* 299** This next routine is really just a wrapper around sqlite3_exec(). 300** Instead of invoking a user-supplied callback for each row of the 301** result, this routine remembers each row of the result in memory 302** obtained from malloc(), then returns all of the result after the 303** query has finished. 304** 305** As an example, suppose the query result where this table: 306** 307** Name | Age 308** ----------------------- 309** Alice | 43 310** Bob | 28 311** Cindy | 21 312** 313** If the 3rd argument were &azResult then after the function returns 314** azResult will contain the following data: 315** 316** azResult[0] = "Name"; 317** azResult[1] = "Age"; 318** azResult[2] = "Alice"; 319** azResult[3] = "43"; 320** azResult[4] = "Bob"; 321** azResult[5] = "28"; 322** azResult[6] = "Cindy"; 323** azResult[7] = "21"; 324** 325** Notice that there is an extra row of data containing the column 326** headers. But the *nrow return value is still 3. *ncolumn is 327** set to 2. In general, the number of values inserted into azResult 328** will be ((*nrow) + 1)*(*ncolumn). 329** 330** After the calling function has finished using the result, it should 331** pass the result data pointer to sqlite3_free_table() in order to 332** release the memory that was malloc-ed. Because of the way the 333** malloc() happens, the calling function must not try to call 334** free() directly. Only sqlite3_free_table() is able to release 335** the memory properly and safely. 336** 337** The return value of this routine is the same as from sqlite3_exec(). 338*/ 339int sqlite3_get_table( 340 sqlite3*, /* An open database */ 341 const char *sql, /* SQL to be executed */ 342 char ***resultp, /* Result written to a char *[] that this points to */ 343 int *nrow, /* Number of result rows written here */ 344 int *ncolumn, /* Number of result columns written here */ 345 char **errmsg /* Error msg written here */ 346); 347 348/* 349** Call this routine to free the memory that sqlite3_get_table() allocated. 350*/ 351void sqlite3_free_table(char **result); 352 353/* 354** The following routines are variants of the "sprintf()" from the 355** standard C library. The resulting string is written into memory 356** obtained from malloc() so that there is never a possiblity of buffer 357** overflow. These routines also implement some additional formatting 358** options that are useful for constructing SQL statements. 359** 360** The strings returned by these routines should be freed by calling 361** sqlite3_free(). 362** 363** All of the usual printf formatting options apply. In addition, there 364** is a "%q" option. %q works like %s in that it substitutes a null-terminated 365** string from the argument list. But %q also doubles every '\'' character. 366** %q is designed for use inside a string literal. By doubling each '\'' 367** character it escapes that character and allows it to be inserted into 368** the string. 369** 370** For example, so some string variable contains text as follows: 371** 372** char *zText = "It's a happy day!"; 373** 374** We can use this text in an SQL statement as follows: 375** 376** char *z = sqlite3_mprintf("INSERT INTO TABLES('%q')", zText); 377** sqlite3_exec(db, z, callback1, 0, 0); 378** sqlite3_free(z); 379** 380** Because the %q format string is used, the '\'' character in zText 381** is escaped and the SQL generated is as follows: 382** 383** INSERT INTO table1 VALUES('It''s a happy day!') 384** 385** This is correct. Had we used %s instead of %q, the generated SQL 386** would have looked like this: 387** 388** INSERT INTO table1 VALUES('It's a happy day!'); 389** 390** This second example is an SQL syntax error. As a general rule you 391** should always use %q instead of %s when inserting text into a string 392** literal. 393*/ 394char *sqlite3_mprintf(const char*,...); 395char *sqlite3_vmprintf(const char*, va_list); 396void sqlite3_free(char *z); 397char *sqlite3_snprintf(int,char*,const char*, ...); 398 399#ifndef SQLITE_OMIT_AUTHORIZATION 400/* 401** This routine registers a callback with the SQLite library. The 402** callback is invoked (at compile-time, not at run-time) for each 403** attempt to access a column of a table in the database. The callback 404** returns SQLITE_OK if access is allowed, SQLITE_DENY if the entire 405** SQL statement should be aborted with an error and SQLITE_IGNORE 406** if the column should be treated as a NULL value. 407*/ 408int sqlite3_set_authorizer( 409 sqlite3*, 410 int (*xAuth)(void*,int,const char*,const char*,const char*,const char*), 411 void *pUserData 412); 413#endif 414 415/* 416** The second parameter to the access authorization function above will 417** be one of the values below. These values signify what kind of operation 418** is to be authorized. The 3rd and 4th parameters to the authorization 419** function will be parameters or NULL depending on which of the following 420** codes is used as the second parameter. The 5th parameter is the name 421** of the database ("main", "temp", etc.) if applicable. The 6th parameter 422** is the name of the inner-most trigger or view that is responsible for 423** the access attempt or NULL if this access attempt is directly from 424** input SQL code. 425** 426** Arg-3 Arg-4 427*/ 428#define SQLITE_COPY 0 /* Table Name File Name */ 429#define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */ 430#define SQLITE_CREATE_TABLE 2 /* Table Name NULL */ 431#define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */ 432#define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */ 433#define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */ 434#define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */ 435#define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */ 436#define SQLITE_CREATE_VIEW 8 /* View Name NULL */ 437#define SQLITE_DELETE 9 /* Table Name NULL */ 438#define SQLITE_DROP_INDEX 10 /* Index Name Table Name */ 439#define SQLITE_DROP_TABLE 11 /* Table Name NULL */ 440#define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */ 441#define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */ 442#define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */ 443#define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */ 444#define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */ 445#define SQLITE_DROP_VIEW 17 /* View Name NULL */ 446#define SQLITE_INSERT 18 /* Table Name NULL */ 447#define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */ 448#define SQLITE_READ 20 /* Table Name Column Name */ 449#define SQLITE_SELECT 21 /* NULL NULL */ 450#define SQLITE_TRANSACTION 22 /* NULL NULL */ 451#define SQLITE_UPDATE 23 /* Table Name Column Name */ 452#define SQLITE_ATTACH 24 /* Filename NULL */ 453#define SQLITE_DETACH 25 /* Database Name NULL */ 454#define SQLITE_ALTER_TABLE 26 /* Database Name Table Name */ 455#define SQLITE_REINDEX 27 /* Index Name NULL */ 456#define SQLITE_ANALYZE 28 /* Table Name NULL */ 457 458 459/* 460** The return value of the authorization function should be one of the 461** following constants: 462*/ 463/* #define SQLITE_OK 0 // Allow access (This is actually defined above) */ 464#define SQLITE_DENY 1 /* Abort the SQL statement with an error */ 465#define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */ 466 467/* 468** Register a function for tracing SQL command evaluation. The function 469** registered by sqlite3_trace() is invoked at the first sqlite3_step() 470** for the evaluation of an SQL statement. The function registered by 471** sqlite3_profile() runs at the end of each SQL statement and includes 472** information on how long that statement ran. 473** 474** The sqlite3_profile() API is currently considered experimental and 475** is subject to change. 476*/ 477void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*); 478void *sqlite3_profile(sqlite3*, 479 void(*xProfile)(void*,const char*,sqlite_uint64), void*); 480 481/* 482** This routine configures a callback function - the progress callback - that 483** is invoked periodically during long running calls to sqlite3_exec(), 484** sqlite3_step() and sqlite3_get_table(). An example use for this API is to 485** keep a GUI updated during a large query. 486** 487** The progress callback is invoked once for every N virtual machine opcodes, 488** where N is the second argument to this function. The progress callback 489** itself is identified by the third argument to this function. The fourth 490** argument to this function is a void pointer passed to the progress callback 491** function each time it is invoked. 492** 493** If a call to sqlite3_exec(), sqlite3_step() or sqlite3_get_table() results 494** in less than N opcodes being executed, then the progress callback is not 495** invoked. 496** 497** To remove the progress callback altogether, pass NULL as the third 498** argument to this function. 499** 500** If the progress callback returns a result other than 0, then the current 501** query is immediately terminated and any database changes rolled back. If the 502** query was part of a larger transaction, then the transaction is not rolled 503** back and remains active. The sqlite3_exec() call returns SQLITE_ABORT. 504** 505******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ****** 506*/ 507void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*); 508 509/* 510** Register a callback function to be invoked whenever a new transaction 511** is committed. The pArg argument is passed through to the callback. 512** callback. If the callback function returns non-zero, then the commit 513** is converted into a rollback. 514** 515** If another function was previously registered, its pArg value is returned. 516** Otherwise NULL is returned. 517** 518** Registering a NULL function disables the callback. 519** 520******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ****** 521*/ 522void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*); 523 524/* 525** Open the sqlite database file "filename". The "filename" is UTF-8 526** encoded for sqlite3_open() and UTF-16 encoded in the native byte order 527** for sqlite3_open16(). An sqlite3* handle is returned in *ppDb, even 528** if an error occurs. If the database is opened (or created) successfully, 529** then SQLITE_OK is returned. Otherwise an error code is returned. The 530** sqlite3_errmsg() or sqlite3_errmsg16() routines can be used to obtain 531** an English language description of the error. 532** 533** If the database file does not exist, then a new database is created. 534** The encoding for the database is UTF-8 if sqlite3_open() is called and 535** UTF-16 if sqlite3_open16 is used. 536** 537** Whether or not an error occurs when it is opened, resources associated 538** with the sqlite3* handle should be released by passing it to 539** sqlite3_close() when it is no longer required. 540*/ 541int sqlite3_open( 542 const char *filename, /* Database filename (UTF-8) */ 543 sqlite3 **ppDb /* OUT: SQLite db handle */ 544); 545int sqlite3_open16( 546 const void *filename, /* Database filename (UTF-16) */ 547 sqlite3 **ppDb /* OUT: SQLite db handle */ 548); 549 550/* 551** Return the error code for the most recent sqlite3_* API call associated 552** with sqlite3 handle 'db'. SQLITE_OK is returned if the most recent 553** API call was successful. 554** 555** Calls to many sqlite3_* functions set the error code and string returned 556** by sqlite3_errcode(), sqlite3_errmsg() and sqlite3_errmsg16() 557** (overwriting the previous values). Note that calls to sqlite3_errcode(), 558** sqlite3_errmsg() and sqlite3_errmsg16() themselves do not affect the 559** results of future invocations. 560** 561** Assuming no other intervening sqlite3_* API calls are made, the error 562** code returned by this function is associated with the same error as 563** the strings returned by sqlite3_errmsg() and sqlite3_errmsg16(). 564*/ 565int sqlite3_errcode(sqlite3 *db); 566 567/* 568** Return a pointer to a UTF-8 encoded string describing in english the 569** error condition for the most recent sqlite3_* API call. The returned 570** string is always terminated by an 0x00 byte. 571** 572** The string "not an error" is returned when the most recent API call was 573** successful. 574*/ 575const char *sqlite3_errmsg(sqlite3*); 576 577/* 578** Return a pointer to a UTF-16 native byte order encoded string describing 579** in english the error condition for the most recent sqlite3_* API call. 580** The returned string is always terminated by a pair of 0x00 bytes. 581** 582** The string "not an error" is returned when the most recent API call was 583** successful. 584*/ 585const void *sqlite3_errmsg16(sqlite3*); 586 587/* 588** An instance of the following opaque structure is used to represent 589** a compiled SQL statment. 590*/ 591typedef struct sqlite3_stmt sqlite3_stmt; 592 593/* 594** To execute an SQL query, it must first be compiled into a byte-code 595** program using one of the following routines. The only difference between 596** them is that the second argument, specifying the SQL statement to 597** compile, is assumed to be encoded in UTF-8 for the sqlite3_prepare() 598** function and UTF-16 for sqlite3_prepare16(). 599** 600** The first parameter "db" is an SQLite database handle. The second 601** parameter "zSql" is the statement to be compiled, encoded as either 602** UTF-8 or UTF-16 (see above). If the next parameter, "nBytes", is less 603** than zero, then zSql is read up to the first nul terminator. If 604** "nBytes" is not less than zero, then it is the length of the string zSql 605** in bytes (not characters). 606** 607** *pzTail is made to point to the first byte past the end of the first 608** SQL statement in zSql. This routine only compiles the first statement 609** in zSql, so *pzTail is left pointing to what remains uncompiled. 610** 611** *ppStmt is left pointing to a compiled SQL statement that can be 612** executed using sqlite3_step(). Or if there is an error, *ppStmt may be 613** set to NULL. If the input text contained no SQL (if the input is and 614** empty string or a comment) then *ppStmt is set to NULL. 615** 616** On success, SQLITE_OK is returned. Otherwise an error code is returned. 617*/ 618int sqlite3_prepare( 619 sqlite3 *db, /* Database handle */ 620 const char *zSql, /* SQL statement, UTF-8 encoded */ 621 int nBytes, /* Length of zSql in bytes. */ 622 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ 623 const char **pzTail /* OUT: Pointer to unused portion of zSql */ 624); 625int sqlite3_prepare16( 626 sqlite3 *db, /* Database handle */ 627 const void *zSql, /* SQL statement, UTF-16 encoded */ 628 int nBytes, /* Length of zSql in bytes. */ 629 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ 630 const void **pzTail /* OUT: Pointer to unused portion of zSql */ 631); 632 633/* 634** Pointers to the following two opaque structures are used to communicate 635** with the implementations of user-defined functions. 636*/ 637typedef struct sqlite3_context sqlite3_context; 638typedef struct Mem sqlite3_value; 639 640/* 641** In the SQL strings input to sqlite3_prepare() and sqlite3_prepare16(), 642** one or more literals can be replace by parameters "?" or ":AAA" or 643** "$VVV" where AAA is an identifer and VVV is a variable name according 644** to the syntax rules of the TCL programming language. 645** The value of these parameters (also called "host parameter names") can 646** be set using the routines listed below. 647** 648** In every case, the first parameter is a pointer to the sqlite3_stmt 649** structure returned from sqlite3_prepare(). The second parameter is the 650** index of the parameter. The first parameter as an index of 1. For 651** named parameters (":AAA" or "$VVV") you can use 652** sqlite3_bind_parameter_index() to get the correct index value given 653** the parameters name. If the same named parameter occurs more than 654** once, it is assigned the same index each time. 655** 656** The fifth parameter to sqlite3_bind_blob(), sqlite3_bind_text(), and 657** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or 658** text after SQLite has finished with it. If the fifth argument is the 659** special value SQLITE_STATIC, then the library assumes that the information 660** is in static, unmanaged space and does not need to be freed. If the 661** fifth argument has the value SQLITE_TRANSIENT, then SQLite makes its 662** own private copy of the data. 663** 664** The sqlite3_bind_* routine must be called before sqlite3_step() after 665** an sqlite3_prepare() or sqlite3_reset(). Unbound parameterss are 666** interpreted as NULL. 667*/ 668int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*)); 669int sqlite3_bind_double(sqlite3_stmt*, int, double); 670int sqlite3_bind_int(sqlite3_stmt*, int, int); 671int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite_int64); 672int sqlite3_bind_null(sqlite3_stmt*, int); 673int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*)); 674int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*)); 675int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*); 676 677/* 678** Return the number of parameters in a compiled SQL statement. This 679** routine was added to support DBD::SQLite. 680*/ 681int sqlite3_bind_parameter_count(sqlite3_stmt*); 682 683/* 684** Return the name of the i-th parameter. Ordinary parameters "?" are 685** nameless and a NULL is returned. For parameters of the form :AAA or 686** $VVV the complete text of the parameter name is returned, including 687** the initial ":" or "$". NULL is returned if the index is out of range. 688*/ 689const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int); 690 691/* 692** Return the index of a parameter with the given name. The name 693** must match exactly. If no parameter with the given name is found, 694** return 0. 695*/ 696int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName); 697 698/* 699** Set all the parameters in the compiled SQL statement to NULL. 700*/ 701int sqlite3_clear_bindings(sqlite3_stmt*); 702 703/* 704** Return the number of columns in the result set returned by the compiled 705** SQL statement. This routine returns 0 if pStmt is an SQL statement 706** that does not return data (for example an UPDATE). 707*/ 708int sqlite3_column_count(sqlite3_stmt *pStmt); 709 710/* 711** The first parameter is a compiled SQL statement. This function returns 712** the column heading for the Nth column of that statement, where N is the 713** second function parameter. The string returned is UTF-8 for 714** sqlite3_column_name() and UTF-16 for sqlite3_column_name16(). 715*/ 716const char *sqlite3_column_name(sqlite3_stmt*,int); 717const void *sqlite3_column_name16(sqlite3_stmt*,int); 718 719/* 720** The first parameter is a compiled SQL statement. If this statement 721** is a SELECT statement, the Nth column of the returned result set 722** of the SELECT is a table column then the declared type of the table 723** column is returned. If the Nth column of the result set is not at table 724** column, then a NULL pointer is returned. The returned string is always 725** UTF-8 encoded. For example, in the database schema: 726** 727** CREATE TABLE t1(c1 VARIANT); 728** 729** And the following statement compiled: 730** 731** SELECT c1 + 1, 0 FROM t1; 732** 733** Then this routine would return the string "VARIANT" for the second 734** result column (i==1), and a NULL pointer for the first result column 735** (i==0). 736*/ 737const char *sqlite3_column_decltype(sqlite3_stmt *, int i); 738 739/* 740** The first parameter is a compiled SQL statement. If this statement 741** is a SELECT statement, the Nth column of the returned result set 742** of the SELECT is a table column then the declared type of the table 743** column is returned. If the Nth column of the result set is not at table 744** column, then a NULL pointer is returned. The returned string is always 745** UTF-16 encoded. For example, in the database schema: 746** 747** CREATE TABLE t1(c1 INTEGER); 748** 749** And the following statement compiled: 750** 751** SELECT c1 + 1, 0 FROM t1; 752** 753** Then this routine would return the string "INTEGER" for the second 754** result column (i==1), and a NULL pointer for the first result column 755** (i==0). 756*/ 757const void *sqlite3_column_decltype16(sqlite3_stmt*,int); 758 759/* 760** After an SQL query has been compiled with a call to either 761** sqlite3_prepare() or sqlite3_prepare16(), then this function must be 762** called one or more times to execute the statement. 763** 764** The return value will be either SQLITE_BUSY, SQLITE_DONE, 765** SQLITE_ROW, SQLITE_ERROR, or SQLITE_MISUSE. 766** 767** SQLITE_BUSY means that the database engine attempted to open 768** a locked database and there is no busy callback registered. 769** Call sqlite3_step() again to retry the open. 770** 771** SQLITE_DONE means that the statement has finished executing 772** successfully. sqlite3_step() should not be called again on this virtual 773** machine. 774** 775** If the SQL statement being executed returns any data, then 776** SQLITE_ROW is returned each time a new row of data is ready 777** for processing by the caller. The values may be accessed using 778** the sqlite3_column_*() functions described below. sqlite3_step() 779** is called again to retrieve the next row of data. 780** 781** SQLITE_ERROR means that a run-time error (such as a constraint 782** violation) has occurred. sqlite3_step() should not be called again on 783** the VM. More information may be found by calling sqlite3_errmsg(). 784** 785** SQLITE_MISUSE means that the this routine was called inappropriately. 786** Perhaps it was called on a virtual machine that had already been 787** finalized or on one that had previously returned SQLITE_ERROR or 788** SQLITE_DONE. Or it could be the case the the same database connection 789** is being used simulataneously by two or more threads. 790*/ 791int sqlite3_step(sqlite3_stmt*); 792 793/* 794** Return the number of values in the current row of the result set. 795** 796** After a call to sqlite3_step() that returns SQLITE_ROW, this routine 797** will return the same value as the sqlite3_column_count() function. 798** After sqlite3_step() has returned an SQLITE_DONE, SQLITE_BUSY or 799** error code, or before sqlite3_step() has been called on a 800** compiled SQL statement, this routine returns zero. 801*/ 802int sqlite3_data_count(sqlite3_stmt *pStmt); 803 804/* 805** Values are stored in the database in one of the following fundamental 806** types. 807*/ 808#define SQLITE_INTEGER 1 809#define SQLITE_FLOAT 2 810/* #define SQLITE_TEXT 3 // See below */ 811#define SQLITE_BLOB 4 812#define SQLITE_NULL 5 813 814/* 815** SQLite version 2 defines SQLITE_TEXT differently. To allow both 816** version 2 and version 3 to be included, undefine them both if a 817** conflict is seen. Define SQLITE3_TEXT to be the version 3 value. 818*/ 819#ifdef SQLITE_TEXT 820# undef SQLITE_TEXT 821#else 822# define SQLITE_TEXT 3 823#endif 824#define SQLITE3_TEXT 3 825 826/* 827** The next group of routines returns information about the information 828** in a single column of the current result row of a query. In every 829** case the first parameter is a pointer to the SQL statement that is being 830** executed (the sqlite_stmt* that was returned from sqlite3_prepare()) and 831** the second argument is the index of the column for which information 832** should be returned. iCol is zero-indexed. The left-most column as an 833** index of 0. 834** 835** If the SQL statement is not currently point to a valid row, or if the 836** the colulmn index is out of range, the result is undefined. 837** 838** These routines attempt to convert the value where appropriate. For 839** example, if the internal representation is FLOAT and a text result 840** is requested, sprintf() is used internally to do the conversion 841** automatically. The following table details the conversions that 842** are applied: 843** 844** Internal Type Requested Type Conversion 845** ------------- -------------- -------------------------- 846** NULL INTEGER Result is 0 847** NULL FLOAT Result is 0.0 848** NULL TEXT Result is an empty string 849** NULL BLOB Result is a zero-length BLOB 850** INTEGER FLOAT Convert from integer to float 851** INTEGER TEXT ASCII rendering of the integer 852** INTEGER BLOB Same as for INTEGER->TEXT 853** FLOAT INTEGER Convert from float to integer 854** FLOAT TEXT ASCII rendering of the float 855** FLOAT BLOB Same as FLOAT->TEXT 856** TEXT INTEGER Use atoi() 857** TEXT FLOAT Use atof() 858** TEXT BLOB No change 859** BLOB INTEGER Convert to TEXT then use atoi() 860** BLOB FLOAT Convert to TEXT then use atof() 861** BLOB TEXT Add a \000 terminator if needed 862** 863** The following access routines are provided: 864** 865** _type() Return the datatype of the result. This is one of 866** SQLITE_INTEGER, SQLITE_FLOAT, SQLITE_TEXT, SQLITE_BLOB, 867** or SQLITE_NULL. 868** _blob() Return the value of a BLOB. 869** _bytes() Return the number of bytes in a BLOB value or the number 870** of bytes in a TEXT value represented as UTF-8. The \000 871** terminator is included in the byte count for TEXT values. 872** _bytes16() Return the number of bytes in a BLOB value or the number 873** of bytes in a TEXT value represented as UTF-16. The \u0000 874** terminator is included in the byte count for TEXT values. 875** _double() Return a FLOAT value. 876** _int() Return an INTEGER value in the host computer's native 877** integer representation. This might be either a 32- or 64-bit 878** integer depending on the host. 879** _int64() Return an INTEGER value as a 64-bit signed integer. 880** _text() Return the value as UTF-8 text. 881** _text16() Return the value as UTF-16 text. 882*/ 883const void *sqlite3_column_blob(sqlite3_stmt*, int iCol); 884int sqlite3_column_bytes(sqlite3_stmt*, int iCol); 885int sqlite3_column_bytes16(sqlite3_stmt*, int iCol); 886double sqlite3_column_double(sqlite3_stmt*, int iCol); 887int sqlite3_column_int(sqlite3_stmt*, int iCol); 888sqlite_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol); 889const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol); 890const void *sqlite3_column_text16(sqlite3_stmt*, int iCol); 891int sqlite3_column_type(sqlite3_stmt*, int iCol); 892 893/* 894** The sqlite3_finalize() function is called to delete a compiled 895** SQL statement obtained by a previous call to sqlite3_prepare() 896** or sqlite3_prepare16(). If the statement was executed successfully, or 897** not executed at all, then SQLITE_OK is returned. If execution of the 898** statement failed then an error code is returned. 899** 900** This routine can be called at any point during the execution of the 901** virtual machine. If the virtual machine has not completed execution 902** when this routine is called, that is like encountering an error or 903** an interrupt. (See sqlite3_interrupt().) Incomplete updates may be 904** rolled back and transactions cancelled, depending on the circumstances, 905** and the result code returned will be SQLITE_ABORT. 906*/ 907int sqlite3_finalize(sqlite3_stmt *pStmt); 908 909/* 910** The sqlite3_reset() function is called to reset a compiled SQL 911** statement obtained by a previous call to sqlite3_prepare() or 912** sqlite3_prepare16() back to it's initial state, ready to be re-executed. 913** Any SQL statement variables that had values bound to them using 914** the sqlite3_bind_*() API retain their values. 915*/ 916int sqlite3_reset(sqlite3_stmt *pStmt); 917 918/* 919** The following two functions are used to add user functions or aggregates 920** implemented in C to the SQL langauge interpreted by SQLite. The 921** difference only between the two is that the second parameter, the 922** name of the (scalar) function or aggregate, is encoded in UTF-8 for 923** sqlite3_create_function() and UTF-16 for sqlite3_create_function16(). 924** 925** The first argument is the database handle that the new function or 926** aggregate is to be added to. If a single program uses more than one 927** database handle internally, then user functions or aggregates must 928** be added individually to each database handle with which they will be 929** used. 930** 931** The third parameter is the number of arguments that the function or 932** aggregate takes. If this parameter is negative, then the function or 933** aggregate may take any number of arguments. 934** 935** The fourth parameter is one of SQLITE_UTF* values defined below, 936** indicating the encoding that the function is most likely to handle 937** values in. This does not change the behaviour of the programming 938** interface. However, if two versions of the same function are registered 939** with different encoding values, SQLite invokes the version likely to 940** minimize conversions between text encodings. 941** 942** The seventh, eighth and ninth parameters, xFunc, xStep and xFinal, are 943** pointers to user implemented C functions that implement the user 944** function or aggregate. A scalar function requires an implementation of 945** the xFunc callback only, NULL pointers should be passed as the xStep 946** and xFinal parameters. An aggregate function requires an implementation 947** of xStep and xFinal, but NULL should be passed for xFunc. To delete an 948** existing user function or aggregate, pass NULL for all three function 949** callback. Specifying an inconstent set of callback values, such as an 950** xFunc and an xFinal, or an xStep but no xFinal, SQLITE_ERROR is 951** returned. 952*/ 953int sqlite3_create_function( 954 sqlite3 *, 955 const char *zFunctionName, 956 int nArg, 957 int eTextRep, 958 void*, 959 void (*xFunc)(sqlite3_context*,int,sqlite3_value**), 960 void (*xStep)(sqlite3_context*,int,sqlite3_value**), 961 void (*xFinal)(sqlite3_context*) 962); 963int sqlite3_create_function16( 964 sqlite3*, 965 const void *zFunctionName, 966 int nArg, 967 int eTextRep, 968 void*, 969 void (*xFunc)(sqlite3_context*,int,sqlite3_value**), 970 void (*xStep)(sqlite3_context*,int,sqlite3_value**), 971 void (*xFinal)(sqlite3_context*) 972); 973 974/* 975** The next routine returns the number of calls to xStep for a particular 976** aggregate function instance. The current call to xStep counts so this 977** routine always returns at least 1. 978*/ 979int sqlite3_aggregate_count(sqlite3_context*); 980 981/* 982** The next group of routines returns information about parameters to 983** a user-defined function. Function implementations use these routines 984** to access their parameters. These routines are the same as the 985** sqlite3_column_* routines except that these routines take a single 986** sqlite3_value* pointer instead of an sqlite3_stmt* and an integer 987** column number. 988*/ 989const void *sqlite3_value_blob(sqlite3_value*); 990int sqlite3_value_bytes(sqlite3_value*); 991int sqlite3_value_bytes16(sqlite3_value*); 992double sqlite3_value_double(sqlite3_value*); 993int sqlite3_value_int(sqlite3_value*); 994sqlite_int64 sqlite3_value_int64(sqlite3_value*); 995const unsigned char *sqlite3_value_text(sqlite3_value*); 996const void *sqlite3_value_text16(sqlite3_value*); 997const void *sqlite3_value_text16le(sqlite3_value*); 998const void *sqlite3_value_text16be(sqlite3_value*); 999int sqlite3_value_type(sqlite3_value*); 1000 1001/* 1002** Aggregate functions use the following routine to allocate 1003** a structure for storing their state. The first time this routine 1004** is called for a particular aggregate, a new structure of size nBytes 1005** is allocated, zeroed, and returned. On subsequent calls (for the 1006** same aggregate instance) the same buffer is returned. The implementation 1007** of the aggregate can use the returned buffer to accumulate data. 1008** 1009** The buffer allocated is freed automatically by SQLite. 1010*/ 1011void *sqlite3_aggregate_context(sqlite3_context*, int nBytes); 1012 1013/* 1014** The pUserData parameter to the sqlite3_create_function() 1015** routine used to register user functions is available to 1016** the implementation of the function using this call. 1017*/ 1018void *sqlite3_user_data(sqlite3_context*); 1019 1020/* 1021** The following two functions may be used by scalar user functions to 1022** associate meta-data with argument values. If the same value is passed to 1023** multiple invocations of the user-function during query execution, under 1024** some circumstances the associated meta-data may be preserved. This may 1025** be used, for example, to add a regular-expression matching scalar 1026** function. The compiled version of the regular expression is stored as 1027** meta-data associated with the SQL value passed as the regular expression 1028** pattern. 1029** 1030** Calling sqlite3_get_auxdata() returns a pointer to the meta data 1031** associated with the Nth argument value to the current user function 1032** call, where N is the second parameter. If no meta-data has been set for 1033** that value, then a NULL pointer is returned. 1034** 1035** The sqlite3_set_auxdata() is used to associate meta data with a user 1036** function argument. The third parameter is a pointer to the meta data 1037** to be associated with the Nth user function argument value. The fourth 1038** parameter specifies a 'delete function' that will be called on the meta 1039** data pointer to release it when it is no longer required. If the delete 1040** function pointer is NULL, it is not invoked. 1041** 1042** In practice, meta-data is preserved between function calls for 1043** expressions that are constant at compile time. This includes literal 1044** values and SQL variables. 1045*/ 1046void *sqlite3_get_auxdata(sqlite3_context*, int); 1047void sqlite3_set_auxdata(sqlite3_context*, int, void*, void (*)(void*)); 1048 1049 1050/* 1051** These are special value for the destructor that is passed in as the 1052** final argument to routines like sqlite3_result_blob(). If the destructor 1053** argument is SQLITE_STATIC, it means that the content pointer is constant 1054** and will never change. It does not need to be destroyed. The 1055** SQLITE_TRANSIENT value means that the content will likely change in 1056** the near future and that SQLite should make its own private copy of 1057** the content before returning. 1058*/ 1059#define SQLITE_STATIC ((void(*)(void *))0) 1060#define SQLITE_TRANSIENT ((void(*)(void *))-1) 1061 1062/* 1063** User-defined functions invoke the following routines in order to 1064** set their return value. 1065*/ 1066void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*)); 1067void sqlite3_result_double(sqlite3_context*, double); 1068void sqlite3_result_error(sqlite3_context*, const char*, int); 1069void sqlite3_result_error16(sqlite3_context*, const void*, int); 1070void sqlite3_result_int(sqlite3_context*, int); 1071void sqlite3_result_int64(sqlite3_context*, sqlite_int64); 1072void sqlite3_result_null(sqlite3_context*); 1073void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*)); 1074void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*)); 1075void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*)); 1076void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*)); 1077void sqlite3_result_value(sqlite3_context*, sqlite3_value*); 1078 1079/* 1080** These are the allowed values for the eTextRep argument to 1081** sqlite3_create_collation and sqlite3_create_function. 1082*/ 1083#define SQLITE_UTF8 1 1084#define SQLITE_UTF16LE 2 1085#define SQLITE_UTF16BE 3 1086#define SQLITE_UTF16 4 /* Use native byte order */ 1087#define SQLITE_ANY 5 /* sqlite3_create_function only */ 1088 1089/* 1090** These two functions are used to add new collation sequences to the 1091** sqlite3 handle specified as the first argument. 1092** 1093** The name of the new collation sequence is specified as a UTF-8 string 1094** for sqlite3_create_collation() and a UTF-16 string for 1095** sqlite3_create_collation16(). In both cases the name is passed as the 1096** second function argument. 1097** 1098** The third argument must be one of the constants SQLITE_UTF8, 1099** SQLITE_UTF16LE or SQLITE_UTF16BE, indicating that the user-supplied 1100** routine expects to be passed pointers to strings encoded using UTF-8, 1101** UTF-16 little-endian or UTF-16 big-endian respectively. 1102** 1103** A pointer to the user supplied routine must be passed as the fifth 1104** argument. If it is NULL, this is the same as deleting the collation 1105** sequence (so that SQLite cannot call it anymore). Each time the user 1106** supplied function is invoked, it is passed a copy of the void* passed as 1107** the fourth argument to sqlite3_create_collation() or 1108** sqlite3_create_collation16() as its first parameter. 1109** 1110** The remaining arguments to the user-supplied routine are two strings, 1111** each represented by a [length, data] pair and encoded in the encoding 1112** that was passed as the third argument when the collation sequence was 1113** registered. The user routine should return negative, zero or positive if 1114** the first string is less than, equal to, or greater than the second 1115** string. i.e. (STRING1 - STRING2). 1116*/ 1117int sqlite3_create_collation( 1118 sqlite3*, 1119 const char *zName, 1120 int eTextRep, 1121 void*, 1122 int(*xCompare)(void*,int,const void*,int,const void*) 1123); 1124int sqlite3_create_collation16( 1125 sqlite3*, 1126 const char *zName, 1127 int eTextRep, 1128 void*, 1129 int(*xCompare)(void*,int,const void*,int,const void*) 1130); 1131 1132/* 1133** To avoid having to register all collation sequences before a database 1134** can be used, a single callback function may be registered with the 1135** database handle to be called whenever an undefined collation sequence is 1136** required. 1137** 1138** If the function is registered using the sqlite3_collation_needed() API, 1139** then it is passed the names of undefined collation sequences as strings 1140** encoded in UTF-8. If sqlite3_collation_needed16() is used, the names 1141** are passed as UTF-16 in machine native byte order. A call to either 1142** function replaces any existing callback. 1143** 1144** When the user-function is invoked, the first argument passed is a copy 1145** of the second argument to sqlite3_collation_needed() or 1146** sqlite3_collation_needed16(). The second argument is the database 1147** handle. The third argument is one of SQLITE_UTF8, SQLITE_UTF16BE or 1148** SQLITE_UTF16LE, indicating the most desirable form of the collation 1149** sequence function required. The fourth parameter is the name of the 1150** required collation sequence. 1151** 1152** The collation sequence is returned to SQLite by a collation-needed 1153** callback using the sqlite3_create_collation() or 1154** sqlite3_create_collation16() APIs, described above. 1155*/ 1156int sqlite3_collation_needed( 1157 sqlite3*, 1158 void*, 1159 void(*)(void*,sqlite3*,int eTextRep,const char*) 1160); 1161int sqlite3_collation_needed16( 1162 sqlite3*, 1163 void*, 1164 void(*)(void*,sqlite3*,int eTextRep,const void*) 1165); 1166 1167/* 1168** Specify the key for an encrypted database. This routine should be 1169** called right after sqlite3_open(). 1170** 1171** The code to implement this API is not available in the public release 1172** of SQLite. 1173*/ 1174int sqlite3_key( 1175 sqlite3 *db, /* Database to be rekeyed */ 1176 const void *pKey, int nKey /* The key */ 1177); 1178 1179/* 1180** Change the key on an open database. If the current database is not 1181** encrypted, this routine will encrypt it. If pNew==0 or nNew==0, the 1182** database is decrypted. 1183** 1184** The code to implement this API is not available in the public release 1185** of SQLite. 1186*/ 1187int sqlite3_rekey( 1188 sqlite3 *db, /* Database to be rekeyed */ 1189 const void *pKey, int nKey /* The new key */ 1190); 1191 1192/* 1193** Sleep for a little while. The second parameter is the number of 1194** miliseconds to sleep for. 1195** 1196** If the operating system does not support sleep requests with 1197** milisecond time resolution, then the time will be rounded up to 1198** the nearest second. The number of miliseconds of sleep actually 1199** requested from the operating system is returned. 1200*/ 1201int sqlite3_sleep(int); 1202 1203/* 1204** Return TRUE (non-zero) if the statement supplied as an argument needs 1205** to be recompiled. A statement needs to be recompiled whenever the 1206** execution environment changes in a way that would alter the program 1207** that sqlite3_prepare() generates. For example, if new functions or 1208** collating sequences are registered or if an authorizer function is 1209** added or changed. 1210** 1211*/ 1212int sqlite3_expired(sqlite3_stmt*); 1213 1214/* 1215** Move all bindings from the first prepared statement over to the second. 1216** This routine is useful, for example, if the first prepared statement 1217** fails with an SQLITE_SCHEMA error. The same SQL can be prepared into 1218** the second prepared statement then all of the bindings transfered over 1219** to the second statement before the first statement is finalized. 1220*/ 1221int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*); 1222 1223/* 1224** If the following global variable is made to point to a 1225** string which is the name of a directory, then all temporary files 1226** created by SQLite will be placed in that directory. If this variable 1227** is NULL pointer, then SQLite does a search for an appropriate temporary 1228** file directory. 1229** 1230** Once sqlite3_open() has been called, changing this variable will invalidate 1231** the current temporary database, if any. 1232*/ 1233extern char *sqlite3_temp_directory; 1234 1235/* 1236** This function is called to recover from a malloc() failure that occured 1237** within the SQLite library. Normally, after a single malloc() fails the 1238** library refuses to function (all major calls return SQLITE_NOMEM). 1239** This function restores the library state so that it can be used again. 1240** 1241** All existing statements (sqlite3_stmt pointers) must be finalized or 1242** reset before this call is made. Otherwise, SQLITE_BUSY is returned. 1243** If any in-memory databases are in use, either as a main or TEMP 1244** database, SQLITE_ERROR is returned. In either of these cases, the 1245** library is not reset and remains unusable. 1246** 1247** This function is *not* threadsafe. Calling this from within a threaded 1248** application when threads other than the caller have used SQLite is 1249** dangerous and will almost certainly result in malfunctions. 1250** 1251** This functionality can be omitted from a build by defining the 1252** SQLITE_OMIT_GLOBALRECOVER at compile time. 1253*/ 1254int sqlite3_global_recover(); 1255 1256/* 1257** Test to see whether or not the database connection is in autocommit 1258** mode. Return TRUE if it is and FALSE if not. Autocommit mode is on 1259** by default. Autocommit is disabled by a BEGIN statement and reenabled 1260** by the next COMMIT or ROLLBACK. 1261*/ 1262int sqlite3_get_autocommit(sqlite3*); 1263 1264/* 1265** Return the sqlite3* database handle to which the prepared statement given 1266** in the argument belongs. This is the same database handle that was 1267** the first argument to the sqlite3_prepare() that was used to create 1268** the statement in the first place. 1269*/ 1270sqlite3 *sqlite3_db_handle(sqlite3_stmt*); 1271 1272#ifdef __cplusplus 1273} /* End of the 'extern "C"' block */ 1274#endif 1275#endif 1276