System.Data.SQLite
Check-in [f31a811fbb]
Not logged in

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

Overview
Comment:More work on docs.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | virtualTables
Files: files | file ages | folders
SHA1: f31a811fbb122f520e4a73277958c772772cbcf0
User & Date: mistachkin 2013-06-25 06:40:08
Context
2013-06-25
06:58
Document the SQLiteMemory class. check-in: 3b2c842774 user: mistachkin tags: virtualTables
06:40
More work on docs. check-in: f31a811fbb user: mistachkin tags: virtualTables
04:17
Add SQLiteNativeModule class. Revise table/cursor error handling methods of the SQLiteModule class to add the static variants of them. Rename the old CreateNativeModuleImpl method to GetNativeModuleImpl. Add new CreateNativeModuleImpl method that returns the default ISQLiteNativeModule implementation. More work on docs. check-in: c6554ef4c6 user: mistachkin tags: virtualTables
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to Doc/buildChm.tcl.

    78     78   
    79     79   if {[string length $xmlDocFile] == 0 || ![file exists $xmlDocFile]} then {
    80     80     puts stdout "Cannot find XML doc file: $xmlDocFile"
    81     81     exit 1
    82     82   }
    83     83   
    84     84   set data [readFile $xmlDocFile]
           85  +set count 0
           86  +
    85     87   set pattern { cref="([A-Z]):System\.Data\.SQLite\.}
    86         -set count [regsub -all -- $pattern $data { cref="\1:system.Data.SQLite.} data]
           88  +incr count [regsub -all -- $pattern $data { cref="\1:system.Data.SQLite.} data]
           89  +
           90  +set pattern { name="([A-Z]):System\.Data\.SQLite\.}
           91  +incr count [regsub -all -- $pattern $data { name="\1:system.Data.SQLite.} data]
    87     92   
    88     93   if {$count > 0} then {
    89     94     writeFile $xmlDocFile $data
    90     95   } else {
    91     96     puts stdout "*WARNING* File \"$xmlDocFile\" does not match: $pattern"
    92     97   }
    93     98   

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

   283    283           #endregion
   284    284       }
   285    285       #endregion
   286    286   
   287    287       ///////////////////////////////////////////////////////////////////////////
   288    288   
   289    289       #region SQLiteValue Helper Class
          290  +    /// <summary>
          291  +    /// This class represents a value from the SQLite core library that can be
          292  +    /// passed to the sqlite3_value_*() and associated functions.
          293  +    /// </summary>
   290    294       public sealed class SQLiteValue : ISQLiteNativeHandle
   291    295       {
   292    296           #region Private Data
   293    297           /// <summary>
   294    298           /// The native value handle.
   295    299           /// </summary>
   296    300           private IntPtr pValue;
................................................................................
  1595   1599       /// <summary>
  1596   1600       /// This interface represents a virtual table implementation written in
  1597   1601       /// native code.
  1598   1602       /// </summary>
  1599   1603       public interface ISQLiteNativeModule
  1600   1604       {
  1601   1605           /// <summary>
         1606  +        /// <para>
  1602   1607           /// This method is called to create a new instance of a virtual table
  1603   1608           /// in response to a CREATE VIRTUAL TABLE statement. The db parameter
  1604   1609           /// is a pointer to the SQLite database connection that is executing
  1605   1610           /// the CREATE VIRTUAL TABLE statement. The pAux argument is the copy
  1606   1611           /// of the client data pointer that was the fourth argument to the
  1607   1612           /// sqlite3_create_module() or sqlite3_create_module_v2() call that
  1608   1613           /// registered the virtual table module. The argv parameter is an
................................................................................
  1616   1621           /// database, or "temp" for TEMP database, or the name given at the
  1617   1622           /// end of the ATTACH statement for attached databases. The third
  1618   1623           /// element of the array, argv[2], is the name of the new virtual
  1619   1624           /// table, as specified following the TABLE keyword in the CREATE
  1620   1625           /// VIRTUAL TABLE statement. If present, the fourth and subsequent
  1621   1626           /// strings in the argv[] array report the arguments to the module name
  1622   1627           /// in the CREATE VIRTUAL TABLE statement.
  1623         -        ///
         1628  +        /// </para>
         1629  +        /// <para>
  1624   1630           /// The job of this method is to construct the new virtual table object
  1625   1631           /// (an sqlite3_vtab object) and return a pointer to it in *ppVTab.
  1626         -        ///
         1632  +        /// </para>
         1633  +        /// <para>
  1627   1634           /// As part of the task of creating a new sqlite3_vtab structure, this
  1628   1635           /// method must invoke sqlite3_declare_vtab() to tell the SQLite core
  1629   1636           /// about the columns and datatypes in the virtual table. The
  1630   1637           /// sqlite3_declare_vtab() API has the following prototype:
  1631         -        ///
         1638  +        /// </para>
         1639  +        /// <para>
         1640  +        /// <code>
  1632   1641           /// int sqlite3_declare_vtab(sqlite3 *db, const char *zCreateTable)
  1633         -        ///
         1642  +        /// </code>
         1643  +        /// </para>
         1644  +        /// <para>
  1634   1645           /// The first argument to sqlite3_declare_vtab() must be the same
  1635   1646           /// database connection pointer as the first parameter to this method.
  1636   1647           /// The second argument to sqlite3_declare_vtab() must a
  1637   1648           /// zero-terminated UTF-8 string that contains a well-formed CREATE
  1638   1649           /// TABLE statement that defines the columns in the virtual table and
  1639   1650           /// their data types. The name of the table in this CREATE TABLE
  1640   1651           /// statement is ignored, as are all constraints. Only the column names
  1641   1652           /// and datatypes matter. The CREATE TABLE statement string need not to
  1642   1653           /// be held in persistent memory. The string can be deallocated and/or
  1643   1654           /// reused as soon as the sqlite3_declare_vtab() routine returns.
         1655  +        /// </para>
  1644   1656           /// </summary>
  1645   1657           /// <param name="pDb">
  1646   1658           /// The native database connection handle.
  1647   1659           /// </param>
  1648   1660           /// <param name="pAux">
  1649   1661           /// The original native pointer value that was provided to the
  1650   1662           /// sqlite3_create_module(), sqlite3_create_module_v2() or
................................................................................
  1677   1689               ref IntPtr pVtab,
  1678   1690               ref IntPtr pError
  1679   1691               );
  1680   1692   
  1681   1693           ///////////////////////////////////////////////////////////////////////
  1682   1694   
  1683   1695           /// <summary>
         1696  +        /// <para>
  1684   1697           /// The xConnect method is very similar to xCreate. It has the same
  1685   1698           /// parameters and constructs a new sqlite3_vtab structure just like
  1686   1699           /// xCreate. And it must also call sqlite3_declare_vtab() like xCreate.
  1687         -        ///
         1700  +        /// </para>
         1701  +        /// <para>
  1688   1702           /// The difference is that xConnect is called to establish a new
  1689   1703           /// connection to an existing virtual table whereas xCreate is called
  1690   1704           /// to create a new virtual table from scratch.
  1691         -        ///
         1705  +        /// </para>
         1706  +        /// <para>
  1692   1707           /// The xCreate and xConnect methods are only different when the
  1693   1708           /// virtual table has some kind of backing store that must be
  1694   1709           /// initialized the first time the virtual table is created. The
  1695   1710           /// xCreate method creates and initializes the backing store. The
  1696   1711           /// xConnect method just connects to an existing backing store.
  1697         -        ///
         1712  +        /// </para>
         1713  +        /// <para>
  1698   1714           /// As an example, consider a virtual table implementation that
  1699   1715           /// provides read-only access to existing comma-separated-value (CSV)
  1700   1716           /// files on disk. There is no backing store that needs to be created
  1701   1717           /// or initialized for such a virtual table (since the CSV files
  1702   1718           /// already exist on disk) so the xCreate and xConnect methods will be
  1703   1719           /// identical for that module.
  1704         -        ///
         1720  +        /// </para>
         1721  +        /// <para>
  1705   1722           /// Another example is a virtual table that implements a full-text
  1706   1723           /// index. The xCreate method must create and initialize data
  1707   1724           /// structures to hold the dictionary and posting lists for that index.
  1708   1725           /// The xConnect method, on the other hand, only has to locate and use
  1709   1726           /// an existing dictionary and posting lists that were created by a
  1710   1727           /// prior xCreate call.
  1711         -        ///
         1728  +        /// </para>
         1729  +        /// <para>
  1712   1730           /// The xConnect method must return SQLITE_OK if it is successful in
  1713   1731           /// creating the new virtual table, or SQLITE_ERROR if it is not
  1714   1732           /// successful. If not successful, the sqlite3_vtab structure must not
  1715   1733           /// be allocated. An error message may optionally be returned in *pzErr
  1716   1734           /// if unsuccessful. Space to hold the error message string must be
  1717   1735           /// allocated using an SQLite memory allocation function like
  1718   1736           /// sqlite3_malloc() or sqlite3_mprintf() as the SQLite core will
  1719   1737           /// attempt to free the space using sqlite3_free() after the error has
  1720   1738           /// been reported up to the application.
  1721         -        ///
         1739  +        /// </para>
         1740  +        /// <para>
  1722   1741           /// The xConnect method is required for every virtual table
  1723   1742           /// implementation, though the xCreate and xConnect pointers of the
  1724   1743           /// sqlite3_module object may point to the same function the virtual
  1725   1744           /// table does not need to initialize backing store.
         1745  +        /// </para>
  1726   1746           /// </summary>
  1727   1747           /// <param name="pDb">
  1728   1748           /// The native database connection handle.
  1729   1749           /// </param>
  1730   1750           /// <param name="pAux">
  1731   1751           /// The original native pointer value that was provided to the
  1732   1752           /// sqlite3_create_module(), sqlite3_create_module_v2() or
................................................................................
  1759   1779               ref IntPtr pVtab,
  1760   1780               ref IntPtr pError
  1761   1781               );
  1762   1782   
  1763   1783           ///////////////////////////////////////////////////////////////////////
  1764   1784   
  1765   1785           /// <summary>
         1786  +        /// <para>
  1766   1787           /// SQLite uses the xBestIndex method of a virtual table module to
  1767   1788           /// determine the best way to access the virtual table. The xBestIndex
  1768   1789           /// method has a prototype like this:
  1769         -        ///
  1770         -        ///  int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*);
  1771         -        ///
         1790  +        /// </para>
         1791  +        /// <code>
         1792  +        /// int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*);
         1793  +        /// </code>
         1794  +        /// <para>
  1772   1795           /// The SQLite core communicates with the xBestIndex method by filling
  1773   1796           /// in certain fields of the sqlite3_index_info structure and passing a
  1774   1797           /// pointer to that structure into xBestIndex as the second parameter.
  1775   1798           /// The xBestIndex method fills out other fields of this structure
  1776   1799           /// which forms the reply. The sqlite3_index_info structure looks like
  1777   1800           /// this:
  1778         -        ///
         1801  +        /// </para>
         1802  +        /// <code>
  1779   1803           ///  struct sqlite3_index_info {
  1780   1804           ///    /* Inputs */
  1781   1805           ///    const int nConstraint;   /* Number of entries in aConstraint */
  1782   1806           ///    const struct sqlite3_index_constraint {
  1783   1807           ///       int iColumn;          /* Column on left-hand side of
  1784   1808           ///                              * constraint */
  1785   1809           ///       unsigned char op;     /* Constraint operator */
................................................................................
  1804   1828           ///    char *idxStr;            /* String, possibly obtained from
  1805   1829           ///                              * sqlite3_malloc() */
  1806   1830           ///    int needToFreeIdxStr;    /* Free idxStr using sqlite3_free() if
  1807   1831           ///                              * true */
  1808   1832           ///    int orderByConsumed;     /* True if output is already ordered */
  1809   1833           ///    double estimatedCost;    /* Estimated cost of using this index */
  1810   1834           ///  };
  1811         -        ///
         1835  +        /// </code>
         1836  +        /// <para>
  1812   1837           /// In addition, there are some defined constants:
  1813         -        ///
         1838  +        /// </para>
         1839  +        /// <code>
  1814   1840           ///  #define SQLITE_INDEX_CONSTRAINT_EQ    2
  1815   1841           ///  #define SQLITE_INDEX_CONSTRAINT_GT    4
  1816   1842           ///  #define SQLITE_INDEX_CONSTRAINT_LE    8
  1817   1843           ///  #define SQLITE_INDEX_CONSTRAINT_LT    16
  1818   1844           ///  #define SQLITE_INDEX_CONSTRAINT_GE    32
  1819   1845           ///  #define SQLITE_INDEX_CONSTRAINT_MATCH 64
  1820         -        ///
         1846  +        /// </code>
         1847  +        /// <para>
  1821   1848           /// The SQLite core calls the xBestIndex method when it is compiling a
  1822   1849           /// query that involves a virtual table. In other words, SQLite calls
  1823   1850           /// this method when it is running sqlite3_prepare() or the equivalent.
  1824   1851           /// By calling this method, the SQLite core is saying to the virtual
  1825   1852           /// table that it needs to access some subset of the rows in the
  1826   1853           /// virtual table and it wants to know the most efficient way to do
  1827   1854           /// that access. The xBestIndex method replies with information that
  1828   1855           /// the SQLite core can then use to conduct an efficient search of the
  1829   1856           /// virtual table.
  1830         -        ///
         1857  +        /// </para>
         1858  +        /// <para>
  1831   1859           /// While compiling a single SQL query, the SQLite core might call
  1832   1860           /// xBestIndex multiple times with different settings in
  1833   1861           /// sqlite3_index_info. The SQLite core will then select the
  1834   1862           /// combination that appears to give the best performance.
  1835         -        ///
         1863  +        /// </para>
         1864  +        /// <para>
  1836   1865           /// Before calling this method, the SQLite core initializes an instance
  1837   1866           /// of the sqlite3_index_info structure with information about the
  1838   1867           /// query that it is currently trying to process. This information
  1839   1868           /// derives mainly from the WHERE clause and ORDER BY or GROUP BY
  1840   1869           /// clauses of the query, but also from any ON or USING clauses if the
  1841   1870           /// query is a join. The information that the SQLite core provides to
  1842   1871           /// the xBestIndex method is held in the part of the structure that is
  1843   1872           /// marked as "Inputs". The "Outputs" section is initialized to zero.
  1844         -        ///
         1873  +        /// </para>
         1874  +        /// <para>
  1845   1875           /// The information in the sqlite3_index_info structure is ephemeral
  1846   1876           /// and may be overwritten or deallocated as soon as the xBestIndex
  1847   1877           /// method returns. If the xBestIndex method needs to remember any part
  1848   1878           /// of the sqlite3_index_info structure, it should make a copy. Care
  1849   1879           /// must be take to store the copy in a place where it will be
  1850   1880           /// deallocated, such as in the idxStr field with needToFreeIdxStr set
  1851   1881           /// to 1.
  1852         -        ///
         1882  +        /// </para>
         1883  +        /// <para>
  1853   1884           /// Note that xBestIndex will always be called before xFilter, since
  1854   1885           /// the idxNum and idxStr outputs from xBestIndex are required inputs
  1855   1886           /// to xFilter. However, there is no guarantee that xFilter will be
  1856   1887           /// called following a successful xBestIndex.
  1857         -        ///
         1888  +        /// </para>
         1889  +        /// <para>
  1858   1890           /// The xBestIndex method is required for every virtual table
  1859   1891           /// implementation.
  1860         -        /// 
         1892  +        /// </para>
         1893  +        /// <para>
  1861   1894           /// 2.3.1 Inputs
  1862         -        ///
         1895  +        /// </para>
         1896  +        /// <para>
  1863   1897           /// The main thing that the SQLite core is trying to communicate to the
  1864   1898           /// virtual table is the constraints that are available to limit the
  1865   1899           /// number of rows that need to be searched. The aConstraint[] array
  1866   1900           /// contains one entry for each constraint. There will be exactly
  1867   1901           /// nConstraint entries in that array.
  1868         -        ///
         1902  +        /// </para>
         1903  +        /// <para>
  1869   1904           /// Each constraint will correspond to a term in the WHERE clause or in
  1870   1905           /// a USING or ON clause that is of the form
  1871         -        ///
         1906  +        /// </para>
         1907  +        /// <code>
  1872   1908           ///     column OP EXPR
  1873         -        ///
         1909  +        /// </code>
         1910  +        /// <para>
  1874   1911           /// Where "column" is a column in the virtual table, OP is an operator
  1875   1912           /// like "=" or "&lt;", and EXPR is an arbitrary expression. So, for
  1876   1913           /// example, if the WHERE clause contained a term like this:
  1877         -        ///
         1914  +        /// </para>
         1915  +        /// <code>
  1878   1916           ///          a = 5
  1879         -        ///
         1917  +        /// </code>
         1918  +        /// <para>
  1880   1919           /// Then one of the constraints would be on the "a" column with
  1881   1920           /// operator "=" and an expression of "5". Constraints need not have a
  1882   1921           /// literal representation of the WHERE clause. The query optimizer
  1883   1922           /// might make transformations to the WHERE clause in order to extract
  1884   1923           /// as many constraints as it can. So, for example, if the WHERE clause
  1885   1924           /// contained something like this:
  1886         -        ///
         1925  +        /// </para>
         1926  +        /// <code>
  1887   1927           ///          x BETWEEN 10 AND 100 AND 999&gt;y
  1888         -        ///
         1928  +        /// </code>
         1929  +        /// <para>
  1889   1930           /// The query optimizer might translate this into three separate
  1890   1931           /// constraints:
  1891         -        ///
         1932  +        /// </para>
         1933  +        /// <code>
  1892   1934           ///          x &gt;= 10
  1893   1935           ///          x &lt;= 100
  1894   1936           ///          y &lt; 999
  1895         -        ///
         1937  +        /// </code>
         1938  +        /// <para>
  1896   1939           /// For each constraint, the aConstraint[].iColumn field indicates
  1897   1940           /// which column appears on the left-hand side of the constraint. The
  1898   1941           /// first column of the virtual table is column 0. The rowid of the
  1899   1942           /// virtual table is column -1. The aConstraint[].op field indicates
  1900   1943           /// which operator is used. The SQLITE_INDEX_CONSTRAINT_* constants map
  1901   1944           /// integer constants into operator values. Columns occur in the order
  1902   1945           /// they were defined by the call to sqlite3_declare_vtab() in the
  1903   1946           /// xCreate or xConnect method. Hidden columns are counted when
  1904   1947           /// determining the column index.
  1905         -        ///
         1948  +        /// </para>
         1949  +        /// <para>
  1906   1950           /// The aConstraint[] array contains information about all constraints
  1907   1951           /// that apply to the virtual table. But some of the constraints might
  1908   1952           /// not be usable because of the way tables are ordered in a join. The
  1909   1953           /// xBestIndex method must therefore only consider constraints that
  1910   1954           /// have an aConstraint[].usable flag which is true.
  1911         -        ///
         1955  +        /// </para>
         1956  +        /// <para>
  1912   1957           /// In addition to WHERE clause constraints, the SQLite core also tells
  1913   1958           /// the xBestIndex method about the ORDER BY clause. (In an aggregate
  1914   1959           /// query, the SQLite core might put in GROUP BY clause information in
  1915   1960           /// place of the ORDER BY clause information, but this fact should not
  1916   1961           /// make any difference to the xBestIndex method.) If all terms of the
  1917   1962           /// ORDER BY clause are columns in the virtual table, then nOrderBy
  1918   1963           /// will be the number of terms in the ORDER BY clause and the
  1919   1964           /// aOrderBy[] array will identify the column for each term in the
  1920   1965           /// order by clause and whether or not that column is ASC or DESC.
  1921         -        /// 
         1966  +        /// </para>
         1967  +        /// <para>
  1922   1968           /// 2.3.2 Outputs
  1923         -        ///
         1969  +        /// </para>
         1970  +        /// <para>
  1924   1971           /// Given all of the information above, the job of the xBestIndex
  1925   1972           /// method it to figure out the best way to search the virtual table.
  1926         -        ///
         1973  +        /// </para>
         1974  +        /// <para>
  1927   1975           /// The xBestIndex method fills the idxNum and idxStr fields with
  1928   1976           /// information that communicates an indexing strategy to the xFilter
  1929   1977           /// method. The information in idxNum and idxStr is arbitrary as far as
  1930   1978           /// the SQLite core is concerned. The SQLite core just copies the
  1931   1979           /// information through to the xFilter method. Any desired meaning can
  1932   1980           /// be assigned to idxNum and idxStr as long as xBestIndex and xFilter
  1933   1981           /// agree on what that meaning is.
  1934         -        ///
         1982  +        /// </para>
         1983  +        /// <para>
  1935   1984           /// The idxStr value may be a string obtained from an SQLite memory
  1936   1985           /// allocation function such as sqlite3_mprintf(). If this is the case,
  1937   1986           /// then the needToFreeIdxStr flag must be set to true so that the
  1938   1987           /// SQLite core will know to call sqlite3_free() on that string when it
  1939   1988           /// has finished with it, and thus avoid a memory leak.
  1940         -        ///
         1989  +        /// </para>
         1990  +        /// <para>
  1941   1991           /// If the virtual table will output rows in the order specified by the
  1942   1992           /// ORDER BY clause, then the orderByConsumed flag may be set to true.
  1943   1993           /// If the output is not automatically in the correct order then
  1944   1994           /// orderByConsumed must be left in its default false setting. This
  1945   1995           /// will indicate to the SQLite core that it will need to do a separate
  1946   1996           /// sorting pass over the data after it comes out of the virtual table.
  1947         -        ///
         1997  +        /// </para>
         1998  +        /// <para>
  1948   1999           /// The estimatedCost field should be set to the estimated number of
  1949   2000           /// disk access operations required to execute this query against the
  1950   2001           /// virtual table. The SQLite core will often call xBestIndex multiple
  1951   2002           /// times with different constraints, obtain multiple cost estimates,
  1952   2003           /// then choose the query plan that gives the lowest estimate.
  1953         -        ///
         2004  +        /// </para>
         2005  +        /// <para>
  1954   2006           /// The aConstraintUsage[] array contains one element for each of the
  1955   2007           /// nConstraint constraints in the inputs section of the
  1956   2008           /// sqlite3_index_info structure. The aConstraintUsage[] array is used
  1957   2009           /// by xBestIndex to tell the core how it is using the constraints.
  1958         -        ///
         2010  +        /// </para>
         2011  +        /// <para>
  1959   2012           /// The xBestIndex method may set aConstraintUsage[].argvIndex entries
  1960   2013           /// to values greater than one. Exactly one entry should be set to 1,
  1961   2014           /// another to 2, another to 3, and so forth up to as many or as few as
  1962   2015           /// the xBestIndex method wants. The EXPR of the corresponding
  1963   2016           /// constraints will then be passed in as the argv[] parameters to
  1964   2017           /// xFilter.
  1965         -        ///
         2018  +        /// </para>
         2019  +        /// <para>
  1966   2020           /// For example, if the aConstraint[3].argvIndex is set to 1, then when
  1967   2021           /// xFilter is called, the argv[0] passed to xFilter will have the EXPR
  1968   2022           /// value of the aConstraint[3] constraint.
  1969         -        ///
         2023  +        /// </para>
         2024  +        /// <para>
  1970   2025           /// By default, the SQLite core double checks all constraints on each
  1971   2026           /// row of the virtual table that it receives. If such a check is
  1972   2027           /// redundant, the xBestFilter method can suppress that double-check by
  1973   2028           /// setting aConstraintUsage[].omit.
         2029  +        /// </para>
  1974   2030           /// </summary>
  1975   2031           /// <param name="pVtab">
  1976   2032           /// The native pointer to the sqlite3_vtab derived structure.
  1977   2033           /// </param>
  1978   2034           /// <param name="pIndex">
  1979   2035           /// The native pointer to the sqlite3_index_info structure.
  1980   2036           /// </param>
................................................................................
  1985   2041               IntPtr pVtab,
  1986   2042               IntPtr pIndex
  1987   2043               );
  1988   2044   
  1989   2045           ///////////////////////////////////////////////////////////////////////
  1990   2046   
  1991   2047           /// <summary>
         2048  +        /// <para>
  1992   2049           /// This method releases a connection to a virtual table. Only the
  1993   2050           /// sqlite3_vtab object is destroyed. The virtual table is not
  1994   2051           /// destroyed and any backing store associated with the virtual table
  1995   2052           /// persists. This method undoes the work of xConnect.
  1996         -        ///
         2053  +        /// </para>
         2054  +        /// <para>
  1997   2055           /// This method is a destructor for a connection to the virtual table.
  1998   2056           /// Contrast this method with xDestroy. The xDestroy is a destructor
  1999   2057           /// for the entire virtual table.
  2000         -        ///
         2058  +        /// </para>
         2059  +        /// <para>
  2001   2060           /// The xDisconnect method is required for every virtual table
  2002   2061           /// implementation, though it is acceptable for the xDisconnect and
  2003   2062           /// xDestroy methods to be the same function if that makes sense for
  2004   2063           /// the particular virtual table.
         2064  +        /// </para>
  2005   2065           /// </summary>
  2006   2066           /// <param name="pVtab">
  2007   2067           /// The native pointer to the sqlite3_vtab derived structure.
  2008   2068           /// </param>
  2009   2069           /// <returns>
  2010   2070           /// A standard SQLite return code.
  2011   2071           /// </returns>
................................................................................
  2012   2072           SQLiteErrorCode xDisconnect(
  2013   2073               IntPtr pVtab
  2014   2074               );
  2015   2075   
  2016   2076           ///////////////////////////////////////////////////////////////////////
  2017   2077   
  2018   2078           /// <summary>
         2079  +        /// <para>
  2019   2080           /// This method releases a connection to a virtual table, just like the
  2020   2081           /// xDisconnect method, and it also destroys the underlying table
  2021   2082           /// implementation. This method undoes the work of xCreate.
  2022         -        ///
         2083  +        /// </para>
         2084  +        /// <para>
  2023   2085           /// The xDisconnect method is called whenever a database connection
  2024   2086           /// that uses a virtual table is closed. The xDestroy method is only
  2025   2087           /// called when a DROP TABLE statement is executed against the virtual
  2026   2088           /// table.
  2027         -        ///
         2089  +        /// </para>
         2090  +        /// <para>
  2028   2091           /// The xDestroy method is required for every virtual table
  2029   2092           /// implementation, though it is acceptable for the xDisconnect and
  2030   2093           /// xDestroy methods to be the same function if that makes sense for
  2031   2094           /// the particular virtual table.
         2095  +        /// </para>
  2032   2096           /// </summary>
  2033   2097           /// <param name="pVtab">
  2034   2098           /// The native pointer to the sqlite3_vtab derived structure.
  2035   2099           /// </param>
  2036   2100           /// <returns>
  2037   2101           /// A standard SQLite return code.
  2038   2102           /// </returns>
................................................................................
  2039   2103           SQLiteErrorCode xDestroy(
  2040   2104               IntPtr pVtab
  2041   2105               );
  2042   2106   
  2043   2107           ///////////////////////////////////////////////////////////////////////
  2044   2108   
  2045   2109           /// <summary>
         2110  +        /// <para>
  2046   2111           /// The xOpen method creates a new cursor used for accessing (read
  2047   2112           /// and/or writing) a virtual table. A successful invocation of this
  2048   2113           /// method will allocate the memory for the sqlite3_vtab_cursor (or a
  2049   2114           /// subclass), initialize the new object, and make *ppCursor point to
  2050   2115           /// the new object. The successful call then returns SQLITE_OK.
  2051         -        ///
         2116  +        /// </para>
         2117  +        /// <para>
  2052   2118           /// For every successful call to this method, the SQLite core will
  2053   2119           /// later invoke the xClose method to destroy the allocated cursor.
  2054         -        ///
         2120  +        /// </para>
         2121  +        /// <para>
  2055   2122           /// The xOpen method need not initialize the pVtab field of the
  2056   2123           /// sqlite3_vtab_cursor structure. The SQLite core will take care of
  2057   2124           /// that chore automatically.
  2058         -        ///
         2125  +        /// </para>
         2126  +        /// <para>
  2059   2127           /// A virtual table implementation must be able to support an arbitrary
  2060   2128           /// number of simultaneously open cursors.
  2061         -        ///
         2129  +        /// </para>
         2130  +        /// <para>
  2062   2131           /// When initially opened, the cursor is in an undefined state. The
  2063   2132           /// SQLite core will invoke the xFilter method on the cursor prior to
  2064   2133           /// any attempt to position or read from the cursor.
  2065         -        ///
         2134  +        /// </para>
         2135  +        /// <para>
  2066   2136           /// The xOpen method is required for every virtual table
  2067   2137           /// implementation.
         2138  +        /// </para>
  2068   2139           /// </summary>
  2069   2140           /// <param name="pVtab">
  2070   2141           /// The native pointer to the sqlite3_vtab derived structure.
  2071   2142           /// </param>
  2072   2143           /// <param name="pCursor">
  2073   2144           /// Upon success, this parameter must be modified to point to the newly
  2074   2145           /// created native sqlite3_vtab_cursor derived structure.
................................................................................
  2080   2151               IntPtr pVtab,
  2081   2152               ref IntPtr pCursor
  2082   2153               );
  2083   2154   
  2084   2155           ///////////////////////////////////////////////////////////////////////
  2085   2156   
  2086   2157           /// <summary>
         2158  +        /// <para>
  2087   2159           /// The xClose method closes a cursor previously opened by xOpen. The
  2088   2160           /// SQLite core will always call xClose once for each cursor opened
  2089   2161           /// using xOpen.
  2090         -        ///
         2162  +        /// </para>
         2163  +        /// <para>
  2091   2164           /// This method must release all resources allocated by the
  2092   2165           /// corresponding xOpen call. The routine will not be called again even
  2093   2166           /// if it returns an error. The SQLite core will not use the
  2094   2167           /// sqlite3_vtab_cursor again after it has been closed.
  2095         -        ///
         2168  +        /// </para>
         2169  +        /// <para>
  2096   2170           /// The xClose method is required for every virtual table
  2097   2171           /// implementation.
         2172  +        /// </para>
  2098   2173           /// </summary>
  2099   2174           /// <param name="pCursor">
  2100   2175           /// The native pointer to the sqlite3_vtab_cursor derived structure.
  2101   2176           /// </param>
  2102   2177           /// <returns>
  2103   2178           /// A standard SQLite return code.
  2104   2179           /// </returns>
................................................................................
  2105   2180           SQLiteErrorCode xClose(
  2106   2181               IntPtr pCursor
  2107   2182               );
  2108   2183   
  2109   2184           ///////////////////////////////////////////////////////////////////////
  2110   2185   
  2111   2186           /// <summary>
         2187  +        /// <para>
  2112   2188           /// This method begins a search of a virtual table. The first argument
  2113   2189           /// is a cursor opened by xOpen. The next two argument define a
  2114   2190           /// particular search index previously chosen by xBestIndex. The
  2115   2191           /// specific meanings of idxNum and idxStr are unimportant as long as
  2116   2192           /// xFilter and xBestIndex agree on what that meaning is.
  2117         -        ///
         2193  +        /// </para>
         2194  +        /// <para>
  2118   2195           /// The xBestIndex function may have requested the values of certain
  2119   2196           /// expressions using the aConstraintUsage[].argvIndex values of the
  2120   2197           /// sqlite3_index_info structure. Those values are passed to xFilter
  2121   2198           /// using the argc and argv parameters.
  2122         -        ///
         2199  +        /// </para>
         2200  +        /// <para>
  2123   2201           /// If the virtual table contains one or more rows that match the
  2124   2202           /// search criteria, then the cursor must be left point at the first
  2125   2203           /// row. Subsequent calls to xEof must return false (zero). If there
  2126   2204           /// are no rows match, then the cursor must be left in a state that
  2127   2205           /// will cause the xEof to return true (non-zero). The SQLite engine
  2128   2206           /// will use the xColumn and xRowid methods to access that row content.
  2129   2207           /// The xNext method will be used to advance to the next row.
  2130         -        ///
         2208  +        /// </para>
         2209  +        /// <para>
  2131   2210           /// This method must return SQLITE_OK if successful, or an sqlite error
  2132   2211           /// code if an error occurs.
  2133         -        ///
         2212  +        /// </para>
         2213  +        /// <para>
  2134   2214           /// The xFilter method is required for every virtual table
  2135   2215           /// implementation.
         2216  +        /// </para>
  2136   2217           /// </summary>
  2137   2218           /// <param name="pCursor">
  2138   2219           /// The native pointer to the sqlite3_vtab_cursor derived structure.
  2139   2220           /// </param>
  2140   2221           /// <param name="idxNum">
  2141   2222           /// Number used to help identify the selected index.
  2142   2223           /// </param>
................................................................................
  2162   2243               int argc,
  2163   2244               IntPtr[] argv
  2164   2245               );
  2165   2246   
  2166   2247           ///////////////////////////////////////////////////////////////////////
  2167   2248   
  2168   2249           /// <summary>
         2250  +        /// <para>
  2169   2251           /// The xNext method advances a virtual table cursor to the next row of
  2170   2252           /// a result set initiated by xFilter. If the cursor is already
  2171   2253           /// pointing at the last row when this routine is called, then the
  2172   2254           /// cursor no longer points to valid data and a subsequent call to the
  2173   2255           /// xEof method must return true (non-zero). If the cursor is
  2174   2256           /// successfully advanced to another row of content, then subsequent
  2175   2257           /// calls to xEof must return false (zero).
  2176         -        ///
         2258  +        /// </para>
         2259  +        /// <para>
  2177   2260           /// This method must return SQLITE_OK if successful, or an sqlite error
  2178   2261           /// code if an error occurs.
  2179         -        ///
         2262  +        /// </para>
         2263  +        /// <para>
  2180   2264           /// The xNext method is required for every virtual table
  2181   2265           /// implementation.
         2266  +        /// </para>
  2182   2267           /// </summary>
  2183   2268           /// <param name="pCursor">
  2184   2269           /// The native pointer to the sqlite3_vtab_cursor derived structure.
  2185   2270           /// </param>
  2186   2271           /// <returns>
  2187   2272           /// A standard SQLite return code.
  2188   2273           /// </returns>
................................................................................
  2189   2274           SQLiteErrorCode xNext(
  2190   2275               IntPtr pCursor
  2191   2276               );
  2192   2277   
  2193   2278           ///////////////////////////////////////////////////////////////////////
  2194   2279   
  2195   2280           /// <summary>
         2281  +        /// <para>
  2196   2282           /// The xEof method must return false (zero) if the specified cursor
  2197   2283           /// currently points to a valid row of data, or true (non-zero)
  2198   2284           /// otherwise. This method is called by the SQL engine immediately
  2199   2285           /// after each xFilter and xNext invocation.
  2200         -        ///
         2286  +        /// </para>
         2287  +        /// <para>
  2201   2288           /// The xEof method is required for every virtual table implementation.
         2289  +        /// </para>
  2202   2290           /// </summary>
  2203   2291           /// <param name="pCursor">
  2204   2292           /// The native pointer to the sqlite3_vtab_cursor derived structure.
  2205   2293           /// </param>
  2206   2294           /// <returns>
  2207   2295           /// Non-zero if no more rows are available; zero otherwise.
  2208   2296           /// </returns>
................................................................................
  2209   2297           int xEof(
  2210   2298               IntPtr pCursor
  2211   2299               );
  2212   2300   
  2213   2301           ///////////////////////////////////////////////////////////////////////
  2214   2302   
  2215   2303           /// <summary>
         2304  +        /// <para>
  2216   2305           /// The SQLite core invokes this method in order to find the value for
  2217   2306           /// the N-th column of the current row. N is zero-based so the first
  2218   2307           /// column is numbered 0. The xColumn method may return its result back
  2219   2308           /// to SQLite using one of the following interface:
  2220         -        ///
  2221         -        ///     * sqlite3_result_blob()
  2222         -        ///     * sqlite3_result_double()
  2223         -        ///     * sqlite3_result_int()
  2224         -        ///     * sqlite3_result_int64()
  2225         -        ///     * sqlite3_result_null()
  2226         -        ///     * sqlite3_result_text()
  2227         -        ///     * sqlite3_result_text16()
  2228         -        ///     * sqlite3_result_text16le()
  2229         -        ///     * sqlite3_result_text16be()
  2230         -        ///     * sqlite3_result_zeroblob()
  2231         -        ///
         2309  +        /// </para>
         2310  +        /// <code>
         2311  +        ///     sqlite3_result_blob()
         2312  +        ///     sqlite3_result_double()
         2313  +        ///     sqlite3_result_int()
         2314  +        ///     sqlite3_result_int64()
         2315  +        ///     sqlite3_result_null()
         2316  +        ///     sqlite3_result_text()
         2317  +        ///     sqlite3_result_text16()
         2318  +        ///     sqlite3_result_text16le()
         2319  +        ///     sqlite3_result_text16be()
         2320  +        ///     sqlite3_result_zeroblob()
         2321  +        /// </code>
         2322  +        /// <para>
  2232   2323           /// If the xColumn method implementation calls none of the functions
  2233   2324           /// above, then the value of the column defaults to an SQL NULL.
  2234         -        ///
         2325  +        /// </para>
         2326  +        /// <para>
  2235   2327           /// To raise an error, the xColumn method should use one of the
  2236   2328           /// result_text() methods to set the error message text, then return an
  2237   2329           /// appropriate error code. The xColumn method must return SQLITE_OK on
  2238   2330           /// success.
  2239         -        ///
         2331  +        /// </para>
         2332  +        /// <para>
  2240   2333           /// The xColumn method is required for every virtual table
  2241   2334           /// implementation.
         2335  +        /// </para>
  2242   2336           /// </summary>
  2243   2337           /// <param name="pCursor">
  2244   2338           /// The native pointer to the sqlite3_vtab_cursor derived structure.
  2245   2339           /// </param>
  2246   2340           /// <param name="pContext">
  2247   2341           /// The native pointer to the sqlite3_context structure to be used
  2248   2342           /// for returning the specified column value to the SQLite core
................................................................................
  2260   2354               IntPtr pContext,
  2261   2355               int index
  2262   2356               );
  2263   2357   
  2264   2358           ///////////////////////////////////////////////////////////////////////
  2265   2359   
  2266   2360           /// <summary>
         2361  +        /// <para>
  2267   2362           /// A successful invocation of this method will cause *pRowid to be
  2268   2363           /// filled with the rowid of row that the virtual table cursor pCur is
  2269   2364           /// currently pointing at. This method returns SQLITE_OK on success. It
  2270   2365           /// returns an appropriate error code on failure.
  2271         -        ///
         2366  +        /// </para>
         2367  +        /// <para>
  2272   2368           /// The xRowid method is required for every virtual table
  2273   2369           /// implementation.
         2370  +        /// </para>
  2274   2371           /// </summary>
  2275   2372           /// <param name="pCursor">
  2276   2373           /// The native pointer to the sqlite3_vtab_cursor derived structure.
  2277   2374           /// </param>
  2278   2375           /// <param name="rowId">
  2279   2376           /// Upon success, this parameter must be modified to contain the unique
  2280   2377           /// integer row identifier for the current row for the specified cursor.
................................................................................
  2286   2383               IntPtr pCursor,
  2287   2384               ref long rowId
  2288   2385               );
  2289   2386   
  2290   2387           ///////////////////////////////////////////////////////////////////////
  2291   2388   
  2292   2389           /// <summary>
         2390  +        /// <para>
  2293   2391           /// All changes to a virtual table are made using the xUpdate method.
  2294   2392           /// This one method can be used to insert, delete, or update.
  2295         -        ///
         2393  +        /// </para>
         2394  +        /// <para>
  2296   2395           /// The argc parameter specifies the number of entries in the argv
  2297   2396           /// array. The value of argc will be 1 for a pure delete operation or
  2298   2397           /// N+2 for an insert or replace or update where N is the number of
  2299   2398           /// columns in the table. In the previous sentence, N includes any
  2300   2399           /// hidden columns.
  2301         -        ///
         2400  +        /// </para>
         2401  +        /// <para>
  2302   2402           /// Every argv entry will have a non-NULL value in C but may contain
  2303   2403           /// the SQL value NULL. In other words, it is always true that
  2304   2404           /// argv[i]!=0 for i between 0 and argc-1. However, it might be the
  2305   2405           /// case that sqlite3_value_type(argv[i])==SQLITE_NULL.
  2306         -        ///
         2406  +        /// </para>
         2407  +        /// <para>
  2307   2408           /// The argv[0] parameter is the rowid of a row in the virtual table
  2308   2409           /// to be deleted. If argv[0] is an SQL NULL, then no deletion occurs.
  2309         -        ///
         2410  +        /// </para>
         2411  +        /// <para>
  2310   2412           /// The argv[1] parameter is the rowid of a new row to be inserted into
  2311   2413           /// the virtual table. If argv[1] is an SQL NULL, then the
  2312   2414           /// implementation must choose a rowid for the newly inserted row.
  2313   2415           /// Subsequent argv[] entries contain values of the columns of the
  2314   2416           /// virtual table, in the order that the columns were declared. The
  2315   2417           /// number of columns will match the table declaration that the
  2316   2418           /// xConnect or xCreate method made using the sqlite3_declare_vtab()
  2317   2419           /// call. All hidden columns are included.
  2318         -        ///
         2420  +        /// </para>
         2421  +        /// <para>
  2319   2422           /// When doing an insert without a rowid (argc>1, argv[1] is an SQL
  2320   2423           /// NULL), the implementation must set *pRowid to the rowid of the
  2321   2424           /// newly inserted row; this will become the value returned by the
  2322   2425           /// sqlite3_last_insert_rowid() function. Setting this value in all the
  2323   2426           /// other cases is a harmless no-op; the SQLite engine ignores the
  2324   2427           /// *pRowid return value if argc==1 or argv[1] is not an SQL NULL.
  2325         -        ///
         2428  +        /// </para>
         2429  +        /// <para>
  2326   2430           /// Each call to xUpdate will fall into one of cases shown below. Note
  2327   2431           /// that references to argv[i] mean the SQL value held within the
  2328   2432           /// argv[i] object, not the argv[i] object itself.
  2329         -        ///
         2433  +        /// </para>
         2434  +        /// <code>
  2330   2435           ///     argc = 1
  2331         -        ///
         2436  +        /// </code>
         2437  +        /// <para>
  2332   2438           ///         The single row with rowid equal to argv[0] is deleted. No
  2333   2439           ///         insert occurs.
  2334         -        ///
         2440  +        /// </para>
         2441  +        /// <code>
  2335   2442           ///     argc > 1
  2336   2443           ///     argv[0] = NULL
  2337         -        ///
         2444  +        /// </code>
         2445  +        /// <para>
  2338   2446           ///         A new row is inserted with a rowid argv[1] and column
  2339   2447           ///         values in argv[2] and following. If argv[1] is an SQL NULL,
  2340   2448           ///         the a new unique rowid is generated automatically.
  2341         -        ///
         2449  +        /// </para>
         2450  +        /// <code>
  2342   2451           ///     argc > 1
  2343   2452           ///     argv[0] ? NULL
  2344   2453           ///     argv[0] = argv[1]
  2345         -        ///
         2454  +        /// </code>
         2455  +        /// <para>
  2346   2456           ///         The row with rowid argv[0] is updated with new values in
  2347   2457           ///         argv[2] and following parameters.
  2348         -        ///
         2458  +        /// </para>
         2459  +        /// <code>
  2349   2460           ///     argc > 1
  2350   2461           ///     argv[0] ? NULL
  2351   2462           ///     argv[0] ? argv[1]
  2352         -        ///
         2463  +        /// </code>
         2464  +        /// <para>
  2353   2465           ///         The row with rowid argv[0] is updated with rowid argv[1]
  2354   2466           ///         and new values in argv[2] and following parameters. This
  2355   2467           ///         will occur when an SQL statement updates a rowid, as in
  2356   2468           ///         the statement:
  2357         -        ///
         2469  +        /// </para>
         2470  +        /// <code>
  2358   2471           ///             UPDATE table SET rowid=rowid+1 WHERE ...;
  2359         -        ///
         2472  +        /// </code>
         2473  +        /// <para>
  2360   2474           /// The xUpdate method must return SQLITE_OK if and only if it is
  2361   2475           /// successful. If a failure occurs, the xUpdate must return an
  2362   2476           /// appropriate error code. On a failure, the pVTab->zErrMsg element
  2363   2477           /// may optionally be replaced with error message text stored in memory
  2364   2478           /// allocated from SQLite using functions such as sqlite3_mprintf() or
  2365   2479           /// sqlite3_malloc().
  2366         -        ///
         2480  +        /// </para>
         2481  +        /// <para>
  2367   2482           /// If the xUpdate method violates some constraint of the virtual table
  2368   2483           /// (including, but not limited to, attempting to store a value of the
  2369   2484           /// wrong datatype, attempting to store a value that is too large or
  2370   2485           /// too small, or attempting to change a read-only value) then the
  2371   2486           /// xUpdate must fail with an appropriate error code.
  2372         -        ///
         2487  +        /// </para>
         2488  +        /// <para>
  2373   2489           /// There might be one or more sqlite3_vtab_cursor objects open and in
  2374   2490           /// use on the virtual table instance and perhaps even on the row of
  2375   2491           /// the virtual table when the xUpdate method is invoked. The
  2376   2492           /// implementation of xUpdate must be prepared for attempts to delete
  2377   2493           /// or modify rows of the table out from other existing cursors. If the
  2378   2494           /// virtual table cannot accommodate such changes, the xUpdate method
  2379   2495           /// must return an error code.
  2380         -        ///
         2496  +        /// </para>
         2497  +        /// <para>
  2381   2498           /// The xUpdate method is optional. If the xUpdate pointer in the
  2382   2499           /// sqlite3_module for a virtual table is a NULL pointer, then the
  2383   2500           /// virtual table is read-only.
         2501  +        /// </para>
  2384   2502           /// </summary>
  2385   2503           /// <param name="pVtab">
  2386   2504           /// The native pointer to the sqlite3_vtab derived structure.
  2387   2505           /// </param>
  2388   2506           /// <param name="argc">
  2389   2507           /// The number of new or modified column values contained in
  2390   2508           /// <paramref name="argv" />.
................................................................................
  2406   2524               IntPtr[] argv,
  2407   2525               ref long rowId
  2408   2526               );
  2409   2527   
  2410   2528           ///////////////////////////////////////////////////////////////////////
  2411   2529   
  2412   2530           /// <summary>
         2531  +        /// <para>
  2413   2532           /// This method begins a transaction on a virtual table. This is method
  2414   2533           /// is optional. The xBegin pointer of sqlite3_module may be NULL.
  2415         -        ///
         2534  +        /// </para>
         2535  +        /// <para>
  2416   2536           /// This method is always followed by one call to either the xCommit or
  2417   2537           /// xRollback method. Virtual table transactions do not nest, so the
  2418   2538           /// xBegin method will not be invoked more than once on a single
  2419   2539           /// virtual table without an intervening call to either xCommit or
  2420   2540           /// xRollback. Multiple calls to other methods can and likely will
  2421   2541           /// occur in between the xBegin and the corresponding xCommit or
  2422   2542           /// xRollback.
         2543  +        /// </para>
  2423   2544           /// </summary>
  2424   2545           /// <param name="pVtab">
  2425   2546           /// The native pointer to the sqlite3_vtab derived structure.
  2426   2547           /// </param>
  2427   2548           /// <returns>
  2428   2549           /// A standard SQLite return code.
  2429   2550           /// </returns>
................................................................................
  2430   2551           SQLiteErrorCode xBegin(
  2431   2552               IntPtr pVtab
  2432   2553               );
  2433   2554   
  2434   2555           ///////////////////////////////////////////////////////////////////////
  2435   2556   
  2436   2557           /// <summary>
         2558  +        /// <para>
  2437   2559           /// This method signals the start of a two-phase commit on a virtual
  2438   2560           /// table. This is method is optional. The xSync pointer of
  2439   2561           /// sqlite3_module may be NULL.
  2440         -        ///
         2562  +        /// </para>
         2563  +        /// <para>
  2441   2564           /// This method is only invoked after call to the xBegin method and
  2442   2565           /// prior to an xCommit or xRollback. In order to implement two-phase
  2443   2566           /// commit, the xSync method on all virtual tables is invoked prior to
  2444   2567           /// invoking the xCommit method on any virtual table. If any of the
  2445   2568           /// xSync methods fail, the entire transaction is rolled back.
         2569  +        /// </para>
  2446   2570           /// </summary>
  2447   2571           /// <param name="pVtab">
  2448   2572           /// The native pointer to the sqlite3_vtab derived structure.
  2449   2573           /// </param>
  2450   2574           /// <returns>
  2451   2575           /// A standard SQLite return code.
  2452   2576           /// </returns>
................................................................................
  2453   2577           SQLiteErrorCode xSync(
  2454   2578               IntPtr pVtab
  2455   2579               );
  2456   2580   
  2457   2581           ///////////////////////////////////////////////////////////////////////
  2458   2582   
  2459   2583           /// <summary>
         2584  +        /// <para>
  2460   2585           /// This method causes a virtual table transaction to commit. This is
  2461   2586           /// method is optional. The xCommit pointer of sqlite3_module may be
  2462   2587           /// NULL.
  2463         -        ///
         2588  +        /// </para>
         2589  +        /// <para>
  2464   2590           /// A call to this method always follows a prior call to xBegin and
  2465   2591           /// xSync.
         2592  +        /// </para>
  2466   2593           /// </summary>
  2467   2594           /// <param name="pVtab">
  2468   2595           /// The native pointer to the sqlite3_vtab derived structure.
  2469   2596           /// </param>
  2470   2597           /// <returns>
  2471   2598           /// A standard SQLite return code.
  2472   2599           /// </returns>
................................................................................
  2473   2600           SQLiteErrorCode xCommit(
  2474   2601               IntPtr pVtab
  2475   2602               );
  2476   2603   
  2477   2604           ///////////////////////////////////////////////////////////////////////
  2478   2605   
  2479   2606           /// <summary>
         2607  +        /// <para>
  2480   2608           /// This method causes a virtual table transaction to rollback. This is
  2481   2609           /// method is optional. The xRollback pointer of sqlite3_module may be
  2482   2610           /// NULL.
  2483         -        ///
         2611  +        /// </para>
         2612  +        /// <para>
  2484   2613           /// A call to this method always follows a prior call to xBegin.
         2614  +        /// </para>
  2485   2615           /// </summary>
  2486   2616           /// <param name="pVtab">
  2487   2617           /// The native pointer to the sqlite3_vtab derived structure.
  2488   2618           /// </param>
  2489   2619           /// <returns>
  2490   2620           /// A standard SQLite return code.
  2491   2621           /// </returns>
................................................................................
  2492   2622           SQLiteErrorCode xRollback(
  2493   2623               IntPtr pVtab
  2494   2624               );
  2495   2625   
  2496   2626           ///////////////////////////////////////////////////////////////////////
  2497   2627   
  2498   2628           /// <summary>
         2629  +        /// <para>
  2499   2630           /// This method provides notification that the virtual table
  2500   2631           /// implementation that the virtual table will be given a new name. If
  2501   2632           /// this method returns SQLITE_OK then SQLite renames the table. If
  2502   2633           /// this method returns an error code then the renaming is prevented.
  2503         -        ///
         2634  +        /// </para>
         2635  +        /// <para>
  2504   2636           /// The xRename method is required for every virtual table
  2505   2637           /// implementation.
         2638  +        /// </para>
  2506   2639           /// </summary>
  2507   2640           /// <param name="pVtab">
  2508   2641           /// The native pointer to the sqlite3_vtab derived structure.
  2509   2642           /// </param>
  2510   2643           /// <param name="nArg">
  2511   2644           /// The number of arguments to the function being sought.
  2512   2645           /// </param>
................................................................................
  2532   2665               ref SQLiteCallback callback,
  2533   2666               ref IntPtr pClientData
  2534   2667               );
  2535   2668   
  2536   2669           ///////////////////////////////////////////////////////////////////////
  2537   2670   
  2538   2671           /// <summary>
         2672  +        /// <para>
  2539   2673           /// This method provides notification that the virtual table
  2540   2674           /// implementation that the virtual table will be given a new name. If
  2541   2675           /// this method returns SQLITE_OK then SQLite renames the table. If
  2542   2676           /// this method returns an error code then the renaming is prevented.
  2543         -        ///
         2677  +        /// </para>
         2678  +        /// <para>
  2544   2679           /// The xRename method is required for every virtual table
  2545   2680           /// implementation.
         2681  +        /// </para>
  2546   2682           /// </summary>
  2547   2683           /// <param name="pVtab">
  2548   2684           /// The native pointer to the sqlite3_vtab derived structure.
  2549   2685           /// </param>
  2550   2686           /// <param name="zNew">
  2551   2687           /// The native pointer to the UTF-8 encoded string containing the new
  2552   2688           /// name for the virtual table.
