System.Data.SQLite
Changes On Branch vtabDocComments
Not logged in

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

Changes In Branch vtabDocComments Excluding Merge-Ins

This is equivalent to a diff from b233d0f72d to fcc756f8d0

2015-10-18
20:28
Update and improve documentation comments for the native virtual table methods. check-in: 2c6bdf20ea user: mistachkin tags: trunk
20:11
Minor simplification to the previous check-in. Also, correct a comment. Closed-Leaf check-in: fcc756f8d0 user: mistachkin tags: vtabDocComments
20:07
Preserve selected HTML tags when processing the virtual table methods documentation into the CHM file. check-in: 42512a2bfb user: mistachkin tags: vtabDocComments
01:51
Fix typo. check-in: b64cf102ce user: mistachkin tags: trunk
00:20
Work in progress on a tool to update the embedded doc comments for the ISQLiteNativeModule interface. check-in: 44c116ca23 user: mistachkin tags: vtabDocComments
00:18
Move the ISQLiteNativeModule interface to its own file. check-in: b233d0f72d user: mistachkin tags: trunk
2015-10-17
21:09
Update the included core library documentation. check-in: b57c9d07fc user: mistachkin tags: trunk

Added Doc/Special/Core/vtab.html.

            1  +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
            2  +<html><head>
            3  +<meta http-equiv="content-type" content="text/html; charset=UTF-8">
            4  +<title>The Virtual Table Mechanism Of SQLite</title>
            5  +<style type="text/css">
            6  +body {
            7  +    margin: auto;
            8  +    font-family: Verdana, sans-serif;
            9  +    padding: 8px 1%;
           10  +}
           11  +
           12  +a { color: #044a64 }
           13  +a:visited { color: #734559 }
           14  +
           15  +.logo { position:absolute; margin:3px; }
           16  +.tagline {
           17  +  float:right;
           18  +  text-align:right;
           19  +  font-style:italic;
           20  +  width:300px;
           21  +  margin:12px;
           22  +  margin-top:58px;
           23  +}
           24  +
           25  +.menubar {
           26  +  clear: both;
           27  +  border-radius: 8px;
           28  +  background: #044a64;
           29  +  padding: 0px;
           30  +  margin: 0px;
           31  +  cell-spacing: 0px;
           32  +}    
           33  +.toolbar {
           34  +  text-align: center;
           35  +  line-height: 1.6em;
           36  +  margin: 0;
           37  +  padding: 0px 8px;
           38  +}
           39  +.toolbar a { color: white; text-decoration: none; padding: 6px 12px; }
           40  +.toolbar a:visited { color: white; }
           41  +.toolbar a:hover { color: #044a64; background: white; }
           42  +
           43  +.content    { margin: 5%; }
           44  +.content dt { font-weight:bold; }
           45  +.content dd { margin-bottom: 25px; margin-left:20%; }
           46  +.content ul { padding:0px; padding-left: 15px; margin:0px; }
           47  +
           48  +/* Things for "fancyformat" documents start here. */
           49  +.fancy img+p {font-style:italic}
           50  +.fancy .codeblock i { color: darkblue; }
           51  +.fancy h1,.fancy h2,.fancy h3,.fancy h4 {font-weight:normal;color:#044a64}
           52  +.fancy h2 { margin-left: 10px }
           53  +.fancy h3 { margin-left: 20px }
           54  +.fancy h4 { margin-left: 30px }
           55  +.fancy th {white-space:nowrap;text-align:left;border-bottom:solid 1px #444}
           56  +.fancy th, .fancy td {padding: 0.2em 1ex; vertical-align:top}
           57  +.fancy #toc a        { color: darkblue ; text-decoration: none }
           58  +.fancy .todo         { color: #AA3333 ; font-style : italic }
           59  +.fancy .todo:before  { content: 'TODO:' }
           60  +.fancy p.todo        { border: solid #AA3333 1px; padding: 1ex }
           61  +.fancy img { display:block; }
           62  +.fancy :link:hover, .fancy :visited:hover { background: wheat }
           63  +.fancy p,.fancy ul,.fancy ol,.fancy dl { margin: 1em 5ex }
           64  +.fancy li p { margin: 1em 0 }
           65  +/* End of "fancyformat" specific rules. */
           66  +
           67  +.yyterm {
           68  +  background: #fff;
           69  +  border: 1px solid #000;
           70  +  border-radius: 11px;
           71  +  padding-left: 4px;
           72  +  padding-right: 4px;
           73  +}
           74  +</style>
           75  +  
           76  +</head>
           77  +<body>
           78  +<div><!-- container div to satisfy validator -->
           79  +
           80  +<a href="index.html">
           81  +<img class="logo" src="images/sqlite370_banner.gif" alt="SQLite Logo"
           82  + border="0"></a>
           83  +<div><!-- IE hack to prevent disappearing logo--></div>
           84  +<div class="tagline">Small. Fast. Reliable.<br>Choose any three.</div>
           85  +
           86  +<table width=100% class="menubar"><tr>
           87  +  <td width=100%>
           88  +  <div class="toolbar">
           89  +    <a href="about.html">About</a>
           90  +    <a href="sitemap.html">Sitemap</a>
           91  +    <a href="docs.html">Documentation</a>
           92  +    <a href="download.html">Download</a>
           93  +    <a href="copyright.html">License</a>
           94  +    <a href="news.html">News</a>
           95  +    <a href="support.html">Support</a>
           96  +  </div>
           97  +<script>
           98  +  gMsg = "Search SQLite Docs..."
           99  +  function entersearch() {
          100  +    var q = document.getElementById("q");
          101  +    if( q.value == gMsg ) { q.value = "" }
          102  +    q.style.color = "black"
          103  +    q.style.fontStyle = "normal"
          104  +  }
          105  +  function leavesearch() {
          106  +    var q = document.getElementById("q");
          107  +    if( q.value == "" ) { 
          108  +      q.value = gMsg
          109  +      q.style.color = "#044a64"
          110  +      q.style.fontStyle = "italic"
          111  +    }
          112  +  }
          113  +  function hideorshow(btn,obj){
          114  +    var x = document.getElementById(obj);
          115  +    var b = document.getElementById(btn);
          116  +    if( x.style.display!='none' ){
          117  +      x.style.display = 'none';
          118  +      b.innerHTML='show';
          119  +    }else{
          120  +      x.style.display = '';
          121  +      b.innerHTML='hide';
          122  +    }
          123  +    return false;
          124  +  }
          125  +</script>
          126  +<td>
          127  +    <div style="padding:0 1em 0px 0;white-space:nowrap">
          128  +    <form name=f method="GET" action="https://www.sqlite.org/search">
          129  +      <input id=q name=q type=text
          130  +       onfocus="entersearch()" onblur="leavesearch()" style="width:24ex;padding:1px 1ex; border:solid white 1px; font-size:0.9em ; font-style:italic;color:#044a64;" value="Search SQLite Docs...">
          131  +      <input type=submit value="Go" style="border:solid white 1px;background-color:#044a64;color:white;font-size:0.9em;padding:0 1ex">
          132  +    </form>
          133  +    </div>
          134  +  </table>
          135  +
          136  +<div class=startsearch></div>
          137  +  
          138  +
          139  +
          140  +<h1 align="center">The Virtual Table Mechanism Of SQLite</h1>
          141  +
          142  +
          143  +<h2>1.0 Introduction</h2>
          144  +
          145  +<p>A virtual table is an object that is registered with an open SQLite
          146  +<a href="c3ref/sqlite3.html">database connection</a>. From the perspective of an SQL statement,
          147  +the virtual table object looks like any other table or view. 
          148  +But behind the scenes, queries and updates on a virtual table
          149  +invoke callback methods of the virtual table object instead of
          150  +reading and writing to the database file.
          151  +
          152  +<p>The virtual table mechanism allows an application to publish
          153  +interfaces that are accessible from SQL statements as if they were
          154  +tables. SQL statements can do almost anything to a
          155  +virtual table that they can do to a real table, with the following
          156  +exceptions:
          157  +
          158  +<p>
          159  +<ul>
          160  +<li> One cannot create a trigger on a virtual table.
          161  +<li> One cannot create additional indices on a virtual table. 
          162  +     (Virtual tables can have indices but that must be built into
          163  +     the virtual table implementation.  Indices cannot be added
          164  +     separately using <a href="lang_createindex.html">CREATE INDEX</a> statements.)
          165  +<li> One cannot run <a href="lang_altertable.html">ALTER TABLE ... ADD COLUMN</a>
          166  +     commands against a virtual table.
          167  +</ul>
          168  +
          169  +<p>Individual virtual table implementations might impose additional
          170  +constraints. For example, some virtual implementations might provide
          171  +read-only tables. Or some virtual table implementations might allow
          172  +<a href="lang_insert.html">INSERT</a> or <a href="lang_delete.html">DELETE</a> but not <a href="lang_update.html">UPDATE</a>.  Or some virtual table implementations
          173  +might limit the kinds of UPDATEs that can be made.
          174  +
          175  +<p>A virtual table might represent an in-memory data structures. 
          176  +Or it might represent a view of data on disk that is not in the
          177  +SQLite format. Or the application might compute the content of the 
          178  +virtual table on demand.
          179  +
          180  +<p>Here are some existing and postulated uses for virtual tables:
          181  +
          182  +<ul>
          183  +<li> A <a href="fts3.html">full-text search</a> interface
          184  +<li> Spatial indices using <a href="rtree.html">R-Trees</a>
          185  +<li> Introspect the disk content of an SQLite database file
          186  +     (the <a href="dbstat.html">dbstat virtual table</a>)
          187  +<li> Read and/or write the content of a comma-separated value (CSV)
          188  +     file
          189  +<li> Access the filesystem of the host computer as if it were a database table
          190  +<li> Enabling SQL manipulation of data in statistics packages like R
          191  +</ul>
          192  +
          193  +<h3>1.1 Usage</h3>
          194  +
          195  +<p>A virtual table is created using a <a href="lang_createvtab.html">CREATE VIRTUAL TABLE</a> statement.
          196  +
          197  +<p><b><a href="syntax/create-virtual-table-stmt.html">create-virtual-table-stmt:</a></b>
          198  +<button id='x1475' onclick='hideorshow("x1475","x1476")'>hide</button></p>
          199  + <blockquote id='x1476'>
          200  + <img alt="syntax diagram create-virtual-table-stmt" src="images/syntax/create-virtual-table-stmt.gif" />
          201  +</blockquote>
          202  +
          203  +
          204  +<p>The CREATE VIRTUAL TABLE statement creates a new table
          205  +called <span class='yyterm'>table-name</span> derived from the class
          206  +class <span class='yyterm'>module-name</span>.  The <span class='yyterm'>module-name</span>
          207  +is the name that is registered for the virtual table by
          208  +the <a href="c3ref/create_module.html">sqlite3_create_module()</a> interface.
          209  +
          210  +<blockquote><pre>
          211  +   CREATE VIRTUAL TABLE tablename USING modulename;
          212  +</pre></blockquote>
          213  +
          214  +<p>One can also provide comma-separated arguments to the module following 
          215  +the module name:
          216  +
          217  +<blockquote><pre>
          218  +   CREATE VIRTUAL TABLE tablename USING modulename(arg1, arg2, ...);
          219  +</pre></blockquote>
          220  +
          221  +<p>The format of the arguments to the module is very general. Each 
          222  +<span class='yyterm'>module-argument</span>
          223  +may contain keywords, string literals, identifiers, numbers, and 
          224  +punctuation. Each <span class='yyterm'>module-argument</span> is passed as 
          225  +written (as text) into the
          226  +<a href="vtab.html#xcreate">constructor method</a> of the virtual table implementation 
          227  +when the virtual 
          228  +table is created and that constructor is responsible for parsing and 
          229  +interpreting the arguments. The argument syntax is sufficiently general 
          230  +that a virtual table implementation can, if it wants to, interpret its
          231  +arguments as <a href="lang_createtable.html#tablecoldef">column definitions</a> in an ordinary <a href="lang_createtable.html">CREATE TABLE</a> statement. 
          232  +The implementation could also impose some other interpretation on the 
          233  +arguments.
          234  +
          235  +<p>Once a virtual table has been created, it can be used like any other 
          236  +table with the exceptions noted above and imposed by specific virtual
          237  +table implementations. A virtual table is destroyed using the ordinary
          238  +<a href="lang_droptable.html">DROP TABLE</a> syntax.
          239  +
          240  +<h4>1.1.1 Temporary virtual tables</h4>
          241  +
          242  +<p>There is no "CREATE TEMP VIRTUAL TABLE" statement.  To create a
          243  +temporary virtual table, add the "temp" schema
          244  +before the virtual table name.
          245  +
          246  +<blockcuqote><pre>
          247  +   CREATE VIRTUAL TABLE <b>temp.</b>tablename USING module(arg1, ...);
          248  +</pre></blockquote>
          249  +
          250  +<a name="epovtab"></a>
          251  +
          252  +<h4>1.1.2 Eponymous virtual tables</h4>
          253  +
          254  +<p>Some virtual tables exist automatically in the "main" schema of
          255  +every database connection in which their
          256  +module is registered, even without a <a href="lang_createvtab.html">CREATE VIRTUAL TABLE</a> statement.
          257  +Such virtual tables are called "eponymous virtual tables".
          258  +To use an eponymous virtual table, simple use the 
          259  +module name as if it were a table.
          260  +Eponymous virtual tables exist in the "main" schema only, so they will
          261  +not work if prefixed with a different schema name.
          262  +
          263  +<p>An example of an eponymous virtual table is the <a href="dbstat.html">dbstat virtual table</a>.
          264  +To use the dbstat virtual table as an eponymous virtual table, 
          265  +simply query against the "dbstat"
          266  +module name, as if it were an ordinary table.  (Note that SQLite
          267  +must be compiled with the <a href="compile.html#enable_dbstat_vtab">SQLITE_ENABLE_DBSTAT_VTAB</a> option to include
          268  +the dbstat virtual table in the build.)
          269  +
          270  +<blockquote><pre>
          271  +   SELECT * FROM dbstat;
          272  +</pre></blockquote>
          273  +
          274  +<p>A virtual table is eponymous if its <a href="vtab.html#xcreate">xCreate</a> method is the exact same
          275  +function as the <a href="vtab.html#xconnect">xConnect</a> method, or if the <a href="vtab.html#xcreate">xCreate</a> method is NULL.
          276  +The <a href="vtab.html#xcreate">xCreate</a> method is called when a virtual table is first created
          277  +using the <a href="lang_createvtab.html">CREATE VIRTUAL TABLE</a> statement.  The <a href="vtab.html#xconnect">xConnect</a> method whenever
          278  +a database connection attaches to or reparses a schema. When these two methods
          279  +are the same, that indicates that the virtual table has no persistent
          280  +state that needs to be created and destroyed.
          281  +
          282  +<a name="epoonlyvtab"></a>
          283  +
          284  +<h5>1.1.2.1 Eponymous-only virtual tables</h5>
          285  +<p>If the <a href="vtab.html#xcreate">xCreate</a> method is NULL, then
          286  +<a href="lang_createvtab.html">CREATE VIRTUAL TABLE</a> statements are prohibited for that virtual table,
          287  +and the virtual table is an "eponymous-only virtual table".
          288  +Eponymous-only virtual tables are useful as 
          289  +<a href="vtab.html#tabfunc2">table-valued functions</a>.
          290  +
          291  +<p>
          292  +Note that SQLite versions prior to 3.9.0 did not check the xCreate method
          293  +for NULL before invoking it.  So if an eponymous-only virtual table is
          294  +registered with SQLite version 3.8.11.1 or earlier and a <a href="lang_createvtab.html">CREATE VIRTUAL TABLE</a>
          295  +command is attempted against that virtual table module, a jump to a NULL
          296  +pointer will occur, resulting in a crash.
          297  +
          298  +<h3>1.2 Implementation</h3>
          299  +
          300  +<p>Several new C-level objects are used by the virtual table implementation:
          301  +
          302  +<blockquote><pre>
          303  +  typedef struct sqlite3_vtab sqlite3_vtab;
          304  +  typedef struct sqlite3_index_info sqlite3_index_info;
          305  +  typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor;
          306  +  typedef struct sqlite3_module sqlite3_module;
          307  +</pre></blockquote>
          308  +
          309  +<p>The <a href="c3ref/module.html">sqlite3_module</a> structure defines a module object used to implement
          310  +a virtual table. Think of a module as a class from which one can 
          311  +construct multiple virtual tables having similar properties. For example,
          312  +one might have a module that provides read-only access to 
          313  +comma-separated-value (CSV) files on disk. That one module can then be
          314  +used to create several virtual tables where each virtual table refers
          315  +to a different CSV file.
          316  +
          317  +<p>The module structure contains methods that are invoked by SQLite to
          318  +perform various actions on the virtual table such as creating new
          319  +instances of a virtual table or destroying old ones, reading and
          320  +writing data, searching for and deleting, updating, or inserting rows. 
          321  +The module structure is explained in more detail below.
          322  +
          323  +<p>Each virtual table instance is represented by an <a href="c3ref/vtab.html">sqlite3_vtab</a> structure. 
          324  +The sqlite3_vtab structure looks like this:
          325  +
          326  +<blockquote><pre>
          327  +  struct sqlite3_vtab {
          328  +    const sqlite3_module *pModule;
          329  +    int nRef;
          330  +    char *zErrMsg;
          331  +  };
          332  +</pre></blockquote>
          333  +
          334  +<p>Virtual table implementations will normally subclass this structure 
          335  +to add additional private and implementation-specific fields. 
          336  +The nRef field is used internally by the SQLite core and should not 
          337  +be altered by the virtual table implementation. The virtual table 
          338  +implementation may pass error message text to the core by putting 
          339  +an error message string in zErrMsg.
          340  +Space to hold this error message string must be obtained from an
          341  +SQLite memory allocation function such as <a href="c3ref/mprintf.html">sqlite3_mprintf()</a> or
          342  +<a href="c3ref/free.html">sqlite3_malloc()</a>.
          343  +Prior to assigning a new value to zErrMsg, the virtual table 
          344  +implementation must free any preexisting content of zErrMsg using 
          345  +<a href="c3ref/free.html">sqlite3_free()</a>. Failure to do this will result in a memory leak. 
          346  +The SQLite core will free and zero the content of zErrMsg when it 
          347  +delivers the error message text to the client application or when 
          348  +it destroys the virtual table. The virtual table implementation only 
          349  +needs to worry about freeing the zErrMsg content when it overwrites 
          350  +the content with a new, different error message.
          351  +
          352  +<p>The <a href="c3ref/vtab_cursor.html">sqlite3_vtab_cursor</a> structure represents a pointer to a specific
          353  +row of a virtual table. This is what an sqlite3_vtab_cursor looks like:
          354  +
          355  +<blockquote><pre>
          356  +  struct sqlite3_vtab_cursor {
          357  +    sqlite3_vtab *pVtab;
          358  +  };
          359  +</pre></blockquote>
          360  +
          361  +<p>Once again, practical implementations will likely subclass this 
          362  +structure to add additional private fields.
          363  +
          364  +<p>The <a href="c3ref/index_info.html">sqlite3_index_info</a> structure is used to pass information into
          365  +and out of the xBestIndex method of the module that implements a 
          366  +virtual table.
          367  +
          368  +<p>Before a <a href="lang_createvtab.html">CREATE VIRTUAL TABLE</a> statement can be run, the module 
          369  +specified in that statement must be registered with the database 
          370  +connection. This is accomplished using either of the <a href="c3ref/create_module.html">sqlite3_create_module()</a>
          371  +or <a href="c3ref/create_module.html">sqlite3_create_module_v2()</a> interfaces:
          372  +
          373  +<blockquote><pre>
          374  +  int sqlite3_create_module(
          375  +    sqlite3 *db,               /* SQLite connection to register module with */
          376  +    const char *zName,         /* Name of the module */
          377  +    const sqlite3_module *,    /* Methods for the module */
          378  +    void *                     /* Client data for xCreate/xConnect */
          379  +  );
          380  +  int sqlite3_create_module_v2(
          381  +    sqlite3 *db,               /* SQLite connection to register module with */
          382  +    const char *zName,         /* Name of the module */
          383  +    const sqlite3_module *,    /* Methods for the module */
          384  +    void *,                    /* Client data for xCreate/xConnect */
          385  +    void(*xDestroy)(void*)     /* Client data destructor function */
          386  +  );
          387  +</pre></blockquote>
          388  +
          389  +<p>The <a href="c3ref/create_module.html">sqlite3_create_module()</a> and <a href="c3ref/create_module.html">sqlite3_create_module_v2()</a>
          390  +routines associates a module name with 
          391  +an <a href="c3ref/module.html">sqlite3_module</a> structure and a separate client data that is specific 
          392  +to each module.  The only difference between the two create_module methods
          393  +is that the _v2 method includes an extra parameter that specifies a
          394  +destructor for client data pointer.  The module structure is what defines
          395  +the behavior of a virtual table.  The module structure looks like this:
          396  +
          397  +<blockquote><pre>  
          398  +  struct sqlite3_module {
          399  +    int iVersion;
          400  +    int (*xCreate)(sqlite3*, void *pAux,
          401  +                 int argc, char **argv,
          402  +                 sqlite3_vtab **ppVTab,
          403  +                 char **pzErr);
          404  +    int (*xConnect)(sqlite3*, void *pAux,
          405  +                 int argc, char **argv,
          406  +                 sqlite3_vtab **ppVTab,
          407  +                 char **pzErr);
          408  +    int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*);
          409  +    int (*xDisconnect)(sqlite3_vtab *pVTab);
          410  +    int (*xDestroy)(sqlite3_vtab *pVTab);
          411  +    int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor);
          412  +    int (*xClose)(sqlite3_vtab_cursor*);
          413  +    int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr,
          414  +                  int argc, sqlite3_value **argv);
          415  +    int (*xNext)(sqlite3_vtab_cursor*);
          416  +    int (*xEof)(sqlite3_vtab_cursor*);
          417  +    int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int);
          418  +    int (*xRowid)(sqlite3_vtab_cursor*, sqlite_int64 *pRowid);
          419  +    int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite_int64 *);
          420  +    int (*xBegin)(sqlite3_vtab *pVTab);
          421  +    int (*xSync)(sqlite3_vtab *pVTab);
          422  +    int (*xCommit)(sqlite3_vtab *pVTab);
          423  +    int (*xRollback)(sqlite3_vtab *pVTab);
          424  +    int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName,
          425  +                       void (**pxFunc)(sqlite3_context*,int,sqlite3_value**),
          426  +                       void **ppArg);
          427  +    int (*Rename)(sqlite3_vtab *pVtab, const char *zNew);
          428  +    /* The methods above are in version 1 of the sqlite_module object. Those 
          429  +    ** below are for version 2 and greater. */
          430  +    int (*xSavepoint)(sqlite3_vtab *pVTab, int);
          431  +    int (*xRelease)(sqlite3_vtab *pVTab, int);
          432  +    int (*xRollbackTo)(sqlite3_vtab *pVTab, int);
          433  +  };
          434  +</pre></blockquote>
          435  +
          436  +<p>The module structure defines all of the methods for each virtual 
          437  +table object. The module structure also contains the iVersion field which
          438  +defines the particular edition of the module table structure. Currently, 
          439  +iVersion is always 1, but in future releases of SQLite the module structure 
          440  +definition might be extended with additional methods and in that case 
          441  +the iVersion value will be increased.
          442  +
          443  +<p>The rest of the module structure consists of methods used to implement
          444  +various features of the virtual table. Details on what each of these 
          445  +methods do are provided in the sequel.
          446  +
          447  +<h3>1.3 Virtual Tables And Shared Cache</h3>
          448  +
          449  +<p>Prior to SQLite <a href="releaselog/3_6_17.html">version 3.6.17</a>, the virtual table mechanism assumes 
          450  +that each <a href="c3ref/sqlite3.html">database connection</a> kept
          451  +its own copy of the database schema. Hence, the virtual table mechanism
          452  +could not be used in a database that has <a href="sharedcache.html">shared cache mode</a> enabled. 
          453  +The <a href="c3ref/create_module.html">sqlite3_create_module()</a> interface would return an error if 
          454  +<a href="sharedcache.html">shared cache mode</a> is enabled.  That restriction was relaxed
          455  +beginning with SQLite <a href="releaselog/3_6_17.html">version 3.6.17</a>.
          456  +
          457  +<h3>1.4 Creating New Virtual Table Implementations</h3>
          458  +
          459  +<p>Follow these steps to create your own virtual table:
          460  +
          461  +<p>
          462  +<ol>
          463  +<li> Write all necessary methods.
          464  +<li> Create an instance of the <a href="c3ref/module.html">sqlite3_module</a> structure containing pointers
          465  +     to all the methods from step 1.
          466  +<li> Register your <a href="c3ref/module.html">sqlite3_module</a> structure using one of the
          467  +     <a href="c3ref/create_module.html">sqlite3_create_module()</a> or <a href="c3ref/create_module.html">sqlite3_create_module_v2()</a> interfaces.
          468  +<li> Run a <a href="lang_createvtab.html">CREATE VIRTUAL TABLE</a> command that specifies the new module in 
          469  +     the USING clause. 
          470  +</ol>
          471  +
          472  +<p>The only really hard part is step 1. You might want to start with an 
          473  +existing virtual table implementation and modify it to suit your needs.
          474  +There are several virtual table implementations in the SQLite source tree 
          475  +(for testing purposes). You might use one of those as a guide. Locate 
          476  +these test virtual table implementations by searching 
          477  +for "sqlite3_create_module".
          478  +
          479  +<p>You might also want to implement your new virtual table as a 
          480  +<a href="c3ref/load_extension.html">loadable extension</a>.
          481  +
          482  +<h2>2.0 Virtual Table Methods</h2>
          483  +
          484  +<a name="xcreate"></a>
          485  +
          486  +<h3>2.1 The xCreate Method</h3>
          487  +
          488  +<blockquote><pre>
          489  +  int (*xCreate)(sqlite3 *db, void *pAux,
          490  +               int argc, char **argv,
          491  +               sqlite3_vtab **ppVTab,
          492  +               char **pzErr);
          493  +</pre></blockquote>
          494  +
          495  +<p>This method is called to create a new instance of a virtual table 
          496  +in response to a <a href="lang_createvtab.html">CREATE VIRTUAL TABLE</a> statement. 
          497  +The db parameter is a pointer to the SQLite <a href="c3ref/sqlite3.html">database connection</a> that 
          498  +is executing the <a href="lang_createvtab.html">CREATE VIRTUAL TABLE</a> statement. 
          499  +The pAux argument is the copy of the client data pointer that was the 
          500  +fourth argument to the <a href="c3ref/create_module.html">sqlite3_create_module()</a> or
          501  +<a href="c3ref/create_module.html">sqlite3_create_module_v2()</a> call that registered the 
          502  +<a href="c3ref/module.html">virtual table module</a>. 
          503  +The argv parameter is an array of argc pointers to null terminated strings. 
          504  +The first string, argv[0], is the name of the module being invoked.   The
          505  +module name is the name provided as the second argument to 
          506  +<a href="c3ref/create_module.html">sqlite3_create_module()</a> and as the argument to the USING clause of the
          507  +<a href="lang_createvtab.html">CREATE VIRTUAL TABLE</a> statement that is running.
          508  +The second, argv[1], is the name of the database in which the new virtual table is being created. The database name is "main" for the primary database, or
          509  +"temp" for TEMP database, or the name given at the end of the <a href="lang_attach.html">ATTACH</a>
          510  +statement for attached databases.  The third element of the array, argv[2], 
          511  +is the name of the new virtual table, as specified following the TABLE
          512  +keyword in the <a href="lang_createvtab.html">CREATE VIRTUAL TABLE</a> statement.
          513  +If present, the fourth and subsequent strings in the argv[] array report 
          514  +the arguments to the module name in the <a href="lang_createvtab.html">CREATE VIRTUAL TABLE</a> statement.
          515  +
          516  +<p>The job of this method is to construct the new virtual table object
          517  +(an <a href="c3ref/vtab.html">sqlite3_vtab</a> object) and return a pointer to it in *ppVTab.
          518  +
          519  +<p>As part of the task of creating a new <a href="c3ref/vtab.html">sqlite3_vtab</a> structure, this 
          520  +method <u>must</u> invoke <a href="c3ref/declare_vtab.html">sqlite3_declare_vtab()</a> to tell the SQLite 
          521  +core about the columns and datatypes in the virtual table. 
          522  +The <a href="c3ref/declare_vtab.html">sqlite3_declare_vtab()</a> API has the following prototype:
          523  +
          524  +<blockquote><pre>
          525  +    int sqlite3_declare_vtab(sqlite3 *db, const char *zCreateTable)
          526  +</pre></blockquote>
          527  +
          528  +<p>The first argument to <a href="c3ref/declare_vtab.html">sqlite3_declare_vtab()</a> must be the same 
          529  +<a href="c3ref/sqlite3.html">database connection</a> pointer as the first parameter to this method.
          530  +The second argument to <a href="c3ref/declare_vtab.html">sqlite3_declare_vtab()</a> must a zero-terminated 
          531  +UTF-8 string that contains a well-formed <a href="lang_createtable.html">CREATE TABLE</a> statement that 
          532  +defines the columns in the virtual table and their data types. 
          533  +The name of the table in this CREATE TABLE statement is ignored, 
          534  +as are all constraints. Only the column names and datatypes matter.
          535  +The CREATE TABLE statement string need not to be 
          536  +held in persistent memory.  The string can be
          537  +deallocated and/or reused as soon as the <a href="c3ref/declare_vtab.html">sqlite3_declare_vtab()</a>
          538  +routine returns.
          539  +
          540  +<p>The xCreate method need not initialize the pModule, nRef, and zErrMsg
          541  +fields of the <a href="c3ref/vtab.html">sqlite3_vtab</a> object.  The SQLite core will take care of 
          542  +that chore.
          543  +
          544  +<p>The xCreate should return <a href="rescode.html#ok">SQLITE_OK</a> if it is successful in 
          545  +creating the new virtual table, or <a href="rescode.html#error">SQLITE_ERROR</a> if it is not successful.
          546  +If not successful, the <a href="c3ref/vtab.html">sqlite3_vtab</a> structure must not be allocated. 
          547  +An error message may optionally be returned in *pzErr if unsuccessful.
          548  +Space to hold the error message string must be allocated using
          549  +an SQLite memory allocation function like 
          550  +<a href="c3ref/free.html">sqlite3_malloc()</a> or <a href="c3ref/mprintf.html">sqlite3_mprintf()</a> as the SQLite core will
          551  +attempt to free the space using <a href="c3ref/free.html">sqlite3_free()</a> after the error has
          552  +been reported up to the application.
          553  +
          554  +<p>
          555  +If the xCreate method is omitted (left as a NULL pointer) then the
          556  +virtual table is an <a href="vtab.html#epoonlyvtab">eponymous-only virtual table</a>.  New instances of
          557  +the virtual table cannot be created using <a href="lang_createvtab.html">CREATE VIRTUAL TABLE</a> and the
          558  +virtual table can only be used via its module name.
          559  +Note that SQLite versions prior to 3.9.0 do not understand
          560  +eponymous-only virtual tables and will segfault if an attempt is made
          561  +to <a href="lang_createvtab.html">CREATE VIRTUAL TABLE</a> on an eponymous-only virtual table because
          562  +the xCreate method was not checked for null.
          563  +
          564  +<p>
          565  +If the xCreate method is the exact same pointer as the <a href="vtab.html#xconnect">xConnect</a> method,
          566  +that indicates that the virtual table does not need to initialize backing
          567  +store.  Such a virtual table can be used as an <a href="vtab.html#epovtab">eponymous virtual table</a>
          568  +or as a named virtual table using <a href="lang_createvtab.html">CREATE VIRTUAL TABLE</a> or both.
          569  +
          570  +<a name="hiddencol"></a>
          571  +
          572  +<h4>2.1.1 Hidden columns in virtual tables</h4>
          573  +<p>If a column datatype contains the special keyword "HIDDEN"
          574  +(in any combination of upper and lower case letters) then that keyword
          575  +it is omitted from the column datatype name and the column is marked 
          576  +as a hidden column internally. 
          577  +A hidden column differs from a normal column in three respects:
          578  +
          579  +<p>
          580  +<ul>
          581  +<li> Hidden columns are not listed in the dataset returned by 
          582  +     "<a href="pragma.html#pragma_table_info">PRAGMA table_info</a>",
          583  +<li> Hidden columns are not included in the expansion of a "*"
          584  +     expression in the result set of a <a href="lang_select.html">SELECT</a>, and
          585  +<li> Hidden columns are not included in the implicit column-list 
          586  +     used by an <a href="lang_insert.html">INSERT</a> statement that lacks an explicit column-list. 
          587  +</ul>
          588  +
          589  +<p>For example, if the following SQL is passed to <a href="c3ref/declare_vtab.html">sqlite3_declare_vtab()</a>:
          590  +
          591  +<blockquote><pre>
          592  +   CREATE TABLE x(a HIDDEN VARCHAR(12), b INTEGER, c INTEGER Hidden);
          593  +</pre></blockquote>
          594  +
          595  +<p>Then the virtual table would be created with two hidden columns,
          596  +and with datatypes of "VARCHAR(12)" and "INTEGER".
          597  +
          598  +<p>An example use of hidden columns can be seen in the <a href="fts3.html">FTS3</a> virtual 
          599  +table implementation, where every FTS virtual table
          600  +contains an <a href="fts3.html#hiddencol">FTS hidden column</a> that is used to pass information from the
          601  +virtual table into <a href="fts3.html#snippet">FTS auxiliary functions</a> and to the <a href="fts3.html#section_3">FTS MATCH</a> operator.
          602  +
          603  +<a name="tabfunc2"></a>
          604  +
          605  +<h4>2.1.2 Table-valued functions</h4>
          606  +
          607  +<p>A <a href="vtab.html">virtual table</a> that contains <a href="vtab.html#hiddencol">hidden columns</a> can be used like
          608  +a table-valued function in the FROM clause of a <a href="lang_select.html">SELECT</a> statement.
          609  +The arguments to the table-valued function become constraints on 
          610  +the HIDDEN columns of the virtual table.
          611  +
          612  +<p>For example, the "generate_series" extension (located in the
          613  +<a href="http://www.sqlite.org/src/artifact?ci=trunk&filename=ext/misc/series.c">ext/misc/series.c</a>
          614  +file in the <a href="http://www.sqlite.org/src/tree?ci=trunk">source tree</a>)
          615  +implements an <a href="vtab.html#epovtab">eponymous virtual table</a> with the following schema:
          616  +
          617  +<blockquote><pre>
          618  +CREATE TABLE generate_series(
          619  +  value,
          620  +  start HIDDEN,
          621  +  stop HIDDEN,
          622  +  step HIDDEN
          623  +);
          624  +</pre></blockquote>
          625  +
          626  +<p>The <a href="vtab.html#xbestindex">sqlite3_module.xBestIndex</a> method in the implementation of this
          627  +table checks for equality constraints against the HIDDEN columns, and uses
          628  +those as input parameters to determine the range of integer "value" outputs
          629  +to generate.  Reasonable defaults are used for any unconstrained columns.
          630  +For example, to list all integers between 5 and 50:
          631  +
          632  +<blockquote><pre>
          633  +SELECT value FROM generate_series(5,50);
          634  +</pre></blockquote>
          635  +
          636  +<p>The previous query is equivalent to the following:
          637  +
          638  +<blockquote><pre>
          639  +SELECT value FROM generate_series WHERE start=5 AND stop=50;
          640  +</pre></blockquote>
          641  +
          642  +<p>Arguments on the virtual table name are matched to <a href="vtab.html#hiddencol">hidden columns</a>
          643  +in order.  The number of arguments can be less than the
          644  +number of hidden columns, in which case the latter hidden columns are
          645  +unconstrained.  However, an error results if there are more arguments
          646  +than there are hidden columns in the virtual table.
          647  +
          648  +
          649  +<a name="xconnect"></a>
          650  +
          651  +<h3>2.2 The xConnect Method</h3>
          652  +
          653  +<blockquote><pre>
          654  +  int (*xConnect)(sqlite3*, void *pAux,
          655  +               int argc, char **argv,
          656  +               sqlite3_vtab **ppVTab,
          657  +               char **pzErr);
          658  +</pre></blockquote>
          659  +
          660  +<p>The xConnect method is very similar to <a href="vtab.html#xcreate">xCreate</a>. 
          661  +It has the same parameters and constructs a new <a href="c3ref/vtab.html">sqlite3_vtab</a> structure 
          662  +just like xCreate. 
          663  +And it must also call <a href="c3ref/declare_vtab.html">sqlite3_declare_vtab()</a> like xCreate.
          664  +
          665  +<p>The difference is that xConnect is called to establish a new 
          666  +connection to an existing virtual table whereas xCreate is called 
          667  +to create a new virtual table from scratch.
          668  +
          669  +<p>The xCreate and xConnect methods are only different when the
          670  +virtual table has some kind of backing store that must be initialized 
          671  +the first time the virtual table is created. The xCreate method creates 
          672  +and initializes the backing store. The xConnect method just connects 
          673  +to an existing backing store.  When xCreate and xConnect are the same,
          674  +the table is an <a href="vtab.html#epovtab">eponymous virtual table</a>.
          675  +
          676  +<p>As an example, consider a virtual table implementation that 
          677  +provides read-only access to existing comma-separated-value (CSV)
          678  +files on disk. There is no backing store that needs to be created 
          679  +or initialized for such a virtual table (since the CSV files already 
          680  +exist on disk) so the xCreate and xConnect methods will be identical 
          681  +for that module.
          682  +
          683  +<p>Another example is a virtual table that implements a full-text index. 
          684  +The xCreate method must create and initialize data structures to hold 
          685  +the dictionary and posting lists for that index. The xConnect method,
          686  +on the other hand, only has to locate and use an existing dictionary 
          687  +and posting lists that were created by a prior xCreate call.
          688  +
          689  +<p>The xConnect method must return <a href="rescode.html#ok">SQLITE_OK</a> if it is successful 
          690  +in creating the new virtual table, or <a href="rescode.html#error">SQLITE_ERROR</a> if it is not 
          691  +successful. If not successful, the <a href="c3ref/vtab.html">sqlite3_vtab</a> structure must not be 
          692  +allocated. An error message may optionally be returned in *pzErr if 
          693  +unsuccessful. 
          694  +Space to hold the error message string must be allocated using
          695  +an SQLite memory allocation function like 
          696  +<a href="c3ref/free.html">sqlite3_malloc()</a> or <a href="c3ref/mprintf.html">sqlite3_mprintf()</a> as the SQLite core will
          697  +attempt to free the space using <a href="c3ref/free.html">sqlite3_free()</a> after the error has
          698  +been reported up to the application.
          699  +
          700  +<p>The xConnect method is required for every virtual table implementation, 
          701  +though the <a href="vtab.html#xcreate">xCreate</a> and xConnect pointers of the <a href="c3ref/module.html">sqlite3_module</a> object
          702  +may point to the same function if the virtual table does not need to
          703  +initialize backing store.
          704  +
          705  +<a name="xbestindex"></a>
          706  +
          707  +<h3>2.3 The xBestIndex Method</h3>
          708  +
          709  +<p>SQLite uses the xBestIndex method of a virtual table module to determine
          710  +the best way to access the virtual table. 
          711  +The xBestIndex method has a prototype like this:
          712  +
          713  +<blockquote><pre>
          714  +  int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*);
          715  +</pre></blockquote>
          716  +
          717  +<p>The SQLite core communicates with the xBestIndex method by filling 
          718  +in certain fields of the <a href="c3ref/index_info.html">sqlite3_index_info</a> structure and passing a 
          719  +pointer to that structure into xBestIndex as the second parameter. 
          720  +The xBestIndex method fills out other fields of this structure which
          721  +forms the reply. The <a href="c3ref/index_info.html">sqlite3_index_info</a> structure looks like this:
          722  +
          723  +<blockquote><pre>
          724  +  struct sqlite3_index_info {
          725  +    /* Inputs */
          726  +    const int nConstraint;     /* Number of entries in aConstraint */
          727  +    const struct sqlite3_index_constraint {
          728  +       int iColumn;              /* Column on left-hand side of constraint */
          729  +       unsigned char op;         /* Constraint operator */
          730  +       unsigned char usable;     /* True if this constraint is usable */
          731  +       int iTermOffset;          /* Used internally - xBestIndex should ignore */
          732  +    } *const aConstraint;      /* Table of WHERE clause constraints */
          733  +    const int nOrderBy;        /* Number of terms in the ORDER BY clause */
          734  +    const struct sqlite3_index_orderby {
          735  +       int iColumn;              /* Column number */
          736  +       unsigned char desc;       /* True for DESC.  False for ASC. */
          737  +    } *const aOrderBy;         /* The ORDER BY clause */
          738  +
          739  +    /* Outputs */
          740  +    struct sqlite3_index_constraint_usage {
          741  +      int argvIndex;           /* if >0, constraint is part of argv to xFilter */
          742  +      unsigned char omit;      /* Do not code a test for this constraint */
          743  +    } *const aConstraintUsage;
          744  +    int idxNum;                /* Number used to identify the index */
          745  +    char *idxStr;              /* String, possibly obtained from sqlite3_malloc */
          746  +    int needToFreeIdxStr;      /* Free idxStr using sqlite3_free() if true */
          747  +    int orderByConsumed;       /* True if output is already ordered */
          748  +    double estimatedCost;      /* Estimated cost of using this index */
          749  +    <b>/* Fields below are only available in SQLite 3.8.2 and later */</b>
          750  +    sqlite3_int64 estimatedRows;    /* Estimated number of rows returned */
          751  +    <b>/* Fields below are only available in SQLite 3.9.0 and later */</b>
          752  +    int idxFlags;              /* Mask of SQLITE_INDEX_SCAN_* flags */
          753  +  };
          754  +</pre></blockquote>
          755  +
          756  +<p>Please note the warnings on the "estimatedRows" and "idxFlags" field.
          757  +These fields were added with SQLite versions 3.8.2 and 3.9.0, respectively. 
          758  +Any extension that reads or writes these fields must first check that the 
          759  +version of the SQLite library in use is greater than or equal to 3.8.2 or
          760  +3.9.0 - perhaps using a call to <a href="c3ref/libversion.html">sqlite3_version()</a>. The result of attempting 
          761  +to access these fields in an sqlite3_index_info structure created by an 
          762  +older version of SQLite are undefined.
          763  +
          764  +<p>In addition, there are some defined constants:
          765  +
          766  +<blockquote><pre>
          767  +  #define SQLITE_INDEX_CONSTRAINT_EQ    2
          768  +  #define SQLITE_INDEX_CONSTRAINT_GT    4
          769  +  #define SQLITE_INDEX_CONSTRAINT_LE    8
          770  +  #define SQLITE_INDEX_CONSTRAINT_LT    16
          771  +  #define SQLITE_INDEX_CONSTRAINT_GE    32
          772  +  #define SQLITE_INDEX_CONSTRAINT_MATCH 64
          773  +  #define SQLITE_INDEX_SCAN_UNIQUE      1     /* Scan visits at most 1 row */
          774  +</pre></blockquote>
          775  +
          776  +<p>The SQLite core calls the xBestIndex method when it is compiling a query
          777  +that involves a virtual table. In other words, SQLite calls this method 
          778  +when it is running <a href="c3ref/prepare.html">sqlite3_prepare()</a> or the equivalent. 
          779  +By calling this method, the 
          780  +SQLite core is saying to the virtual table that it needs to access 
          781  +some subset of the rows in the virtual table and it wants to know the
          782  +most efficient way to do that access. The xBestIndex method replies 
          783  +with information that the SQLite core can then use to conduct an 
          784  +efficient search of the virtual table.
          785  +
          786  +<p>While compiling a single SQL query, the SQLite core might call 
          787  +xBestIndex multiple times with different settings in <a href="c3ref/index_info.html">sqlite3_index_info</a>.
          788  +The SQLite core will then select the combination that appears to 
          789  +give the best performance.
          790  +
          791  +<p>Before calling this method, the SQLite core initializes an instance 
          792  +of the <a href="c3ref/index_info.html">sqlite3_index_info</a> structure with information about the
          793  +query that it is currently trying to process. This information 
          794  +derives mainly from the WHERE clause and ORDER BY or GROUP BY clauses 
          795  +of the query, but also from any ON or USING clauses if the query is a 
          796  +join. The information that the SQLite core provides to the xBestIndex 
          797  +method is held in the part of the structure that is marked as "Inputs". 
          798  +The "Outputs" section is initialized to zero.
          799  +
          800  +<p>The information in the <a href="c3ref/index_info.html">sqlite3_index_info</a> structure is ephemeral
          801  +and may be overwritten or deallocated as soon as the xBestIndex method
          802  +returns.  If the xBestIndex method needs to remember any part of the
          803  +<a href="c3ref/index_info.html">sqlite3_index_info</a> structure, it should make a copy.  Care must be
          804  +take to store the copy in a place where it will be deallocated, such
          805  +as in the idxStr field with needToFreeIdxStr set to 1.
          806  +
          807  +<p>Note that xBestIndex will always be called before <a href="vtab.html#xfilter">xFilter</a>, since
          808  +the idxNum and idxStr outputs from xBestIndex are required inputs to
          809  +xFilter.  However, there is no guarantee that xFilter will be called
          810  +following a successful xBestIndex.  
          811  +
          812  +<p>The xBestIndex method is required for every virtual table implementation.
          813  +
          814  +<h4>2.3.1 Inputs</h4>
          815  +
          816  +<p>The main thing that the SQLite core is trying to communicate to 
          817  +the virtual table is the constraints that are available to limit 
          818  +the number of rows that need to be searched. The aConstraint[] array 
          819  +contains one entry for each constraint. There will be exactly 
          820  +nConstraint entries in that array.
          821  +
          822  +<p>Each constraint will correspond to a term in the WHERE clause
          823  +or in a USING or ON clause that is of the form
          824  +
          825  +<blockquote>
          826  +     column  OP  EXPR
          827  +</blockquote>
          828  +
          829  +<p>Where "column" is a column in the virtual table, OP is an operator 
          830  +like "=" or "<", and EXPR is an arbitrary expression. So, for example,
          831  +if the WHERE clause contained a term like this:
          832  +
          833  +<blockquote><pre>
          834  +     a = 5
          835  +</pre></blockquote>
          836  +
          837  +<p>Then one of the constraints would be on the "a" column with 
          838  +operator "=" and an expression of "5". Constraints need not have a
          839  +literal representation of the WHERE clause. The query optimizer might
          840  +make transformations to the 
          841  +WHERE clause in order to extract as many constraints 
          842  +as it can. So, for example, if the WHERE clause contained something 
          843  +like this:
          844  +
          845  +<blockquote><pre>
          846  +     x BETWEEN 10 AND 100 AND 999>y
          847  +</pre></blockquote>
          848  +
          849  +<p>The query optimizer might translate this into three separate constraints:
          850  +
          851  +<blockquote><pre>
          852  +     x >= 10
          853  +     x <= 100
          854  +     y < 999
          855  +</pre></blockquote>
          856  +
          857  +<p>For each constraint, the aConstraint[].iColumn field indicates which 
          858  +column appears on the left-hand side of the constraint.
          859  +The first column of the virtual table is column 0. 
          860  +The rowid of the virtual table is column -1. 
          861  +The aConstraint[].op field indicates which operator is used. 
          862  +The SQLITE_INDEX_CONSTRAINT_* constants map integer constants 
          863  +into operator values.
          864  +Columns occur in the order they were defined by the call to
          865  +<a href="c3ref/declare_vtab.html">sqlite3_declare_vtab()</a> in the <a href="vtab.html#xcreate">xCreate</a> or <a href="vtab.html#xconnect">xConnect</a> method.
          866  +Hidden columns are counted when determining the column index.
          867  +
          868  +<p>The aConstraint[] array contains information about all constraints 
          869  +that apply to the virtual table. But some of the constraints might
          870  +not be usable because of the way tables are ordered in a join. 
          871  +The xBestIndex method must therefore only consider constraints 
          872  +that have an aConstraint[].usable flag which is true.
          873  +
          874  +<p>In addition to WHERE clause constraints, the SQLite core also 
          875  +tells the xBestIndex method about the ORDER BY clause. 
          876  +(In an aggregate query, the SQLite core might put in GROUP BY clause 
          877  +information in place of the ORDER BY clause information, but this fact
          878  +should not make any difference to the xBestIndex method.) 
          879  +If all terms of the ORDER BY clause are columns in the virtual table, 
          880  +then nOrderBy will be the number of terms in the ORDER BY clause 
          881  +and the aOrderBy[] array will identify the column for each term 
          882  +in the order by clause and whether or not that column is ASC or DESC.
          883  +
          884  +<h4>2.3.2 Outputs</h4>
          885  +
          886  +<p>Given all of the information above, the job of the xBestIndex 
          887  +method it to figure out the best way to search the virtual table.
          888  +
          889  +<p>The xBestIndex method fills the idxNum and idxStr fields with 
          890  +information that communicates an indexing strategy to the <a href="vtab.html#xfilter">xFilter</a> 
          891  +method. The information in idxNum and idxStr is arbitrary as far 
          892  +as the SQLite core is concerned. The SQLite core just copies the 
          893  +information through to the <a href="vtab.html#xfilter">xFilter</a> method. Any desired meaning can 
          894  +be assigned to idxNum and idxStr as long as xBestIndex and xFilter 
          895  +agree on what that meaning is.
          896  +
          897  +<p>The idxStr value may be a string obtained from an SQLite
          898  +memory allocation function such as <a href="c3ref/mprintf.html">sqlite3_mprintf()</a>. 
          899  +If this is the case, then the needToFreeIdxStr flag must be set to 
          900  +true so that the SQLite core will know to call <a href="c3ref/free.html">sqlite3_free()</a> on 
          901  +that string when it has finished with it, and thus avoid a memory leak.
          902  +
          903  +<p>If the virtual table will output rows in the order specified by 
          904  +the ORDER BY clause, then the orderByConsumed flag may be set to 
          905  +true. If the output is not automatically in the correct order 
          906  +then orderByConsumed must be left in its default false setting. 
          907  +This will indicate to the SQLite core that it will need to do a 
          908  +separate sorting pass over the data after it comes out of the virtual table.
          909  +
          910  +<p>The estimatedCost field should be set to the estimated number
          911  +of disk access operations required to execute this query against 
          912  +the virtual table. The SQLite core will often call xBestIndex 
          913  +multiple times with different constraints, obtain multiple cost
          914  +estimates, then choose the query plan that gives the lowest estimate.
          915  +
          916  +<p>If the current version of SQLite is 3.8.2 or greater, the estimatedRows
          917  +field may be set to an estimate of the number of rows returned by the
          918  +proposed query plan. If this value is not explicitly set, the default 
          919  +estimate of 25 rows is used.
          920  +
          921  +<p>If the current version of SQLite is 3.9.0 or greater, the idxFlags field
          922  +may be set to SQLITE_INDEX_SCAN_UNIQUE to indicate that the virtual table
          923  +will return only zero or one rows given the input constraints.  Additional
          924  +bits of the idxFlags field might be understood in later versions of SQLite.
          925  +
          926  +<p>The aConstraintUsage[] array contains one element for each of 
          927  +the nConstraint constraints in the inputs section of the 
          928  +<a href="c3ref/index_info.html">sqlite3_index_info</a> structure. 
          929  +The aConstraintUsage[] array is used by xBestIndex to tell the 
          930  +core how it is using the constraints.
          931  +
          932  +<p>The xBestIndex method may set aConstraintUsage[].argvIndex 
          933  +entries to values greater than zero. 
          934  +Exactly one entry should be set to 1, another to 2, another to 3, 
          935  +and so forth up to as many or as few as the xBestIndex method wants. 
          936  +The EXPR of the corresponding constraints will then be passed 
          937  +in as the argv[] parameters to xFilter.
          938  +
          939  +<p>For example, if the aConstraint[3].argvIndex is set to 1, then 
          940  +when xFilter is called, the argv[0] passed to xFilter will have 
          941  +the EXPR value of the aConstraint[3] constraint.
          942  +
          943  +<p>By default, the SQLite core double checks all constraints on 
          944  +each row of the virtual table that it receives. If such a check 
          945  +is redundant, the xBestFilter method can suppress that double-check by 
          946  +setting aConstraintUsage[].omit.
          947  +
          948  +<a name="xdisconnect"></a>
          949  +
          950  +<h3>2.4 The xDisconnect Method</h3>
          951  +
          952  +<blockquote><pre>
          953  +  int (*xDisconnect)(sqlite3_vtab *pVTab);
          954  +</pre></blockquote>
          955  +
          956  +<p>This method releases a connection to a virtual table. 
          957  +Only the <a href="c3ref/vtab.html">sqlite3_vtab</a> object is destroyed.
          958  +The virtual table is not destroyed and any backing store 
          959  +associated with the virtual table persists. 
          960  +
          961  +This method undoes the work of <a href="vtab.html#xconnect">xConnect</a>.
          962  +
          963  +<p>This method is a destructor for a connection to the virtual table.
          964  +Contrast this method with <a href="vtab.html#sqlite3_module.xDestroy">xDestroy</a>.  The xDestroy is a destructor
          965  +for the entire virtual table.
          966  +
          967  +<p>The xDisconnect method is required for every virtual table implementation,
          968  +though it is acceptable for the xDisconnect and <a href="vtab.html#sqlite3_module.xDestroy">xDestroy</a> methods to be
          969  +the same function if that makes sense for the particular virtual table.
          970  +
          971  +<a name="sqlite3_module.xDestroy"></a>
          972  +
          973  +<h3>2.5 The xDestroy Method</h3>
          974  +
          975  +<blockquote><pre>
          976  +  int (*xDestroy)(sqlite3_vtab *pVTab);
          977  +</pre></blockquote>
          978  +
          979  +<p>This method releases a connection to a virtual table, just like 
          980  +the <a href="vtab.html#xdisconnect">xDisconnect</a> method, and it also destroys the underlying 
          981  +table implementation. This method undoes the work of <a href="vtab.html#xcreate">xCreate</a>.
          982  +
          983  +<p>The <a href="vtab.html#xdisconnect">xDisconnect</a> method is called whenever a database connection
          984  +that uses a virtual table is closed. The xDestroy method is only 
          985  +called when a <a href="lang_droptable.html">DROP TABLE</a> statement is executed against the virtual table.
          986  +
          987  +<p>The xDestroy method is required for every virtual table implementation,
          988  +though it is acceptable for the <a href="vtab.html#xdisconnect">xDisconnect</a> and xDestroy methods to be
          989  +the same function if that makes sense for the particular virtual table.
          990  +
          991  +<a name="xopen"></a>
          992  +
          993  +<h3>2.6 The xOpen Method</h3>
          994  +
          995  +<blockquote><pre>
          996  +  int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor);
          997  +</pre></blockquote>
          998  +
          999  +<p>The xOpen method creates a new cursor used for accessing (read and/or
         1000  +writing) a virtual table.  A successful invocation of this method 
         1001  +will allocate the memory for the <a href="c3ref/vtab_cursor.html">sqlite3_vtab_cursor</a> (or a subclass),
         1002  +initialize the new object, and make *ppCursor point to the new object.
         1003  +The successful call then returns <a href="rescode.html#ok">SQLITE_OK</a>.
         1004  +
         1005  +<p>For every successful call to this method, the SQLite core will
         1006  +later invoke the <a href="vtab.html#xclose">xClose</a> method to destroy 
         1007  +the allocated cursor.
         1008  +
         1009  +<p>The xOpen method need not initialize the pVtab field of the
         1010  +<a href="c3ref/vtab_cursor.html">sqlite3_vtab_cursor</a> structure.  The SQLite core will take care
         1011  +of that chore automatically.
         1012  +
         1013  +<p>A virtual table implementation must be able to support an arbitrary
         1014  +number of simultaneously open cursors.
         1015  +
         1016  +<p>When initially opened, the cursor is in an undefined state.
         1017  +The SQLite core will invoke the <a href="vtab.html#xfilter">xFilter</a> method
         1018  +on the cursor prior to any attempt to position or read from the cursor.
         1019  +
         1020  +<p>The xOpen method is required for every virtual table implementation.
         1021  +
         1022  +<a name="xclose"></a>
         1023  +
         1024  +<h3>2.7 The xClose Method</h3>
         1025  +
         1026  +<blockquote><pre>
         1027  +  int (*xClose)(sqlite3_vtab_cursor*);
         1028  +</pre></blockquote>
         1029  +
         1030  +<p>The xClose method closes a cursor previously opened by 
         1031  +<a href="vtab.html#xopen">xOpen</a>. 
         1032  +The SQLite core will always call xClose once for each cursor opened 
         1033  +using xOpen.
         1034  +
         1035  +<p>This method must release all resources allocated by the
         1036  +corresponding xOpen call. The routine will not be called again even if it
         1037  +returns an error.  The SQLite core will not use the
         1038  +<a href="c3ref/vtab_cursor.html">sqlite3_vtab_cursor</a> again after it has been closed.
         1039  +
         1040  +<p>The xClose method is required for every virtual table implementation.
         1041  +
         1042  +<a name="xeof"></a>
         1043  +
         1044  +<h3>2.8 The xEof Method</h3>
         1045  +
         1046  +<blockquote><pre>
         1047  +  int (*xEof)(sqlite3_vtab_cursor*);
         1048  +</pre></blockquote>
         1049  +
         1050  +<p>The xEof method must return false (zero) if the specified cursor 
         1051  +currently points to a valid row of data, or true (non-zero) otherwise. 
         1052  +This method is called by the SQL engine immediately after each 
         1053  +<a href="vtab.html#xfilter">xFilter</a> and <a href="vtab.html#xnext">xNext</a> invocation.
         1054  +
         1055  +<p>The xEof method is required for every virtual table implementation.
         1056  +
         1057  +<a name="xfilter"></a>
         1058  +
         1059  +<h3>2.9 The xFilter Method</h3>
         1060  +
         1061  +<blockquote><pre>
         1062  +  int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr,
         1063  +                int argc, sqlite3_value **argv);
         1064  +</pre></blockquote>
         1065  +
         1066  +<p>This method begins a search of a virtual table. 
         1067  +The first argument is a cursor opened by <a href="vtab.html#xopen">xOpen</a>. 
         1068  +The next two arguments define a particular search index previously 
         1069  +chosen by <a href="vtab.html#xbestindex">xBestIndex</a>. The specific meanings of idxNum and idxStr 
         1070  +are unimportant as long as xFilter and xBestIndex agree on what 
         1071  +that meaning is.
         1072  +
         1073  +<p>The xBestIndex function may have requested the values of 
         1074  +certain expressions using the aConstraintUsage[].argvIndex values 
         1075  +of the <a href="c3ref/index_info.html">sqlite3_index_info</a> structure. 
         1076  +Those values are passed to xFilter using the argc and argv parameters.
         1077  +
         1078  +<p>If the virtual table contains one or more rows that match the
         1079  +search criteria, then the cursor must be left point at the first row.
         1080  +Subsequent calls to <a href="vtab.html#xeof">xEof</a> must return false (zero).
         1081  +If there are no rows match, then the cursor must be left in a state 
         1082  +that will cause the <a href="vtab.html#xeof">xEof</a> to return true (non-zero).
         1083  +The SQLite engine will use
         1084  +the <a href="vtab.html#xcolumn">xColumn</a> and <a href="vtab.html#xrowid">xRowid</a> methods to access that row content.
         1085  +The <a href="vtab.html#xnext">xNext</a> method will be used to advance to the next row.
         1086  +
         1087  +<p>This method must return <a href="rescode.html#ok">SQLITE_OK</a> if successful, or an sqlite 
         1088  +<a href="rescode.html">error code</a> if an error occurs.
         1089  +
         1090  +<p>The xFilter method is required for every virtual table implementation.
         1091  +
         1092  +<a name="xnext"></a>
         1093  +
         1094  +<h3>2.10 The xNext Method</h3>
         1095  +
         1096  +<blockquote><pre>
         1097  +  int (*xNext)(sqlite3_vtab_cursor*);
         1098  +</pre></blockquote>
         1099  +
         1100  +<p>The xNext method advances a <a href="c3ref/vtab_cursor.html">virtual table cursor</a>
         1101  +to the next row of a result set initiated by <a href="vtab.html#xfilter">xFilter</a>. 
         1102  +If the cursor is already pointing at the last row when this 
         1103  +routine is called, then the cursor no longer points to valid 
         1104  +data and a subsequent call to the <a href="vtab.html#xeof">xEof</a> method must return true (non-zero). 
         1105  +If the cursor is successfully advanced to another row of content, then
         1106  +subsequent calls to <a href="vtab.html#xeof">xEof</a> must return false (zero).
         1107  +
         1108  +<p>This method must return <a href="rescode.html#ok">SQLITE_OK</a> if successful, or an sqlite 
         1109  +<a href="rescode.html">error code</a> if an error occurs.
         1110  +
         1111  +<p>The xNext method is required for every virtual table implementation.
         1112  +
         1113  +<a name="xcolumn"></a>
         1114  +
         1115  +<h3>2.11 The xColumn Method</h3>
         1116  +
         1117  +<blockquote><pre>
         1118  +  int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int N);
         1119  +</pre></blockquote>
         1120  +
         1121  +<p>The SQLite core invokes this method in order to find the value for 
         1122  +the N-th column of the current row. N is zero-based so the first column 
         1123  +is numbered 0. 
         1124  +The xColumn method may return its result back to SQLite using one of the
         1125  +following interface:
         1126  +
         1127  +<p>
         1128  +<ul>
         1129  +<li> <a href="c3ref/result_blob.html">sqlite3_result_blob()</a>
         1130  +<li> <a href="c3ref/result_blob.html">sqlite3_result_double()</a>
         1131  +<li> <a href="c3ref/result_blob.html">sqlite3_result_int()</a>
         1132  +<li> <a href="c3ref/result_blob.html">sqlite3_result_int64()</a>
         1133  +<li> <a href="c3ref/result_blob.html">sqlite3_result_null()</a>
         1134  +<li> <a href="c3ref/result_blob.html">sqlite3_result_text()</a>
         1135  +<li> <a href="c3ref/result_blob.html">sqlite3_result_text16()</a>
         1136  +<li> <a href="c3ref/result_blob.html">sqlite3_result_text16le()</a>
         1137  +<li> <a href="c3ref/result_blob.html">sqlite3_result_text16be()</a>
         1138  +<li> <a href="c3ref/result_blob.html">sqlite3_result_zeroblob()</a>
         1139  +</ul>
         1140  +</p>
         1141  +
         1142  +<p>If the xColumn method implementation calls none of the functions above,
         1143  +then the value of the column defaults to an SQL NULL.
         1144  +
         1145  +<p>To raise an error, the xColumn method should use one of the result_text() 
         1146  +methods to set the error message text, then return an appropriate
         1147  +<a href="rescode.html">error code</a>.  The xColumn method must return <a href="rescode.html#ok">SQLITE_OK</a> on success.
         1148  +
         1149  +<p>The xColumn method is required for every virtual table implementation.
         1150  +
         1151  +<a name="xrowid"></a>
         1152  +
         1153  +<h3>2.12 The xRowid Method</h3>
         1154  +
         1155  +<blockquote><pre>
         1156  +  int (*xRowid)(sqlite3_vtab_cursor *pCur, sqlite_int64 *pRowid);
         1157  +</pre></blockquote>
         1158  +
         1159  +<p>A successful invocation of this method will cause *pRowid to be
         1160  +filled with the <a href="lang_createtable.html#rowid">rowid</a> of row that the
         1161  +<a href="c3ref/vtab_cursor.html">virtual table cursor</a> pCur is currently pointing at.
         1162  +This method returns <a href="rescode.html#ok">SQLITE_OK</a> on success.
         1163  +It returns an appropriate <a href="rescode.html">error code</a> on failure.</p>
         1164  +
         1165  +<p>The xRowid method is required for every virtual table implementation.
         1166  +
         1167  +<a name="xupdate"></a>
         1168  +
         1169  +<h3>2.13 The xUpdate Method</h3>
         1170  +
         1171  +<blockquote><pre>
         1172  +  int (*xUpdate)(
         1173  +    sqlite3_vtab *pVTab,
         1174  +    int argc,
         1175  +    sqlite3_value **argv,
         1176  +    sqlite_int64 *pRowid
         1177  +  );
         1178  +</pre></blockquote>
         1179  +
         1180  +<p>All changes to a virtual table are made using the xUpdate method.
         1181  +This one method can be used to insert, delete, or update.
         1182  +
         1183  +<p>The argc parameter specifies the number of entries in the argv array. 
         1184  +The value of argc will be 1 for a pure delete operation or N+2 for an insert
         1185  +or replace or update where N is the number of columns in the table.  
         1186  +In the previous sentence, N includes any hidden columns.
         1187  +
         1188  +<p>Every argv entry will have a non-NULL value in C but may contain the 
         1189  +SQL value NULL.  In other words, it is always true that
         1190  +<tt>argv&#91;i&#93;!=0</tt> for <b>i</b> between 0 and <tt>argc-1</tt>.
         1191  +However, it might be the case that
         1192  +<tt>sqlite3_value_type(argv&#91;i&#93;)==SQLITE_NULL</tt>.
         1193  +
         1194  +<p>The argv[0] parameter is the <a href="lang_createtable.html#rowid">rowid</a> of a row in the virtual table 
         1195  +to be deleted. If argv[0] is an SQL NULL, then no deletion occurs.
         1196  +
         1197  +<p>The argv[1] parameter is the rowid of a new row to be inserted 
         1198  +into the virtual table. If argv[1] is an SQL NULL, then the implementation 
         1199  +must choose a rowid for the newly inserted row. Subsequent argv[] 
         1200  +entries contain values of the columns of the virtual table, in the 
         1201  +order that the columns were declared. The number of columns will
         1202  +match the table declaration that the <a href="vtab.html#xconnect">xConnect</a> or <a href="vtab.html#xcreate">xCreate</a> method made 
         1203  +using the <a href="c3ref/declare_vtab.html">sqlite3_declare_vtab()</a> call.  All hidden columns are included.
         1204  +
         1205  +<p>When doing an insert without a rowid (argc>1, argv[1] is an SQL NULL), the 
         1206  +implementation must set *pRowid to the rowid of the newly inserted row; 
         1207  +this will become the value returned by the <a href="c3ref/last_insert_rowid.html">sqlite3_last_insert_rowid()</a>
         1208  +function. Setting this value in all the other cases is a harmless no-op;
         1209  +the SQLite engine ignores the *pRowid return value if argc==1 or 
         1210  +argv[1] is not an SQL NULL.
         1211  +
         1212  +<p>Each call to xUpdate will fall into one of cases shown below.
         1213  +Not that references to <b>argv&#91;i&#93</b> mean the SQL value
         1214  +held within the argv&#91;i&#93; object, not the argv&#91;i&#93;
         1215  +object itself.
         1216  +
         1217  +<blockquote>
         1218  +<dl>
         1219  +<dt><b>argc = 1</b>
         1220  +<dd><p>The single row with rowid equal to argv[0] is deleted. No insert occurs.
         1221  +
         1222  +<dt><b>argc > 1 <br> argv[0] = NULL</b>
         1223  +<dd><p>A new row is inserted with a rowid argv[1] and column values in
         1224  +       argv[2] and following.  If argv[1] is an SQL NULL,
         1225  +       the a new unique rowid is generated automatically.
         1226  +
         1227  +<dt><b>argc > 1 <br> argv[0] &ne; NULL <br> argv[0] = argv[1]</b>
         1228  +<dd><p>The row with rowid argv[0] is updated with new values 
         1229  +       in argv[2] and following parameters.
         1230  +
         1231  +<dt><b>argc > 1 <br> argv[0] &ne; NULL <br> argv[0] &ne; argv[1]</b>
         1232  +<dd><p> The row with rowid argv[0] is updated with rowid argv[1] 
         1233  +and new values in argv[2] and following parameters. This will occur 
         1234  +when an SQL statement updates a rowid, as in the statement:
         1235  +<blockquote>
         1236  +   <a href="lang_update.html">UPDATE</a> table SET rowid=rowid+1 WHERE ...; 
         1237  +</blockquote>
         1238  +</dl>
         1239  +</blockquote>
         1240  +
         1241  +<p>The xUpdate method must return <a href="rescode.html#ok">SQLITE_OK</a> if and only if it is
         1242  +successful.  If a failure occurs, the xUpdate must return an appropriate
         1243  +<a href="rescode.html">error code</a>.  On a failure, the pVTab->zErrMsg element may optionally
         1244  +be replaced with error message text stored in memory allocated from SQLite 
         1245  +using functions such as <a href="c3ref/mprintf.html">sqlite3_mprintf()</a> or <a href="c3ref/free.html">sqlite3_malloc()</a>.
         1246  +
         1247  +<p>If the xUpdate method violates some constraint of the virtual table
         1248  +(including, but not limited to, attempting to store a value of the wrong 
         1249  +datatype, attempting to store a value that is too
         1250  +large or too small, or attempting to change a read-only value) then the
         1251  +xUpdate must fail with an appropriate <a href="rescode.html">error code</a>.
         1252  +
         1253  +<p>There might be one or more <a href="c3ref/vtab_cursor.html">sqlite3_vtab_cursor</a> objects open and in use 
         1254  +on the virtual table instance and perhaps even on the row of the virtual
         1255  +table when the xUpdate method is invoked.  The implementation of
         1256  +xUpdate must be prepared for attempts to delete or modify rows of the table
         1257  +out from other existing cursors.  If the virtual table cannot accommodate
         1258  +such changes, the xUpdate method must return an <a href="rescode.html">error code</a>.
         1259  +
         1260  +<p>The xUpdate method is optional.
         1261  +If the xUpdate pointer in the <a href="c3ref/module.html">sqlite3_module</a> for a virtual table
         1262  +is a NULL pointer, then the virtual table is read-only.
         1263  +
         1264  +
         1265  +<a name="xfindfunction"></a>
         1266  +
         1267  +<h3>2.14 The xFindFunction Method</h3>
         1268  +
         1269  +<blockquote><pre>
         1270  +  int (*xFindFunction)(
         1271  +    sqlite3_vtab *pVtab,
         1272  +    int nArg,
         1273  +    const char *zName,
         1274  +    void (**pxFunc)(sqlite3_context*,int,sqlite3_value**),
         1275  +    void **ppArg
         1276  +  );
         1277  +</pre></blockquote>
         1278  +
         1279  +<p>This method is called during <a href="c3ref/prepare.html">sqlite3_prepare()</a> to give the virtual
         1280  +table implementation an opportunity to overload functions. 
         1281  +This method may be set to NULL in which case no overloading occurs.
         1282  +
         1283  +<p>When a function uses a column from a virtual table as its first 
         1284  +argument, this method is called to see if the virtual table would 
         1285  +like to overload the function. The first three parameters are inputs: 
         1286  +the virtual table, the number of arguments to the function, and the 
         1287  +name of the function. If no overloading is desired, this method
         1288  +returns 0. To overload the function, this method writes the new 
         1289  +function implementation into *pxFunc and writes user data into *ppArg 
         1290  +and returns 1.
         1291  +
         1292  +<p>Note that infix functions (<a href="lang_expr.html#like">LIKE</a>, <a href="lang_expr.html#glob">GLOB</a>, <a href="lang_expr.html#regexp">REGEXP</a>, and <a href="lang_expr.html#match">MATCH</a>) reverse 
         1293  +the order of their arguments. So "like(A,B)" is equivalent to "B like A". 
         1294  +For the form "B like A" the B term is considered the first argument 
         1295  +to the function. But for "like(A,B)" the A term is considered the 
         1296  +first argument.
         1297  +
         1298  +<p>The function pointer returned by this routine must be valid for
         1299  +the lifetime of the <a href="c3ref/vtab.html">sqlite3_vtab</a> object given in the first parameter.
         1300  +
         1301  +<a name="xBegin"></a>
         1302  +
         1303  +<h3>2.15 The xBegin Method</h3>
         1304  +
         1305  +<blockquote><pre>
         1306  +  int (*xBegin)(sqlite3_vtab *pVTab);
         1307  +</pre></blockquote>
         1308  +
         1309  +<p>This method begins a transaction on a virtual table.
         1310  +This is method is optional.  The xBegin pointer of <a href="c3ref/module.html">sqlite3_module</a>
         1311  +may be NULL.
         1312  +
         1313  +<p>This method is always followed by one call to either the
         1314  +<a href="vtab.html#xcommit">xCommit</a> or <a href="vtab.html#xrollback">xRollback</a> method.  Virtual table transactions do
         1315  +not nest, so the xBegin method will not be invoked more than once
         1316  +on a single virtual table
         1317  +without an intervening call to either <a href="vtab.html#xcommit">xCommit</a> or <a href="vtab.html#xrollback">xRollback</a>.
         1318  +Multiple calls to other methods can and likely will occur in between
         1319  +the xBegin and the corresponding <a href="vtab.html#xcommit">xCommit</a> or <a href="vtab.html#xrollback">xRollback</a>.
         1320  +
         1321  +<a name="xsync"></a>
         1322  +
         1323  +<h3>2.16 The xSync Method</h3>
         1324  +
         1325  +<blockquote><pre>
         1326  +  int (*xSync)(sqlite3_vtab *pVTab);
         1327  +</pre></blockquote>
         1328  +
         1329  +
         1330  +<p>This method signals the start of a two-phase commit on a virtual
         1331  +table.
         1332  +This is method is optional.  The xSync pointer of <a href="c3ref/module.html">sqlite3_module</a>
         1333  +may be NULL.
         1334  +
         1335  +<p>This method is only invoked after call to the <a href="vtab.html#xBegin">xBegin</a> method and
         1336  +prior to an <a href="vtab.html#xcommit">xCommit</a> or <a href="vtab.html#xrollback">xRollback</a>.  In order to implement two-phase
         1337  +commit, the xSync method on all virtual tables is invoked prior to
         1338  +invoking the <a href="vtab.html#xcommit">xCommit</a> method on any virtual table.  If any of the 
         1339  +xSync methods fail, the entire transaction is rolled back.
         1340  +
         1341  +<a name="xcommit"></a>
         1342  +
         1343  +<h3>2.17 The xCommit Method</h3>
         1344  +
         1345  +<blockquote><pre>
         1346  +  int (*xCommit)(sqlite3_vtab *pVTab);
         1347  +</pre></blockquote>
         1348  +
         1349  +<p>This method causes a virtual table transaction to commit.
         1350  +This is method is optional.  The xCommit pointer of <a href="c3ref/module.html">sqlite3_module</a>
         1351  +may be NULL.
         1352  +
         1353  +<p>A call to this method always follows a prior call to <a href="vtab.html#xBegin">xBegin</a> and
         1354  +<a href="vtab.html#xsync">xSync</a>.
         1355  +
         1356  +
         1357  +<a name="xrollback"></a>
         1358  +
         1359  +<h3>2.18 The xRollback Method</h3>
         1360  +
         1361  +<blockquote><pre>
         1362  +  int (*xRollback)(sqlite3_vtab *pVTab);
         1363  +</pre></blockquote>
         1364  +
         1365  +<p>This method causes a virtual table transaction to rollback.
         1366  +This is method is optional.  The xRollback pointer of <a href="c3ref/module.html">sqlite3_module</a>
         1367  +may be NULL.
         1368  +
         1369  +<p>A call to this method always follows a prior call to <a href="vtab.html#xBegin">xBegin</a>.
         1370  +
         1371  +
         1372  +<a name="xrename"></a>
         1373  +
         1374  +<h3>2.19 The xRename Method</h3>
         1375  +
         1376  +<blockquote><pre>
         1377  +  int (*xRename)(sqlite3_vtab *pVtab, const char *zNew);
         1378  +</pre></blockquote>
         1379  +
         1380  +<p>This method provides notification that the virtual table implementation
         1381  +that the virtual table will be given a new name. 
         1382  +If this method returns <a href="rescode.html#ok">SQLITE_OK</a> then SQLite renames the table.
         1383  +If this method returns an <a href="rescode.html">error code</a> then the renaming is prevented.
         1384  +
         1385  +<p>The xRename method is required for every virtual table implementation.
         1386  +
         1387  +<a name="xsavepoint"></a>
         1388  +
         1389  +<h3>2.20 The xSavepoint, xRelease, and xRollbackTo Methods</h3>
         1390  +
         1391  +<blockquote><pre>
         1392  +  int (*xSavepoint)(sqlite3_vtab *pVtab, int);
         1393  +  int (*xRelease)(sqlite3_vtab *pVtab, int);
         1394  +  int (*xRollbackTo)(sqlite3_vtab *pVtab, int);
         1395  +</pre></blockquote>
         1396  +
         1397  +<p>
         1398  +These methods provide the virtual table implementation an opportunity to
         1399  +implement nested transactions.  They are always optional and will only be
         1400  +called in SQLite <a href="releaselog/3_7_7.html">version 3.7.7</a> and later.
         1401  +</p>
         1402  +
         1403  +<p>
         1404  +When xSavepoint(X,N) is invoked, that is a signal to the virtual table X
         1405  +that it should save its current state as savepoint N.  
         1406  +A subsequent call
         1407  +to xRollbackTo(X,R) means that the state of the virtual table should return
         1408  +to what it was when xSavepoint(X,R) was last called.  
         1409  +The call
         1410  +to xRollbackTo(X,R) will invalidate all savepoints with N>R; none of the
         1411  +invalided savepoints will be rolled back or released without first
         1412  +being reinitialized by a call to xSavepoint().  
         1413  +A call to xRelease(X,M) invalidates all savepoints where N>=M.
         1414  +</p>
         1415  +
         1416  +<p>
         1417  +None of the xSavepoint(), xRelease(), or xRollbackTo() methods will ever
         1418  +be called except in between calls to xBegin() and 
         1419  +either xCommit() or xRollback().
         1420  +</p>
         1421  +

Changes to Doc/buildChm.tcl.

    41     41       exec fossil.exe sha1sum [file nativename $fileName]
    42     42     } result] == 0} then {
    43     43       return [string trim [lindex [split $result " "] 0]]
    44     44     }
    45     45     return ""
    46     46   }
    47     47   
           48  +#
           49  +# NOTE: This procedure unescapes certain HTML tags that are used within the
           50  +#       documentation for the virtual table methods.
           51  +#
           52  +proc unescapeHtmlTags { fileName cdata } {
           53  +  #
           54  +  # NOTE: Read all the textual data from the file.
           55  +  #
           56  +  set data [readFile $fileName]
           57  +
           58  +  #
           59  +  # NOTE: No replacements made yet.
           60  +  #
           61  +  set count 0
           62  +
           63  +  #
           64  +  # NOTE: If requested by the caller, unwrap all content contained with XML
           65  +  #       CDATA sections as well.
           66  +  #
           67  +  if {$cdata} then {
           68  +    #
           69  +    # NOTE: Grab everything within the CDATA tags and use verbatim.
           70  +    #
           71  +    incr count [regsub -all -- {<![CDATA[(.*?)]]>} $data {\1} data]
           72  +  }
           73  +
           74  +  #
           75  +  # TODO: Handle all the HTML tags we know may be present in the virtual
           76  +  #       table method documentation.  This may need adjustments in the
           77  +  #       future.
           78  +  #
           79  +  foreach to [list \
           80  +      {<b>} {</b>} {<br>} {<dd>} {</dd>} {<dl>} {</dl>} {<dt>} \
           81  +      {</dt>} {<li>} {</li>} {<ol>} {</ol>} {<tt>} {</tt>} \
           82  +      {<ul>} {</ul>}] {
           83  +    #
           84  +    # NOTE: Figure out the escaped form of this tag and then replace it
           85  +    #       with the unescaped form.
           86  +    #
           87  +    set from [string map [list < &lt\; > &gt\;] $to]
           88  +    incr count [regsub -all -- $from $data $to data]
           89  +  }
           90  +
           91  +  #
           92  +  # NOTE: Issue a warning if the HTML tag patterns were not matched.
           93  +  #
           94  +  if {$count == 0} then {
           95  +    puts stdout "*WARNING* File \"$fileName\" has no supported HTML tags"
           96  +  }
           97  +
           98  +  #
           99  +  # NOTE: If some replacements were performed on the data from the file,
          100  +  #       then overwrite it with the new data.
          101  +  #
          102  +  if {$count > 0} then {
          103  +    writeFile $fileName $data
          104  +  }
          105  +}
          106  +
    48    107   #
    49    108   # HACK: This procedure checks all the "href" attribute values in the specified
    50    109   #       core documentation file.  For each value, this procedure checks if the
    51    110   #       reference conforms to one of the following general categories:
    52    111   #
    53    112   #       1. A relative reference to a named anchor within the same document.
    54    113   #       2. An absolute reference using HTTP or HTTPS.
