/ Check-in [074ee55f]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Update the documentation to distinguish between protected and unprotected sqlite3_value objects. (CVS 4879)
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 074ee55ffd1f0b7bb120a440d8bcf19e249ada96
User & Date: drh 2008-03-18 13:47:21
Context
2008-03-19
00:21
Remove the dependency on the direct btree interface from as many test scripts as is practical. Fix a bug in the output limiter of the integrity_check pragma that came up while making this change. (CVS 4880) check-in: 24e76997 user: drh tags: trunk
2008-03-18
13:47
Update the documentation to distinguish between protected and unprotected sqlite3_value objects. (CVS 4879) check-in: 074ee55f user: drh tags: trunk
13:46
Test script changes that go with the coverage enhancements of the previous check-in. (CVS 4878) check-in: f87ddf83 user: drh tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to src/sqlite.h.in.

    26     26   ** on how SQLite interfaces are suppose to operate.
    27     27   **
    28     28   ** The name of this file under configuration management is "sqlite.h.in".
    29     29   ** The makefile makes some minor changes to this file (such as inserting
    30     30   ** the version number) and changes its name to "sqlite3.h" as
    31     31   ** part of the build process.
    32     32   **
    33         -** @(#) $Id: sqlite.h.in,v 1.291 2008/03/08 12:37:31 drh Exp $
           33  +** @(#) $Id: sqlite.h.in,v 1.292 2008/03/18 13:47:21 drh Exp $
    34     34   */
    35     35   #ifndef _SQLITE3_H_
    36     36   #define _SQLITE3_H_
    37     37   #include <stdarg.h>     /* Needed for the definition of va_list */
    38     38   
    39     39   /*
    40     40   ** Make sure we can call this stuff from C++.
................................................................................
  2290   2290   ** {F13103} The string returned by [sqlite3_sql(S)] is valid until the
  2291   2291   **          [prepared statement] S is deleted using [sqlite3_finalize(S)].
  2292   2292   */
  2293   2293   const char *sqlite3_sql(sqlite3_stmt *pStmt);
  2294   2294   
  2295   2295   /*
  2296   2296   ** CAPI3REF:  Dynamically Typed Value Object  {F15000}
         2297  +** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value}
  2297   2298   **
  2298   2299   ** SQLite uses the sqlite3_value object to represent all values
  2299         -** that are or can be stored in a database table.
         2300  +** that can be stored in a database table.
  2300   2301   ** SQLite uses dynamic typing for the values it stores.  
  2301   2302   ** Values stored in sqlite3_value objects can be
  2302   2303   ** be integers, floating point values, strings, BLOBs, or NULL.
         2304  +**
         2305  +** An sqlite3_value object may be either "protected" or "unprotected".
         2306  +** Some interfaces require a protected sqlite3_value.  Other interfaces
         2307  +** will accept either a protected or an unprotected sqlite3_value.
         2308  +** Every interface that accepts sqlite3_value arguments specifies 
         2309  +** whether or not it requires a protected sqlite3_value.
         2310  +**
         2311  +** The terms "protected" and "unprotected" refer to whether or not
         2312  +** a mutex is held.  A internal mutex is held for a protected
         2313  +** sqlite3_value object but no mutex is held for an unprotected
         2314  +** sqlite3_value object.  If SQLite is compiled to be single-threaded
         2315  +** (with SQLITE_THREADSAFE=0 and with [sqlite3_threadsafe()] returning 0)
         2316  +** then there is no distinction between
         2317  +** protected and unprotected sqlite3_value objects and they can be
         2318  +** used interchangable.  However, for maximum code portability it
         2319  +** is recommended that applications make the distinction between
         2320  +** between protected and unprotected sqlite3_value objects even if
         2321  +** they are single threaded.
         2322  +**
         2323  +** The sqlite3_value objects that are passed as parameters into the
         2324  +** implementation of application-defined SQL functions are protected.
         2325  +** The sqlite3_value object returned by
         2326  +** [sqlite3_column_value()] is unprotected.
         2327  +** Unprotected sqlite3_value objects may only be used with
         2328  +** [sqlite3_result_value()] and [sqlite3_bind_value()].  All other
         2329  +** interfaces that use sqlite3_value require protected sqlite3_value objects.
  2303   2330   */
  2304   2331   typedef struct Mem sqlite3_value;
  2305   2332   
  2306   2333   /*
  2307   2334   ** CAPI3REF:  SQL Function Context Object {F16001}
  2308   2335   **
  2309   2336   ** The context in which an SQL function executes is stored in an
................................................................................
  2457   2484   **          [sqlite3_bind_text(S,N,V,L,D)], or
  2458   2485   **          [sqlite3_bind_text16(S,N,V,L,D)] when D is a pointer to
  2459   2486   **          a function, SQLite invokes that function to destroy the
  2460   2487   **          V value after it has finished using the V value.
  2461   2488   **
  2462   2489   ** {F13548} In calls to [sqlite3_bind_zeroblob(S,N,V,L)] the value bound
  2463   2490   **          is a blob of L bytes, or a zero-length blob if L is negative.
         2491  +**
         2492  +** {F13551} In calls to [sqlite3_bind_value(S,N,V)] the V argument may
         2493  +**          be either a [protected sqlite3_value] object or an
         2494  +**          [unprotected sqlite3_value] object.
  2464   2495   */
  2465   2496   int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
  2466   2497   int sqlite3_bind_double(sqlite3_stmt*, int, double);
  2467   2498   int sqlite3_bind_int(sqlite3_stmt*, int, int);
  2468   2499   int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
  2469   2500   int sqlite3_bind_null(sqlite3_stmt*, int);
  2470   2501   int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
................................................................................
  3014   3045   ** even empty strings, are always zero terminated.  The return
  3015   3046   ** value from sqlite3_column_blob() for a zero-length blob is an arbitrary
  3016   3047   ** pointer, possibly even a NULL pointer.
  3017   3048   **
  3018   3049   ** The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes()
  3019   3050   ** but leaves the result in UTF-16 in native byte order instead of UTF-8.  
  3020   3051   ** The zero terminator is not included in this count.
         3052  +**
         3053  +** The object returned by [sqlite3_column_value()] is an
         3054  +** [unprotected sqlite3_value] object.  An unprotected sqlite3_value object
         3055  +** may only be used with [sqlite3_bind_value()] and [sqlite3_result_value()].
         3056  +** If the [unprotected sqlite3_value] object returned by
         3057  +** [sqlite3_column_value()] is used in any other way, including calls
         3058  +** to routines like 
         3059  +** [sqlite3_value_int()], [sqlite3_value_text()], or [sqlite3_value_bytes()],
         3060  +** then the behavior is undefined.
  3021   3061   **
  3022   3062   ** These routines attempt to convert the value where appropriate.  For
  3023   3063   ** example, if the internal representation is FLOAT and a text result
  3024   3064   ** is requested, [sqlite3_snprintf()] is used internally to do the conversion
  3025   3065   ** automatically.  The following table details the conversions that
  3026   3066   ** are applied:
  3027   3067   **
................................................................................
  3156   3196   ** {F13827} The [sqlite3_column_type(S,N)] interface returns
  3157   3197   **          one of [SQLITE_NULL], [SQLITE_INTEGER], [SQLITE_FLOAT],
  3158   3198   **          [SQLITE_TEXT], or [SQLITE_BLOB] as appropriate for
  3159   3199   **          the Nth column in the current row of the result set for
  3160   3200   **          [prepared statement] S.
  3161   3201   **
  3162   3202   ** {F13830} The [sqlite3_column_value(S,N)] interface returns a
  3163         -**          pointer to the [sqlite3_value] object that for the
         3203  +**          pointer to an [unprotected sqlite3_value] object for the
  3164   3204   **          Nth column in the current row of the result set for
  3165   3205   **          [prepared statement] S.
  3166   3206   */
  3167   3207   const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
  3168   3208   int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
  3169   3209   int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
  3170   3210   double sqlite3_column_double(sqlite3_stmt*, int iCol);
................................................................................
  3346   3386   **          encodings E, then the implementation where E matches the
  3347   3387   **          database encoding is preferred.
  3348   3388   **
  3349   3389   ** {F16139} For an aggregate SQL function created using
  3350   3390   **          [sqlite3_create_function(D,X,N,E,P,0,S,L)] the finializer
  3351   3391   **          function L will always be invoked exactly once if the
  3352   3392   **          step function S is called one or more times.
         3393  +**
         3394  +** {F16142} When SQLite invokes either the xFunc or xStep function of
         3395  +**          an application-defined SQL function or aggregate created
         3396  +**          by [sqlite3_create_function()] or [sqlite3_create_function16()],
         3397  +**          then the array of [sqlite3_value] objects passed as the
         3398  +**          third parameter are always [protected sqlite3_value] objects.
  3353   3399   */
  3354   3400   int sqlite3_create_function(
  3355   3401     sqlite3 *db,
  3356   3402     const char *zFunctionName,
  3357   3403     int nArg,
  3358   3404     int eTextRep,
  3359   3405     void *pApp,
................................................................................
  3408   3454   ** this set of interface routines to access the parameter values on
  3409   3455   ** the function or aggregate.
  3410   3456   **
  3411   3457   ** The xFunc (for scalar functions) or xStep (for aggregates) parameters
  3412   3458   ** to [sqlite3_create_function()] and [sqlite3_create_function16()]
  3413   3459   ** define callbacks that implement the SQL functions and aggregates.
  3414   3460   ** The 4th parameter to these callbacks is an array of pointers to
  3415         -** [sqlite3_value] objects.  There is one [sqlite3_value] object for
         3461  +** [protected sqlite3_value] objects.  There is one [sqlite3_value] object for
  3416   3462   ** each parameter to the SQL function.  These routines are used to
  3417   3463   ** extract values from the [sqlite3_value] objects.
         3464  +**
         3465  +** These routines work only with [protected sqlite3_value] objects.
         3466  +** Any attempt to use these routines on an [unprotected sqlite3_value]
         3467  +** object results in undefined behavior.
  3418   3468   **
  3419   3469   ** These routines work just like the corresponding 
  3420   3470   ** [sqlite3_column_blob | sqlite3_column_* routines] except that 
  3421         -** these routines take a single [sqlite3_value*] pointer instead
  3422         -** of an [sqlite3_stmt*] pointer and an integer column number.
         3471  +** these routines take a single [protected sqlite3_value] object pointer
         3472  +** instead of an [sqlite3_stmt*] pointer and an integer column number.
  3423   3473   **
  3424   3474   ** The sqlite3_value_text16() interface extracts a UTF16 string
  3425   3475   ** in the native byte-order of the host machine.  The
  3426   3476   ** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces
  3427   3477   ** extract UTF16 strings as big-endian and little-endian respectively.
  3428   3478   **
  3429   3479   ** The sqlite3_value_numeric_type() interface attempts to apply
................................................................................
  3437   3487   ** Please pay particular attention to the fact that the pointer that
  3438   3488   ** is returned from [sqlite3_value_blob()], [sqlite3_value_text()], or
  3439   3489   ** [sqlite3_value_text16()] can be invalidated by a subsequent call to
  3440   3490   ** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()],
  3441   3491   ** or [sqlite3_value_text16()].  
  3442   3492   **
  3443   3493   ** These routines must be called from the same thread as
  3444         -** the SQL function that supplied the sqlite3_value* parameters.
  3445         -** Or, if the sqlite3_value* argument comes from the [sqlite3_column_value()]
  3446         -** interface, then these routines should be called from the same thread
  3447         -** that ran [sqlite3_column_value()].
         3494  +** the SQL function that supplied the [sqlite3_value*] parameters.
  3448   3495   **
  3449   3496   **
  3450   3497   ** INVARIANTS:
  3451   3498   **
  3452   3499   ** {F15103} The [sqlite3_value_blob(V)] interface converts the
  3453         -**          [sqlite3_value] object V into a blob and then returns a
         3500  +**          [protected sqlite3_value] object V into a blob and then returns a
  3454   3501   **          pointer to the converted value.
  3455   3502   **
  3456   3503   ** {F15106} The [sqlite3_value_bytes(V)] interface returns the
  3457   3504   **          number of bytes in the blob or string (exclusive of the
  3458   3505   **          zero terminator on the string) that was returned by the
  3459   3506   **          most recent call to [sqlite3_value_blob(V)] or
  3460   3507   **          [sqlite3_value_text(V)].
................................................................................
  3462   3509   ** {F15109} The [sqlite3_value_bytes16(V)] interface returns the
  3463   3510   **          number of bytes in the string (exclusive of the
  3464   3511   **          zero terminator on the string) that was returned by the
  3465   3512   **          most recent call to [sqlite3_value_text16(V)],
  3466   3513   **          [sqlite3_value_text16be(V)], or [sqlite3_value_text16le(V)].
  3467   3514   **
  3468   3515   ** {F15112} The [sqlite3_value_double(V)] interface converts the
  3469         -**          [sqlite3_value] object V into a floating point value and
         3516  +**          [protected sqlite3_value] object V into a floating point value and
  3470   3517   **          returns a copy of that value.
  3471   3518   **
  3472   3519   ** {F15115} The [sqlite3_value_int(V)] interface converts the
  3473         -**          [sqlite3_value] object V into a 64-bit signed integer and
         3520  +**          [protected sqlite3_value] object V into a 64-bit signed integer and
  3474   3521   **          returns the lower 32 bits of that integer.
  3475   3522   **
  3476   3523   ** {F15118} The [sqlite3_value_int64(V)] interface converts the
  3477         -**          [sqlite3_value] object V into a 64-bit signed integer and
         3524  +**          [protected sqlite3_value] object V into a 64-bit signed integer and
  3478   3525   **          returns a copy of that integer.
  3479   3526   **
  3480   3527   ** {F15121} The [sqlite3_value_text(V)] interface converts the
  3481         -**          [sqlite3_value] object V into a zero-terminated UTF-8 
         3528  +**          [protected sqlite3_value] object V into a zero-terminated UTF-8 
  3482   3529   **          string and returns a pointer to that string.
  3483   3530   **
  3484   3531   ** {F15124} The [sqlite3_value_text16(V)] interface converts the
  3485         -**          [sqlite3_value] object V into a zero-terminated 2-byte
         3532  +**          [protected sqlite3_value] object V into a zero-terminated 2-byte
  3486   3533   **          aligned UTF-16 native byte order
  3487   3534   **          string and returns a pointer to that string.
  3488   3535   **
  3489   3536   ** {F15127} The [sqlite3_value_text16be(V)] interface converts the
  3490         -**          [sqlite3_value] object V into a zero-terminated 2-byte
         3537  +**          [protected sqlite3_value] object V into a zero-terminated 2-byte
  3491   3538   **          aligned UTF-16 big-endian
  3492   3539   **          string and returns a pointer to that string.
  3493   3540   **
  3494   3541   ** {F15130} The [sqlite3_value_text16le(V)] interface converts the
  3495         -**          [sqlite3_value] object V into a zero-terminated 2-byte
         3542  +**          [protected sqlite3_value] object V into a zero-terminated 2-byte
  3496   3543   **          aligned UTF-16 little-endian
  3497   3544   **          string and returns a pointer to that string.
  3498   3545   **
  3499   3546   ** {F15133} The [sqlite3_value_type(V)] interface returns
  3500   3547   **          one of [SQLITE_NULL], [SQLITE_INTEGER], [SQLITE_FLOAT],
  3501   3548   **          [SQLITE_TEXT], or [SQLITE_BLOB] as appropriate for
  3502   3549   **          the [sqlite3_value] object V.
  3503   3550   **
  3504   3551   ** {F15136} The [sqlite3_value_numeric_type(V)] interface converts
  3505         -**          the [sqlite3_value] object V into either an integer or
         3552  +**          the [protected sqlite3_value] object V into either an integer or
  3506   3553   **          a floating point value if it can do so without loss of
  3507   3554   **          information, and returns one of [SQLITE_NULL],
  3508   3555   **          [SQLITE_INTEGER], [SQLITE_FLOAT], [SQLITE_TEXT], or
  3509   3556   **          [SQLITE_BLOB] as appropriate for
  3510         -**          the [sqlite3_value] object V after the conversion attempt.
         3557  +**          the [protected sqlite3_value] object V after the conversion attempt.
  3511   3558   */
  3512   3559   const void *sqlite3_value_blob(sqlite3_value*);
  3513   3560   int sqlite3_value_bytes(sqlite3_value*);
  3514   3561   int sqlite3_value_bytes16(sqlite3_value*);
  3515   3562   double sqlite3_value_double(sqlite3_value*);
  3516   3563   int sqlite3_value_int(sqlite3_value*);
  3517   3564   sqlite3_int64 sqlite3_value_int64(sqlite3_value*);
................................................................................
  3773   3820   ** finished using that result.
  3774   3821   ** If the 4th parameter to the sqlite3_result_text* interfaces
  3775   3822   ** or sqlite3_result_blob is the special constant SQLITE_TRANSIENT
  3776   3823   ** then SQLite makes a copy of the result into space obtained from
  3777   3824   ** from [sqlite3_malloc()] before it returns.
  3778   3825   **
  3779   3826   ** The sqlite3_result_value() interface sets the result of
  3780         -** the application-defined function to be a copy the [sqlite3_value]
  3781         -** object specified by the 2nd parameter.  The
         3827  +** the application-defined function to be a copy the
         3828  +** [unprotected sqlite3_value] object specified by the 2nd parameter.  The
  3782   3829   ** sqlite3_result_value() interface makes a copy of the [sqlite3_value]
  3783   3830   ** so that [sqlite3_value] specified in the parameter may change or
  3784   3831   ** be deallocated after sqlite3_result_value() returns without harm.
         3832  +** A [protected sqlite3_value] object may always be used where an
         3833  +** [unprotected sqlite3_value] object is required, so either
         3834  +** kind of [sqlite3_value] object can be used with this interface.
  3785   3835   **
  3786   3836   ** If these routines are called from within the different thread 
  3787   3837   ** than the one containing the application-defined function that recieved
  3788   3838   ** the [sqlite3_context] pointer, the results are undefined.
  3789   3839   **
  3790   3840   ** INVARIANTS:
  3791   3841   **
................................................................................
  3847   3897   **
  3848   3898   ** {F16445} The [sqlite3_result_text16le(C,V,N,D)] interface changes the
  3849   3899   **          return value of function C to be the UTF16 little-endian
  3850   3900   **          string  V up through the first zero or until N bytes are read if N
  3851   3901   **          is positive.
  3852   3902   **
  3853   3903   ** {F16448} The [sqlite3_result_value(C,V)] interface changes the
  3854         -**          return value of function C to be [sqlite3_value] object V.
         3904  +**          return value of function C to be [unprotected sqlite3_value]
         3905  +**          object V.
  3855   3906   **
  3856   3907   ** {F16451} The [sqlite3_result_zeroblob(C,N)] interface changes the
  3857   3908   **          return value of function C to be an N-byte blob of all zeros.
  3858   3909   **
  3859   3910   ** {F16454} The [sqlite3_result_error()] and [sqlite3_result_error16()]
  3860   3911   **          interfaces make a copy of their error message strings before
  3861   3912   **          returning.