................................................................................
  2558   2694               IntPtr pVtab,
  2559   2695               IntPtr zNew
  2560   2696               );
  2561   2697   
  2562   2698           ///////////////////////////////////////////////////////////////////////
  2563   2699   
  2564   2700           /// <summary>
         2701  +        /// <para>
  2565   2702           /// These methods provide the virtual table implementation an
  2566   2703           /// opportunity to implement nested transactions. They are always
  2567   2704           /// optional and will only be called in SQLite version 3.7.7 and later.
  2568         -        ///
         2705  +        /// </para>
         2706  +        /// <para>
  2569   2707           /// When xSavepoint(X,N) is invoked, that is a signal to the virtual
  2570   2708           /// table X that it should save its current state as savepoint N. A
  2571   2709           /// subsequent call to xRollbackTo(X,R) means that the state of the
  2572   2710           /// virtual table should return to what it was when xSavepoint(X,R) was
  2573   2711           /// last called. The call to xRollbackTo(X,R) will invalidate all
  2574   2712           /// savepoints with N>R; none of the invalided savepoints will be
  2575   2713           /// rolled back or released without first being reinitialized by a call
  2576   2714           /// to xSavepoint(). A call to xRelease(X,M) invalidates all savepoints
  2577   2715           /// where N>=M.
  2578         -        ///
         2716  +        /// </para>
         2717  +        /// <para>
  2579   2718           /// None of the xSavepoint(), xRelease(), or xRollbackTo() methods will
  2580   2719           /// ever be called except in between calls to xBegin() and either
  2581   2720           /// xCommit() or xRollback().
         2721  +        /// </para>
  2582   2722           /// </summary>
  2583   2723           /// <param name="pVtab">
  2584   2724           /// The native pointer to the sqlite3_vtab derived structure.
  2585   2725           /// </param>
  2586   2726           /// <param name="iSavepoint">
  2587   2727           /// This is an integer identifier under which the the current state of
  2588   2728           /// the virtual table should be saved.
