sqlite3.h.svn-base
上传用户:sunhongbo
上传日期:2022-01-25
资源大小:3010k
文件大小:251k
- ** or until [sqlite3_finalize(S)] is called.
- **
- ** {F13727} When a result column of a [SELECT] statement contains
- ** an AS clause, the name of that column is the indentifier
- ** to the right of the AS keyword.
- */
- const char *sqlite3_column_name(sqlite3_stmt*, int N);
- const void *sqlite3_column_name16(sqlite3_stmt*, int N);
- /*
- ** CAPI3REF: Source Of Data In A Query Result {F13740}
- **
- ** These routines provide a means to determine what column of what
- ** table in which database a result of a SELECT statement comes from.
- ** The name of the database or table or column can be returned as
- ** either a UTF8 or UTF16 string. The _database_ routines return
- ** the database name, the _table_ routines return the table name, and
- ** the origin_ routines return the column name.
- ** The returned string is valid until
- ** the [prepared statement] is destroyed using
- ** [sqlite3_finalize()] or until the same information is requested
- ** again in a different encoding.
- **
- ** The names returned are the original un-aliased names of the
- ** database, table, and column.
- **
- ** The first argument to the following calls is a [prepared statement].
- ** These functions return information about the Nth column returned by
- ** the statement, where N is the second function argument.
- **
- ** If the Nth column returned by the statement is an expression
- ** or subquery and is not a column value, then all of these functions
- ** return NULL. These routine might also return NULL if a memory
- ** allocation error occurs. Otherwise, they return the
- ** name of the attached database, table and column that query result
- ** column was extracted from.
- **
- ** As with all other SQLite APIs, those postfixed with "16" return
- ** UTF-16 encoded strings, the other functions return UTF-8. {END}
- **
- ** These APIs are only available if the library was compiled with the
- ** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined.
- **
- ** {U13751}
- ** If two or more threads call one or more of these routines against the same
- ** prepared statement and column at the same time then the results are
- ** undefined.
- **
- ** INVARIANTS:
- **
- ** {F13741} The [sqlite3_column_database_name(S,N)] interface returns either
- ** the UTF-8 zero-terminated name of the database from which the
- ** Nth result column of [prepared statement] S
- ** is extracted, or NULL if the the Nth column of S is a
- ** general expression or if unable to allocate memory
- ** to store the name.
- **
- ** {F13742} The [sqlite3_column_database_name16(S,N)] interface returns either
- ** the UTF-16 native byte order
- ** zero-terminated name of the database from which the
- ** Nth result column of [prepared statement] S
- ** is extracted, or NULL if the the Nth column of S is a
- ** general expression or if unable to allocate memory
- ** to store the name.
- **
- ** {F13743} The [sqlite3_column_table_name(S,N)] interface returns either
- ** the UTF-8 zero-terminated name of the table from which the
- ** Nth result column of [prepared statement] S
- ** is extracted, or NULL if the the Nth column of S is a
- ** general expression or if unable to allocate memory
- ** to store the name.
- **
- ** {F13744} The [sqlite3_column_table_name16(S,N)] interface returns either
- ** the UTF-16 native byte order
- ** zero-terminated name of the table from which the
- ** Nth result column of [prepared statement] S
- ** is extracted, or NULL if the the Nth column of S is a
- ** general expression or if unable to allocate memory
- ** to store the name.
- **
- ** {F13745} The [sqlite3_column_origin_name(S,N)] interface returns either
- ** the UTF-8 zero-terminated name of the table column from which the
- ** Nth result column of [prepared statement] S
- ** is extracted, or NULL if the the Nth column of S is a
- ** general expression or if unable to allocate memory
- ** to store the name.
- **
- ** {F13746} The [sqlite3_column_origin_name16(S,N)] interface returns either
- ** the UTF-16 native byte order
- ** zero-terminated name of the table column from which the
- ** Nth result column of [prepared statement] S
- ** is extracted, or NULL if the the Nth column of S is a
- ** general expression or if unable to allocate memory
- ** to store the name.
- **
- ** {F13748} The return values from
- ** [sqlite3_column_database_name|column metadata interfaces]
- ** are valid
- ** for the lifetime of the [prepared statement]
- ** or until the encoding is changed by another metadata
- ** interface call for the same prepared statement and column.
- **
- ** LIMITATIONS:
- **
- ** {U13751} If two or more threads call one or more
- ** [sqlite3_column_database_name|column metadata interfaces]
- ** the same [prepared statement] and result column
- ** at the same time then the results are undefined.
- */
- const char *sqlite3_column_database_name(sqlite3_stmt*,int);
- const void *sqlite3_column_database_name16(sqlite3_stmt*,int);
- const char *sqlite3_column_table_name(sqlite3_stmt*,int);
- const void *sqlite3_column_table_name16(sqlite3_stmt*,int);
- const char *sqlite3_column_origin_name(sqlite3_stmt*,int);
- const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);
- /*
- ** CAPI3REF: Declared Datatype Of A Query Result {F13760}
- **
- ** The first parameter is a [prepared statement].
- ** If this statement is a SELECT statement and the Nth column of the
- ** returned result set of that SELECT is a table column (not an
- ** expression or subquery) then the declared type of the table
- ** column is returned. If the Nth column of the result set is an
- ** expression or subquery, then a NULL pointer is returned.
- ** The returned string is always UTF-8 encoded. {END}
- ** For example, in the database schema:
- **
- ** CREATE TABLE t1(c1 VARIANT);
- **
- ** And the following statement compiled:
- **
- ** SELECT c1 + 1, c1 FROM t1;
- **
- ** Then this routine would return the string "VARIANT" for the second
- ** result column (i==1), and a NULL pointer for the first result column
- ** (i==0).
- **
- ** SQLite uses dynamic run-time typing. So just because a column
- ** is declared to contain a particular type does not mean that the
- ** data stored in that column is of the declared type. SQLite is
- ** strongly typed, but the typing is dynamic not static. Type
- ** is associated with individual values, not with the containers
- ** used to hold those values.
- **
- ** INVARIANTS:
- **
- ** {F13761} A successful call to [sqlite3_column_decltype(S,N)]
- ** returns a zero-terminated UTF-8 string containing the
- ** the declared datatype of the table column that appears
- ** as the Nth column (numbered from 0) of the result set to the
- ** [prepared statement] S.
- **
- ** {F13762} A successful call to [sqlite3_column_decltype16(S,N)]
- ** returns a zero-terminated UTF-16 native byte order string
- ** containing the declared datatype of the table column that appears
- ** as the Nth column (numbered from 0) of the result set to the
- ** [prepared statement] S.
- **
- ** {F13763} If N is less than 0 or N is greater than or equal to
- ** the number of columns in [prepared statement] S
- ** or if the Nth column of S is an expression or subquery rather
- ** than a table column or if a memory allocation failure
- ** occurs during encoding conversions, then
- ** calls to [sqlite3_column_decltype(S,N)] or
- ** [sqlite3_column_decltype16(S,N)] return NULL.
- */
- const char *sqlite3_column_decltype(sqlite3_stmt*,int);
- const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
- /*
- ** CAPI3REF: Evaluate An SQL Statement {F13200}
- **
- ** After an [prepared statement] has been prepared with a call
- ** to either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or to one of
- ** the legacy interfaces [sqlite3_prepare()] or [sqlite3_prepare16()],
- ** then this function must be called one or more times to evaluate the
- ** statement.
- **
- ** The details of the behavior of this sqlite3_step() interface depend
- ** on whether the statement was prepared using the newer "v2" interface
- ** [sqlite3_prepare_v2()] and [sqlite3_prepare16_v2()] or the older legacy
- ** interface [sqlite3_prepare()] and [sqlite3_prepare16()]. The use of the
- ** new "v2" interface is recommended for new applications but the legacy
- ** interface will continue to be supported.
- **
- ** In the lagacy interface, the return value will be either [SQLITE_BUSY],
- ** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE].
- ** With the "v2" interface, any of the other [SQLITE_OK | result code]
- ** or [SQLITE_IOERR_READ | extended result code] might be returned as
- ** well.
- **
- ** [SQLITE_BUSY] means that the database engine was unable to acquire the
- ** database locks it needs to do its job. If the statement is a COMMIT
- ** or occurs outside of an explicit transaction, then you can retry the
- ** statement. If the statement is not a COMMIT and occurs within a
- ** explicit transaction then you should rollback the transaction before
- ** continuing.
- **
- ** [SQLITE_DONE] means that the statement has finished executing
- ** successfully. sqlite3_step() should not be called again on this virtual
- ** machine without first calling [sqlite3_reset()] to reset the virtual
- ** machine back to its initial state.
- **
- ** If the SQL statement being executed returns any data, then
- ** [SQLITE_ROW] is returned each time a new row of data is ready
- ** for processing by the caller. The values may be accessed using
- ** the [sqlite3_column_int | column access functions].
- ** sqlite3_step() is called again to retrieve the next row of data.
- **
- ** [SQLITE_ERROR] means that a run-time error (such as a constraint
- ** violation) has occurred. sqlite3_step() should not be called again on
- ** the VM. More information may be found by calling [sqlite3_errmsg()].
- ** With the legacy interface, a more specific error code (example:
- ** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth)
- ** can be obtained by calling [sqlite3_reset()] on the
- ** [prepared statement]. In the "v2" interface,
- ** the more specific error code is returned directly by sqlite3_step().
- **
- ** [SQLITE_MISUSE] means that the this routine was called inappropriately.
- ** Perhaps it was called on a [prepared statement] that has
- ** already been [sqlite3_finalize | finalized] or on one that had
- ** previously returned [SQLITE_ERROR] or [SQLITE_DONE]. Or it could
- ** be the case that the same database connection is being used by two or
- ** more threads at the same moment in time.
- **
- ** <b>Goofy Interface Alert:</b>
- ** In the legacy interface,
- ** the sqlite3_step() API always returns a generic error code,
- ** [SQLITE_ERROR], following any error other than [SQLITE_BUSY]
- ** and [SQLITE_MISUSE]. You must call [sqlite3_reset()] or
- ** [sqlite3_finalize()] in order to find one of the specific
- ** [error codes] that better describes the error.
- ** We admit that this is a goofy design. The problem has been fixed
- ** with the "v2" interface. If you prepare all of your SQL statements
- ** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead
- ** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()], then the
- ** more specific [error codes] are returned directly
- ** by sqlite3_step(). The use of the "v2" interface is recommended.
- **
- ** INVARIANTS:
- **
- ** {F13202} If [prepared statement] S is ready to be
- ** run, then [sqlite3_step(S)] advances that prepared statement
- ** until to completion or until it is ready to return another
- ** row of the result set or an interrupt or run-time error occurs.
- **
- ** {F15304} When a call to [sqlite3_step(S)] causes the
- ** [prepared statement] S to run to completion,
- ** the function returns [SQLITE_DONE].
- **
- ** {F15306} When a call to [sqlite3_step(S)] stops because it is ready
- ** to return another row of the result set, it returns
- ** [SQLITE_ROW].
- **
- ** {F15308} If a call to [sqlite3_step(S)] encounters an
- ** [sqlite3_interrupt|interrupt] or a run-time error,
- ** it returns an appropraite error code that is not one of
- ** [SQLITE_OK], [SQLITE_ROW], or [SQLITE_DONE].
- **
- ** {F15310} If an [sqlite3_interrupt|interrupt] or run-time error
- ** occurs during a call to [sqlite3_step(S)]
- ** for a [prepared statement] S created using
- ** legacy interfaces [sqlite3_prepare()] or
- ** [sqlite3_prepare16()] then the function returns either
- ** [SQLITE_ERROR], [SQLITE_BUSY], or [SQLITE_MISUSE].
- */
- int sqlite3_step(sqlite3_stmt*);
- /*
- ** CAPI3REF: Number of columns in a result set {F13770}
- **
- ** Return the number of values in the current row of the result set.
- **
- ** INVARIANTS:
- **
- ** {F13771} After a call to [sqlite3_step(S)] that returns
- ** [SQLITE_ROW], the [sqlite3_data_count(S)] routine
- ** will return the same value as the
- ** [sqlite3_column_count(S)] function.
- **
- ** {F13772} After [sqlite3_step(S)] has returned any value other than
- ** [SQLITE_ROW] or before [sqlite3_step(S)] has been
- ** called on the [prepared statement] for
- ** the first time since it was [sqlite3_prepare|prepared]
- ** or [sqlite3_reset|reset], the [sqlite3_data_count(S)]
- ** routine returns zero.
- */
- int sqlite3_data_count(sqlite3_stmt *pStmt);
- /*
- ** CAPI3REF: Fundamental Datatypes {F10265}
- ** KEYWORDS: SQLITE_TEXT
- **
- ** {F10266}Every value in SQLite has one of five fundamental datatypes:
- **
- ** <ul>
- ** <li> 64-bit signed integer
- ** <li> 64-bit IEEE floating point number
- ** <li> string
- ** <li> BLOB
- ** <li> NULL
- ** </ul> {END}
- **
- ** These constants are codes for each of those types.
- **
- ** Note that the SQLITE_TEXT constant was also used in SQLite version 2
- ** for a completely different meaning. Software that links against both
- ** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT not
- ** SQLITE_TEXT.
- */
- #define SQLITE_INTEGER 1
- #define SQLITE_FLOAT 2
- #define SQLITE_BLOB 4
- #define SQLITE_NULL 5
- #ifdef SQLITE_TEXT
- # undef SQLITE_TEXT
- #else
- # define SQLITE_TEXT 3
- #endif
- #define SQLITE3_TEXT 3
- /*
- ** CAPI3REF: Results Values From A Query {F13800}
- **
- ** These routines form the "result set query" interface.
- **
- ** These routines return information about
- ** a single column of the current result row of a query. In every
- ** case the first argument is a pointer to the
- ** [prepared statement] that is being
- ** evaluated (the [sqlite3_stmt*] that was returned from
- ** [sqlite3_prepare_v2()] or one of its variants) and
- ** the second argument is the index of the column for which information
- ** should be returned. The left-most column of the result set
- ** has an index of 0.
- **
- ** If the SQL statement is not currently point to a valid row, or if the
- ** the column index is out of range, the result is undefined.
- ** These routines may only be called when the most recent call to
- ** [sqlite3_step()] has returned [SQLITE_ROW] and neither
- ** [sqlite3_reset()] nor [sqlite3_finalize()] has been call subsequently.
- ** If any of these routines are called after [sqlite3_reset()] or
- ** [sqlite3_finalize()] or after [sqlite3_step()] has returned
- ** something other than [SQLITE_ROW], the results are undefined.
- ** If [sqlite3_step()] or [sqlite3_reset()] or [sqlite3_finalize()]
- ** are called from a different thread while any of these routines
- ** are pending, then the results are undefined.
- **
- ** The sqlite3_column_type() routine returns
- ** [SQLITE_INTEGER | datatype code] for the initial data type
- ** of the result column. The returned value is one of [SQLITE_INTEGER],
- ** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL]. The value
- ** returned by sqlite3_column_type() is only meaningful if no type
- ** conversions have occurred as described below. After a type conversion,
- ** the value returned by sqlite3_column_type() is undefined. Future
- ** versions of SQLite may change the behavior of sqlite3_column_type()
- ** following a type conversion.
- **
- ** If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
- ** routine returns the number of bytes in that BLOB or string.
- ** If the result is a UTF-16 string, then sqlite3_column_bytes() converts
- ** the string to UTF-8 and then returns the number of bytes.
- ** If the result is a numeric value then sqlite3_column_bytes() uses
- ** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns
- ** the number of bytes in that string.
- ** The value returned does not include the zero terminator at the end
- ** of the string. For clarity: the value returned is the number of
- ** bytes in the string, not the number of characters.
- **
- ** Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
- ** even empty strings, are always zero terminated. The return
- ** value from sqlite3_column_blob() for a zero-length blob is an arbitrary
- ** pointer, possibly even a NULL pointer.
- **
- ** The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes()
- ** but leaves the result in UTF-16 in native byte order instead of UTF-8.
- ** The zero terminator is not included in this count.
- **
- ** The object returned by [sqlite3_column_value()] is an
- ** [unprotected sqlite3_value] object. An unprotected sqlite3_value object
- ** may only be used with [sqlite3_bind_value()] and [sqlite3_result_value()].
- ** If the [unprotected sqlite3_value] object returned by
- ** [sqlite3_column_value()] is used in any other way, including calls
- ** to routines like
- ** [sqlite3_value_int()], [sqlite3_value_text()], or [sqlite3_value_bytes()],
- ** then the behavior is undefined.
- **
- ** These routines attempt to convert the value where appropriate. For
- ** example, if the internal representation is FLOAT and a text result
- ** is requested, [sqlite3_snprintf()] is used internally to do the conversion
- ** automatically. The following table details the conversions that
- ** are applied:
- **
- ** <blockquote>
- ** <table border="1">
- ** <tr><th> Internal<br>Type <th> Requested<br>Type <th> Conversion
- **
- ** <tr><td> NULL <td> INTEGER <td> Result is 0
- ** <tr><td> NULL <td> FLOAT <td> Result is 0.0
- ** <tr><td> NULL <td> TEXT <td> Result is NULL pointer
- ** <tr><td> NULL <td> BLOB <td> Result is NULL pointer
- ** <tr><td> INTEGER <td> FLOAT <td> Convert from integer to float
- ** <tr><td> INTEGER <td> TEXT <td> ASCII rendering of the integer
- ** <tr><td> INTEGER <td> BLOB <td> Same as for INTEGER->TEXT
- ** <tr><td> FLOAT <td> INTEGER <td> Convert from float to integer
- ** <tr><td> FLOAT <td> TEXT <td> ASCII rendering of the float
- ** <tr><td> FLOAT <td> BLOB <td> Same as FLOAT->TEXT
- ** <tr><td> TEXT <td> INTEGER <td> Use atoi()
- ** <tr><td> TEXT <td> FLOAT <td> Use atof()
- ** <tr><td> TEXT <td> BLOB <td> No change
- ** <tr><td> BLOB <td> INTEGER <td> Convert to TEXT then use atoi()
- ** <tr><td> BLOB <td> FLOAT <td> Convert to TEXT then use atof()
- ** <tr><td> BLOB <td> TEXT <td> Add a zero terminator if needed
- ** </table>
- ** </blockquote>
- **
- ** The table above makes reference to standard C library functions atoi()
- ** and atof(). SQLite does not really use these functions. It has its
- ** on equavalent internal routines. The atoi() and atof() names are
- ** used in the table for brevity and because they are familiar to most
- ** C programmers.
- **
- ** Note that when type conversions occur, pointers returned by prior
- ** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
- ** sqlite3_column_text16() may be invalidated.
- ** Type conversions and pointer invalidations might occur
- ** in the following cases:
- **
- ** <ul>
- ** <li><p> The initial content is a BLOB and sqlite3_column_text()
- ** or sqlite3_column_text16() is called. A zero-terminator might
- ** need to be added to the string.</p></li>
- **
- ** <li><p> The initial content is UTF-8 text and sqlite3_column_bytes16() or
- ** sqlite3_column_text16() is called. The content must be converted
- ** to UTF-16.</p></li>
- **
- ** <li><p> The initial content is UTF-16 text and sqlite3_column_bytes() or
- ** sqlite3_column_text() is called. The content must be converted
- ** to UTF-8.</p></li>
- ** </ul>
- **
- ** Conversions between UTF-16be and UTF-16le are always done in place and do
- ** not invalidate a prior pointer, though of course the content of the buffer
- ** that the prior pointer points to will have been modified. Other kinds
- ** of conversion are done in place when it is possible, but sometime it is
- ** not possible and in those cases prior pointers are invalidated.
- **
- ** The safest and easiest to remember policy is to invoke these routines
- ** in one of the following ways:
- **
- ** <ul>
- ** <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li>
- ** <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li>
- ** <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li>
- ** </ul>
- **
- ** In other words, you should call sqlite3_column_text(), sqlite3_column_blob(),
- ** or sqlite3_column_text16() first to force the result into the desired
- ** format, then invoke sqlite3_column_bytes() or sqlite3_column_bytes16() to
- ** find the size of the result. Do not mix call to sqlite3_column_text() or
- ** sqlite3_column_blob() with calls to sqlite3_column_bytes16(). And do not
- ** mix calls to sqlite3_column_text16() with calls to sqlite3_column_bytes().
- **
- ** The pointers returned are valid until a type conversion occurs as
- ** described above, or until [sqlite3_step()] or [sqlite3_reset()] or
- ** [sqlite3_finalize()] is called. The memory space used to hold strings
- ** and blobs is freed automatically. Do <b>not</b> pass the pointers returned
- ** [sqlite3_column_blob()], [sqlite3_column_text()], etc. into
- ** [sqlite3_free()].
- **
- ** If a memory allocation error occurs during the evaluation of any
- ** of these routines, a default value is returned. The default value
- ** is either the integer 0, the floating point number 0.0, or a NULL
- ** pointer. Subsequent calls to [sqlite3_errcode()] will return
- ** [SQLITE_NOMEM].
- **
- ** INVARIANTS:
- **
- ** {F13803} The [sqlite3_column_blob(S,N)] interface converts the
- ** Nth column in the current row of the result set for
- ** [prepared statement] S into a blob and then returns a
- ** pointer to the converted value.
- **
- ** {F13806} The [sqlite3_column_bytes(S,N)] interface returns the
- ** number of bytes in the blob or string (exclusive of the
- ** zero terminator on the string) that was returned by the
- ** most recent call to [sqlite3_column_blob(S,N)] or
- ** [sqlite3_column_text(S,N)].
- **
- ** {F13809} The [sqlite3_column_bytes16(S,N)] interface returns the
- ** number of bytes in the string (exclusive of the
- ** zero terminator on the string) that was returned by the
- ** most recent call to [sqlite3_column_text16(S,N)].
- **
- ** {F13812} The [sqlite3_column_double(S,N)] interface converts the
- ** Nth column in the current row of the result set for
- ** [prepared statement] S into a floating point value and
- ** returns a copy of that value.
- **
- ** {F13815} The [sqlite3_column_int(S,N)] interface converts the
- ** Nth column in the current row of the result set for
- ** [prepared statement] S into a 64-bit signed integer and
- ** returns the lower 32 bits of that integer.
- **
- ** {F13818} The [sqlite3_column_int64(S,N)] interface converts the
- ** Nth column in the current row of the result set for
- ** [prepared statement] S into a 64-bit signed integer and
- ** returns a copy of that integer.
- **
- ** {F13821} The [sqlite3_column_text(S,N)] interface converts the
- ** Nth column in the current row of the result set for
- ** [prepared statement] S into a zero-terminated UTF-8
- ** string and returns a pointer to that string.
- **
- ** {F13824} The [sqlite3_column_text16(S,N)] interface converts the
- ** Nth column in the current row of the result set for
- ** [prepared statement] S into a zero-terminated 2-byte
- ** aligned UTF-16 native byte order
- ** string and returns a pointer to that string.
- **
- ** {F13827} The [sqlite3_column_type(S,N)] interface returns
- ** one of [SQLITE_NULL], [SQLITE_INTEGER], [SQLITE_FLOAT],
- ** [SQLITE_TEXT], or [SQLITE_BLOB] as appropriate for
- ** the Nth column in the current row of the result set for
- ** [prepared statement] S.
- **
- ** {F13830} The [sqlite3_column_value(S,N)] interface returns a
- ** pointer to an [unprotected sqlite3_value] object for the
- ** Nth column in the current row of the result set for
- ** [prepared statement] S.
- */
- const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
- int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
- int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
- double sqlite3_column_double(sqlite3_stmt*, int iCol);
- int sqlite3_column_int(sqlite3_stmt*, int iCol);
- sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
- const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
- const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
- int sqlite3_column_type(sqlite3_stmt*, int iCol);
- sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
- /*
- ** CAPI3REF: Destroy A Prepared Statement Object {F13300}
- **
- ** The sqlite3_finalize() function is called to delete a
- ** [prepared statement]. If the statement was
- ** executed successfully, or not executed at all, then SQLITE_OK is returned.
- ** If execution of the statement failed then an
- ** [error code] or [extended error code]
- ** is returned.
- **
- ** This routine can be called at any point during the execution of the
- ** [prepared statement]. If the virtual machine has not
- ** completed execution when this routine is called, that is like
- ** encountering an error or an interrupt. (See [sqlite3_interrupt()].)
- ** Incomplete updates may be rolled back and transactions cancelled,
- ** depending on the circumstances, and the
- ** [error code] returned will be [SQLITE_ABORT].
- **
- ** INVARIANTS:
- **
- ** {F11302} The [sqlite3_finalize(S)] interface destroys the
- ** [prepared statement] S and releases all
- ** memory and file resources held by that object.
- **
- ** {F11304} If the most recent call to [sqlite3_step(S)] for the
- ** [prepared statement] S returned an error,
- ** then [sqlite3_finalize(S)] returns that same error.
- */
- int sqlite3_finalize(sqlite3_stmt *pStmt);
- /*
- ** CAPI3REF: Reset A Prepared Statement Object {F13330}
- **
- ** The sqlite3_reset() function is called to reset a
- ** [prepared statement] object.
- ** back to its initial state, ready to be re-executed.
- ** Any SQL statement variables that had values bound to them using
- ** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values.
- ** Use [sqlite3_clear_bindings()] to reset the bindings.
- **
- ** {F11332} The [sqlite3_reset(S)] interface resets the [prepared statement] S
- ** back to the beginning of its program.
- **
- ** {F11334} If the most recent call to [sqlite3_step(S)] for
- ** [prepared statement] S returned [SQLITE_ROW] or [SQLITE_DONE],
- ** or if [sqlite3_step(S)] has never before been called on S,
- ** then [sqlite3_reset(S)] returns [SQLITE_OK].
- **
- ** {F11336} If the most recent call to [sqlite3_step(S)] for
- ** [prepared statement] S indicated an error, then
- ** [sqlite3_reset(S)] returns an appropriate [error code].
- **
- ** {F11338} The [sqlite3_reset(S)] interface does not change the values
- ** of any [sqlite3_bind_blob|bindings] on [prepared statement] S.
- */
- int sqlite3_reset(sqlite3_stmt *pStmt);
- /*
- ** CAPI3REF: Create Or Redefine SQL Functions {F16100}
- ** KEYWORDS: {function creation routines}
- **
- ** These two functions (collectively known as
- ** "function creation routines") are used to add SQL functions or aggregates
- ** or to redefine the behavior of existing SQL functions or aggregates. The
- ** difference only between the two is that the second parameter, the
- ** name of the (scalar) function or aggregate, is encoded in UTF-8 for
- ** sqlite3_create_function() and UTF-16 for sqlite3_create_function16().
- **
- ** The first parameter is the [database connection] to which the SQL
- ** function is to be added. If a single
- ** program uses more than one [database connection] internally, then SQL
- ** functions must be added individually to each [database connection].
- **
- ** The second parameter is the name of the SQL function to be created
- ** or redefined.
- ** The length of the name is limited to 255 bytes, exclusive of the
- ** zero-terminator. Note that the name length limit is in bytes, not
- ** characters. Any attempt to create a function with a longer name
- ** will result in an SQLITE_ERROR error.
- **
- ** The third parameter is the number of arguments that the SQL function or
- ** aggregate takes. If this parameter is negative, then the SQL function or
- ** aggregate may take any number of arguments.
- **
- ** The fourth parameter, eTextRep, specifies what
- ** [SQLITE_UTF8 | text encoding] this SQL function prefers for
- ** its parameters. Any SQL function implementation should be able to work
- ** work with UTF-8, UTF-16le, or UTF-16be. But some implementations may be
- ** more efficient with one encoding than another. It is allowed to
- ** invoke sqlite3_create_function() or sqlite3_create_function16() multiple
- ** times with the same function but with different values of eTextRep.
- ** When multiple implementations of the same function are available, SQLite
- ** will pick the one that involves the least amount of data conversion.
- ** If there is only a single implementation which does not care what
- ** text encoding is used, then the fourth argument should be
- ** [SQLITE_ANY].
- **
- ** The fifth parameter is an arbitrary pointer. The implementation
- ** of the function can gain access to this pointer using
- ** [sqlite3_user_data()].
- **
- ** The seventh, eighth and ninth parameters, xFunc, xStep and xFinal, are
- ** pointers to C-language functions that implement the SQL
- ** function or aggregate. A scalar SQL function requires an implementation of
- ** the xFunc callback only, NULL pointers should be passed as the xStep
- ** and xFinal parameters. An aggregate SQL function requires an implementation
- ** of xStep and xFinal and NULL should be passed for xFunc. To delete an
- ** existing SQL function or aggregate, pass NULL for all three function
- ** callback.
- **
- ** It is permitted to register multiple implementations of the same
- ** functions with the same name but with either differing numbers of
- ** arguments or differing perferred text encodings. SQLite will use
- ** the implementation most closely matches the way in which the
- ** SQL function is used.
- **
- ** INVARIANTS:
- **
- ** {F16103} The [sqlite3_create_function16()] interface behaves exactly
- ** like [sqlite3_create_function()] in every way except that it
- ** interprets the zFunctionName argument as
- ** zero-terminated UTF-16 native byte order instead of as a
- ** zero-terminated UTF-8.
- **
- ** {F16106} A successful invocation of
- ** the [sqlite3_create_function(D,X,N,E,...)] interface registers
- ** or replaces callback functions in [database connection] D
- ** used to implement the SQL function named X with N parameters
- ** and having a perferred text encoding of E.
- **
- ** {F16109} A successful call to [sqlite3_create_function(D,X,N,E,P,F,S,L)]
- ** replaces the P, F, S, and L values from any prior calls with
- ** the same D, X, N, and E values.
- **
- ** {F16112} The [sqlite3_create_function(D,X,...)] interface fails with
- ** a return code of [SQLITE_ERROR] if the SQL function name X is
- ** longer than 255 bytes exclusive of the zero terminator.
- **
- ** {F16118} Either F must be NULL and S and L are non-NULL or else F
- ** is non-NULL and S and L are NULL, otherwise
- ** [sqlite3_create_function(D,X,N,E,P,F,S,L)] returns [SQLITE_ERROR].
- **
- ** {F16121} The [sqlite3_create_function(D,...)] interface fails with an
- ** error code of [SQLITE_BUSY] if there exist [prepared statements]
- ** associated with the [database connection] D.
- **
- ** {F16124} The [sqlite3_create_function(D,X,N,...)] interface fails with an
- ** error code of [SQLITE_ERROR] if parameter N (specifying the number
- ** of arguments to the SQL function being registered) is less
- ** than -1 or greater than 127.
- **
- ** {F16127} When N is non-negative, the [sqlite3_create_function(D,X,N,...)]
- ** interface causes callbacks to be invoked for the SQL function
- ** named X when the number of arguments to the SQL function is
- ** exactly N.
- **
- ** {F16130} When N is -1, the [sqlite3_create_function(D,X,N,...)]
- ** interface causes callbacks to be invoked for the SQL function
- ** named X with any number of arguments.
- **
- ** {F16133} When calls to [sqlite3_create_function(D,X,N,...)]
- ** specify multiple implementations of the same function X
- ** and when one implementation has N>=0 and the other has N=(-1)
- ** the implementation with a non-zero N is preferred.
- **
- ** {F16136} When calls to [sqlite3_create_function(D,X,N,E,...)]
- ** specify multiple implementations of the same function X with
- ** the same number of arguments N but with different
- ** encodings E, then the implementation where E matches the
- ** database encoding is preferred.
- **
- ** {F16139} For an aggregate SQL function created using
- ** [sqlite3_create_function(D,X,N,E,P,0,S,L)] the finializer
- ** function L will always be invoked exactly once if the
- ** step function S is called one or more times.
- **
- ** {F16142} When SQLite invokes either the xFunc or xStep function of
- ** an application-defined SQL function or aggregate created
- ** by [sqlite3_create_function()] or [sqlite3_create_function16()],
- ** then the array of [sqlite3_value] objects passed as the
- ** third parameter are always [protected sqlite3_value] objects.
- */
- int sqlite3_create_function(
- sqlite3 *db,
- const char *zFunctionName,
- int nArg,
- int eTextRep,
- void *pApp,
- void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
- void (*xStep)(sqlite3_context*,int,sqlite3_value**),
- void (*xFinal)(sqlite3_context*)
- );
- int sqlite3_create_function16(
- sqlite3 *db,
- const void *zFunctionName,
- int nArg,
- int eTextRep,
- void *pApp,
- void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
- void (*xStep)(sqlite3_context*,int,sqlite3_value**),
- void (*xFinal)(sqlite3_context*)
- );
- /*
- ** CAPI3REF: Text Encodings {F10267}
- **
- ** These constant define integer codes that represent the various
- ** text encodings supported by SQLite.
- */
- #define SQLITE_UTF8 1
- #define SQLITE_UTF16LE 2
- #define SQLITE_UTF16BE 3
- #define SQLITE_UTF16 4 /* Use native byte order */
- #define SQLITE_ANY 5 /* sqlite3_create_function only */
- #define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */
- /*
- ** CAPI3REF: Obsolete Functions
- **
- ** These functions are all now obsolete. In order to maintain
- ** backwards compatibility with older code, we continue to support
- ** these functions. However, new development projects should avoid
- ** the use of these functions. To help encourage people to avoid
- ** using these functions, we are not going to tell you want they do.
- */
- int sqlite3_aggregate_count(sqlite3_context*);
- int sqlite3_expired(sqlite3_stmt*);
- int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
- int sqlite3_global_recover(void);
- void sqlite3_thread_cleanup(void);
- int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),void*,sqlite3_int64);
- /*
- ** CAPI3REF: Obtaining SQL Function Parameter Values {F15100}
- **
- ** The C-language implementation of SQL functions and aggregates uses
- ** this set of interface routines to access the parameter values on
- ** the function or aggregate.
- **
- ** The xFunc (for scalar functions) or xStep (for aggregates) parameters
- ** to [sqlite3_create_function()] and [sqlite3_create_function16()]
- ** define callbacks that implement the SQL functions and aggregates.
- ** The 4th parameter to these callbacks is an array of pointers to
- ** [protected sqlite3_value] objects. There is one [sqlite3_value] object for
- ** each parameter to the SQL function. These routines are used to
- ** extract values from the [sqlite3_value] objects.
- **
- ** These routines work only with [protected sqlite3_value] objects.
- ** Any attempt to use these routines on an [unprotected sqlite3_value]
- ** object results in undefined behavior.
- **
- ** These routines work just like the corresponding
- ** [sqlite3_column_blob | sqlite3_column_* routines] except that
- ** these routines take a single [protected sqlite3_value] object pointer
- ** instead of an [sqlite3_stmt*] pointer and an integer column number.
- **
- ** The sqlite3_value_text16() interface extracts a UTF16 string
- ** in the native byte-order of the host machine. The
- ** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces
- ** extract UTF16 strings as big-endian and little-endian respectively.
- **
- ** The sqlite3_value_numeric_type() interface attempts to apply
- ** numeric affinity to the value. This means that an attempt is
- ** made to convert the value to an integer or floating point. If
- ** such a conversion is possible without loss of information (in other
- ** words if the value is a string that looks like a number)
- ** then the conversion is done. Otherwise no conversion occurs. The
- ** [SQLITE_INTEGER | datatype] after conversion is returned.
- **
- ** Please pay particular attention to the fact that the pointer that
- ** is returned from [sqlite3_value_blob()], [sqlite3_value_text()], or
- ** [sqlite3_value_text16()] can be invalidated by a subsequent call to
- ** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()],
- ** or [sqlite3_value_text16()].
- **
- ** These routines must be called from the same thread as
- ** the SQL function that supplied the [sqlite3_value*] parameters.
- **
- **
- ** INVARIANTS:
- **
- ** {F15103} The [sqlite3_value_blob(V)] interface converts the
- ** [protected sqlite3_value] object V into a blob and then returns a
- ** pointer to the converted value.
- **
- ** {F15106} The [sqlite3_value_bytes(V)] interface returns the
- ** number of bytes in the blob or string (exclusive of the
- ** zero terminator on the string) that was returned by the
- ** most recent call to [sqlite3_value_blob(V)] or
- ** [sqlite3_value_text(V)].
- **
- ** {F15109} The [sqlite3_value_bytes16(V)] interface returns the
- ** number of bytes in the string (exclusive of the
- ** zero terminator on the string) that was returned by the
- ** most recent call to [sqlite3_value_text16(V)],
- ** [sqlite3_value_text16be(V)], or [sqlite3_value_text16le(V)].
- **
- ** {F15112} The [sqlite3_value_double(V)] interface converts the
- ** [protected sqlite3_value] object V into a floating point value and
- ** returns a copy of that value.
- **
- ** {F15115} The [sqlite3_value_int(V)] interface converts the
- ** [protected sqlite3_value] object V into a 64-bit signed integer and
- ** returns the lower 32 bits of that integer.
- **
- ** {F15118} The [sqlite3_value_int64(V)] interface converts the
- ** [protected sqlite3_value] object V into a 64-bit signed integer and
- ** returns a copy of that integer.
- **
- ** {F15121} The [sqlite3_value_text(V)] interface converts the
- ** [protected sqlite3_value] object V into a zero-terminated UTF-8
- ** string and returns a pointer to that string.
- **
- ** {F15124} The [sqlite3_value_text16(V)] interface converts the
- ** [protected sqlite3_value] object V into a zero-terminated 2-byte
- ** aligned UTF-16 native byte order
- ** string and returns a pointer to that string.
- **
- ** {F15127} The [sqlite3_value_text16be(V)] interface converts the
- ** [protected sqlite3_value] object V into a zero-terminated 2-byte
- ** aligned UTF-16 big-endian
- ** string and returns a pointer to that string.
- **
- ** {F15130} The [sqlite3_value_text16le(V)] interface converts the
- ** [protected sqlite3_value] object V into a zero-terminated 2-byte
- ** aligned UTF-16 little-endian
- ** string and returns a pointer to that string.
- **
- ** {F15133} The [sqlite3_value_type(V)] interface returns
- ** one of [SQLITE_NULL], [SQLITE_INTEGER], [SQLITE_FLOAT],
- ** [SQLITE_TEXT], or [SQLITE_BLOB] as appropriate for
- ** the [sqlite3_value] object V.
- **
- ** {F15136} The [sqlite3_value_numeric_type(V)] interface converts
- ** the [protected sqlite3_value] object V into either an integer or
- ** a floating point value if it can do so without loss of
- ** information, and returns one of [SQLITE_NULL],
- ** [SQLITE_INTEGER], [SQLITE_FLOAT], [SQLITE_TEXT], or
- ** [SQLITE_BLOB] as appropriate for
- ** the [protected sqlite3_value] object V after the conversion attempt.
- */
- const void *sqlite3_value_blob(sqlite3_value*);
- int sqlite3_value_bytes(sqlite3_value*);
- int sqlite3_value_bytes16(sqlite3_value*);
- double sqlite3_value_double(sqlite3_value*);
- int sqlite3_value_int(sqlite3_value*);
- sqlite3_int64 sqlite3_value_int64(sqlite3_value*);
- const unsigned char *sqlite3_value_text(sqlite3_value*);
- const void *sqlite3_value_text16(sqlite3_value*);
- const void *sqlite3_value_text16le(sqlite3_value*);
- const void *sqlite3_value_text16be(sqlite3_value*);
- int sqlite3_value_type(sqlite3_value*);
- int sqlite3_value_numeric_type(sqlite3_value*);
- /*
- ** CAPI3REF: Obtain Aggregate Function Context {F16210}
- **
- ** The implementation of aggregate SQL functions use this routine to allocate
- ** a structure for storing their state.
- ** The first time the sqlite3_aggregate_context() routine is
- ** is called for a particular aggregate, SQLite allocates nBytes of memory
- ** zeros that memory, and returns a pointer to it.
- ** On second and subsequent calls to sqlite3_aggregate_context()
- ** for the same aggregate function index, the same buffer is returned.
- ** The implementation
- ** of the aggregate can use the returned buffer to accumulate data.
- **
- ** SQLite automatically frees the allocated buffer when the aggregate
- ** query concludes.
- **
- ** The first parameter should be a copy of the
- ** [sqlite3_context | SQL function context] that is the first
- ** parameter to the callback routine that implements the aggregate
- ** function.
- **
- ** This routine must be called from the same thread in which
- ** the aggregate SQL function is running.
- **
- ** INVARIANTS:
- **
- ** {F16211} The first invocation of [sqlite3_aggregate_context(C,N)] for
- ** a particular instance of an aggregate function (for a particular
- ** context C) causes SQLite to allocation N bytes of memory,
- ** zero that memory, and return a pointer to the allocationed
- ** memory.
- **
- ** {F16213} If a memory allocation error occurs during
- ** [sqlite3_aggregate_context(C,N)] then the function returns 0.
- **
- ** {F16215} Second and subsequent invocations of
- ** [sqlite3_aggregate_context(C,N)] for the same context pointer C
- ** ignore the N parameter and return a pointer to the same
- ** block of memory returned by the first invocation.
- **
- ** {F16217} The memory allocated by [sqlite3_aggregate_context(C,N)] is
- ** automatically freed on the next call to [sqlite3_reset()]
- ** or [sqlite3_finalize()] for the [prepared statement] containing
- ** the aggregate function associated with context C.
- */
- void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
- /*
- ** CAPI3REF: User Data For Functions {F16240}
- **
- ** The sqlite3_user_data() interface returns a copy of
- ** the pointer that was the pUserData parameter (the 5th parameter)
- ** of the the [sqlite3_create_function()]
- ** and [sqlite3_create_function16()] routines that originally
- ** registered the application defined function. {END}
- **
- ** This routine must be called from the same thread in which
- ** the application-defined function is running.
- **
- ** INVARIANTS:
- **
- ** {F16243} The [sqlite3_user_data(C)] interface returns a copy of the
- ** P pointer from the [sqlite3_create_function(D,X,N,E,P,F,S,L)]
- ** or [sqlite3_create_function16(D,X,N,E,P,F,S,L)] call that
- ** registered the SQL function associated with
- ** [sqlite3_context] C.
- */
- void *sqlite3_user_data(sqlite3_context*);
- /*
- ** CAPI3REF: Database Connection For Functions {F16250}
- **
- ** The sqlite3_context_db_handle() interface returns a copy of
- ** the pointer to the [database connection] (the 1st parameter)
- ** of the the [sqlite3_create_function()]
- ** and [sqlite3_create_function16()] routines that originally
- ** registered the application defined function.
- **
- ** INVARIANTS:
- **
- ** {F16253} The [sqlite3_context_db_handle(C)] interface returns a copy of the
- ** D pointer from the [sqlite3_create_function(D,X,N,E,P,F,S,L)]
- ** or [sqlite3_create_function16(D,X,N,E,P,F,S,L)] call that
- ** registered the SQL function associated with
- ** [sqlite3_context] C.
- */
- sqlite3 *sqlite3_context_db_handle(sqlite3_context*);
- /*
- ** CAPI3REF: Function Auxiliary Data {F16270}
- **
- ** The following two functions may be used by scalar SQL functions to
- ** associate meta-data with argument values. If the same value is passed to
- ** multiple invocations of the same SQL function during query execution, under
- ** some circumstances the associated meta-data may be preserved. This may
- ** be used, for example, to add a regular-expression matching scalar
- ** function. The compiled version of the regular expression is stored as
- ** meta-data associated with the SQL value passed as the regular expression
- ** pattern. The compiled regular expression can be reused on multiple
- ** invocations of the same function so that the original pattern string
- ** does not need to be recompiled on each invocation.
- **
- ** The sqlite3_get_auxdata() interface returns a pointer to the meta-data
- ** associated by the sqlite3_set_auxdata() function with the Nth argument
- ** value to the application-defined function.
- ** If no meta-data has been ever been set for the Nth
- ** argument of the function, or if the cooresponding function parameter
- ** has changed since the meta-data was set, then sqlite3_get_auxdata()
- ** returns a NULL pointer.
- **
- ** The sqlite3_set_auxdata() interface saves the meta-data
- ** pointed to by its 3rd parameter as the meta-data for the N-th
- ** argument of the application-defined function. Subsequent
- ** calls to sqlite3_get_auxdata() might return this data, if it has
- ** not been destroyed.
- ** If it is not NULL, SQLite will invoke the destructor
- ** function given by the 4th parameter to sqlite3_set_auxdata() on
- ** the meta-data when the corresponding function parameter changes
- ** or when the SQL statement completes, whichever comes first.
- **
- ** SQLite is free to call the destructor and drop meta-data on
- ** any parameter of any function at any time. The only guarantee
- ** is that the destructor will be called before the metadata is
- ** dropped.
- **
- ** In practice, meta-data is preserved between function calls for
- ** expressions that are constant at compile time. This includes literal
- ** values and SQL variables.
- **
- ** These routines must be called from the same thread in which
- ** the SQL function is running.
- **
- ** INVARIANTS:
- **
- ** {F16272} The [sqlite3_get_auxdata(C,N)] interface returns a pointer
- ** to metadata associated with the Nth parameter of the SQL function
- ** whose context is C, or NULL if there is no metadata associated
- ** with that parameter.
- **
- ** {F16274} The [sqlite3_set_auxdata(C,N,P,D)] interface assigns a metadata
- ** pointer P to the Nth parameter of the SQL function with context
- ** C.
- **
- ** {F16276} SQLite will invoke the destructor D with a single argument
- ** which is the metadata pointer P following a call to
- ** [sqlite3_set_auxdata(C,N,P,D)] when SQLite ceases to hold
- ** the metadata.
- **
- ** {F16277} SQLite ceases to hold metadata for an SQL function parameter
- ** when the value of that parameter changes.
- **
- ** {F16278} When [sqlite3_set_auxdata(C,N,P,D)] is invoked, the destructor
- ** is called for any prior metadata associated with the same function
- ** context C and parameter N.
- **
- ** {F16279} SQLite will call destructors for any metadata it is holding
- ** in a particular [prepared statement] S when either
- ** [sqlite3_reset(S)] or [sqlite3_finalize(S)] is called.
- */
- void *sqlite3_get_auxdata(sqlite3_context*, int N);
- void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));
- /*
- ** CAPI3REF: Constants Defining Special Destructor Behavior {F10280}
- **
- ** These are special value for the destructor that is passed in as the
- ** final argument to routines like [sqlite3_result_blob()]. If the destructor
- ** argument is SQLITE_STATIC, it means that the content pointer is constant
- ** and will never change. It does not need to be destroyed. The
- ** 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.
- */
- typedef void (*sqlite3_destructor_type)(void*);
- #define SQLITE_STATIC ((sqlite3_destructor_type)0)
- #define SQLITE_TRANSIENT ((sqlite3_destructor_type)-1)
- /*
- ** CAPI3REF: Setting The Result Of An SQL Function {F16400}
- **
- ** These routines are used by the xFunc or xFinal callbacks that
- ** implement SQL functions and aggregates. See
- ** [sqlite3_create_function()] and [sqlite3_create_function16()]
- ** for additional information.
- **
- ** These functions work very much like the
- ** [sqlite3_bind_blob | sqlite3_bind_*] family of functions used
- ** to bind values to host parameters in prepared statements.
- ** Refer to the
- ** [sqlite3_bind_blob | sqlite3_bind_* documentation] for
- ** additional information.
- **
- ** The sqlite3_result_blob() interface sets the result from
- ** an application defined function to be the BLOB whose content is pointed
- ** to by the second parameter and which is N bytes long where N is the
- ** third parameter.
- ** The sqlite3_result_zeroblob() inerfaces set the result of
- ** the application defined function to be a BLOB containing all zero
- ** bytes and N bytes in size, where N is the value of the 2nd parameter.
- **
- ** The sqlite3_result_double() interface sets the result from
- ** an application defined function to be a floating point value specified
- ** by its 2nd argument.
- **
- ** The sqlite3_result_error() and sqlite3_result_error16() functions
- ** cause the implemented SQL function to throw an exception.
- ** SQLite uses the string pointed to by the
- ** 2nd parameter of sqlite3_result_error() or sqlite3_result_error16()
- ** as the text of an error message. SQLite interprets the error
- ** message string from sqlite3_result_error() as UTF8. SQLite
- ** interprets the string from sqlite3_result_error16() as UTF16 in native
- ** byte order. If the third parameter to sqlite3_result_error()
- ** or sqlite3_result_error16() is negative then SQLite takes as the error
- ** message all text up through the first zero character.
- ** If the third parameter to sqlite3_result_error() or
- ** sqlite3_result_error16() is non-negative then SQLite takes that many
- ** bytes (not characters) from the 2nd parameter as the error message.
- ** The sqlite3_result_error() and sqlite3_result_error16()
- ** routines make a copy private copy of the error message text before
- ** they return. Hence, the calling function can deallocate or
- ** modify the text after they return without harm.
- ** The sqlite3_result_error_code() function changes the error code
- ** returned by SQLite as a result of an error in a function. By default,
- ** the error code is SQLITE_ERROR. A subsequent call to sqlite3_result_error()
- ** or sqlite3_result_error16() resets the error code to SQLITE_ERROR.
- **
- ** The sqlite3_result_toobig() interface causes SQLite
- ** to throw an error indicating that a string or BLOB is to long
- ** to represent. The sqlite3_result_nomem() interface
- ** causes SQLite to throw an exception indicating that the a
- ** memory allocation failed.
- **
- ** The sqlite3_result_int() interface sets the return value
- ** of the application-defined function to be the 32-bit signed integer
- ** value given in the 2nd argument.
- ** The sqlite3_result_int64() interface sets the return value
- ** of the application-defined function to be the 64-bit signed integer
- ** value given in the 2nd argument.
- **
- ** The sqlite3_result_null() interface sets the return value
- ** of the application-defined function to be NULL.
- **
- ** The sqlite3_result_text(), sqlite3_result_text16(),
- ** sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces
- ** set the return value of the application-defined function to be
- ** a text string which is represented as UTF-8, UTF-16 native byte order,
- ** UTF-16 little endian, or UTF-16 big endian, respectively.
- ** SQLite takes the text result from the application from
- ** the 2nd parameter of the sqlite3_result_text* interfaces.
- ** If the 3rd parameter to the sqlite3_result_text* interfaces
- ** is negative, then SQLite takes result text from the 2nd parameter
- ** through the first zero character.
- ** If the 3rd parameter to the sqlite3_result_text* interfaces
- ** is non-negative, then as many bytes (not characters) of the text
- ** pointed to by the 2nd parameter are taken as the application-defined
- ** function result.
- ** If the 4th parameter to the sqlite3_result_text* interfaces
- ** or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that
- ** function as the destructor on the text or blob result when it has
- ** finished using that result.
- ** If the 4th parameter to the sqlite3_result_text* interfaces
- ** or sqlite3_result_blob is the special constant SQLITE_STATIC, then
- ** SQLite assumes that the text or blob result is constant space and
- ** does not copy the space or call a destructor when it has
- ** finished using that result.
- ** If the 4th parameter to the sqlite3_result_text* interfaces
- ** or sqlite3_result_blob is the special constant SQLITE_TRANSIENT
- ** then SQLite makes a copy of the result into space obtained from
- ** from [sqlite3_malloc()] before it returns.
- **
- ** The sqlite3_result_value() interface sets the result of
- ** the application-defined function to be a copy the
- ** [unprotected sqlite3_value] object specified by the 2nd parameter. The
- ** sqlite3_result_value() interface makes a copy of the [sqlite3_value]
- ** so that [sqlite3_value] specified in the parameter may change or
- ** be deallocated after sqlite3_result_value() returns without harm.
- ** A [protected sqlite3_value] object may always be used where an
- ** [unprotected sqlite3_value] object is required, so either
- ** kind of [sqlite3_value] object can be used with this interface.
- **
- ** If these routines are called from within the different thread
- ** than the one containing the application-defined function that recieved
- ** the [sqlite3_context] pointer, the results are undefined.
- **
- ** INVARIANTS:
- **
- ** {F16403} The default return value from any SQL function is NULL.
- **
- ** {F16406} The [sqlite3_result_blob(C,V,N,D)] interface changes the
- ** return value of function C to be a blob that is N bytes
- ** in length and with content pointed to by V.
- **
- ** {F16409} The [sqlite3_result_double(C,V)] interface changes the
- ** return value of function C to be the floating point value V.
- **
- ** {F16412} The [sqlite3_result_error(C,V,N)] interface changes the return
- ** value of function C to be an exception with error code
- ** [SQLITE_ERROR] and a UTF8 error message copied from V up to the
- ** first zero byte or until N bytes are read if N is positive.
- **
- ** {F16415} The [sqlite3_result_error16(C,V,N)] interface changes the return
- ** value of function C to be an exception with error code
- ** [SQLITE_ERROR] and a UTF16 native byte order error message
- ** copied from V up to the first zero terminator or until N bytes
- ** are read if N is positive.
- **
- ** {F16418} The [sqlite3_result_error_toobig(C)] interface changes the return
- ** value of the function C to be an exception with error code
- ** [SQLITE_TOOBIG] and an appropriate error message.
- **
- ** {F16421} The [sqlite3_result_error_nomem(C)] interface changes the return
- ** value of the function C to be an exception with error code
- ** [SQLITE_NOMEM] and an appropriate error message.
- **
- ** {F16424} The [sqlite3_result_error_code(C,E)] interface changes the return
- ** value of the function C to be an exception with error code E.
- ** The error message text is unchanged.
- **
- ** {F16427} The [sqlite3_result_int(C,V)] interface changes the
- ** return value of function C to be the 32-bit integer value V.
- **
- ** {F16430} The [sqlite3_result_int64(C,V)] interface changes the
- ** return value of function C to be the 64-bit integer value V.
- **
- ** {F16433} The [sqlite3_result_null(C)] interface changes the
- ** return value of function C to be NULL.
- **
- ** {F16436} The [sqlite3_result_text(C,V,N,D)] interface changes the
- ** return value of function C to be the UTF8 string
- ** V up the first zero if N is negative
- ** or the first N bytes of V if N is non-negative.
- **
- ** {F16439} The [sqlite3_result_text16(C,V,N,D)] interface changes the
- ** return value of function C to be the UTF16 native byte order
- ** string V up to the first zero if N is
- ** negative or the first N bytes of V if N is non-negative.
- **
- ** {F16442} The [sqlite3_result_text16be(C,V,N,D)] interface changes the
- ** return value of function C to be the UTF16 big-endian
- ** string V up to the first zero if N is
- ** is negative or the first N bytes or V if N is non-negative.
- **
- ** {F16445} The [sqlite3_result_text16le(C,V,N,D)] interface changes the
- ** return value of function C to be the UTF16 little-endian
- ** string V up to the first zero if N is
- ** negative or the first N bytes of V if N is non-negative.
- **
- ** {F16448} The [sqlite3_result_value(C,V)] interface changes the
- ** return value of function C to be [unprotected sqlite3_value]
- ** object V.
- **
- ** {F16451} The [sqlite3_result_zeroblob(C,N)] interface changes the
- ** return value of function C to be an N-byte blob of all zeros.
- **
- ** {F16454} The [sqlite3_result_error()] and [sqlite3_result_error16()]
- ** interfaces make a copy of their error message strings before
- ** returning.
- **
- ** {F16457} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)],
- ** [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)],
- ** [sqlite3_result_text16be(C,V,N,D)], or
- ** [sqlite3_result_text16le(C,V,N,D)] is the constant [SQLITE_STATIC]
- ** then no destructor is ever called on the pointer V and SQLite
- ** assumes that V is immutable.
- **
- ** {F16460} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)],
- ** [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)],
- ** [sqlite3_result_text16be(C,V,N,D)], or
- ** [sqlite3_result_text16le(C,V,N,D)] is the constant
- ** [SQLITE_TRANSIENT] then the interfaces makes a copy of the
- ** content of V and retains the copy.
- **
- ** {F16463} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)],
- ** [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)],
- ** [sqlite3_result_text16be(C,V,N,D)], or
- ** [sqlite3_result_text16le(C,V,N,D)] is some value other than
- ** the constants [SQLITE_STATIC] and [SQLITE_TRANSIENT] then
- ** SQLite will invoke the destructor D with V as its only argument
- ** when it has finished with the V value.
- */
- void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
- void sqlite3_result_double(sqlite3_context*, double);
- void sqlite3_result_error(sqlite3_context*, const char*, int);
- void sqlite3_result_error16(sqlite3_context*, const void*, int);
- void sqlite3_result_error_toobig(sqlite3_context*);
- void sqlite3_result_error_nomem(sqlite3_context*);
- void sqlite3_result_error_code(sqlite3_context*, int);
- void sqlite3_result_int(sqlite3_context*, int);
- void sqlite3_result_int64(sqlite3_context*, sqlite3_int64);
- void sqlite3_result_null(sqlite3_context*);
- void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
- void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
- void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
- void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
- void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
- void sqlite3_result_zeroblob(sqlite3_context*, int n);
- /*
- ** CAPI3REF: Define New Collating Sequences {F16600}
- **
- ** These functions are used to add new collation sequences to the
- ** [sqlite3*] handle specified as the first argument.
- **
- ** The name of the new collation sequence is specified as a UTF-8 string
- ** for sqlite3_create_collation() and sqlite3_create_collation_v2()
- ** and a UTF-16 string for sqlite3_create_collation16(). In all cases
- ** the name is passed as the second function argument.
- **
- ** The third argument may be one of the constants [SQLITE_UTF8],
- ** [SQLITE_UTF16LE] or [SQLITE_UTF16BE], indicating that the user-supplied
- ** routine expects to be passed pointers to strings encoded using UTF-8,
- ** UTF-16 little-endian or UTF-16 big-endian respectively. The
- ** third argument might also be [SQLITE_UTF16_ALIGNED] to indicate that
- ** the routine expects pointers to 16-bit word aligned strings
- ** of UTF16 in the native byte order of the host computer.
- **
- ** A pointer to the user supplied routine must be passed as the fifth
- ** argument. If it is NULL, this is the same as deleting the collation
- ** sequence (so that SQLite cannot call it anymore).
- ** Each time the application
- ** supplied function is invoked, it is passed a copy of the void* passed as
- ** the fourth argument to sqlite3_create_collation() or
- ** sqlite3_create_collation16() as its first parameter.
- **
- ** The remaining arguments to the application-supplied routine are two strings,
- ** each represented by a (length, data) pair and encoded in the encoding
- ** that was passed as the third argument when the collation sequence was
- ** registered. {END} The application defined collation routine should
- ** return negative, zero or positive if
- ** the first string is less than, equal to, or greater than the second
- ** string. i.e. (STRING1 - STRING2).
- **
- ** The sqlite3_create_collation_v2() works like sqlite3_create_collation()
- ** excapt that it takes an extra argument which is a destructor for
- ** the collation. The destructor is called when the collation is
- ** destroyed and is passed a copy of the fourth parameter void* pointer
- ** of the sqlite3_create_collation_v2().
- ** Collations are destroyed when
- ** they are overridden by later calls to the collation creation functions
- ** or when the [sqlite3*] database handle is closed using [sqlite3_close()].
- **
- ** INVARIANTS:
- **
- ** {F16603} A successful call to the
- ** [sqlite3_create_collation_v2(B,X,E,P,F,D)] interface
- ** registers function F as the comparison function used to
- ** implement collation X on [database connection] B for
- ** databases having encoding E.
- **
- ** {F16604} SQLite understands the X parameter to
- ** [sqlite3_create_collation_v2(B,X,E,P,F,D)] as a zero-terminated
- ** UTF-8 string in which case is ignored for ASCII characters and
- ** is significant for non-ASCII characters.
- **
- ** {F16606} Successive calls to [sqlite3_create_collation_v2(B,X,E,P,F,D)]
- ** with the same values for B, X, and E, override prior values
- ** of P, F, and D.
- **
- ** {F16609} The destructor D in [sqlite3_create_collation_v2(B,X,E,P,F,D)]
- ** is not NULL then it is called with argument P when the
- ** collating function is dropped by SQLite.
- **
- ** {F16612} A collating function is dropped when it is overloaded.
- **
- ** {F16615} A collating function is dropped when the database connection
- ** is closed using [sqlite3_close()].
- **
- ** {F16618} The pointer P in [sqlite3_create_collation_v2(B,X,E,P,F,D)]
- ** is passed through as the first parameter to the comparison
- ** function F for all subsequent invocations of F.
- **
- ** {F16621} A call to [sqlite3_create_collation(B,X,E,P,F)] is exactly
- ** the same as a call to [sqlite3_create_collation_v2()] with
- ** the same parameters and a NULL destructor.
- **
- ** {F16624} Following a [sqlite3_create_collation_v2(B,X,E,P,F,D)],
- ** SQLite uses the comparison function F for all text comparison
- ** operations on [database connection] B on text values that
- ** use the collating sequence name X.
- **
- ** {F16627} The [sqlite3_create_collation16(B,X,E,P,F)] works the same
- ** as [sqlite3_create_collation(B,X,E,P,F)] except that the
- ** collation name X is understood as UTF-16 in native byte order
- ** instead of UTF-8.
- **
- ** {F16630} When multiple comparison functions are available for the same
- ** collating sequence, SQLite chooses the one whose text encoding
- ** requires the least amount of conversion from the default
- ** text encoding of the database.
- */
- int sqlite3_create_collation(
- sqlite3*,
- const char *zName,
- int eTextRep,
- void*,
- int(*xCompare)(void*,int,const void*,int,const void*)
- );
- int sqlite3_create_collation_v2(
- sqlite3*,
- const char *zName,
- int eTextRep,
- void*,
- int(*xCompare)(void*,int,const void*,int,const void*),
- void(*xDestroy)(void*)
- );
- int sqlite3_create_collation16(
- sqlite3*,
- const char *zName,
- int eTextRep,
- void*,
- int(*xCompare)(void*,int,const void*,int,const void*)
- );
- /*
- ** CAPI3REF: Collation Needed Callbacks {F16700}
- **
- ** To avoid having to register all collation sequences before a database
- ** can be used, a single callback function may be registered with the
- ** database handle to be called whenever an undefined collation sequence is
- ** required.
- **
- ** If the function is registered using the sqlite3_collation_needed() API,
- ** then it is passed the names of undefined collation sequences as strings
- ** encoded in UTF-8. {F16703} If sqlite3_collation_needed16() is used, the names
- ** are passed as UTF-16 in machine native byte order. A call to either
- ** function replaces any existing callback.
- **
- ** When the callback is invoked, the first argument passed is a copy
- ** of the second argument to sqlite3_collation_needed() or
- ** sqlite3_collation_needed16(). The second argument is the database
- ** handle. The third argument is one of [SQLITE_UTF8],
- ** [SQLITE_UTF16BE], or [SQLITE_UTF16LE], indicating the most
- ** desirable form of the collation sequence function required.
- ** The fourth parameter is the name of the
- ** required collation sequence.
- **
- ** The callback function should register the desired collation using
- ** [sqlite3_create_collation()], [sqlite3_create_collation16()], or
- ** [sqlite3_create_collation_v2()].
- **
- ** INVARIANTS:
- **
- ** {F16702} A successful call to [sqlite3_collation_needed(D,P,F)]
- ** or [sqlite3_collation_needed16(D,P,F)] causes
- ** the [database connection] D to invoke callback F with first
- ** parameter P whenever it needs a comparison function for a
- ** collating sequence that it does not know about.
- **
- ** {F16704} Each successful call to [sqlite3_collation_needed()] or
- ** [sqlite3_collation_needed16()] overrides the callback registered
- ** on the same [database connection] by prior calls to either
- ** interface.
- **
- ** {F16706} The name of the requested collating function passed in the
- ** 4th parameter to the callback is in UTF-8 if the callback
- ** was registered using [sqlite3_collation_needed()] and
- ** is in UTF-16 native byte order if the callback was
- ** registered using [sqlite3_collation_needed16()].
- **
- **
- */
- int sqlite3_collation_needed(
- sqlite3*,
- void*,
- void(*)(void*,sqlite3*,int eTextRep,const char*)
- );
- int sqlite3_collation_needed16(
- sqlite3*,
- void*,
- void(*)(void*,sqlite3*,int eTextRep,const void*)
- );
- /*
- ** Specify the key for an encrypted database. This routine should be
- ** called right after sqlite3_open().
- **
- ** The code to implement this API is not available in the public release
- ** of SQLite.
- */
- int sqlite3_key(
- sqlite3 *db, /* Database to be rekeyed */
- const void *pKey, int nKey /* The key */
- );
- /*
- ** Change the key on an open database. If the current database is not
- ** encrypted, this routine will encrypt it. If pNew==0 or nNew==0, the
- ** database is decrypted.
- **
- ** The code to implement this API is not available in the public release
- ** of SQLite.
- */
- int sqlite3_rekey(
- sqlite3 *db, /* Database to be rekeyed */
- const void *pKey, int nKey /* The new key */
- );
- /*
- ** CAPI3REF: Suspend Execution For A Short Time {F10530}
- **
- ** The sqlite3_sleep() function
- ** causes the current thread to suspend execution
- ** for at least a number of milliseconds specified in its parameter.
- **
- ** If the operating system does not support sleep requests with
- ** millisecond time resolution, then the time will be rounded up to
- ** the nearest second. The number of milliseconds of sleep actually
- ** requested from the operating system is returned.
- **
- ** SQLite implements this interface by calling the xSleep()
- ** method of the default [sqlite3_vfs] object.
- **
- ** INVARIANTS:
- **
- ** {F10533} The [sqlite3_sleep(M)] interface invokes the xSleep
- ** method of the default [sqlite3_vfs|VFS] in order to
- ** suspend execution of the current thread for at least
- ** M milliseconds.
- **
- ** {F10536} The [sqlite3_sleep(M)] interface returns the number of
- ** milliseconds of sleep actually requested of the operating
- ** system, which might be larger than the parameter M.
- */
- int sqlite3_sleep(int);
- /*
- ** CAPI3REF: Name Of The Folder Holding Temporary Files {F10310}
- **
- ** If this global variable is made to point to a string which is
- ** the name of a folder (a.ka. directory), then all temporary files
- ** created by SQLite will be placed in that directory. If this variable
- ** is NULL pointer, then SQLite does a search for an appropriate temporary
- ** file directory.
- **
- ** It is not safe to modify this variable once a database connection
- ** has been opened. It is intended that this variable be set once
- ** as part of process initialization and before any SQLite interface
- ** routines have been call and remain unchanged thereafter.
- */
- SQLITE_EXTERN char *sqlite3_temp_directory;
- /*
- ** CAPI3REF: Test To See If The Database Is In Auto-Commit Mode {F12930}
- **
- ** The sqlite3_get_autocommit() interfaces returns non-zero or
- ** zero if the given database connection is or is not in autocommit mode,
- ** respectively. Autocommit mode is on
- ** by default. Autocommit mode is disabled by a [BEGIN] statement.
- ** Autocommit mode is reenabled by a [COMMIT] or [ROLLBACK].
- **
- ** If certain kinds of errors occur on a statement within a multi-statement
- ** transactions (errors including [SQLITE_FULL], [SQLITE_IOERR],
- ** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the
- ** transaction might be rolled back automatically. The only way to
- ** find out if SQLite automatically rolled back the transaction after
- ** an error is to use this function.
- **
- ** INVARIANTS:
- **
- ** {F12931} The [sqlite3_get_autocommit(D)] interface returns non-zero or
- ** zero if the [database connection] D is or is not in autocommit
- ** mode, respectively.
- **
- ** {F12932} Autocommit mode is on by default.
- **
- ** {F12933} Autocommit mode is disabled by a successful [BEGIN] statement.
- **
- ** {F12934} Autocommit mode is enabled by a successful [COMMIT] or [ROLLBACK]
- ** statement.
- **
- **
- ** LIMITATIONS:
- ***
- ** {U12936} If another thread changes the autocommit status of the database
- ** connection while this routine is running, then the return value
- ** is undefined.
- */
- int sqlite3_get_autocommit(sqlite3*);
- /*
- ** CAPI3REF: Find The Database Handle Of A Prepared Statement {F13120}
- **
- ** The sqlite3_db_handle interface
- ** returns the [sqlite3*] database handle to which a
- ** [prepared statement] belongs.
- ** The database handle returned by sqlite3_db_handle
- ** is the same database handle that was
- ** the first argument to the [sqlite3_prepare_v2()] or its variants
- ** that was used to create the statement in the first place.
- **
- ** INVARIANTS:
- **
- ** {F13123} The [sqlite3_db_handle(S)] interface returns a pointer
- ** to the [database connection] associated with
- ** [prepared statement] S.
- */
- sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
- /*
- ** CAPI3REF: Commit And Rollback Notification Callbacks {F12950}
- **
- ** The sqlite3_commit_hook() interface registers a callback
- ** function to be invoked whenever a transaction is committed.
- ** Any callback set by a previous call to sqlite3_commit_hook()
- ** for the same database connection is overridden.
- ** The sqlite3_rollback_hook() interface registers a callback
- ** function to be invoked whenever a transaction is committed.
- ** Any callback set by a previous call to sqlite3_commit_hook()
- ** for the same database connection is overridden.
- ** The pArg argument is passed through
- ** to the callback. If the callback on a commit hook function
- ** returns non-zero, then the commit is converted into a rollback.
- **
- ** If another function was previously registered, its
- ** pArg value is returned. Otherwise NULL is returned.
- **
- ** Registering a NULL function disables the callback.
- **
- ** For the purposes of this API, a transaction is said to have been
- ** rolled back if an explicit "ROLLBACK" statement is executed, or
- ** an error or constraint causes an implicit rollback to occur.
- ** The rollback callback is not invoked if a transaction is
- ** automatically rolled back because the database connection is closed.
- ** The rollback callback is not invoked if a transaction is
- ** rolled back because a commit callback returned non-zero.
- ** <todo> Check on this </todo>
- **
- ** These are experimental interfaces and are subject to change.
- **
- ** INVARIANTS:
- **
- ** {F12951} The [sqlite3_commit_hook(D,F,P)] interface registers the
- ** callback function F to be invoked with argument P whenever
- ** a transaction commits on [database connection] D.
- **
- ** {F12952} The [sqlite3_commit_hook(D,F,P)] interface returns the P
- ** argument from the previous call with the same
- ** [database connection ] D , or NULL on the first call
- ** for a particular [database connection] D.
- **
- ** {F12953} Each call to [sqlite3_commit_hook()] overwrites the callback
- ** registered by prior calls.
- **
- ** {F12954} If the F argument to [sqlite3_commit_hook(D,F,P)] is NULL
- ** then the commit hook callback is cancelled and no callback
- ** is invoked when a transaction commits.
- **
- ** {F12955} If the commit callback returns non-zero then the commit is
- ** converted into a rollback.
- **
- ** {F12961} The [sqlite3_rollback_hook(D,F,P)] interface registers the
- ** callback function F to be invoked with argument P whenever
- ** a transaction rolls back on [database connection] D.
- **
- ** {F12962} The [sqlite3_rollback_hook(D,F,P)] interface returns the P
- ** argument from the previous call with the same
- ** [database connection ] D , or NULL on the first call
- ** for a particular [database connection] D.
- **
- ** {F12963} Each call to [sqlite3_rollback_hook()] overwrites the callback
- ** registered by prior calls.
- **
- ** {F12964} If the F argument to [sqlite3_rollback_hook(D,F,P)] is NULL
- ** then the rollback hook callback is cancelled and no callback
- ** is invoked when a transaction rolls back.
- */
- void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
- void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
- /*
- ** CAPI3REF: Data Change Notification Callbacks {F12970}
- **
- ** The sqlite3_update_hook() interface
- ** registers a callback function with the database connection identified by the
- ** first argument to be invoked whenever a row is updated, inserted or deleted.
- ** Any callback set by a previous call to this function for the same
- ** database connection is overridden.
- **
- ** The second argument is a pointer to the function to invoke when a
- ** row is updated, inserted or deleted.
- ** The first argument to the callback is
- ** a copy of the third argument to sqlite3_update_hook().
- ** The second callback
- ** argument is one of [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE],
- ** depending on the operation that caused the callback to be invoked.
- ** The third and
- ** fourth arguments to the callback contain pointers to the database and
- ** table name containing the affected row.
- ** The final callback parameter is
- ** the rowid of the row.
- ** In the case of an update, this is the rowid after
- ** the update takes place.
- **
- ** The update hook is not invoked when internal system tables are
- ** modified (i.e. sqlite_master and sqlite_sequence).
- **
- ** If another function was previously registered, its pArg value
- ** is returned. Otherwise NULL is returned.
- **
- ** INVARIANTS:
- **
- ** {F12971} The [sqlite3_update_hook(D,F,P)] interface causes callback
- ** function F to be invoked with first parameter P whenever
- ** a table row is modified, inserted, or deleted on
- ** [database connection] D.
- **
- ** {F12973} The [sqlite3_update_hook(D,F,P)] interface returns the value
- ** of P for the previous call on the same [database connection] D,
- ** or NULL for the first call.
- **
- ** {F12975} If the update hook callback F in [sqlite3_update_hook(D,F,P)]
- ** is NULL then the no update callbacks are made.
- **
- ** {F12977} Each call to [sqlite3_update_hook(D,F,P)] overrides prior calls
- ** to the same interface on the same [database connection] D.
- **
- ** {F12979} The update hook callback is not invoked when internal system
- ** tables such as sqlite_master and sqlite_sequence are modified.
- **
- ** {F12981} The second parameter to the update callback
- ** is one of [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE],
- ** depending on the operation that caused the callback to be invoked.
- **
- ** {F12983} The third and fourth arguments to the callback contain pointers
- ** to zero-terminated UTF-8 strings which are the names of the
- ** database and table that is being updated.
- ** {F12985} The final callback parameter is the rowid of the row after
- ** the change occurs.
- */
- void *sqlite3_update_hook(
- sqlite3*,
- void(*)(void *,int ,char const *,char const *,sqlite3_int64),
- void*
- );
- /*
- ** CAPI3REF: Enable Or Disable Shared Pager Cache {F10330}
- **
- ** This routine enables or disables the sharing of the database cache
- ** and schema data structures between connections to the same database.
- ** Sharing is enabled if the argument is true and disabled if the argument
- ** is false.
- **
- ** Cache sharing is enabled and disabled
- ** for an entire process. {END} This is a change as of SQLite version 3.5.0.
- ** In prior versions of SQLite, sharing was
- ** enabled or disabled for each thread separately.
- **
- ** The cache sharing mode set by this interface effects all subsequent
- ** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()].
- ** Existing database connections continue use the sharing mode
- ** that was in effect at the time they were opened.
- **
- ** Virtual tables cannot be used with a shared cache. When shared
- ** cache is enabled, the [sqlite3_create_module()] API used to register
- ** virtual tables will always return an error.
- **
- ** This routine returns [SQLITE_OK] if shared cache was
- ** enabled or disabled successfully. An [error code]
- ** is returned otherwise.
- **
- ** Shared cache is disabled by default. But this might change in
- ** future releases of SQLite. Applications that care about shared
- ** cache setting should set it explicitly.
- **
- ** INVARIANTS:
- **
- ** {F10331} A successful invocation of [sqlite3_enable_shared_cache(B)]
- ** will enable or disable shared cache mode for any subsequently
- ** created [database connection] in the same process.
- **
- ** {F10336} When shared cache is enabled, the [sqlite3_create_module()]
- ** interface will always return an error.
- **
- ** {F10337} The [sqlite3_enable_shared_cache(B)] interface returns
- ** [SQLITE_OK] if shared cache was enabled or disabled successfully.
- **
- ** {F10339} Shared cache is disabled by default.
- */
- int sqlite3_enable_shared_cache(int);
- /*
- ** CAPI3REF: Attempt To Free Heap Memory {F17340}
- **
- ** The sqlite3_release_memory() interface attempts to
- ** free N bytes of heap memory by deallocating non-essential memory
- ** allocations held by the database labrary. {END} Memory used
- ** to cache database pages to improve performance is an example of
- ** non-essential memory. Sqlite3_release_memory() returns
- ** the number of bytes actually freed, which might be more or less
- ** than the amount requested.
- **
- ** INVARIANTS:
- **
- ** {F17341} The [sqlite3_release_memory(N)] interface attempts to
- ** free N bytes of heap memory by deallocating non-essential
- ** memory allocations held by the database labrary.
- **
- ** {F16342} The [sqlite3_release_memory(N)] returns the number
- ** of bytes actually freed, which might be more or less
- ** than the amount requested.
- */
- int sqlite3_release_memory(int);
- /*
- ** CAPI3REF: Impose A Limit On Heap Size {F17350}
- **
- ** The sqlite3_soft_heap_limit() interface
- ** places a "soft" limit on the amount of heap memory that may be allocated
- ** by SQLite. If an internal allocation is requested
- ** that would exceed the soft heap limit, [sqlite3_release_memory()] is
- ** invoked one or more times to free up some space before the allocation
- ** is made.
- **
- ** The limit is called "soft", because if
- ** [sqlite3_release_memory()] cannot
- ** free sufficient memory to prevent the limit from being exceeded,
- ** the memory is allocated anyway and the current operation proceeds.
- **
- ** A negative or zero value for N means that there is no soft heap limit and
- ** [sqlite3_release_memory()] will only be called when memory is exhausted.
- ** The default value for the soft heap limit is zero.
- **
- ** SQLite makes a best effort to honor the soft heap limit.
- ** But if the soft heap limit cannot honored, execution will
- ** continue without error or notification. This is why the limit is
- ** called a "soft" limit. It is advisory only.
- **
- ** Prior to SQLite version 3.5.0, this routine only constrained the memory
- ** allocated by a single thread - the same thread in which this routine
- ** runs. Beginning with SQLite version 3.5.0, the soft heap limit is
- ** applied to all threads. The value specified for the soft heap limit
- ** is an upper bound on the total memory allocation for all threads. In
- ** version 3.5.0 there is no mechanism for limiting the heap usage for
- ** individual threads.
- **
- ** INVARIANTS:
- **
- ** {F16351} The [sqlite3_soft_heap_limit(N)] interface places a soft limit
- ** of N bytes on the amount of heap memory that may be allocated
- ** using [sqlite3_malloc()] or [sqlite3_realloc()] at any point
- ** in time.
- **
- ** {F16352} If a call to [sqlite3_malloc()] or [sqlite3_realloc()] would
- ** cause the total amount of allocated memory to exceed the
- ** soft heap limit, then [sqlite3_release_memory()] is invoked
- ** in an attempt to reduce the memory usage prior to proceeding
- ** with the memory allocation attempt.
- **
- ** {F16353} Calls to [sqlite3_malloc()] or [sqlite3_realloc()] that trigger
- ** attempts to reduce memory usage through the soft heap limit
- ** mechanism continue even if the attempt to reduce memory
- ** usage is unsuccessful.
- **
- ** {F16354} A negative or zero value for N in a call to
- ** [sqlite3_soft_heap_limit(N)] means that there is no soft
- ** heap limit and [sqlite3_release_memory()] will only be
- ** called when memory is completely exhausted.
- **
- ** {F16355} The default value for the soft heap limit is zero.
- **
- ** {F16358} Each call to [sqlite3_soft_heap_limit(N)] overrides the
- ** values set by all prior calls.
- */
- void sqlite3_soft_heap_limit(int);
- /*
- ** CAPI3REF: Extract Metadata About A Column Of A Table {F12850}
- **
- ** This routine
- ** returns meta-data about a specific column of a specific database
- ** table accessible using the connection handle passed as the first function
- ** argument.
- **
- ** The column is identified by the second, third and fourth parameters to
- ** this function. The second parameter is either the name of the database
- ** (i.e. "main", "temp" or an attached database) containing the specified
- ** table or NULL. If it is NULL, then all attached databases are searched
- ** for the table using the same algorithm as the database engine uses to
- ** resolve unqualified table references.
- **
- ** The third and fourth parameters to this function are the table and column
- ** name of the desired column, respectively. Neither of these parameters
- ** may be NULL.
- **
- ** Meta information is returned by writing to the memory locations passed as
- ** the 5th and subsequent parameters to this function. Any of these
- ** arguments may be NULL, in which case the corresponding element of meta
- ** information is ommitted.
- **
- ** <pre>
- ** Parameter Output Type Description
- ** -----------------------------------
- **
- ** 5th const char* Data type
- ** 6th const char* Name of the default collation sequence
- ** 7th int True if the column has a NOT NULL constraint
- ** 8th int True if the column is part of the PRIMARY KEY
- ** 9th int True if the column is AUTOINCREMENT
- ** </pre>
- **
- **
- ** The memory pointed to by the character pointers returned for the
- ** declaration type and collation sequence is valid only until the next
- ** call to any sqlite API function.
- **
- ** If the specified table is actually a view, then an error is returned.
- **
- ** If the specified column is "rowid", "oid" or "_rowid_" and an
- ** INTEGER PRIMARY KEY column has been explicitly declared, then the output
- ** parameters are set for the explicitly declared column. If there is no
- ** explicitly declared IPK column, then the output parameters are set as
- ** follows:
- **
- ** <pre>
- ** data type: "INTEGER"
- ** collation sequence: "BINARY"
- ** not null: 0
- ** primary key: 1
- ** auto increment: 0
- ** </pre>
- **
- ** This function may load one or more schemas from database files. If an
- ** error occurs during this process, or if the requested table or column
- ** cannot be found, an SQLITE error code is returned and an error message
- ** left in the database handle (to be retrieved using sqlite3_errmsg()).
- **
- ** This API is only available if the library was compiled with the
- ** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined.
- */
- int sqlite3_table_column_metadata(
- sqlite3 *db, /* Connection handle */
- const char *zDbName, /* Database name or NULL */
- const char *zTableName, /* Table name */
- const char *zColumnName, /* Column name */
- char const **pzDataType, /* OUTPUT: Declared data type */
- char const **pzCollSeq, /* OUTPUT: Collation sequence name */
- int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */
- int *pPrimaryKey, /* OUTPUT: True if column part of PK */
- int *pAutoinc /* OUTPUT: True if column is auto-increment */
- );
- /*
- ** CAPI3REF: Load An Extension {F12600}
- **
- ** {F12601} The sqlite3_load_extension() interface
- ** attempts to load an SQLite extension library contained in the file
- ** zFile. {F12602} The entry point is zProc. {F12603} zProc may be 0
- ** in which case the name of the entry point defaults
- ** to "sqlite3_extension_init".
- **
- ** {F12604} The sqlite3_load_extension() interface shall
- ** return [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong.
- **
- ** {F12605}
- ** If an error occurs and pzErrMsg is not 0, then the
- ** sqlite3_load_extension() interface shall attempt to fill *pzErrMsg with
- ** error message text stored in memory obtained from [sqlite3_malloc()].
- ** {END} The calling function should free this memory
- ** by calling [sqlite3_free()].
- **
- ** {F12606}
- ** Extension loading must be enabled using [sqlite3_enable_load_extension()]
- ** prior to calling this API or an error will be returned.
- */
- int sqlite3_load_extension(
- sqlite3 *db, /* Load the extension into this database connection */
- const char *zFile, /* Name of the shared library containing extension */
- const char *zProc, /* Entry point. Derived from zFile if 0 */
- char **pzErrMsg /* Put error message here if not 0 */
- );
- /*
- ** CAPI3REF: Enable Or Disable Extension Loading {F12620}
- **
- ** So as not to open security holes in older applications that are
- ** unprepared to deal with extension loading, and as a means of disabling
- ** extension loading while evaluating user-entered SQL, the following
- ** API is provided to turn the [sqlite3_load_extension()] mechanism on and
- ** off. {F12622} It is off by default. {END} See ticket #1863.
- **
- ** {F12621} Call the sqlite3_enable_load_extension() routine
- ** with onoff==1 to turn extension loading on
- ** and call it with onoff==0 to turn it back off again. {END}
- */
- int sqlite3_enable_load_extension(sqlite3 *db, int onoff);
- /*
- ** CAPI3REF: Make Arrangements To Automatically Load An Extension {F12640}
- **
- ** {F12641} This function
- ** registers an extension entry point that is automatically invoked
- ** whenever a new database connection is opened using
- ** [sqlite3_open()], [sqlite3_open16()], or [sqlite3_open_v2()]. {END}
- **
- ** 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.
- **
- ** {F12642} Duplicate extensions are detected so calling this routine multiple
- ** times with the same extension is harmless.
- **
- ** {F12643} This routine stores a pointer to the extension in an array
- ** that is obtained from sqlite_malloc(). {END} If you run a memory leak
- ** checker on your program and it reports a leak because of this
- ** array, then invoke [sqlite3_reset_auto_extension()] prior
- ** to shutdown to free the memory.
- **
- ** {F12644} Automatic extensions apply across all threads. {END}
- **
- ** This interface is experimental and is subject to change or
- ** removal in future releases of SQLite.
- */
- int sqlite3_auto_extension(void *xEntryPoint);
- /*
- ** CAPI3REF: Reset Automatic Extension Loading {F12660}
- **
- ** {F12661} This function disables all previously registered
- ** automatic extensions. {END} This
- ** routine undoes the effect of all prior [sqlite3_auto_extension()]
- ** calls.
- **
- ** {F12662} This call disabled automatic extensions in all threads. {END}
- **
- ** This interface is experimental and is subject to change or
- ** removal in future releases of SQLite.
- */
- 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.
- **
- ** When the virtual-table mechanism stablizes, we will declare the
- ** interface fixed, support it indefinitely, and remove this comment.
- */
- /*
- ** Structures used by the virtual table interface
- */
- typedef struct sqlite3_vtab sqlite3_vtab;
- typedef struct sqlite3_index_info sqlite3_index_info;
- typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor;
- typedef struct sqlite3_module sqlite3_module;
- /*
- ** CAPI3REF: Virtual Table Object {F18000}
- ** KEYWORDS: sqlite3_module
- **
- ** A module is a class of virtual tables. Each module is defined
- ** by an instance of the following structure. This structure consists
- ** mostly of methods for the module.
- */
- struct sqlite3_module {
- int iVersion;
- int (*xCreate)(sqlite3*, void *pAux,
- int argc, const char *const*argv,
- sqlite3_vtab **ppVTab, char**);
- int (*xConnect)(sqlite3*, void *pAux,
- 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);
- int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor);
- int (*xClose)(sqlite3_vtab_cursor*);
- int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr,
- int argc, sqlite3_value **argv);
- int (*xNext)(sqlite3_vtab_cursor*);
- int (*xEof)(sqlite3_vtab_cursor*);
- int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int);
- int (*xRowid)(sqlite3_vtab_cursor*, sqlite3_int64 *pRowid);
- int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite3_int64 *);
- int (*xBegin)(sqlite3_vtab *pVTab);
- int (*xSync)(sqlite3_vtab *pVTab);
- int (*xCommit)(sqlite3_vtab *pVTab);
- int (*xRollback)(sqlite3_vtab *pVTab);
- int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName,
- void (**pxFunc)(sqlite3_context*,int,sqlite3_value**),
- void **ppArg);
- int (*xRename)(sqlite3_vtab *pVtab, const char *zNew);
- };
- /*
- ** CAPI3REF: Virtual Table Indexing Information {F18100}
- ** KEYWORDS: sqlite3_index_info
- **
- ** The sqlite3_index_info structure and its substructures is used to
- ** pass information into and receive the reply from the xBestIndex
- ** method of an sqlite3_module. The fields under **Inputs** are the
- ** inputs to xBestIndex and are read-only. xBestIndex inserts its
- ** results into the **Outputs** fields.
- **
- ** The aConstraint[] array records WHERE clause constraints of the
- ** form:
- **
- ** column OP expr
- **
- ** Where OP is =, <, <=, >, or >=.
- ** The particular operator is stored
- ** in aConstraint[].op. The index of the column is stored in
- ** aConstraint[].iColumn. aConstraint[].usable is TRUE if the
- ** expr on the right-hand side can be evaluated (and thus the constraint
- ** is usable) and false if it cannot.
- **
- ** The optimizer automatically inverts terms of the form "expr OP column"
- ** and makes other simplifications to the WHERE clause in an attempt to
- ** get as many WHERE clause terms into the form shown above as possible.
- ** The aConstraint[] array only reports WHERE clause terms in the correct
- ** form that refer to the particular virtual table being queried.
- **
- ** Information about the ORDER BY clause is stored in aOrderBy[].
- ** Each term of aOrderBy records a column of the ORDER BY clause.
- **
- ** The xBestIndex method must fill aConstraintUsage[] with information
- ** about what parameters to pass to xFilter. If argvIndex>0 then
- ** the right-hand side of the corresponding aConstraint[] is evaluated
- ** and becomes the argvIndex-th entry in argv. If aConstraintUsage[].omit
- ** is true, then the constraint is assumed to be fully handled by the
- ** virtual table and is not checked again by SQLite.
- **
- ** The idxNum and idxPtr values are recorded and passed into xFilter.
- ** sqlite3_free() is used to free idxPtr if needToFreeIdxPtr is true.
- **
- ** The orderByConsumed means that output from xFilter will occur in
- ** the correct order to satisfy the ORDER BY clause so that no separate
- ** sorting step is required.
- **
- ** The estimatedCost value is an estimate of the cost of doing the
- ** particular lookup. A full scan of a table with N entries should have
- ** a cost of N. A binary search of a table of N entries should have a
- ** cost of approximately log(N).
- */
- struct sqlite3_index_info {
- /* Inputs */
- int nConstraint; /* Number of entries in aConstraint */
- struct sqlite3_index_constraint {
- int iColumn; /* Column on left-hand side of constraint */
- unsigned char op; /* Constraint operator */
- unsigned char usable; /* True if this constraint is usable */
- int iTermOffset; /* Used internally - xBestIndex should ignore */
- } *aConstraint; /* Table of WHERE clause constraints */
- int nOrderBy; /* Number of terms in the ORDER BY clause */
- struct sqlite3_index_orderby {
- int iColumn; /* Column number */
- unsigned char desc; /* True for DESC. False for ASC. */
- } *aOrderBy; /* The ORDER BY clause */
- /* Outputs */
- struct sqlite3_index_constraint_usage {
- int argvIndex; /* if >0, constraint is part of argv to xFilter */
- unsigned char omit; /* Do not code a test for this constraint */
- } *aConstraintUsage;
- int idxNum; /* Number used to identify the index */
- char *idxStr; /* String, possibly obtained from sqlite3_malloc */
- int needToFreeIdxStr; /* Free idxStr using sqlite3_free() if true */
- int orderByConsumed; /* True if output is already ordered */
- double estimatedCost; /* Estimated cost of using this index */
- };
- #define SQLITE_INDEX_CONSTRAINT_EQ 2
- #define SQLITE_INDEX_CONSTRAINT_GT 4
- #define SQLITE_INDEX_CONSTRAINT_LE 8
- #define SQLITE_INDEX_CONSTRAINT_LT 16
- #define SQLITE_INDEX_CONSTRAINT_GE 32
- #define SQLITE_INDEX_CONSTRAINT_MATCH 64
- /*
- ** CAPI3REF: Register A Virtual Table Implementation {F18200}
- **
- ** This routine is used to register a new module name with an SQLite
- ** connection. Module names must be registered before creating new
- ** virtual tables on the module, or before using preexisting virtual
- ** tables of the module.
- */
- int sqlite3_create_module(
- sqlite3 *db, /* SQLite connection to register module with */
- const char *zName, /* Name of the module */
- const sqlite3_module *, /* Methods for the module */
- void * /* Client data for xCreate/xConnect */
- );
- /*
- ** CAPI3REF: Register A Virtual Table Implementation {F18210}
- **
- ** This routine is identical to the sqlite3_create_module() method above,
- ** except that it allows a destructor function to be specified. It is
- ** even more experimental than the rest of the virtual tables API.
- */
- int sqlite3_create_module_v2(
- sqlite3 *db, /* SQLite connection to register module with */
- const char *zName, /* Name of the module */
- const sqlite3_module *, /* Methods for the module */
- void *, /* Client data for xCreate/xConnect */
- void(*xDestroy)(void*) /* Module destructor function */
- );
- /*
- ** CAPI3REF: Virtual Table Instance Object {F18010}
- ** KEYWORDS: sqlite3_vtab
- **
- ** Every module implementation uses a subclass of the following structure
- ** to describe a particular instance of the module. Each subclass will
- ** be tailored 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 */
- };
- /*
- ** CAPI3REF: Virtual Table Cursor Object {F18020}
- ** KEYWORDS: sqlite3_vtab_cursor
- **
- ** Every module implementation uses a subclass of the following structure
- ** to describe cursors that point into the virtual table and are used
- ** to loop through the virtual table. Cursors are created using the
- ** xOpen method of the module. Each module implementation will define
- ** the content of a cursor structure to suit its own needs.
- **
- ** This superclass exists in order to define fields of the cursor that
- ** are common to all implementations.
- */
- struct sqlite3_vtab_cursor {
- sqlite3_vtab *pVtab; /* Virtual table of this cursor */
- /* Virtual table implementations will typically add additional fields */
- };
- /*
- ** CAPI3REF: Declare The Schema Of A Virtual Table {F18280}
- **
- ** The xCreate and xConnect methods of a module use the following API
- ** to declare the format (the names and datatypes of the columns) of
- ** the virtual tables they implement.
- */
- int sqlite3_declare_vtab(sqlite3*, const char *zCreateTable);
- /*
- ** CAPI3REF: Overload A Function For A Virtual Table {F18300}
- **
- ** 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.
- ** If this is a problem for you, do not use the interface at this time.
- **
- ** When the virtual-table mechanism stabilizes, we will declare the
- ** interface fixed, support it indefinitely, and remove this comment.
- **
- ****** EXPERIMENTAL - subject to change without notice **************
- */
- /*
- ** CAPI3REF: A Handle To An Open BLOB {F17800}
- **
- ** An instance of this object represents an open BLOB on which
- ** incremental I/O can be preformed.
- ** Objects of this type are created by
- ** [sqlite3_blob_open()] and destroyed by [sqlite3_blob_close()].
- ** The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces
- ** can be used to read or write small subsections of the blob.
- ** The [sqlite3_blob_bytes()] interface returns the size of the
- ** blob in bytes.
- */
- typedef struct sqlite3_blob sqlite3_blob;
- /*
- ** CAPI3REF: Open A BLOB For Incremental I/O {F17810}
- **
- ** This interfaces opens a handle to the blob located
- ** in row iRow, column zColumn, table zTable in database zDb;
- ** in other words, the same blob that would be selected by:
- **
- ** <pre>
- ** SELECT zColumn FROM zDb.zTable WHERE rowid = iRow;
- ** </pre> {END}
- **
- ** If the flags parameter is non-zero, the blob is opened for
- ** read and write access. If it is zero, the blob is opened for read
- ** access.
- **
- ** Note that the database name is not the filename that contains
- ** the database but rather the symbolic name of the database that
- ** is assigned when the database is connected using [ATTACH].
- ** For the main database file, the database name is "main". For
- ** TEMP tables, the database name is "temp".
- **
- ** On success, [SQLITE_OK] is returned and the new
- ** [sqlite3_blob | blob handle] is written to *ppBlob.
- ** Otherwise an error code is returned and
- ** any value written to *ppBlob should not be used by the caller.
- ** This function sets the database-handle error code and message
- ** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()].
- **
- ** INVARIANTS:
- **
- ** {F17813} A successful invocation of the [sqlite3_blob_open(D,B,T,C,R,F,P)]
- ** interface opens an [sqlite3_blob] object P on the blob
- ** in column C of table T in database B on [database connection] D.
- **
- ** {F17814} A successful invocation of [sqlite3_blob_open(D,...)] starts
- ** a new transaction on [database connection] D if that connection
- ** is not already in a transaction.
- **
- ** {F17816} The [sqlite3_blob_open(D,B,T,C,R,F,P)] interface opens the blob
- ** for read and write access if and only if the F parameter
- ** is non-zero.
- **
- ** {F17819} The [sqlite3_blob_open()] interface returns [SQLITE_OK] on
- ** success and an appropriate [error code] on failure.
- **
- ** {F17821} If an error occurs during evaluation of [sqlite3_blob_open(D,...)]
- ** then subsequent calls to [sqlite3_errcode(D)],
- ** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] will return
- ** information approprate for that error.
- */
- int sqlite3_blob_open(
- sqlite3*,
- const char *zDb,
- const char *zTable,
- const char *zColumn,
- sqlite3_int64 iRow,
- int flags,
- sqlite3_blob **ppBlob
- );
- /*
- ** CAPI3REF: Close A BLOB Handle {F17830}
- **
- ** Close an open [sqlite3_blob | blob handle].
- **
- ** Closing a BLOB shall cause the current transaction to commit
- ** if there are no other BLOBs, no pending prepared statements, and the
- ** database connection is in autocommit mode.
- ** If any writes were made to the BLOB, they might be held in cache
- ** until the close operation if they will fit. {END}
- ** Closing the BLOB often forces the changes
- ** out to disk and so if any I/O errors occur, they will likely occur
- ** at the time when the BLOB is closed. {F17833} Any errors that occur during
- ** closing are reported as a non-zero return value.
- **
- ** The BLOB is closed unconditionally. Even if this routine returns
- ** an error code, the BLOB is still closed.
- **
- ** INVARIANTS:
- **
- ** {F17833} The [sqlite3_blob_close(P)] interface closes an
- ** [sqlite3_blob] object P previously opened using
- ** [sqlite3_blob_open()].
- **
- ** {F17836} Closing an [sqlite3_blob] object using
- ** [sqlite3_blob_close()] shall cause the current transaction to
- ** commit if there are no other open [sqlite3_blob] objects
- ** or [prepared statements] on the same [database connection] and
- ** the [database connection] is in
- ** [sqlite3_get_autocommit | autocommit mode].
- **
- ** {F17839} The [sqlite3_blob_close(P)] interfaces closes the
- ** [sqlite3_blob] object P unconditionally, even if
- ** [sqlite3_blob_close(P)] returns something other than [SQLITE_OK].
- **
- */
- int sqlite3_blob_close(sqlite3_blob *);
- /*
- ** CAPI3REF: Return The Size Of An Open BLOB {F17840}
- **
- ** Return the size in bytes of the blob accessible via the open
- ** [sqlite3_blob] object in its only argument.
- **
- ** INVARIANTS:
- **
- ** {F17843} The [sqlite3_blob_bytes(P)] interface returns the size
- ** in bytes of the BLOB that the [sqlite3_blob] object P
- ** refers to.
- */
- int sqlite3_blob_bytes(sqlite3_blob *);
- /*
- ** CAPI3REF: Read Data From A BLOB Incrementally {F17850}
- **
- ** This function is used to read data from an open
- ** [sqlite3_blob | blob-handle] into a caller supplied buffer.
- ** N bytes of data are copied into buffer
- ** Z from the open blob, starting at offset iOffset.
- **
- ** If offset iOffset is less than N bytes from the end of the blob,
- ** [SQLITE_ERROR] is returned and no data is read. If N or iOffset is
- ** less than zero [SQLITE_ERROR] is returned and no data is read.
- **
- ** On success, SQLITE_OK is returned. Otherwise, an
- ** [error code] or an [extended error code] is returned.
- **
- ** INVARIANTS:
- **
- ** {F17853} The [sqlite3_blob_read(P,Z,N,X)] interface reads N bytes
- ** beginning at offset X from
- ** the blob that [sqlite3_blob] object P refers to
- ** and writes those N bytes into buffer Z.
- **
- ** {F17856} In [sqlite3_blob_read(P,Z,N,X)] if the size of the blob
- ** is less than N+X bytes, then the function returns [SQLITE_ERROR]
- ** and nothing is read from the blob.
- **
- ** {F17859} In [sqlite3_blob_read(P,Z,N,X)] if X or N is less than zero
- ** then the function returns [SQLITE_ERROR]
- ** and nothing is read from the blob.
- **
- ** {F17862} The [sqlite3_blob_read(P,Z,N,X)] interface returns [SQLITE_OK]
- ** if N bytes where successfully read into buffer Z.
- **
- ** {F17865} If the requested read could not be completed,
- ** the [sqlite3_blob_read(P,Z,N,X)] interface returns an
- ** appropriate [error code] or [extended error code].
- **
- ** {F17868} If an error occurs during evaluation of [sqlite3_blob_read(D,...)]
- ** then subsequent calls to [sqlite3_errcode(D)],
- ** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] will return
- ** information approprate for that error.
- */
- int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);
- /*
- ** CAPI3REF: Write Data Into A BLOB Incrementally {F17870}
- **
- ** This function is used to write data into an open
- ** [sqlite3_blob | blob-handle] from a user supplied buffer.
- ** n bytes of data are copied from the buffer
- ** pointed to by z into the open blob, starting at offset iOffset.
- **
- ** If the [sqlite3_blob | blob-handle] passed as the first argument
- ** was not opened for writing (the flags parameter to [sqlite3_blob_open()]
- *** was zero), this function returns [SQLITE_READONLY].
- **
- ** This function may only modify the contents of the blob; it is
- ** not possible to increase the size of a blob using this API.
- ** If offset iOffset is less than n bytes from the end of the blob,
- ** [SQLITE_ERROR] is returned and no data is written. If n is
- ** less than zero [SQLITE_ERROR] is returned and no data is written.
- **
- ** On success, SQLITE_OK is returned. Otherwise, an
- ** [error code] or an [extended error code] is returned.
- **
- ** INVARIANTS:
- **
- ** {F17873} The [sqlite3_blob_write(P,Z,N,X)] interface writes N bytes
- ** from buffer Z into
- ** the blob that [sqlite3_blob] object P refers to
- ** beginning at an offset of X into the blob.
- **
- ** {F17875} The [sqlite3_blob_write(P,Z,N,X)] interface returns
- ** [SQLITE_READONLY] if the [sqlite3_blob] object P was
- ** [sqlite3_blob_open | opened] for reading only.
- **
- ** {F17876} In [sqlite3_blob_write(P,Z,N,X)] if the size of the blob
- ** is less than N+X bytes, then the function returns [SQLITE_ERROR]
- ** and nothing is written into the blob.
- **
- ** {F17879} In [sqlite3_blob_write(P,Z,N,X)] if X or N is less than zero
- ** then the function returns [SQLITE_ERROR]
- ** and nothing is written into the blob.
- **
- ** {F17882} The [sqlite3_blob_write(P,Z,N,X)] interface returns [SQLITE_OK]
- ** if N bytes where successfully written into blob.
- **
- ** {F17885} If the requested write could not be completed,
- ** the [sqlite3_blob_write(P,Z,N,X)] interface returns an
- ** appropriate [error code] or [extended error code].
- **
- ** {F17888} If an error occurs during evaluation of [sqlite3_blob_write(D,...)]
- ** then subsequent calls to [sqlite3_errcode(D)],
- ** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] will return
- ** information approprate for that error.
- */
- int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);
- /*
- ** CAPI3REF: Virtual File System Objects {F11200}
- **
- ** A virtual filesystem (VFS) is an [sqlite3_vfs] object
- ** that SQLite uses to interact
- ** with the underlying operating system. Most SQLite builds come with a
- ** single default VFS that is appropriate for the host computer.
- ** New VFSes can be registered and existing VFSes can be unregistered.
- ** The following interfaces are provided.
- **
- ** The sqlite3_vfs_find() interface returns a pointer to
- ** a VFS given its name. Names are case sensitive.
- ** Names are zero-terminated UTF-8 strings.
- ** If there is no match, a NULL
- ** pointer is returned. If zVfsName is NULL then the default
- ** VFS is returned.
- **
- ** New VFSes are registered with sqlite3_vfs_register().
- ** Each new VFS becomes the default VFS if the makeDflt flag is set.
- ** The same VFS can be registered multiple times without injury.
- ** To make an existing VFS into the default VFS, register it again
- ** with the makeDflt flag set. If two different VFSes with the
- ** same name are registered, the behavior is undefined. If a
- ** VFS is registered with a name that is NULL or an empty string,
- ** then the behavior is undefined.
- **
- ** Unregister a VFS with the sqlite3_vfs_unregister() interface.
- ** If the default VFS is unregistered, another VFS is chosen as
- ** the default. The choice for the new VFS is arbitrary.
- **
- ** INVARIANTS:
- **
- ** {F11203} The [sqlite3_vfs_find(N)] interface returns a pointer to the
- ** registered [sqlite3_vfs] object whose name exactly matches
- ** the zero-terminated UTF-8 string N, or it returns NULL if
- ** there is no match.
- **
- ** {F11206} If the N parameter to [sqlite3_vfs_find(N)] is NULL then
- ** the function returns a pointer to the default [sqlite3_vfs]
- ** object if there is one, or NULL if there is no default
- ** [sqlite3_vfs] object.
- **
- ** {F11209} The [sqlite3_vfs_register(P,F)] interface registers the
- ** well-formed [sqlite3_vfs] object P using the name given
- ** by the zName field of the object.
- **
- ** {F11212} Using the [sqlite3_vfs_register(P,F)] interface to register
- ** the same [sqlite3_vfs] object multiple times is a harmless no-op.
- **
- ** {F11215} The [sqlite3_vfs_register(P,F)] interface makes the
- ** the [sqlite3_vfs] object P the default [sqlite3_vfs] object
- ** if F is non-zero.
- **
- ** {F11218} The [sqlite3_vfs_unregister(P)] interface unregisters the
- ** [sqlite3_vfs] object P so that it is no longer returned by
- ** subsequent calls to [sqlite3_vfs_find()].
- */
- sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName);
- int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);
- int sqlite3_vfs_unregister(sqlite3_vfs*);
- /*
- ** CAPI3REF: Mutexes {F17000}
- **
- ** The SQLite core uses these routines for thread
- ** synchronization. Though they are intended for internal
- ** use by SQLite, code that links against SQLite is
- ** permitted to use any of these routines.
- **
- ** The SQLite source code contains multiple implementations
- ** of these mutex routines. An appropriate implementation
- ** is selected automatically at compile-time. The following
- ** implementations are available in the SQLite core:
- **
- ** <ul>
- ** <li> SQLITE_MUTEX_OS2
- ** <li> SQLITE_MUTEX_PTHREAD
- ** <li> SQLITE_MUTEX_W32
- ** <li> SQLITE_MUTEX_NOOP
- ** </ul>
- **
- ** The SQLITE_MUTEX_NOOP implementation is a set of routines
- ** that does no real locking and is appropriate for use in
- ** a single-threaded application. The SQLITE_MUTEX_OS2,
- ** SQLITE_MUTEX_PTHREAD, and SQLITE_MUTEX_W32 implementations
- ** are appropriate for use on os/2, unix, and windows.
- **
- ** If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor
- ** macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex
- ** implementation is included with the library. The
- ** mutex interface routines defined here become external
- ** references in the SQLite library for which implementations
- ** must be provided by the application. This facility allows an
- ** application that links against SQLite to provide its own mutex
- ** implementation without having to modify the SQLite core.
- **
- ** {F17011} The sqlite3_mutex_alloc() routine allocates a new
- ** mutex and returns a pointer to it. {F17012} If it returns NULL
- ** that means that a mutex could not be allocated. {F17013} SQLite
- ** will unwind its stack and return an error. {F17014} The argument
- ** to sqlite3_mutex_alloc() is one of these integer constants:
- **
- ** <ul>
- ** <li> SQLITE_MUTEX_FAST
- ** <li> SQLITE_MUTEX_RECURSIVE
- ** <li> SQLITE_MUTEX_STATIC_MASTER
- ** <li> SQLITE_MUTEX_STATIC_MEM
- ** <li> SQLITE_MUTEX_STATIC_MEM2
- ** <li> SQLITE_MUTEX_STATIC_PRNG
- ** <li> SQLITE_MUTEX_STATIC_LRU
- ** <li> SQLITE_MUTEX_STATIC_LRU2
- ** </ul> {END}
- **
- ** {F17015} The first two constants cause sqlite3_mutex_alloc() to create
- ** a new mutex. The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
- ** is used but not necessarily so when SQLITE_MUTEX_FAST is used. {END}
- ** The mutex implementation does not need to make a distinction
- ** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does
- ** not want to. {F17016} But SQLite will only request a recursive mutex in
- ** cases where it really needs one. {END} If a faster non-recursive mutex
- ** implementation is available on the host platform, the mutex subsystem
- ** might return such a mutex in response to SQLITE_MUTEX_FAST.
- **
- ** {F17017} The other allowed parameters to sqlite3_mutex_alloc() each return
- ** a pointer to a static preexisting mutex. {END} Four static mutexes are
- ** used by the current version of SQLite. Future versions of SQLite
- ** may add additional static mutexes. Static mutexes are for internal
- ** use by SQLite only. Applications that use SQLite mutexes should
- ** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or
- ** SQLITE_MUTEX_RECURSIVE.
- **
- ** {F17018} Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST
- ** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
- ** returns a different mutex on every call. {F17034} But for the static
- ** mutex types, the same mutex is returned on every call that has
- ** the same type number. {END}
- **
- ** {F17019} The sqlite3_mutex_free() routine deallocates a previously
- ** allocated dynamic mutex. {F17020} SQLite is careful to deallocate every
- ** dynamic mutex that it allocates. {U17021} The dynamic mutexes must not be in
- ** use when they are deallocated. {U17022} Attempting to deallocate a static
- ** mutex results in undefined behavior. {F17023} SQLite never deallocates
- ** a static mutex. {END}
- **
- ** The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt
- ** to enter a mutex. {F17024} If another thread is already within the mutex,
- ** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return
- ** SQLITE_BUSY. {F17025} The sqlite3_mutex_try() interface returns SQLITE_OK
- ** upon successful entry. {F17026} Mutexes created using
- ** SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread.
- ** {F17027} In such cases the,
- ** mutex must be exited an equal number of times before another thread
- ** can enter. {U17028} If the same thread tries to enter any other
- ** kind of mutex more than once, the behavior is undefined.
- ** {F17029} SQLite will never exhibit
- ** such behavior in its own use of mutexes. {END}
- **
- ** Some systems (ex: windows95) do not the operation implemented by
- ** sqlite3_mutex_try(). On those systems, sqlite3_mutex_try() will
- ** always return SQLITE_BUSY. {F17030} The SQLite core only ever uses
- ** sqlite3_mutex_try() as an optimization so this is acceptable behavior. {END}
- **
- ** {F17031} The sqlite3_mutex_leave() routine exits a mutex that was
- ** previously entered by the same thread. {U17032} The behavior
- ** is undefined if the mutex is not currently entered by the
- ** calling thread or is not currently allocated. {F17033} SQLite will
- ** never do either. {END}
- **
- ** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()].
- */
- sqlite3_mutex *sqlite3_mutex_alloc(int);
- void sqlite3_mutex_free(sqlite3_mutex*);
- void sqlite3_mutex_enter(sqlite3_mutex*);
- int sqlite3_mutex_try(sqlite3_mutex*);
- void sqlite3_mutex_leave(sqlite3_mutex*);
- /*
- ** CAPI3REF: Mutex Verifcation Routines {F17080}
- **
- ** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines
- ** are intended for use inside assert() statements. {F17081} The SQLite core
- ** never uses these routines except inside an assert() and applications
- ** are advised to follow the lead of the core. {F17082} The core only
- ** provides implementations for these routines when it is compiled
- ** with the SQLITE_DEBUG flag. {U17087} External mutex implementations
- ** are only required to provide these routines if SQLITE_DEBUG is
- ** defined and if NDEBUG is not defined.
- **
- ** {F17083} These routines should return true if the mutex in their argument
- ** is held or not held, respectively, by the calling thread. {END}
- **
- ** {X17084} The implementation is not required to provided versions of these
- ** routines that actually work.
- ** If the implementation does not provide working
- ** versions of these routines, it should at least provide stubs
- ** that always return true so that one does not get spurious
- ** assertion failures. {END}
- **
- ** {F17085} If the argument to sqlite3_mutex_held() is a NULL pointer then
- ** the routine should return 1. {END} This seems counter-intuitive since
- ** clearly the mutex cannot be held if it does not exist. But the
- ** the reason the mutex does not exist is because the build is not
- ** using mutexes. And we do not want the assert() containing the
- ** call to sqlite3_mutex_held() to fail, so a non-zero return is
- ** the appropriate thing to do. {F17086} The sqlite3_mutex_notheld()
- ** interface should also return 1 when given a NULL pointer.
- */
- int sqlite3_mutex_held(sqlite3_mutex*);
- int sqlite3_mutex_notheld(sqlite3_mutex*);
- /*
- ** CAPI3REF: Mutex Types {F17001}
- **
- ** {F17002} The [sqlite3_mutex_alloc()] interface takes a single argument
- ** which is one of these integer constants. {END}
- */
- #define SQLITE_MUTEX_FAST 0
- #define SQLITE_MUTEX_RECURSIVE 1
- #define SQLITE_MUTEX_STATIC_MASTER 2
- #define SQLITE_MUTEX_STATIC_MEM 3 /* sqlite3_malloc() */
- #define SQLITE_MUTEX_STATIC_MEM2 4 /* sqlite3_release_memory() */
- #define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_random() */
- #define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */
- #define SQLITE_MUTEX_STATIC_LRU2 7 /* lru page list */
- /*
- ** CAPI3REF: Low-Level Control Of Database Files {F11300}
- **
- ** {F11301} The [sqlite3_file_control()] interface makes a direct call to the
- ** xFileControl method for the [sqlite3_io_methods] object associated
- ** with a particular database identified by the second argument. {F11302} The
- ** name of the database is the name assigned to the database by the
- ** <a href="lang_attach.html">ATTACH</a> SQL command that opened the
- ** database. {F11303} To control the main database file, use the name "main"
- ** or a NULL pointer. {F11304} The third and fourth parameters to this routine
- ** are passed directly through to the second and third parameters of
- ** the xFileControl method. {F11305} The return value of the xFileControl
- ** method becomes the return value of this routine.
- **
- ** {F11306} If the second parameter (zDbName) does not match the name of any
- ** open database file, then SQLITE_ERROR is returned. {F11307} This error
- ** code is not remembered and will not be recalled by [sqlite3_errcode()]
- ** or [sqlite3_errmsg()]. {U11308} The underlying xFileControl method might
- ** also return SQLITE_ERROR. {U11309} There is no way to distinguish between
- ** an incorrect zDbName and an SQLITE_ERROR return from the underlying
- ** xFileControl method. {END}
- **
- ** See also: [SQLITE_FCNTL_LOCKSTATE]
- */
- int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*);
- /*
- ** CAPI3REF: Testing Interface {F11400}
- **
- ** The sqlite3_test_control() interface is used to read out internal
- ** state of SQLite and to inject faults into SQLite for testing
- ** purposes. The first parameter a operation code that determines
- ** the number, meaning, and operation of all subsequent parameters.
- **
- ** This interface is not for use by applications. It exists solely
- ** for verifying the correct operation of the SQLite library. Depending
- ** on how the SQLite library is compiled, this interface might not exist.
- **
- ** The details of the operation codes, their meanings, the parameters
- ** they take, and what they do are all subject to change without notice.
- ** Unlike most of the SQLite API, this function is not guaranteed to
- ** operate consistently from one release to the next.
- */
- int sqlite3_test_control(int op, ...);
- /*
- ** CAPI3REF: Testing Interface Operation Codes {F11410}
- **
- ** These constants are the valid operation code parameters used
- ** as the first argument to [sqlite3_test_control()].
- **
- ** These parameters and their meansing are subject to change
- ** without notice. These values are for testing purposes only.
- ** Applications should not use any of these parameters or the
- ** [sqlite3_test_control()] interface.
- */
- #define SQLITE_TESTCTRL_FAULT_CONFIG 1
- #define SQLITE_TESTCTRL_FAULT_FAILURES 2
- #define SQLITE_TESTCTRL_FAULT_BENIGN_FAILURES 3
- #define SQLITE_TESTCTRL_FAULT_PENDING 4
- #define SQLITE_TESTCTRL_PRNG_SAVE 5
- #define SQLITE_TESTCTRL_PRNG_RESTORE 6
- #define SQLITE_TESTCTRL_PRNG_RESET 7
- #define SQLITE_TESTCTRL_BITVEC_TEST 8
- /*
- ** Undo the hack that converts floating point types to integer for
- ** builds on processors without floating point support.
- */
- #ifdef SQLITE_OMIT_FLOATING_POINT
- # undef double
- #endif
- #ifdef __cplusplus
- } /* End of the 'extern "C"' block */
- #endif
- #endif