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

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.449 2009/05/14 03:21:28 shane Exp $
           33  +** @(#) $Id: sqlite.h.in,v 1.450 2009/05/14 22:37:48 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++.
................................................................................
  3737   3737   */
  3738   3738   sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt);
  3739   3739   
  3740   3740   /*
  3741   3741   ** CAPI3REF: Commit And Rollback Notification Callbacks {H12950} <S60400>
  3742   3742   **
  3743   3743   ** The sqlite3_commit_hook() interface registers a callback
  3744         -** function to be invoked whenever a transaction is committed.
         3744  +** function to be invoked whenever a transaction is [COMMIT | committed].
  3745   3745   ** Any callback set by a previous call to sqlite3_commit_hook()
  3746   3746   ** for the same database connection is overridden.
  3747   3747   ** The sqlite3_rollback_hook() interface registers a callback
  3748         -** function to be invoked whenever a transaction is committed.
         3748  +** function to be invoked whenever a transaction is [ROLLBACK | rolled back].
  3749   3749   ** Any callback set by a previous call to sqlite3_commit_hook()
  3750   3750   ** for the same database connection is overridden.
  3751   3751   ** The pArg argument is passed through to the callback.
  3752   3752   ** If the callback on a commit hook function returns non-zero,
  3753   3753   ** then the commit is converted into a rollback.
  3754   3754   **
  3755   3755   ** If another function was previously registered, its
................................................................................
  3761   3761   ** completion of the [sqlite3_step()] call that triggered the commit
  3762   3762   ** or rollback hook in the first place.
  3763   3763   ** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
  3764   3764   ** database connections for the meaning of "modify" in this paragraph.
  3765   3765   **
  3766   3766   ** Registering a NULL function disables the callback.
  3767   3767   **
         3768  +** When the commit hook callback routine returns zero, the [COMMIT]
         3769  +** operation is allowed to continue normally.  If the commit hook
         3770  +** returns non-zero, then the [COMMIT] is converted into a [ROLLBACK].
         3771  +** The rollback hook is invoked on a rollback that results from a commit
         3772  +** hook returning non-zero, just as it would be with any other rollback.
         3773  +**
  3768   3774   ** For the purposes of this API, a transaction is said to have been
  3769   3775   ** rolled back if an explicit "ROLLBACK" statement is executed, or
  3770   3776   ** an error or constraint causes an implicit rollback to occur.
  3771   3777   ** The rollback callback is not invoked if a transaction is
  3772   3778   ** automatically rolled back because the database connection is closed.
  3773   3779   ** The rollback callback is not invoked if a transaction is
  3774   3780   ** rolled back because a commit callback returned non-zero.
  3775   3781   ** <todo> Check on this </todo>
         3782  +**
         3783  +** See also the [sqlite3_update_hook()] interface.
  3776   3784   **
  3777   3785   ** Requirements:
  3778   3786   ** [H12951] [H12952] [H12953] [H12954] [H12955]
  3779   3787   ** [H12961] [H12962] [H12963] [H12964]
  3780   3788   */
  3781   3789   void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
  3782   3790   void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