................................................................................
  2594   2734               IntPtr pVtab,
  2595   2735               int iSavepoint
  2596   2736               );
  2597   2737   
  2598   2738           ///////////////////////////////////////////////////////////////////////
  2599   2739   
  2600   2740           /// <summary>
         2741  +        /// <para>
  2601   2742           /// These methods provide the virtual table implementation an
  2602   2743           /// opportunity to implement nested transactions. They are always
  2603   2744           /// optional and will only be called in SQLite version 3.7.7 and later.
  2604         -        ///
         2745  +        /// </para>
         2746  +        /// <para>
  2605   2747           /// When xSavepoint(X,N) is invoked, that is a signal to the virtual
  2606   2748           /// table X that it should save its current state as savepoint N. A
  2607   2749           /// subsequent call to xRollbackTo(X,R) means that the state of the
  2608   2750           /// virtual table should return to what it was when xSavepoint(X,R) was
  2609   2751           /// last called. The call to xRollbackTo(X,R) will invalidate all
  2610   2752           /// savepoints with N>R; none of the invalided savepoints will be
  2611   2753           /// rolled back or released without first being reinitialized by a call
  2612   2754           /// to xSavepoint(). A call to xRelease(X,M) invalidates all savepoints
  2613   2755           /// where N>=M.
  2614         -        ///
         2756  +        /// </para>
         2757  +        /// <para>
  2615   2758           /// None of the xSavepoint(), xRelease(), or xRollbackTo() methods will
  2616   2759           /// ever be called except in between calls to xBegin() and either
  2617   2760           /// xCommit() or xRollback().
         2761  +        /// </para>
  2618   2762           /// </summary>
  2619   2763           /// <param name="pVtab">
  2620   2764           /// The native pointer to the sqlite3_vtab derived structure.
  2621   2765           /// </param>
  2622   2766           /// <param name="iSavepoint">
  2623   2767           /// This is an integer used to indicate that any saved states with an
  2624   2768           /// identifier greater than or equal to this should be deleted by the