................................................................................
   135    194       # NOTE: Perform the replacements, if any, keeping track of how many were
   136    195       #       done.
   137    196       #
   138    197       incr count [regsub -all -- $pattern $data $subSpec data]
   139    198     }
   140    199   
   141    200     #
   142         -  # NOTE: If some replacements were performed on the data from the file, then
   143         -  #       overwrite it with the new data; otherwise, issue a warning.
          201  +  # NOTE: Issue a warning if the "href" pattern was not matched.
          202  +  #
          203  +  if {$count == 0} then {
          204  +    puts stdout "*WARNING* File \"$fileName\" does not match: href=\"(.*?)\""
          205  +  }
          206  +
          207  +  #
          208  +  # NOTE: If some replacements were performed on the data from the file,
          209  +  #       then overwrite it with the new data.
   144    210     #
   145    211     if {$count > 0} then {
   146    212       writeFile $fileName $data
   147         -  } else {
   148         -    puts stdout "*WARNING* File \"$fileName\" does not match: href=\"(.*?)\""
   149    213     }
   150    214   }
   151    215   
   152    216   #
   153    217   # HACK: Copy our local [fixed] copy of the MSDN documenter assembly into the
   154    218   #       installed location of NDoc3, if necessary.  Actually copying the file
   155    219   #       will require elevated administrator privileges; otherwise, it will
