diff options
Diffstat (limited to 'ext/pdo_sqlite/sqlite/src/sqlite.h.in')
| -rw-r--r-- | ext/pdo_sqlite/sqlite/src/sqlite.h.in | 243 |
1 files changed, 203 insertions, 40 deletions
diff --git a/ext/pdo_sqlite/sqlite/src/sqlite.h.in b/ext/pdo_sqlite/sqlite/src/sqlite.h.in index a1b4759f8..8478cc27a 100644 --- a/ext/pdo_sqlite/sqlite/src/sqlite.h.in +++ b/ext/pdo_sqlite/sqlite/src/sqlite.h.in @@ -125,7 +125,7 @@ typedef int (*sqlite3_callback)(void*,int,char**, char**); ** value then the query is aborted, all subsequent SQL statements ** are skipped and the sqlite3_exec() function returns the SQLITE_ABORT. ** -** The 4th parameter is an arbitrary pointer that is passed +** The 1st parameter is an arbitrary pointer that is passed ** to the callback function as its first parameter. ** ** The 2nd parameter to the callback function is the number of @@ -182,7 +182,7 @@ int sqlite3_exec( #define SQLITE_NOTFOUND 12 /* NOT USED. Table or record not found */ #define SQLITE_FULL 13 /* Insertion failed because database is full */ #define SQLITE_CANTOPEN 14 /* Unable to open the database file */ -#define SQLITE_PROTOCOL 15 /* Database lock protocol error */ +#define SQLITE_PROTOCOL 15 /* NOT USED. Database lock protocol error */ #define SQLITE_EMPTY 16 /* Database is empty */ #define SQLITE_SCHEMA 17 /* The database schema changed */ #define SQLITE_TOOBIG 18 /* NOT USED. Too much data for one row */ @@ -199,27 +199,70 @@ int sqlite3_exec( /* end-of-error-codes */ /* +** Using the sqlite3_extended_result_codes() API, you can cause +** SQLite to return result codes with additional information in +** their upper bits. The lower 8 bits will be the same as the +** primary result codes above. But the upper bits might contain +** more specific error information. +** +** To extract the primary result code from an extended result code, +** simply mask off the lower 8 bits. +** +** primary = extended & 0xff; +** +** New result error codes may be added from time to time. Software +** that uses the extended result codes should plan accordingly and be +** sure to always handle new unknown codes gracefully. +** +** The SQLITE_OK result code will never be extended. It will always +** be exactly zero. +** +** The extended result codes always have the primary result code +** as a prefix. Primary result codes only contain a single "_" +** character. Extended result codes contain two or more "_" characters. +*/ +#define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8)) +#define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8)) +#define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8)) +#define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4<<8)) +#define SQLITE_IOERR_DIR_FSYNC (SQLITE_IOERR | (5<<8)) +#define SQLITE_IOERR_TRUNCATE (SQLITE_IOERR | (6<<8)) +#define SQLITE_IOERR_FSTAT (SQLITE_IOERR | (7<<8)) +#define SQLITE_IOERR_UNLOCK (SQLITE_IOERR | (8<<8)) +#define SQLITE_IOERR_RDLOCK (SQLITE_IOERR | (9<<8)) +#define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8)) + +/* +** Enable or disable the extended result codes. +*/ +int sqlite3_extended_result_codes(sqlite3*, int onoff); + +/* ** Each entry in an SQLite table has a unique integer key. (The key is ** the value of the INTEGER PRIMARY KEY column if there is such a column, -** otherwise the key is generated at random. The unique key is always +** otherwise the key is generated automatically. The unique key is always ** available as the ROWID, OID, or _ROWID_ column.) The following routine ** returns the integer key of the most recent insert in the database. -** -** This function is similar to the mysql_insert_id() function from MySQL. */ sqlite_int64 sqlite3_last_insert_rowid(sqlite3*); /* ** This function returns the number of database rows that were changed -** (or inserted or deleted) by the most recent called sqlite3_exec(). +** (or inserted or deleted) by the most recent SQL statement. Only +** changes that are directly specified by the INSERT, UPDATE, or +** DELETE statement are counted. Auxiliary changes caused by +** triggers are not counted. Within the body of a trigger, however, +** the sqlite3_changes() API can be called to find the number of +** changes in the most recently completed INSERT, UPDATE, or DELETE +** statement within the body of the trigger. ** ** All changes are counted, even if they were later undone by a ** ROLLBACK or ABORT. Except, changes associated with creating and ** dropping tables are not counted. ** -** If a callback invokes sqlite3_exec() recursively, then the changes -** in the inner, recursive call are counted together with the changes -** in the outer call. +** If a callback invokes sqlite3_exec() or sqlite3_step() recursively, +** then the changes in the inner, recursive call are counted together +** with the changes in the outer call. ** ** SQLite implements the command "DELETE FROM table" without a WHERE clause ** by dropping and recreating the table. (This is much faster than going @@ -254,6 +297,9 @@ int sqlite3_total_changes(sqlite3*); ** called in response to a user action such as pressing "Cancel" ** or Ctrl-C where the user wants a long query operation to halt ** immediately. +** +** It is safe to call this routine from a different thread that the +** thread that is currently running the database operation. */ void sqlite3_interrupt(sqlite3*); @@ -264,9 +310,13 @@ void sqlite3_interrupt(sqlite3*); ** sqlite3_complete16(), a nul-terminated machine byte order UTF-16 string ** is required. ** -** The algorithm is simple. If the last token other than spaces -** and comments is a semicolon, then return true. otherwise return -** false. +** This routine is useful for command-line input to see of the user has +** entered a complete statement of SQL or if the current statement needs +** to be continued on the next line. The algorithm is simple. If the +** last token other than spaces and comments is a semicolon, then return +** true. Actually, the algorithm is a little more complicated than that +** in order to deal with triggers, but the basic idea is the same: the +** statement is not complete unless it ends in a semicolon. */ int sqlite3_complete(const char *sql); int sqlite3_complete16(const void *sql); @@ -277,13 +327,30 @@ int sqlite3_complete16(const void *sql); ** currently locked by another process or thread. If the busy callback ** is NULL, then sqlite3_exec() returns SQLITE_BUSY immediately if ** it finds a locked table. If the busy callback is not NULL, then -** sqlite3_exec() invokes the callback with three arguments. The -** second argument is the name of the locked table and the third -** argument is the number of times the table has been busy. If the +** sqlite3_exec() invokes the callback with two arguments. The +** first argument to the handler is a copy of the void* pointer which +** is the third argument to this routine. The second argument to +** the handler is the number of times that the busy handler has +** been invoked for this locking event. If the ** busy callback returns 0, then sqlite3_exec() immediately returns ** SQLITE_BUSY. If the callback returns non-zero, then sqlite3_exec() ** tries to open the table again and the cycle repeats. ** +** The presence of a busy handler does not guarantee that +** it will be invoked when there is lock contention. +** If SQLite determines that invoking the busy handler could result in +** a deadlock, it will return SQLITE_BUSY instead. +** Consider a scenario where one process is holding a read lock that +** it is trying to promote to a reserved lock and +** a second process is holding a reserved lock that it is trying +** to promote to an exclusive lock. The first process cannot proceed +** because it is blocked by the second and the second process cannot +** proceed because it is blocked by the first. If both processes +** invoke the busy handlers, neither will make any progress. Therefore, +** SQLite returns SQLITE_BUSY for the first process, hoping that this +** will induce the first process to release its read lock and allow +** the second process to proceed. +** ** The default busy callback is NULL. ** ** Sqlite is re-entrant, so the busy handler may start a new query. @@ -478,6 +545,7 @@ int sqlite3_set_authorizer( #define SQLITE_ANALYZE 28 /* Table Name NULL */ #define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */ #define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */ +#define SQLITE_FUNCTION 31 /* Function Name NULL */ /* ** The return value of the authorization function should be one of the @@ -654,6 +722,31 @@ int sqlite3_prepare16( ); /* +** Newer versions of the prepare API work just like the legacy versions +** but with one exception: The a copy of the SQL text is saved in the +** sqlite3_stmt structure that is returned. If this copy exists, it +** modifieds the behavior of sqlite3_step() slightly. First, sqlite3_step() +** will no longer return an SQLITE_SCHEMA error but will instead automatically +** rerun the compiler to rebuild the prepared statement. Secondly, +** sqlite3_step() now turns a full result code - the result code that +** use used to have to call sqlite3_reset() to get. +*/ +int sqlite3_prepare_v2( + sqlite3 *db, /* Database handle */ + const char *zSql, /* SQL statement, UTF-8 encoded */ + int nBytes, /* Length of zSql in bytes. */ + sqlite3_stmt **ppStmt, /* OUT: Statement handle */ + const char **pzTail /* OUT: Pointer to unused portion of zSql */ +); +int sqlite3_prepare16_v2( + sqlite3 *db, /* Database handle */ + const void *zSql, /* SQL statement, UTF-16 encoded */ + int nBytes, /* Length of zSql in bytes. */ + sqlite3_stmt **ppStmt, /* OUT: Statement handle */ + const void **pzTail /* OUT: Pointer to unused portion of zSql */ +); + +/* ** Pointers to the following two opaque structures are used to communicate ** with the implementations of user-defined functions. */ @@ -662,31 +755,32 @@ typedef struct Mem sqlite3_value; /* ** In the SQL strings input to sqlite3_prepare() and sqlite3_prepare16(), -** one or more literals can be replace by parameters "?" or ":AAA" or -** "$VVV" where AAA is an identifer and VVV is a variable name according -** to the syntax rules of the TCL programming language. -** The value of these parameters (also called "host parameter names") can -** be set using the routines listed below. -** -** In every case, the first parameter is a pointer to the sqlite3_stmt -** structure returned from sqlite3_prepare(). The second parameter is the -** index of the parameter. The first parameter as an index of 1. For -** named parameters (":AAA" or "$VVV") you can use +** one or more literals can be replace by parameters "?" or "?NNN" or +** ":AAA" or "@AAA" or "$VVV" where NNN is a integer, AAA is an identifer, +** and VVV is a variable name according to the syntax rules of the +** TCL programming language. The value of these parameters (also called +** "host parameter names") can be set using the routines listed below. +** +** In every case, the first argument is a pointer to the sqlite3_stmt +** structure returned from sqlite3_prepare(). The second argument is the +** index of the host parameter name. The first host parameter as an index +** of 1. For named host parameters (":AAA" or "$VVV") you can use ** sqlite3_bind_parameter_index() to get the correct index value given -** the parameters name. If the same named parameter occurs more than +** the parameter name. If the same named parameter occurs more than ** once, it is assigned the same index each time. ** -** The fifth parameter to sqlite3_bind_blob(), sqlite3_bind_text(), and +** The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and ** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or ** text after SQLite has finished with it. If the fifth argument is the ** special value SQLITE_STATIC, then the library assumes that the information ** is in static, unmanaged space and does not need to be freed. If the ** fifth argument has the value SQLITE_TRANSIENT, then SQLite makes its -** own private copy of the data. +** own private copy of the data before the sqlite3_bind_* routine returns. ** -** The sqlite3_bind_* routine must be called before sqlite3_step() after -** an sqlite3_prepare() or sqlite3_reset(). Unbound parameterss are -** interpreted as NULL. +** The sqlite3_bind_* routine must be called before sqlite3_step() and after +** an sqlite3_prepare() or sqlite3_reset(). Bindings persist across +** multiple calls to sqlite3_reset() and sqlite3_step(). Unbound parameters +** are interpreted as NULL. */ int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*)); int sqlite3_bind_double(sqlite3_stmt*, int, double); @@ -698,13 +792,13 @@ int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*)); int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*); /* -** Return the number of parameters in a compiled SQL statement. This +** Return the number of host parameters in a compiled SQL statement. This ** routine was added to support DBD::SQLite. */ int sqlite3_bind_parameter_count(sqlite3_stmt*); /* -** Return the name of the i-th parameter. Ordinary parameters "?" are +** Return the name of the i-th name parameter. Ordinary parameters "?" are ** nameless and a NULL is returned. For parameters of the form :AAA or ** $VVV the complete text of the parameter name is returned, including ** the initial ":" or "$". NULL is returned if the index is out of range. @@ -740,7 +834,7 @@ const char *sqlite3_column_name(sqlite3_stmt*,int); const void *sqlite3_column_name16(sqlite3_stmt*,int); /* -** The first parameter to the following calls is a compiled SQL statement. +** The first argument to the following calls is a compiled SQL statement. ** These functions return information about the Nth column returned by ** the statement, where N is the second function argument. ** @@ -1104,9 +1198,13 @@ void sqlite3_set_auxdata(sqlite3_context*, int, void*, void (*)(void*)); ** SQLITE_TRANSIENT value means that the content will likely change in ** the near future and that SQLite should make its own private copy of ** the content before returning. +** +** The typedef is necessary to work around problems in certain +** C++ compilers. See ticket #2191. */ -#define SQLITE_STATIC ((void(*)(void *))0) -#define SQLITE_TRANSIENT ((void(*)(void *))-1) +typedef void (*sqlite3_destructor_type)(void*); +#define SQLITE_STATIC ((sqlite3_destructor_type)0) +#define SQLITE_TRANSIENT ((sqlite3_destructor_type)-1) /* ** User-defined functions invoke the following routines in order to @@ -1520,6 +1618,42 @@ int sqlite3_enable_load_extension(sqlite3 *db, int onoff); /* ****** EXPERIMENTAL - subject to change without notice ************** ** +** Register an extension entry point that is automatically invoked +** whenever a new database connection is opened. +** +** This API can be invoked at program startup in order to register +** one or more statically linked extensions that will be available +** to all new database connections. +** +** Duplicate extensions are detected so calling this routine multiple +** times with the same extension is harmless. +** +** This routine stores a pointer to the extension in an array +** that is obtained from malloc(). If you run a memory leak +** checker on your program and it reports a leak because of this +** array, then invoke sqlite3_automatic_extension_reset() prior +** to shutdown to free the memory. +** +** Automatic extensions apply across all threads. +*/ +int sqlite3_auto_extension(void *xEntryPoint); + + +/* +****** EXPERIMENTAL - subject to change without notice ************** +** +** Disable all previously registered automatic extensions. This +** routine undoes the effect of all prior sqlite3_automatic_extension() +** calls. +** +** This call disabled automatic extensions in all threads. +*/ +void sqlite3_reset_auto_extension(void); + + +/* +****** EXPERIMENTAL - subject to change without notice ************** +** ** The interface to the virtual-table mechanism is currently considered ** to be experimental. The interface might change in incompatible ways. ** If this is a problem for you, do not use the interface at this time. @@ -1544,11 +1678,11 @@ typedef struct sqlite3_module sqlite3_module; struct sqlite3_module { int iVersion; int (*xCreate)(sqlite3*, void *pAux, - int argc, char **argv, - sqlite3_vtab **ppVTab); + int argc, const char *const*argv, + sqlite3_vtab **ppVTab, char**); int (*xConnect)(sqlite3*, void *pAux, - int argc, char **argv, - sqlite3_vtab **ppVTab); + int argc, const char *const*argv, + sqlite3_vtab **ppVTab, char**); int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*); int (*xDisconnect)(sqlite3_vtab *pVTab); int (*xDestroy)(sqlite3_vtab *pVTab); @@ -1668,10 +1802,21 @@ int sqlite3_create_module( ** be taylored to the specific needs of the module implementation. The ** purpose of this superclass is to define certain fields that are common ** to all module implementations. +** +** Virtual tables methods can set an error message by assigning a +** string obtained from sqlite3_mprintf() to zErrMsg. The method should +** take care that any prior string is freed by a call to sqlite3_free() +** prior to assigning a new string to zErrMsg. After the error message +** is delivered up to the client application, the string will be automatically +** freed by sqlite3_free() and the zErrMsg field will be zeroed. Note +** that sqlite3_mprintf() and sqlite3_free() are used on the zErrMsg field +** since virtual tables are commonly implemented in loadable extensions which +** do not have access to sqlite3MPrintf() or sqlite3Free(). */ struct sqlite3_vtab { const sqlite3_module *pModule; /* The module for this virtual table */ int nRef; /* Used internally */ + char *zErrMsg; /* Error message from sqlite3_mprintf() */ /* Virtual table implementations will typically add additional fields */ }; @@ -1697,6 +1842,24 @@ struct sqlite3_vtab_cursor { int sqlite3_declare_vtab(sqlite3*, const char *zCreateTable); /* +** Virtual tables can provide alternative implementations of functions +** using the xFindFunction method. But global versions of those functions +** must exist in order to be overloaded. +** +** This API makes sure a global version of a function with a particular +** name and number of parameters exists. If no such function exists +** before this API is called, a new function is created. The implementation +** of the new function always causes an exception to be thrown. So +** the new function is not good for anything by itself. Its only +** purpose is to be a place-holder function that can be overloaded +** by virtual tables. +** +** This API should be considered part of the virtual table interface, +** which is experimental and subject to change. +*/ +int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg); + +/* ** The interface to the virtual-table mechanism defined above (back up ** to a comment remarkably similar to this one) is currently considered ** to be experimental. The interface might change in incompatible ways. |