................................................................................
  2631   2775               IntPtr pVtab,
  2632   2776               int iSavepoint
  2633   2777               );
  2634   2778   
  2635   2779           ///////////////////////////////////////////////////////////////////////
  2636   2780   
  2637   2781           /// <summary>
         2782  +        /// <para>
  2638   2783           /// These methods provide the virtual table implementation an
  2639   2784           /// opportunity to implement nested transactions. They are always
  2640   2785           /// optional and will only be called in SQLite version 3.7.7 and later.
  2641         -        ///
         2786  +        /// </para>
         2787  +        /// <para>
  2642   2788           /// When xSavepoint(X,N) is invoked, that is a signal to the virtual
  2643   2789           /// table X that it should save its current state as savepoint N. A
  2644   2790           /// subsequent call to xRollbackTo(X,R) means that the state of the
  2645   2791           /// virtual table should return to what it was when xSavepoint(X,R) was
  2646   2792           /// last called. The call to xRollbackTo(X,R) will invalidate all
  2647   2793           /// savepoints with N>R; none of the invalided savepoints will be
  2648   2794           /// rolled back or released without first being reinitialized by a call
  2649   2795           /// to xSavepoint(). A call to xRelease(X,M) invalidates all savepoints
  2650   2796           /// where N>=M.
  2651         -        ///
         2797  +        /// </para>
         2798  +        /// <para>
  2652   2799           /// None of the xSavepoint(), xRelease(), or xRollbackTo() methods will
  2653   2800           /// ever be called except in between calls to xBegin() and either
  2654   2801           /// xCommit() or xRollback().
         2802  +        /// </para>
  2655   2803           /// </summary>
  2656   2804           /// <param name="pVtab">
  2657   2805           /// The native pointer to the sqlite3_vtab derived structure.
  2658   2806           /// </param>
  2659   2807           /// <param name="iSavepoint">
  2660   2808           /// This is an integer identifier used to specify a specific saved
  2661   2809           /// state for the virtual table for it to restore itself back to, which
