Documentation Source Text

  incr nChng
}

chng {2017-07-20 (3.20.0)} {
<li> Update the text of error messages returned by [sqlite3_errmsg()] for some
     error codes.
<li> Add new interfaces [sqlite3_bind_pointer()], [sqlite3_result_pointer()], and
     [sqlite3_value_pointer()].
<li> Backwards-incompatible changes to some extensions in order to take 
     advantage of the improved security offered by the new [sqlite3_bind_pointer()]
     interface:
     <ul>
     <li> [Extending FTS5] &rarr; requires [sqlite3_bind_pointer()] to find
          the fts5_api pointer.
     <li> [carray(PTR,N)] &rarr; requires [sqlite3_bind_pointer()] to set the PTR parameter.
     <li> [https://www.sqlite.org/src/file/ext/misc/remember.c|remember(V,PTR)]
          &rarr; requires [sqlite3_bind_pointer()] to set the PTR parameter.
     </ul>
<li> Added the [SQLITE_STMT virtual table] extension.
<li> Added the [COMPLETION extension] - designed to suggest
     tab-completions for interactive user interfaces.  This is a work in progress.
     Expect further enhancements in future releases.
<li> Added the [sqlite3_prepare_v3()] and [sqlite3_prepare16_v3()] interfaces
     with the extra "prepFlags" parameters.
<li> Provide the [SQLITE_PREPARE_PERSISTENT] flag [sqlite3_prepare_v3()] and
     use it to limit [lookaside memory] misuse by [FTS3], [FTS5], and the
     [R-Tree extension].
<li> Added the [PRAGMA secure_delete=FAST] command.  When secure_delete is
     set to FAST, old content is overwritten with zeros as long as that does

document are all implemented using the publicly available API described
below.

<p> Before a new auxiliary function or tokenizer implementation may be 
registered with FTS5, an application must obtain a pointer to the "fts5_api"
structure. There is one fts5_api structure for each database connection with
which the FTS5 extension is registered. To obtain the pointer, the application
invokes the SQL user-defined function fts5() with a single argument.  That
argument must be set to a pointer to a pointer to an fts5_api object
using the [sqlite3_bind_pointer()] interface.
The following example code demonstrates the technique:

<codeblock>
  <i>/*
  ** Return a pointer to the fts5_api pointer for database connection db.
  ** If an error occurs, return NULL and leave an error in the database 
  ** handle (accessible using sqlite3_errcode()/errmsg()).
  */</i>
  fts5_api *fts5_api_from_db(sqlite3 *db){
    fts5_api *pRet = 0;
    sqlite3_stmt *pStmt = 0;

    if( SQLITE_OK==sqlite3_prepare(db, "SELECT fts5(?1)", -1, &pStmt, 0) ){
      sqlite3_bind_pointer(pStmt, (void*)&pRet, "fts5_api_ptr");
      sqlite3_step(pStmt);



    }
    sqlite3_finalize(pStmt);
    return pRet;
  }
</codeblock>

<p><b>Backwards Compatibility Warning:</b>
Prior to SQLite version 3.20.0 ([dateof:3.20.0]), the fts5() worked slightly
differently.  Older applications that extend FTS5 must be revised to use 
the new technique shown above.

<p> The fts5_api structure is defined as follows. It exposes three methods, 
one each for registering new auxiliary functions and tokenizers, and one for
retrieving existing tokenizer. The latter is intended to facilitate the
implementation of "tokenizer wrappers" similar to the built-in
porter tokenizer.

** Return a pointer to the fts5_api pointer for database connection db.
** If an error occurs, return NULL and leave an error in the database 
** handle (accessible using sqlite3_errcode()/errmsg()).
*/
fts5_api *fts5_api_from_db(sqlite3 *db){
  fts5_api *pRet = 0;
  sqlite3_stmt *pStmt = 0;
  if( SQLITE_OK==sqlite3_prepare(db, "SELECT fts5(?1)", -1, &pStmt, 0) ){
    sqlite3_bind_pointer(pStmt, 1, (void*)&pRet, "fts5_api_ptr");
    sqlite3_step(pStmt);



  }
  sqlite3_finalize(pStmt);
  return pRet;
}
/************************************************************************/

/*