................................................................................
   292    356     if {![file isfile $fileName]} then {
   293    357       puts stdout "Cannot find core syntax file: $fileName"
   294    358       exit 1
   295    359     }
   296    360   
   297    361     transformCoreDocumentationFile $fileName https://www.sqlite.org/
   298    362   }
          363  +
          364  +###############################################################################
          365  +
          366  +foreach fileName [glob -nocomplain [file join $temporaryPath \
          367  +    System.Data.SQLite~System.Data.SQLite.ISQLiteNativeModule*.html]] {
          368  +  set fileName [file join $path $fileName]
          369  +
          370  +  if {![file isfile $fileName]} then {
          371  +    puts stdout "Cannot find temporary provider file: $fileName"
          372  +    exit 1
          373  +  }
          374  +
          375  +  unescapeHtmlTags $fileName false
          376  +}
   299    377   
   300    378   ###############################################################################
   301    379   
   302    380   set patterns(.hhc,1) {<!--This document contains Table of Contents information\
   303    381   for the HtmlHelp compiler\.--><UL>}
   304    382   
   305    383   set patterns(.hhp,1) {Default topic=~System\.Data\.SQLite\.html}

Added Doc/vtab.tcl.

            1  +###############################################################################
            2  +#
            3  +# vtab.tcl --
            4  +#
            5  +# Written by Joe Mistachkin.
            6  +# Released to the public domain, use at your own risk!
            7  +#
            8  +###############################################################################
            9  +
           10  +proc readFile { fileName } {
           11  +  set file_id [open $fileName RDONLY]
           12  +  fconfigure $file_id -encoding binary -translation binary
           13  +  set result [read $file_id]
           14  +  close $file_id
           15  +  return $result
           16  +}
           17  +
           18  +proc writeFile { fileName data } {
           19  +  set file_id [open $fileName {WRONLY CREAT TRUNC}]
           20  +  fconfigure $file_id -encoding binary -translation binary
           21  +  puts -nonewline $file_id $data
           22  +  close $file_id
           23  +  return ""
           24  +}
           25  +
           26  +proc escapeSubSpec { data } {
           27  +  regsub -all -- {&} $data {\\\&} data
           28  +  regsub -all -- {\\(\d+)} $data {\\\\\1} data
           29  +  return $data
           30  +}
           31  +
           32  +proc englishToList { value } {
           33  +  set result [list]
           34  +
           35  +  foreach element [split $value "\t\n ,"] {
           36  +    if {[string tolower $element] ni [list "" and or]} then {
           37  +      lappend result $element
           38  +    }
           39  +  }
           40  +
           41  +  return $result
           42  +}
           43  +
           44  +proc processLine { line prefix } {
           45  +  if {[string length [string trim $line]] == 0 || \
           46  +      [regexp -- {<h\d(?: |>)} [string range $line 0 3]]} then {
           47  +    return ""
           48  +  }
           49  +
           50  +  set result $line
           51  +
           52  +  foreach remove [list \
           53  +      {<a name=".*?">} {<a href=".*?">} {</a>} {<p>} {</p>}] {
           54  +    regsub -all -- $remove $result "" result
           55  +
           56  +    if {[string length [string trim $result]] == 0} then {
           57  +      return ""
           58  +    }
           59  +  }
           60  +
           61  +  foreach escape [list \
           62  +      {<b>} {</b>} {<br>} {<dd>} {</dd>} {<dl>} {</dl>} {<dt>} \
           63  +      {</dt>} {<li>} {</li>} {<ol>} {</ol>} {<tt>} {</tt>} \
           64  +      {<ul>} {</ul>}] {
           65  +    regsub -all -- ($escape) $result {<![CDATA[\1]]>} result
           66  +  }
           67  +
           68  +  regsub -all -- {&ne;} $result {\&#8800;} result
           69  +  regsub -all -- {&#91(?:;)?} $result {[} result
           70  +  regsub -all -- {&#93(?:;)?} $result {]} result
           71  +  regsub -all -- {<( |\"|\d|=)} $result {\&lt;\1} result
           72  +  regsub -all -- {( |\"|\d|=)>} $result {\1\&gt;} result
           73  +  regsub -all -- {<blockquote><pre>} $result <para><code> result
           74  +  regsub -all -- {</pre></blockquote>} $result </code></para> result
           75  +  regsub -all -- {<blockquote>} $result <para><code> result
           76  +  regsub -all -- {</blockquote>} $result </code></para> result
           77  +
           78  +  return $result
           79  +}
           80  +
           81  +proc extractMethod { name lines pattern prefix indexVarName methodsVarName } {
           82  +  upvar 1 $indexVarName index
           83  +  upvar 1 $methodsVarName methods
           84  +
           85  +  array set levels {p 0}
           86  +  set length [llength $lines]
           87  +
           88  +  while {$index < $length} {
           89  +    set line [lindex $lines $index]
           90  +
           91  +    if {[regexp -- $pattern $line]} then {
           92  +      break; # stop on this line for outer loop.
           93  +    } else {
           94  +      set trimLine [string trim $line]; set data ""
           95  +
           96  +      if {$levels(p) > 0 && [string length $trimLine] == 0} then {
           97  +        # blank line, close paragraph.
           98  +        if {[info exists methods($name)]} then {
           99  +          # non-first line, leading line separator.
          100  +          append data \n $prefix </para>
          101  +        } else {
          102  +          # first line, no leading line separator.
          103  +          append data $prefix </para>
          104  +        }
          105  +
          106  +        incr levels(p) -1
          107  +      } elseif {[string range $trimLine 0 2] eq "<p>"} then {
          108  +        # open tag ... maybe one line?
          109  +        if {[string range $trimLine end-3 end] eq "</p>"} then {
          110  +          set newLine [processLine $line $prefix]
          111  +
          112  +          if {[string length $newLine] > 0} then {
          113  +            # one line tag, wrap.
          114  +            if {[info exists methods($name)]} then {
          115  +              # non-first line, leading line separator.
          116  +              append data \n $prefix <para>
          117  +            } else {
          118  +              # first line, no leading line separator.
          119  +              append data $prefix <para>
          120  +            }
          121  +
          122  +            append data \n $prefix $newLine
          123  +            append data \n $prefix </para>
          124  +          }
          125  +        } else {
          126  +          if {[info exists methods($name)]} then {
          127  +            # non-first line, leading line separator.
          128  +            append data \n $prefix <para>
          129  +          } else {
          130  +            # first line, no leading line separator.
          131  +            append data $prefix <para>
          132  +          }
          133  +
          134  +          set newLine [processLine $line $prefix]
          135  +
          136  +          if {[string length $newLine] > 0} then {
          137  +            append data \n $prefix $newLine
          138  +          }
          139  +
          140  +          incr levels(p)
          141  +        }
          142  +      } else {
          143  +        set newLine [processLine $line $prefix]
          144  +
          145  +        if {[string length $newLine] > 0} then {
          146  +          if {[info exists methods($name)]} then {
          147  +            # non-first line, leading line separator.
          148  +            append data \n $prefix $newLine
          149  +          } else {
          150  +            # first line, no leading line separator.
          151  +            append data $prefix $newLine
          152  +          }
          153  +        }
          154  +      }
          155  +
          156  +      if {[string length $data] > 0} then {
          157  +        append methods($name) $data
          158  +      }
          159  +
          160  +      incr index; # consume this line for outer loop.
          161  +    }
          162  +  }
          163  +}
          164  +
          165  +#
          166  +# NOTE: This is the entry point for this script.
          167  +#
          168  +set path [file normalize [file dirname [info script]]]
          169  +
          170  +set coreDocPath [file join $path Special Core]
          171  +set interfacePath [file join [file dirname $path] System.Data.SQLite]
          172  +set inputFileName [file join $coreDocPath vtab.html]
          173  +
          174  +if {![file exists $inputFileName]} then {
          175  +  puts "input file \"$inputFileName\" does not exist"
          176  +  exit 1
          177  +}
          178  +
          179  +set outputFileName [file join $interfacePath ISQLiteNativeModule.cs]
          180  +
          181  +if {![file exists $outputFileName]} then {
          182  +  puts "output file \"$outputFileName\" does not exist"
          183  +  exit 1
          184  +}
          185  +
          186  +set lines [split [string map [list \r\n \n] [readFile $inputFileName]] \n]
          187  +set patterns(method) {^<h3>2\.\d+ The (.*) Method(?:s)?</h3>$}
          188  +set prefix "        /// "
          189  +unset -nocomplain methods; set start false
          190  +
          191  +for {set index 0} {$index < [llength $lines]} {} {
          192  +  set line [lindex $lines $index]
          193  +
          194  +  if {$start} then {
          195  +    if {[regexp -- $patterns(method) $line dummy capture]} then {
          196  +      foreach method [englishToList $capture] {
          197  +        set methodIndex [expr {$index + 1}]
          198  +
          199  +        extractMethod \
          200  +            $method $lines $patterns(method) $prefix methodIndex methods
          201  +      }
          202  +
          203  +      set index $methodIndex
          204  +    } else {
          205  +      incr index
          206  +    }
          207  +  } elseif {[regexp -- {^<h2>2\.0 Virtual Table Methods</h2>$} $line]} then {
          208  +    set start true; incr index
          209  +  } else {
          210  +    incr index
          211  +  }
          212  +}
          213  +
          214  +set data [string map [list \r\n \n] [readFile $outputFileName]]
          215  +set count 0; set start 0
          216  +
          217  +#
          218  +# NOTE: These method names must be processed in the EXACT order that they
          219  +#       appear in the output file.
          220  +#
          221  +foreach name [list \
          222  +    xCreate xConnect xBestIndex xDisconnect xDestroy xOpen xClose \
          223  +    xFilter xNext xEof xColumn xRowid xUpdate xBegin xSync xCommit \
          224  +    xRollback xFindFunction xRename xSavepoint xRelease xRollbackTo] {
          225  +  #
          226  +  # HACK: This assumes that a line of 71 forward slashes will be present
          227  +  #       before each method, except for the first one.
          228  +  #
          229  +  if {$count > 0} then {
          230  +    set start [string first [string repeat / 71] $data $start]
          231  +  }
          232  +
          233  +  set pattern ""
          234  +
          235  +  append pattern ^ {\s{8}} "/// <summary>"
          236  +  append pattern {((?:.|\n)*?)}
          237  +  append pattern {\n\s{8}} "/// </summary>"
          238  +  append pattern {(?:(?:.|\n)*?)}
          239  +  append pattern {\n\s{8}[\w]+?\s+?} $name {\($}
          240  +
          241  +  if {[regexp -nocase -start \
          242  +      $start -line -indices -- $pattern $data dummy indexes]} then {
          243  +    set summaryStart [lindex $indexes 0]
          244  +    set summaryEnd [lindex $indexes 1]
          245  +
          246  +    set data [string range $data 0 $summaryStart]$methods($name)[string \
          247  +        range $data [expr {$summaryEnd + 1}] end]
          248  +
          249  +    incr count; set start [expr {$summaryEnd + 1}]
          250  +  } else {
          251  +    error "cannot find virtual table method \"$name\" in \"$outputFileName\""
          252  +  }
          253  +}
          254  +
          255  +if {$count > 0} then {
          256  +  writeFile $outputFileName [string map [list \n \r\n] $data]
          257  +}
          258  +
          259  +exit 0

Changes to System.Data.SQLite/ISQLiteNativeModule.cs.

    11     11       /// <summary>
    12     12       /// This interface represents a virtual table implementation written in
    13     13       /// native code.
    14     14       /// </summary>
    15     15       public interface ISQLiteNativeModule
    16     16       {
    17     17           /// <summary>
    18         -        /// <para>
    19         -        /// This method is called to create a new instance of a virtual table
    20         -        /// in response to a CREATE VIRTUAL TABLE statement. The db parameter
    21         -        /// is a pointer to the SQLite database connection that is executing
    22         -        /// the CREATE VIRTUAL TABLE statement. The pAux argument is the copy
    23         -        /// of the client data pointer that was the fourth argument to the
    24         -        /// sqlite3_create_module() or sqlite3_create_module_v2() call that
    25         -        /// registered the virtual table module. The argv parameter is an
    26         -        /// array of argc pointers to null terminated strings. The first
    27         -        /// string, argv[0], is the name of the module being invoked. The
    28         -        /// module name is the name provided as the second argument to
    29         -        /// sqlite3_create_module() and as the argument to the USING clause of
    30         -        /// the CREATE VIRTUAL TABLE statement that is running. The second,
    31         -        /// argv[1], is the name of the database in which the new virtual table
    32         -        /// is being created. The database name is "main" for the primary
    33         -        /// database, or "temp" for TEMP database, or the name given at the
    34         -        /// end of the ATTACH statement for attached databases. The third
    35         -        /// element of the array, argv[2], is the name of the new virtual
    36         -        /// table, as specified following the TABLE keyword in the CREATE
    37         -        /// VIRTUAL TABLE statement. If present, the fourth and subsequent
    38         -        /// strings in the argv[] array report the arguments to the module name
    39         -        /// in the CREATE VIRTUAL TABLE statement.
           18  +        /// <para><code>
           19  +        ///   int (*xCreate)(sqlite3 *db, void *pAux,
           20  +        ///                int argc, char **argv,
           21  +        ///                sqlite3_vtab **ppVTab,
           22  +        ///                char **pzErr);
           23  +        /// </code></para>
           24  +        /// <para>
           25  +        /// This method is called to create a new instance of a virtual table 
           26  +        /// in response to a CREATE VIRTUAL TABLE statement. 
           27  +        /// The db parameter is a pointer to the SQLite database connection that 
           28  +        /// is executing the CREATE VIRTUAL TABLE statement. 
           29  +        /// The pAux argument is the copy of the client data pointer that was the 
           30  +        /// fourth argument to the sqlite3_create_module() or
           31  +        /// sqlite3_create_module_v2() call that registered the 
           32  +        /// virtual table module. 
           33  +        /// The argv parameter is an array of argc pointers to null terminated strings. 
           34  +        /// The first string, argv[0], is the name of the module being invoked.   The
           35  +        /// module name is the name provided as the second argument to 
           36  +        /// sqlite3_create_module() and as the argument to the USING clause of the
           37  +        /// CREATE VIRTUAL TABLE statement that is running.
           38  +        /// The second, argv[1], is the name of the database in which the new virtual table is being created. The database name is "main" for the primary database, or
           39  +        /// "temp" for TEMP database, or the name given at the end of the ATTACH
           40  +        /// statement for attached databases.  The third element of the array, argv[2], 
           41  +        /// is the name of the new virtual table, as specified following the TABLE
           42  +        /// keyword in the CREATE VIRTUAL TABLE statement.
           43  +        /// If present, the fourth and subsequent strings in the argv[] array report 
           44  +        /// the arguments to the module name in the CREATE VIRTUAL TABLE statement.
    40     45           /// </para>
    41     46           /// <para>
    42     47           /// The job of this method is to construct the new virtual table object
    43     48           /// (an sqlite3_vtab object) and return a pointer to it in *ppVTab.
    44     49           /// </para>
    45     50           /// <para>
    46         -        /// As part of the task of creating a new sqlite3_vtab structure, this
    47         -        /// method must invoke sqlite3_declare_vtab() to tell the SQLite core
    48         -        /// about the columns and datatypes in the virtual table. The
    49         -        /// sqlite3_declare_vtab() API has the following prototype:
           51  +        /// As part of the task of creating a new sqlite3_vtab structure, this 
           52  +        /// method <u>must</u> invoke sqlite3_declare_vtab() to tell the SQLite 
           53  +        /// core about the columns and datatypes in the virtual table. 
           54  +        /// The sqlite3_declare_vtab() API has the following prototype:
    50     55           /// </para>
           56  +        /// <para><code>
           57  +        ///     int sqlite3_declare_vtab(sqlite3 *db, const char *zCreateTable)
           58  +        /// </code></para>
    51     59           /// <para>
    52         -        /// <code>
    53         -        /// int sqlite3_declare_vtab(sqlite3 *db, const char *zCreateTable)
    54         -        /// </code>
    55         -        /// </para>
    56         -        /// <para>
    57         -        /// The first argument to sqlite3_declare_vtab() must be the same
           60  +        /// The first argument to sqlite3_declare_vtab() must be the same 
    58     61           /// database connection pointer as the first parameter to this method.
    59         -        /// The second argument to sqlite3_declare_vtab() must a
    60         -        /// zero-terminated UTF-8 string that contains a well-formed CREATE
    61         -        /// TABLE statement that defines the columns in the virtual table and
    62         -        /// their data types. The name of the table in this CREATE TABLE
    63         -        /// statement is ignored, as are all constraints. Only the column names
    64         -        /// and datatypes matter. The CREATE TABLE statement string need not to
    65         -        /// be held in persistent memory. The string can be deallocated and/or
    66         -        /// reused as soon as the sqlite3_declare_vtab() routine returns.
           62  +        /// The second argument to sqlite3_declare_vtab() must a zero-terminated 
           63  +        /// UTF-8 string that contains a well-formed CREATE TABLE statement that 
           64  +        /// defines the columns in the virtual table and their data types. 
           65  +        /// The name of the table in this CREATE TABLE statement is ignored, 
           66  +        /// as are all constraints. Only the column names and datatypes matter.
           67  +        /// The CREATE TABLE statement string need not to be 
           68  +        /// held in persistent memory.  The string can be
           69  +        /// deallocated and/or reused as soon as the sqlite3_declare_vtab()
           70  +        /// routine returns.
           71  +        /// </para>
           72  +        /// <para>
           73  +        /// The xCreate method need not initialize the pModule, nRef, and zErrMsg
           74  +        /// fields of the sqlite3_vtab object.  The SQLite core will take care of 
           75  +        /// that chore.
           76  +        /// </para>
           77  +        /// <para>
           78  +        /// The xCreate should return SQLITE_OK if it is successful in 
           79  +        /// creating the new virtual table, or SQLITE_ERROR if it is not successful.
           80  +        /// If not successful, the sqlite3_vtab structure must not be allocated. 
           81  +        /// An error message may optionally be returned in *pzErr if unsuccessful.
           82  +        /// Space to hold the error message string must be allocated using
           83  +        /// an SQLite memory allocation function like 
           84  +        /// sqlite3_malloc() or sqlite3_mprintf() as the SQLite core will
           85  +        /// attempt to free the space using sqlite3_free() after the error has
           86  +        /// been reported up to the application.
           87  +        /// </para>
           88  +        /// <para>
           89  +        /// If the xCreate method is omitted (left as a NULL pointer) then the
           90  +        /// virtual table is an eponymous-only virtual table.  New instances of
           91  +        /// the virtual table cannot be created using CREATE VIRTUAL TABLE and the
           92  +        /// virtual table can only be used via its module name.
           93  +        /// Note that SQLite versions prior to 3.9.0 do not understand
           94  +        /// eponymous-only virtual tables and will segfault if an attempt is made
           95  +        /// to CREATE VIRTUAL TABLE on an eponymous-only virtual table because
           96  +        /// the xCreate method was not checked for null.
           97  +        /// </para>
           98  +        /// <para>
           99  +        /// If the xCreate method is the exact same pointer as the xConnect method,
          100  +        /// that indicates that the virtual table does not need to initialize backing
          101  +        /// store.  Such a virtual table can be used as an eponymous virtual table
          102  +        /// or as a named virtual table using CREATE VIRTUAL TABLE or both.
          103  +        /// </para>
          104  +        /// <para>
          105  +        /// If a column datatype contains the special keyword "HIDDEN"
          106  +        /// (in any combination of upper and lower case letters) then that keyword
          107  +        /// it is omitted from the column datatype name and the column is marked 
          108  +        /// as a hidden column internally. 
          109  +        /// A hidden column differs from a normal column in three respects:
          110  +        /// </para>
          111  +        /// <para>
          112  +        /// <![CDATA[<ul>]]>
          113  +        /// <![CDATA[<li>]]> Hidden columns are not listed in the dataset returned by 
          114  +        ///      "PRAGMA table_info",
          115  +        /// <![CDATA[<li>]]> Hidden columns are not included in the expansion of a "*"
          116  +        ///      expression in the result set of a SELECT, and
          117  +        /// <![CDATA[<li>]]> Hidden columns are not included in the implicit column-list 
          118  +        ///      used by an INSERT statement that lacks an explicit column-list. 
          119  +        /// <![CDATA[</ul>]]>
          120  +        /// </para>
          121  +        /// <para>
          122  +        /// For example, if the following SQL is passed to sqlite3_declare_vtab():
          123  +        /// </para>
          124  +        /// <para><code>
          125  +        ///    CREATE TABLE x(a HIDDEN VARCHAR(12), b INTEGER, c INTEGER Hidden);
          126  +        /// </code></para>
          127  +        /// <para>
          128  +        /// Then the virtual table would be created with two hidden columns,
          129  +        /// and with datatypes of "VARCHAR(12)" and "INTEGER".
          130  +        /// </para>
          131  +        /// <para>
          132  +        /// An example use of hidden columns can be seen in the FTS3 virtual 
          133  +        /// table implementation, where every FTS virtual table
          134  +        /// contains an FTS hidden column that is used to pass information from the
          135  +        /// virtual table into FTS auxiliary functions and to the FTS MATCH operator.
          136  +        /// </para>
          137  +        /// <para>
          138  +        /// A virtual table that contains hidden columns can be used like
          139  +        /// a table-valued function in the FROM clause of a SELECT statement.
          140  +        /// The arguments to the table-valued function become constraints on 
          141  +        /// the HIDDEN columns of the virtual table.
          142  +        /// </para>
          143  +        /// <para>
          144  +        /// For example, the "generate_series" extension (located in the
          145  +        /// ext/misc/series.c
          146  +        /// file in the source tree)
          147  +        /// implements an eponymous virtual table with the following schema:
          148  +        /// </para>
          149  +        /// <para><code>
          150  +        /// CREATE TABLE generate_series(
          151  +        ///   value,
          152  +        ///   start HIDDEN,
          153  +        ///   stop HIDDEN,
          154  +        ///   step HIDDEN
          155  +        /// );
          156  +        /// </code></para>
          157  +        /// <para>
          158  +        /// The sqlite3_module.xBestIndex method in the implementation of this
          159  +        /// table checks for equality constraints against the HIDDEN columns, and uses
          160  +        /// those as input parameters to determine the range of integer "value" outputs
          161  +        /// to generate.  Reasonable defaults are used for any unconstrained columns.
          162  +        /// For example, to list all integers between 5 and 50:
          163  +        /// </para>
          164  +        /// <para><code>
          165  +        /// SELECT value FROM generate_series(5,50);
          166  +        /// </code></para>
          167  +        /// <para>
          168  +        /// The previous query is equivalent to the following:
          169  +        /// </para>
          170  +        /// <para><code>
          171  +        /// SELECT value FROM generate_series WHERE start=5 AND stop=50;
          172  +        /// </code></para>
          173  +        /// <para>
          174  +        /// Arguments on the virtual table name are matched to hidden columns
          175  +        /// in order.  The number of arguments can be less than the
          176  +        /// number of hidden columns, in which case the latter hidden columns are
          177  +        /// unconstrained.  However, an error results if there are more arguments
          178  +        /// than there are hidden columns in the virtual table.
    67    179           /// </para>
    68    180           /// </summary>
    69    181           /// <param name="pDb">
    70    182           /// The native database connection handle.
    71    183           /// </param>
    72    184           /// <param name="pAux">
    73    185           /// The original native pointer value that was provided to the
................................................................................
   101    213               ref IntPtr pVtab,
   102    214               ref IntPtr pError
   103    215               );
   104    216   
   105    217           ///////////////////////////////////////////////////////////////////////
   106    218   
   107    219           /// <summary>
          220  +        /// <para><code>
          221  +        ///   int (*xConnect)(sqlite3*, void *pAux,
          222  +        ///                int argc, char **argv,
          223  +        ///                sqlite3_vtab **ppVTab,
          224  +        ///                char **pzErr);
          225  +        /// </code></para>
   108    226           /// <para>
   109         -        /// The xConnect method is very similar to xCreate. It has the same
   110         -        /// parameters and constructs a new sqlite3_vtab structure just like
   111         -        /// xCreate. And it must also call sqlite3_declare_vtab() like xCreate.
          227  +        /// The xConnect method is very similar to xCreate. 
          228  +        /// It has the same parameters and constructs a new sqlite3_vtab structure 
          229  +        /// just like xCreate. 
          230  +        /// And it must also call sqlite3_declare_vtab() like xCreate.
   112    231           /// </para>
   113    232           /// <para>
   114         -        /// The difference is that xConnect is called to establish a new
   115         -        /// connection to an existing virtual table whereas xCreate is called
          233  +        /// The difference is that xConnect is called to establish a new 
          234  +        /// connection to an existing virtual table whereas xCreate is called 
   116    235           /// to create a new virtual table from scratch.
   117    236           /// </para>
   118    237           /// <para>
   119    238           /// The xCreate and xConnect methods are only different when the
   120         -        /// virtual table has some kind of backing store that must be
   121         -        /// initialized the first time the virtual table is created. The
   122         -        /// xCreate method creates and initializes the backing store. The
   123         -        /// xConnect method just connects to an existing backing store.
          239  +        /// virtual table has some kind of backing store that must be initialized 
          240  +        /// the first time the virtual table is created. The xCreate method creates 
          241  +        /// and initializes the backing store. The xConnect method just connects 
          242  +        /// to an existing backing store.  When xCreate and xConnect are the same,
          243  +        /// the table is an eponymous virtual table.
   124    244           /// </para>
   125    245           /// <para>
   126         -        /// As an example, consider a virtual table implementation that
          246  +        /// As an example, consider a virtual table implementation that 
   127    247           /// provides read-only access to existing comma-separated-value (CSV)
   128         -        /// files on disk. There is no backing store that needs to be created
   129         -        /// or initialized for such a virtual table (since the CSV files
   130         -        /// already exist on disk) so the xCreate and xConnect methods will be
   131         -        /// identical for that module.
   132         -        /// </para>
   133         -        /// <para>
   134         -        /// Another example is a virtual table that implements a full-text
   135         -        /// index. The xCreate method must create and initialize data
   136         -        /// structures to hold the dictionary and posting lists for that index.
   137         -        /// The xConnect method, on the other hand, only has to locate and use
   138         -        /// an existing dictionary and posting lists that were created by a
   139         -        /// prior xCreate call.
   140         -        /// </para>
   141         -        /// <para>
   142         -        /// The xConnect method must return SQLITE_OK if it is successful in
   143         -        /// creating the new virtual table, or SQLITE_ERROR if it is not
   144         -        /// successful. If not successful, the sqlite3_vtab structure must not
   145         -        /// be allocated. An error message may optionally be returned in *pzErr
   146         -        /// if unsuccessful. Space to hold the error message string must be
   147         -        /// allocated using an SQLite memory allocation function like
          248  +        /// files on disk. There is no backing store that needs to be created 
          249  +        /// or initialized for such a virtual table (since the CSV files already 
          250  +        /// exist on disk) so the xCreate and xConnect methods will be identical 
          251  +        /// for that module.
          252  +        /// </para>
          253  +        /// <para>
          254  +        /// Another example is a virtual table that implements a full-text index. 
          255  +        /// The xCreate method must create and initialize data structures to hold 
          256  +        /// the dictionary and posting lists for that index. The xConnect method,
          257  +        /// on the other hand, only has to locate and use an existing dictionary 
          258  +        /// and posting lists that were created by a prior xCreate call.
          259  +        /// </para>
          260  +        /// <para>
          261  +        /// The xConnect method must return SQLITE_OK if it is successful 
          262  +        /// in creating the new virtual table, or SQLITE_ERROR if it is not 
          263  +        /// successful. If not successful, the sqlite3_vtab structure must not be 
          264  +        /// allocated. An error message may optionally be returned in *pzErr if 
          265  +        /// unsuccessful. 
          266  +        /// Space to hold the error message string must be allocated using
          267  +        /// an SQLite memory allocation function like 
   148    268           /// sqlite3_malloc() or sqlite3_mprintf() as the SQLite core will
   149    269           /// attempt to free the space using sqlite3_free() after the error has
   150    270           /// been reported up to the application.
   151    271           /// </para>
   152    272           /// <para>
   153         -        /// The xConnect method is required for every virtual table
   154         -        /// implementation, though the xCreate and xConnect pointers of the
   155         -        /// sqlite3_module object may point to the same function the virtual
   156         -        /// table does not need to initialize backing store.
          273  +        /// The xConnect method is required for every virtual table implementation, 
          274  +        /// though the xCreate and xConnect pointers of the sqlite3_module object
          275  +        /// may point to the same function if the virtual table does not need to
          276  +        /// initialize backing store.
   157    277           /// </para>
   158    278           /// </summary>
   159    279           /// <param name="pDb">
   160    280           /// The native database connection handle.
   161    281           /// </param>
   162    282           /// <param name="pAux">
   163    283           /// The original native pointer value that was provided to the
................................................................................
   192    312               ref IntPtr pError
   193    313               );
   194    314   
   195    315           ///////////////////////////////////////////////////////////////////////
   196    316   
   197    317           /// <summary>
   198    318           /// <para>
   199         -        /// SQLite uses the xBestIndex method of a virtual table module to
   200         -        /// determine the best way to access the virtual table. The xBestIndex
   201         -        /// method has a prototype like this:
   202         -        /// </para>
   203         -        /// <code>
   204         -        /// int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*);
   205         -        /// </code>
   206         -        /// <para>
   207         -        /// The SQLite core communicates with the xBestIndex method by filling
   208         -        /// in certain fields of the sqlite3_index_info structure and passing a
   209         -        /// pointer to that structure into xBestIndex as the second parameter.
   210         -        /// The xBestIndex method fills out other fields of this structure
   211         -        /// which forms the reply. The sqlite3_index_info structure looks like
   212         -        /// this:
   213         -        /// </para>
   214         -        /// <code>
   215         -        ///  struct sqlite3_index_info {
   216         -        ///    /* Inputs */
   217         -        ///    const int nConstraint;   /* Number of entries in aConstraint */
   218         -        ///    const struct sqlite3_index_constraint {
   219         -        ///       int iColumn;          /* Column on left-hand side of
   220         -        ///                              * constraint */
   221         -        ///       unsigned char op;     /* Constraint operator */
   222         -        ///       unsigned char usable; /* True if this constraint is usable */
   223         -        ///       int iTermOffset;      /* Used internally - xBestIndex should
   224         -        ///                              * ignore */
   225         -        ///    } *const aConstraint;    /* Table of WHERE clause constraints */
   226         -        ///    const int nOrderBy;      /* Number of terms in the ORDER BY
   227         -        ///                              * clause */
   228         -        ///    const struct sqlite3_index_orderby {
   229         -        ///       int iColumn;          /* Column number */
   230         -        ///       unsigned char desc;   /* True for DESC.  False for ASC. */
   231         -        ///    } *const aOrderBy;       /* The ORDER BY clause */
   232         -        ///    /* Outputs */
   233         -        ///    struct sqlite3_index_constraint_usage {
   234         -        ///      int argvIndex;         /* if greater than zero, constraint is
   235         -        ///                              * part of argv to xFilter */
   236         -        ///      unsigned char omit;    /* Do not code a test for this
   237         -        ///                              * constraint */
   238         -        ///    } *const aConstraintUsage;
   239         -        ///    int idxNum;              /* Number used to identify the index */
   240         -        ///    char *idxStr;            /* String, possibly obtained from
   241         -        ///                              * sqlite3_malloc() */
   242         -        ///    int needToFreeIdxStr;    /* Free idxStr using sqlite3_free() if
   243         -        ///                              * true */
   244         -        ///    int orderByConsumed;     /* True if output is already ordered */
   245         -        ///    double estimatedCost;    /* Estimated cost of using this index */
   246         -        ///  };
   247         -        /// </code>
          319  +        /// SQLite uses the xBestIndex method of a virtual table module to determine
          320  +        /// the best way to access the virtual table. 
          321  +        /// The xBestIndex method has a prototype like this:
          322  +        /// </para>
          323  +        /// <para><code>
          324  +        ///   int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*);
          325  +        /// </code></para>
          326  +        /// <para>
          327  +        /// The SQLite core communicates with the xBestIndex method by filling 
          328  +        /// in certain fields of the sqlite3_index_info structure and passing a 
          329  +        /// pointer to that structure into xBestIndex as the second parameter. 
          330  +        /// The xBestIndex method fills out other fields of this structure which
          331  +        /// forms the reply. The sqlite3_index_info structure looks like this:
          332  +        /// </para>
          333  +        /// <para><code>
          334  +        ///   struct sqlite3_index_info {
          335  +        ///     /* Inputs */
          336  +        ///     const int nConstraint;     /* Number of entries in aConstraint */
          337  +        ///     const struct sqlite3_index_constraint {
          338  +        ///        int iColumn;              /* Column on left-hand side of constraint */
          339  +        ///        unsigned char op;         /* Constraint operator */
          340  +        ///        unsigned char usable;     /* True if this constraint is usable */
          341  +        ///        int iTermOffset;          /* Used internally - xBestIndex should ignore */
          342  +        ///     } *const aConstraint;      /* Table of WHERE clause constraints */
          343  +        ///     const int nOrderBy;        /* Number of terms in the ORDER BY clause */
          344  +        ///     const struct sqlite3_index_orderby {
          345  +        ///        int iColumn;              /* Column number */
          346  +        ///        unsigned char desc;       /* True for DESC.  False for ASC. */
          347  +        ///     } *const aOrderBy;         /* The ORDER BY clause */
          348  +        ///     /* Outputs */
          349  +        ///     struct sqlite3_index_constraint_usage {
          350  +        ///       int argvIndex;           /* if &gt;0, constraint is part of argv to xFilter */
          351  +        ///       unsigned char omit;      /* Do not code a test for this constraint */
          352  +        ///     } *const aConstraintUsage;
          353  +        ///     int idxNum;                /* Number used to identify the index */
          354  +        ///     char *idxStr;              /* String, possibly obtained from sqlite3_malloc */
          355  +        ///     int needToFreeIdxStr;      /* Free idxStr using sqlite3_free() if true */
          356  +        ///     int orderByConsumed;       /* True if output is already ordered */
          357  +        ///     double estimatedCost;      /* Estimated cost of using this index */
          358  +        ///     <![CDATA[<b>]]>/* Fields below are only available in SQLite 3.8.2 and later */<![CDATA[</b>]]>
          359  +        ///     sqlite3_int64 estimatedRows;    /* Estimated number of rows returned */
          360  +        ///     <![CDATA[<b>]]>/* Fields below are only available in SQLite 3.9.0 and later */<![CDATA[</b>]]>
          361  +        ///     int idxFlags;              /* Mask of SQLITE_INDEX_SCAN_* flags */
          362  +        ///   };
          363  +        /// </code></para>
          364  +        /// <para>
          365  +        /// Please note the warnings on the "estimatedRows" and "idxFlags" field.
          366  +        /// These fields were added with SQLite versions 3.8.2 and 3.9.0, respectively. 
          367  +        /// Any extension that reads or writes these fields must first check that the 
          368  +        /// version of the SQLite library in use is greater than or equal to 3.8.2 or
          369  +        /// 3.9.0 - perhaps using a call to sqlite3_version(). The result of attempting 
          370  +        /// to access these fields in an sqlite3_index_info structure created by an 
          371  +        /// older version of SQLite are undefined.
          372  +        /// </para>
   248    373           /// <para>
   249    374           /// In addition, there are some defined constants:
   250    375           /// </para>
   251         -        /// <code>
   252         -        ///  #define SQLITE_INDEX_CONSTRAINT_EQ    2
   253         -        ///  #define SQLITE_INDEX_CONSTRAINT_GT    4
   254         -        ///  #define SQLITE_INDEX_CONSTRAINT_LE    8
   255         -        ///  #define SQLITE_INDEX_CONSTRAINT_LT    16
   256         -        ///  #define SQLITE_INDEX_CONSTRAINT_GE    32
   257         -        ///  #define SQLITE_INDEX_CONSTRAINT_MATCH 64
   258         -        /// </code>
   259         -        /// <para>
   260         -        /// The SQLite core calls the xBestIndex method when it is compiling a
   261         -        /// query that involves a virtual table. In other words, SQLite calls
   262         -        /// this method when it is running sqlite3_prepare() or the equivalent.
   263         -        /// By calling this method, the SQLite core is saying to the virtual
   264         -        /// table that it needs to access some subset of the rows in the
   265         -        /// virtual table and it wants to know the most efficient way to do
   266         -        /// that access. The xBestIndex method replies with information that
   267         -        /// the SQLite core can then use to conduct an efficient search of the
   268         -        /// virtual table.
   269         -        /// </para>
   270         -        /// <para>
   271         -        /// While compiling a single SQL query, the SQLite core might call
   272         -        /// xBestIndex multiple times with different settings in
   273         -        /// sqlite3_index_info. The SQLite core will then select the
   274         -        /// combination that appears to give the best performance.
   275         -        /// </para>
   276         -        /// <para>
   277         -        /// Before calling this method, the SQLite core initializes an instance
          376  +        /// <para><code>
          377  +        ///   #define SQLITE_INDEX_CONSTRAINT_EQ    2
          378  +        ///   #define SQLITE_INDEX_CONSTRAINT_GT    4
          379  +        ///   #define SQLITE_INDEX_CONSTRAINT_LE    8
          380  +        ///   #define SQLITE_INDEX_CONSTRAINT_LT    16
          381  +        ///   #define SQLITE_INDEX_CONSTRAINT_GE    32
          382  +        ///   #define SQLITE_INDEX_CONSTRAINT_MATCH 64
          383  +        ///   #define SQLITE_INDEX_SCAN_UNIQUE      1     /* Scan visits at most 1 row */
          384  +        /// </code></para>
          385  +        /// <para>
          386  +        /// The SQLite core calls the xBestIndex method when it is compiling a query
          387  +        /// that involves a virtual table. In other words, SQLite calls this method 
          388  +        /// when it is running sqlite3_prepare() or the equivalent. 
          389  +        /// By calling this method, the 
          390  +        /// SQLite core is saying to the virtual table that it needs to access 
          391  +        /// some subset of the rows in the virtual table and it wants to know the
          392  +        /// most efficient way to do that access. The xBestIndex method replies 
          393  +        /// with information that the SQLite core can then use to conduct an 
          394  +        /// efficient search of the virtual table.
          395  +        /// </para>
          396  +        /// <para>
          397  +        /// While compiling a single SQL query, the SQLite core might call 
          398  +        /// xBestIndex multiple times with different settings in sqlite3_index_info.
          399  +        /// The SQLite core will then select the combination that appears to 
          400  +        /// give the best performance.
          401  +        /// </para>
          402  +        /// <para>
          403  +        /// Before calling this method, the SQLite core initializes an instance 
   278    404           /// of the sqlite3_index_info structure with information about the
   279         -        /// query that it is currently trying to process. This information
   280         -        /// derives mainly from the WHERE clause and ORDER BY or GROUP BY
   281         -        /// clauses of the query, but also from any ON or USING clauses if the
   282         -        /// query is a join. The information that the SQLite core provides to
   283         -        /// the xBestIndex method is held in the part of the structure that is
   284         -        /// marked as "Inputs". The "Outputs" section is initialized to zero.
          405  +        /// query that it is currently trying to process. This information 
          406  +        /// derives mainly from the WHERE clause and ORDER BY or GROUP BY clauses 
          407  +        /// of the query, but also from any ON or USING clauses if the query is a 
          408  +        /// join. The information that the SQLite core provides to the xBestIndex 
          409  +        /// method is held in the part of the structure that is marked as "Inputs". 
          410  +        /// The "Outputs" section is initialized to zero.
   285    411           /// </para>
   286    412           /// <para>
   287    413           /// The information in the sqlite3_index_info structure is ephemeral
   288         -        /// and may be overwritten or deallocated as soon as the xBestIndex
   289         -        /// method returns. If the xBestIndex method needs to remember any part
   290         -        /// of the sqlite3_index_info structure, it should make a copy. Care
   291         -        /// must be take to store the copy in a place where it will be
   292         -        /// deallocated, such as in the idxStr field with needToFreeIdxStr set
   293         -        /// to 1.
          414  +        /// and may be overwritten or deallocated as soon as the xBestIndex method
          415  +        /// returns.  If the xBestIndex method needs to remember any part of the
          416  +        /// sqlite3_index_info structure, it should make a copy.  Care must be
          417  +        /// take to store the copy in a place where it will be deallocated, such
          418  +        /// as in the idxStr field with needToFreeIdxStr set to 1.
   294    419           /// </para>
   295    420           /// <para>
   296    421           /// Note that xBestIndex will always be called before xFilter, since
   297         -        /// the idxNum and idxStr outputs from xBestIndex are required inputs
   298         -        /// to xFilter. However, there is no guarantee that xFilter will be
   299         -        /// called following a successful xBestIndex.
          422  +        /// the idxNum and idxStr outputs from xBestIndex are required inputs to
          423  +        /// xFilter.  However, there is no guarantee that xFilter will be called
          424  +        /// following a successful xBestIndex.  
   300    425           /// </para>
   301    426           /// <para>
   302         -        /// The xBestIndex method is required for every virtual table
   303         -        /// implementation.
          427  +        /// The xBestIndex method is required for every virtual table implementation.
   304    428           /// </para>
   305    429           /// <para>
   306         -        /// 2.3.1 Inputs
   307         -        /// </para>
   308         -        /// <para>
   309         -        /// The main thing that the SQLite core is trying to communicate to the
   310         -        /// virtual table is the constraints that are available to limit the
   311         -        /// number of rows that need to be searched. The aConstraint[] array
   312         -        /// contains one entry for each constraint. There will be exactly
          430  +        /// The main thing that the SQLite core is trying to communicate to 
          431  +        /// the virtual table is the constraints that are available to limit 
          432  +        /// the number of rows that need to be searched. The aConstraint[] array 
          433  +        /// contains one entry for each constraint. There will be exactly 
   313    434           /// nConstraint entries in that array.
   314    435           /// </para>
   315    436           /// <para>
   316         -        /// Each constraint will correspond to a term in the WHERE clause or in
   317         -        /// a USING or ON clause that is of the form
          437  +        /// Each constraint will correspond to a term in the WHERE clause
          438  +        /// or in a USING or ON clause that is of the form
   318    439           /// </para>
   319         -        /// <code>
   320         -        ///     column OP EXPR
   321         -        /// </code>
          440  +        /// <para><code>
          441  +        ///      column  OP  EXPR
          442  +        /// </code></para>
   322    443           /// <para>
   323         -        /// Where "column" is a column in the virtual table, OP is an operator
   324         -        /// like "=" or "&lt;", and EXPR is an arbitrary expression. So, for
   325         -        /// example, if the WHERE clause contained a term like this:
          444  +        /// Where "column" is a column in the virtual table, OP is an operator 
          445  +        /// like "=" or "&lt;", and EXPR is an arbitrary expression. So, for example,
          446  +        /// if the WHERE clause contained a term like this:
   326    447           /// </para>
   327         -        /// <code>
   328         -        ///          a = 5
   329         -        /// </code>
          448  +        /// <para><code>
          449  +        ///      a = 5
          450  +        /// </code></para>
   330    451           /// <para>
   331         -        /// Then one of the constraints would be on the "a" column with
          452  +        /// Then one of the constraints would be on the "a" column with 
   332    453           /// operator "=" and an expression of "5". Constraints need not have a
   333         -        /// literal representation of the WHERE clause. The query optimizer
   334         -        /// might make transformations to the WHERE clause in order to extract
   335         -        /// as many constraints as it can. So, for example, if the WHERE clause
   336         -        /// contained something like this:
   337         -        /// </para>
   338         -        /// <code>
   339         -        ///          x BETWEEN 10 AND 100 AND 999&gt;y
   340         -        /// </code>
   341         -        /// <para>
   342         -        /// The query optimizer might translate this into three separate
   343         -        /// constraints:
   344         -        /// </para>
   345         -        /// <code>
   346         -        ///          x &gt;= 10
   347         -        ///          x &lt;= 100
   348         -        ///          y &lt; 999
   349         -        /// </code>
   350         -        /// <para>
   351         -        /// For each constraint, the aConstraint[].iColumn field indicates
   352         -        /// which column appears on the left-hand side of the constraint. The
   353         -        /// first column of the virtual table is column 0. The rowid of the
   354         -        /// virtual table is column -1. The aConstraint[].op field indicates
   355         -        /// which operator is used. The SQLITE_INDEX_CONSTRAINT_* constants map
   356         -        /// integer constants into operator values. Columns occur in the order
   357         -        /// they were defined by the call to sqlite3_declare_vtab() in the
   358         -        /// xCreate or xConnect method. Hidden columns are counted when
   359         -        /// determining the column index.
   360         -        /// </para>
   361         -        /// <para>
   362         -        /// The aConstraint[] array contains information about all constraints
          454  +        /// literal representation of the WHERE clause. The query optimizer might
          455  +        /// make transformations to the 
          456  +        /// WHERE clause in order to extract as many constraints 
          457  +        /// as it can. So, for example, if the WHERE clause contained something 
          458  +        /// like this:
          459  +        /// </para>
          460  +        /// <para><code>
          461  +        ///      x BETWEEN 10 AND 100 AND 999&gt;y
          462  +        /// </code></para>
          463  +        /// <para>
          464  +        /// The query optimizer might translate this into three separate constraints:
          465  +        /// </para>
          466  +        /// <para><code>
          467  +        ///      x &gt;= 10
          468  +        ///      x &lt;= 100
          469  +        ///      y &lt; 999
          470  +        /// </code></para>
          471  +        /// <para>
          472  +        /// For each constraint, the aConstraint[].iColumn field indicates which 
          473  +        /// column appears on the left-hand side of the constraint.
          474  +        /// The first column of the virtual table is column 0. 
          475  +        /// The rowid of the virtual table is column -1. 
          476  +        /// The aConstraint[].op field indicates which operator is used. 
          477  +        /// The SQLITE_INDEX_CONSTRAINT_* constants map integer constants 
          478  +        /// into operator values.
          479  +        /// Columns occur in the order they were defined by the call to
          480  +        /// sqlite3_declare_vtab() in the xCreate or xConnect method.
          481  +        /// Hidden columns are counted when determining the column index.
          482  +        /// </para>
          483  +        /// <para>
          484  +        /// The aConstraint[] array contains information about all constraints 
   363    485           /// that apply to the virtual table. But some of the constraints might
   364         -        /// not be usable because of the way tables are ordered in a join. The
   365         -        /// xBestIndex method must therefore only consider constraints that
   366         -        /// have an aConstraint[].usable flag which is true.
          486  +        /// not be usable because of the way tables are ordered in a join. 
          487  +        /// The xBestIndex method must therefore only consider constraints 
          488  +        /// that have an aConstraint[].usable flag which is true.
   367    489           /// </para>
   368    490           /// <para>
   369         -        /// In addition to WHERE clause constraints, the SQLite core also tells
   370         -        /// the xBestIndex method about the ORDER BY clause. (In an aggregate
   371         -        /// query, the SQLite core might put in GROUP BY clause information in
   372         -        /// place of the ORDER BY clause information, but this fact should not
   373         -        /// make any difference to the xBestIndex method.) If all terms of the
   374         -        /// ORDER BY clause are columns in the virtual table, then nOrderBy
   375         -        /// will be the number of terms in the ORDER BY clause and the
   376         -        /// aOrderBy[] array will identify the column for each term in the
   377         -        /// order by clause and whether or not that column is ASC or DESC.
          491  +        /// In addition to WHERE clause constraints, the SQLite core also 
          492  +        /// tells the xBestIndex method about the ORDER BY clause. 
          493  +        /// (In an aggregate query, the SQLite core might put in GROUP BY clause 
          494  +        /// information in place of the ORDER BY clause information, but this fact
          495  +        /// should not make any difference to the xBestIndex method.) 
          496  +        /// If all terms of the ORDER BY clause are columns in the virtual table, 
          497  +        /// then nOrderBy will be the number of terms in the ORDER BY clause 
          498  +        /// and the aOrderBy[] array will identify the column for each term 
          499  +        /// in the order by clause and whether or not that column is ASC or DESC.
   378    500           /// </para>
   379    501           /// <para>
   380         -        /// 2.3.2 Outputs
   381         -        /// </para>
   382         -        /// <para>
   383         -        /// Given all of the information above, the job of the xBestIndex
          502  +        /// Given all of the information above, the job of the xBestIndex 
   384    503           /// method it to figure out the best way to search the virtual table.
   385    504           /// </para>
   386    505           /// <para>
   387         -        /// The xBestIndex method fills the idxNum and idxStr fields with
   388         -        /// information that communicates an indexing strategy to the xFilter
   389         -        /// method. The information in idxNum and idxStr is arbitrary as far as
   390         -        /// the SQLite core is concerned. The SQLite core just copies the
   391         -        /// information through to the xFilter method. Any desired meaning can
   392         -        /// be assigned to idxNum and idxStr as long as xBestIndex and xFilter
          506  +        /// The xBestIndex method fills the idxNum and idxStr fields with 
          507  +        /// information that communicates an indexing strategy to the xFilter 
          508  +        /// method. The information in idxNum and idxStr is arbitrary as far 
          509  +        /// as the SQLite core is concerned. The SQLite core just copies the 
          510  +        /// information through to the xFilter method. Any desired meaning can 
          511  +        /// be assigned to idxNum and idxStr as long as xBestIndex and xFilter 
   393    512           /// agree on what that meaning is.
   394    513           /// </para>
   395    514           /// <para>
   396         -        /// The idxStr value may be a string obtained from an SQLite memory
   397         -        /// allocation function such as sqlite3_mprintf(). If this is the case,
   398         -        /// then the needToFreeIdxStr flag must be set to true so that the
   399         -        /// SQLite core will know to call sqlite3_free() on that string when it
   400         -        /// has finished with it, and thus avoid a memory leak.
   401         -        /// </para>
   402         -        /// <para>
   403         -        /// If the virtual table will output rows in the order specified by the
   404         -        /// ORDER BY clause, then the orderByConsumed flag may be set to true.
   405         -        /// If the output is not automatically in the correct order then
   406         -        /// orderByConsumed must be left in its default false setting. This
   407         -        /// will indicate to the SQLite core that it will need to do a separate
   408         -        /// sorting pass over the data after it comes out of the virtual table.
   409         -        /// </para>
   410         -        /// <para>
   411         -        /// The estimatedCost field should be set to the estimated number of
   412         -        /// disk access operations required to execute this query against the
   413         -        /// virtual table. The SQLite core will often call xBestIndex multiple
   414         -        /// times with different constraints, obtain multiple cost estimates,
   415         -        /// then choose the query plan that gives the lowest estimate.
   416         -        /// </para>
   417         -        /// <para>
   418         -        /// The aConstraintUsage[] array contains one element for each of the
   419         -        /// nConstraint constraints in the inputs section of the
   420         -        /// sqlite3_index_info structure. The aConstraintUsage[] array is used
   421         -        /// by xBestIndex to tell the core how it is using the constraints.
   422         -        /// </para>
   423         -        /// <para>
   424         -        /// The xBestIndex method may set aConstraintUsage[].argvIndex entries
   425         -        /// to values greater than one. Exactly one entry should be set to 1,
   426         -        /// another to 2, another to 3, and so forth up to as many or as few as
   427         -        /// the xBestIndex method wants. The EXPR of the corresponding
   428         -        /// constraints will then be passed in as the argv[] parameters to
   429         -        /// xFilter.
   430         -        /// </para>
   431         -        /// <para>
   432         -        /// For example, if the aConstraint[3].argvIndex is set to 1, then when
   433         -        /// xFilter is called, the argv[0] passed to xFilter will have the EXPR
   434         -        /// value of the aConstraint[3] constraint.
   435         -        /// </para>
   436         -        /// <para>
   437         -        /// By default, the SQLite core double checks all constraints on each
   438         -        /// row of the virtual table that it receives. If such a check is
   439         -        /// redundant, the xBestFilter method can suppress that double-check by
          515  +        /// The idxStr value may be a string obtained from an SQLite
          516  +        /// memory allocation function such as sqlite3_mprintf(). 
          517  +        /// If this is the case, then the needToFreeIdxStr flag must be set to 
          518  +        /// true so that the SQLite core will know to call sqlite3_free() on 
          519  +        /// that string when it has finished with it, and thus avoid a memory leak.
          520  +        /// </para>
          521  +        /// <para>
          522  +        /// If the virtual table will output rows in the order specified by 
          523  +        /// the ORDER BY clause, then the orderByConsumed flag may be set to 
          524  +        /// true. If the output is not automatically in the correct order 
          525  +        /// then orderByConsumed must be left in its default false setting. 
          526  +        /// This will indicate to the SQLite core that it will need to do a 
          527  +        /// separate sorting pass over the data after it comes out of the virtual table.
          528  +        /// </para>
          529  +        /// <para>
          530  +        /// The estimatedCost field should be set to the estimated number
          531  +        /// of disk access operations required to execute this query against 
          532  +        /// the virtual table. The SQLite core will often call xBestIndex 
          533  +        /// multiple times with different constraints, obtain multiple cost
          534  +        /// estimates, then choose the query plan that gives the lowest estimate.
          535  +        /// </para>
          536  +        /// <para>
          537  +        /// If the current version of SQLite is 3.8.2 or greater, the estimatedRows
          538  +        /// field may be set to an estimate of the number of rows returned by the
          539  +        /// proposed query plan. If this value is not explicitly set, the default 
          540  +        /// estimate of 25 rows is used.
          541  +        /// </para>
          542  +        /// <para>
          543  +        /// If the current version of SQLite is 3.9.0 or greater, the idxFlags field
          544  +        /// may be set to SQLITE_INDEX_SCAN_UNIQUE to indicate that the virtual table
          545  +        /// will return only zero or one rows given the input constraints.  Additional
          546  +        /// bits of the idxFlags field might be understood in later versions of SQLite.
          547  +        /// </para>
          548  +        /// <para>
          549  +        /// The aConstraintUsage[] array contains one element for each of 
          550  +        /// the nConstraint constraints in the inputs section of the 
          551  +        /// sqlite3_index_info structure. 
          552  +        /// The aConstraintUsage[] array is used by xBestIndex to tell the 
          553  +        /// core how it is using the constraints.
          554  +        /// </para>
          555  +        /// <para>
          556  +        /// The xBestIndex method may set aConstraintUsage[].argvIndex 
          557  +        /// entries to values greater than zero. 
          558  +        /// Exactly one entry should be set to 1, another to 2, another to 3, 
          559  +        /// and so forth up to as many or as few as the xBestIndex method wants. 
          560  +        /// The EXPR of the corresponding constraints will then be passed 
          561  +        /// in as the argv[] parameters to xFilter.
          562  +        /// </para>
          563  +        /// <para>
          564  +        /// For example, if the aConstraint[3].argvIndex is set to 1, then 
          565  +        /// when xFilter is called, the argv[0] passed to xFilter will have 
          566  +        /// the EXPR value of the aConstraint[3] constraint.
          567  +        /// </para>
          568  +        /// <para>
          569  +        /// By default, the SQLite core double checks all constraints on 
          570  +        /// each row of the virtual table that it receives. If such a check 
          571  +        /// is redundant, the xBestFilter method can suppress that double-check by 
   440    572           /// setting aConstraintUsage[].omit.
   441    573           /// </para>
   442    574           /// </summary>
   443    575           /// <param name="pVtab">
   444    576           /// The native pointer to the sqlite3_vtab derived structure.
   445    577           /// </param>
   446    578           /// <param name="pIndex">
................................................................................
   453    585               IntPtr pVtab,
   454    586               IntPtr pIndex
   455    587               );
   456    588   
   457    589           ///////////////////////////////////////////////////////////////////////
   458    590   
   459    591           /// <summary>
          592  +        /// <para><code>
          593  +        ///   int (*xDisconnect)(sqlite3_vtab *pVTab);
          594  +        /// </code></para>
   460    595           /// <para>
   461         -        /// This method releases a connection to a virtual table. Only the
   462         -        /// sqlite3_vtab object is destroyed. The virtual table is not
   463         -        /// destroyed and any backing store associated with the virtual table
   464         -        /// persists. This method undoes the work of xConnect.
          596  +        /// This method releases a connection to a virtual table. 
          597  +        /// Only the sqlite3_vtab object is destroyed.
          598  +        /// The virtual table is not destroyed and any backing store 
          599  +        /// associated with the virtual table persists. 
   465    600           /// </para>
          601  +        /// This method undoes the work of xConnect.
   466    602           /// <para>
   467    603           /// This method is a destructor for a connection to the virtual table.
   468         -        /// Contrast this method with xDestroy. The xDestroy is a destructor
          604  +        /// Contrast this method with xDestroy.  The xDestroy is a destructor
   469    605           /// for the entire virtual table.
   470    606           /// </para>
   471    607           /// <para>
   472         -        /// The xDisconnect method is required for every virtual table
   473         -        /// implementation, though it is acceptable for the xDisconnect and
   474         -        /// xDestroy methods to be the same function if that makes sense for
   475         -        /// the particular virtual table.
          608  +        /// The xDisconnect method is required for every virtual table implementation,
          609  +        /// though it is acceptable for the xDisconnect and xDestroy methods to be
          610  +        /// the same function if that makes sense for the particular virtual table.
   476    611           /// </para>
   477    612           /// </summary>
   478    613           /// <param name="pVtab">
   479    614           /// The native pointer to the sqlite3_vtab derived structure.
   480    615           /// </param>
   481    616           /// <returns>
   482    617           /// A standard SQLite return code.
................................................................................
   484    619           SQLiteErrorCode xDisconnect(
   485    620               IntPtr pVtab
   486    621               );
   487    622   
   488    623           ///////////////////////////////////////////////////////////////////////
   489    624   
   490    625           /// <summary>
          626  +        /// <para><code>
          627  +        ///   int (*xDestroy)(sqlite3_vtab *pVTab);
          628  +        /// </code></para>
   491    629           /// <para>
   492         -        /// This method releases a connection to a virtual table, just like the
   493         -        /// xDisconnect method, and it also destroys the underlying table
   494         -        /// implementation. This method undoes the work of xCreate.
          630  +        /// This method releases a connection to a virtual table, just like 
          631  +        /// the xDisconnect method, and it also destroys the underlying 
          632  +        /// table implementation. This method undoes the work of xCreate.
   495    633           /// </para>
   496    634           /// <para>
   497    635           /// The xDisconnect method is called whenever a database connection
   498         -        /// that uses a virtual table is closed. The xDestroy method is only
   499         -        /// called when a DROP TABLE statement is executed against the virtual
   500         -        /// table.
          636  +        /// that uses a virtual table is closed. The xDestroy method is only 
          637  +        /// called when a DROP TABLE statement is executed against the virtual table.
   501    638           /// </para>
   502    639           /// <para>
   503         -        /// The xDestroy method is required for every virtual table
   504         -        /// implementation, though it is acceptable for the xDisconnect and
   505         -        /// xDestroy methods to be the same function if that makes sense for
   506         -        /// the particular virtual table.
          640  +        /// The xDestroy method is required for every virtual table implementation,
          641  +        /// though it is acceptable for the xDisconnect and xDestroy methods to be
          642  +        /// the same function if that makes sense for the particular virtual table.
   507    643           /// </para>
   508    644           /// </summary>
   509    645           /// <param name="pVtab">
   510    646           /// The native pointer to the sqlite3_vtab derived structure.
   511    647           /// </param>
   512    648           /// <returns>
   513    649           /// A standard SQLite return code.
................................................................................
   515    651           SQLiteErrorCode xDestroy(
   516    652               IntPtr pVtab
   517    653               );
   518    654   
   519    655           ///////////////////////////////////////////////////////////////////////
   520    656   
   521    657           /// <summary>
          658  +        /// <para><code>
          659  +        ///   int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor);
          660  +        /// </code></para>
   522    661           /// <para>
   523         -        /// The xOpen method creates a new cursor used for accessing (read
   524         -        /// and/or writing) a virtual table. A successful invocation of this
   525         -        /// method will allocate the memory for the sqlite3_vtab_cursor (or a
   526         -        /// subclass), initialize the new object, and make *ppCursor point to
   527         -        /// the new object. The successful call then returns SQLITE_OK.
          662  +        /// The xOpen method creates a new cursor used for accessing (read and/or
          663  +        /// writing) a virtual table.  A successful invocation of this method 
          664  +        /// will allocate the memory for the sqlite3_vtab_cursor (or a subclass),
          665  +        /// initialize the new object, and make *ppCursor point to the new object.
          666  +        /// The successful call then returns SQLITE_OK.
   528    667           /// </para>
   529    668           /// <para>
   530    669           /// For every successful call to this method, the SQLite core will
   531         -        /// later invoke the xClose method to destroy the allocated cursor.
          670  +        /// later invoke the xClose method to destroy 
          671  +        /// the allocated cursor.
   532    672           /// </para>
   533    673           /// <para>
   534    674           /// The xOpen method need not initialize the pVtab field of the
   535         -        /// sqlite3_vtab_cursor structure. The SQLite core will take care of
   536         -        /// that chore automatically.
          675  +        /// sqlite3_vtab_cursor structure.  The SQLite core will take care
          676  +        /// of that chore automatically.
   537    677           /// </para>
   538    678           /// <para>
   539    679           /// A virtual table implementation must be able to support an arbitrary
   540    680           /// number of simultaneously open cursors.
   541    681           /// </para>
   542    682           /// <para>
   543         -        /// When initially opened, the cursor is in an undefined state. The
   544         -        /// SQLite core will invoke the xFilter method on the cursor prior to
   545         -        /// any attempt to position or read from the cursor.
          683  +        /// When initially opened, the cursor is in an undefined state.
          684  +        /// The SQLite core will invoke the xFilter method
          685  +        /// on the cursor prior to any attempt to position or read from the cursor.
   546    686           /// </para>
   547    687           /// <para>
   548         -        /// The xOpen method is required for every virtual table
   549         -        /// implementation.
          688  +        /// The xOpen method is required for every virtual table implementation.
   550    689           /// </para>
   551    690           /// </summary>
   552    691           /// <param name="pVtab">
   553    692           /// The native pointer to the sqlite3_vtab derived structure.
   554    693           /// </param>
   555    694           /// <param name="pCursor">
   556    695           /// Upon success, this parameter must be modified to point to the newly
................................................................................
   563    702               IntPtr pVtab,
   564    703               ref IntPtr pCursor
   565    704               );
   566    705   
   567    706           ///////////////////////////////////////////////////////////////////////
   568    707   
   569    708           /// <summary>
          709  +        /// <para><code>
          710  +        ///   int (*xClose)(sqlite3_vtab_cursor*);
          711  +        /// </code></para>
   570    712           /// <para>
   571         -        /// The xClose method closes a cursor previously opened by xOpen. The
   572         -        /// SQLite core will always call xClose once for each cursor opened
          713  +        /// The xClose method closes a cursor previously opened by 
          714  +        /// xOpen. 
          715  +        /// The SQLite core will always call xClose once for each cursor opened 
   573    716           /// using xOpen.
   574    717           /// </para>
   575    718           /// <para>
   576    719           /// This method must release all resources allocated by the
   577         -        /// corresponding xOpen call. The routine will not be called again even
   578         -        /// if it returns an error. The SQLite core will not use the
          720  +        /// corresponding xOpen call. The routine will not be called again even if it
          721  +        /// returns an error.  The SQLite core will not use the
   579    722           /// sqlite3_vtab_cursor again after it has been closed.
   580    723           /// </para>
   581    724           /// <para>
   582         -        /// The xClose method is required for every virtual table
   583         -        /// implementation.
          725  +        /// The xClose method is required for every virtual table implementation.
   584    726           /// </para>
   585    727           /// </summary>
   586    728           /// <param name="pCursor">
   587    729           /// The native pointer to the sqlite3_vtab_cursor derived structure.
   588    730           /// </param>
   589    731           /// <returns>
   590    732           /// A standard SQLite return code.
................................................................................
   592    734           SQLiteErrorCode xClose(
   593    735               IntPtr pCursor
   594    736               );
   595    737   
   596    738           ///////////////////////////////////////////////////////////////////////
   597    739   
   598    740           /// <summary>
          741  +        /// <para><code>
          742  +        ///   int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr,
          743  +        ///                 int argc, sqlite3_value **argv);
          744  +        /// </code></para>
   599    745           /// <para>
   600         -        /// This method begins a search of a virtual table. The first argument
   601         -        /// is a cursor opened by xOpen. The next two argument define a
   602         -        /// particular search index previously chosen by xBestIndex. The
   603         -        /// specific meanings of idxNum and idxStr are unimportant as long as
   604         -        /// xFilter and xBestIndex agree on what that meaning is.
          746  +        /// This method begins a search of a virtual table. 
          747  +        /// The first argument is a cursor opened by xOpen. 
          748  +        /// The next two arguments define a particular search index previously 
          749  +        /// chosen by xBestIndex. The specific meanings of idxNum and idxStr 
          750  +        /// are unimportant as long as xFilter and xBestIndex agree on what 
          751  +        /// that meaning is.
   605    752           /// </para>
   606    753           /// <para>
   607         -        /// The xBestIndex function may have requested the values of certain
   608         -        /// expressions using the aConstraintUsage[].argvIndex values of the
   609         -        /// sqlite3_index_info structure. Those values are passed to xFilter
   610         -        /// using the argc and argv parameters.
          754  +        /// The xBestIndex function may have requested the values of 
          755  +        /// certain expressions using the aConstraintUsage[].argvIndex values 
          756  +        /// of the sqlite3_index_info structure. 
          757  +        /// Those values are passed to xFilter using the argc and argv parameters.
   611    758           /// </para>
   612    759           /// <para>
   613    760           /// If the virtual table contains one or more rows that match the
   614         -        /// search criteria, then the cursor must be left point at the first
   615         -        /// row. Subsequent calls to xEof must return false (zero). If there
   616         -        /// are no rows match, then the cursor must be left in a state that
   617         -        /// will cause the xEof to return true (non-zero). The SQLite engine
   618         -        /// will use the xColumn and xRowid methods to access that row content.
          761  +        /// search criteria, then the cursor must be left point at the first row.
          762  +        /// Subsequent calls to xEof must return false (zero).
          763  +        /// If there are no rows match, then the cursor must be left in a state 
          764  +        /// that will cause the xEof to return true (non-zero).
          765  +        /// The SQLite engine will use
          766  +        /// the xColumn and xRowid methods to access that row content.
   619    767           /// The xNext method will be used to advance to the next row.
   620    768           /// </para>
   621    769           /// <para>
   622         -        /// This method must return SQLITE_OK if successful, or an sqlite error
   623         -        /// code if an error occurs.
          770  +        /// This method must return SQLITE_OK if successful, or an sqlite 
          771  +        /// error code if an error occurs.
   624    772           /// </para>
   625    773           /// <para>
   626         -        /// The xFilter method is required for every virtual table
   627         -        /// implementation.
          774  +        /// The xFilter method is required for every virtual table implementation.
   628    775           /// </para>
   629    776           /// </summary>
   630    777           /// <param name="pCursor">
   631    778           /// The native pointer to the sqlite3_vtab_cursor derived structure.
   632    779           /// </param>
   633    780           /// <param name="idxNum">
   634    781           /// Number used to help identify the selected index.
................................................................................
   655    802               int argc,
   656    803               IntPtr argv
   657    804               );
   658    805   
   659    806           ///////////////////////////////////////////////////////////////////////
   660    807   
   661    808           /// <summary>
          809  +        /// <para><code>
          810  +        ///   int (*xNext)(sqlite3_vtab_cursor*);
          811  +        /// </code></para>
   662    812           /// <para>
   663         -        /// The xNext method advances a virtual table cursor to the next row of
   664         -        /// a result set initiated by xFilter. If the cursor is already
   665         -        /// pointing at the last row when this routine is called, then the
   666         -        /// cursor no longer points to valid data and a subsequent call to the
   667         -        /// xEof method must return true (non-zero). If the cursor is
   668         -        /// successfully advanced to another row of content, then subsequent
   669         -        /// calls to xEof must return false (zero).
          813  +        /// The xNext method advances a virtual table cursor
          814  +        /// to the next row of a result set initiated by xFilter. 
          815  +        /// If the cursor is already pointing at the last row when this 
          816  +        /// routine is called, then the cursor no longer points to valid 
          817  +        /// data and a subsequent call to the xEof method must return true (non-zero). 
          818  +        /// If the cursor is successfully advanced to another row of content, then
          819  +        /// subsequent calls to xEof must return false (zero).
   670    820           /// </para>
   671    821           /// <para>
   672         -        /// This method must return SQLITE_OK if successful, or an sqlite error
   673         -        /// code if an error occurs.
          822  +        /// This method must return SQLITE_OK if successful, or an sqlite 
          823  +        /// error code if an error occurs.
   674    824           /// </para>
   675    825           /// <para>
   676         -        /// The xNext method is required for every virtual table
   677         -        /// implementation.
          826  +        /// The xNext method is required for every virtual table implementation.
   678    827           /// </para>
   679    828           /// </summary>
   680    829           /// <param name="pCursor">
   681    830           /// The native pointer to the sqlite3_vtab_cursor derived structure.
   682    831           /// </param>
   683    832           /// <returns>
   684    833           /// A standard SQLite return code.
................................................................................
   686    835           SQLiteErrorCode xNext(
   687    836               IntPtr pCursor
   688    837               );
   689    838   
   690    839           ///////////////////////////////////////////////////////////////////////
   691    840   
   692    841           /// <summary>
          842  +        /// <para><code>
          843  +        ///   int (*xEof)(sqlite3_vtab_cursor*);
          844  +        /// </code></para>
   693    845           /// <para>
   694         -        /// The xEof method must return false (zero) if the specified cursor
   695         -        /// currently points to a valid row of data, or true (non-zero)
   696         -        /// otherwise. This method is called by the SQL engine immediately
   697         -        /// after each xFilter and xNext invocation.
          846  +        /// The xEof method must return false (zero) if the specified cursor 
          847  +        /// currently points to a valid row of data, or true (non-zero) otherwise. 
          848  +        /// This method is called by the SQL engine immediately after each 
          849  +        /// xFilter and xNext invocation.
   698    850           /// </para>
   699    851           /// <para>
   700    852           /// The xEof method is required for every virtual table implementation.
   701    853           /// </para>
   702    854           /// </summary>
   703    855           /// <param name="pCursor">
   704    856           /// The native pointer to the sqlite3_vtab_cursor derived structure.
................................................................................
   709    861           int xEof(
   710    862               IntPtr pCursor
   711    863               );
   712    864   
   713    865           ///////////////////////////////////////////////////////////////////////
   714    866   
   715    867           /// <summary>
   716         -        /// <para>
   717         -        /// The SQLite core invokes this method in order to find the value for
   718         -        /// the N-th column of the current row. N is zero-based so the first
   719         -        /// column is numbered 0. The xColumn method may return its result back
   720         -        /// to SQLite using one of the following interface:
   721         -        /// </para>
   722         -        /// <code>
   723         -        ///     sqlite3_result_blob()
   724         -        ///     sqlite3_result_double()
   725         -        ///     sqlite3_result_int()
   726         -        ///     sqlite3_result_int64()
   727         -        ///     sqlite3_result_null()
   728         -        ///     sqlite3_result_text()
   729         -        ///     sqlite3_result_text16()
   730         -        ///     sqlite3_result_text16le()
   731         -        ///     sqlite3_result_text16be()
   732         -        ///     sqlite3_result_zeroblob()
   733         -        /// </code>
   734         -        /// <para>
   735         -        /// If the xColumn method implementation calls none of the functions
   736         -        /// above, then the value of the column defaults to an SQL NULL.
   737         -        /// </para>
   738         -        /// <para>
   739         -        /// To raise an error, the xColumn method should use one of the
   740         -        /// result_text() methods to set the error message text, then return an
   741         -        /// appropriate error code. The xColumn method must return SQLITE_OK on
   742         -        /// success.
   743         -        /// </para>
   744         -        /// <para>
   745         -        /// The xColumn method is required for every virtual table
   746         -        /// implementation.
          868  +        /// <para><code>
          869  +        ///   int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int N);
          870  +        /// </code></para>
          871  +        /// <para>
          872  +        /// The SQLite core invokes this method in order to find the value for 
          873  +        /// the N-th column of the current row. N is zero-based so the first column 
          874  +        /// is numbered 0. 
          875  +        /// The xColumn method may return its result back to SQLite using one of the
          876  +        /// following interface:
          877  +        /// </para>
          878  +        /// <para>
          879  +        /// <![CDATA[<ul>]]>
          880  +        /// <![CDATA[<li>]]> sqlite3_result_blob()
          881  +        /// <![CDATA[<li>]]> sqlite3_result_double()
          882  +        /// <![CDATA[<li>]]> sqlite3_result_int()
          883  +        /// <![CDATA[<li>]]> sqlite3_result_int64()
          884  +        /// <![CDATA[<li>]]> sqlite3_result_null()
          885  +        /// <![CDATA[<li>]]> sqlite3_result_text()
          886  +        /// <![CDATA[<li>]]> sqlite3_result_text16()
          887  +        /// <![CDATA[<li>]]> sqlite3_result_text16le()
          888  +        /// <![CDATA[<li>]]> sqlite3_result_text16be()
          889  +        /// <![CDATA[<li>]]> sqlite3_result_zeroblob()
          890  +        /// <![CDATA[</ul>]]>
          891  +        /// </para>
          892  +        /// <para>
          893  +        /// If the xColumn method implementation calls none of the functions above,
          894  +        /// then the value of the column defaults to an SQL NULL.
          895  +        /// </para>
          896  +        /// <para>
          897  +        /// To raise an error, the xColumn method should use one of the result_text() 
          898  +        /// methods to set the error message text, then return an appropriate
          899  +        /// error code.  The xColumn method must return SQLITE_OK on success.
          900  +        /// </para>
          901  +        /// <para>
          902  +        /// The xColumn method is required for every virtual table implementation.
   747    903           /// </para>
   748    904           /// </summary>
   749    905           /// <param name="pCursor">
   750    906           /// The native pointer to the sqlite3_vtab_cursor derived structure.
   751    907           /// </param>
   752    908           /// <param name="pContext">
   753    909           /// The native pointer to the sqlite3_context structure to be used
................................................................................
   766    922               IntPtr pContext,
   767    923               int index
   768    924               );
   769    925   
   770    926           ///////////////////////////////////////////////////////////////////////
   771    927   
   772    928           /// <summary>
          929  +        /// <para><code>
          930  +        ///   int (*xRowid)(sqlite3_vtab_cursor *pCur, sqlite_int64 *pRowid);
          931  +        /// </code></para>
   773    932           /// <para>
   774    933           /// A successful invocation of this method will cause *pRowid to be
   775         -        /// filled with the rowid of row that the virtual table cursor pCur is
   776         -        /// currently pointing at. This method returns SQLITE_OK on success. It
   777         -        /// returns an appropriate error code on failure.
          934  +        /// filled with the rowid of row that the
          935  +        /// virtual table cursor pCur is currently pointing at.
          936  +        /// This method returns SQLITE_OK on success.
          937  +        /// It returns an appropriate error code on failure.
   778    938           /// </para>
   779    939           /// <para>
   780         -        /// The xRowid method is required for every virtual table
   781         -        /// implementation.
          940  +        /// The xRowid method is required for every virtual table implementation.
   782    941           /// </para>
   783    942           /// </summary>
   784    943           /// <param name="pCursor">
   785    944           /// The native pointer to the sqlite3_vtab_cursor derived structure.
   786    945           /// </param>
   787    946           /// <param name="rowId">
   788    947           /// Upon success, this parameter must be modified to contain the unique
................................................................................
   795    954               IntPtr pCursor,
   796    955               ref long rowId
   797    956               );
   798    957   
   799    958           ///////////////////////////////////////////////////////////////////////
   800    959   
   801    960           /// <summary>
          961  +        /// <para><code>
          962  +        ///   int (*xUpdate)(
          963  +        ///     sqlite3_vtab *pVTab,
          964  +        ///     int argc,
          965  +        ///     sqlite3_value **argv,
          966  +        ///     sqlite_int64 *pRowid
          967  +        ///   );
          968  +        /// </code></para>
   802    969           /// <para>
   803    970           /// All changes to a virtual table are made using the xUpdate method.
   804    971           /// This one method can be used to insert, delete, or update.
   805    972           /// </para>
   806    973           /// <para>
   807         -        /// The argc parameter specifies the number of entries in the argv
   808         -        /// array. The value of argc will be 1 for a pure delete operation or
   809         -        /// N+2 for an insert or replace or update where N is the number of
   810         -        /// columns in the table. In the previous sentence, N includes any
   811         -        /// hidden columns.
          974  +        /// The argc parameter specifies the number of entries in the argv array. 
          975  +        /// The value of argc will be 1 for a pure delete operation or N+2 for an insert
          976  +        /// or replace or update where N is the number of columns in the table.  
          977  +        /// In the previous sentence, N includes any hidden columns.
   812    978           /// </para>
   813    979           /// <para>
   814         -        /// Every argv entry will have a non-NULL value in C but may contain
   815         -        /// the SQL value NULL. In other words, it is always true that
   816         -        /// argv[i]!=0 for i between 0 and argc-1. However, it might be the
   817         -        /// case that sqlite3_value_type(argv[i])==SQLITE_NULL.
          980  +        /// Every argv entry will have a non-NULL value in C but may contain the 
          981  +        /// SQL value NULL.  In other words, it is always true that
          982  +        /// <![CDATA[<tt>]]>argv[i]!=0<![CDATA[</tt>]]> for <![CDATA[<b>]]>i<![CDATA[</b>]]> between 0 and <![CDATA[<tt>]]>argc-1<![CDATA[</tt>]]>.
          983  +        /// However, it might be the case that
          984  +        /// <![CDATA[<tt>]]>sqlite3_value_type(argv[i])==SQLITE_NULL<![CDATA[</tt>]]>.
   818    985           /// </para>
   819    986           /// <para>
   820         -        /// The argv[0] parameter is the rowid of a row in the virtual table
          987  +        /// The argv[0] parameter is the rowid of a row in the virtual table 
   821    988           /// to be deleted. If argv[0] is an SQL NULL, then no deletion occurs.
   822    989           /// </para>
   823    990           /// <para>
   824         -        /// The argv[1] parameter is the rowid of a new row to be inserted into
   825         -        /// the virtual table. If argv[1] is an SQL NULL, then the
   826         -        /// implementation must choose a rowid for the newly inserted row.
   827         -        /// Subsequent argv[] entries contain values of the columns of the
   828         -        /// virtual table, in the order that the columns were declared. The
   829         -        /// number of columns will match the table declaration that the
   830         -        /// xConnect or xCreate method made using the sqlite3_declare_vtab()
   831         -        /// call. All hidden columns are included.
   832         -        /// </para>
   833         -        /// <para>
   834         -        /// When doing an insert without a rowid (argc>1, argv[1] is an SQL
   835         -        /// NULL), the implementation must set *pRowid to the rowid of the
   836         -        /// newly inserted row; this will become the value returned by the
   837         -        /// sqlite3_last_insert_rowid() function. Setting this value in all the
   838         -        /// other cases is a harmless no-op; the SQLite engine ignores the
   839         -        /// *pRowid return value if argc==1 or argv[1] is not an SQL NULL.
   840         -        /// </para>
   841         -        /// <para>
   842         -        /// Each call to xUpdate will fall into one of cases shown below. Note
   843         -        /// that references to argv[i] mean the SQL value held within the
   844         -        /// argv[i] object, not the argv[i] object itself.
   845         -        /// </para>
   846         -        /// <code>
   847         -        ///     argc = 1
   848         -        /// </code>
   849         -        /// <para>
   850         -        ///         The single row with rowid equal to argv[0] is deleted. No
   851         -        ///         insert occurs.
   852         -        /// </para>
   853         -        /// <code>
   854         -        ///     argc > 1
   855         -        ///     argv[0] = NULL
   856         -        /// </code>
   857         -        /// <para>
   858         -        ///         A new row is inserted with a rowid argv[1] and column
   859         -        ///         values in argv[2] and following. If argv[1] is an SQL NULL,
   860         -        ///         the a new unique rowid is generated automatically.
   861         -        /// </para>
   862         -        /// <code>
   863         -        ///     argc > 1
   864         -        ///     argv[0] ? NULL
   865         -        ///     argv[0] = argv[1]
   866         -        /// </code>
   867         -        /// <para>
   868         -        ///         The row with rowid argv[0] is updated with new values in
   869         -        ///         argv[2] and following parameters.
   870         -        /// </para>
   871         -        /// <code>
   872         -        ///     argc > 1
   873         -        ///     argv[0] ? NULL
   874         -        ///     argv[0] ? argv[1]
   875         -        /// </code>
   876         -        /// <para>
   877         -        ///         The row with rowid argv[0] is updated with rowid argv[1]
   878         -        ///         and new values in argv[2] and following parameters. This
   879         -        ///         will occur when an SQL statement updates a rowid, as in
   880         -        ///         the statement:
   881         -        /// </para>
   882         -        /// <code>
   883         -        ///             UPDATE table SET rowid=rowid+1 WHERE ...;
   884         -        /// </code>
          991  +        /// The argv[1] parameter is the rowid of a new row to be inserted 
          992  +        /// into the virtual table. If argv[1] is an SQL NULL, then the implementation 
          993  +        /// must choose a rowid for the newly inserted row. Subsequent argv[] 
          994  +        /// entries contain values of the columns of the virtual table, in the 
          995  +        /// order that the columns were declared. The number of columns will
          996  +        /// match the table declaration that the xConnect or xCreate method made 
          997  +        /// using the sqlite3_declare_vtab() call.  All hidden columns are included.
          998  +        /// </para>
          999  +        /// <para>
         1000  +        /// When doing an insert without a rowid (argc>1, argv[1] is an SQL NULL), the 
         1001  +        /// implementation must set *pRowid to the rowid of the newly inserted row; 
         1002  +        /// this will become the value returned by the sqlite3_last_insert_rowid()
         1003  +        /// function. Setting this value in all the other cases is a harmless no-op;
         1004  +        /// the SQLite engine ignores the *pRowid return value if argc==1 or 
         1005  +        /// argv[1] is not an SQL NULL.
         1006  +        /// </para>
         1007  +        /// <para>
         1008  +        /// Each call to xUpdate will fall into one of cases shown below.
         1009  +        /// Not that references to <![CDATA[<b>]]>argv[i]<![CDATA[</b>]]> mean the SQL value
         1010  +        /// held within the argv[i] object, not the argv[i]
         1011  +        /// object itself.
         1012  +        /// </para>
         1013  +        /// <para><code>
         1014  +        /// <![CDATA[<dl>]]>
         1015  +        /// <![CDATA[<dt>]]><![CDATA[<b>]]>argc = 1<![CDATA[</b>]]>
         1016  +        /// <![CDATA[<dd>]]>The single row with rowid equal to argv[0] is deleted. No insert occurs.
         1017  +        /// <![CDATA[<dt>]]><![CDATA[<b>]]>argc &gt; 1 <![CDATA[<br>]]> argv[0] = NULL<![CDATA[</b>]]>
         1018  +        /// <![CDATA[<dd>]]>A new row is inserted with a rowid argv[1] and column values in
         1019  +        ///        argv[2] and following.  If argv[1] is an SQL NULL,
         1020  +        ///        the a new unique rowid is generated automatically.
         1021  +        /// <![CDATA[<dt>]]><![CDATA[<b>]]>argc &gt; 1 <![CDATA[<br>]]> argv[0] &#8800; NULL <![CDATA[<br>]]> argv[0] = argv[1]<![CDATA[</b>]]>
         1022  +        /// <![CDATA[<dd>]]>The row with rowid argv[0] is updated with new values 
         1023  +        ///        in argv[2] and following parameters.
         1024  +        /// <![CDATA[<dt>]]><![CDATA[<b>]]>argc &gt; 1 <![CDATA[<br>]]> argv[0] &#8800; NULL <![CDATA[<br>]]> argv[0] &#8800; argv[1]<![CDATA[</b>]]>
         1025  +        /// <![CDATA[<dd>]]> The row with rowid argv[0] is updated with rowid argv[1] 
         1026  +        /// and new values in argv[2] and following parameters. This will occur 
         1027  +        /// when an SQL statement updates a rowid, as in the statement:
         1028  +        /// <para><code>
         1029  +        ///    UPDATE table SET rowid=rowid+1 WHERE ...; 
         1030  +        /// </code></para>
         1031  +        /// <![CDATA[</dl>]]>
         1032  +        /// </code></para>
   885   1033           /// <para>
   886   1034           /// The xUpdate method must return SQLITE_OK if and only if it is
   887         -        /// successful. If a failure occurs, the xUpdate must return an
   888         -        /// appropriate error code. On a failure, the pVTab->zErrMsg element
   889         -        /// may optionally be replaced with error message text stored in memory
   890         -        /// allocated from SQLite using functions such as sqlite3_mprintf() or
   891         -        /// sqlite3_malloc().
         1035  +        /// successful.  If a failure occurs, the xUpdate must return an appropriate
         1036  +        /// error code.  On a failure, the pVTab->zErrMsg element may optionally
         1037  +        /// be replaced with error message text stored in memory allocated from SQLite 
         1038  +        /// using functions such as sqlite3_mprintf() or sqlite3_malloc().
   892   1039           /// </para>
   893   1040           /// <para>
   894   1041           /// If the xUpdate method violates some constraint of the virtual table
   895         -        /// (including, but not limited to, attempting to store a value of the
   896         -        /// wrong datatype, attempting to store a value that is too large or
   897         -        /// too small, or attempting to change a read-only value) then the
         1042  +        /// (including, but not limited to, attempting to store a value of the wrong 
         1043  +        /// datatype, attempting to store a value that is too
         1044  +        /// large or too small, or attempting to change a read-only value) then the
   898   1045           /// xUpdate must fail with an appropriate error code.
   899   1046           /// </para>
   900   1047           /// <para>
   901         -        /// There might be one or more sqlite3_vtab_cursor objects open and in
   902         -        /// use on the virtual table instance and perhaps even on the row of
   903         -        /// the virtual table when the xUpdate method is invoked. The
   904         -        /// implementation of xUpdate must be prepared for attempts to delete
   905         -        /// or modify rows of the table out from other existing cursors. If the
   906         -        /// virtual table cannot accommodate such changes, the xUpdate method
   907         -        /// must return an error code.
         1048  +        /// There might be one or more sqlite3_vtab_cursor objects open and in use 
         1049  +        /// on the virtual table instance and perhaps even on the row of the virtual
         1050  +        /// table when the xUpdate method is invoked.  The implementation of
         1051  +        /// xUpdate must be prepared for attempts to delete or modify rows of the table
         1052  +        /// out from other existing cursors.  If the virtual table cannot accommodate
         1053  +        /// such changes, the xUpdate method must return an error code.
   908   1054           /// </para>
   909   1055           /// <para>
   910         -        /// The xUpdate method is optional. If the xUpdate pointer in the
   911         -        /// sqlite3_module for a virtual table is a NULL pointer, then the
   912         -        /// virtual table is read-only.
         1056  +        /// The xUpdate method is optional.
         1057  +        /// If the xUpdate pointer in the sqlite3_module for a virtual table
         1058  +        /// is a NULL pointer, then the virtual table is read-only.
   913   1059           /// </para>
   914   1060           /// </summary>
   915   1061           /// <param name="pVtab">
   916   1062           /// The native pointer to the sqlite3_vtab derived structure.
   917   1063           /// </param>
   918   1064           /// <param name="argc">
   919   1065           /// The number of new or modified column values contained in
................................................................................
   936   1082               IntPtr argv,
   937   1083               ref long rowId
   938   1084               );
   939   1085   
   940   1086           ///////////////////////////////////////////////////////////////////////
   941   1087   
   942   1088           /// <summary>
         1089  +        /// <para><code>
         1090  +        ///   int (*xBegin)(sqlite3_vtab *pVTab);
         1091  +        /// </code></para>
   943   1092           /// <para>
   944         -        /// This method begins a transaction on a virtual table. This is method
   945         -        /// is optional. The xBegin pointer of sqlite3_module may be NULL.
         1093  +        /// This method begins a transaction on a virtual table.
         1094  +        /// This is method is optional.  The xBegin pointer of sqlite3_module
         1095  +        /// may be NULL.
   946   1096           /// </para>
   947   1097           /// <para>
   948         -        /// This method is always followed by one call to either the xCommit or
   949         -        /// xRollback method. Virtual table transactions do not nest, so the
   950         -        /// xBegin method will not be invoked more than once on a single
   951         -        /// virtual table without an intervening call to either xCommit or
   952         -        /// xRollback. Multiple calls to other methods can and likely will
   953         -        /// occur in between the xBegin and the corresponding xCommit or
   954         -        /// xRollback.
         1098  +        /// This method is always followed by one call to either the
         1099  +        /// xCommit or xRollback method.  Virtual table transactions do
         1100  +        /// not nest, so the xBegin method will not be invoked more than once
         1101  +        /// on a single virtual table
         1102  +        /// without an intervening call to either xCommit or xRollback.
         1103  +        /// Multiple calls to other methods can and likely will occur in between
         1104  +        /// the xBegin and the corresponding xCommit or xRollback.
   955   1105           /// </para>
   956   1106           /// </summary>
   957   1107           /// <param name="pVtab">
   958   1108           /// The native pointer to the sqlite3_vtab derived structure.
   959   1109           /// </param>
   960   1110           /// <returns>
   961   1111           /// A standard SQLite return code.
................................................................................
   963   1113           SQLiteErrorCode xBegin(
   964   1114               IntPtr pVtab
   965   1115               );
   966   1116   
   967   1117           ///////////////////////////////////////////////////////////////////////
   968   1118   
   969   1119           /// <summary>
         1120  +        /// <para><code>
         1121  +        ///   int (*xSync)(sqlite3_vtab *pVTab);
         1122  +        /// </code></para>
   970   1123           /// <para>
   971   1124           /// This method signals the start of a two-phase commit on a virtual
   972         -        /// table. This is method is optional. The xSync pointer of
   973         -        /// sqlite3_module may be NULL.
         1125  +        /// table.
         1126  +        /// This is method is optional.  The xSync pointer of sqlite3_module
         1127  +        /// may be NULL.
   974   1128           /// </para>
   975   1129           /// <para>
   976   1130           /// This method is only invoked after call to the xBegin method and
   977         -        /// prior to an xCommit or xRollback. In order to implement two-phase
         1131  +        /// prior to an xCommit or xRollback.  In order to implement two-phase
   978   1132           /// commit, the xSync method on all virtual tables is invoked prior to
   979         -        /// invoking the xCommit method on any virtual table. If any of the
         1133  +        /// invoking the xCommit method on any virtual table.  If any of the 
   980   1134           /// xSync methods fail, the entire transaction is rolled back.
   981   1135           /// </para>
   982   1136           /// </summary>
   983   1137           /// <param name="pVtab">
   984   1138           /// The native pointer to the sqlite3_vtab derived structure.
   985   1139           /// </param>
   986   1140           /// <returns>
................................................................................
   989   1143           SQLiteErrorCode xSync(
   990   1144               IntPtr pVtab
   991   1145               );
   992   1146   
   993   1147           ///////////////////////////////////////////////////////////////////////
   994   1148   
   995   1149           /// <summary>
         1150  +        /// <para><code>
         1151  +        ///   int (*xCommit)(sqlite3_vtab *pVTab);
         1152  +        /// </code></para>
   996   1153           /// <para>
   997         -        /// This method causes a virtual table transaction to commit. This is
   998         -        /// method is optional. The xCommit pointer of sqlite3_module may be
   999         -        /// NULL.
         1154  +        /// This method causes a virtual table transaction to commit.
         1155  +        /// This is method is optional.  The xCommit pointer of sqlite3_module
         1156  +        /// may be NULL.
  1000   1157           /// </para>
  1001   1158           /// <para>
  1002   1159           /// A call to this method always follows a prior call to xBegin and
  1003   1160           /// xSync.
  1004   1161           /// </para>
  1005   1162           /// </summary>
  1006   1163           /// <param name="pVtab">
................................................................................
  1012   1169           SQLiteErrorCode xCommit(
  1013   1170               IntPtr pVtab
  1014   1171               );
  1015   1172   
  1016   1173           ///////////////////////////////////////////////////////////////////////
  1017   1174   
  1018   1175           /// <summary>
         1176  +        /// <para><code>
         1177  +        ///   int (*xRollback)(sqlite3_vtab *pVTab);
         1178  +        /// </code></para>
  1019   1179           /// <para>
  1020         -        /// This method causes a virtual table transaction to rollback. This is
  1021         -        /// method is optional. The xRollback pointer of sqlite3_module may be
  1022         -        /// NULL.
         1180  +        /// This method causes a virtual table transaction to rollback.
         1181  +        /// This is method is optional.  The xRollback pointer of sqlite3_module
         1182  +        /// may be NULL.
  1023   1183           /// </para>
  1024   1184           /// <para>
  1025   1185           /// A call to this method always follows a prior call to xBegin.
  1026   1186           /// </para>
  1027   1187           /// </summary>
  1028   1188           /// <param name="pVtab">
  1029   1189           /// The native pointer to the sqlite3_vtab derived structure.
................................................................................
  1034   1194           SQLiteErrorCode xRollback(
  1035   1195               IntPtr pVtab
  1036   1196               );
  1037   1197   
  1038   1198           ///////////////////////////////////////////////////////////////////////
  1039   1199   
  1040   1200           /// <summary>
         1201  +        /// <para><code>
         1202  +        ///   int (*xFindFunction)(
         1203  +        ///     sqlite3_vtab *pVtab,
         1204  +        ///     int nArg,
         1205  +        ///     const char *zName,
         1206  +        ///     void (**pxFunc)(sqlite3_context*,int,sqlite3_value**),
         1207  +        ///     void **ppArg
         1208  +        ///   );
         1209  +        /// </code></para>
  1041   1210           /// <para>
  1042         -        /// This method provides notification that the virtual table
  1043         -        /// implementation that the virtual table will be given a new name. If
  1044         -        /// this method returns SQLITE_OK then SQLite renames the table. If
  1045         -        /// this method returns an error code then the renaming is prevented.
         1211  +        /// This method is called during sqlite3_prepare() to give the virtual
         1212  +        /// table implementation an opportunity to overload functions. 
         1213  +        /// This method may be set to NULL in which case no overloading occurs.
         1214  +        /// </para>
         1215  +        /// <para>
         1216  +        /// When a function uses a column from a virtual table as its first 
         1217  +        /// argument, this method is called to see if the virtual table would 
         1218  +        /// like to overload the function. The first three parameters are inputs: 
         1219  +        /// the virtual table, the number of arguments to the function, and the 
         1220  +        /// name of the function. If no overloading is desired, this method
         1221  +        /// returns 0. To overload the function, this method writes the new 
         1222  +        /// function implementation into *pxFunc and writes user data into *ppArg 
         1223  +        /// and returns 1.
         1224  +        /// </para>
         1225  +        /// <para>
         1226  +        /// Note that infix functions (LIKE, GLOB, REGEXP, and MATCH) reverse 
         1227  +        /// the order of their arguments. So "like(A,B)" is equivalent to "B like A". 
         1228  +        /// For the form "B like A" the B term is considered the first argument 
         1229  +        /// to the function. But for "like(A,B)" the A term is considered the 
         1230  +        /// first argument.
  1046   1231           /// </para>
  1047   1232           /// <para>
  1048         -        /// The xRename method is required for every virtual table
  1049         -        /// implementation.
         1233  +        /// The function pointer returned by this routine must be valid for
         1234  +        /// the lifetime of the sqlite3_vtab object given in the first parameter.
  1050   1235           /// </para>
  1051   1236           /// </summary>
  1052   1237           /// <param name="pVtab">
  1053   1238           /// The native pointer to the sqlite3_vtab derived structure.
  1054   1239           /// </param>
  1055   1240           /// <param name="nArg">
  1056   1241           /// The number of arguments to the function being sought.
................................................................................
  1077   1262               ref SQLiteCallback callback,
  1078   1263               ref IntPtr pClientData
  1079   1264               );
  1080   1265   
  1081   1266           ///////////////////////////////////////////////////////////////////////
  1082   1267   
  1083   1268           /// <summary>
         1269  +        /// <para><code>
         1270  +        ///   int (*xRename)(sqlite3_vtab *pVtab, const char *zNew);
         1271  +        /// </code></para>
  1084   1272           /// <para>
  1085         -        /// This method provides notification that the virtual table
  1086         -        /// implementation that the virtual table will be given a new name. If
  1087         -        /// this method returns SQLITE_OK then SQLite renames the table. If
  1088         -        /// this method returns an error code then the renaming is prevented.
         1273  +        /// This method provides notification that the virtual table implementation
         1274  +        /// that the virtual table will be given a new name. 
         1275  +        /// If this method returns SQLITE_OK then SQLite renames the table.
         1276  +        /// If this method returns an error code then the renaming is prevented.
  1089   1277           /// </para>
  1090   1278           /// <para>
  1091         -        /// The xRename method is required for every virtual table
  1092         -        /// implementation.
         1279  +        /// The xRename method is required for every virtual table implementation.
  1093   1280           /// </para>
  1094   1281           /// </summary>
  1095   1282           /// <param name="pVtab">
  1096   1283           /// The native pointer to the sqlite3_vtab derived structure.
  1097   1284           /// </param>
  1098   1285           /// <param name="zNew">
  1099   1286           /// The native pointer to the UTF-8 encoded string containing the new
