Index: src/sqlite.h.in ================================================================== --- src/sqlite.h.in +++ src/sqlite.h.in @@ -28,11 +28,11 @@ ** The name of this file under configuration management is "sqlite.h.in". ** The makefile makes some minor changes to this file (such as inserting ** the version number) and changes its name to "sqlite3.h" as ** part of the build process. ** -** @(#) $Id: sqlite.h.in,v 1.291 2008/03/08 12:37:31 drh Exp $ +** @(#) $Id: sqlite.h.in,v 1.292 2008/03/18 13:47:21 drh Exp $ */ #ifndef _SQLITE3_H_ #define _SQLITE3_H_ #include /* Needed for the definition of va_list */ @@ -2292,16 +2292,43 @@ */ const char *sqlite3_sql(sqlite3_stmt *pStmt); /* ** CAPI3REF: Dynamically Typed Value Object {F15000} +** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value} ** ** SQLite uses the sqlite3_value object to represent all values -** that are or can be stored in a database table. +** that can be stored in a database table. ** SQLite uses dynamic typing for the values it stores. ** Values stored in sqlite3_value objects can be ** be integers, floating point values, strings, BLOBs, or NULL. +** +** An sqlite3_value object may be either "protected" or "unprotected". +** Some interfaces require a protected sqlite3_value. Other interfaces +** will accept either a protected or an unprotected sqlite3_value. +** Every interface that accepts sqlite3_value arguments specifies +** whether or not it requires a protected sqlite3_value. +** +** The terms "protected" and "unprotected" refer to whether or not +** a mutex is held. A internal mutex is held for a protected +** sqlite3_value object but no mutex is held for an unprotected +** sqlite3_value object. If SQLite is compiled to be single-threaded +** (with SQLITE_THREADSAFE=0 and with [sqlite3_threadsafe()] returning 0) +** then there is no distinction between +** protected and unprotected sqlite3_value objects and they can be +** used interchangable. However, for maximum code portability it +** is recommended that applications make the distinction between +** between protected and unprotected sqlite3_value objects even if +** they are single threaded. +** +** The sqlite3_value objects that are passed as parameters into the +** implementation of application-defined SQL functions are protected. +** The sqlite3_value object returned by +** [sqlite3_column_value()] is unprotected. +** Unprotected sqlite3_value objects may only be used with +** [sqlite3_result_value()] and [sqlite3_bind_value()]. All other +** interfaces that use sqlite3_value require protected sqlite3_value objects. */ typedef struct Mem sqlite3_value; /* ** CAPI3REF: SQL Function Context Object {F16001} @@ -2459,10 +2486,14 @@ ** a function, SQLite invokes that function to destroy the ** V value after it has finished using the V value. ** ** {F13548} In calls to [sqlite3_bind_zeroblob(S,N,V,L)] the value bound ** is a blob of L bytes, or a zero-length blob if L is negative. +** +** {F13551} In calls to [sqlite3_bind_value(S,N,V)] the V argument may +** be either a [protected sqlite3_value] object or an +** [unprotected sqlite3_value] object. */ int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*)); int sqlite3_bind_double(sqlite3_stmt*, int, double); int sqlite3_bind_int(sqlite3_stmt*, int, int); int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64); @@ -3016,10 +3047,19 @@ ** 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 @@ -3158,11 +3198,11 @@ ** [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 the [sqlite3_value] object that for the +** 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); @@ -3348,10 +3388,16 @@ ** ** {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, @@ -3410,18 +3456,22 @@ ** ** 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 -** [sqlite3_value] objects. There is one [sqlite3_value] object for +** [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 [sqlite3_value*] pointer instead -** of an [sqlite3_stmt*] pointer and an integer column number. +** 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. @@ -3439,20 +3489,17 @@ ** [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. -** Or, if the sqlite3_value* argument comes from the [sqlite3_column_value()] -** interface, then these routines should be called from the same thread -** that ran [sqlite3_column_value()]. +** the SQL function that supplied the [sqlite3_value*] parameters. ** ** ** INVARIANTS: ** ** {F15103} The [sqlite3_value_blob(V)] interface converts the -** [sqlite3_value] object V into a blob and then returns a +** [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 @@ -3464,52 +3511,52 @@ ** 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 -** [sqlite3_value] object V into a floating point value and +** [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 -** [sqlite3_value] object V into a 64-bit signed integer and +** [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 -** [sqlite3_value] object V into a 64-bit signed integer and +** [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 -** [sqlite3_value] object V into a zero-terminated UTF-8 +** [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 -** [sqlite3_value] object V into a zero-terminated 2-byte +** [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 -** [sqlite3_value] object V into a zero-terminated 2-byte +** [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 -** [sqlite3_value] object V into a zero-terminated 2-byte +** [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 [sqlite3_value] object V into either an integer or +** 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 [sqlite3_value] object V after the conversion attempt. +** 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*); @@ -3775,15 +3822,18 @@ ** 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 [sqlite3_value] -** object specified by the 2nd parameter. The +** 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. ** @@ -3849,11 +3899,12 @@ ** return value of function C to be the UTF16 little-endian ** string V up through the first zero or until N bytes are read if N ** is positive. ** ** {F16448} The [sqlite3_result_value(C,V)] interface changes the -** return value of function C to be [sqlite3_value] object V. +** 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()]