................................................................................
  3800   3808   ** The third and fourth arguments to the callback contain pointers to the
  3801   3809   ** database and table name containing the affected row.
  3802   3810   ** The final callback parameter is the [rowid] of the row.
  3803   3811   ** In the case of an update, this is the [rowid] after the update takes place.
  3804   3812   **
  3805   3813   ** The update hook is not invoked when internal system tables are
  3806   3814   ** modified (i.e. sqlite_master and sqlite_sequence).
         3815  +**
         3816  +** In the current implementation, the update hook
         3817  +** is not invoked when duplication rows are deleted because of an
         3818  +** [ON CONFLICT | ON CONFLICT REPLACE] clause.  Nor is the update hook
         3819  +** invoked when rows are deleted using the [truncate optimization].
         3820  +** The exceptions defined in this paragraph might change in a future
         3821  +** release of SQLite.
  3807   3822   **
  3808   3823   ** The update hook implementation must not do anything that will modify
  3809   3824   ** the database connection that invoked the update hook.  Any actions
  3810   3825   ** to modify the database connection must be deferred until after the
  3811   3826   ** completion of the [sqlite3_step()] call that triggered the update hook.
  3812   3827   ** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
  3813   3828   ** database connections for the meaning of "modify" in this paragraph.
  3814   3829   **
  3815   3830   ** If another function was previously registered, its pArg value
  3816   3831   ** is returned.  Otherwise NULL is returned.
         3832  +**
         3833  +** See also the [sqlite3_commit_hook()] and [sqlite3_rollback_hook()]
         3834  +** interfaces.
  3817   3835   **
  3818   3836   ** Requirements:
  3819   3837   ** [H12971] [H12973] [H12975] [H12977] [H12979] [H12981] [H12983] [H12986]
  3820   3838   */
  3821   3839   void *sqlite3_update_hook(
  3822   3840     sqlite3*, 
  3823   3841     void(*)(void *,int ,char const *,char const *,sqlite3_int64),
................................................................................
  4390   4408   ** Note that the database name is not the filename that contains
  4391   4409   ** the database but rather the symbolic name of the database that
  4392   4410   ** is assigned when the database is connected using [ATTACH].
  4393   4411   ** For the main database file, the database name is "main".
  4394   4412   ** For TEMP tables, the database name is "temp".
  4395   4413   **
  4396   4414   ** On success, [SQLITE_OK] is returned and the new [BLOB handle] is written
  4397         -** to *ppBlob. Otherwise an [error code] is returned and any value written
  4398         -** to *ppBlob should not be used by the caller.
         4415  +** to *ppBlob. Otherwise an [error code] is returned and *ppBlob is set
         4416  +** to be a null pointer.
  4399   4417   ** This function sets the [database connection] error code and message
  4400         -** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()].
         4418  +** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()] and related
         4419  +** functions.  Note that the *ppBlob variable is always initialized in a
         4420  +** way that makes it safe to invoke [sqlite3_blob_close()] on *ppBlob
         4421  +** regardless of the success or failure of this routine.
  4401   4422   **
  4402   4423   ** If the row that a BLOB handle points to is modified by an
  4403   4424   ** [UPDATE], [DELETE], or by [ON CONFLICT] side-effects
  4404   4425   ** then the BLOB handle is marked as "expired".
  4405   4426   ** This is true if any column of the row is changed, even a column
  4406   4427   ** other than the one the BLOB handle is open on.
  4407   4428   ** Calls to [sqlite3_blob_read()] and [sqlite3_blob_write()] for
  4408   4429   ** a expired BLOB handle fail with an return code of [SQLITE_ABORT].
  4409   4430   ** Changes written into a BLOB prior to the BLOB expiring are not
  4410   4431   ** rollback by the expiration of the BLOB.  Such changes will eventually
  4411   4432   ** commit if the transaction continues to completion.
         4433  +**
         4434  +** Use the [sqlite3_blob_bytes()] interface to determine the size of
         4435  +** the opened blob.  The size of a blob may not be changed by this
         4436  +** underface.  Use the [UPDATE] SQL command to change the size of a
         4437  +** blob.
         4438  +**
         4439  +** The [sqlite3_bind_zeroblob()] and [sqlite3_result_zeroblob()] interfaces
         4440  +** and the built-in [zeroblob] SQL function can be used, if desired,
         4441  +** to create an empty, zero-filled blob in which to read or write using
         4442  +** this interface.
         4443  +**
         4444  +** To avoid a resource leak, every open [BLOB handle] should eventually
         4445  +** be released by a call to [sqlite3_blob_close()].
  4412   4446   **
  4413   4447   ** Requirements:
  4414   4448   ** [H17813] [H17814] [H17816] [H17819] [H17821] [H17824]
  4415   4449   */
  4416   4450   int sqlite3_blob_open(
  4417   4451     sqlite3*,
  4418   4452     const char *zDb,
................................................................................
  4428   4462   **
  4429   4463   ** Closes an open [BLOB handle].
  4430   4464   **
  4431   4465   ** Closing a BLOB shall cause the current transaction to commit
  4432   4466   ** if there are no other BLOBs, no pending prepared statements, and the
  4433   4467   ** database connection is in [autocommit mode].
  4434   4468   ** If any writes were made to the BLOB, they might be held in cache
  4435         -** until the close operation if they will fit. {END}
         4469  +** until the close operation if they will fit.
  4436   4470   **
  4437   4471   ** Closing the BLOB often forces the changes
  4438   4472   ** out to disk and so if any I/O errors occur, they will likely occur
  4439         -** at the time when the BLOB is closed.  {H17833} Any errors that occur during
         4473  +** at the time when the BLOB is closed.  Any errors that occur during
  4440   4474   ** closing are reported as a non-zero return value.
  4441   4475   **
  4442   4476   ** The BLOB is closed unconditionally.  Even if this routine returns
  4443   4477   ** an error code, the BLOB is still closed.
         4478  +**
         4479  +** Calling this routine with a null pointer (which as would be returned
         4480  +** by failed call to [sqlite3_blob_open()]) is a harmless no-op.
  4444   4481   **
  4445   4482   ** Requirements:
  4446   4483   ** [H17833] [H17836] [H17839]
  4447   4484   */
  4448   4485   int sqlite3_blob_close(sqlite3_blob *);
  4449   4486   
  4450   4487   /*
  4451   4488   ** CAPI3REF: Return The Size Of An Open BLOB {H17840} <S30230>
  4452   4489   **
  4453         -** Returns the size in bytes of the BLOB accessible via the open
  4454         -** []BLOB handle] in its only argument.
         4490  +** Returns the size in bytes of the BLOB accessible via the 
         4491  +** successfully opened [BLOB handle] in its only argument.  The
         4492  +** incremental blob I/O routines can only read or overwriting existing
         4493  +** blob content; they cannot change the size of a blob.
         4494  +**
         4495  +** This routine only works on a [BLOB handle] which has been created
         4496  +** by a prior successful call to [sqlite3_blob_open()] and which has not
         4497  +** been closed by [sqlite3_blob_close()].  Passing any other pointer in
         4498  +** to this routine results in undefined and probably undesirable behavior.
  4455   4499   **
  4456   4500   ** Requirements:
  4457   4501   ** [H17843]
  4458   4502   */
  4459   4503   int sqlite3_blob_bytes(sqlite3_blob *);
  4460   4504   
  4461   4505   /*
................................................................................
  4464   4508   ** This function is used to read data from an open [BLOB handle] into a
  4465   4509   ** caller-supplied buffer. N bytes of data are copied into buffer Z
  4466   4510   ** from the open BLOB, starting at offset iOffset.
  4467   4511   **
  4468   4512   ** If offset iOffset is less than N bytes from the end of the BLOB,
  4469   4513   ** [SQLITE_ERROR] is returned and no data is read.  If N or iOffset is
  4470   4514   ** less than zero, [SQLITE_ERROR] is returned and no data is read.
         4515  +** The size of the blob (and hence the maximum value of N+iOffset)
         4516  +** can be determined using the [sqlite3_blob_bytes()] interface.
  4471   4517   **
  4472   4518   ** An attempt to read from an expired [BLOB handle] fails with an
  4473   4519   ** error code of [SQLITE_ABORT].
  4474   4520   **
  4475   4521   ** On success, SQLITE_OK is returned.
  4476   4522   ** Otherwise, an [error code] or an [extended error code] is returned.
         4523  +**
         4524  +** This routine only works on a [BLOB handle] which has been created
         4525  +** by a prior successful call to [sqlite3_blob_open()] and which has not
         4526  +** been closed by [sqlite3_blob_close()].  Passing any other pointer in
         4527  +** to this routine results in undefined and probably undesirable behavior.
         4528  +**
         4529  +** See also: [sqlite3_blob_write()].
  4477   4530   **
  4478   4531   ** Requirements:
  4479   4532   ** [H17853] [H17856] [H17859] [H17862] [H17863] [H17865] [H17868]
  4480   4533   */
  4481   4534   int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);
  4482   4535   
  4483   4536   /*
................................................................................
  4492   4545   ** this function returns [SQLITE_READONLY].
  4493   4546   **
  4494   4547   ** This function may only modify the contents of the BLOB; it is
  4495   4548   ** not possible to increase the size of a BLOB using this API.
  4496   4549   ** If offset iOffset is less than N bytes from the end of the BLOB,
  4497   4550   ** [SQLITE_ERROR] is returned and no data is written.  If N is
  4498   4551   ** less than zero [SQLITE_ERROR] is returned and no data is written.
         4552  +** The size of the BLOB (and hence the maximum value of N+iOffset)
         4553  +** can be determined using the [sqlite3_blob_bytes()] interface.
  4499   4554   **
  4500   4555   ** An attempt to write to an expired [BLOB handle] fails with an
  4501   4556   ** error code of [SQLITE_ABORT].  Writes to the BLOB that occurred
  4502   4557   ** before the [BLOB handle] expired are not rolled back by the
  4503   4558   ** expiration of the handle, though of course those changes might
  4504   4559   ** have been overwritten by the statement that expired the BLOB handle
  4505   4560   ** or by other independent statements.
  4506   4561   **
  4507   4562   ** On success, SQLITE_OK is returned.
  4508   4563   ** Otherwise, an  [error code] or an [extended error code] is returned.
         4564  +**
         4565  +** This routine only works on a [BLOB handle] which has been created
         4566  +** by a prior successful call to [sqlite3_blob_open()] and which has not
         4567  +** been closed by [sqlite3_blob_close()].  Passing any other pointer in
         4568  +** to this routine results in undefined and probably undesirable behavior.
         4569  +**
         4570  +** See also: [sqlite3_blob_read()].
  4509   4571   **
  4510   4572   ** Requirements:
  4511   4573   ** [H17873] [H17874] [H17875] [H17876] [H17877] [H17879] [H17882] [H17885]
  4512   4574   ** [H17888]
  4513   4575   */
  4514   4576   int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);
  4515   4577