................................................................................
  1106   1293               IntPtr pVtab,
  1107   1294               IntPtr zNew
  1108   1295               );
  1109   1296   
  1110   1297           ///////////////////////////////////////////////////////////////////////
  1111   1298   
  1112   1299           /// <summary>
         1300  +        /// <para><code>
         1301  +        ///   int (*xSavepoint)(sqlite3_vtab *pVtab, int);
         1302  +        ///   int (*xRelease)(sqlite3_vtab *pVtab, int);
         1303  +        ///   int (*xRollbackTo)(sqlite3_vtab *pVtab, int);
         1304  +        /// </code></para>
  1113   1305           /// <para>
  1114         -        /// These methods provide the virtual table implementation an
  1115         -        /// opportunity to implement nested transactions. They are always
  1116         -        /// optional and will only be called in SQLite version 3.7.7 and later.
         1306  +        /// These methods provide the virtual table implementation an opportunity to
         1307  +        /// implement nested transactions.  They are always optional and will only be
         1308  +        /// called in SQLite version 3.7.7 and later.
  1117   1309           /// </para>
  1118   1310           /// <para>
  1119         -        /// When xSavepoint(X,N) is invoked, that is a signal to the virtual
  1120         -        /// table X that it should save its current state as savepoint N. A
  1121         -        /// subsequent call to xRollbackTo(X,R) means that the state of the
  1122         -        /// virtual table should return to what it was when xSavepoint(X,R) was
  1123         -        /// last called. The call to xRollbackTo(X,R) will invalidate all
  1124         -        /// savepoints with N>R; none of the invalided savepoints will be
  1125         -        /// rolled back or released without first being reinitialized by a call
  1126         -        /// to xSavepoint(). A call to xRelease(X,M) invalidates all savepoints
  1127         -        /// where N>=M.
         1311  +        /// When xSavepoint(X,N) is invoked, that is a signal to the virtual table X
         1312  +        /// that it should save its current state as savepoint N.  
         1313  +        /// A subsequent call
         1314  +        /// to xRollbackTo(X,R) means that the state of the virtual table should return
         1315  +        /// to what it was when xSavepoint(X,R) was last called.  
         1316  +        /// The call
         1317  +        /// to xRollbackTo(X,R) will invalidate all savepoints with N>R; none of the
         1318  +        /// invalided savepoints will be rolled back or released without first
         1319  +        /// being reinitialized by a call to xSavepoint().  
         1320  +        /// A call to xRelease(X,M) invalidates all savepoints where N>=M.
  1128   1321           /// </para>
  1129   1322           /// <para>
  1130         -        /// None of the xSavepoint(), xRelease(), or xRollbackTo() methods will
  1131         -        /// ever be called except in between calls to xBegin() and either
  1132         -        /// xCommit() or xRollback().
         1323  +        /// None of the xSavepoint(), xRelease(), or xRollbackTo() methods will ever
         1324  +        /// be called except in between calls to xBegin() and 
         1325  +        /// either xCommit() or xRollback().
  1133   1326           /// </para>
  1134   1327           /// </summary>
  1135   1328           /// <param name="pVtab">
  1136   1329           /// The native pointer to the sqlite3_vtab derived structure.
  1137   1330           /// </param>
  1138   1331           /// <param name="iSavepoint">
  1139   1332           /// This is an integer identifier under which the the current state of