................................................................................
  4035   4183               /// </param>
  4036   4184               /// <param name="pVtab">
  4037   4185               /// See the <see cref="ISQLiteNativeModule.xConnect" /> method.
  4038   4186               /// </param>
  4039   4187               /// <param name="pError">
  4040   4188               /// See the <see cref="ISQLiteNativeModule.xConnect" /> method.
  4041   4189               /// </param>
  4042         -            /// <returns></returns>
         4190  +            /// <returns>
         4191  +            /// See the <see cref="ISQLiteNativeModule.xConnect" /> method.
         4192  +            /// </returns>
  4043   4193               public SQLiteErrorCode xConnect(
  4044   4194                   IntPtr pDb,
  4045   4195                   IntPtr pAux,
  4046   4196                   int argc,
  4047   4197                   IntPtr[] argv,
  4048   4198                   ref IntPtr pVtab,
  4049   4199                   ref IntPtr pError
................................................................................
  4693   4843               #endregion
  4694   4844           }
  4695   4845           #endregion
  4696   4846   
  4697   4847           ///////////////////////////////////////////////////////////////////////
  4698   4848   
  4699   4849           #region Private Constants
  4700         -        private const double DefaultCost = double.MaxValue;
         4850  +        /// <summary>
         4851  +        /// The default estimated cost for use with the
         4852  +        /// <see cref="ISQLiteManagedModule.BestIndex" /> method.
         4853  +        /// </summary>
         4854  +        private static readonly double DefaultEstimatedCost = double.MaxValue;
         4855  +
         4856  +        ///////////////////////////////////////////////////////////////////////
         4857  +
         4858  +        /// <summary>
         4859  +        /// The default version of the native sqlite3_module structure in use.
         4860  +        /// </summary>
         4861  +        private static readonly int DefaultModuleVersion = 2;
  4701   4862           #endregion
  4702   4863   
  4703   4864           ///////////////////////////////////////////////////////////////////////
  4704   4865   
  4705   4866           #region Private Data
         4867  +        /// <summary>
         4868  +        /// This field is used to store the native sqlite3_module structure
         4869  +        /// associated with this object instance.
         4870  +        /// </summary>
  4706   4871           private UnsafeNativeMethods.sqlite3_module nativeModule;
         4872  +
         4873  +        ///////////////////////////////////////////////////////////////////////
         4874  +
         4875  +        /// <summary>
         4876  +        /// This field is used to store the virtual table instances associated
         4877  +        /// with this module.  The native pointer to the sqlite3_vtab derived
         4878  +        /// structure is used to key into this collection.
         4879  +        /// </summary>
  4707   4880           private Dictionary<IntPtr, SQLiteVirtualTable> tables;
  4708         -        private Dictionary<IntPtr, SQLiteVirtualTableCursor> cursors;
  4709         -        #endregion
  4710   4881   
  4711   4882           ///////////////////////////////////////////////////////////////////////
  4712   4883   
  4713         -        #region Internal Methods
  4714         -        internal UnsafeNativeMethods.sqlite3_module CreateNativeModule()
  4715         -        {
  4716         -            return CreateNativeModule(GetNativeModuleImpl());
  4717         -        }
         4884  +        /// <summary>
         4885  +        /// This field is used to store the virtual table cursor instances
         4886  +        /// associated with this module.  The native pointer to the
         4887  +        /// sqlite3_vtab_cursor derived structure is used to key into this
         4888  +        /// collection.
         4889  +        /// </summary>
         4890  +        private Dictionary<IntPtr, SQLiteVirtualTableCursor> cursors;
  4718   4891           #endregion
  4719   4892   
  4720   4893           ///////////////////////////////////////////////////////////////////////
  4721   4894   
  4722   4895           #region Public Constructors
         4896  +        /// <summary>
         4897  +        /// Constructs an instance of this class.
         4898  +        /// </summary>
         4899  +        /// <param name="name">
         4900  +        /// The name of the module.
         4901  +        /// </param>
  4723   4902           public SQLiteModule(string name)
  4724   4903           {
  4725   4904               if (name == null)
  4726   4905                   throw new ArgumentNullException("name");
  4727   4906   
  4728   4907               this.name = name;
  4729   4908               this.tables = new Dictionary<IntPtr, SQLiteVirtualTable>();
  4730   4909               this.cursors = new Dictionary<IntPtr, SQLiteVirtualTableCursor>();
  4731   4910           }
  4732   4911           #endregion
  4733   4912   
  4734   4913           ///////////////////////////////////////////////////////////////////////
  4735   4914   
         4915  +        #region Internal Methods
         4916  +        /// <summary>
         4917  +        /// Creates and returns the native sqlite_module structure using the
         4918  +        /// configured (or default) <see cref="ISQLiteNativeModule" />
         4919  +        /// interface implementation.
         4920  +        /// </summary>
         4921  +        /// <returns>
         4922  +        /// The native sqlite_module structure using the configured (or
         4923  +        /// default) <see cref="ISQLiteNativeModule" /> interface
         4924  +        /// implementation.
         4925  +        /// </returns>
         4926  +        internal UnsafeNativeMethods.sqlite3_module CreateNativeModule()
         4927  +        {
         4928  +            return CreateNativeModule(GetNativeModuleImpl());
         4929  +        }
         4930  +        #endregion
         4931  +
         4932  +        ///////////////////////////////////////////////////////////////////////
         4933  +
  4736   4934           #region Private Methods
         4935  +        /// <summary>
         4936  +        /// Creates and returns the native sqlite_module structure using the
         4937  +        /// specified <see cref="ISQLiteNativeModule" /> interface
         4938  +        /// implementation.
         4939  +        /// </summary>
         4940  +        /// <param name="module">
         4941  +        /// The <see cref="ISQLiteNativeModule" /> interface implementation to
         4942  +        /// use.
         4943  +        /// </param>
         4944  +        /// <returns>
         4945  +        /// The native sqlite_module structure using the specified
         4946  +        /// <see cref="ISQLiteNativeModule" /> interface implementation.
         4947  +        /// </returns>
  4737   4948           private UnsafeNativeMethods.sqlite3_module CreateNativeModule(
  4738   4949               ISQLiteNativeModule module
  4739   4950               )
  4740   4951           {
  4741   4952               nativeModule = new UnsafeNativeMethods.sqlite3_module();
  4742         -            nativeModule.iVersion = 2;
         4953  +            nativeModule.iVersion = DefaultModuleVersion;
  4743   4954   
  4744   4955               if (module != null)
  4745   4956               {
  4746   4957                   nativeModule.xCreate = new UnsafeNativeMethods.xCreate(
  4747   4958                       module.xCreate);
  4748   4959   
  4749   4960                   nativeModule.xConnect = new UnsafeNativeMethods.xConnect(
................................................................................
  4871   5082           }
  4872   5083           #endregion
  4873   5084   
  4874   5085           ///////////////////////////////////////////////////////////////////////
  4875   5086   
  4876   5087           #region Protected Members
  4877   5088           #region Module Helper Methods
         5089  +        /// <summary>
         5090  +        /// Gets and returns the <see cref="ISQLiteNativeModule" /> interface
         5091  +        /// implementation to be used when creating the native sqlite3_module
         5092  +        /// structure.  Derived classes may override this method to supply an
         5093  +        /// alternate implementation for the <see cref="ISQLiteNativeModule" />
         5094  +        /// interface.
         5095  +        /// </summary>
         5096  +        /// <returns>
         5097  +        /// The <see cref="ISQLiteNativeModule" /> interface implementation to
         5098  +        /// be used when populating the native sqlite3_module structure.  If
         5099  +        /// the returned value is null, the private methods provided by the
         5100  +        /// <see cref="SQLiteModule" /> class and relating to the
         5101  +        /// <see cref="ISQLiteNativeModule" /> interface  will be used to
         5102  +        /// create the necessary delegates.
         5103  +        /// </returns>
  4878   5104           protected virtual ISQLiteNativeModule GetNativeModuleImpl()
  4879   5105           {
  4880         -            return null; /* NOTE: Use built-in defaults. */
         5106  +            return null; /* NOTE: Use the built-in default delegates. */
  4881   5107           }
  4882   5108   
  4883   5109           ///////////////////////////////////////////////////////////////////////
  4884   5110   
         5111  +        /// <summary>
         5112  +        /// Creates and returns the <see cref="ISQLiteNativeModule" />
         5113  +        /// interface implementation corresponding to the current
         5114  +        /// <see cref="SQLiteModule" /> object instance.
         5115  +        /// </summary>
         5116  +        /// <returns>
         5117  +        /// The <see cref="ISQLiteNativeModule" /> interface implementation
         5118  +        /// corresponding to the current <see cref="SQLiteModule" /> object
         5119  +        /// instance.
         5120  +        /// </returns>
  4885   5121           protected virtual ISQLiteNativeModule CreateNativeModuleImpl()
  4886   5122           {
  4887   5123               return new SQLiteNativeModule(this);
  4888   5124           }
  4889   5125           #endregion
  4890   5126   
  4891   5127           ///////////////////////////////////////////////////////////////////////
  4892   5128   
  4893   5129           #region Native Table Helper Methods
         5130  +        /// <summary>
         5131  +        /// Allocates a native sqlite3_vtab derived structure and returns a
         5132  +        /// native pointer to it.
         5133  +        /// </summary>
         5134  +        /// <returns>
         5135  +        /// A native pointer to a native sqlite3_vtab derived structure.
         5136  +        /// </returns>
  4894   5137           protected virtual IntPtr AllocateTable()
  4895   5138           {
  4896   5139               int size = Marshal.SizeOf(typeof(
  4897   5140                   UnsafeNativeMethods.sqlite3_vtab));
  4898   5141   
  4899   5142               return SQLiteMemory.Allocate(size);
  4900   5143           }
  4901   5144   
  4902   5145           ///////////////////////////////////////////////////////////////////////
  4903   5146   
         5147  +        /// <summary>
         5148  +        /// Zeros out the fields of a native sqlite3_vtab derived structure.
         5149  +        /// </summary>
         5150  +        /// <param name="pVtab">
         5151  +        /// The native pointer to the native sqlite3_vtab derived structure to
         5152  +        /// zero.
         5153  +        /// </param>
  4904   5154           protected virtual void ZeroTable(
  4905   5155               IntPtr pVtab
  4906   5156               )
  4907   5157           {
  4908   5158               if (pVtab == IntPtr.Zero)
  4909   5159                   return;
  4910   5160   
................................................................................
  4919   5169               offset += sizeof(int);
  4920   5170   
  4921   5171               SQLiteMarshal.WriteIntPtr(pVtab, offset, IntPtr.Zero);
  4922   5172           }
  4923   5173   
  4924   5174           ///////////////////////////////////////////////////////////////////////
  4925   5175   
         5176  +        /// <summary>
         5177  +        /// Frees a native sqlite3_vtab structure using the provided native
         5178  +        /// pointer to it.
         5179  +        /// </summary>
         5180  +        /// <param name="pVtab">
         5181  +        /// A native pointer to a native sqlite3_vtab derived structure.
         5182  +        /// </param>
  4926   5183           protected virtual void FreeTable(
  4927   5184               IntPtr pVtab
  4928   5185               )
  4929   5186           {
  4930   5187               SetTableError(pVtab, null);
  4931   5188               SQLiteMemory.Free(pVtab);
  4932   5189           }
  4933   5190           #endregion
  4934   5191   
  4935   5192           ///////////////////////////////////////////////////////////////////////
  4936   5193   
  4937   5194           #region Native Cursor Helper Methods
         5195  +        /// <summary>
         5196  +        /// Allocates a native sqlite3_vtab_cursor derived structure and
         5197  +        /// returns a native pointer to it.
         5198  +        /// </summary>
         5199  +        /// <returns>
         5200  +        /// A native pointer to a native sqlite3_vtab_cursor derived structure.
         5201  +        /// </returns>
  4938   5202           protected virtual IntPtr AllocateCursor()
  4939   5203           {
  4940   5204               int size = Marshal.SizeOf(typeof(
  4941   5205                   UnsafeNativeMethods.sqlite3_vtab_cursor));
  4942   5206   
  4943   5207               return SQLiteMemory.Allocate(size);
  4944   5208           }
  4945   5209   
  4946   5210           ///////////////////////////////////////////////////////////////////////
  4947   5211   
         5212  +        /// <summary>
         5213  +        /// Frees a native sqlite3_vtab_cursor structure using the provided
         5214  +        /// native pointer to it.
         5215  +        /// </summary>
         5216  +        /// <param name="pCursor">
         5217  +        /// A native pointer to a native sqlite3_vtab_cursor derived structure.
         5218  +        /// </param>
  4948   5219           protected virtual void FreeCursor(
  4949   5220               IntPtr pCursor
  4950   5221               )
  4951   5222           {
  4952   5223               SQLiteMemory.Free(pCursor);
  4953   5224           }
  4954   5225           #endregion
  4955   5226   
  4956   5227           ///////////////////////////////////////////////////////////////////////
  4957   5228   
  4958   5229           #region Static Table Lookup Methods
         5230  +        /// <summary>
         5231  +        /// Reads and returns the native pointer to the sqlite3_vtab derived
         5232  +        /// structure based on the native pointer to the sqlite3_vtab_cursor
         5233  +        /// derived structure.
         5234  +        /// </summary>
         5235  +        /// <param name="module">
         5236  +        /// The <see cref="SQLiteModule" /> object instance to be used.
         5237  +        /// </param>
         5238  +        /// <param name="pCursor">
         5239  +        /// The native pointer to the sqlite3_vtab_cursor derived structure
         5240  +        /// from which to read the native pointer to the sqlite3_vtab derived
         5241  +        /// structure.
         5242  +        /// </param>
         5243  +        /// <returns>
         5244  +        /// The native pointer to the sqlite3_vtab derived structure -OR-
         5245  +        /// <see cref="IntPtr.Zero"/> if it cannot be determined.
         5246  +        /// </returns>
  4959   5247           private static IntPtr TableFromCursor(
  4960   5248               SQLiteModule module,
  4961   5249               IntPtr pCursor
  4962   5250               )
  4963   5251           {
  4964   5252               if (pCursor == IntPtr.Zero)
  4965   5253                   return IntPtr.Zero;
................................................................................
  4967   5255               return Marshal.ReadIntPtr(pCursor);
  4968   5256           }
  4969   5257           #endregion
  4970   5258   
  4971   5259           ///////////////////////////////////////////////////////////////////////
  4972   5260   
  4973   5261           #region Table Lookup Methods
         5262  +        /// <summary>
         5263  +        /// Reads and returns the native pointer to the sqlite3_vtab derived
         5264  +        /// structure based on the native pointer to the sqlite3_vtab_cursor
         5265  +        /// derived structure.
         5266  +        /// </summary>
         5267  +        /// <param name="pCursor">
         5268  +        /// The native pointer to the sqlite3_vtab_cursor derived structure
         5269  +        /// from which to read the native pointer to the sqlite3_vtab derived
         5270  +        /// structure.
         5271  +        /// </param>
         5272  +        /// <returns>
         5273  +        /// The native pointer to the sqlite3_vtab derived structure -OR-
         5274  +        /// <see cref="IntPtr.Zero"/> if it cannot be determined.
         5275  +        /// </returns>
  4974   5276           protected virtual IntPtr TableFromCursor(
  4975   5277               IntPtr pCursor
  4976   5278               )
  4977   5279           {
  4978   5280               return TableFromCursor(this, pCursor);
  4979   5281           }
  4980   5282   
  4981   5283           ///////////////////////////////////////////////////////////////////////
  4982   5284   
         5285  +        /// <summary>
         5286  +        /// Looks up and returns the <see cref="SQLiteVirtualTable" /> object
         5287  +        /// instance based on the native pointer to the sqlite3_vtab derived
         5288  +        /// structure.
         5289  +        /// </summary>
         5290  +        /// <param name="pVtab">
         5291  +        /// The native pointer to the sqlite3_vtab derived structure.
         5292  +        /// </param>
         5293  +        /// <returns>
         5294  +        /// The <see cref="SQLiteVirtualTable" /> object instance or null if
         5295  +        /// the corresponding one cannot be found.
         5296  +        /// </returns>
  4983   5297           protected virtual SQLiteVirtualTable TableFromIntPtr(
  4984   5298               IntPtr pVtab
  4985   5299               )
  4986   5300           {
  4987   5301               if (pVtab == IntPtr.Zero)
  4988   5302               {
  4989   5303                   SetTableError(pVtab, "invalid native table");
................................................................................
  5003   5317                   "managed table for {0} not found", pVtab));
  5004   5318   
  5005   5319               return null;
  5006   5320           }
  5007   5321   
  5008   5322           ///////////////////////////////////////////////////////////////////////
  5009   5323   
         5324  +        /// <summary>
         5325  +        /// Allocates and returns a native pointer to a sqlite3_vtab derived
         5326  +        /// structure and creates an association between it and the specified
         5327  +        /// <see cref="SQLiteVirtualTable" /> object instance.
         5328  +        /// </summary>
         5329  +        /// <param name="table">
         5330  +        /// The <see cref="SQLiteVirtualTable" /> object instance to be used
         5331  +        /// when creating the association.
         5332  +        /// </param>
         5333  +        /// <returns>
         5334  +        /// The native pointer to a sqlite3_vtab derived structure or
         5335  +        /// <see cref="IntPtr.Zero"/> if the method fails for any reason.
         5336  +        /// </returns>
  5010   5337           protected virtual IntPtr TableToIntPtr(
  5011   5338               SQLiteVirtualTable table
  5012   5339               )
  5013   5340           {
  5014   5341               if ((table == null) || (tables == null))
  5015   5342                   return IntPtr.Zero;
  5016   5343   
................................................................................
  5041   5368               return pVtab;
  5042   5369           }
  5043   5370           #endregion
  5044   5371   
  5045   5372           ///////////////////////////////////////////////////////////////////////
  5046   5373   
  5047   5374           #region Cursor Lookup Methods
         5375  +        /// <summary>
         5376  +        /// Looks up and returns the <see cref="SQLiteVirtualTableCursor" />
         5377  +        /// object instance based on the native pointer to the
         5378  +        /// sqlite3_vtab_cursor derived structure.
         5379  +        /// </summary>
         5380  +        /// <param name="pVtab">
         5381  +        /// The native pointer to the sqlite3_vtab derived structure.
         5382  +        /// </param>
         5383  +        /// <param name="pCursor">
         5384  +        /// The native pointer to the sqlite3_vtab_cursor derived structure.
         5385  +        /// </param>
         5386  +        /// <returns>
         5387  +        /// The <see cref="SQLiteVirtualTableCursor" /> object instance or null
         5388  +        /// if the corresponding one cannot be found.
         5389  +        /// </returns>
  5048   5390           protected virtual SQLiteVirtualTableCursor CursorFromIntPtr(
  5049   5391               IntPtr pVtab,
  5050   5392               IntPtr pCursor
  5051   5393               )
  5052   5394           {
  5053   5395               if (pCursor == IntPtr.Zero)
  5054   5396               {
................................................................................
  5069   5411                   "managed cursor for {0} not found", pCursor));
  5070   5412   
  5071   5413               return null;
  5072   5414           }
  5073   5415   
  5074   5416           ///////////////////////////////////////////////////////////////////////
  5075   5417   
         5418  +        /// <summary>
         5419  +        /// Allocates and returns a native pointer to a sqlite3_vtab_cursor
         5420  +        /// derived structure and creates an association between it and the
         5421  +        /// specified <see cref="SQLiteVirtualTableCursor" /> object instance.
         5422  +        /// </summary>
         5423  +        /// <param name="cursor">
         5424  +        /// The <see cref="SQLiteVirtualTableCursor" /> object instance to be
         5425  +        /// used when creating the association.
         5426  +        /// </param>
         5427  +        /// <returns>
         5428  +        /// The native pointer to a sqlite3_vtab_cursor derived structure or
         5429  +        /// <see cref="IntPtr.Zero"/> if the method fails for any reason.
         5430  +        /// </returns>
  5076   5431           protected virtual IntPtr CursorToIntPtr(
  5077   5432               SQLiteVirtualTableCursor cursor
  5078   5433               )
  5079   5434           {
  5080   5435               if ((cursor == null) || (cursors == null))
  5081   5436                   return IntPtr.Zero;
  5082   5437   
................................................................................
  5106   5461               return pCursor;
  5107   5462           }
  5108   5463           #endregion
  5109   5464   
  5110   5465           ///////////////////////////////////////////////////////////////////////
  5111   5466   
  5112   5467           #region Table Declaration Helper Methods
         5468  +        /// <summary>
         5469  +        /// Attempts to declare the schema for the virtual table using the
         5470  +        /// specified database connection.
         5471  +        /// </summary>
         5472  +        /// <param name="connection">
         5473  +        /// The <see cref="SQLiteConnection" /> object instance to use when
         5474  +        /// declaring the schema of the virtual table.
         5475  +        /// </param>
         5476  +        /// <param name="sql">
         5477  +        /// The string containing the CREATE TABLE statement that completely
         5478  +        /// describes the schema for the virtual table.
         5479  +        /// </param>
         5480  +        /// <param name="error">
         5481  +        /// Upon failure, this parameter must be modified to contain an error
         5482  +        /// message.
         5483  +        /// </param>
         5484  +        /// <returns>
         5485  +        /// A standard SQLite return code.
         5486  +        /// </returns>
  5113   5487           protected virtual SQLiteErrorCode DeclareTable(
  5114   5488               SQLiteConnection connection,
  5115   5489               string sql,
  5116   5490               ref string error
  5117   5491               )
  5118   5492           {
  5119   5493               if (connection == null)
................................................................................
  5133   5507               return sqliteBase.DeclareVirtualTable(this, sql, ref error);
  5134   5508           }
  5135   5509           #endregion
  5136   5510   
  5137   5511           ///////////////////////////////////////////////////////////////////////
  5138   5512   
  5139   5513           #region Error Handling Helper Methods
         5514  +        /// <summary>
         5515  +        /// Arranges for the specified error message to be placed into the
         5516  +        /// zErrMsg field of a sqlite3_vtab derived structure, freeing the
         5517  +        /// existing error message, if any.
         5518  +        /// </summary>
         5519  +        /// <param name="pVtab">
         5520  +        /// The native pointer to the sqlite3_vtab derived structure.
         5521  +        /// </param>
         5522  +        /// <param name="error">
         5523  +        /// The error message.
         5524  +        /// </param>
         5525  +        /// <returns>
         5526  +        /// Non-zero upon success.
         5527  +        /// </returns>
  5140   5528           protected virtual bool SetTableError(
  5141   5529               IntPtr pVtab,
  5142   5530               string error
  5143   5531               )
  5144   5532           {
  5145   5533               return SetTableError(this, pVtab, LogErrors, error);
  5146   5534           }
  5147   5535   
  5148   5536           ///////////////////////////////////////////////////////////////////////
  5149   5537   
         5538  +        /// <summary>
         5539  +        /// Arranges for the specified error message to be placed into the
         5540  +        /// zErrMsg field of a sqlite3_vtab derived structure, freeing the
         5541  +        /// existing error message, if any.
         5542  +        /// </summary>
         5543  +        /// <param name="table">
         5544  +        /// The <see cref="SQLiteVirtualTable" /> object instance used to
         5545  +        /// lookup the native pointer to the sqlite3_vtab derived structure.
         5546  +        /// </param>
         5547  +        /// <param name="error">
         5548  +        /// The error message.
         5549  +        /// </param>
         5550  +        /// <returns>
         5551  +        /// Non-zero upon success.
         5552  +        /// </returns>
  5150   5553           protected virtual bool SetTableError(
  5151   5554               SQLiteVirtualTable table,
  5152   5555               string error
  5153   5556               )
  5154   5557           {
  5155   5558               return SetTableError(this, table, LogErrors, error);
  5156   5559           }
  5157   5560   
  5158   5561           ///////////////////////////////////////////////////////////////////////
  5159   5562   
         5563  +        /// <summary>
         5564  +        /// Arranges for the specified error message to be placed into the
         5565  +        /// zErrMsg field of a sqlite3_vtab derived structure, freeing the
         5566  +        /// existing error message, if any.
         5567  +        /// </summary>
         5568  +        /// <param name="cursor">
         5569  +        /// The <see cref="SQLiteVirtualTableCursor" /> object instance used to
         5570  +        /// lookup the native pointer to the sqlite3_vtab derived structure.
         5571  +        /// </param>
         5572  +        /// <param name="error">
         5573  +        /// The error message.
         5574  +        /// </param>
         5575  +        /// <returns>
         5576  +        /// Non-zero upon success.
         5577  +        /// </returns>
  5160   5578           protected virtual bool SetCursorError(
  5161   5579               SQLiteVirtualTableCursor cursor,
  5162   5580               string error
  5163   5581               )
  5164   5582           {
  5165   5583               return SetCursorError(this, cursor, LogErrors, error);
  5166   5584           }
  5167   5585           #endregion
  5168   5586   
  5169   5587           ///////////////////////////////////////////////////////////////////////
  5170   5588   
  5171   5589           #region Static Error Handling Helper Methods
         5590  +        /// <summary>
         5591  +        /// Arranges for the specified error message to be placed into the
         5592  +        /// zErrMsg field of a sqlite3_vtab derived structure, freeing the
         5593  +        /// existing error message, if any.
         5594  +        /// </summary>
         5595  +        /// <param name="module">
         5596  +        /// The <see cref="SQLiteModule" /> object instance to be used.
         5597  +        /// </param>
         5598  +        /// <param name="pVtab">
         5599  +        /// The native pointer to the sqlite3_vtab derived structure.
         5600  +        /// </param>
         5601  +        /// <param name="logErrors">
         5602  +        /// Non-zero if this error message should also be logged using the
         5603  +        /// <see cref="SQLiteLog" /> class.
         5604  +        /// </param>
         5605  +        /// <param name="error">
         5606  +        /// The error message.
         5607  +        /// </param>
         5608  +        /// <returns>
         5609  +        /// Non-zero upon success.
         5610  +        /// </returns>
  5172   5611           private static bool SetTableError(
  5173   5612               SQLiteModule module,
  5174   5613               IntPtr pVtab,
  5175   5614               bool logErrors,
  5176   5615               string error
  5177   5616               )
  5178   5617           {
................................................................................
  5223   5662               }
  5224   5663   
  5225   5664               return success;
  5226   5665           }
  5227   5666   
  5228   5667           ///////////////////////////////////////////////////////////////////////
  5229   5668   
         5669  +        /// <summary>
         5670  +        /// Arranges for the specified error message to be placed into the
         5671  +        /// zErrMsg field of a sqlite3_vtab derived structure, freeing the
         5672  +        /// existing error message, if any.
         5673  +        /// </summary>
         5674  +        /// <param name="module">
         5675  +        /// The <see cref="SQLiteModule" /> object instance to be used.
         5676  +        /// </param>
         5677  +        /// <param name="table">
         5678  +        /// The <see cref="SQLiteVirtualTable" /> object instance used to
         5679  +        /// lookup the native pointer to the sqlite3_vtab derived structure.
         5680  +        /// </param>
         5681  +        /// <param name="logErrors">
         5682  +        /// Non-zero if this error message should also be logged using the
         5683  +        /// <see cref="SQLiteLog" /> class.
         5684  +        /// </param>
         5685  +        /// <param name="error">
         5686  +        /// The error message.
         5687  +        /// </param>
         5688  +        /// <returns>
         5689  +        /// Non-zero upon success.
         5690  +        /// </returns>
  5230   5691           private static bool SetTableError(
  5231   5692               SQLiteModule module,
  5232   5693               SQLiteVirtualTable table,
  5233   5694               bool logErrors,
  5234   5695               string error
  5235   5696               )
  5236   5697           {
................................................................................
  5243   5704                   return false;
  5244   5705   
  5245   5706               return SetTableError(module, pVtab, logErrors, error);
  5246   5707           }
  5247   5708   
  5248   5709           ///////////////////////////////////////////////////////////////////////
  5249   5710   
         5711  +        /// <summary>
         5712  +        /// Arranges for the specified error message to be placed into the
         5713  +        /// zErrMsg field of a sqlite3_vtab derived structure, freeing the
         5714  +        /// existing error message, if any.
         5715  +        /// </summary>
         5716  +        /// <param name="module">
         5717  +        /// The <see cref="SQLiteModule" /> object instance to be used.
         5718  +        /// </param>
         5719  +        /// <param name="pCursor">
         5720  +        /// The native pointer to the sqlite3_vtab_cursor derived structure
         5721  +        /// used to get the native pointer to the sqlite3_vtab derived
         5722  +        /// structure.
         5723  +        /// </param>
         5724  +        /// <param name="logErrors">
         5725  +        /// Non-zero if this error message should also be logged using the
         5726  +        /// <see cref="SQLiteLog" /> class.
         5727  +        /// </param>
         5728  +        /// <param name="error">
         5729  +        /// The error message.
         5730  +        /// </param>
         5731  +        /// <returns>
         5732  +        /// Non-zero upon success.
         5733  +        /// </returns>
  5250   5734           private static bool SetCursorError(
  5251   5735               SQLiteModule module,
  5252   5736               IntPtr pCursor,
  5253   5737               bool logErrors,
  5254   5738               string error
  5255   5739               )
  5256   5740           {
................................................................................
  5263   5747                   return false;
  5264   5748   
  5265   5749               return SetTableError(module, pVtab, logErrors, error);
  5266   5750           }
  5267   5751   
  5268   5752           ///////////////////////////////////////////////////////////////////////
  5269   5753   
         5754  +        /// <summary>
         5755  +        /// Arranges for the specified error message to be placed into the
         5756  +        /// zErrMsg field of a sqlite3_vtab derived structure, freeing the
         5757  +        /// existing error message, if any.
         5758  +        /// </summary>
         5759  +        /// <param name="module">
         5760  +        /// The <see cref="SQLiteModule" /> object instance to be used.
         5761  +        /// </param>
         5762  +        /// <param name="cursor">
         5763  +        /// The <see cref="SQLiteVirtualTableCursor" /> object instance used to
         5764  +        /// lookup the native pointer to the sqlite3_vtab derived structure.
         5765  +        /// </param>
         5766  +        /// <param name="logErrors">
         5767  +        /// Non-zero if this error message should also be logged using the
         5768  +        /// <see cref="SQLiteLog" /> class.
         5769  +        /// </param>
         5770  +        /// <param name="error">
         5771  +        /// The error message.
         5772  +        /// </param>
         5773  +        /// <returns>
         5774  +        /// Non-zero upon success.
         5775  +        /// </returns>
  5270   5776           private static bool SetCursorError(
  5271   5777               SQLiteModule module,
  5272   5778               SQLiteVirtualTableCursor cursor,
  5273   5779               bool logErrors,
  5274   5780               string error
  5275   5781               )
  5276   5782           {
................................................................................
  5285   5791               return SetCursorError(module, pCursor, logErrors, error);
  5286   5792           }
  5287   5793           #endregion
  5288   5794   
  5289   5795           ///////////////////////////////////////////////////////////////////////
  5290   5796   
  5291   5797           #region Index Handling Helper Methods
         5798  +        /// <summary>
         5799  +        /// Modifies the specified <see cref="SQLiteIndex" /> object instance
         5800  +        /// to contain the specified estimated cost.
         5801  +        /// </summary>
         5802  +        /// <param name="index">
         5803  +        /// The <see cref="SQLiteIndex" /> object instance to modify.
         5804  +        /// </param>
         5805  +        /// <param name="estimatedCost">
         5806  +        /// The estimated cost value to use.
         5807  +        /// </param>
         5808  +        /// <returns>
         5809  +        /// Non-zero upon success.
         5810  +        /// </returns>
  5292   5811           protected virtual bool SetEstimatedCost(
  5293   5812               SQLiteIndex index,
  5294   5813               double estimatedCost
  5295   5814               )
  5296   5815           {
  5297   5816               if ((index == null) || (index.Outputs == null))
  5298   5817                   return false;
................................................................................
  5299   5818   
  5300   5819               index.Outputs.EstimatedCost = estimatedCost;
  5301   5820               return true;
  5302   5821           }
  5303   5822   
  5304   5823           ///////////////////////////////////////////////////////////////////////
  5305   5824   
         5825  +        /// <summary>
         5826  +        /// Modifies the specified <see cref="SQLiteIndex" /> object instance
         5827  +        /// to contain the default estimated cost.
         5828  +        /// </summary>
         5829  +        /// <param name="index">
         5830  +        /// The <see cref="SQLiteIndex" /> object instance to modify.
         5831  +        /// </param>
         5832  +        /// <returns>
         5833  +        /// Non-zero upon success.
         5834  +        /// </returns>
  5306   5835           protected virtual bool SetEstimatedCost(
  5307   5836               SQLiteIndex index
  5308   5837               )
  5309   5838           {
  5310         -            return SetEstimatedCost(index, DefaultCost);
         5839  +            return SetEstimatedCost(index, DefaultEstimatedCost);
  5311   5840           }
  5312   5841           #endregion
  5313   5842           #endregion
  5314   5843   
  5315   5844           ///////////////////////////////////////////////////////////////////////
  5316   5845   
  5317   5846           #region Public Properties
  5318   5847           private bool logErrors;
         5848  +        /// <summary>
         5849  +        /// Returns or sets a boolean value indicating whether virtual table
         5850  +        /// errors should be logged using the <see cref="SQLiteLog" /> class.
         5851  +        /// </summary>
  5319   5852           public virtual bool LogErrors
  5320   5853           {
  5321   5854               get { CheckDisposed(); return logErrors; }
  5322   5855               set { CheckDisposed(); logErrors = value; }
  5323   5856           }
  5324   5857   
  5325   5858           ///////////////////////////////////////////////////////////////////////
  5326   5859   
  5327   5860           private bool logExceptions;
         5861  +        /// <summary>
         5862  +        /// Returns or sets a boolean value indicating whether exceptions
         5863  +        /// caught in the
         5864  +        /// <see cref="ISQLiteNativeModule.xDisconnect" /> method,
         5865  +        /// <see cref="ISQLiteNativeModule.xDestroy" /> method, and the
         5866  +        /// <see cref="Dispose()" /> method should be logged using the
         5867  +        /// <see cref="SQLiteLog" /> class.
         5868  +        /// </summary>
  5328   5869           public virtual bool LogExceptions
  5329   5870           {
  5330   5871               get { CheckDisposed(); return logExceptions; }
  5331   5872               set { CheckDisposed(); logExceptions = value; }
  5332   5873           }
  5333   5874           #endregion
  5334   5875   
  5335   5876           ///////////////////////////////////////////////////////////////////////
  5336   5877   
  5337   5878           #region ISQLiteNativeModule Members
         5879  +        /// <summary>
         5880  +        /// See the <see cref="ISQLiteNativeModule.xCreate" /> method.
         5881  +        /// </summary>
         5882  +        /// <param name="pDb">
         5883  +        /// See the <see cref="ISQLiteNativeModule.xCreate" /> method.
         5884  +        /// </param>
         5885  +        /// <param name="pAux">
         5886  +        /// See the <see cref="ISQLiteNativeModule.xCreate" /> method.
         5887  +        /// </param>
         5888  +        /// <param name="argc">
         5889  +        /// See the <see cref="ISQLiteNativeModule.xCreate" /> method.
         5890  +        /// </param>
         5891  +        /// <param name="argv">
         5892  +        /// See the <see cref="ISQLiteNativeModule.xCreate" /> method.
         5893  +        /// </param>
         5894  +        /// <param name="pVtab">
         5895  +        /// See the <see cref="ISQLiteNativeModule.xCreate" /> method.
         5896  +        /// </param>
         5897  +        /// <param name="pError">
         5898  +        /// See the <see cref="ISQLiteNativeModule.xCreate" /> method.
         5899  +        /// </param>
         5900  +        /// <returns>
         5901  +        /// See the <see cref="ISQLiteNativeModule.xCreate" /> method.
         5902  +        /// </returns>
  5338   5903           private SQLiteErrorCode xCreate(
  5339   5904               IntPtr pDb,
  5340   5905               IntPtr pAux,
  5341   5906               int argc,
  5342   5907               IntPtr[] argv,
  5343   5908               ref IntPtr pVtab,
  5344   5909               ref IntPtr pError
................................................................................
  5382   5947               }
  5383   5948   
  5384   5949               return SQLiteErrorCode.Error;
  5385   5950           }
  5386   5951   
  5387   5952           ///////////////////////////////////////////////////////////////////////
  5388   5953   
         5954  +        /// <summary>
         5955  +        /// See the <see cref="ISQLiteNativeModule.xConnect" /> method.
         5956  +        /// </summary>
         5957  +        /// <param name="pDb">
         5958  +        /// See the <see cref="ISQLiteNativeModule.xConnect" /> method.
         5959  +        /// </param>
         5960  +        /// <param name="pAux">
         5961  +        /// See the <see cref="ISQLiteNativeModule.xConnect" /> method.
         5962  +        /// </param>
         5963  +        /// <param name="argc">
         5964  +        /// See the <see cref="ISQLiteNativeModule.xConnect" /> method.
         5965  +        /// </param>
         5966  +        /// <param name="argv">
         5967  +        /// See the <see cref="ISQLiteNativeModule.xConnect" /> method.
         5968  +        /// </param>
         5969  +        /// <param name="pVtab">
         5970  +        /// See the <see cref="ISQLiteNativeModule.xConnect" /> method.
         5971  +        /// </param>
         5972  +        /// <param name="pError">
         5973  +        /// See the <see cref="ISQLiteNativeModule.xConnect" /> method.
         5974  +        /// </param>
         5975  +        /// <returns>
         5976  +        /// See the <see cref="ISQLiteNativeModule.xConnect" /> method.
         5977  +        /// </returns>
  5389   5978           private SQLiteErrorCode xConnect(
  5390   5979               IntPtr pDb,
  5391   5980               IntPtr pAux,
  5392   5981               int argc,
  5393   5982               IntPtr[] argv,
  5394   5983               ref IntPtr pVtab,
  5395   5984               ref IntPtr pError
................................................................................
  5433   6022               }
  5434   6023   
  5435   6024               return SQLiteErrorCode.Error;
  5436   6025           }
  5437   6026   
  5438   6027           ///////////////////////////////////////////////////////////////////////
  5439   6028   
         6029  +        /// <summary>
         6030  +        /// See the <see cref="ISQLiteNativeModule.xBestIndex" /> method.
         6031  +        /// </summary>
         6032  +        /// <param name="pVtab">
         6033  +        /// See the <see cref="ISQLiteNativeModule.xBestIndex" /> method.
         6034  +        /// </param>
         6035  +        /// <param name="pIndex">
         6036  +        /// See the <see cref="ISQLiteNativeModule.xBestIndex" /> method.
         6037  +        /// </param>
         6038  +        /// <returns>
         6039  +        /// See the <see cref="ISQLiteNativeModule.xBestIndex" /> method.
         6040  +        /// </returns>
  5440   6041           private SQLiteErrorCode xBestIndex(
  5441   6042               IntPtr pVtab,
  5442   6043               IntPtr pIndex
  5443   6044               )
  5444   6045           {
  5445   6046               try
  5446   6047               {
................................................................................
  5465   6066               }
  5466   6067   
  5467   6068               return SQLiteErrorCode.Error;
  5468   6069           }
  5469   6070   
  5470   6071           ///////////////////////////////////////////////////////////////////////
  5471   6072   
         6073  +        /// <summary>
         6074  +        /// See the <see cref="ISQLiteNativeModule.xDisconnect" /> method.
         6075  +        /// </summary>
         6076  +        /// <param name="pVtab">
         6077  +        /// See the <see cref="ISQLiteNativeModule.xDisconnect" /> method.
         6078  +        /// </param>
         6079  +        /// <returns>
         6080  +        /// See the <see cref="ISQLiteNativeModule.xDisconnect" /> method.
         6081  +        /// </returns>
  5472   6082           private SQLiteErrorCode xDisconnect(
  5473   6083               IntPtr pVtab
  5474   6084               )
  5475   6085           {
  5476   6086               try
  5477   6087               {
  5478   6088                   SQLiteVirtualTable table = TableFromIntPtr(pVtab);
................................................................................
  5516   6126               }
  5517   6127   
  5518   6128               return SQLiteErrorCode.Error;
  5519   6129           }
  5520   6130   
  5521   6131           ///////////////////////////////////////////////////////////////////////
  5522   6132   
         6133  +        /// <summary>
         6134  +        /// See the <see cref="ISQLiteNativeModule.xDestroy" /> method.
         6135  +        /// </summary>
         6136  +        /// <param name="pVtab">
         6137  +        /// See the <see cref="ISQLiteNativeModule.xDestroy" /> method.
         6138  +        /// </param>
         6139  +        /// <returns>
         6140  +        /// See the <see cref="ISQLiteNativeModule.xDestroy" /> method.
         6141  +        /// </returns>
  5523   6142           private SQLiteErrorCode xDestroy(
  5524   6143               IntPtr pVtab
  5525   6144               )
  5526   6145           {
  5527   6146               try
  5528   6147               {
  5529   6148                   SQLiteVirtualTable table = TableFromIntPtr(pVtab);
................................................................................
  5567   6186               }
  5568   6187   
  5569   6188               return SQLiteErrorCode.Error;
  5570   6189           }
  5571   6190   
  5572   6191           ///////////////////////////////////////////////////////////////////////
  5573   6192   
         6193  +        /// <summary>
         6194  +        /// See the <see cref="ISQLiteNativeModule.xOpen" /> method.
         6195  +        /// </summary>
         6196  +        /// <param name="pVtab">
         6197  +        /// See the <see cref="ISQLiteNativeModule.xOpen" /> method.
         6198  +        /// </param>
         6199  +        /// <param name="pCursor">
         6200  +        /// See the <see cref="ISQLiteNativeModule.xOpen" /> method.
         6201  +        /// </param>
         6202  +        /// <returns>
         6203  +        /// See the <see cref="ISQLiteNativeModule.xOpen" /> method.
         6204  +        /// </returns>
  5574   6205           private SQLiteErrorCode xOpen(
  5575   6206               IntPtr pVtab,
  5576   6207               ref IntPtr pCursor
  5577   6208               )
  5578   6209           {
  5579   6210               try
  5580   6211               {
................................................................................
  5614   6245               }
  5615   6246   
  5616   6247               return SQLiteErrorCode.Error;
  5617   6248           }
  5618   6249   
  5619   6250           ///////////////////////////////////////////////////////////////////////
  5620   6251   
         6252  +        /// <summary>
         6253  +        /// See the <see cref="ISQLiteNativeModule.xClose" /> method.
         6254  +        /// </summary>
         6255  +        /// <param name="pCursor">
         6256  +        /// See the <see cref="ISQLiteNativeModule.xClose" /> method.
         6257  +        /// </param>
         6258  +        /// <returns>
         6259  +        /// See the <see cref="ISQLiteNativeModule.xClose" /> method.
         6260  +        /// </returns>
  5621   6261           private SQLiteErrorCode xClose(
  5622   6262               IntPtr pCursor
  5623   6263               )
  5624   6264           {
  5625   6265               IntPtr pVtab = IntPtr.Zero;
  5626   6266   
  5627   6267               try
................................................................................
  5652   6292               }
  5653   6293   
  5654   6294               return SQLiteErrorCode.Error;
  5655   6295           }
  5656   6296   
  5657   6297           ///////////////////////////////////////////////////////////////////////
  5658   6298   
         6299  +        /// <summary>
         6300  +        /// See the <see cref="ISQLiteNativeModule.xFilter" /> method.
         6301  +        /// </summary>
         6302  +        /// <param name="pCursor">
         6303  +        /// See the <see cref="ISQLiteNativeModule.xFilter" /> method.
         6304  +        /// </param>
         6305  +        /// <param name="idxNum">
         6306  +        /// See the <see cref="ISQLiteNativeModule.xFilter" /> method.
         6307  +        /// </param>
         6308  +        /// <param name="idxStr">
         6309  +        /// See the <see cref="ISQLiteNativeModule.xFilter" /> method.
         6310  +        /// </param>
         6311  +        /// <param name="argc">
         6312  +        /// See the <see cref="ISQLiteNativeModule.xFilter" /> method.
         6313  +        /// </param>
         6314  +        /// <param name="argv">
         6315  +        /// See the <see cref="ISQLiteNativeModule.xFilter" /> method.
         6316  +        /// </param>
         6317  +        /// <returns>
         6318  +        /// See the <see cref="ISQLiteNativeModule.xFilter" /> method.
         6319  +        /// </returns>
  5659   6320           private SQLiteErrorCode xFilter(
  5660   6321               IntPtr pCursor,
  5661   6322               int idxNum,
  5662   6323               IntPtr idxStr,
  5663   6324               int argc,
  5664   6325               IntPtr[] argv
  5665   6326               )
