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. If a C-function, structure, datatype, 14 ** or constant definition does not appear in this file, then it is 15 ** not a published API of SQLite, is subject to change without 16 ** notice, and should not be referenced by programs that use SQLite. 17 ** 18 ** Some of the definitions that are in this file are marked as 19 ** "experimental". Experimental interfaces are normally new 20 ** features recently added to SQLite. We do not anticipate changes 21 ** to experimental interfaces but reserve to make minor changes if 22 ** experience from use "in the wild" suggest such changes are prudent. 23 ** 24 ** The official C-language API documentation for SQLite is derived 25 ** from comments in this file. This file is the authoritative source 26 ** on how SQLite interfaces are suppose to operate. 27 ** 28 ** The name of this file under configuration management is "sqlite.h.in". 29 ** The makefile makes some minor changes to this file (such as inserting 30 ** the version number) and changes its name to "sqlite3.h" as 31 ** part of the build process. 32 ** 33 ** @(#) $Id: sqlite.h.in,v 1.212 2007/06/14 20:57:19 drh Exp $ 34 */ 35 #ifndef _SQLITE3_H_ 36 #define _SQLITE3_H_ 37 #include <stdarg.h> /* Needed for the definition of va_list */ 38 39 /* 40 ** Make sure we can call this stuff from C++. 41 */ 42 #ifdef __cplusplus 43 extern "C" { 44 #endif 45 46 /* 47 ** Make sure these symbols where not defined by some previous header 48 ** file. 49 */ 50 #ifdef SQLITE_VERSION 51 # undef SQLITE_VERSION 52 #endif 53 #ifdef SQLITE_VERSION_NUMBER 54 # undef SQLITE_VERSION_NUMBER 55 #endif 56 57 /* 58 ** CAPI3REF: Compile-Time Library Version Numbers 59 ** 60 ** The version of the SQLite library is contained in the sqlite3.h 61 ** header file in a #define named SQLITE_VERSION. The SQLITE_VERSION 62 ** macro resolves to a string constant. 63 ** 64 ** The format of the version string is "X.Y.Z", where 65 ** X is the major version number, Y is the minor version number and Z 66 ** is the release number. The X.Y.Z might be followed by "alpha" or "beta". 67 ** For example "3.1.1beta". 68 ** 69 ** The X value is always 3 in SQLite. The X value only changes when 70 ** backwards compatibility is broken and we intend to never break 71 ** backwards compatibility. The Y value only changes when 72 ** there are major feature enhancements that are forwards compatible 73 ** but not backwards compatible. The Z value is incremented with 74 ** each release but resets back to 0 when Y is incremented. 75 ** 76 ** The SQLITE_VERSION_NUMBER is an integer with the value 77 ** (X*1000000 + Y*1000 + Z). For example, for version "3.1.1beta", 78 ** SQLITE_VERSION_NUMBER is set to 3001001. To detect if they are using 79 ** version 3.1.1 or greater at compile time, programs may use the test 80 ** (SQLITE_VERSION_NUMBER>=3001001). 81 ** 82 ** See also: [sqlite3_libversion()] and [sqlite3_libversion_number()]. 83 */ 84 #define SQLITE_VERSION "3.4.0" 85 #define SQLITE_VERSION_NUMBER 3004000 86 87 /* 88 ** CAPI3REF: Run-Time Library Version Numbers 89 ** 90 ** These routines return values equivalent to the header constants 91 ** [SQLITE_VERSION] and [SQLITE_VERSION_NUMBER]. The values returned 92 ** by this routines should only be different from the header values 93 ** if you compile your program using an sqlite3.h header from a 94 ** different version of SQLite that the version of the library you 95 ** link against. 96 ** 97 ** The sqlite3_version[] string constant contains the text of the 98 ** [SQLITE_VERSION] string. The sqlite3_libversion() function returns 99 ** a poiner to the sqlite3_version[] string constant. The function 100 ** is provided for DLL users who can only access functions and not 101 ** constants within the DLL. 102 */ 103 extern const char sqlite3_version[]; 104 const char *sqlite3_libversion(void); 105 int sqlite3_libversion_number(void); 106 107 /* 108 ** CAPI3REF: Database Connection Handle 109 ** 110 ** Each open SQLite database is represented by pointer to an instance of the 111 ** opaque structure named "sqlite3". It is useful to think of an sqlite3 112 ** pointer as an object. The [sqlite3_open] interface is its constructor 113 ** and [sqlite3_close] is its destructor. There are many other interfaces 114 ** (such as [sqlite3_prepare_v2], [sqlite3_create_function], and 115 ** [sqlite3_busy_timeout] to name but three) that are methods on this 116 ** object. 117 */ 118 typedef struct sqlite3 sqlite3; 119 120 121 /* 122 ** CAPI3REF: 64-Bit Integer Types 123 ** 124 ** Some compilers do not support the "long long" datatype. So we have 125 ** to do compiler-specific typedefs for 64-bit signed and unsigned integers. 126 ** 127 ** Many SQLite interface functions require a 64-bit integer arguments. 128 ** Those interfaces are declared using this typedef. 129 */ 130 #ifdef SQLITE_INT64_TYPE 131 typedef SQLITE_INT64_TYPE sqlite_int64; 132 typedef unsigned SQLITE_INT64_TYPE sqlite_uint64; 133 #elif defined(_MSC_VER) || defined(__BORLANDC__) 134 typedef __int64 sqlite_int64; 135 typedef unsigned __int64 sqlite_uint64; 136 #else 137 typedef long long int sqlite_int64; 138 typedef unsigned long long int sqlite_uint64; 139 #endif 140 141 /* 142 ** If compiling for a processor that lacks floating point support, 143 ** substitute integer for floating-point 144 */ 145 #ifdef SQLITE_OMIT_FLOATING_POINT 146 # define double sqlite_int64 147 #endif 148 149 /* 150 ** CAPI3REF: Closing A Database Connection 151 ** 152 ** Call this function with a pointer to a structure that was previously 153 ** returned from [sqlite3_open()] and the corresponding database will by 154 ** closed. 155 ** 156 ** All SQL statements prepared using [sqlite3_prepare_v2()] or 157 ** [sqlite3_prepare16_v2()] must be destroyed using [sqlite3_finalize()] 158 ** before this routine is called. Otherwise, SQLITE_BUSY is returned and the 159 ** database connection remains open. 160 */ 161 int sqlite3_close(sqlite3 *); 162 163 /* 164 ** The type for a callback function. 165 ** This is legacy and deprecated. It is included for historical 166 ** compatibility and is not documented. 167 */ 168 typedef int (*sqlite3_callback)(void*,int,char**, char**); 169 170 /* 171 ** CAPI3REF: One-Step Query Execution Interface 172 ** 173 ** This interface is used to do a one-time evaluatation of zero 174 ** or more SQL statements. UTF-8 text of the SQL statements to 175 ** be evaluted is passed in as the second parameter. The statements 176 ** are prepared one by one using [sqlite3_prepare()], evaluated 177 ** using [sqlite3_step()], then destroyed using [sqlite3_finalize()]. 178 ** 179 ** If one or more of the SQL statements are queries, then 180 ** the callback function specified by the 3rd parameter is 181 ** invoked once for each row of the query result. This callback 182 ** should normally return 0. If the callback returns a non-zero 183 ** value then the query is aborted, all subsequent SQL statements 184 ** are skipped and the sqlite3_exec() function returns the SQLITE_ABORT. 185 ** 186 ** The 4th parameter to this interface is an arbitrary pointer that is 187 ** passed through to the callback function as its first parameter. 188 ** 189 ** The 2nd parameter to the callback function is the number of 190 ** columns in the query result. The 3rd parameter to the callback 191 ** is an array of strings holding the values for each column 192 ** as extracted using [sqlite3_column_text()]. 193 ** The 4th parameter to the callback is an array of strings 194 ** obtained using [sqlite3_column_name()] and holding 195 ** the names of each column. 196 ** 197 ** The callback function may be NULL, even for queries. A NULL 198 ** callback is not an error. It just means that no callback 199 ** will be invoked. 200 ** 201 ** If an error occurs while parsing or evaluating the SQL (but 202 ** not while executing the callback) then an appropriate error 203 ** message is written into memory obtained from [sqlite3_malloc()] and 204 ** *errmsg is made to point to that message. The calling function 205 ** is responsible for freeing the memory that holds the error 206 ** message. Use [sqlite3_free()] for this. If errmsg==NULL, 207 ** then no error message is ever written. 208 ** 209 ** The return value is is SQLITE_OK if there are no errors and 210 ** some other [SQLITE_OK | return code] if there is an error. 211 ** The particular return value depends on the type of error. 212 ** 213 */ 214 int sqlite3_exec( 215 sqlite3*, /* An open database */ 216 const char *sql, /* SQL to be evaluted */ 217 int (*callback)(void*,int,char**,char**), /* Callback function */ 218 void *, /* 1st argument to callback */ 219 char **errmsg /* Error msg written here */ 220 ); 221 222 /* 223 ** CAPI3REF: Result Codes 224 ** KEYWORDS: SQLITE_OK 225 ** 226 ** Many SQLite functions return an integer result code from the set shown 227 ** above in order to indicates success or failure. 228 ** 229 ** The result codes above are the only ones returned by SQLite in its 230 ** default configuration. However, the [sqlite3_extended_result_codes()] 231 ** API can be used to set a database connectoin to return more detailed 232 ** result codes. 233 ** 234 ** See also: [SQLITE_IOERR_READ | extended result codes] 235 ** 236 */ 237 #define SQLITE_OK 0 /* Successful result */ 238 /* beginning-of-error-codes */ 239 #define SQLITE_ERROR 1 /* SQL error or missing database */ 240 #define SQLITE_INTERNAL 2 /* NOT USED. Internal logic error in SQLite */ 241 #define SQLITE_PERM 3 /* Access permission denied */ 242 #define SQLITE_ABORT 4 /* Callback routine requested an abort */ 243 #define SQLITE_BUSY 5 /* The database file is locked */ 244 #define SQLITE_LOCKED 6 /* A table in the database is locked */ 245 #define SQLITE_NOMEM 7 /* A malloc() failed */ 246 #define SQLITE_READONLY 8 /* Attempt to write a readonly database */ 247 #define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite3_interrupt()*/ 248 #define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */ 249 #define SQLITE_CORRUPT 11 /* The database disk image is malformed */ 250 #define SQLITE_NOTFOUND 12 /* NOT USED. Table or record not found */ 251 #define SQLITE_FULL 13 /* Insertion failed because database is full */ 252 #define SQLITE_CANTOPEN 14 /* Unable to open the database file */ 253 #define SQLITE_PROTOCOL 15 /* NOT USED. Database lock protocol error */ 254 #define SQLITE_EMPTY 16 /* Database is empty */ 255 #define SQLITE_SCHEMA 17 /* The database schema changed */ 256 #define SQLITE_TOOBIG 18 /* String or BLOB exceeds size limit */ 257 #define SQLITE_CONSTRAINT 19 /* Abort due to contraint violation */ 258 #define SQLITE_MISMATCH 20 /* Data type mismatch */ 259 #define SQLITE_MISUSE 21 /* Library used incorrectly */ 260 #define SQLITE_NOLFS 22 /* Uses OS features not supported on host */ 261 #define SQLITE_AUTH 23 /* Authorization denied */ 262 #define SQLITE_FORMAT 24 /* Auxiliary database format error */ 263 #define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */ 264 #define SQLITE_NOTADB 26 /* File opened that is not a database file */ 265 #define SQLITE_ROW 100 /* sqlite3_step() has another row ready */ 266 #define SQLITE_DONE 101 /* sqlite3_step() has finished executing */ 267 /* end-of-error-codes */ 268 269 /* 270 ** CAPI3REF: Extended Result Codes 271 ** 272 ** In its default configuration, SQLite API routines return one of 26 integer 273 ** result codes described at result-codes. However, experience has shown that 274 ** many of these result codes are too course-grained. They do not provide as 275 ** much information about problems as users might like. In an effort to 276 ** address this, newer versions of SQLite (version 3.3.8 and later) include 277 ** support for additional result codes that provide more detailed information 278 ** about errors. The extended result codes are enabled (or disabled) for 279 ** each database 280 ** connection using the [sqlite3_extended_result_codes()] API. 281 ** 282 ** Some of the available extended result codes are listed above. 283 ** We expect the number of extended result codes will be expand 284 ** over time. Software that uses extended result codes should expect 285 ** to see new result codes in future releases of SQLite. 286 ** 287 ** The symbolic name for an extended result code always contains a related 288 ** primary result code as a prefix. Primary result codes contain a single 289 ** "_" character. Extended result codes contain two or more "_" characters. 290 ** The numeric value of an extended result code can be converted to its 291 ** corresponding primary result code by masking off the lower 8 bytes. 292 ** 293 ** The SQLITE_OK result code will never be extended. It will always 294 ** be exactly zero. 295 */ 296 #define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8)) 297 #define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8)) 298 #define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8)) 299 #define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4<<8)) 300 #define SQLITE_IOERR_DIR_FSYNC (SQLITE_IOERR | (5<<8)) 301 #define SQLITE_IOERR_TRUNCATE (SQLITE_IOERR | (6<<8)) 302 #define SQLITE_IOERR_FSTAT (SQLITE_IOERR | (7<<8)) 303 #define SQLITE_IOERR_UNLOCK (SQLITE_IOERR | (8<<8)) 304 #define SQLITE_IOERR_RDLOCK (SQLITE_IOERR | (9<<8)) 305 #define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8)) 306 #define SQLITE_IOERR_BLOCKED (SQLITE_IOERR | (11<<8)) 307 308 /* 309 ** CAPI3REF: Enable Or Disable Extended Result Codes 310 ** 311 ** This routine enables or disables the 312 ** [SQLITE_IOERR_READ | extended result codes] feature. 313 ** By default, SQLite API routines return one of only 26 integer 314 ** [SQLITE_OK | result codes]. When extended result codes 315 ** are enabled by this routine, the repetoire of result codes can be 316 ** much larger and can (hopefully) provide more detailed information 317 ** about the cause of an error. 318 ** 319 ** The second argument is a boolean value that turns extended result 320 ** codes on and off. Extended result codes are off by default for 321 ** backwards compatibility with older versions of SQLite. 322 */ 323 int sqlite3_extended_result_codes(sqlite3*, int onoff); 324 325 /* 326 ** CAPI3REF: Last Insert Rowid 327 ** 328 ** Each entry in an SQLite table has a unique 64-bit signed integer key 329 ** called the "rowid". The rowid is always available as an undeclared 330 ** column named ROWID, OID, or _ROWID_. If the table has a column of 331 ** type INTEGER PRIMARY KEY then that column is another an alias for the 332 ** rowid. 333 ** 334 ** This routine returns the rowid of the most recent INSERT into 335 ** the database from the database connection given in the first 336 ** argument. If no inserts have ever occurred on this database 337 ** connection, zero is returned. 338 ** 339 ** If an INSERT occurs within a trigger, then the rowid of the 340 ** inserted row is returned by this routine as long as the trigger 341 ** is running. But once the trigger terminates, the value returned 342 ** by this routine reverts to the last value inserted before the 343 ** trigger fired. 344 */ 345 sqlite_int64 sqlite3_last_insert_rowid(sqlite3*); 346 347 /* 348 ** CAPI3REF: Count The Number Of Rows Modified 349 ** 350 ** This function returns the number of database rows that were changed 351 ** (or inserted or deleted) by the most recent SQL statement. Only 352 ** changes that are directly specified by the INSERT, UPDATE, or 353 ** DELETE statement are counted. Auxiliary changes caused by 354 ** triggers are not counted. Use the [sqlite3_total_changes()] function 355 ** to find the total number of changes including changes caused by triggers. 356 ** 357 ** Within the body of a trigger, the sqlite3_changes() interface can be 358 ** called to find the number of 359 ** changes in the most recently completed INSERT, UPDATE, or DELETE 360 ** statement within the body of the trigger. 361 ** 362 ** All changes are counted, even if they were later undone by a 363 ** ROLLBACK or ABORT. Except, changes associated with creating and 364 ** dropping tables are not counted. 365 ** 366 ** If a callback invokes [sqlite3_exec()] or [sqlite3_step()] recursively, 367 ** then the changes in the inner, recursive call are counted together 368 ** with the changes in the outer call. 369 ** 370 ** SQLite implements the command "DELETE FROM table" without a WHERE clause 371 ** by dropping and recreating the table. (This is much faster than going 372 ** through and deleting individual elements form the table.) Because of 373 ** this optimization, the change count for "DELETE FROM table" will be 374 ** zero regardless of the number of elements that were originally in the 375 ** table. To get an accurate count of the number of rows deleted, use 376 ** "DELETE FROM table WHERE 1" instead. 377 */ 378 int sqlite3_changes(sqlite3*); 379 380 /* 381 ** CAPI3REF: Total Number Of Rows Modified 382 *** 383 ** This function returns the number of database rows that have been 384 ** modified by INSERT, UPDATE or DELETE statements since the database handle 385 ** was opened. This includes UPDATE, INSERT and DELETE statements executed 386 ** as part of trigger programs. All changes are counted as soon as the 387 ** statement that makes them is completed (when the statement handle is 388 ** passed to [sqlite3_reset()] or [sqlite_finalise()]). 389 ** 390 ** See also the [sqlite3_change()] interface. 391 ** 392 ** SQLite implements the command "DELETE FROM table" without a WHERE clause 393 ** by dropping and recreating the table. (This is much faster than going 394 ** through and deleting individual elements form the table.) Because of 395 ** this optimization, the change count for "DELETE FROM table" will be 396 ** zero regardless of the number of elements that were originally in the 397 ** table. To get an accurate count of the number of rows deleted, use 398 ** "DELETE FROM table WHERE 1" instead. 399 */ 400 int sqlite3_total_changes(sqlite3*); 401 402 /* 403 ** CAPI3REF: Interrupt A Long-Running Query 404 ** 405 ** This function causes any pending database operation to abort and 406 ** return at its earliest opportunity. This routine is typically 407 ** called in response to a user action such as pressing "Cancel" 408 ** or Ctrl-C where the user wants a long query operation to halt 409 ** immediately. 410 ** 411 ** It is safe to call this routine from a thread different from the 412 ** thread that is currently running the database operation. 413 ** 414 ** The SQL operation that is interrupted will return [SQLITE_INTERRUPT]. 415 ** If an interrupted operation was an update that is inside an 416 ** explicit transaction, then the entire transaction will be rolled 417 ** back automatically. 418 */ 419 void sqlite3_interrupt(sqlite3*); 420 421 /* 422 ** CAPI3REF: Determine If An SQL Statement Is Complete 423 ** 424 ** These functions return true if the given input string comprises 425 ** one or more complete SQL statements. For the sqlite3_complete() call, 426 ** the parameter must be a nul-terminated UTF-8 string. For 427 ** sqlite3_complete16(), a nul-terminated machine byte order UTF-16 string 428 ** is required. 429 ** 430 ** These routines are useful for command-line input to determine if the 431 ** currently entered text forms one or more complete SQL statements or 432 ** if additional input is needed before sending the statements into 433 ** SQLite for parsing. The algorithm is simple. If the 434 ** last token other than spaces and comments is a semicolon, then return 435 ** true. Actually, the algorithm is a little more complicated than that 436 ** in order to deal with triggers, but the basic idea is the same: the 437 ** statement is not complete unless it ends in a semicolon. 438 */ 439 int sqlite3_complete(const char *sql); 440 int sqlite3_complete16(const void *sql); 441 442 /* 443 ** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors 444 ** 445 ** This routine identifies a callback function that might be invoked 446 ** whenever an attempt is made to open a database table 447 ** that another thread or process has locked. 448 ** If the busy callback is NULL, then [SQLITE_BUSY] 449 ** (or sometimes [SQLITE_IOERR_BLOCKED]) 450 ** is returned immediately upon encountering the lock. 451 ** If the busy callback is not NULL, then the 452 ** callback will be invoked with two arguments. The 453 ** first argument to the handler is a copy of the void* pointer which 454 ** is the third argument to this routine. The second argument to 455 ** the handler is the number of times that the busy handler has 456 ** been invoked for this locking event. If the 457 ** busy callback returns 0, then no additional attempts are made to 458 ** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned. 459 ** If the callback returns non-zero, then another attempt is made to open the 460 ** database for reading and the cycle repeats. 461 ** 462 ** The presence of a busy handler does not guarantee that 463 ** it will be invoked when there is lock contention. 464 ** If SQLite determines that invoking the busy handler could result in 465 ** a deadlock, it will return [SQLITE_BUSY] instead. 466 ** Consider a scenario where one process is holding a read lock that 467 ** it is trying to promote to a reserved lock and 468 ** a second process is holding a reserved lock that it is trying 469 ** to promote to an exclusive lock. The first process cannot proceed 470 ** because it is blocked by the second and the second process cannot 471 ** proceed because it is blocked by the first. If both processes 472 ** invoke the busy handlers, neither will make any progress. Therefore, 473 ** SQLite returns [SQLITE_BUSY] for the first process, hoping that this 474 ** will induce the first process to release its read lock and allow 475 ** the second process to proceed. 476 ** 477 ** The default busy callback is NULL. 478 ** 479 ** The [SQLITE_BUSY] error is converted to [SQLITE_IOERR_BLOCKED] when 480 ** SQLite is in the middle of a large transaction where all the 481 ** changes will not fit into the in-memory cache. SQLite will 482 ** already hold a RESERVED lock on the database file, but it needs 483 ** to promote this lock to EXCLUSIVE so that it can spill cache 484 ** pages into the database file without harm to concurrent 485 ** readers. If it is unable to promote the lock, then the in-memory 486 ** cache will be left in an inconsistent state and so the error 487 ** code is promoted from the relatively benign [SQLITE_BUSY] to 488 ** the more severe [SQLITE_IOERR_BLOCKED]. This error code promotion 489 ** forces an automatic rollback of the changes. See the 490 ** <a href="http://www.sqlite.org/cvstrac/wiki?p=CorruptionFollowingBusyError"> 491 ** CorruptionFollowingBusyError</a> wiki page for a discussion of why 492 ** this is important. 493 ** 494 ** Sqlite is re-entrant, so the busy handler may start a new query. 495 ** (It is not clear why anyone would every want to do this, but it 496 ** is allowed, in theory.) But the busy handler may not close the 497 ** database. Closing the database from a busy handler will delete 498 ** data structures out from under the executing query and will 499 ** probably result in a segmentation fault or other runtime error. 500 ** 501 ** There can only be a single busy handler defined for each database 502 ** connection. Setting a new busy handler clears any previous one. 503 ** Note that calling [sqlite3_busy_timeout()] will also set or clear 504 ** the busy handler. 505 */ 506 int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*); 507 508 /* 509 ** CAPI3REF: Set A Busy Timeout 510 ** 511 ** This routine sets a busy handler that sleeps for a while when a 512 ** table is locked. The handler will sleep multiple times until 513 ** at least "ms" milliseconds of sleeping have been done. After 514 ** "ms" milliseconds of sleeping, the handler returns 0 which 515 ** causes [sqlite3_step()] to return [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED]. 516 ** 517 ** Calling this routine with an argument less than or equal to zero 518 ** turns off all busy handlers. 519 ** 520 ** There can only be a single busy handler for a particular database 521 ** connection. If another busy handler was defined 522 ** (using [sqlite3_busy_handler()]) prior to calling 523 ** this routine, that other busy handler is cleared. 524 */ 525 int sqlite3_busy_timeout(sqlite3*, int ms); 526 527 /* 528 ** CAPI3REF: Convenience Routines For Running Queries 529 ** 530 ** This next routine is a convenience wrapper around [sqlite3_exec()]. 531 ** Instead of invoking a user-supplied callback for each row of the 532 ** result, this routine remembers each row of the result in memory 533 ** obtained from [sqlite3_malloc()], then returns all of the result after the 534 ** query has finished. 535 ** 536 ** As an example, suppose the query result where this table: 537 ** 538 ** <pre> 539 ** Name | Age 540 ** ----------------------- 541 ** Alice | 43 542 ** Bob | 28 543 ** Cindy | 21 544 ** </pre> 545 ** 546 ** If the 3rd argument were &azResult then after the function returns 547 ** azResult will contain the following data: 548 ** 549 ** <pre> 550 ** azResult[0] = "Name"; 551 ** azResult[1] = "Age"; 552 ** azResult[2] = "Alice"; 553 ** azResult[3] = "43"; 554 ** azResult[4] = "Bob"; 555 ** azResult[5] = "28"; 556 ** azResult[6] = "Cindy"; 557 ** azResult[7] = "21"; 558 ** </pre> 559 ** 560 ** Notice that there is an extra row of data containing the column 561 ** headers. But the *nrow return value is still 3. *ncolumn is 562 ** set to 2. In general, the number of values inserted into azResult 563 ** will be ((*nrow) + 1)*(*ncolumn). 564 ** 565 ** After the calling function has finished using the result, it should 566 ** pass the result data pointer to sqlite3_free_table() in order to 567 ** release the memory that was malloc-ed. Because of the way the 568 ** [sqlite3_malloc()] happens, the calling function must not try to call 569 ** [sqlite3_free()] directly. Only [sqlite3_free_table()] is able to release 570 ** the memory properly and safely. 571 ** 572 ** The return value of this routine is the same as from [sqlite3_exec()]. 573 */ 574 int sqlite3_get_table( 575 sqlite3*, /* An open database */ 576 const char *sql, /* SQL to be executed */ 577 char ***resultp, /* Result written to a char *[] that this points to */ 578 int *nrow, /* Number of result rows written here */ 579 int *ncolumn, /* Number of result columns written here */ 580 char **errmsg /* Error msg written here */ 581 ); 582 void sqlite3_free_table(char **result); 583 584 /* 585 ** CAPI3REF: Formatted String Printing Functions 586 ** 587 ** These routines are workalikes of the "printf()" family of functions 588 ** from the standard C library. 589 ** 590 ** The sqlite3_mprintf() and sqlite3_vmprintf() routines write their 591 ** results into memory obtained from [sqlite_malloc()]. 592 ** The strings returned by these two routines should be 593 ** released by [sqlite3_free()]. Both routines return a 594 ** NULL pointer if [sqlite3_malloc()] is unable to allocate enough 595 ** memory to hold the resulting string. 596 ** 597 ** In sqlite3_snprintf() routine is similar to "snprintf()" from 598 ** the standard C library. The result is written into the 599 ** buffer supplied as the second parameter whose size is given by 600 ** the first parameter. Note that the order of the 601 ** first two parameters is reversed from snprintf(). This is an 602 ** historical accident that cannot be fixed without breaking 603 ** backwards compatibility. Note also that sqlite3_snprintf() 604 ** returns a pointer to its buffer instead of the number of 605 ** characters actually written into the buffer. We admit that 606 ** the number of characters written would be a more useful return 607 ** value but we cannot change the implementation of sqlite3_snprintf() 608 ** now without breaking compatibility. 609 ** 610 ** As long as the buffer size is greater than zero, sqlite3_snprintf() 611 ** guarantees that the buffer is always zero-terminated. The first 612 ** parameter "n" is the total size of the buffer, including space for 613 ** the zero terminator. So the longest string that can be completely 614 ** written will be n-1 characters. 615 ** 616 ** These routines all implement some additional formatting 617 ** options that are useful for constructing SQL statements. 618 ** All of the usual printf formatting options apply. In addition, there 619 ** is are "%q" and "%Q" options. 620 ** 621 ** The %q option works like %s in that it substitutes a null-terminated 622 ** string from the argument list. But %q also doubles every '\'' character. 623 ** %q is designed for use inside a string literal. By doubling each '\'' 624 ** character it escapes that character and allows it to be inserted into 625 ** the string. 626 ** 627 ** For example, so some string variable contains text as follows: 628 ** 629 ** <blockquote><pre> 630 ** char *zText = "It's a happy day!"; 631 ** </pre></blockquote> 632 ** 633 ** One can use this text in an SQL statement as follows: 634 ** 635 ** <blockquote><pre> 636 ** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText); 637 ** sqlite3_exec(db, zSQL, 0, 0, 0); 638 ** sqlite3_free(zSQL); 639 ** </pre></blockquote> 640 ** 641 ** Because the %q format string is used, the '\'' character in zText 642 ** is escaped and the SQL generated is as follows: 643 ** 644 ** <blockquote><pre> 645 ** INSERT INTO table1 VALUES('It''s a happy day!') 646 ** </pre></blockquote> 647 ** 648 ** This is correct. Had we used %s instead of %q, the generated SQL 649 ** would have looked like this: 650 ** 651 ** <blockquote><pre> 652 ** INSERT INTO table1 VALUES('It's a happy day!'); 653 ** </pre></blockquote> 654 ** 655 ** This second example is an SQL syntax error. As a general rule you 656 ** should always use %q instead of %s when inserting text into a string 657 ** literal. 658 ** 659 ** The %Q option works like %q except it also adds single quotes around 660 ** the outside of the total string. Or if the parameter in the argument 661 ** list is a NULL pointer, %Q substitutes the text "NULL" (without single 662 ** quotes) in place of the %Q option. So, for example, one could say: 663 ** 664 ** <blockquote><pre> 665 ** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText); 666 ** sqlite3_exec(db, zSQL, 0, 0, 0); 667 ** sqlite3_free(zSQL); 668 ** </pre></blockquote> 669 ** 670 ** The code above will render a correct SQL statement in the zSQL 671 ** variable even if the zText variable is a NULL pointer. 672 */ 673 char *sqlite3_mprintf(const char*,...); 674 char *sqlite3_vmprintf(const char*, va_list); 675 char *sqlite3_snprintf(int,char*,const char*, ...); 676 677 /* 678 ** CAPI3REF: Memory Allocation Functions 679 ** 680 ** SQLite uses its own memory allocator. On some installations, this 681 ** memory allocator is identical to the standard malloc()/realloc()/free() 682 ** and can be used interchangable. On others, the implementations are 683 ** different. For maximum portability, it is best not to mix calls 684 ** to the standard malloc/realloc/free with the sqlite versions. 685 */ 686 void *sqlite3_malloc(int); 687 void *sqlite3_realloc(void*, int); 688 void sqlite3_free(void*); 689 690 /* 691 ** CAPI3REF: Compile-Time Authorization Callbacks 692 *** 693 ** This routine registers a authorizer callback with the SQLite library. 694 ** The authorizer callback is invoked as SQL statements are being compiled 695 ** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()], 696 ** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()]. At various 697 ** points during the compilation process, as logic is being created 698 ** to perform various actions, the authorizer callback is invoked to 699 ** see if those actions are allowed. The authorizer callback should 700 ** return SQLITE_OK to allow the action, [SQLITE_IGNORE] to disallow the 701 ** specific action but allow the SQL statement to continue to be 702 ** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be 703 ** rejected with an error. 704 ** 705 ** Depending on the action, the [SQLITE_IGNORE] and [SQLITE_DENY] return 706 ** codes might mean something different or they might mean the same 707 ** thing. If the action is, for example, to perform a delete opertion, 708 ** then [SQLITE_IGNORE] and [SQLITE_DENY] both cause the statement compilation 709 ** to fail with an error. But if the action is to read a specific column 710 ** from a specific table, then [SQLITE_DENY] will cause the entire 711 ** statement to fail but [SQLITE_IGNORE] will cause a NULL value to be 712 ** read instead of the actual column value. 713 ** 714 ** The first parameter to the authorizer callback is a copy of 715 ** the third parameter to the sqlite3_set_authorizer() interface. 716 ** The second parameter to the callback is an integer 717 ** [SQLITE_COPY | action code] that specifies the particular action 718 ** to be authorized. The available action codes are 719 ** [SQLITE_COPY | documented separately]. The third through sixth 720 ** parameters to the callback are strings that contain additional 721 ** details about the action to be authorized. 722 ** 723 ** An authorizer is used when preparing SQL statements from an untrusted 724 ** source, to ensure that the SQL statements do not try to access data 725 ** that they are not allowed to see, or that they do not try to 726 ** execute malicious statements that damage the database. For 727 ** example, an application may allow a user to enter arbitrary 728 ** SQL queries for evaluation by a database. But the application does 729 ** not want the user to be able to make arbitrary changes to the 730 ** database. An authorizer could then be put in place while the 731 ** user-entered SQL is being prepared that disallows everything 732 ** except SELECT statements. 733 ** 734 ** Only a single authorizer can be in place on a database connection 735 ** at a time. Each call to sqlite3_set_authorizer overrides the 736 ** previous call. A NULL authorizer means that no authorization 737 ** callback is invoked. The default authorizer is NULL. 738 ** 739 ** Note that the authorizer callback is invoked only during 740 ** [sqlite3_prepare()] or its variants. Authorization is not 741 ** performed during statement evaluation in [sqlite3_step()]. 742 */ 743 int sqlite3_set_authorizer( 744 sqlite3*, 745 int (*xAuth)(void*,int,const char*,const char*,const char*,const char*), 746 void *pUserData 747 ); 748 749 /* 750 ** CAPI3REF: Authorizer Return Codes 751 ** 752 ** The [sqlite3_set_authorizer | authorizer callback function] must 753 ** return either [SQLITE_OK] or one of these two constants in order 754 ** to signal SQLite whether or not the action is permitted. See the 755 ** [sqlite3_set_authorizer | authorizer documentation] for additional 756 ** information. 757 */ 758 #define SQLITE_DENY 1 /* Abort the SQL statement with an error */ 759 #define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */ 760 761 /* 762 ** CAPI3REF: Authorizer Action Codes 763 ** 764 ** The [sqlite3_set_authorizer()] interface registers a callback function 765 ** that is invoked to authorizer certain SQL statement actions. The 766 ** second parameter to the callback is an integer code that specifies 767 ** what action is being authorized. These are the integer action codes that 768 ** the authorizer callback may be passed. 769 ** 770 ** These action code values signify what kind of operation is to be 771 ** authorized. The 3rd and 4th parameters to the authorization callback 772 ** function will be parameters or NULL depending on which of these 773 ** codes is used as the second parameter. The 5th parameter to the 774 ** authorizer callback is the name of the database ("main", "temp", 775 ** etc.) if applicable. The 6th parameter to the authorizer callback 776 ** is the name of the inner-most trigger or view that is responsible for 777 ** the access attempt or NULL if this access attempt is directly from 778 ** top-level SQL code. 779 */ 780 /******************************************* 3rd ************ 4th ***********/ 781 #define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */ 782 #define SQLITE_CREATE_TABLE 2 /* Table Name NULL */ 783 #define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */ 784 #define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */ 785 #define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */ 786 #define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */ 787 #define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */ 788 #define SQLITE_CREATE_VIEW 8 /* View Name NULL */ 789 #define SQLITE_DELETE 9 /* Table Name NULL */ 790 #define SQLITE_DROP_INDEX 10 /* Index Name Table Name */ 791 #define SQLITE_DROP_TABLE 11 /* Table Name NULL */ 792 #define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */ 793 #define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */ 794 #define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */ 795 #define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */ 796 #define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */ 797 #define SQLITE_DROP_VIEW 17 /* View Name NULL */ 798 #define SQLITE_INSERT 18 /* Table Name NULL */ 799 #define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */ 800 #define SQLITE_READ 20 /* Table Name Column Name */ 801 #define SQLITE_SELECT 21 /* NULL NULL */ 802 #define SQLITE_TRANSACTION 22 /* NULL NULL */ 803 #define SQLITE_UPDATE 23 /* Table Name Column Name */ 804 #define SQLITE_ATTACH 24 /* Filename NULL */ 805 #define SQLITE_DETACH 25 /* Database Name NULL */ 806 #define SQLITE_ALTER_TABLE 26 /* Database Name Table Name */ 807 #define SQLITE_REINDEX 27 /* Index Name NULL */ 808 #define SQLITE_ANALYZE 28 /* Table Name NULL */ 809 #define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */ 810 #define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */ 811 #define SQLITE_FUNCTION 31 /* Function Name NULL */ 812 #define SQLITE_COPY 0 /* No longer used */ 813 814 /* 815 ** CAPI3REF: Tracing And Profiling Functions 816 ** 817 ** These routines register callback functions that can be used for 818 ** tracing and profiling the execution of SQL statements. 819 ** The callback function registered by sqlite3_trace() is invoked 820 ** at the first [sqlite3_step()] for the evaluation of an SQL statement. 821 ** The callback function registered by sqlite3_profile() is invoked 822 ** as each SQL statement finishes and includes 823 ** information on how long that statement ran. 824 ** 825 ** The sqlite3_profile() API is currently considered experimental and 826 ** is subject to change. 827 */ 828 void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*); 829 void *sqlite3_profile(sqlite3*, 830 void(*xProfile)(void*,const char*,sqlite_uint64), void*); 831 832 /* 833 ** CAPI3REF: Query Progress Callbacks 834 ** 835 ** This routine configures a callback function - the progress callback - that 836 ** is invoked periodically during long running calls to [sqlite3_exec()], 837 ** [sqlite3_step()] and [sqlite3_get_table()]. An example use for this 838 ** interface is to keep a GUI updated during a large query. 839 ** 840 ** The progress callback is invoked once for every N virtual machine opcodes, 841 ** where N is the second argument to this function. The progress callback 842 ** itself is identified by the third argument to this function. The fourth 843 ** argument to this function is a void pointer passed to the progress callback 844 ** function each time it is invoked. 845 ** 846 ** If a call to [sqlite3_exec()], [sqlite3_step()], or [sqlite3_get_table()] 847 ** results in fewer than N opcodes being executed, then the progress 848 ** callback is never invoked. 849 ** 850 ** Only a single progress callback function may be registered for each 851 ** open database connection. Every call to sqlite3_progress_handler() 852 ** overwrites the results of the previous call. 853 ** To remove the progress callback altogether, pass NULL as the third 854 ** argument to this function. 855 ** 856 ** If the progress callback returns a result other than 0, then the current 857 ** query is immediately terminated and any database changes rolled back. 858 ** The containing [sqlite3_exec()], [sqlite3_step()], or 859 ** [sqlite3_get_table()] call returns SQLITE_INTERRUPT. This feature 860 ** can be used, for example, to implement the "Cancel" button on a 861 ** progress dialog box in a GUI. 862 */ 863 void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*); 864 865 /* 866 ** CAPI3REF: Opening A New Database Connection 867 ** 868 ** Open the sqlite database file "filename". The "filename" is UTF-8 869 ** encoded for sqlite3_open() and UTF-16 encoded in the native byte order 870 ** for sqlite3_open16(). An [sqlite3*] handle is returned in *ppDb, even 871 ** if an error occurs. If the database is opened (or created) successfully, 872 ** then SQLITE_OK is returned. Otherwise an error code is returned. The 873 ** sqlite3_errmsg() or sqlite3_errmsg16() routines can be used to obtain 874 ** an English language description of the error. 875 ** 876 ** If the database file does not exist, then a new database will be created 877 ** as needed. The default encoding for the database will be UTF-8 if 878 ** sqlite3_open() is called and UTF-16 if sqlite3_open16 is used. 879 ** 880 ** Whether or not an error occurs when it is opened, resources associated 881 ** with the [sqlite3*] handle should be released by passing it to 882 ** sqlite3_close() when it is no longer required. 883 ** 884 ** Note to windows users: The encoding used for the filename argument 885 ** of sqlite3_open() must be UTF-8, not whatever codepage is currently 886 ** defined. Filenames containing international characters must be converted 887 ** to UTF-8 prior to passing them into sqlite3_open(). 888 */ 889 int sqlite3_open( 890 const char *filename, /* Database filename (UTF-8) */ 891 sqlite3 **ppDb /* OUT: SQLite db handle */ 892 ); 893 int sqlite3_open16( 894 const void *filename, /* Database filename (UTF-16) */ 895 sqlite3 **ppDb /* OUT: SQLite db handle */ 896 ); 897 898 /* 899 ** CAPI3REF: Error Codes And Messages 900 ** 901 ** The sqlite3_errcode() interface returns the numeric 902 ** [SQLITE_OK | result code] or [SQLITE_IOERR_READ | extended result code] 903 ** for the most recent failed sqlite3_* API call associated 904 ** with [sqlite3] handle 'db'. If a prior API call failed but the 905 ** most recent API call succeeded, the return value from sqlite3_errcode() 906 ** is undefined. 907 ** 908 ** The sqlite3_errmsg() and sqlite3_errmsg16() return English-langauge 909 ** text that describes the error, as either UTF8 or UTF16 respectively. 910 ** Memory to hold the error message string is managed internally. The 911 ** string may be overwritten or deallocated by subsequent calls to SQLite 912 ** interface functions. 913 ** 914 ** Calls to many sqlite3_* functions set the error code and string returned 915 ** by [sqlite3_errcode()], [sqlite3_errmsg()], and [sqlite3_errmsg16()] 916 ** (overwriting the previous values). Note that calls to [sqlite3_errcode()], 917 ** [sqlite3_errmsg()], and [sqlite3_errmsg16()] themselves do not affect the 918 ** results of future invocations. Calls to API routines that do not return 919 ** an error code (examples: [sqlite3_data_count()] or [sqlite3_mprintf()]) do 920 ** not change the error code returned by this routine. 921 ** 922 ** Assuming no other intervening sqlite3_* API calls are made, the error 923 ** code returned by this function is associated with the same error as 924 ** the strings returned by [sqlite3_errmsg()] and [sqlite3_errmsg16()]. 925 */ 926 int sqlite3_errcode(sqlite3 *db); 927 const char *sqlite3_errmsg(sqlite3*); 928 const void *sqlite3_errmsg16(sqlite3*); 929 930 /* 931 ** CAPI3REF: SQL Statement Object 932 ** 933 ** Instance of this object represent single SQL statements. This 934 ** is variously known as a "prepared statement" or a 935 ** "compiled SQL statement" or simply as a "statement". 936 ** 937 ** The life of a statement object goes something like this: 938 ** 939 ** <ol> 940 ** <li> Create the object using [sqlite3_prepare_v2()] or a related 941 ** function. 942 ** <li> Bind values to host parameters using 943 ** [sqlite3_bind_blob | sqlite3_bind_* interfaces]. 944 ** <li> Run the SQL by calling [sqlite3_step()] one or more times. 945 ** <li> Reset the statement using [sqlite3_reset()] then go back 946 ** to step 2. Do this zero or more times. 947 ** <li> Destroy the object using [sqlite3_finalize()]. 948 ** </ol> 949 ** 950 ** Refer to documentation on individual methods above for additional 951 ** information. 952 */ 953 typedef struct sqlite3_stmt sqlite3_stmt; 954 955 /* 956 ** CAPI3REF: Compiling An SQL Statement 957 ** 958 ** To execute an SQL query, it must first be compiled into a byte-code 959 ** program using one of these routines. 960 ** 961 ** The first argument "db" is an [sqlite3 | SQLite database handle] 962 ** obtained from a prior call to [sqlite3_open()] or [sqlite3_open16()]. 963 ** The second argument "zSql" is the statement to be compiled, encoded 964 ** as either UTF-8 or UTF-16. The sqlite3_prepare() and sqlite3_prepare_v2() 965 ** interfaces uses UTF-8 and sqlite3_prepare16() and sqlite3_prepare16_v2() 966 ** use UTF-16. If the next argument, "nBytes", is less 967 ** than zero, then zSql is read up to the first zero terminator. If 968 ** "nBytes" is not less than zero, then it is the length of the string zSql 969 ** in bytes (not characters). 970 ** 971 ** *pzTail is made to point to the first byte past the end of the first 972 ** SQL statement in zSql. This routine only compiles the first statement 973 ** in zSql, so *pzTail is left pointing to what remains uncompiled. 974 ** 975 ** *ppStmt is left pointing to a compiled 976 ** [sqlite3_stmt | SQL statement structure] that can be 977 ** executed using [sqlite3_step()]. Or if there is an error, *ppStmt may be 978 ** set to NULL. If the input text contained no SQL (if the input is and 979 ** empty string or a comment) then *ppStmt is set to NULL. The calling 980 ** procedure is responsible for deleting the compiled SQL statement 981 ** using [sqlite3_finalize()] after it has finished with it. 982 ** 983 ** On success, [SQLITE_OK] is returned. Otherwise an 984 ** [SQLITE_ERROR | error code] is returned. 985 ** 986 ** The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are 987 ** recommended for all new programs. The two older interfaces are retained 988 ** for backwards compatibility, but their use is discouraged. 989 ** In the "v2" interfaces, the prepared statement 990 ** that is returned (the [sqlite3_stmt] object) contains a copy of the 991 ** original SQL text. This causes the [sqlite3_step()] interface to 992 ** behave a differently in two ways: 993 ** 994 ** <ol> 995 ** <li> 996 ** If the database schema changes, instead of returning [SQLITE_SCHEMA] as it 997 ** always used to do, [sqlite3_step()] will automatically recompile the SQL 998 ** statement and try to run it again. If the schema has changed in a way 999 ** that makes the statement no longer valid, [sqlite3_step()] will still 1000 ** return [SQLITE_SCHEMA]. But unlike the legacy behavior, [SQLITE_SCHEMA] is 1001 ** now a fatal error. Calling [sqlite3_prepare_v2()] again will not make the 1002 ** error go away. Note: use [sqlite3_errmsg()] to find the text of the parsing 1003 ** error that results in an [SQLITE_SCHEMA] return. 1004 ** </li> 1005 ** 1006 ** <li> 1007 ** When an error occurs, 1008 ** [sqlite3_step()] will return one of the detailed 1009 ** [SQLITE_ERROR | result codes] or 1010 ** [SQLITE_IOERR_READ | extended result codes] such as directly. 1011 ** The legacy behavior was that [sqlite3_step()] would only return a generic 1012 ** [SQLITE_ERROR] result code and you would have to make a second call to 1013 ** [sqlite3_reset()] in order to find the underlying cause of the problem. 1014 ** With the "v2" prepare interfaces, the underlying reason for the error is 1015 ** returned immediately. 1016 ** </li> 1017 ** </ol> 1018 */ 1019 int sqlite3_prepare( 1020 sqlite3 *db, /* Database handle */ 1021 const char *zSql, /* SQL statement, UTF-8 encoded */ 1022 int nBytes, /* Length of zSql in bytes. */ 1023 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ 1024 const char **pzTail /* OUT: Pointer to unused portion of zSql */ 1025 ); 1026 int sqlite3_prepare_v2( 1027 sqlite3 *db, /* Database handle */ 1028 const char *zSql, /* SQL statement, UTF-8 encoded */ 1029 int nBytes, /* Length of zSql in bytes. */ 1030 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ 1031 const char **pzTail /* OUT: Pointer to unused portion of zSql */ 1032 ); 1033 int sqlite3_prepare16( 1034 sqlite3 *db, /* Database handle */ 1035 const void *zSql, /* SQL statement, UTF-16 encoded */ 1036 int nBytes, /* Length of zSql in bytes. */ 1037 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ 1038 const void **pzTail /* OUT: Pointer to unused portion of zSql */ 1039 ); 1040 int sqlite3_prepare16_v2( 1041 sqlite3 *db, /* Database handle */ 1042 const void *zSql, /* SQL statement, UTF-16 encoded */ 1043 int nBytes, /* Length of zSql in bytes. */ 1044 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ 1045 const void **pzTail /* OUT: Pointer to unused portion of zSql */ 1046 ); 1047 1048 /* 1049 ** CAPI3REF: Dynamically Typed Value Object 1050 ** 1051 ** SQLite uses dynamic typing for the values it stores. Values can 1052 ** be integers, floating point values, strings, BLOBs, or NULL. When 1053 ** passing around values internally, each value is represented as 1054 ** an instance of the sqlite3_value object. 1055 */ 1056 typedef struct Mem sqlite3_value; 1057 1058 /* 1059 ** CAPI3REF: SQL Function Context Object 1060 ** 1061 ** The context in which an SQL function executes is stored in an 1062 ** sqlite3_context object. A pointer to such an object is the 1063 ** first parameter to user-defined SQL functions. 1064 */ 1065 typedef struct sqlite3_context sqlite3_context; 1066 1067 /* 1068 ** CAPI3REF: Binding Values To Prepared Statements 1069 ** 1070 ** In the SQL strings input to [sqlite3_prepare_v2()] and its variants, 1071 ** one or more literals can be replace by a parameter in one of these 1072 ** forms: 1073 ** 1074 ** <ul> 1075 ** <li> ? 1076 ** <li> ?NNN 1077 ** <li> :AAA 1078 ** <li> @AAA 1079 ** <li> $VVV 1080 ** </ul> 1081 ** 1082 ** In the parameter forms shown above NNN is an integer literal, 1083 ** AAA is an alphanumeric identifier and VVV is a variable name according 1084 ** to the syntax rules of the TCL programming language. 1085 ** The values of these parameters (also called "host parameter names") 1086 ** can be set using the sqlite3_bind_*() routines defined here. 1087 ** 1088 ** The first argument to the sqlite3_bind_*() routines always is a pointer 1089 ** to the [sqlite3_stmt] object returned from [sqlite3_prepare_v2()] or 1090 ** its variants. The second 1091 ** argument is the index of the parameter to be set. The first parameter has 1092 ** an index of 1. When the same named parameter is used more than once, second 1093 ** and subsequent 1094 ** occurrences have the same index as the first occurrence. The index for 1095 ** named parameters can be looked up using the 1096 ** [sqlite3_bind_parameter_name()] API if desired. The index for "?NNN" 1097 ** parametes is the value of NNN. 1098 ** The NNN value must be between 1 and the compile-time 1099 ** parameter SQLITE_MAX_VARIABLE_NUMBER (default value: 999). 1100 ** See <a href="limits.html">limits.html</a> for additional information. 1101 ** 1102 ** The third argument is the value to bind to the parameter. 1103 ** 1104 ** In those 1105 ** routines that have a fourth argument, its value is the number of bytes 1106 ** in the parameter. To be clear: the value is the number of bytes in the 1107 ** string, not the number of characters. The number 1108 ** of bytes does not include the zero-terminator at the end of strings. 1109 ** If the fourth parameter is negative, the length of the string is 1110 ** number of bytes up to the first zero terminator. 1111 ** 1112 ** The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and 1113 ** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or 1114 ** text after SQLite has finished with it. If the fifth argument is the 1115 ** special value [SQLITE_STATIC], then the library assumes that the information 1116 ** is in static, unmanaged space and does not need to be freed. If the 1117 ** fifth argument has the value [SQLITE_TRANSIENT], then SQLite makes its 1118 ** own private copy of the data immediately, before the sqlite3_bind_*() 1119 ** routine returns. 1120 ** 1121 ** The sqlite3_bind_zeroblob() routine binds a BLOB of length n that 1122 ** is filled with zeros. A zeroblob uses a fixed amount of memory 1123 ** (just an integer to hold it size) while it is being processed. 1124 ** Zeroblobs are intended to serve as place-holders for BLOBs whose 1125 ** content is later written using 1126 ** [sqlite3_blob_open | increment BLOB I/O] routines. 1127 ** 1128 ** The sqlite3_bind_*() routines must be called after 1129 ** [sqlite3_prepare_v2()] (and its variants) or [sqlite3_reset()] and 1130 ** before [sqlite3_step()]. 1131 ** Bindings are not cleared by the [sqlite3_reset()] routine. 1132 ** Unbound parameters are interpreted as NULL. 1133 ** 1134 ** These routines return [SQLITE_OK] on success or an error code if 1135 ** anything goes wrong. [SQLITE_RANGE] is returned if the parameter 1136 ** index is out of range. [SQLITE_NOMEM] is returned if malloc fails. 1137 ** [SQLITE_MISUSE] is returned if these routines are called on a virtual 1138 ** machine that is the wrong state or which has already been finalized. 1139 */ 1140 int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*)); 1141 int sqlite3_bind_double(sqlite3_stmt*, int, double); 1142 int sqlite3_bind_int(sqlite3_stmt*, int, int); 1143 int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite_int64); 1144 int sqlite3_bind_null(sqlite3_stmt*, int); 1145 int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*)); 1146 int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*)); 1147 int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*); 1148 int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n); 1149 1150 /* 1151 ** CAPI3REF: Number Of Host Parameters 1152 ** 1153 ** Return the largest host parameter index in the precompiled statement given 1154 ** as the argument. When the host parameters are of the forms like ":AAA" 1155 ** or "?", then they are assigned sequential increasing numbers beginning 1156 ** with one, so the value returned is the number of parameters. However 1157 ** if the same host parameter name is used multiple times, each occurrance 1158 ** is given the same number, so the value returned in that case is the number 1159 ** of unique host parameter names. If host parameters of the form "?NNN" 1160 ** are used (where NNN is an integer) then there might be gaps in the 1161 ** numbering and the value returned by this interface is the index of the 1162 ** host parameter with the largest index value. 1163 */ 1164 int sqlite3_bind_parameter_count(sqlite3_stmt*); 1165 1166 /* 1167 ** CAPI3REF: Name Of A Host Parameter 1168 ** 1169 ** This routine returns a pointer to the name of the n-th parameter in a 1170 ** [sqlite3_stmt | prepared statement]. 1171 ** Host parameters of the form ":AAA" or "@AAA" or "$VVV" have a name 1172 ** which is the string ":AAA" or "@AAA" or "$VVV". 1173 ** In other words, the initial ":" or "$" or "@" 1174 ** is included as part of the name. 1175 ** Parameters of the form "?" or "?NNN" have no name. 1176 ** 1177 ** The first bound parameter has an index of 1, not 0. 1178 ** 1179 ** If the value n is out of range or if the n-th parameter is nameless, 1180 ** then NULL is returned. The returned string is always in the 1181 ** UTF-8 encoding even if the named parameter was originally specified 1182 ** as UTF-16 in [sqlite3_prepare16()] or [sqlite3_prepare16_v2()]. 1183 */ 1184 const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int); 1185 1186 /* 1187 ** CAPI3REF: Index Of A Parameter With A Given Name 1188 ** 1189 ** This routine returns the index of a host parameter with the given name. 1190 ** The name must match exactly. If no parameter with the given name is 1191 ** found, return 0. Parameter names must be UTF8. 1192 */ 1193 int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName); 1194 1195 /* 1196 ** CAPI3REF: Reset All Bindings On A Prepared Statement 1197 ** 1198 ** Contrary to the intuition of many, [sqlite3_reset()] does not 1199 ** reset the [sqlite3_bind_blob | bindings] on a 1200 ** [sqlite3_stmt | prepared statement]. Use this routine to 1201 ** reset all host parameters to NULL. 1202 */ 1203 int sqlite3_clear_bindings(sqlite3_stmt*); 1204 1205 /* 1206 ** CAPI3REF: Number Of Columns In A Result Set 1207 ** 1208 ** Return the number of columns in the result set returned by the 1209 ** [sqlite3_stmt | compiled SQL statement]. This routine returns 0 1210 ** if pStmt is an SQL statement that does not return data (for 1211 ** example an UPDATE). 1212 */ 1213 int sqlite3_column_count(sqlite3_stmt *pStmt); 1214 1215 /* 1216 ** CAPI3REF: Column Names In A Result Set 1217 ** 1218 ** These routines return the name assigned to a particular column 1219 ** in the result set of a SELECT statement. The sqlite3_column_name() 1220 ** interface returns a pointer to a UTF8 string and sqlite3_column_name16() 1221 ** returns a pointer to a UTF16 string. The first parameter is the 1222 ** [sqlite_stmt | prepared statement] that implements the SELECT statement. 1223 ** The second parameter is the column number. The left-most column is 1224 ** number 0. 1225 ** 1226 ** The returned string pointer is valid until either the 1227 ** [sqlite_stmt | prepared statement] is destroyed by [sqlite3_finalize()] 1228 ** or until the next call sqlite3_column_name() or sqlite3_column_name16() 1229 ** on the same column. 1230 */ 1231 const char *sqlite3_column_name(sqlite3_stmt*, int N); 1232 const void *sqlite3_column_name16(sqlite3_stmt*, int N); 1233 1234 /* 1235 ** CAPI3REF: Source Of Data In A Query Result 1236 ** 1237 ** These routines provide a means to determine what column of what 1238 ** table in which database a result of a SELECT statement comes from. 1239 ** The name of the database or table or column can be returned as 1240 ** either a UTF8 or UTF16 string. The returned string is valid until 1241 ** the [sqlite3_stmt | prepared statement] is destroyed using 1242 ** [sqlite3_finalize()] or until the same information is requested 1243 ** again about the same column. 1244 ** 1245 ** The first argument to the following calls is a 1246 ** [sqlite3_stmt | compiled SQL statement]. 1247 ** These functions return information about the Nth column returned by 1248 ** the statement, where N is the second function argument. 1249 ** 1250 ** If the Nth column returned by the statement is an expression 1251 ** or subquery and is not a column value, then all of these functions 1252 ** return NULL. Otherwise, they return the 1253 ** name of the attached database, table and column that query result 1254 ** column was extracted from. 1255 ** 1256 ** As with all other SQLite APIs, those postfixed with "16" return UTF-16 1257 ** encoded strings, the other functions return UTF-8. 1258 ** 1259 ** These APIs are only available if the library was compiled with the 1260 ** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined. 1261 */ 1262 const char *sqlite3_column_database_name(sqlite3_stmt*,int); 1263 const void *sqlite3_column_database_name16(sqlite3_stmt*,int); 1264 const char *sqlite3_column_table_name(sqlite3_stmt*,int); 1265 const void *sqlite3_column_table_name16(sqlite3_stmt*,int); 1266 const char *sqlite3_column_origin_name(sqlite3_stmt*,int); 1267 const void *sqlite3_column_origin_name16(sqlite3_stmt*,int); 1268 1269 /* 1270 ** CAPI3REF: Declared Datatype Of A Query Result 1271 ** 1272 ** The first parameter is a [sqlite3_stmt | compiled SQL statement]. 1273 ** If this statement is a SELECT statement and the Nth column of the 1274 ** returned result set of that SELECT is a table column (not an 1275 ** expression or subquery) then the declared type of the table 1276 ** column is returned. If the Nth column of the result set is an 1277 ** expression or subquery, then a NULL pointer is returned. 1278 ** The returned string is always UTF-8 encoded. For example, in 1279 ** the database schema: 1280 ** 1281 ** CREATE TABLE t1(c1 VARIANT); 1282 ** 1283 ** And the following statement compiled: 1284 ** 1285 ** SELECT c1 + 1, c1 FROM t1; 1286 ** 1287 ** Then this routine would return the string "VARIANT" for the second 1288 ** result column (i==1), and a NULL pointer for the first result column 1289 ** (i==0). 1290 ** 1291 ** SQLite uses dynamic run-time typing. So just because a column 1292 ** is declared to contain a particular type does not mean that the 1293 ** data stored in that column is of the declared type. SQLite is 1294 ** strongly typed, but the typing is dynamic not static. Type 1295 ** is associated with individual values, not with the containers 1296 ** used to hold those values. 1297 */ 1298 const char *sqlite3_column_decltype(sqlite3_stmt *, int i); 1299 const void *sqlite3_column_decltype16(sqlite3_stmt*,int); 1300 1301 /* 1302 ** CAPI3REF: Evaluate An SQL Statement 1303 ** 1304 ** After an [sqlite3_stmt | SQL statement] has been prepared with a call 1305 ** to either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or to one of 1306 ** the legacy interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], 1307 ** then this function must be called one or more times to evaluate the 1308 ** statement. 1309 ** 1310 ** The details of the behavior of this sqlite3_step() interface depend 1311 ** on whether the statement was prepared using the newer "v2" interface 1312 ** [sqlite3_prepare_v2()] and [sqlite3_prepare16_v2()] or the older legacy 1313 ** interface [sqlite3_prepare()] and [sqlite3_prepare16()]. The use of the 1314 ** new "v2" interface is recommended for new applications but the legacy 1315 ** interface will continue to be supported. 1316 ** 1317 ** In the lagacy interface, the return value will be either [SQLITE_BUSY], 1318 ** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE]. 1319 ** With the "v2" interface, any of the other [SQLITE_OK | result code] 1320 ** or [SQLITE_IOERR_READ | extended result code] might be returned as 1321 ** well. 1322 ** 1323 ** [SQLITE_BUSY] means that the database engine was unable to acquire the 1324 ** database locks it needs to do its job. If the statement is a COMMIT 1325 ** or occurs outside of an explicit transaction, then you can retry the 1326 ** statement. If the statement is not a COMMIT and occurs within a 1327 ** explicit transaction then you should rollback the transaction before 1328 ** continuing. 1329 ** 1330 ** [SQLITE_DONE] means that the statement has finished executing 1331 ** successfully. sqlite3_step() should not be called again on this virtual 1332 ** machine without first calling [sqlite3_reset()] to reset the virtual 1333 ** machine back to its initial state. 1334 ** 1335 ** If the SQL statement being executed returns any data, then 1336 ** [SQLITE_ROW] is returned each time a new row of data is ready 1337 ** for processing by the caller. The values may be accessed using 1338 ** the [sqlite3_column_int | column access functions]. 1339 ** sqlite3_step() is called again to retrieve the next row of data. 1340 ** 1341 ** [SQLITE_ERROR] means that a run-time error (such as a constraint 1342 ** violation) has occurred. sqlite3_step() should not be called again on 1343 ** the VM. More information may be found by calling [sqlite3_errmsg()]. 1344 ** With the legacy interface, a more specific error code (example: 1345 ** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth) 1346 ** can be obtained by calling [sqlite3_reset()] on the 1347 ** [sqlite_stmt | prepared statement]. In the "v2" interface, 1348 ** the more specific error code is returned directly by sqlite3_step(). 1349 ** 1350 ** [SQLITE_MISUSE] means that the this routine was called inappropriately. 1351 ** Perhaps it was called on a [sqlite_stmt | prepared statement] that has 1352 ** already been [sqlite3_finalize | finalized] or on one that had 1353 ** previously returned [SQLITE_ERROR] or [SQLITE_DONE]. Or it could 1354 ** be the case that the same database connection is being used by two or 1355 ** more threads at the same moment in time. 1356 ** 1357 ** <b>Goofy Interface Alert:</b> 1358 ** In the legacy interface, 1359 ** the sqlite3_step() API always returns a generic error code, 1360 ** [SQLITE_ERROR], following any error other than [SQLITE_BUSY] 1361 ** and [SQLITE_MISUSE]. You must call [sqlite3_reset()] or 1362 ** [sqlite3_finalize()] in order to find one of the specific 1363 ** [SQLITE_ERROR | result codes] that better describes the error. 1364 ** We admit that this is a goofy design. The problem has been fixed 1365 ** with the "v2" interface. If you prepare all of your SQL statements 1366 ** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead 1367 ** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()], then the 1368 ** more specific [SQLITE_ERROR | result codes] are returned directly 1369 ** by sqlite3_step(). The use of the "v2" interface is recommended. 1370 */ 1371 int sqlite3_step(sqlite3_stmt*); 1372 1373 /* 1374 ** CAPI3REF: 1375 ** 1376 ** Return the number of values in the current row of the result set. 1377 ** 1378 ** After a call to [sqlite3_step()] that returns [SQLITE_ROW], this routine 1379 ** will return the same value as the [sqlite3_column_count()] function. 1380 ** After [sqlite3_step()] has returned an [SQLITE_DONE], [SQLITE_BUSY], or 1381 ** a [SQLITE_ERROR | error code], or before [sqlite3_step()] has been 1382 ** called on the [sqlite_stmt | prepared statement] for the first time, 1383 ** this routine returns zero. 1384 */ 1385 int sqlite3_data_count(sqlite3_stmt *pStmt); 1386 1387 /* 1388 ** CAPI3REF: Fundamental Datatypes 1389 ** 1390 ** Every value in SQLite has one of five fundamental datatypes: 1391 ** 1392 ** <ul> 1393 ** <li> 64-bit signed integer 1394 ** <li> 64-bit IEEE floating point number 1395 ** <li> string 1396 ** <li> BLOB 1397 ** <li> NULL 1398 ** </ul> 1399 ** 1400 ** These constants are codes for each of those types. 1401 ** 1402 ** Note that the SQLITE_TEXT constant was also used in SQLite version 2 1403 ** for a completely different meaning. Software that links against both 1404 ** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT not 1405 ** SQLITE_TEXT. 1406 */ 1407 #define SQLITE_INTEGER 1 1408 #define SQLITE_FLOAT 2 1409 #define SQLITE_BLOB 4 1410 #define SQLITE_NULL 5 1411 #ifdef SQLITE_TEXT 1412 # undef SQLITE_TEXT 1413 #else 1414 # define SQLITE_TEXT 3 1415 #endif 1416 #define SQLITE3_TEXT 3 1417 1418 /* 1419 ** CAPI3REF: Results Values From A Query 1420 ** 1421 ** These routines return information about the information 1422 ** in a single column of the current result row of a query. In every 1423 ** case the first argument is a pointer to the 1424 ** [sqlite3_stmt | SQL statement] that is being 1425 ** evaluate (the [sqlite_stmt*] that was returned from 1426 ** [sqlite3_prepare_v2()] or one of its variants) and 1427 ** the second argument is the index of the column for which information 1428 ** should be returned. The left-most column has an index of 0. 1429 ** 1430 ** If the SQL statement is not currently point to a valid row, or if the 1431 ** the column index is out of range, the result is undefined. 1432 ** 1433 ** The sqlite3_column_type() routine returns 1434 ** [SQLITE_INTEGER | datatype code] for the initial data type 1435 ** of the result column. The returned value is one of [SQLITE_INTEGER], 1436 ** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL]. The value 1437 ** returned by sqlite3_column_type() is only meaningful if no type 1438 ** conversions have occurred as described below. After a type conversion, 1439 ** the value returned by sqlite3_column_type() is undefined. Future 1440 ** versions of SQLite may change the behavior of sqlite3_column_type() 1441 ** following a type conversion. 1442 ** 1443 *** The sqlite3_column_nm 1444 ** 1445 ** If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes() 1446 ** routine returns the number of bytes in that BLOB or string. 1447 ** If the result is a UTF-16 string, then sqlite3_column_bytes() converts 1448 ** the string to UTF-8 and then returns the number of bytes. 1449 ** If the result is a numeric value then sqlite3_column_bytes() uses 1450 ** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns 1451 ** the number of bytes in that string. 1452 ** The value returned does not include the zero terminator at the end 1453 ** of the string. For clarity: the value returned is the number of 1454 ** bytes in the string, not the number of characters. 1455 ** 1456 ** The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes() 1457 ** but leaves the result in UTF-16 instead of UTF-8. 1458 ** The zero terminator is not included in this count. 1459 ** 1460 ** These routines attempt to convert the value where appropriate. For 1461 ** example, if the internal representation is FLOAT and a text result 1462 ** is requested, [sqlite3_snprintf()] is used internally to do the conversion 1463 ** automatically. The following table details the conversions that 1464 ** are applied: 1465 ** 1466 ** <blockquote> 1467 ** <table border="1"> 1468 ** <tr><th> Internal <th> Requested <th> 1469 ** <tr><th> Type <th> Type <th> Conversion 1470 ** 1471 ** <tr><td> NULL <td> INTEGER <td> Result is 0 1472 ** <tr><td> NULL <td> FLOAT <td> Result is 0.0 1473 ** <tr><td> NULL <td> TEXT <td> Result is NULL pointer 1474 ** <tr><td> NULL <td> BLOB <td> Result is NULL pointer 1475 ** <tr><td> INTEGER <td> FLOAT <td> Convert from integer to float 1476 ** <tr><td> INTEGER <td> TEXT <td> ASCII rendering of the integer 1477 ** <tr><td> INTEGER <td> BLOB <td> Same as for INTEGER->TEXT 1478 ** <tr><td> FLOAT <td> INTEGER <td> Convert from float to integer 1479 ** <tr><td> FLOAT <td> TEXT <td> ASCII rendering of the float 1480 ** <tr><td> FLOAT <td> BLOB <td> Same as FLOAT->TEXT 1481 ** <tr><td> TEXT <td> INTEGER <td> Use atoi() 1482 ** <tr><td> TEXT <td> FLOAT <td> Use atof() 1483 ** <tr><td> TEXT <td> BLOB <td> No change 1484 ** <tr><td> BLOB <td> INTEGER <td> Convert to TEXT then use atoi() 1485 ** <tr><td> BLOB <td> FLOAT <td> Convert to TEXT then use atof() 1486 ** <tr><td> BLOB <td> TEXT <td> Add a zero terminator if needed 1487 ** </table> 1488 ** </blockquote> 1489 ** 1490 ** The table above makes reference to standard C library functions atoi() 1491 ** and atof(). SQLite does not really use these functions. It has its 1492 ** on equavalent internal routines. The atoi() and atof() names are 1493 ** used in the table for brevity and because they are familiar to most 1494 ** C programmers. 1495 ** 1496 ** Note that when type conversions occur, pointers returned by prior 1497 ** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or 1498 ** sqlite3_column_text16() may be invalidated. 1499 ** Type conversions and pointer invalidations might occur 1500 ** in the following cases: 1501 ** 1502 ** <ul> 1503 ** <li><p> The initial content is a BLOB and sqlite3_column_text() 1504 ** or sqlite3_column_text16() is called. A zero-terminator might 1505 ** need to be added to the string.</p></li> 1506 ** 1507 ** <li><p> The initial content is UTF-8 text and sqlite3_column_bytes16() or 1508 ** sqlite3_column_text16() is called. The content must be converted 1509 ** to UTF-16.</p></li> 1510 ** 1511 ** <li><p> The initial content is UTF-16 text and sqlite3_column_bytes() or 1512 ** sqlite3_column_text() is called. The content must be converted 1513 ** to UTF-8.</p></li> 1514 ** </ul> 1515 ** 1516 ** Conversions between UTF-16be and UTF-16le are always done in place and do 1517 ** not invalidate a prior pointer, though of course the content of the buffer 1518 ** that the prior pointer points to will have been modified. Other kinds 1519 ** of conversion are done in place when it is possible, but sometime it is 1520 ** not possible and in those cases prior pointers are invalidated. 1521 ** 1522 ** The safest and easiest to remember policy is to invoke these routines 1523 ** in one of the following ways: 1524 ** 1525 ** <ul> 1526 ** <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li> 1527 ** <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li> 1528 ** <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li> 1529 ** </ul> 1530 ** 1531 ** In other words, you should call sqlite3_column_text(), sqlite3_column_blob(), 1532 ** or sqlite3_column_text16() first to force the result into the desired 1533 ** format, then invoke sqlite3_column_bytes() or sqlite3_column_bytes16() to 1534 ** find the size of the result. Do not mix call to sqlite3_column_text() or 1535 ** sqlite3_column_blob() with calls to sqlite3_column_bytes16(). And do not 1536 ** mix calls to sqlite3_column_text16() with calls to sqlite3_column_bytes(). 1537 */ 1538 const void *sqlite3_column_blob(sqlite3_stmt*, int iCol); 1539 int sqlite3_column_bytes(sqlite3_stmt*, int iCol); 1540 int sqlite3_column_bytes16(sqlite3_stmt*, int iCol); 1541 double sqlite3_column_double(sqlite3_stmt*, int iCol); 1542 int sqlite3_column_int(sqlite3_stmt*, int iCol); 1543 sqlite_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol); 1544 const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol); 1545 const void *sqlite3_column_text16(sqlite3_stmt*, int iCol); 1546 int sqlite3_column_type(sqlite3_stmt*, int iCol); 1547 sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol); 1548 1549 /* 1550 ** CAPI3REF: Destroy A Prepared Statement Object 1551 ** 1552 ** The sqlite3_finalize() function is called to delete a 1553 ** [sqlite3_stmt | compiled SQL statement]. If the statement was 1554 ** executed successfully, or not executed at all, then SQLITE_OK is returned. 1555 ** If execution of the statement failed then an 1556 ** [SQLITE_ERROR | error code] or [SQLITE_IOERR_READ | extended error code] 1557 ** is returned. 1558 ** 1559 ** This routine can be called at any point during the execution of the 1560 ** [sqlite3_stmt | virtual machine]. If the virtual machine has not 1561 ** completed execution when this routine is called, that is like 1562 ** encountering an error or an interrupt. (See [sqlite3_interrupt()].) 1563 ** Incomplete updates may be rolled back and transactions cancelled, 1564 ** depending on the circumstances, and the 1565 ** [SQLITE_ERROR | result code] returned will be [SQLITE_ABORT]. 1566 */ 1567 int sqlite3_finalize(sqlite3_stmt *pStmt); 1568 1569 /* 1570 ** CAPI3REF: Reset A Prepared Statement Object 1571 ** 1572 ** The sqlite3_reset() function is called to reset a 1573 ** [sqlite_stmt | compiled SQL statement] object. 1574 ** back to it's initial state, ready to be re-executed. 1575 ** Any SQL statement variables that had values bound to them using 1576 ** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values. 1577 ** Use [sqlite3_clear_bindings()] to reset the bindings. 1578 */ 1579 int sqlite3_reset(sqlite3_stmt *pStmt); 1580 1581 /* 1582 ** CAPI3REF: Create Or Redefine SQL Functions 1583 ** 1584 ** The following two functions are used to add SQL functions or aggregates 1585 ** or to redefine the behavior of existing SQL functions or aggregates. The 1586 ** difference only between the two is that the second parameter, the 1587 ** name of the (scalar) function or aggregate, is encoded in UTF-8 for 1588 ** sqlite3_create_function() and UTF-16 for sqlite3_create_function16(). 1589 ** 1590 ** The first argument is the [sqlite3 | database handle] that holds the 1591 ** SQL function or aggregate is to be added or redefined. If a single 1592 ** program uses more than one database handle internally, then SQL 1593 ** functions or aggregates must be added individually to each database 1594 ** handle with which they will be used. 1595 ** 1596 ** The second parameter is the name of the SQL function to be created 1597 ** or redefined. 1598 ** The length of the name is limited to 255 bytes, exclusive of the 1599 ** zero-terminator. Note that the name length limit is in bytes, not 1600 ** characters. Any attempt to create a function with a longer name 1601 ** will result in an SQLITE_ERROR error. 1602 ** 1603 ** The third parameter is the number of arguments that the SQL function or 1604 ** aggregate takes. If this parameter is negative, then the SQL function or 1605 ** aggregate may take any number of arguments. 1606 ** 1607 ** The fourth parameter, eTextRep, specifies what 1608 ** [SQLITE_UTF8 | text encoding] this SQL function prefers for 1609 ** its parameters. Any SQL function implementation should be able to work 1610 ** work with UTF-8, UTF-16le, or UTF-16be. But some implementations may be 1611 ** more efficient with one encoding than another. It is allowed to 1612 ** invoke sqlite_create_function() or sqlite3_create_function16() multiple 1613 ** times with the same function but with different values of eTextRep. 1614 ** When multiple implementations of the same function are available, SQLite 1615 ** will pick the one that involves the least amount of data conversion. 1616 ** If there is only a single implementation which does not care what 1617 ** text encoding is used, then the fourth argument should be 1618 ** [SQLITE_ANY]. 1619 ** 1620 ** The fifth parameter is an arbitrary pointer. The implementation 1621 ** of the function can gain access to this pointer using 1622 ** [sqlite_user_data()]. 1623 ** 1624 ** The seventh, eighth and ninth parameters, xFunc, xStep and xFinal, are 1625 ** pointers to C-language functions that implement the SQL 1626 ** function or aggregate. A scalar SQL function requires an implementation of 1627 ** the xFunc callback only, NULL pointers should be passed as the xStep 1628 ** and xFinal parameters. An aggregate SQL function requires an implementation 1629 ** of xStep and xFinal and NULL should be passed for xFunc. To delete an 1630 ** existing SQL function or aggregate, pass NULL for all three function 1631 ** callback. 1632 ** 1633 ** It is permitted to register multiple implementations of the same 1634 ** functions with the same name but with either differing numbers of 1635 ** arguments or differing perferred text encodings. SQLite will use 1636 ** the implementation most closely matches the way in which the 1637 ** SQL function is used. 1638 */ 1639 int sqlite3_create_function( 1640 sqlite3 *, 1641 const char *zFunctionName, 1642 int nArg, 1643 int eTextRep, 1644 void*, 1645 void (*xFunc)(sqlite3_context*,int,sqlite3_value**), 1646 void (*xStep)(sqlite3_context*,int,sqlite3_value**), 1647 void (*xFinal)(sqlite3_context*) 1648 ); 1649 int sqlite3_create_function16( 1650 sqlite3*, 1651 const void *zFunctionName, 1652 int nArg, 1653 int eTextRep, 1654 void*, 1655 void (*xFunc)(sqlite3_context*,int,sqlite3_value**), 1656 void (*xStep)(sqlite3_context*,int,sqlite3_value**), 1657 void (*xFinal)(sqlite3_context*) 1658 ); 1659 1660 /* 1661 ** CAPI3REF: Text Encodings 1662 ** 1663 ** These constant define integer codes that represent the various 1664 ** text encodings supported by SQLite. 1665 */ 1666 #define SQLITE_UTF8 1 1667 #define SQLITE_UTF16LE 2 1668 #define SQLITE_UTF16BE 3 1669 #define SQLITE_UTF16 4 /* Use native byte order */ 1670 #define SQLITE_ANY 5 /* sqlite3_create_function only */ 1671 #define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */ 1672 1673 /* 1674 ** CAPI3REF: Obsolete Functions 1675 ** 1676 ** These functions are all now obsolete. In order to maintain 1677 ** backwards compatibility with older code, we continue to support 1678 ** these functions. However, new development projects should avoid 1679 ** the use of these functions. To help encourage people to avoid 1680 ** using these functions, we are not going to tell you want they do. 1681 */ 1682 int sqlite3_aggregate_count(sqlite3_context*); 1683 int sqlite3_expired(sqlite3_stmt*); 1684 int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*); 1685 int sqlite3_global_recover(void); 1686 1687 1688 /* 1689 ** CAPI3REF: Obtaining SQL Function Parameter Values 1690 ** 1691 ** The C-language implementation of SQL functions and aggregates uses 1692 ** this set of interface routines to access the parameter values on 1693 ** the function or aggregate. 1694 ** 1695 ** The xFunc (for scalar functions) or xStep (for aggregates) parameters 1696 ** to [sqlite3_create_function()] and [sqlite3_create_function16()] 1697 ** define callbacks that implement the SQL functions and aggregates. 1698 ** The 4th parameter to these callbacks is an array of pointers to 1699 ** [sqlite3_value] objects. There is one [sqlite3_value] object for 1700 ** each parameter to the SQL function. These routines are used to 1701 ** extract values from the [sqlite3_value] objects. 1702 ** 1703 ** These routines work just like the corresponding 1704 ** [sqlite3_column_blob | sqlite3_column_* routines] except that 1705 ** these routines take a single [sqlite3_value*] pointer instead 1706 ** of an [sqlite3_stmt*] pointer and an integer column number. 1707 ** 1708 ** The sqlite3_value_text16() interface extracts a UTF16 string 1709 ** in the native byte-order of the host machine. The 1710 ** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces 1711 ** extract UTF16 strings as big-endian and little-endian respectively. 1712 ** 1713 ** The sqlite3_value_numeric_type() interface attempts to apply 1714 ** numeric affinity to the value. This means that an attempt is 1715 ** made to convert the value to an integer or floating point. If 1716 ** such a conversion is possible without loss of information (in order 1717 ** words if the value is original a string that looks like a number) 1718 ** then it is done. Otherwise no conversion occurs. The 1719 ** [SQLITE_INTEGER | datatype] after conversion is returned. 1720 ** 1721 ** Please pay particular attention to the fact that the pointer that 1722 ** is returned from [sqlite3_value_blob()], [sqlite3_value_text()], or 1723 ** [sqlite3_value_text16()] can be invalidated by a subsequent call to 1724 ** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite_value_text()], 1725 ** or [sqlite3_value_text16()]. 1726 */ 1727 const void *sqlite3_value_blob(sqlite3_value*); 1728 int sqlite3_value_bytes(sqlite3_value*); 1729 int sqlite3_value_bytes16(sqlite3_value*); 1730 double sqlite3_value_double(sqlite3_value*); 1731 int sqlite3_value_int(sqlite3_value*); 1732 sqlite_int64 sqlite3_value_int64(sqlite3_value*); 1733 const unsigned char *sqlite3_value_text(sqlite3_value*); 1734 const void *sqlite3_value_text16(sqlite3_value*); 1735 const void *sqlite3_value_text16le(sqlite3_value*); 1736 const void *sqlite3_value_text16be(sqlite3_value*); 1737 int sqlite3_value_type(sqlite3_value*); 1738 int sqlite3_value_numeric_type(sqlite3_value*); 1739 1740 /* 1741 ** CAPI3REF: Obtain Aggregate Function Context 1742 ** 1743 ** The implementation of aggregate SQL functions use this routine to allocate 1744 ** a structure for storing their state. The first time this routine 1745 ** is called for a particular aggregate, a new structure of size nBytes 1746 ** is allocated, zeroed, and returned. On subsequent calls (for the 1747 ** same aggregate instance) the same buffer is returned. The implementation 1748 ** of the aggregate can use the returned buffer to accumulate data. 1749 ** 1750 ** The buffer allocated is freed automatically by SQLite whan the aggregate 1751 ** query concludes. 1752 ** 1753 ** The first parameter should be a copy of the 1754 ** [sqlite3_context | SQL function context] that is the first 1755 ** parameter to the callback routine that implements the aggregate 1756 ** function. 1757 */ 1758 void *sqlite3_aggregate_context(sqlite3_context*, int nBytes); 1759 1760 /* 1761 ** CAPI3REF: User Data For Functions 1762 ** 1763 ** The pUserData parameter to the [sqlite3_create_function()] 1764 ** and [sqlite3_create_function16()] routines 1765 ** used to register user functions is available to 1766 ** the implementation of the function using this call. 1767 */ 1768 void *sqlite3_user_data(sqlite3_context*); 1769 1770 /* 1771 ** CAPI3REF: Function Auxiliary Data 1772 ** 1773 ** The following two functions may be used by scalar SQL functions to 1774 ** associate meta-data with argument values. If the same value is passed to 1775 ** multiple invocations of the same SQL function during query execution, under 1776 ** some circumstances the associated meta-data may be preserved. This may 1777 ** be used, for example, to add a regular-expression matching scalar 1778 ** function. The compiled version of the regular expression is stored as 1779 ** meta-data associated with the SQL value passed as the regular expression 1780 ** pattern. The compiled regular expression can be reused on multiple 1781 ** invocations of the same function so that the original pattern string 1782 ** does not need to be recompiled on each invocation. 1783 ** 1784 ** The sqlite3_get_auxdata() interface returns a pointer to the meta-data 1785 ** associated with the Nth argument value to the current SQL function 1786 ** call, where N is the second parameter. If no meta-data has been set for 1787 ** that value, then a NULL pointer is returned. 1788 ** 1789 ** The sqlite3_set_auxdata() is used to associate meta-data with an SQL 1790 ** function argument. The third parameter is a pointer to the meta-data 1791 ** to be associated with the Nth user function argument value. The fourth 1792 ** parameter specifies a destructor that will be called on the meta- 1793 ** data pointer to release it when it is no longer required. If the 1794 ** destructor is NULL, it is not invoked. 1795 ** 1796 ** In practice, meta-data is preserved between function calls for 1797 ** expressions that are constant at compile time. This includes literal 1798 ** values and SQL variables. 1799 */ 1800 void *sqlite3_get_auxdata(sqlite3_context*, int); 1801 void sqlite3_set_auxdata(sqlite3_context*, int, void*, void (*)(void*)); 1802 1803 1804 /* 1805 ** CAPI3REF: Constants Defining Special Destructor Behavior 1806 ** 1807 ** These are special value for the destructor that is passed in as the 1808 ** final argument to routines like [sqlite3_result_blob()]. If the destructor 1809 ** argument is SQLITE_STATIC, it means that the content pointer is constant 1810 ** and will never change. It does not need to be destroyed. The 1811 ** SQLITE_TRANSIENT value means that the content will likely change in 1812 ** the near future and that SQLite should make its own private copy of 1813 ** the content before returning. 1814 ** 1815 ** The typedef is necessary to work around problems in certain 1816 ** C++ compilers. See ticket #2191. 1817 */ 1818 typedef void (*sqlite3_destructor_type)(void*); 1819 #define SQLITE_STATIC ((sqlite3_destructor_type)0) 1820 #define SQLITE_TRANSIENT ((sqlite3_destructor_type)-1) 1821 1822 /* 1823 ** CAPI3REF: Setting The Result Of An SQL Function 1824 ** 1825 ** These routines are used by the xFunc or xFinal callbacks that 1826 ** implement SQL functions and aggregates. See 1827 ** [sqlite3_create_function()] and [sqlite3_create_function16()] 1828 ** for additional information. 1829 ** 1830 ** These functions work very much like the 1831 ** [sqlite3_bind_blob | sqlite3_bind_*] family of functions used 1832 ** to bind values to host parameters in prepared statements. 1833 ** Refer to the 1834 ** [sqlite3_bind_blob | sqlite3_bind_* documentation] for 1835 ** additional information. 1836 ** 1837 ** The sqlite3_result_error() and sqlite3_result_error16() functions 1838 ** cause the implemented SQL function to throw an exception. The 1839 ** parameter to sqlite3_result_error() or sqlite3_result_error16() 1840 ** is the text of an error message. 1841 ** 1842 ** The sqlite3_result_toobig() cause the function implementation 1843 ** to throw and error indicating that a string or BLOB is to long 1844 ** to represent. 1845 */ 1846 void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*)); 1847 void sqlite3_result_double(sqlite3_context*, double); 1848 void sqlite3_result_error(sqlite3_context*, const char*, int); 1849 void sqlite3_result_error16(sqlite3_context*, const void*, int); 1850 void sqlite3_result_error_toobig(sqlite3_context*); 1851 void sqlite3_result_int(sqlite3_context*, int); 1852 void sqlite3_result_int64(sqlite3_context*, sqlite_int64); 1853 void sqlite3_result_null(sqlite3_context*); 1854 void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*)); 1855 void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*)); 1856 void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*)); 1857 void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*)); 1858 void sqlite3_result_value(sqlite3_context*, sqlite3_value*); 1859 void sqlite3_result_zeroblob(sqlite3_context*, int n); 1860 1861 /* 1862 ** CAPI3REF: Define New Collating Sequences 1863 ** 1864 ** These functions are used to add new collation sequences to the 1865 ** [sqlite3*] handle specified as the first argument. 1866 ** 1867 ** The name of the new collation sequence is specified as a UTF-8 string 1868 ** for sqlite3_create_collation() and sqlite3_create_collation_v2() 1869 ** and a UTF-16 string for sqlite3_create_collation16(). In all cases 1870 ** the name is passed as the second function argument. 1871 ** 1872 ** The third argument must be one of the constants [SQLITE_UTF8], 1873 ** [SQLITE_UTF16LE] or [SQLITE_UTF16BE], indicating that the user-supplied 1874 ** routine expects to be passed pointers to strings encoded using UTF-8, 1875 ** UTF-16 little-endian or UTF-16 big-endian respectively. 1876 ** 1877 ** A pointer to the user supplied routine must be passed as the fifth 1878 ** argument. If it is NULL, this is the same as deleting the collation 1879 ** sequence (so that SQLite cannot call it anymore). Each time the user 1880 ** supplied function is invoked, it is passed a copy of the void* passed as 1881 ** the fourth argument to sqlite3_create_collation() or 1882 ** sqlite3_create_collation16() as its first parameter. 1883 ** 1884 ** The remaining arguments to the user-supplied routine are two strings, 1885 ** each represented by a [length, data] pair and encoded in the encoding 1886 ** that was passed as the third argument when the collation sequence was 1887 ** registered. The user routine should return negative, zero or positive if 1888 ** the first string is less than, equal to, or greater than the second 1889 ** string. i.e. (STRING1 - STRING2). 1890 ** 1891 ** The sqlite3_create_collation_v2() works like sqlite3_create_collation() 1892 ** excapt that it takes an extra argument which is a destructor for 1893 ** the collation. The destructor is called when the collation is 1894 ** destroyed and is passed a copy of the fourth parameter void* pointer 1895 ** of the sqlite3_create_collation_v2(). Collations are destroyed when 1896 ** they are overridden by later calls to the collation creation functions 1897 ** or when the [sqlite3*] database handle is closed using [sqlite3_close()]. 1898 ** 1899 ** The sqlite3_create_collation_v2() interface is experimental and 1900 ** subject to change in future releases. The other collation creation 1901 ** functions are stable. 1902 */ 1903 int sqlite3_create_collation( 1904 sqlite3*, 1905 const char *zName, 1906 int eTextRep, 1907 void*, 1908 int(*xCompare)(void*,int,const void*,int,const void*) 1909 ); 1910 int sqlite3_create_collation_v2( 1911 sqlite3*, 1912 const char *zName, 1913 int eTextRep, 1914 void*, 1915 int(*xCompare)(void*,int,const void*,int,const void*), 1916 void(*xDestroy)(void*) 1917 ); 1918 int sqlite3_create_collation16( 1919 sqlite3*, 1920 const char *zName, 1921 int eTextRep, 1922 void*, 1923 int(*xCompare)(void*,int,const void*,int,const void*) 1924 ); 1925 1926 /* 1927 ** CAPI3REF: Collation Needed Callbacks 1928 ** 1929 ** To avoid having to register all collation sequences before a database 1930 ** can be used, a single callback function may be registered with the 1931 ** database handle to be called whenever an undefined collation sequence is 1932 ** required. 1933 ** 1934 ** If the function is registered using the sqlite3_collation_needed() API, 1935 ** then it is passed the names of undefined collation sequences as strings 1936 ** encoded in UTF-8. If sqlite3_collation_needed16() is used, the names 1937 ** are passed as UTF-16 in machine native byte order. A call to either 1938 ** function replaces any existing callback. 1939 ** 1940 ** When the callback is invoked, the first argument passed is a copy 1941 ** of the second argument to sqlite3_collation_needed() or 1942 ** sqlite3_collation_needed16(). The second argument is the database 1943 ** handle. The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE], or 1944 ** [SQLITE_UTF16LE], indicating the most desirable form of the collation 1945 ** sequence function required. The fourth parameter is the name of the 1946 ** required collation sequence. 1947 ** 1948 ** The callback function should register the desired collation using 1949 ** [sqlite3_create_collation()], [sqlite3_create_collation16()], or 1950 ** [sqlite3_create_collation_v2()]. 1951 */ 1952 int sqlite3_collation_needed( 1953 sqlite3*, 1954 void*, 1955 void(*)(void*,sqlite3*,int eTextRep,const char*) 1956 ); 1957 int sqlite3_collation_needed16( 1958 sqlite3*, 1959 void*, 1960 void(*)(void*,sqlite3*,int eTextRep,const void*) 1961 ); 1962 1963 /* 1964 ** Specify the key for an encrypted database. This routine should be 1965 ** called right after sqlite3_open(). 1966 ** 1967 ** The code to implement this API is not available in the public release 1968 ** of SQLite. 1969 */ 1970 int sqlite3_key( 1971 sqlite3 *db, /* Database to be rekeyed */ 1972 const void *pKey, int nKey /* The key */ 1973 ); 1974 1975 /* 1976 ** Change the key on an open database. If the current database is not 1977 ** encrypted, this routine will encrypt it. If pNew==0 or nNew==0, the 1978 ** database is decrypted. 1979 ** 1980 ** The code to implement this API is not available in the public release 1981 ** of SQLite. 1982 */ 1983 int sqlite3_rekey( 1984 sqlite3 *db, /* Database to be rekeyed */ 1985 const void *pKey, int nKey /* The new key */ 1986 ); 1987 1988 /* 1989 ** CAPI3REF: Suspend Execution For A Short Time 1990 ** 1991 ** This function causes the current thread to suspect execution 1992 ** a number of milliseconds specified in its parameter. 1993 ** 1994 ** If the operating system does not support sleep requests with 1995 ** millisecond time resolution, then the time will be rounded up to 1996 ** the nearest second. The number of milliseconds of sleep actually 1997 ** requested from the operating system is returned. 1998 */ 1999 int sqlite3_sleep(int); 2000 2001 /* 2002 ** CAPI3REF: Name Of The Folder Holding Temporary Files 2003 ** 2004 ** If this global variable is made to point to a string which is 2005 ** the name of a folder (a.ka. directory), then all temporary files 2006 ** created by SQLite will be placed in that directory. If this variable 2007 ** is NULL pointer, then SQLite does a search for an appropriate temporary 2008 ** file directory. 2009 ** 2010 ** Once [sqlite3_open()] has been called, changing this variable will 2011 ** invalidate the current temporary database, if any. Generally speaking, 2012 ** it is not safe to invoke this routine after [sqlite3_open()] has 2013 ** been called. 2014 */ 2015 extern char *sqlite3_temp_directory; 2016 2017 /* 2018 ** CAPI3REF: Test To See If The Databse Is In Auto-Commit Mode 2019 ** 2020 ** Test to see whether or not the database connection is in autocommit 2021 ** mode. Return TRUE if it is and FALSE if not. Autocommit mode is on 2022 ** by default. Autocommit is disabled by a BEGIN statement and reenabled 2023 ** by the next COMMIT or ROLLBACK. 2024 */ 2025 int sqlite3_get_autocommit(sqlite3*); 2026 2027 /* 2028 ** CAPI3REF: Find The Database Handle Associated With A Prepared Statement 2029 ** 2030 ** Return the [sqlite3*] database handle to which a 2031 ** [sqlite3_stmt | prepared statement] belongs. 2032 ** This is the same database handle that was 2033 ** the first argument to the [sqlite3_prepare_v2()] or its variants 2034 ** that was used to create the statement in the first place. 2035 */ 2036 sqlite3 *sqlite3_db_handle(sqlite3_stmt*); 2037 2038 2039 /* 2040 ** CAPI3REF: Commit And Rollback Notification Callbacks 2041 ** 2042 ** These routines 2043 ** register callback functions to be invoked whenever a transaction 2044 ** is committed or rolled back. The pArg argument is passed through 2045 ** to the callback. If the callback on a commit hook function 2046 ** returns non-zero, then the commit is converted into a rollback. 2047 ** 2048 ** If another function was previously registered, its pArg value is returned. 2049 ** Otherwise NULL is returned. 2050 ** 2051 ** Registering a NULL function disables the callback. 2052 ** 2053 ** For the purposes of this API, a transaction is said to have been 2054 ** rolled back if an explicit "ROLLBACK" statement is executed, or 2055 ** an error or constraint causes an implicit rollback to occur. The 2056 ** callback is not invoked if a transaction is automatically rolled 2057 ** back because the database connection is closed. 2058 ** 2059 ** These are experimental interfaces and are subject to change. 2060 */ 2061 void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*); 2062 void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*); 2063 2064 /* 2065 ** CAPI3REF: Data Change Notification Callbacks 2066 ** 2067 ** Register a callback function with the database connection identified by the 2068 ** first argument to be invoked whenever a row is updated, inserted or deleted. 2069 ** Any callback set by a previous call to this function for the same 2070 ** database connection is overridden. 2071 ** 2072 ** The second argument is a pointer to the function to invoke when a 2073 ** row is updated, inserted or deleted. The first argument to the callback is 2074 ** a copy of the third argument to sqlite3_update_hook(). The second callback 2075 ** argument is one of SQLITE_INSERT, SQLITE_DELETE or SQLITE_UPDATE, depending 2076 ** on the operation that caused the callback to be invoked. The third and 2077 ** fourth arguments to the callback contain pointers to the database and 2078 ** table name containing the affected row. The final callback parameter is 2079 ** the rowid of the row. In the case of an update, this is the rowid after 2080 ** the update takes place. 2081 ** 2082 ** The update hook is not invoked when internal system tables are 2083 ** modified (i.e. sqlite_master and sqlite_sequence). 2084 ** 2085 ** If another function was previously registered, its pArg value is returned. 2086 ** Otherwise NULL is returned. 2087 */ 2088 void *sqlite3_update_hook( 2089 sqlite3*, 2090 void(*)(void *,int ,char const *,char const *,sqlite_int64), 2091 void* 2092 ); 2093 2094 /* 2095 ** CAPI3REF: Enable Or Disable Shared Pager Cache 2096 ** 2097 ** This routine enables or disables the sharing of the database cache 2098 ** and schema data structures between connections to the same database. 2099 ** Sharing is enabled if the argument is true and disabled if the argument 2100 ** is false. 2101 ** 2102 ** Cache sharing is enabled and disabled on a thread-by-thread basis. 2103 ** Each call to this routine enables or disables cache sharing only for 2104 ** connections created in the same thread in which this routine is called. 2105 ** There is no mechanism for sharing cache between database connections 2106 ** running in different threads. 2107 ** 2108 ** Sharing must be disabled prior to shutting down a thread or else 2109 ** the thread will leak memory. Call this routine with an argument of 2110 ** 0 to turn off sharing. Or use the sqlite3_thread_cleanup() API. 2111 ** 2112 ** This routine must not be called when any database connections 2113 ** are active in the current thread. Enabling or disabling shared 2114 ** cache while there are active database connections will result 2115 ** in memory corruption. 2116 ** 2117 ** When the shared cache is enabled, the 2118 ** following routines must always be called from the same thread: 2119 ** [sqlite3_open()], [sqlite3_prepare_v2()], [sqlite3_step()], 2120 ** [sqlite3_reset()], [sqlite3_finalize()], and [sqlite3_close()]. 2121 ** This is due to the fact that the shared cache makes use of 2122 ** thread-specific storage so that it will be available for sharing 2123 ** with other connections. 2124 ** 2125 ** Virtual tables cannot be used with a shared cache. When shared 2126 ** cache is enabled, the sqlite3_create_module() API used to register 2127 ** virtual tables will always return an error. 2128 ** 2129 ** This routine returns [SQLITE_OK] if shared cache was 2130 ** enabled or disabled successfully. An [SQLITE_ERROR | error code] 2131 ** is returned otherwise. 2132 ** 2133 ** Shared cache is disabled by default for backward compatibility. 2134 */ 2135 int sqlite3_enable_shared_cache(int); 2136 2137 /* 2138 ** CAPI3REF: Attempt To Free Heap Memory 2139 ** 2140 ** Attempt to free N bytes of heap memory by deallocating non-essential 2141 ** memory allocations held by the database library (example: memory 2142 ** used to cache database pages to improve performance). 2143 ** 2144 ** This function is not a part of standard builds. It is only created 2145 ** if SQLite is compiled with the SQLITE_ENABLE_MEMORY_MANAGEMENT macro. 2146 */ 2147 int sqlite3_release_memory(int); 2148 2149 /* 2150 ** CAPI3REF: Impose A Limit On Heap Size 2151 ** 2152 ** Place a "soft" limit on the amount of heap memory that may be allocated by 2153 ** SQLite within the current thread. If an internal allocation is requested 2154 ** that would exceed the specified limit, [sqlite3_release_memory()] is invoked 2155 ** one or more times to free up some space before the allocation is made. 2156 ** 2157 ** The limit is called "soft", because if [sqlite3_release_memory()] cannot free 2158 ** sufficient memory to prevent the limit from being exceeded, the memory is 2159 ** allocated anyway and the current operation proceeds. 2160 ** 2161 ** Prior to shutting down a thread sqlite3_soft_heap_limit() must be set to 2162 ** zero (the default) or else the thread will leak memory. Alternatively, use 2163 ** the [sqlite3_thread_cleanup()] API. 2164 ** 2165 ** A negative or zero value for N means that there is no soft heap limit and 2166 ** [sqlite3_release_memory()] will only be called when memory is exhaused. 2167 ** The default value for the soft heap limit is zero. 2168 ** 2169 ** SQLite makes a best effort to honor the soft heap limit. But if it 2170 ** is unable to reduce memory usage below the soft limit, execution will 2171 ** continue without error or notification. This is why the limit is 2172 ** called a "soft" limit. It is advisory only. 2173 ** 2174 ** This function is only available if the library was compiled with the 2175 ** SQLITE_ENABLE_MEMORY_MANAGEMENT option set. 2176 ** memory-management has been enabled. 2177 */ 2178 void sqlite3_soft_heap_limit(int); 2179 2180 /* 2181 ** CAPI3REF: Clean Up Thread Local Storage 2182 ** 2183 ** This routine makes sure that all thread-local storage has been 2184 ** deallocated for the current thread. 2185 ** 2186 ** This routine is not technically necessary. All thread-local storage 2187 ** will be automatically deallocated once memory-management and 2188 ** shared-cache are disabled and the soft heap limit has been set 2189 ** to zero. This routine is provided as a convenience for users who 2190 ** want to make absolutely sure they have not forgotten something 2191 ** prior to killing off a thread. 2192 */ 2193 void sqlite3_thread_cleanup(void); 2194 2195 /* 2196 ** CAPI3REF: Extract Metadata About A Column Of A Table 2197 ** 2198 ** This routine 2199 ** returns meta-data about a specific column of a specific database 2200 ** table accessible using the connection handle passed as the first function 2201 ** argument. 2202 ** 2203 ** The column is identified by the second, third and fourth parameters to 2204 ** this function. The second parameter is either the name of the database 2205 ** (i.e. "main", "temp" or an attached database) containing the specified 2206 ** table or NULL. If it is NULL, then all attached databases are searched 2207 ** for the table using the same algorithm as the database engine uses to 2208 ** resolve unqualified table references. 2209 ** 2210 ** The third and fourth parameters to this function are the table and column 2211 ** name of the desired column, respectively. Neither of these parameters 2212 ** may be NULL. 2213 ** 2214 ** Meta information is returned by writing to the memory locations passed as 2215 ** the 5th and subsequent parameters to this function. Any of these 2216 ** arguments may be NULL, in which case the corresponding element of meta 2217 ** information is ommitted. 2218 ** 2219 ** <pre> 2220 ** Parameter Output Type Description 2221 ** ----------------------------------- 2222 ** 2223 ** 5th const char* Data type 2224 ** 6th const char* Name of the default collation sequence 2225 ** 7th int True if the column has a NOT NULL constraint 2226 ** 8th int True if the column is part of the PRIMARY KEY 2227 ** 9th int True if the column is AUTOINCREMENT 2228 ** </pre> 2229 ** 2230 ** 2231 ** The memory pointed to by the character pointers returned for the 2232 ** declaration type and collation sequence is valid only until the next 2233 ** call to any sqlite API function. 2234 ** 2235 ** If the specified table is actually a view, then an error is returned. 2236 ** 2237 ** If the specified column is "rowid", "oid" or "_rowid_" and an 2238 ** INTEGER PRIMARY KEY column has been explicitly declared, then the output 2239 ** parameters are set for the explicitly declared column. If there is no 2240 ** explicitly declared IPK column, then the output parameters are set as 2241 ** follows: 2242 ** 2243 ** <pre> 2244 ** data type: "INTEGER" 2245 ** collation sequence: "BINARY" 2246 ** not null: 0 2247 ** primary key: 1 2248 ** auto increment: 0 2249 ** </pre> 2250 ** 2251 ** This function may load one or more schemas from database files. If an 2252 ** error occurs during this process, or if the requested table or column 2253 ** cannot be found, an SQLITE error code is returned and an error message 2254 ** left in the database handle (to be retrieved using sqlite3_errmsg()). 2255 ** 2256 ** This API is only available if the library was compiled with the 2257 ** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined. 2258 */ 2259 int sqlite3_table_column_metadata( 2260 sqlite3 *db, /* Connection handle */ 2261 const char *zDbName, /* Database name or NULL */ 2262 const char *zTableName, /* Table name */ 2263 const char *zColumnName, /* Column name */ 2264 char const **pzDataType, /* OUTPUT: Declared data type */ 2265 char const **pzCollSeq, /* OUTPUT: Collation sequence name */ 2266 int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */ 2267 int *pPrimaryKey, /* OUTPUT: True if column part of PK */ 2268 int *pAutoinc /* OUTPUT: True if colums is auto-increment */ 2269 ); 2270 2271 /* 2272 ** CAPI3REF: Load An Extension 2273 ** 2274 ** Attempt to load an SQLite extension library contained in the file 2275 ** zFile. The entry point is zProc. zProc may be 0 in which case the 2276 ** name of the entry point defaults to "sqlite3_extension_init". 2277 ** 2278 ** Return [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong. 2279 ** 2280 ** If an error occurs and pzErrMsg is not 0, then fill *pzErrMsg with 2281 ** error message text. The calling function should free this memory 2282 ** by calling [sqlite3_free()]. 2283 ** 2284 ** Extension loading must be enabled using [sqlite3_enable_load_extension()] 2285 ** prior to calling this API or an error will be returned. 2286 */ 2287 int sqlite3_load_extension( 2288 sqlite3 *db, /* Load the extension into this database connection */ 2289 const char *zFile, /* Name of the shared library containing extension */ 2290 const char *zProc, /* Entry point. Derived from zFile if 0 */ 2291 char **pzErrMsg /* Put error message here if not 0 */ 2292 ); 2293 2294 /* 2295 ** CAPI3REF: Enable Or Disable Extension Loading 2296 ** 2297 ** So as not to open security holes in older applications that are 2298 ** unprepared to deal with extension loading, and as a means of disabling 2299 ** extension loading while evaluating user-entered SQL, the following 2300 ** API is provided to turn the [sqlite3_load_extension()] mechanism on and 2301 ** off. It is off by default. See ticket #1863. 2302 ** 2303 ** Call this routine with onoff==1 to turn extension loading on 2304 ** and call it with onoff==0 to turn it back off again. 2305 */ 2306 int sqlite3_enable_load_extension(sqlite3 *db, int onoff); 2307 2308 /* 2309 ** CAPI3REF: Make Arrangements To Automatically Load An Extension 2310 ** 2311 ** Register an extension entry point that is automatically invoked 2312 ** whenever a new database connection is opened using 2313 ** [sqlite3_open()] or [sqlite3_open16()]. 2314 ** 2315 ** This API can be invoked at program startup in order to register 2316 ** one or more statically linked extensions that will be available 2317 ** to all new database connections. 2318 ** 2319 ** Duplicate extensions are detected so calling this routine multiple 2320 ** times with the same extension is harmless. 2321 ** 2322 ** This routine stores a pointer to the extension in an array 2323 ** that is obtained from malloc(). If you run a memory leak 2324 ** checker on your program and it reports a leak because of this 2325 ** array, then invoke [sqlite3_automatic_extension_reset()] prior 2326 ** to shutdown to free the memory. 2327 ** 2328 ** Automatic extensions apply across all threads. 2329 ** 2330 ** This interface is experimental and is subject to change or 2331 ** removal in future releases of SQLite. 2332 */ 2333 int sqlite3_auto_extension(void *xEntryPoint); 2334 2335 2336 /* 2337 ** CAPI3REF: Reset Automatic Extension Loading 2338 ** 2339 ** Disable all previously registered automatic extensions. This 2340 ** routine undoes the effect of all prior [sqlite3_automatic_extension()] 2341 ** calls. 2342 ** 2343 ** This call disabled automatic extensions in all threads. 2344 ** 2345 ** This interface is experimental and is subject to change or 2346 ** removal in future releases of SQLite. 2347 */ 2348 void sqlite3_reset_auto_extension(void); 2349 2350 2351 /* 2352 ****** EXPERIMENTAL - subject to change without notice ************** 2353 ** 2354 ** The interface to the virtual-table mechanism is currently considered 2355 ** to be experimental. The interface might change in incompatible ways. 2356 ** If this is a problem for you, do not use the interface at this time. 2357 ** 2358 ** When the virtual-table mechanism stablizes, we will declare the 2359 ** interface fixed, support it indefinitely, and remove this comment. 2360 */ 2361 2362 /* 2363 ** Structures used by the virtual table interface 2364 */ 2365 typedef struct sqlite3_vtab sqlite3_vtab; 2366 typedef struct sqlite3_index_info sqlite3_index_info; 2367 typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor; 2368 typedef struct sqlite3_module sqlite3_module; 2369 2370 /* 2371 ** A module is a class of virtual tables. Each module is defined 2372 ** by an instance of the following structure. This structure consists 2373 ** mostly of methods for the module. 2374 */ 2375 struct sqlite3_module { 2376 int iVersion; 2377 int (*xCreate)(sqlite3*, void *pAux, 2378 int argc, const char *const*argv, 2379 sqlite3_vtab **ppVTab, char**); 2380 int (*xConnect)(sqlite3*, void *pAux, 2381 int argc, const char *const*argv, 2382 sqlite3_vtab **ppVTab, char**); 2383 int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*); 2384 int (*xDisconnect)(sqlite3_vtab *pVTab); 2385 int (*xDestroy)(sqlite3_vtab *pVTab); 2386 int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor); 2387 int (*xClose)(sqlite3_vtab_cursor*); 2388 int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr, 2389 int argc, sqlite3_value **argv); 2390 int (*xNext)(sqlite3_vtab_cursor*); 2391 int (*xEof)(sqlite3_vtab_cursor*); 2392 int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int); 2393 int (*xRowid)(sqlite3_vtab_cursor*, sqlite_int64 *pRowid); 2394 int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite_int64 *); 2395 int (*xBegin)(sqlite3_vtab *pVTab); 2396 int (*xSync)(sqlite3_vtab *pVTab); 2397 int (*xCommit)(sqlite3_vtab *pVTab); 2398 int (*xRollback)(sqlite3_vtab *pVTab); 2399 int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName, 2400 void (**pxFunc)(sqlite3_context*,int,sqlite3_value**), 2401 void **ppArg); 2402 }; 2403 2404 /* 2405 ** The sqlite3_index_info structure and its substructures is used to 2406 ** pass information into and receive the reply from the xBestIndex 2407 ** method of an sqlite3_module. The fields under **Inputs** are the 2408 ** inputs to xBestIndex and are read-only. xBestIndex inserts its 2409 ** results into the **Outputs** fields. 2410 ** 2411 ** The aConstraint[] array records WHERE clause constraints of the 2412 ** form: 2413 ** 2414 ** column OP expr 2415 ** 2416 ** Where OP is =, <, <=, >, or >=. The particular operator is stored 2417 ** in aConstraint[].op. The index of the column is stored in 2418 ** aConstraint[].iColumn. aConstraint[].usable is TRUE if the 2419 ** expr on the right-hand side can be evaluated (and thus the constraint 2420 ** is usable) and false if it cannot. 2421 ** 2422 ** The optimizer automatically inverts terms of the form "expr OP column" 2423 ** and makes other simplificatinos to the WHERE clause in an attempt to 2424 ** get as many WHERE clause terms into the form shown above as possible. 2425 ** The aConstraint[] array only reports WHERE clause terms in the correct 2426 ** form that refer to the particular virtual table being queried. 2427 ** 2428 ** Information about the ORDER BY clause is stored in aOrderBy[]. 2429 ** Each term of aOrderBy records a column of the ORDER BY clause. 2430 ** 2431 ** The xBestIndex method must fill aConstraintUsage[] with information 2432 ** about what parameters to pass to xFilter. If argvIndex>0 then 2433 ** the right-hand side of the corresponding aConstraint[] is evaluated 2434 ** and becomes the argvIndex-th entry in argv. If aConstraintUsage[].omit 2435 ** is true, then the constraint is assumed to be fully handled by the 2436 ** virtual table and is not checked again by SQLite. 2437 ** 2438 ** The idxNum and idxPtr values are recorded and passed into xFilter. 2439 ** sqlite3_free() is used to free idxPtr if needToFreeIdxPtr is true. 2440 ** 2441 ** The orderByConsumed means that output from xFilter will occur in 2442 ** the correct order to satisfy the ORDER BY clause so that no separate 2443 ** sorting step is required. 2444 ** 2445 ** The estimatedCost value is an estimate of the cost of doing the 2446 ** particular lookup. A full scan of a table with N entries should have 2447 ** a cost of N. A binary search of a table of N entries should have a 2448 ** cost of approximately log(N). 2449 */ 2450 struct sqlite3_index_info { 2451 /* Inputs */ 2452 const int nConstraint; /* Number of entries in aConstraint */ 2453 const struct sqlite3_index_constraint { 2454 int iColumn; /* Column on left-hand side of constraint */ 2455 unsigned char op; /* Constraint operator */ 2456 unsigned char usable; /* True if this constraint is usable */ 2457 int iTermOffset; /* Used internally - xBestIndex should ignore */ 2458 } *const aConstraint; /* Table of WHERE clause constraints */ 2459 const int nOrderBy; /* Number of terms in the ORDER BY clause */ 2460 const struct sqlite3_index_orderby { 2461 int iColumn; /* Column number */ 2462 unsigned char desc; /* True for DESC. False for ASC. */ 2463 } *const aOrderBy; /* The ORDER BY clause */ 2464 2465 /* Outputs */ 2466 struct sqlite3_index_constraint_usage { 2467 int argvIndex; /* if >0, constraint is part of argv to xFilter */ 2468 unsigned char omit; /* Do not code a test for this constraint */ 2469 } *const aConstraintUsage; 2470 int idxNum; /* Number used to identify the index */ 2471 char *idxStr; /* String, possibly obtained from sqlite3_malloc */ 2472 int needToFreeIdxStr; /* Free idxStr using sqlite3_free() if true */ 2473 int orderByConsumed; /* True if output is already ordered */ 2474 double estimatedCost; /* Estimated cost of using this index */ 2475 }; 2476 #define SQLITE_INDEX_CONSTRAINT_EQ 2 2477 #define SQLITE_INDEX_CONSTRAINT_GT 4 2478 #define SQLITE_INDEX_CONSTRAINT_LE 8 2479 #define SQLITE_INDEX_CONSTRAINT_LT 16 2480 #define SQLITE_INDEX_CONSTRAINT_GE 32 2481 #define SQLITE_INDEX_CONSTRAINT_MATCH 64 2482 2483 /* 2484 ** This routine is used to register a new module name with an SQLite 2485 ** connection. Module names must be registered before creating new 2486 ** virtual tables on the module, or before using preexisting virtual 2487 ** tables of the module. 2488 */ 2489 int sqlite3_create_module( 2490 sqlite3 *db, /* SQLite connection to register module with */ 2491 const char *zName, /* Name of the module */ 2492 const sqlite3_module *, /* Methods for the module */ 2493 void * /* Client data for xCreate/xConnect */ 2494 ); 2495 2496 /* 2497 ** Every module implementation uses a subclass of the following structure 2498 ** to describe a particular instance of the module. Each subclass will 2499 ** be taylored to the specific needs of the module implementation. The 2500 ** purpose of this superclass is to define certain fields that are common 2501 ** to all module implementations. 2502 ** 2503 ** Virtual tables methods can set an error message by assigning a 2504 ** string obtained from sqlite3_mprintf() to zErrMsg. The method should 2505 ** take care that any prior string is freed by a call to sqlite3_free() 2506 ** prior to assigning a new string to zErrMsg. After the error message 2507 ** is delivered up to the client application, the string will be automatically 2508 ** freed by sqlite3_free() and the zErrMsg field will be zeroed. Note 2509 ** that sqlite3_mprintf() and sqlite3_free() are used on the zErrMsg field 2510 ** since virtual tables are commonly implemented in loadable extensions which 2511 ** do not have access to sqlite3MPrintf() or sqlite3Free(). 2512 */ 2513 struct sqlite3_vtab { 2514 const sqlite3_module *pModule; /* The module for this virtual table */ 2515 int nRef; /* Used internally */ 2516 char *zErrMsg; /* Error message from sqlite3_mprintf() */ 2517 /* Virtual table implementations will typically add additional fields */ 2518 }; 2519 2520 /* Every module implementation uses a subclass of the following structure 2521 ** to describe cursors that point into the virtual table and are used 2522 ** to loop through the virtual table. Cursors are created using the 2523 ** xOpen method of the module. Each module implementation will define 2524 ** the content of a cursor structure to suit its own needs. 2525 ** 2526 ** This superclass exists in order to define fields of the cursor that 2527 ** are common to all implementations. 2528 */ 2529 struct sqlite3_vtab_cursor { 2530 sqlite3_vtab *pVtab; /* Virtual table of this cursor */ 2531 /* Virtual table implementations will typically add additional fields */ 2532 }; 2533 2534 /* 2535 ** The xCreate and xConnect methods of a module use the following API 2536 ** to declare the format (the names and datatypes of the columns) of 2537 ** the virtual tables they implement. 2538 */ 2539 int sqlite3_declare_vtab(sqlite3*, const char *zCreateTable); 2540 2541 /* 2542 ** Virtual tables can provide alternative implementations of functions 2543 ** using the xFindFunction method. But global versions of those functions 2544 ** must exist in order to be overloaded. 2545 ** 2546 ** This API makes sure a global version of a function with a particular 2547 ** name and number of parameters exists. If no such function exists 2548 ** before this API is called, a new function is created. The implementation 2549 ** of the new function always causes an exception to be thrown. So 2550 ** the new function is not good for anything by itself. Its only 2551 ** purpose is to be a place-holder function that can be overloaded 2552 ** by virtual tables. 2553 ** 2554 ** This API should be considered part of the virtual table interface, 2555 ** which is experimental and subject to change. 2556 */ 2557 int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg); 2558 2559 /* 2560 ** The interface to the virtual-table mechanism defined above (back up 2561 ** to a comment remarkably similar to this one) is currently considered 2562 ** to be experimental. The interface might change in incompatible ways. 2563 ** If this is a problem for you, do not use the interface at this time. 2564 ** 2565 ** When the virtual-table mechanism stablizes, we will declare the 2566 ** interface fixed, support it indefinitely, and remove this comment. 2567 ** 2568 ****** EXPERIMENTAL - subject to change without notice ************** 2569 */ 2570 2571 /* 2572 ** CAPI3REF: A Handle To An Open BLOB 2573 ** 2574 ** An instance of the following opaque structure is used to 2575 ** represent an blob-handle. A blob-handle is created by 2576 ** [sqlite3_blob_open()] and destroyed by [sqlite3_blob_close()]. 2577 ** The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces 2578 ** can be used to read or write small subsections of the blob. 2579 ** The [sqltie3_blob_size()] interface returns the size of the 2580 ** blob in bytes. 2581 */ 2582 typedef struct sqlite3_blob sqlite3_blob; 2583 2584 /* 2585 ** CAPI3REF: Open A BLOB For Incremental I/O 2586 ** 2587 ** Open a handle to the blob located in row iRow,, column zColumn, 2588 ** table zTable in database zDb. i.e. the same blob that would 2589 ** be selected by: 2590 ** 2591 ** <pre> 2592 ** SELECT zColumn FROM zDb.zTable WHERE rowid = iRow; 2593 ** </pre> 2594 ** 2595 ** If the flags parameter is non-zero, the blob is opened for 2596 ** read and write access. If it is zero, the blob is opened for read 2597 ** access. 2598 ** 2599 ** On success, [SQLITE_OK] is returned and the new 2600 ** [sqlite3_blob | blob handle] is written to *ppBlob. 2601 ** Otherwise an error code is returned and 2602 ** any value written to *ppBlob should not be used by the caller. 2603 ** This function sets the database-handle error code and message 2604 ** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()]. 2605 */ 2606 int sqlite3_blob_open( 2607 sqlite3*, 2608 const char *zDb, 2609 const char *zTable, 2610 const char *zColumn, 2611 sqlite_int64 iRow, 2612 int flags, 2613 sqlite3_blob **ppBlob 2614 ); 2615 2616 /* 2617 ** CAPI3REF: Close A BLOB Handle 2618 ** 2619 ** Close an open [sqlite3_blob | blob handle]. 2620 */ 2621 int sqlite3_blob_close(sqlite3_blob *); 2622 2623 /* 2624 ** CAPI3REF: Return The Size Of An Open BLOB 2625 ** 2626 ** Return the size in bytes of the blob accessible via the open 2627 ** [sqlite3_blob | blob-handle] passed as an argument. 2628 */ 2629 int sqlite3_blob_bytes(sqlite3_blob *); 2630 2631 /* 2632 ** CAPI3REF: Read Data From A BLOB Incrementally 2633 ** 2634 ** This function is used to read data from an open 2635 ** [sqlite3_blob | blob-handle] into a caller supplied buffer. 2636 ** n bytes of data are copied into buffer 2637 ** z from the open blob, starting at offset iOffset. 2638 ** 2639 ** On success, SQLITE_OK is returned. Otherwise, an 2640 ** [SQLITE_ERROR | SQLite error code] or an 2641 ** [SQLITE_IOERR_READ | extended error code] is returned. 2642 */ 2643 int sqlite3_blob_read(sqlite3_blob *, void *z, int n, int iOffset); 2644 2645 /* 2646 ** CAPI3REF: Write Data Into A BLOB Incrementally 2647 ** 2648 ** This function is used to write data into an open 2649 ** [sqlite3_blob | blob-handle] from a user supplied buffer. 2650 ** n bytes of data are copied from the buffer 2651 ** pointed to by z into the open blob, starting at offset iOffset. 2652 ** 2653 ** If the [sqlite3_blob | blob-handle] passed as the first argument 2654 ** was not opened for writing (the flags parameter to [sqlite3_blob_open()] 2655 *** was zero), this function returns [SQLITE_READONLY]. 2656 ** 2657 ** This function may only modify the contents of the blob, it is 2658 ** not possible to increase the size of a blob using this API. If 2659 ** offset iOffset is less than n bytes from the end of the blob, 2660 ** [SQLITE_ERROR] is returned and no data is written. 2661 ** 2662 ** On success, SQLITE_OK is returned. Otherwise, an 2663 ** [SQLITE_ERROR | SQLite error code] or an 2664 ** [SQLITE_IOERR_READ | extended error code] is returned. 2665 */ 2666 int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset); 2667 2668 /* 2669 ** Undo the hack that converts floating point types to integer for 2670 ** builds on processors without floating point support. 2671 */ 2672 #ifdef SQLITE_OMIT_FLOATING_POINT 2673 # undef double 2674 #endif 2675 2676 #ifdef __cplusplus 2677 } /* End of the 'extern "C"' block */ 2678 #endif 2679 #endif 2680