................................................................................
  1146   1339               IntPtr pVtab,
  1147   1340               int iSavepoint
  1148   1341               );
  1149   1342   
  1150   1343           ///////////////////////////////////////////////////////////////////////
  1151   1344   
  1152   1345           /// <summary>
         1346  +        /// <para><code>
         1347  +        ///   int (*xSavepoint)(sqlite3_vtab *pVtab, int);
         1348  +        ///   int (*xRelease)(sqlite3_vtab *pVtab, int);
         1349  +        ///   int (*xRollbackTo)(sqlite3_vtab *pVtab, int);
         1350  +        /// </code></para>
  1153   1351           /// <para>
  1154         -        /// These methods provide the virtual table implementation an
  1155         -        /// opportunity to implement nested transactions. They are always
  1156         -        /// optional and will only be called in SQLite version 3.7.7 and later.
         1352  +        /// These methods provide the virtual table implementation an opportunity to
         1353  +        /// implement nested transactions.  They are always optional and will only be
         1354  +        /// called in SQLite version 3.7.7 and later.
  1157   1355           /// </para>
  1158   1356           /// <para>
  1159         -        /// When xSavepoint(X,N) is invoked, that is a signal to the virtual
  1160         -        /// table X that it should save its current state as savepoint N. A
  1161         -        /// subsequent call to xRollbackTo(X,R) means that the state of the
  1162         -        /// virtual table should return to what it was when xSavepoint(X,R) was
  1163         -        /// last called. The call to xRollbackTo(X,R) will invalidate all
  1164         -        /// savepoints with N>R; none of the invalided savepoints will be
  1165         -        /// rolled back or released without first being reinitialized by a call
  1166         -        /// to xSavepoint(). A call to xRelease(X,M) invalidates all savepoints
  1167         -        /// where N>=M.
         1357  +        /// When xSavepoint(X,N) is invoked, that is a signal to the virtual table X
         1358  +        /// that it should save its current state as savepoint N.  
         1359  +        /// A subsequent call
         1360  +        /// to xRollbackTo(X,R) means that the state of the virtual table should return
         1361  +        /// to what it was when xSavepoint(X,R) was last called.  
         1362  +        /// The call
         1363  +        /// to xRollbackTo(X,R) will invalidate all savepoints with N>R; none of the
         1364  +        /// invalided savepoints will be rolled back or released without first
         1365  +        /// being reinitialized by a call to xSavepoint().  
         1366  +        /// A call to xRelease(X,M) invalidates all savepoints where N>=M.
  1168   1367           /// </para>
  1169   1368           /// <para>
  1170         -        /// None of the xSavepoint(), xRelease(), or xRollbackTo() methods will
  1171         -        /// ever be called except in between calls to xBegin() and either
  1172         -        /// xCommit() or xRollback().
         1369  +        /// None of the xSavepoint(), xRelease(), or xRollbackTo() methods will ever
         1370  +        /// be called except in between calls to xBegin() and 
         1371  +        /// either xCommit() or xRollback().
  1173   1372           /// </para>
  1174   1373           /// </summary>
  1175   1374           /// <param name="pVtab">
  1176   1375           /// The native pointer to the sqlite3_vtab derived structure.
  1177   1376           /// </param>
  1178   1377           /// <param name="iSavepoint">
  1179   1378           /// This is an integer used to indicate that any saved states with an