................................................................................
  5690   6351               }
  5691   6352   
  5692   6353               return SQLiteErrorCode.Error;
  5693   6354           }
  5694   6355   
  5695   6356           ///////////////////////////////////////////////////////////////////////
  5696   6357   
         6358  +        /// <summary>
         6359  +        /// See the <see cref="ISQLiteNativeModule.xNext" /> method.
         6360  +        /// </summary>
         6361  +        /// <param name="pCursor">
         6362  +        /// See the <see cref="ISQLiteNativeModule.xNext" /> method.
         6363  +        /// </param>
         6364  +        /// <returns>
         6365  +        /// See the <see cref="ISQLiteNativeModule.xNext" /> method.
         6366  +        /// </returns>
  5697   6367           private SQLiteErrorCode xNext(
  5698   6368               IntPtr pCursor
  5699   6369               )
  5700   6370           {
  5701   6371               IntPtr pVtab = IntPtr.Zero;
  5702   6372   
  5703   6373               try
................................................................................
  5719   6389               }
  5720   6390   
  5721   6391               return SQLiteErrorCode.Error;
  5722   6392           }
  5723   6393   
  5724   6394           ///////////////////////////////////////////////////////////////////////
  5725   6395   
         6396  +        /// <summary>
         6397  +        /// See the <see cref="ISQLiteNativeModule.xEof" /> method.
         6398  +        /// </summary>
         6399  +        /// <param name="pCursor">
         6400  +        /// See the <see cref="ISQLiteNativeModule.xEof" /> method.
         6401  +        /// </param>
         6402  +        /// <returns>
         6403  +        /// See the <see cref="ISQLiteNativeModule.xEof" /> method.
         6404  +        /// </returns>
  5726   6405           private int xEof(
  5727   6406               IntPtr pCursor
  5728   6407               )
  5729   6408           {
  5730   6409               IntPtr pVtab = IntPtr.Zero;
  5731   6410   
  5732   6411               try
................................................................................
  5745   6424               }
  5746   6425   
  5747   6426               return 1;
  5748   6427           }
  5749   6428   
  5750   6429           ///////////////////////////////////////////////////////////////////////
  5751   6430   
         6431  +        /// <summary>
         6432  +        /// See the <see cref="ISQLiteNativeModule.xColumn" /> method.
         6433  +        /// </summary>
         6434  +        /// <param name="pCursor">
         6435  +        /// See the <see cref="ISQLiteNativeModule.xColumn" /> method.
         6436  +        /// </param>
         6437  +        /// <param name="pContext">
         6438  +        /// See the <see cref="ISQLiteNativeModule.xColumn" /> method.
         6439  +        /// </param>
         6440  +        /// <param name="index">
         6441  +        /// See the <see cref="ISQLiteNativeModule.xColumn" /> method.
         6442  +        /// </param>
         6443  +        /// <returns>
         6444  +        /// See the <see cref="ISQLiteNativeModule.xColumn" /> method.
         6445  +        /// </returns>
  5752   6446           private SQLiteErrorCode xColumn(
  5753   6447               IntPtr pCursor,
  5754   6448               IntPtr pContext,
  5755   6449               int index
  5756   6450               )
  5757   6451           {
  5758   6452               IntPtr pVtab = IntPtr.Zero;
................................................................................
  5777   6471               }
  5778   6472   
  5779   6473               return SQLiteErrorCode.Error;
  5780   6474           }
  5781   6475   
  5782   6476           ///////////////////////////////////////////////////////////////////////
  5783   6477   
         6478  +        /// <summary>
         6479  +        /// See the <see cref="ISQLiteNativeModule.xRowId" /> method.
         6480  +        /// </summary>
         6481  +        /// <param name="pCursor">
         6482  +        /// See the <see cref="ISQLiteNativeModule.xRowId" /> method.
         6483  +        /// </param>
         6484  +        /// <param name="rowId">
         6485  +        /// See the <see cref="ISQLiteNativeModule.xRowId" /> method.
         6486  +        /// </param>
         6487  +        /// <returns>
         6488  +        /// See the <see cref="ISQLiteNativeModule.xRowId" /> method.
         6489  +        /// </returns>
  5784   6490           private SQLiteErrorCode xRowId(
  5785   6491               IntPtr pCursor,
  5786   6492               ref long rowId
  5787   6493               )
  5788   6494           {
  5789   6495               IntPtr pVtab = IntPtr.Zero;
  5790   6496   
................................................................................
  5804   6510               }
  5805   6511   
  5806   6512               return SQLiteErrorCode.Error;
  5807   6513           }
  5808   6514   
  5809   6515           ///////////////////////////////////////////////////////////////////////
  5810   6516   
         6517  +        /// <summary>
         6518  +        /// See the <see cref="ISQLiteNativeModule.xUpdate" /> method.
         6519  +        /// </summary>
         6520  +        /// <param name="pVtab">
         6521  +        /// See the <see cref="ISQLiteNativeModule.xUpdate" /> method.
         6522  +        /// </param>
         6523  +        /// <param name="argc">
         6524  +        /// See the <see cref="ISQLiteNativeModule.xUpdate" /> method.
         6525  +        /// </param>
         6526  +        /// <param name="argv">
         6527  +        /// See the <see cref="ISQLiteNativeModule.xUpdate" /> method.
         6528  +        /// </param>
         6529  +        /// <param name="rowId">
         6530  +        /// See the <see cref="ISQLiteNativeModule.xUpdate" /> method.
         6531  +        /// </param>
         6532  +        /// <returns>
         6533  +        /// See the <see cref="ISQLiteNativeModule.xUpdate" /> method.
         6534  +        /// </returns>
  5811   6535           private SQLiteErrorCode xUpdate(
  5812   6536               IntPtr pVtab,
  5813   6537               int argc,
  5814   6538               IntPtr[] argv,
  5815   6539               ref long rowId
  5816   6540               )
  5817   6541           {
................................................................................
  5832   6556               }
  5833   6557   
  5834   6558               return SQLiteErrorCode.Error;
  5835   6559           }
  5836   6560   
  5837   6561           ///////////////////////////////////////////////////////////////////////
  5838   6562   
         6563  +        /// <summary>
         6564  +        /// See the <see cref="ISQLiteNativeModule.xBegin" /> method.
         6565  +        /// </summary>
         6566  +        /// <param name="pVtab">
         6567  +        /// See the <see cref="ISQLiteNativeModule.xBegin" /> method.
         6568  +        /// </param>
         6569  +        /// <returns>
         6570  +        /// See the <see cref="ISQLiteNativeModule.xBegin" /> method.
         6571  +        /// </returns>
  5839   6572           private SQLiteErrorCode xBegin(
  5840   6573               IntPtr pVtab
  5841   6574               )
  5842   6575           {
  5843   6576               try
  5844   6577               {
  5845   6578                   SQLiteVirtualTable table = TableFromIntPtr(pVtab);
................................................................................
  5853   6586               }
  5854   6587   
  5855   6588               return SQLiteErrorCode.Error;
  5856   6589           }
  5857   6590   
  5858   6591           ///////////////////////////////////////////////////////////////////////
  5859   6592   
         6593  +        /// <summary>
         6594  +        /// See the <see cref="ISQLiteNativeModule.xSync" /> method.
         6595  +        /// </summary>
         6596  +        /// <param name="pVtab">
         6597  +        /// See the <see cref="ISQLiteNativeModule.xSync" /> method.
         6598  +        /// </param>
         6599  +        /// <returns>
         6600  +        /// See the <see cref="ISQLiteNativeModule.xSync" /> method.
         6601  +        /// </returns>
  5860   6602           private SQLiteErrorCode xSync(
  5861   6603               IntPtr pVtab
  5862   6604               )
  5863   6605           {
  5864   6606               try
  5865   6607               {
  5866   6608                   SQLiteVirtualTable table = TableFromIntPtr(pVtab);
................................................................................
  5874   6616               }
  5875   6617   
  5876   6618               return SQLiteErrorCode.Error;
  5877   6619           }
  5878   6620   
  5879   6621           ///////////////////////////////////////////////////////////////////////
  5880   6622   
         6623  +        /// <summary>
         6624  +        /// See the <see cref="ISQLiteNativeModule.xCommit" /> method.
         6625  +        /// </summary>
         6626  +        /// <param name="pVtab">
         6627  +        /// See the <see cref="ISQLiteNativeModule.xCommit" /> method.
         6628  +        /// </param>
         6629  +        /// <returns>
         6630  +        /// See the <see cref="ISQLiteNativeModule.xCommit" /> method.
         6631  +        /// </returns>
  5881   6632           private SQLiteErrorCode xCommit(
  5882   6633               IntPtr pVtab
  5883   6634               )
  5884   6635           {
  5885   6636               try
  5886   6637               {
  5887   6638                   SQLiteVirtualTable table = TableFromIntPtr(pVtab);
................................................................................
  5895   6646               }
  5896   6647   
  5897   6648               return SQLiteErrorCode.Error;
  5898   6649           }
  5899   6650   
  5900   6651           ///////////////////////////////////////////////////////////////////////
  5901   6652   
         6653  +        /// <summary>
         6654  +        /// See the <see cref="ISQLiteNativeModule.xRollback" /> method.
         6655  +        /// </summary>
         6656  +        /// <param name="pVtab">
         6657  +        /// See the <see cref="ISQLiteNativeModule.xRollback" /> method.
         6658  +        /// </param>
         6659  +        /// <returns>
         6660  +        /// See the <see cref="ISQLiteNativeModule.xRollback" /> method.
         6661  +        /// </returns>
  5902   6662           private SQLiteErrorCode xRollback(
  5903   6663               IntPtr pVtab
  5904   6664               )
  5905   6665           {
  5906   6666               try
  5907   6667               {
  5908   6668                   SQLiteVirtualTable table = TableFromIntPtr(pVtab);
................................................................................
  5916   6676               }
  5917   6677   
  5918   6678               return SQLiteErrorCode.Error;
  5919   6679           }
  5920   6680   
  5921   6681           ///////////////////////////////////////////////////////////////////////
  5922   6682   
         6683  +        /// <summary>
         6684  +        /// See the <see cref="ISQLiteNativeModule.xFindFunction" /> method.
         6685  +        /// </summary>
         6686  +        /// <param name="pVtab">
         6687  +        /// See the <see cref="ISQLiteNativeModule.xFindFunction" /> method.
         6688  +        /// </param>
         6689  +        /// <param name="nArg">
         6690  +        /// See the <see cref="ISQLiteNativeModule.xFindFunction" /> method.
         6691  +        /// </param>
         6692  +        /// <param name="zName">
         6693  +        /// See the <see cref="ISQLiteNativeModule.xFindFunction" /> method.
         6694  +        /// </param>
         6695  +        /// <param name="callback">
         6696  +        /// See the <see cref="ISQLiteNativeModule.xFindFunction" /> method.
         6697  +        /// </param>
         6698  +        /// <param name="pClientData">
         6699  +        /// See the <see cref="ISQLiteNativeModule.xFindFunction" /> method.
         6700  +        /// </param>
         6701  +        /// <returns>
         6702  +        /// See the <see cref="ISQLiteNativeModule.xFindFunction" /> method.
         6703  +        /// </returns>
  5923   6704           private int xFindFunction(
  5924   6705               IntPtr pVtab,
  5925   6706               int nArg,
  5926   6707               IntPtr zName,
  5927   6708               ref SQLiteCallback callback,
  5928   6709               ref IntPtr pClientData
  5929   6710               )
................................................................................
  5959   6740               }
  5960   6741   
  5961   6742               return 0;
  5962   6743           }
  5963   6744   
  5964   6745           ///////////////////////////////////////////////////////////////////////
  5965   6746   
         6747  +        /// <summary>
         6748  +        /// See the <see cref="ISQLiteNativeModule.xRename" /> method.
         6749  +        /// </summary>
         6750  +        /// <param name="pVtab">
         6751  +        /// See the <see cref="ISQLiteNativeModule.xRename" /> method.
         6752  +        /// </param>
         6753  +        /// <param name="zNew">
         6754  +        /// See the <see cref="ISQLiteNativeModule.xRename" /> method.
         6755  +        /// </param>
         6756  +        /// <returns>
         6757  +        /// See the <see cref="ISQLiteNativeModule.xRename" /> method.
         6758  +        /// </returns>
  5966   6759           private SQLiteErrorCode xRename(
  5967   6760               IntPtr pVtab,
  5968   6761               IntPtr zNew
  5969   6762               )
  5970   6763           {
  5971   6764               try
  5972   6765               {
................................................................................
  5984   6777               }
  5985   6778   
  5986   6779               return SQLiteErrorCode.Error;
  5987   6780           }
  5988   6781   
  5989   6782           ///////////////////////////////////////////////////////////////////////
  5990   6783   
         6784  +        /// <summary>
         6785  +        /// See the <see cref="ISQLiteNativeModule.xSavepoint" /> method.
         6786  +        /// </summary>
         6787  +        /// <param name="pVtab">
         6788  +        /// See the <see cref="ISQLiteNativeModule.xSavepoint" /> method.
         6789  +        /// </param>
         6790  +        /// <param name="iSavepoint">
         6791  +        /// See the <see cref="ISQLiteNativeModule.xSavepoint" /> method.
         6792  +        /// </param>
         6793  +        /// <returns>
         6794  +        /// See the <see cref="ISQLiteNativeModule.xSavepoint" /> method.
         6795  +        /// </returns>
  5991   6796           private SQLiteErrorCode xSavepoint(
  5992   6797               IntPtr pVtab,
  5993   6798               int iSavepoint
  5994   6799               )
  5995   6800           {
  5996   6801               try
  5997   6802               {
................................................................................
  6006   6811               }
  6007   6812   
  6008   6813               return SQLiteErrorCode.Error;
  6009   6814           }
  6010   6815   
  6011   6816           ///////////////////////////////////////////////////////////////////////
  6012   6817   
         6818  +        /// <summary>
         6819  +        /// See the <see cref="ISQLiteNativeModule.xRelease" /> method.
         6820  +        /// </summary>
         6821  +        /// <param name="pVtab">
         6822  +        /// See the <see cref="ISQLiteNativeModule.xRelease" /> method.
         6823  +        /// </param>
         6824  +        /// <param name="iSavepoint">
         6825  +        /// See the <see cref="ISQLiteNativeModule.xRelease" /> method.
         6826  +        /// </param>
         6827  +        /// <returns>
         6828  +        /// See the <see cref="ISQLiteNativeModule.xRelease" /> method.
         6829  +        /// </returns>
  6013   6830           private SQLiteErrorCode xRelease(
  6014   6831               IntPtr pVtab,
  6015   6832               int iSavepoint
  6016   6833               )
  6017   6834           {
  6018   6835               try
  6019   6836               {
................................................................................
  6028   6845               }
  6029   6846   
  6030   6847               return SQLiteErrorCode.Error;
  6031   6848           }
  6032   6849   
  6033   6850           ///////////////////////////////////////////////////////////////////////
  6034   6851   
         6852  +        /// <summary>
         6853  +        /// See the <see cref="ISQLiteNativeModule.xRollbackTo" /> method.
         6854  +        /// </summary>
         6855  +        /// <param name="pVtab">
         6856  +        /// See the <see cref="ISQLiteNativeModule.xRollbackTo" /> method.
         6857  +        /// </param>
         6858  +        /// <param name="iSavepoint">
         6859  +        /// See the <see cref="ISQLiteNativeModule.xRollbackTo" /> method.
         6860  +        /// </param>
         6861  +        /// <returns>
         6862  +        /// See the <see cref="ISQLiteNativeModule.xRollbackTo" /> method.
         6863  +        /// </returns>
  6035   6864           private SQLiteErrorCode xRollbackTo(
  6036   6865               IntPtr pVtab,
  6037   6866               int iSavepoint
  6038   6867               )
  6039   6868           {
  6040   6869               try
  6041   6870               {
................................................................................
  6053   6882           }
  6054   6883           #endregion
  6055   6884   
  6056   6885           ///////////////////////////////////////////////////////////////////////
  6057   6886   
  6058   6887           #region ISQLiteManagedModule Members
  6059   6888           private bool declared;
         6889  +        /// <summary>
         6890  +        /// Returns non-zero if the schema for the virtual table has been
         6891  +        /// declared.
         6892  +        /// </summary>
  6060   6893           public virtual bool Declared
  6061   6894           {
  6062   6895               get { CheckDisposed(); return declared; }
  6063   6896               internal set { declared = value; }
  6064   6897           }
  6065   6898   
  6066   6899           ///////////////////////////////////////////////////////////////////////
  6067   6900   
  6068   6901           private string name;
         6902  +        /// <summary>
         6903  +        /// Returns the name of the module as it was registered with the SQLite
         6904  +        /// core library.
         6905  +        /// </summary>
  6069   6906           public virtual string Name
  6070   6907           {
  6071   6908               get { CheckDisposed(); return name; }
  6072   6909           }
  6073   6910   
  6074   6911           ///////////////////////////////////////////////////////////////////////
  6075   6912   
         6913  +        /// <summary>
         6914  +        /// This method is called in response to the
         6915  +        /// <see cref="ISQLiteNativeModule.xCreate" /> method.
         6916  +        /// </summary>
         6917  +        /// <param name="connection">
         6918  +        /// The <see cref="SQLiteConnection" /> object instance associated with
         6919  +        /// the virtual table.
         6920  +        /// </param>
         6921  +        /// <param name="pClientData">
         6922  +        /// The native user-data pointer associated with this module, as it was
         6923  +        /// provided to the SQLite core library when the native module instance
         6924  +        /// was created.
         6925  +        /// </param>
         6926  +        /// <param name="arguments">
         6927  +        /// The module name, database name, virtual table name, and all other
         6928  +        /// arguments passed to the CREATE VIRTUAL TABLE statement.
         6929  +        /// </param>
         6930  +        /// <param name="table">
         6931  +        /// Upon success, this parameter must be modified to contain the
         6932  +        /// <see cref="SQLiteVirtualTable" /> object instance associated with
         6933  +        /// the virtual table.
         6934  +        /// </param>
         6935  +        /// <param name="error">
         6936  +        /// Upon failure, this parameter must be modified to contain an error
         6937  +        /// message.
         6938  +        /// </param>
         6939  +        /// <returns>
         6940  +        /// A standard SQLite return code.
         6941  +        /// </returns>
  6076   6942           public abstract SQLiteErrorCode Create(
  6077   6943               SQLiteConnection connection,
  6078   6944               IntPtr pClientData,
  6079   6945               string[] arguments,
  6080   6946               ref SQLiteVirtualTable table,
  6081   6947               ref string error
  6082   6948               );
  6083   6949   
  6084   6950           ///////////////////////////////////////////////////////////////////////
  6085   6951   
         6952  +        /// <summary>
         6953  +        /// This method is called in response to the
         6954  +        /// <see cref="ISQLiteNativeModule.xConnect" /> method.
         6955  +        /// </summary>
         6956  +        /// <param name="connection">
         6957  +        /// The <see cref="SQLiteConnection" /> object instance associated with
         6958  +        /// the virtual table.
         6959  +        /// </param>
         6960  +        /// <param name="pClientData">
         6961  +        /// The native user-data pointer associated with this module, as it was
         6962  +        /// provided to the SQLite core library when the native module instance
         6963  +        /// was created.
         6964  +        /// </param>
         6965  +        /// <param name="arguments">
         6966  +        /// The module name, database name, virtual table name, and all other
         6967  +        /// arguments passed to the CREATE VIRTUAL TABLE statement.
         6968  +        /// </param>
         6969  +        /// <param name="table">
         6970  +        /// Upon success, this parameter must be modified to contain the
         6971  +        /// <see cref="SQLiteVirtualTable" /> object instance associated with
         6972  +        /// the virtual table.
         6973  +        /// </param>
         6974  +        /// <param name="error">
         6975  +        /// Upon failure, this parameter must be modified to contain an error
         6976  +        /// message.
         6977  +        /// </param>
         6978  +        /// <returns>
         6979  +        /// A standard SQLite return code.
         6980  +        /// </returns>
  6086   6981           public abstract SQLiteErrorCode Connect(
  6087   6982               SQLiteConnection connection,
  6088   6983               IntPtr pClientData,
  6089   6984               string[] arguments,
  6090   6985               ref SQLiteVirtualTable table,
  6091   6986               ref string error
  6092   6987               );
  6093   6988   
  6094   6989           ///////////////////////////////////////////////////////////////////////
  6095   6990   
         6991  +        /// <summary>
         6992  +        /// This method is called in response to the
         6993  +        /// <see cref="ISQLiteNativeModule.xBestIndex" /> method.
         6994  +        /// </summary>
         6995  +        /// <param name="table">
         6996  +        /// The <see cref="SQLiteVirtualTable" /> object instance associated
         6997  +        /// with this virtual table.
         6998  +        /// </param>
         6999  +        /// <param name="index">
         7000  +        /// The <see cref="SQLiteIndex" /> object instance containing all the
         7001  +        /// data for the inputs and outputs relating to index selection.
         7002  +        /// </param>
         7003  +        /// <returns>
         7004  +        /// A standard SQLite return code.
         7005  +        /// </returns>
  6096   7006           public abstract SQLiteErrorCode BestIndex(
  6097   7007               SQLiteVirtualTable table,
  6098   7008               SQLiteIndex index
  6099   7009               );
  6100   7010   
  6101   7011           ///////////////////////////////////////////////////////////////////////
  6102   7012   
         7013  +        /// <summary>
         7014  +        /// This method is called in response to the
         7015  +        /// <see cref="ISQLiteNativeModule.xDisconnect" /> method.
         7016  +        /// </summary>
         7017  +        /// <param name="table">
         7018  +        /// The <see cref="SQLiteVirtualTable" /> object instance associated
         7019  +        /// with this virtual table.
         7020  +        /// </param>
         7021  +        /// <returns>
         7022  +        /// A standard SQLite return code.
         7023  +        /// </returns>
  6103   7024           public abstract SQLiteErrorCode Disconnect(
  6104   7025               SQLiteVirtualTable table
  6105   7026               );
  6106   7027   
  6107   7028           ///////////////////////////////////////////////////////////////////////
  6108   7029   
         7030  +        /// <summary>
         7031  +        /// This method is called in response to the
         7032  +        /// <see cref="ISQLiteNativeModule.xDestroy" /> method.
         7033  +        /// </summary>
         7034  +        /// <param name="table">
         7035  +        /// The <see cref="SQLiteVirtualTable" /> object instance associated
         7036  +        /// with this virtual table.
         7037  +        /// </param>
         7038  +        /// <returns>
         7039  +        /// A standard SQLite return code.
         7040  +        /// </returns>
  6109   7041           public abstract SQLiteErrorCode Destroy(
  6110   7042               SQLiteVirtualTable table
  6111   7043               );
  6112   7044   
  6113   7045           ///////////////////////////////////////////////////////////////////////
  6114   7046   
         7047  +        /// <summary>
         7048  +        /// This method is called in response to the
         7049  +        /// <see cref="ISQLiteNativeModule.xOpen" /> method.
         7050  +        /// </summary>
         7051  +        /// <param name="table">
         7052  +        /// The <see cref="SQLiteVirtualTable" /> object instance associated
         7053  +        /// with this virtual table.
         7054  +        /// </param>
         7055  +        /// <param name="cursor">
         7056  +        /// Upon success, this parameter must be modified to contain the
         7057  +        /// <see cref="SQLiteVirtualTableCursor" /> object instance associated
         7058  +        /// with the newly opened virtual table cursor.
         7059  +        /// </param>
         7060  +        /// <returns>
         7061  +        /// A standard SQLite return code.
         7062  +        /// </returns>
  6115   7063           public abstract SQLiteErrorCode Open(
  6116   7064               SQLiteVirtualTable table,
  6117   7065               ref SQLiteVirtualTableCursor cursor
  6118   7066               );
  6119   7067   
  6120   7068           ///////////////////////////////////////////////////////////////////////
  6121   7069   
         7070  +        /// <summary>
         7071  +        /// This method is called in response to the
         7072  +        /// <see cref="ISQLiteNativeModule.xClose" /> method.
         7073  +        /// </summary>
         7074  +        /// <param name="cursor">
         7075  +        /// The <see cref="SQLiteVirtualTableCursor" /> object instance
         7076  +        /// associated with the previously opened virtual table cursor to be
         7077  +        /// used.
         7078  +        /// </param>
         7079  +        /// <returns>
         7080  +        /// A standard SQLite return code.
         7081  +        /// </returns>
  6122   7082           public abstract SQLiteErrorCode Close(
  6123   7083               SQLiteVirtualTableCursor cursor
  6124   7084               );
  6125   7085   
  6126   7086           ///////////////////////////////////////////////////////////////////////
  6127   7087   
         7088  +        /// <summary>
         7089  +        /// This method is called in response to the
         7090  +        /// <see cref="ISQLiteNativeModule.xFilter" /> method.
         7091  +        /// </summary>
         7092  +        /// <param name="cursor">
         7093  +        /// The <see cref="SQLiteVirtualTableCursor" /> object instance
         7094  +        /// associated with the previously opened virtual table cursor to be
         7095  +        /// used.
         7096  +        /// </param>
         7097  +        /// <param name="indexNumber">
         7098  +        /// Number used to help identify the selected index.
         7099  +        /// </param>
         7100  +        /// <param name="indexString">
         7101  +        /// String used to help identify the selected index.
         7102  +        /// </param>
         7103  +        /// <param name="values">
         7104  +        /// The values corresponding to each column in the selected index.
         7105  +        /// </param>
         7106  +        /// <returns>
         7107  +        /// A standard SQLite return code.
         7108  +        /// </returns>
  6128   7109           public abstract SQLiteErrorCode Filter(
  6129   7110               SQLiteVirtualTableCursor cursor,
  6130   7111               int indexNumber,
  6131   7112               string indexString,
  6132   7113               SQLiteValue[] values
  6133   7114               );
  6134   7115   
  6135   7116           ///////////////////////////////////////////////////////////////////////
  6136   7117   
         7118  +        /// <summary>
         7119  +        /// This method is called in response to the
         7120  +        /// <see cref="ISQLiteNativeModule.xNext" /> method.
         7121  +        /// </summary>
         7122  +        /// <param name="cursor">
         7123  +        /// The <see cref="SQLiteVirtualTableCursor" /> object instance
         7124  +        /// associated with the previously opened virtual table cursor to be
         7125  +        /// used.
         7126  +        /// </param>
         7127  +        /// <returns>
         7128  +        /// A standard SQLite return code.
         7129  +        /// </returns>
  6137   7130           public abstract SQLiteErrorCode Next(
  6138   7131               SQLiteVirtualTableCursor cursor
  6139   7132               );
  6140   7133   
  6141   7134           ///////////////////////////////////////////////////////////////////////
  6142   7135   
         7136  +        /// <summary>
         7137  +        /// This method is called in response to the
         7138  +        /// <see cref="ISQLiteNativeModule.xEof" /> method.
         7139  +        /// </summary>
         7140  +        /// <param name="cursor">
         7141  +        /// The <see cref="SQLiteVirtualTableCursor" /> object instance
         7142  +        /// associated with the previously opened virtual table cursor to be
         7143  +        /// used.
         7144  +        /// </param>
         7145  +        /// <returns>
         7146  +        /// Non-zero if no more rows are available; zero otherwise.
         7147  +        /// </returns>
  6143   7148           public abstract bool Eof(
  6144   7149               SQLiteVirtualTableCursor cursor
  6145   7150               );
  6146   7151   
  6147   7152           ///////////////////////////////////////////////////////////////////////
  6148   7153   
         7154  +        /// <summary>
         7155  +        /// This method is called in response to the
         7156  +        /// <see cref="ISQLiteNativeModule.xColumn" /> method.
         7157  +        /// </summary>
         7158  +        /// <param name="cursor">
         7159  +        /// The <see cref="SQLiteVirtualTableCursor" /> object instance
         7160  +        /// associated with the previously opened virtual table cursor to be
         7161  +        /// used.
         7162  +        /// </param>
         7163  +        /// <param name="context">
         7164  +        /// The <see cref="SQLiteContext" /> object instance to be used for
         7165  +        /// returning the specified column value to the SQLite core library.
         7166  +        /// </param>
         7167  +        /// <param name="index">
         7168  +        /// The zero-based index corresponding to the column containing the
         7169  +        /// value to be returned.
         7170  +        /// </param>
         7171  +        /// <returns>
         7172  +        /// A standard SQLite return code.
         7173  +        /// </returns>
  6149   7174           public abstract SQLiteErrorCode Column(
  6150   7175               SQLiteVirtualTableCursor cursor,
  6151   7176               SQLiteContext context,
  6152   7177               int index
  6153   7178               );
  6154   7179   
  6155   7180           ///////////////////////////////////////////////////////////////////////
  6156   7181   
         7182  +        /// <summary>
         7183  +        /// This method is called in response to the
         7184  +        /// <see cref="ISQLiteNativeModule.xRowId" /> method.
         7185  +        /// </summary>
         7186  +        /// <param name="cursor">
         7187  +        /// The <see cref="SQLiteVirtualTableCursor" /> object instance
         7188  +        /// associated with the previously opened virtual table cursor to be
         7189  +        /// used.
         7190  +        /// </param>
         7191  +        /// <param name="rowId">
         7192  +        /// Upon success, this parameter must be modified to contain the unique
         7193  +        /// integer row identifier for the current row for the specified cursor.
         7194  +        /// </param>
         7195  +        /// <returns>
         7196  +        /// A standard SQLite return code.
         7197  +        /// </returns>
  6157   7198           public abstract SQLiteErrorCode RowId(
  6158   7199               SQLiteVirtualTableCursor cursor,
  6159   7200               ref long rowId
  6160   7201               );
  6161   7202   
  6162   7203           ///////////////////////////////////////////////////////////////////////
  6163   7204   
         7205  +        /// <summary>
         7206  +        /// This method is called in response to the
         7207  +        /// <see cref="ISQLiteNativeModule.xUpdate" /> method.
         7208  +        /// </summary>
         7209  +        /// <param name="table">
         7210  +        /// The <see cref="SQLiteVirtualTable" /> object instance associated
         7211  +        /// with this virtual table.
         7212  +        /// </param>
         7213  +        /// <param name="values">
         7214  +        /// The array of <see cref="SQLiteValue" /> object instances containing
         7215  +        /// the new or modified column values, if any.
         7216  +        /// </param>
         7217  +        /// <param name="rowId">
         7218  +        /// Upon success, this parameter must be modified to contain the unique
         7219  +        /// integer row identifier for the row that was inserted, if any.
         7220  +        /// </param>
         7221  +        /// <returns>
         7222  +        /// A standard SQLite return code.
         7223  +        /// </returns>
  6164   7224           public abstract SQLiteErrorCode Update(
  6165   7225               SQLiteVirtualTable table,
  6166   7226               SQLiteValue[] values,
  6167   7227               ref long rowId
  6168   7228               );
  6169   7229   
  6170   7230           ///////////////////////////////////////////////////////////////////////
  6171   7231   
         7232  +        /// <summary>
         7233  +        /// This method is called in response to the
         7234  +        /// <see cref="ISQLiteNativeModule.xBegin" /> method.
         7235  +        /// </summary>
         7236  +        /// <param name="table">
         7237  +        /// The <see cref="SQLiteVirtualTable" /> object instance associated
         7238  +        /// with this virtual table.
         7239  +        /// </param>
         7240  +        /// <returns>
         7241  +        /// A standard SQLite return code.
         7242  +        /// </returns>
  6172   7243           public abstract SQLiteErrorCode Begin(
  6173   7244               SQLiteVirtualTable table
  6174   7245               );
  6175   7246   
  6176   7247           ///////////////////////////////////////////////////////////////////////
  6177   7248   
         7249  +        /// <summary>
         7250  +        /// This method is called in response to the
         7251  +        /// <see cref="ISQLiteNativeModule.xSync" /> method.
         7252  +        /// </summary>
         7253  +        /// <param name="table">
         7254  +        /// The <see cref="SQLiteVirtualTable" /> object instance associated
         7255  +        /// with this virtual table.
         7256  +        /// </param>
         7257  +        /// <returns>
         7258  +        /// A standard SQLite return code.
         7259  +        /// </returns>
  6178   7260           public abstract SQLiteErrorCode Sync(
  6179   7261               SQLiteVirtualTable table
  6180   7262               );
  6181   7263   
  6182   7264           ///////////////////////////////////////////////////////////////////////
  6183   7265   
         7266  +        /// <summary>
         7267  +        /// This method is called in response to the
         7268  +        /// <see cref="ISQLiteNativeModule.xCommit" /> method.
         7269  +        /// </summary>
         7270  +        /// <param name="table">
         7271  +        /// The <see cref="SQLiteVirtualTable" /> object instance associated
         7272  +        /// with this virtual table.
         7273  +        /// </param>
         7274  +        /// <returns>
         7275  +        /// A standard SQLite return code.
         7276  +        /// </returns>
  6184   7277           public abstract SQLiteErrorCode Commit(
  6185   7278               SQLiteVirtualTable table
  6186   7279               );
  6187   7280   
  6188   7281           ///////////////////////////////////////////////////////////////////////
  6189   7282   
         7283  +        /// <summary>
         7284  +        /// This method is called in response to the
         7285  +        /// <see cref="ISQLiteNativeModule.xRollback" /> method.
         7286  +        /// </summary>
         7287  +        /// <param name="table">
         7288  +        /// The <see cref="SQLiteVirtualTable" /> object instance associated
         7289  +        /// with this virtual table.
         7290  +        /// </param>
         7291  +        /// <returns>
         7292  +        /// A standard SQLite return code.
         7293  +        /// </returns>
  6190   7294           public abstract SQLiteErrorCode Rollback(
  6191   7295               SQLiteVirtualTable table
  6192   7296               );
  6193   7297   
  6194   7298           ///////////////////////////////////////////////////////////////////////
  6195   7299   
         7300  +        /// <summary>
         7301  +        /// This method is called in response to the
         7302  +        /// <see cref="ISQLiteNativeModule.xFindFunction" /> method.
         7303  +        /// </summary>
         7304  +        /// <param name="table">
         7305  +        /// The <see cref="SQLiteVirtualTable" /> object instance associated
         7306  +        /// with this virtual table.
         7307  +        /// </param>
         7308  +        /// <param name="argumentCount">
         7309  +        /// The number of arguments to the function being sought.
         7310  +        /// </param>
         7311  +        /// <param name="name">
         7312  +        /// The name of the function being sought.
         7313  +        /// </param>
         7314  +        /// <param name="function">
         7315  +        /// Upon success, this parameter must be modified to contain the
         7316  +        /// <see cref="SQLiteFunction" /> object instance responsible for
         7317  +        /// implementing the specified function.
         7318  +        /// </param>
         7319  +        /// <param name="pClientData">
         7320  +        /// Upon success, this parameter must be modified to contain the
         7321  +        /// native user-data pointer associated with
         7322  +        /// <paramref name="function" />.
         7323  +        /// </param>
         7324  +        /// <returns>
         7325  +        /// Non-zero if the specified function was found; zero otherwise.
         7326  +        /// </returns>
  6196   7327           public abstract bool FindFunction(
  6197   7328               SQLiteVirtualTable table,
  6198   7329               int argumentCount,
  6199   7330               string name,
  6200   7331               ref SQLiteFunction function,
  6201   7332               ref IntPtr pClientData
  6202   7333               );
  6203   7334   
  6204   7335           ///////////////////////////////////////////////////////////////////////
  6205   7336   
         7337  +        /// <summary>
         7338  +        /// This method is called in response to the
         7339  +        /// <see cref="ISQLiteNativeModule.xRename" /> method.
         7340  +        /// </summary>
         7341  +        /// <param name="table">
         7342  +        /// The <see cref="SQLiteVirtualTable" /> object instance associated
         7343  +        /// with this virtual table.
         7344  +        /// </param>
         7345  +        /// <param name="newName">
         7346  +        /// The new name for the virtual table.
         7347  +        /// </param>
         7348  +        /// <returns>
         7349  +        /// A standard SQLite return code.
         7350  +        /// </returns>
  6206   7351           public abstract SQLiteErrorCode Rename(
  6207   7352               SQLiteVirtualTable table,
  6208   7353               string newName
  6209   7354               );
  6210   7355   
  6211   7356           ///////////////////////////////////////////////////////////////////////
  6212   7357   
         7358  +        /// <summary>
         7359  +        /// This method is called in response to the
         7360  +        /// <see cref="ISQLiteNativeModule.xSavepoint" /> method.
         7361  +        /// </summary>
         7362  +        /// <param name="table">
         7363  +        /// The <see cref="SQLiteVirtualTable" /> object instance associated
         7364  +        /// with this virtual table.
         7365  +        /// </param>
         7366  +        /// <param name="savepoint">
         7367  +        /// This is an integer identifier under which the the current state of
         7368  +        /// the virtual table should be saved.
         7369  +        /// </param>
         7370  +        /// <returns>
         7371  +        /// A standard SQLite return code.
         7372  +        /// </returns>
  6213   7373           public abstract SQLiteErrorCode Savepoint(
  6214   7374               SQLiteVirtualTable table,
  6215   7375               int savepoint
  6216   7376               );
  6217   7377   
  6218   7378           ///////////////////////////////////////////////////////////////////////
  6219   7379   
         7380  +        /// <summary>
         7381  +        /// This method is called in response to the
         7382  +        /// <see cref="ISQLiteNativeModule.xRelease" /> method.
         7383  +        /// </summary>
         7384  +        /// <param name="table">
         7385  +        /// The <see cref="SQLiteVirtualTable" /> object instance associated
         7386  +        /// with this virtual table.
         7387  +        /// </param>
         7388  +        /// <param name="savepoint">
         7389  +        /// This is an integer used to indicate that any saved states with an
         7390  +        /// identifier greater than or equal to this should be deleted by the
         7391  +        /// virtual table.
         7392  +        /// </param>
         7393  +        /// <returns>
         7394  +        /// A standard SQLite return code.
         7395  +        /// </returns>
  6220   7396           public abstract SQLiteErrorCode Release(
  6221   7397               SQLiteVirtualTable table,
  6222   7398               int savepoint
  6223   7399               );
  6224   7400   
  6225   7401           ///////////////////////////////////////////////////////////////////////
  6226   7402   
         7403  +        /// <summary>
         7404  +        /// This method is called in response to the
         7405  +        /// <see cref="ISQLiteNativeModule.xRollbackTo" /> method.
         7406  +        /// </summary>
         7407  +        /// <param name="table">
         7408  +        /// The <see cref="SQLiteVirtualTable" /> object instance associated
         7409  +        /// with this virtual table.
         7410  +        /// </param>
         7411  +        /// <param name="savepoint">
         7412  +        /// This is an integer identifier used to specify a specific saved
         7413  +        /// state for the virtual table for it to restore itself back to, which
         7414  +        /// should also have the effect of deleting all saved states with an
         7415  +        /// integer identifier greater than this one.
         7416  +        /// </param>
         7417  +        /// <returns>
         7418  +        /// A standard SQLite return code.
         7419  +        /// </returns>
  6227   7420           public abstract SQLiteErrorCode RollbackTo(
  6228   7421               SQLiteVirtualTable table,
  6229   7422               int savepoint
  6230   7423               );
  6231   7424           #endregion
  6232   7425   
  6233   7426           ///////////////////////////////////////////////////////////////////////
  6234   7427   
  6235   7428           #region IDisposable Members
         7429  +        /// <summary>
         7430  +        /// Disposes of this object instance.
         7431  +        /// </summary>
  6236   7432           public void Dispose()
  6237   7433           {
  6238   7434               Dispose(true);
  6239   7435               GC.SuppressFinalize(this);
  6240   7436           }
  6241   7437           #endregion
  6242   7438   
  6243   7439           ///////////////////////////////////////////////////////////////////////
  6244   7440   
  6245   7441           #region IDisposable "Pattern" Members
  6246   7442           private bool disposed;
         7443  +        /// <summary>
         7444  +        /// Throws an <see cref="System.ObjectDisposedException"/> if this
         7445  +        /// object instance has been disposed.
         7446  +        /// </summary>
  6247   7447           private void CheckDisposed() /* throw */
  6248   7448           {
  6249   7449   #if THROW_ON_DISPOSED
  6250   7450               if (disposed)
  6251   7451               {
  6252   7452                   throw new ObjectDisposedException(
  6253   7453                       typeof(SQLiteModule).Name);
  6254   7454               }
  6255   7455   #endif
  6256   7456           }
  6257   7457   
  6258   7458           ///////////////////////////////////////////////////////////////////////
  6259   7459   
         7460  +        /// <summary>
         7461  +        /// Disposes of this object instance.
         7462  +        /// </summary>
         7463  +        /// <param name="disposing">
         7464  +        /// Non-zero if this method is being called from the
         7465  +        /// <see cref="Dispose()" /> method.  Zero if this method is being
         7466  +        /// called from the finalizer.
         7467  +        /// </param>
  6260   7468           protected virtual void Dispose(bool disposing)
  6261   7469           {
  6262   7470               if (!disposed)
  6263   7471               {
  6264   7472                   //if (disposing)
  6265   7473                   //{
  6266   7474                   //    ////////////////////////////////////
................................................................................
  6299   7507               }
  6300   7508           }
  6301   7509           #endregion
  6302   7510   
  6303   7511           ///////////////////////////////////////////////////////////////////////
  6304   7512   
  6305   7513           #region Destructor
         7514  +        /// <summary>
         7515  +        /// Finalizes this object instance.
         7516  +        /// </summary>
  6306   7517           ~SQLiteModule()
  6307   7518           {
  6308   7519               Dispose(false);
  6309   7520           }
  6310   7521           #endregion
  6311   7522       }
  6312   7523       #endregion
  6313   7524   }