................................................................................
  1187   1386               IntPtr pVtab,
  1188   1387               int iSavepoint
  1189   1388               );
  1190   1389   
  1191   1390           ///////////////////////////////////////////////////////////////////////
  1192   1391   
  1193   1392           /// <summary>
         1393  +        /// <para><code>
         1394  +        ///   int (*xSavepoint)(sqlite3_vtab *pVtab, int);
         1395  +        ///   int (*xRelease)(sqlite3_vtab *pVtab, int);
         1396  +        ///   int (*xRollbackTo)(sqlite3_vtab *pVtab, int);
         1397  +        /// </code></para>
  1194   1398           /// <para>
  1195         -        /// These methods provide the virtual table implementation an
  1196         -        /// opportunity to implement nested transactions. They are always
  1197         -        /// optional and will only be called in SQLite version 3.7.7 and later.
         1399  +        /// These methods provide the virtual table implementation an opportunity to
         1400  +        /// implement nested transactions.  They are always optional and will only be
         1401  +        /// called in SQLite version 3.7.7 and later.
  1198   1402           /// </para>
  1199   1403           /// <para>
  1200         -        /// When xSavepoint(X,N) is invoked, that is a signal to the virtual
  1201         -        /// table X that it should save its current state as savepoint N. A
  1202         -        /// subsequent call to xRollbackTo(X,R) means that the state of the
  1203         -        /// virtual table should return to what it was when xSavepoint(X,R) was
  1204         -        /// last called. The call to xRollbackTo(X,R) will invalidate all
  1205         -        /// savepoints with N>R; none of the invalided savepoints will be
  1206         -        /// rolled back or released without first being reinitialized by a call
  1207         -        /// to xSavepoint(). A call to xRelease(X,M) invalidates all savepoints
  1208         -        /// where N>=M.
         1404  +        /// When xSavepoint(X,N) is invoked, that is a signal to the virtual table X
         1405  +        /// that it should save its current state as savepoint N.  
         1406  +        /// A subsequent call
         1407  +        /// to xRollbackTo(X,R) means that the state of the virtual table should return
         1408  +        /// to what it was when xSavepoint(X,R) was last called.  
         1409  +        /// The call
         1410  +        /// to xRollbackTo(X,R) will invalidate all savepoints with N>R; none of the
         1411  +        /// invalided savepoints will be rolled back or released without first
         1412  +        /// being reinitialized by a call to xSavepoint().  
         1413  +        /// A call to xRelease(X,M) invalidates all savepoints where N>=M.
  1209   1414           /// </para>
  1210   1415           /// <para>
  1211         -        /// None of the xSavepoint(), xRelease(), or xRollbackTo() methods will
  1212         -        /// ever be called except in between calls to xBegin() and either
  1213         -        /// xCommit() or xRollback().
         1416  +        /// None of the xSavepoint(), xRelease(), or xRollbackTo() methods will ever
         1417  +        /// be called except in between calls to xBegin() and 
         1418  +        /// either xCommit() or xRollback().
  1214   1419           /// </para>
  1215   1420           /// </summary>
  1216   1421           /// <param name="pVtab">
  1217   1422           /// The native pointer to the sqlite3_vtab derived structure.
  1218   1423           /// </param>
  1219   1424           /// <param name="iSavepoint">
  1220   1425           /// This is an integer identifier used to specify a specific saved
  1221   1426           /// state for the virtual table for it to restore itself back to, which
  1222   1427           /// should also have the effect of deleting all saved states with an
  1223   1428           /// integer identifier greater than this one.
  1224         -        /// <list type=""></list>
  1225   1429           /// </param>
  1226   1430           /// <returns>
  1227   1431           /// A standard SQLite return code.
  1228   1432           /// </returns>
  1229   1433           SQLiteErrorCode xRollbackTo(
  1230   1434               IntPtr pVtab,
  1231   1435               int iSavepoint
  1232   1436               );
  1233   1437       }
  1234   1438       #endregion
  1235   1439   }