System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 523bce69295ebbd78be0664659b0a060cae5c1b0:


0000: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
0010: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0020: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0030: 2a 2a 2a 2a 2a 2a 2a 2a 2a 0d 0a 20 2a 20 41 44  *********.. * AD
0040: 4f 2e 4e 45 54 20 32 2e 30 20 44 61 74 61 20 50  O.NET 2.0 Data P
0050: 72 6f 76 69 64 65 72 20 66 6f 72 20 53 51 4c 69  rovider for SQLi
0060: 74 65 20 56 65 72 73 69 6f 6e 20 33 2e 58 0d 0a  te Version 3.X..
0070: 20 2a 20 57 72 69 74 74 65 6e 20 62 79 20 4a 6f   * Written by Jo
0080: 65 20 4d 69 73 74 61 63 68 6b 69 6e 20 28 6a 6f  e Mistachkin (jo
0090: 65 40 6d 69 73 74 61 63 68 6b 69 6e 2e 63 6f 6d  e@mistachkin.com
00a0: 29 0d 0a 20 2a 0d 0a 20 2a 20 52 65 6c 65 61 73  ).. *.. * Releas
00b0: 65 64 20 74 6f 20 74 68 65 20 70 75 62 6c 69 63  ed to the public
00c0: 20 64 6f 6d 61 69 6e 2c 20 75 73 65 20 61 74 20   domain, use at 
00d0: 79 6f 75 72 20 6f 77 6e 20 72 69 73 6b 21 0d 0a  your own risk!..
00e0: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   ***************
00f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0100: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0110: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0d 0a 0d 0a 6e 61  *********/....na
0120: 6d 65 73 70 61 63 65 20 53 79 73 74 65 6d 2e 44  mespace System.D
0130: 61 74 61 2e 53 51 4c 69 74 65 0d 0a 7b 0d 0a 20  ata.SQLite..{.. 
0140: 20 20 20 23 72 65 67 69 6f 6e 20 49 53 51 4c 69     #region ISQLi
0150: 74 65 4e 61 74 69 76 65 4d 6f 64 75 6c 65 20 49  teNativeModule I
0160: 6e 74 65 72 66 61 63 65 0d 0a 20 20 20 20 2f 2f  nterface..    //
0170: 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20  / <summary>..   
0180: 20 2f 2f 2f 20 54 68 69 73 20 69 6e 74 65 72 66   /// This interf
0190: 61 63 65 20 72 65 70 72 65 73 65 6e 74 73 20 61  ace represents a
01a0: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
01b0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 72  mplementation wr
01c0: 69 74 74 65 6e 20 69 6e 0d 0a 20 20 20 20 2f 2f  itten in..    //
01d0: 2f 20 6e 61 74 69 76 65 20 63 6f 64 65 2e 0d 0a  / native code...
01e0: 20 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72      /// </summar
01f0: 79 3e 0d 0a 20 20 20 20 70 75 62 6c 69 63 20 69  y>..    public i
0200: 6e 74 65 72 66 61 63 65 20 49 53 51 4c 69 74 65  nterface ISQLite
0210: 4e 61 74 69 76 65 4d 6f 64 75 6c 65 0d 0a 20 20  NativeModule..  
0220: 20 20 7b 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f    {..        ///
0230: 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20   <summary>..    
0240: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63      /// <para><c
0250: 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ode>..        //
0260: 2f 20 20 20 69 6e 74 20 28 2a 78 43 72 65 61 74  /   int (*xCreat
0270: 65 29 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  e)(sqlite3 *db, 
0280: 76 6f 69 64 20 2a 70 41 75 78 2c 0d 0a 20 20 20  void *pAux,..   
0290: 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 20 20 20       ///        
02a0: 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63          int argc
02b0: 2c 20 63 68 61 72 20 2a 2a 61 72 67 76 2c 0d 0a  , char **argv,..
02c0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20          ///     
02d0: 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74             sqlit
02e0: 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62  e3_vtab **ppVTab
02f0: 2c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20  ,..        ///  
0300: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 63 68                ch
0310: 61 72 20 2a 2a 70 7a 45 72 72 29 3b 0d 0a 20 20  ar **pzErr);..  
0320: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65        /// </code
0330: 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  ></para>..      
0340: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
0350: 20 20 20 20 20 20 2f 2f 2f 20 54 68 69 73 20 6d        /// This m
0360: 65 74 68 6f 64 20 69 73 20 63 61 6c 6c 65 64 20  ethod is called 
0370: 74 6f 20 63 72 65 61 74 65 20 61 20 6e 65 77 20  to create a new 
0380: 69 6e 73 74 61 6e 63 65 20 6f 66 20 61 20 76 69  instance of a vi
0390: 72 74 75 61 6c 20 74 61 62 6c 65 20 0d 0a 20 20  rtual table ..  
03a0: 20 20 20 20 20 20 2f 2f 2f 20 69 6e 20 72 65 73        /// in res
03b0: 70 6f 6e 73 65 20 74 6f 20 61 20 43 52 45 41 54  ponse to a CREAT
03c0: 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20  E VIRTUAL TABLE 
03d0: 73 74 61 74 65 6d 65 6e 74 2e 20 0d 0a 20 20 20  statement. ..   
03e0: 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 64 62 20       /// The db 
03f0: 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
0400: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 53 51  ointer to the SQ
0410: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 63 6f  Lite database co
0420: 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 0d 0a  nnection that ..
0430: 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 73 20 65          /// is e
0440: 78 65 63 75 74 69 6e 67 20 74 68 65 20 43 52 45  xecuting the CRE
0450: 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c  ATE VIRTUAL TABL
0460: 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 0d 0a 20  E statement. .. 
0470: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 70         /// The p
0480: 41 75 78 20 61 72 67 75 6d 65 6e 74 20 69 73 20  Aux argument is 
0490: 74 68 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  the copy of the 
04a0: 63 6c 69 65 6e 74 20 64 61 74 61 20 70 6f 69 6e  client data poin
04b0: 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65  ter that was the
04c0: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 66   ..        /// f
04d0: 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
04e0: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72  o the sqlite3_cr
04f0: 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 20 6f 72  eate_module() or
0500: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 71  ..        /// sq
0510: 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
0520: 75 6c 65 5f 76 32 28 29 20 63 61 6c 6c 20 74 68  ule_v2() call th
0530: 61 74 20 72 65 67 69 73 74 65 72 65 64 20 74 68  at registered th
0540: 65 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e ..        /// 
0550: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
0560: 64 75 6c 65 2e 20 0d 0a 20 20 20 20 20 20 20 20  dule. ..        
0570: 2f 2f 2f 20 54 68 65 20 61 72 67 76 20 70 61 72  /// The argv par
0580: 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 72  ameter is an arr
0590: 61 79 20 6f 66 20 61 72 67 63 20 70 6f 69 6e 74  ay of argc point
05a0: 65 72 73 20 74 6f 20 6e 75 6c 6c 20 74 65 72 6d  ers to null term
05b0: 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 2e 20  inated strings. 
05c0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
05d0: 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 2c 20  e first string, 
05e0: 61 72 67 76 5b 30 5d 2c 20 69 73 20 74 68 65 20  argv[0], is the 
05f0: 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75  name of the modu
0600: 6c 65 20 62 65 69 6e 67 20 69 6e 76 6f 6b 65 64  le being invoked
0610: 2e 20 20 20 54 68 65 0d 0a 20 20 20 20 20 20 20  .   The..       
0620: 20 2f 2f 2f 20 6d 6f 64 75 6c 65 20 6e 61 6d 65   /// module name
0630: 20 69 73 20 74 68 65 20 6e 61 6d 65 20 70 72 6f   is the name pro
0640: 76 69 64 65 64 20 61 73 20 74 68 65 20 73 65 63  vided as the sec
0650: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
0660: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 71  ..        /// sq
0670: 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
0680: 75 6c 65 28 29 20 61 6e 64 20 61 73 20 74 68 65  ule() and as the
0690: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
06a0: 20 55 53 49 4e 47 20 63 6c 61 75 73 65 20 6f 66   USING clause of
06b0: 20 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f   the..        //
06c0: 2f 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c  / CREATE VIRTUAL
06d0: 20 54 41 42 4c 45 20 73 74 61 74 65 6d 65 6e 74   TABLE statement
06e0: 20 74 68 61 74 20 69 73 20 72 75 6e 6e 69 6e 67   that is running
06f0: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54  ...        /// T
0700: 68 65 20 73 65 63 6f 6e 64 2c 20 61 72 67 76 5b  he second, argv[
0710: 31 5d 2c 20 69 73 20 74 68 65 20 6e 61 6d 65 20  1], is the name 
0720: 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
0730: 69 6e 20 77 68 69 63 68 20 74 68 65 20 6e 65 77  in which the new
0740: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
0750: 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 2e  s being created.
0760: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   The database na
0770: 6d 65 20 69 73 20 22 6d 61 69 6e 22 20 66 6f 72  me is "main" for
0780: 20 74 68 65 20 70 72 69 6d 61 72 79 20 64 61 74   the primary dat
0790: 61 62 61 73 65 2c 20 6f 72 0d 0a 20 20 20 20 20  abase, or..     
07a0: 20 20 20 2f 2f 2f 20 22 74 65 6d 70 22 20 66 6f     /// "temp" fo
07b0: 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 2c  r TEMP database,
07c0: 20 6f 72 20 74 68 65 20 6e 61 6d 65 20 67 69 76   or the name giv
07d0: 65 6e 20 61 74 20 74 68 65 20 65 6e 64 20 6f 66  en at the end of
07e0: 20 74 68 65 20 41 54 54 41 43 48 0d 0a 20 20 20   the ATTACH..   
07f0: 20 20 20 20 20 2f 2f 2f 20 73 74 61 74 65 6d 65       /// stateme
0800: 6e 74 20 66 6f 72 20 61 74 74 61 63 68 65 64 20  nt for attached 
0810: 64 61 74 61 62 61 73 65 73 2e 20 20 54 68 65 20  databases.  The 
0820: 74 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 6f 66  third element of
0830: 20 74 68 65 20 61 72 72 61 79 2c 20 61 72 67 76   the array, argv
0840: 5b 32 5d 2c 20 0d 0a 20 20 20 20 20 20 20 20 2f  [2], ..        /
0850: 2f 2f 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  // is the name o
0860: 66 20 74 68 65 20 6e 65 77 20 76 69 72 74 75 61  f the new virtua
0870: 6c 20 74 61 62 6c 65 2c 20 61 73 20 73 70 65 63  l table, as spec
0880: 69 66 69 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20  ified following 
0890: 74 68 65 20 54 41 42 4c 45 0d 0a 20 20 20 20 20  the TABLE..     
08a0: 20 20 20 2f 2f 2f 20 6b 65 79 77 6f 72 64 20 69     /// keyword i
08b0: 6e 20 74 68 65 20 43 52 45 41 54 45 20 56 49 52  n the CREATE VIR
08c0: 54 55 41 4c 20 54 41 42 4c 45 20 73 74 61 74 65  TUAL TABLE state
08d0: 6d 65 6e 74 2e 0d 0a 20 20 20 20 20 20 20 20 2f  ment...        /
08e0: 2f 2f 20 49 66 20 70 72 65 73 65 6e 74 2c 20 74  // If present, t
08f0: 68 65 20 66 6f 75 72 74 68 20 61 6e 64 20 73 75  he fourth and su
0900: 62 73 65 71 75 65 6e 74 20 73 74 72 69 6e 67 73  bsequent strings
0910: 20 69 6e 20 74 68 65 20 61 72 67 76 5b 5d 20 61   in the argv[] a
0920: 72 72 61 79 20 72 65 70 6f 72 74 20 0d 0a 20 20  rray report ..  
0930: 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 20 61 72        /// the ar
0940: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 6d  guments to the m
0950: 6f 64 75 6c 65 20 6e 61 6d 65 20 69 6e 20 74 68  odule name in th
0960: 65 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c  e CREATE VIRTUAL
0970: 20 54 41 42 4c 45 20 73 74 61 74 65 6d 65 6e 74   TABLE statement
0980: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
0990: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
09a0: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20  /// <para>..    
09b0: 20 20 20 20 2f 2f 2f 20 54 68 65 20 6a 6f 62 20      /// The job 
09c0: 6f 66 20 74 68 69 73 20 6d 65 74 68 6f 64 20 69  of this method i
09d0: 73 20 74 6f 20 63 6f 6e 73 74 72 75 63 74 20 74  s to construct t
09e0: 68 65 20 6e 65 77 20 76 69 72 74 75 61 6c 20 74  he new virtual t
09f0: 61 62 6c 65 20 6f 62 6a 65 63 74 0d 0a 20 20 20  able object..   
0a00: 20 20 20 20 20 2f 2f 2f 20 28 61 6e 20 73 71 6c       /// (an sql
0a10: 69 74 65 33 5f 76 74 61 62 20 6f 62 6a 65 63 74  ite3_vtab object
0a20: 29 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70  ) and return a p
0a30: 6f 69 6e 74 65 72 20 74 6f 20 69 74 20 69 6e 20  ointer to it in 
0a40: 2a 70 70 56 54 61 62 2e 0d 0a 20 20 20 20 20 20  *ppVTab...      
0a50: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
0a60: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
0a70: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41  >..        /// A
0a80: 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 61  s part of the ta
0a90: 73 6b 20 6f 66 20 63 72 65 61 74 69 6e 67 20 61  sk of creating a
0aa0: 20 6e 65 77 20 73 71 6c 69 74 65 33 5f 76 74 61   new sqlite3_vta
0ab0: 62 20 73 74 72 75 63 74 75 72 65 2c 20 74 68 69  b structure, thi
0ac0: 73 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  s ..        /// 
0ad0: 6d 65 74 68 6f 64 20 3c 75 3e 6d 75 73 74 3c 2f  method <u>must</
0ae0: 75 3e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  u> invoke sqlite
0af0: 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 29  3_declare_vtab()
0b00: 20 74 6f 20 74 65 6c 6c 20 74 68 65 20 53 51 4c   to tell the SQL
0b10: 69 74 65 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ite ..        //
0b20: 2f 20 63 6f 72 65 20 61 62 6f 75 74 20 74 68 65  / core about the
0b30: 20 63 6f 6c 75 6d 6e 73 20 61 6e 64 20 64 61 74   columns and dat
0b40: 61 74 79 70 65 73 20 69 6e 20 74 68 65 20 76 69  atypes in the vi
0b50: 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 0d 0a 20  rtual table. .. 
0b60: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 73         /// The s
0b70: 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76  qlite3_declare_v
0b80: 74 61 62 28 29 20 41 50 49 20 68 61 73 20 74 68  tab() API has th
0b90: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 74  e following prot
0ba0: 6f 74 79 70 65 3a 0d 0a 20 20 20 20 20 20 20 20  otype:..        
0bb0: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
0bc0: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c       /// <para><
0bd0: 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f  code>..        /
0be0: 2f 2f 20 20 20 20 20 69 6e 74 20 73 71 6c 69 74  //     int sqlit
0bf0: 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28  e3_declare_vtab(
0c00: 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e  sqlite3 *db, con
0c10: 73 74 20 63 68 61 72 20 2a 7a 43 72 65 61 74 65  st char *zCreate
0c20: 54 61 62 6c 65 29 0d 0a 20 20 20 20 20 20 20 20  Table)..        
0c30: 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72  /// </code></par
0c40: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
0c50: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
0c60: 2f 2f 2f 20 54 68 65 20 66 69 72 73 74 20 61 72  /// The first ar
0c70: 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
0c80: 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 29  3_declare_vtab()
0c90: 20 6d 75 73 74 20 62 65 20 74 68 65 20 73 61 6d   must be the sam
0ca0: 65 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e ..        /// 
0cb0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
0cc0: 69 6f 6e 20 70 6f 69 6e 74 65 72 20 61 73 20 74  ion pointer as t
0cd0: 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
0ce0: 65 72 20 74 6f 20 74 68 69 73 20 6d 65 74 68 6f  er to this metho
0cf0: 64 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  d...        /// 
0d00: 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
0d10: 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  ent to sqlite3_d
0d20: 65 63 6c 61 72 65 5f 76 74 61 62 28 29 20 6d 75  eclare_vtab() mu
0d30: 73 74 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  st a zero-termin
0d40: 61 74 65 64 20 0d 0a 20 20 20 20 20 20 20 20 2f  ated ..        /
0d50: 2f 2f 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  // UTF-8 string 
0d60: 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 61 20  that contains a 
0d70: 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41  well-formed CREA
0d80: 54 45 20 54 41 42 4c 45 20 73 74 61 74 65 6d 65  TE TABLE stateme
0d90: 6e 74 20 74 68 61 74 20 0d 0a 20 20 20 20 20 20  nt that ..      
0da0: 20 20 2f 2f 2f 20 64 65 66 69 6e 65 73 20 74 68    /// defines th
0db0: 65 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  e columns in the
0dc0: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61   virtual table a
0dd0: 6e 64 20 74 68 65 69 72 20 64 61 74 61 20 74 79  nd their data ty
0de0: 70 65 73 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f  pes. ..        /
0df0: 2f 2f 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  // The name of t
0e00: 68 65 20 74 61 62 6c 65 20 69 6e 20 74 68 69 73  he table in this
0e10: 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 73 74   CREATE TABLE st
0e20: 61 74 65 6d 65 6e 74 20 69 73 20 69 67 6e 6f 72  atement is ignor
0e30: 65 64 2c 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ed, ..        //
0e40: 2f 20 61 73 20 61 72 65 20 61 6c 6c 20 63 6f 6e  / as are all con
0e50: 73 74 72 61 69 6e 74 73 2e 20 4f 6e 6c 79 20 74  straints. Only t
0e60: 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20  he column names 
0e70: 61 6e 64 20 64 61 74 61 74 79 70 65 73 20 6d 61  and datatypes ma
0e80: 74 74 65 72 2e 0d 0a 20 20 20 20 20 20 20 20 2f  tter...        /
0e90: 2f 2f 20 54 68 65 20 43 52 45 41 54 45 20 54 41  // The CREATE TA
0ea0: 42 4c 45 20 73 74 61 74 65 6d 65 6e 74 20 73 74  BLE statement st
0eb0: 72 69 6e 67 20 6e 65 65 64 20 6e 6f 74 20 74 6f  ring need not to
0ec0: 20 62 65 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f   be ..        //
0ed0: 2f 20 68 65 6c 64 20 69 6e 20 70 65 72 73 69 73  / held in persis
0ee0: 74 65 6e 74 20 6d 65 6d 6f 72 79 2e 20 20 54 68  tent memory.  Th
0ef0: 65 20 73 74 72 69 6e 67 20 63 61 6e 20 62 65 0d  e string can be.
0f00: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 64 65 61  .        /// dea
0f10: 6c 6c 6f 63 61 74 65 64 20 61 6e 64 2f 6f 72 20  llocated and/or 
0f20: 72 65 75 73 65 64 20 61 73 20 73 6f 6f 6e 20 61  reused as soon a
0f30: 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 64 65  s the sqlite3_de
0f40: 63 6c 61 72 65 5f 76 74 61 62 28 29 0d 0a 20 20  clare_vtab()..  
0f50: 20 20 20 20 20 20 2f 2f 2f 20 72 6f 75 74 69 6e        /// routin
0f60: 65 20 72 65 74 75 72 6e 73 2e 0d 0a 20 20 20 20  e returns...    
0f70: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
0f80: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
0f90: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
0fa0: 20 54 68 65 20 78 43 72 65 61 74 65 20 6d 65 74   The xCreate met
0fb0: 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 69 6e 69  hod need not ini
0fc0: 74 69 61 6c 69 7a 65 20 74 68 65 20 70 4d 6f 64  tialize the pMod
0fd0: 75 6c 65 2c 20 6e 52 65 66 2c 20 61 6e 64 20 7a  ule, nRef, and z
0fe0: 45 72 72 4d 73 67 0d 0a 20 20 20 20 20 20 20 20  ErrMsg..        
0ff0: 2f 2f 2f 20 66 69 65 6c 64 73 20 6f 66 20 74 68  /// fields of th
1000: 65 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 6f  e sqlite3_vtab o
1010: 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69  bject.  The SQLi
1020: 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 74 61 6b  te core will tak
1030: 65 20 63 61 72 65 20 6f 66 20 0d 0a 20 20 20 20  e care of ..    
1040: 20 20 20 20 2f 2f 2f 20 74 68 61 74 20 63 68 6f      /// that cho
1050: 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  re...        ///
1060: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
1070: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
1080: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 43        /// The xC
1090: 72 65 61 74 65 20 73 68 6f 75 6c 64 20 72 65 74  reate should ret
10a0: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
10b0: 20 69 74 20 69 73 20 73 75 63 63 65 73 73 66 75   it is successfu
10c0: 6c 20 69 6e 20 0d 0a 20 20 20 20 20 20 20 20 2f  l in ..        /
10d0: 2f 2f 20 63 72 65 61 74 69 6e 67 20 74 68 65 20  // creating the 
10e0: 6e 65 77 20 76 69 72 74 75 61 6c 20 74 61 62 6c  new virtual tabl
10f0: 65 2c 20 6f 72 20 53 51 4c 49 54 45 5f 45 52 52  e, or SQLITE_ERR
1100: 4f 52 20 69 66 20 69 74 20 69 73 20 6e 6f 74 20  OR if it is not 
1110: 73 75 63 63 65 73 73 66 75 6c 2e 0d 0a 20 20 20  successful...   
1120: 20 20 20 20 20 2f 2f 2f 20 49 66 20 6e 6f 74 20       /// If not 
1130: 73 75 63 63 65 73 73 66 75 6c 2c 20 74 68 65 20  successful, the 
1140: 73 71 6c 69 74 65 33 5f 76 74 61 62 20 73 74 72  sqlite3_vtab str
1150: 75 63 74 75 72 65 20 6d 75 73 74 20 6e 6f 74 20  ucture must not 
1160: 62 65 20 61 6c 6c 6f 63 61 74 65 64 2e 20 0d 0a  be allocated. ..
1170: 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 6e 20 65          /// An e
1180: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 6d 61 79  rror message may
1190: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 72   optionally be r
11a0: 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 7a 45 72  eturned in *pzEr
11b0: 72 20 69 66 20 75 6e 73 75 63 63 65 73 73 66 75  r if unsuccessfu
11c0: 6c 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  l...        /// 
11d0: 53 70 61 63 65 20 74 6f 20 68 6f 6c 64 20 74 68  Space to hold th
11e0: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
11f0: 73 74 72 69 6e 67 20 6d 75 73 74 20 62 65 20 61  string must be a
1200: 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 0d 0a  llocated using..
1210: 20 20 20 20 20 20 20 20 2f 2f 2f 20 61 6e 20 53          /// an S
1220: 51 4c 69 74 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  QLite memory all
1230: 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  ocation function
1240: 20 6c 69 6b 65 20 0d 0a 20 20 20 20 20 20 20 20   like ..        
1250: 2f 2f 2f 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  /// sqlite3_mall
1260: 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
1270: 6d 70 72 69 6e 74 66 28 29 20 61 73 20 74 68 65  mprintf() as the
1280: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c   SQLite core wil
1290: 6c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 61  l..        /// a
12a0: 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74  ttempt to free t
12b0: 68 65 20 73 70 61 63 65 20 75 73 69 6e 67 20 73  he space using s
12c0: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61 66  qlite3_free() af
12d0: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 68 61  ter the error ha
12e0: 73 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 62  s..        /// b
12f0: 65 65 6e 20 72 65 70 6f 72 74 65 64 20 75 70 20  een reported up 
1300: 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
1310: 6f 6e 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  on...        ///
1320: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
1330: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
1340: 20 20 20 20 20 20 2f 2f 2f 20 49 66 20 74 68 65        /// If the
1350: 20 78 43 72 65 61 74 65 20 6d 65 74 68 6f 64 20   xCreate method 
1360: 69 73 20 6f 6d 69 74 74 65 64 20 28 6c 65 66 74  is omitted (left
1370: 20 61 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   as a NULL point
1380: 65 72 29 20 74 68 65 6e 20 74 68 65 0d 0a 20 20  er) then the..  
1390: 20 20 20 20 20 20 2f 2f 2f 20 76 69 72 74 75 61        /// virtua
13a0: 6c 20 74 61 62 6c 65 20 69 73 20 61 6e 20 65 70  l table is an ep
13b0: 6f 6e 79 6d 6f 75 73 2d 6f 6e 6c 79 20 76 69 72  onymous-only vir
13c0: 74 75 61 6c 20 74 61 62 6c 65 2e 20 20 4e 65 77  tual table.  New
13d0: 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 0d 0a 20   instances of.. 
13e0: 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 20 76         /// the v
13f0: 69 72 74 75 61 6c 20 74 61 62 6c 65 20 63 61 6e  irtual table can
1400: 6e 6f 74 20 62 65 20 63 72 65 61 74 65 64 20 75  not be created u
1410: 73 69 6e 67 20 43 52 45 41 54 45 20 56 49 52 54  sing CREATE VIRT
1420: 55 41 4c 20 54 41 42 4c 45 20 61 6e 64 20 74 68  UAL TABLE and th
1430: 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 76  e..        /// v
1440: 69 72 74 75 61 6c 20 74 61 62 6c 65 20 63 61 6e  irtual table can
1450: 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 76 69   only be used vi
1460: 61 20 69 74 73 20 6d 6f 64 75 6c 65 20 6e 61 6d  a its module nam
1470: 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e...        /// 
1480: 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65  Note that SQLite
1490: 20 76 65 72 73 69 6f 6e 73 20 70 72 69 6f 72 20   versions prior 
14a0: 74 6f 20 33 2e 39 2e 30 20 64 6f 20 6e 6f 74 20  to 3.9.0 do not 
14b0: 75 6e 64 65 72 73 74 61 6e 64 0d 0a 20 20 20 20  understand..    
14c0: 20 20 20 20 2f 2f 2f 20 65 70 6f 6e 79 6d 6f 75      /// eponymou
14d0: 73 2d 6f 6e 6c 79 20 76 69 72 74 75 61 6c 20 74  s-only virtual t
14e0: 61 62 6c 65 73 20 61 6e 64 20 77 69 6c 6c 20 73  ables and will s
14f0: 65 67 66 61 75 6c 74 20 69 66 20 61 6e 20 61 74  egfault if an at
1500: 74 65 6d 70 74 20 69 73 20 6d 61 64 65 0d 0a 20  tempt is made.. 
1510: 20 20 20 20 20 20 20 2f 2f 2f 20 74 6f 20 43 52         /// to CR
1520: 45 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42  EATE VIRTUAL TAB
1530: 4c 45 20 6f 6e 20 61 6e 20 65 70 6f 6e 79 6d 6f  LE on an eponymo
1540: 75 73 2d 6f 6e 6c 79 20 76 69 72 74 75 61 6c 20  us-only virtual 
1550: 74 61 62 6c 65 20 62 65 63 61 75 73 65 0d 0a 20  table because.. 
1560: 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 20 78         /// the x
1570: 43 72 65 61 74 65 20 6d 65 74 68 6f 64 20 77 61  Create method wa
1580: 73 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 66 6f  s not checked fo
1590: 72 20 6e 75 6c 6c 2e 0d 0a 20 20 20 20 20 20 20  r null...       
15a0: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
15b0: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
15c0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 49 66  ..        /// If
15d0: 20 74 68 65 20 78 43 72 65 61 74 65 20 6d 65 74   the xCreate met
15e0: 68 6f 64 20 69 73 20 74 68 65 20 65 78 61 63 74  hod is the exact
15f0: 20 73 61 6d 65 20 70 6f 69 6e 74 65 72 20 61 73   same pointer as
1600: 20 74 68 65 20 78 43 6f 6e 6e 65 63 74 20 6d 65   the xConnect me
1610: 74 68 6f 64 2c 0d 0a 20 20 20 20 20 20 20 20 2f  thod,..        /
1620: 2f 2f 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  // that indicate
1630: 73 20 74 68 61 74 20 74 68 65 20 76 69 72 74 75  s that the virtu
1640: 61 6c 20 74 61 62 6c 65 20 64 6f 65 73 20 6e 6f  al table does no
1650: 74 20 6e 65 65 64 20 74 6f 20 69 6e 69 74 69 61  t need to initia
1660: 6c 69 7a 65 20 62 61 63 6b 69 6e 67 0d 0a 20 20  lize backing..  
1670: 20 20 20 20 20 20 2f 2f 2f 20 73 74 6f 72 65 2e        /// store.
1680: 20 20 53 75 63 68 20 61 20 76 69 72 74 75 61 6c    Such a virtual
1690: 20 74 61 62 6c 65 20 63 61 6e 20 62 65 20 75 73   table can be us
16a0: 65 64 20 61 73 20 61 6e 20 65 70 6f 6e 79 6d 6f  ed as an eponymo
16b0: 75 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  us virtual table
16c0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6f 72  ..        /// or
16d0: 20 61 73 20 61 20 6e 61 6d 65 64 20 76 69 72 74   as a named virt
16e0: 75 61 6c 20 74 61 62 6c 65 20 75 73 69 6e 67 20  ual table using 
16f0: 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20 54  CREATE VIRTUAL T
1700: 41 42 4c 45 20 6f 72 20 62 6f 74 68 2e 0d 0a 20  ABLE or both... 
1710: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
1720: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
1730: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
1740: 2f 2f 2f 20 49 66 20 61 20 63 6f 6c 75 6d 6e 20  /// If a column 
1750: 64 61 74 61 74 79 70 65 20 63 6f 6e 74 61 69 6e  datatype contain
1760: 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 6b 65  s the special ke
1770: 79 77 6f 72 64 20 22 48 49 44 44 45 4e 22 0d 0a  yword "HIDDEN"..
1780: 20 20 20 20 20 20 20 20 2f 2f 2f 20 28 69 6e 20          /// (in 
1790: 61 6e 79 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  any combination 
17a0: 6f 66 20 75 70 70 65 72 20 61 6e 64 20 6c 6f 77  of upper and low
17b0: 65 72 20 63 61 73 65 20 6c 65 74 74 65 72 73 29  er case letters)
17c0: 20 74 68 65 6e 20 74 68 61 74 20 6b 65 79 77 6f   then that keywo
17d0: 72 64 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  rd..        /// 
17e0: 69 74 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  it is omitted fr
17f0: 6f 6d 20 74 68 65 20 63 6f 6c 75 6d 6e 20 64 61  om the column da
1800: 74 61 74 79 70 65 20 6e 61 6d 65 20 61 6e 64 20  tatype name and 
1810: 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 6d 61  the column is ma
1820: 72 6b 65 64 20 0d 0a 20 20 20 20 20 20 20 20 2f  rked ..        /
1830: 2f 2f 20 61 73 20 61 20 68 69 64 64 65 6e 20 63  // as a hidden c
1840: 6f 6c 75 6d 6e 20 69 6e 74 65 72 6e 61 6c 6c 79  olumn internally
1850: 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  . ..        /// 
1860: 41 20 68 69 64 64 65 6e 20 63 6f 6c 75 6d 6e 20  A hidden column 
1870: 64 69 66 66 65 72 73 20 66 72 6f 6d 20 61 20 6e  differs from a n
1880: 6f 72 6d 61 6c 20 63 6f 6c 75 6d 6e 20 69 6e 20  ormal column in 
1890: 74 68 72 65 65 20 72 65 73 70 65 63 74 73 3a 0d  three respects:.
18a0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
18b0: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
18c0: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
18d0: 20 20 2f 2f 2f 20 20 48 69 64 64 65 6e 20 63 6f    ///  Hidden co
18e0: 6c 75 6d 6e 73 20 61 72 65 20 6e 6f 74 20 6c 69  lumns are not li
18f0: 73 74 65 64 20 69 6e 20 74 68 65 20 64 61 74 61  sted in the data
1900: 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  set returned by 
1910: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20  ..        ///   
1920: 20 20 20 22 50 52 41 47 4d 41 20 74 61 62 6c 65     "PRAGMA table
1930: 5f 69 6e 66 6f 22 2c 0d 0a 20 20 20 20 20 20 20  _info",..       
1940: 20 2f 2f 2f 20 20 48 69 64 64 65 6e 20 63 6f 6c   ///  Hidden col
1950: 75 6d 6e 73 20 61 72 65 20 6e 6f 74 20 69 6e 63  umns are not inc
1960: 6c 75 64 65 64 20 69 6e 20 74 68 65 20 65 78 70  luded in the exp
1970: 61 6e 73 69 6f 6e 20 6f 66 20 61 20 22 2a 22 0d  ansion of a "*".
1980: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20  .        ///    
1990: 20 20 65 78 70 72 65 73 73 69 6f 6e 20 69 6e 20    expression in 
19a0: 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
19b0: 66 20 61 20 53 45 4c 45 43 54 2c 20 61 6e 64 0d  f a SELECT, and.
19c0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 48 69  .        ///  Hi
19d0: 64 64 65 6e 20 63 6f 6c 75 6d 6e 73 20 61 72 65  dden columns are
19e0: 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 6e   not included in
19f0: 20 74 68 65 20 69 6d 70 6c 69 63 69 74 20 63 6f   the implicit co
1a00: 6c 75 6d 6e 2d 6c 69 73 74 20 0d 0a 20 20 20 20  lumn-list ..    
1a10: 20 20 20 20 2f 2f 2f 20 20 20 20 20 20 75 73 65      ///      use
1a20: 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 20 73  d by an INSERT s
1a30: 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6c 61  tatement that la
1a40: 63 6b 73 20 61 6e 20 65 78 70 6c 69 63 69 74 20  cks an explicit 
1a50: 63 6f 6c 75 6d 6e 2d 6c 69 73 74 2e 20 0d 0a 20  column-list. .. 
1a60: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
1a70: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
1a80: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
1a90: 2f 2f 2f 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  /// For example,
1aa0: 20 69 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   if the followin
1ab0: 67 20 53 51 4c 20 69 73 20 70 61 73 73 65 64 20  g SQL is passed 
1ac0: 74 6f 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61  to sqlite3_decla
1ad0: 72 65 5f 76 74 61 62 28 29 3a 0d 0a 20 20 20 20  re_vtab():..    
1ae0: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
1af0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
1b00: 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20  ra><code>..     
1b10: 20 20 20 2f 2f 2f 20 20 20 20 43 52 45 41 54 45     ///    CREATE
1b20: 20 54 41 42 4c 45 20 78 28 61 20 48 49 44 44 45   TABLE x(a HIDDE
1b30: 4e 20 56 41 52 43 48 41 52 28 31 32 29 2c 20 62  N VARCHAR(12), b
1b40: 20 49 4e 54 45 47 45 52 2c 20 63 20 49 4e 54 45   INTEGER, c INTE
1b50: 47 45 52 20 48 69 64 64 65 6e 29 3b 0d 0a 20 20  GER Hidden);..  
1b60: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65        /// </code
1b70: 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  ></para>..      
1b80: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
1b90: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 6e 20 74        /// Then t
1ba0: 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
1bb0: 20 77 6f 75 6c 64 20 62 65 20 63 72 65 61 74 65   would be create
1bc0: 64 20 77 69 74 68 20 74 77 6f 20 68 69 64 64 65  d with two hidde
1bd0: 6e 20 63 6f 6c 75 6d 6e 73 2c 0d 0a 20 20 20 20  n columns,..    
1be0: 20 20 20 20 2f 2f 2f 20 61 6e 64 20 77 69 74 68      /// and with
1bf0: 20 64 61 74 61 74 79 70 65 73 20 6f 66 20 22 56   datatypes of "V
1c00: 41 52 43 48 41 52 28 31 32 29 22 20 61 6e 64 20  ARCHAR(12)" and 
1c10: 22 49 4e 54 45 47 45 52 22 2e 0d 0a 20 20 20 20  "INTEGER"...    
1c20: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
1c30: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
1c40: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
1c50: 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20   An example use 
1c60: 6f 66 20 68 69 64 64 65 6e 20 63 6f 6c 75 6d 6e  of hidden column
1c70: 73 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e  s can be seen in
1c80: 20 74 68 65 20 46 54 53 33 20 76 69 72 74 75 61   the FTS3 virtua
1c90: 6c 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  l ..        /// 
1ca0: 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
1cb0: 74 69 6f 6e 2c 20 77 68 65 72 65 20 65 76 65 72  tion, where ever
1cc0: 79 20 46 54 53 20 76 69 72 74 75 61 6c 20 74 61  y FTS virtual ta
1cd0: 62 6c 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ble..        ///
1ce0: 20 63 6f 6e 74 61 69 6e 73 20 61 6e 20 46 54 53   contains an FTS
1cf0: 20 68 69 64 64 65 6e 20 63 6f 6c 75 6d 6e 20 74   hidden column t
1d00: 68 61 74 20 69 73 20 75 73 65 64 20 74 6f 20 70  hat is used to p
1d10: 61 73 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ass information 
1d20: 66 72 6f 6d 20 74 68 65 0d 0a 20 20 20 20 20 20  from the..      
1d30: 20 20 2f 2f 2f 20 76 69 72 74 75 61 6c 20 74 61    /// virtual ta
1d40: 62 6c 65 20 69 6e 74 6f 20 46 54 53 20 61 75 78  ble into FTS aux
1d50: 69 6c 69 61 72 79 20 66 75 6e 63 74 69 6f 6e 73  iliary functions
1d60: 20 61 6e 64 20 74 6f 20 74 68 65 20 46 54 53 20   and to the FTS 
1d70: 4d 41 54 43 48 20 6f 70 65 72 61 74 6f 72 2e 0d  MATCH operator..
1d80: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
1d90: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
1da0: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
1db0: 20 20 2f 2f 2f 20 41 20 76 69 72 74 75 61 6c 20    /// A virtual 
1dc0: 74 61 62 6c 65 20 74 68 61 74 20 63 6f 6e 74 61  table that conta
1dd0: 69 6e 73 20 68 69 64 64 65 6e 20 63 6f 6c 75 6d  ins hidden colum
1de0: 6e 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c  ns can be used l
1df0: 69 6b 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ike..        ///
1e00: 20 61 20 74 61 62 6c 65 2d 76 61 6c 75 65 64 20   a table-valued 
1e10: 66 75 6e 63 74 69 6f 6e 20 69 6e 20 74 68 65 20  function in the 
1e20: 46 52 4f 4d 20 63 6c 61 75 73 65 20 6f 66 20 61  FROM clause of a
1e30: 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
1e40: 74 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  t...        /// 
1e50: 54 68 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  The arguments to
1e60: 20 74 68 65 20 74 61 62 6c 65 2d 76 61 6c 75 65   the table-value
1e70: 64 20 66 75 6e 63 74 69 6f 6e 20 62 65 63 6f 6d  d function becom
1e80: 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 6f 6e  e constraints on
1e90: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74   ..        /// t
1ea0: 68 65 20 48 49 44 44 45 4e 20 63 6f 6c 75 6d 6e  he HIDDEN column
1eb0: 73 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c  s of the virtual
1ec0: 20 74 61 62 6c 65 2e 0d 0a 20 20 20 20 20 20 20   table...       
1ed0: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
1ee0: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
1ef0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 46 6f  ..        /// Fo
1f00: 72 20 65 78 61 6d 70 6c 65 2c 20 74 68 65 20 22  r example, the "
1f10: 67 65 6e 65 72 61 74 65 5f 73 65 72 69 65 73 22  generate_series"
1f20: 20 65 78 74 65 6e 73 69 6f 6e 20 28 6c 6f 63 61   extension (loca
1f30: 74 65 64 20 69 6e 20 74 68 65 0d 0a 20 20 20 20  ted in the..    
1f40: 20 20 20 20 2f 2f 2f 20 65 78 74 2f 6d 69 73 63      /// ext/misc
1f50: 2f 73 65 72 69 65 73 2e 63 0d 0a 20 20 20 20 20  /series.c..     
1f60: 20 20 20 2f 2f 2f 20 66 69 6c 65 20 69 6e 20 74     /// file in t
1f70: 68 65 20 73 6f 75 72 63 65 20 74 72 65 65 29 0d  he source tree).
1f80: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6d 70  .        /// imp
1f90: 6c 65 6d 65 6e 74 73 20 61 6e 20 65 70 6f 6e 79  lements an epony
1fa0: 6d 6f 75 73 20 76 69 72 74 75 61 6c 20 74 61 62  mous virtual tab
1fb0: 6c 65 20 77 69 74 68 20 74 68 65 20 66 6f 6c 6c  le with the foll
1fc0: 6f 77 69 6e 67 20 73 63 68 65 6d 61 3a 0d 0a 20  owing schema:.. 
1fd0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
1fe0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
1ff0: 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20  <para><code>..  
2000: 20 20 20 20 20 20 2f 2f 2f 20 43 52 45 41 54 45        /// CREATE
2010: 20 54 41 42 4c 45 20 67 65 6e 65 72 61 74 65 5f   TABLE generate_
2020: 73 65 72 69 65 73 28 0d 0a 20 20 20 20 20 20 20  series(..       
2030: 20 2f 2f 2f 20 20 20 76 61 6c 75 65 2c 0d 0a 20   ///   value,.. 
2040: 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 73 74 61         ///   sta
2050: 72 74 20 48 49 44 44 45 4e 2c 0d 0a 20 20 20 20  rt HIDDEN,..    
2060: 20 20 20 20 2f 2f 2f 20 20 20 73 74 6f 70 20 48      ///   stop H
2070: 49 44 44 45 4e 2c 0d 0a 20 20 20 20 20 20 20 20  IDDEN,..        
2080: 2f 2f 2f 20 20 20 73 74 65 70 20 48 49 44 44 45  ///   step HIDDE
2090: 4e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 29  N..        /// )
20a0: 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ;..        /// <
20b0: 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20  /code></para>.. 
20c0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
20d0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54  >..        /// T
20e0: 68 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  he sqlite3_modul
20f0: 65 2e 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74  e.xBestIndex met
2100: 68 6f 64 20 69 6e 20 74 68 65 20 69 6d 70 6c 65  hod in the imple
2110: 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 69  mentation of thi
2120: 73 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74  s..        /// t
2130: 61 62 6c 65 20 63 68 65 63 6b 73 20 66 6f 72 20  able checks for 
2140: 65 71 75 61 6c 69 74 79 20 63 6f 6e 73 74 72 61  equality constra
2150: 69 6e 74 73 20 61 67 61 69 6e 73 74 20 74 68 65  ints against the
2160: 20 48 49 44 44 45 4e 20 63 6f 6c 75 6d 6e 73 2c   HIDDEN columns,
2170: 20 61 6e 64 20 75 73 65 73 0d 0a 20 20 20 20 20   and uses..     
2180: 20 20 20 2f 2f 2f 20 74 68 6f 73 65 20 61 73 20     /// those as 
2190: 69 6e 70 75 74 20 70 61 72 61 6d 65 74 65 72 73  input parameters
21a0: 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68   to determine th
21b0: 65 20 72 61 6e 67 65 20 6f 66 20 69 6e 74 65 67  e range of integ
21c0: 65 72 20 22 76 61 6c 75 65 22 20 6f 75 74 70 75  er "value" outpu
21d0: 74 73 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ts..        /// 
21e0: 74 6f 20 67 65 6e 65 72 61 74 65 2e 20 20 52 65  to generate.  Re
21f0: 61 73 6f 6e 61 62 6c 65 20 64 65 66 61 75 6c 74  asonable default
2200: 73 20 61 72 65 20 75 73 65 64 20 66 6f 72 20 61  s are used for a
2210: 6e 79 20 75 6e 63 6f 6e 73 74 72 61 69 6e 65 64  ny unconstrained
2220: 20 63 6f 6c 75 6d 6e 73 2e 0d 0a 20 20 20 20 20   columns...     
2230: 20 20 20 2f 2f 2f 20 46 6f 72 20 65 78 61 6d 70     /// For examp
2240: 6c 65 2c 20 74 6f 20 6c 69 73 74 20 61 6c 6c 20  le, to list all 
2250: 69 6e 74 65 67 65 72 73 20 62 65 74 77 65 65 6e  integers between
2260: 20 35 20 61 6e 64 20 35 30 3a 0d 0a 20 20 20 20   5 and 50:..    
2270: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
2280: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
2290: 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20  ra><code>..     
22a0: 20 20 20 2f 2f 2f 20 53 45 4c 45 43 54 20 76 61     /// SELECT va
22b0: 6c 75 65 20 46 52 4f 4d 20 67 65 6e 65 72 61 74  lue FROM generat
22c0: 65 5f 73 65 72 69 65 73 28 35 2c 35 30 29 3b 0d  e_series(5,50);.
22d0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63  .        /// </c
22e0: 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  ode></para>..   
22f0: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
2300: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65  .        /// The
2310: 20 70 72 65 76 69 6f 75 73 20 71 75 65 72 79 20   previous query 
2320: 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
2330: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 3a 0d   the following:.
2340: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
2350: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
2360: 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a  / <para><code>..
2370: 20 20 20 20 20 20 20 20 2f 2f 2f 20 53 45 4c 45          /// SELE
2380: 43 54 20 76 61 6c 75 65 20 46 52 4f 4d 20 67 65  CT value FROM ge
2390: 6e 65 72 61 74 65 5f 73 65 72 69 65 73 20 57 48  nerate_series WH
23a0: 45 52 45 20 73 74 61 72 74 3d 35 20 41 4e 44 20  ERE start=5 AND 
23b0: 73 74 6f 70 3d 35 30 3b 0d 0a 20 20 20 20 20 20  stop=50;..      
23c0: 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70    /// </code></p
23d0: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
23e0: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
23f0: 20 20 2f 2f 2f 20 41 72 67 75 6d 65 6e 74 73 20    /// Arguments 
2400: 6f 6e 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  on the virtual t
2410: 61 62 6c 65 20 6e 61 6d 65 20 61 72 65 20 6d 61  able name are ma
2420: 74 63 68 65 64 20 74 6f 20 68 69 64 64 65 6e 20  tched to hidden 
2430: 63 6f 6c 75 6d 6e 73 0d 0a 20 20 20 20 20 20 20  columns..       
2440: 20 2f 2f 2f 20 69 6e 20 6f 72 64 65 72 2e 20 20   /// in order.  
2450: 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  The number of ar
2460: 67 75 6d 65 6e 74 73 20 63 61 6e 20 62 65 20 6c  guments can be l
2470: 65 73 73 20 74 68 61 6e 20 74 68 65 0d 0a 20 20  ess than the..  
2480: 20 20 20 20 20 20 2f 2f 2f 20 6e 75 6d 62 65 72        /// number
2490: 20 6f 66 20 68 69 64 64 65 6e 20 63 6f 6c 75 6d   of hidden colum
24a0: 6e 73 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73  ns, in which cas
24b0: 65 20 74 68 65 20 6c 61 74 74 65 72 20 68 69 64  e the latter hid
24c0: 64 65 6e 20 63 6f 6c 75 6d 6e 73 20 61 72 65 0d  den columns are.
24d0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 75 6e 63  .        /// unc
24e0: 6f 6e 73 74 72 61 69 6e 65 64 2e 20 20 48 6f 77  onstrained.  How
24f0: 65 76 65 72 2c 20 61 6e 20 65 72 72 6f 72 20 72  ever, an error r
2500: 65 73 75 6c 74 73 20 69 66 20 74 68 65 72 65 20  esults if there 
2510: 61 72 65 20 6d 6f 72 65 20 61 72 67 75 6d 65 6e  are more argumen
2520: 74 73 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ts..        /// 
2530: 74 68 61 6e 20 74 68 65 72 65 20 61 72 65 20 68  than there are h
2540: 69 64 64 65 6e 20 63 6f 6c 75 6d 6e 73 20 69 6e  idden columns in
2550: 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
2560: 6c 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  le...        ///
2570: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
2580: 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e    /// </summary>
2590: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
25a0: 61 72 61 6d 20 6e 61 6d 65 3d 22 70 44 62 22 3e  aram name="pDb">
25b0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
25c0: 65 20 6e 61 74 69 76 65 20 64 61 74 61 62 61 73  e native databas
25d0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e  e connection han
25e0: 64 6c 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  dle...        //
25f0: 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20  / </param>..    
2600: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e      /// <param n
2610: 61 6d 65 3d 22 70 41 75 78 22 3e 0d 0a 20 20 20  ame="pAux">..   
2620: 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 6f 72 69       /// The ori
2630: 67 69 6e 61 6c 20 6e 61 74 69 76 65 20 70 6f 69  ginal native poi
2640: 6e 74 65 72 20 76 61 6c 75 65 20 74 68 61 74 20  nter value that 
2650: 77 61 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20  was provided to 
2660: 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  the..        ///
2670: 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2680: 6d 6f 64 75 6c 65 28 29 2c 20 73 71 6c 69 74 65  module(), sqlite
2690: 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f  3_create_module_
26a0: 76 32 28 29 20 6f 72 0d 0a 20 20 20 20 20 20 20  v2() or..       
26b0: 20 2f 2f 2f 20 73 71 6c 69 74 65 33 5f 63 72 65   /// sqlite3_cre
26c0: 61 74 65 5f 64 69 73 70 6f 73 61 62 6c 65 5f 6d  ate_disposable_m
26d0: 6f 64 75 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  odule() function
26e0: 73 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  s...        /// 
26f0: 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20  </param>..      
2700: 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d    /// <param nam
2710: 65 3d 22 61 72 67 63 22 3e 0d 0a 20 20 20 20 20  e="argc">..     
2720: 20 20 20 2f 2f 2f 20 54 68 65 20 6e 75 6d 62 65     /// The numbe
2730: 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 66  r of arguments f
2740: 72 6f 6d 20 74 68 65 20 43 52 45 41 54 45 20 56  rom the CREATE V
2750: 49 52 54 55 41 4c 20 54 41 42 4c 45 20 73 74 61  IRTUAL TABLE sta
2760: 74 65 6d 65 6e 74 2e 0d 0a 20 20 20 20 20 20 20  tement...       
2770: 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20   /// </param>.. 
2780: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
2790: 6d 20 6e 61 6d 65 3d 22 61 72 67 76 22 3e 0d 0a  m name="argv">..
27a0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20          /// The 
27b0: 61 72 72 61 79 20 6f 66 20 73 74 72 69 6e 67 20  array of string 
27c0: 61 72 67 75 6d 65 6e 74 73 20 66 72 6f 6d 20 74  arguments from t
27d0: 68 65 20 43 52 45 41 54 45 20 56 49 52 54 55 41  he CREATE VIRTUA
27e0: 4c 20 54 41 42 4c 45 0d 0a 20 20 20 20 20 20 20  L TABLE..       
27f0: 20 2f 2f 2f 20 73 74 61 74 65 6d 65 6e 74 2e 0d   /// statement..
2800: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
2810: 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f  aram>..        /
2820: 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22  // <param name="
2830: 70 56 74 61 62 22 3e 0d 0a 20 20 20 20 20 20 20  pVtab">..       
2840: 20 2f 2f 2f 20 55 70 6f 6e 20 73 75 63 63 65 73   /// Upon succes
2850: 73 2c 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  s, this paramete
2860: 72 20 6d 75 73 74 20 62 65 20 6d 6f 64 69 66 69  r must be modifi
2870: 65 64 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74  ed to point to t
2880: 68 65 20 6e 65 77 6c 79 0d 0a 20 20 20 20 20 20  he newly..      
2890: 20 20 2f 2f 2f 20 63 72 65 61 74 65 64 20 6e 61    /// created na
28a0: 74 69 76 65 20 73 71 6c 69 74 65 33 5f 76 74 61  tive sqlite3_vta
28b0: 62 20 64 65 72 69 76 65 64 20 73 74 72 75 63 74  b derived struct
28c0: 75 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ure...        //
28d0: 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20  / </param>..    
28e0: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e      /// <param n
28f0: 61 6d 65 3d 22 70 45 72 72 6f 72 22 3e 0d 0a 20  ame="pError">.. 
2900: 20 20 20 20 20 20 20 2f 2f 2f 20 55 70 6f 6e 20         /// Upon 
2910: 66 61 69 6c 75 72 65 2c 20 74 68 69 73 20 70 61  failure, this pa
2920: 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20  rameter must be 
2930: 6d 6f 64 69 66 69 65 64 20 74 6f 20 70 6f 69 6e  modified to poin
2940: 74 20 74 6f 20 74 68 65 20 65 72 72 6f 72 0d 0a  t to the error..
2950: 20 20 20 20 20 20 20 20 2f 2f 2f 20 6d 65 73 73          /// mess
2960: 61 67 65 2c 20 77 69 74 68 20 74 68 65 20 75 6e  age, with the un
2970: 64 65 72 6c 79 69 6e 67 20 6d 65 6d 6f 72 79 20  derlying memory 
2980: 68 61 76 69 6e 67 20 62 65 65 6e 20 6f 62 74 61  having been obta
2990: 69 6e 65 64 20 66 72 6f 6d 20 74 68 65 0d 0a 20  ined from the.. 
29a0: 20 20 20 20 20 20 20 2f 2f 2f 20 73 71 6c 69 74         /// sqlit
29b0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 75 6e 63  e3_malloc() func
29c0: 74 69 6f 6e 2e 0d 0a 20 20 20 20 20 20 20 20 2f  tion...        /
29d0: 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20  // </param>..   
29e0: 20 20 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72 6e       /// <return
29f0: 73 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  s>..        /// 
2a00: 41 20 73 74 61 6e 64 61 72 64 20 53 51 4c 69 74  A standard SQLit
2a10: 65 20 72 65 74 75 72 6e 20 63 6f 64 65 2e 0d 0a  e return code...
2a20: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72 65          /// </re
2a30: 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20  turns>..        
2a40: 53 51 4c 69 74 65 45 72 72 6f 72 43 6f 64 65 20  SQLiteErrorCode 
2a50: 78 43 72 65 61 74 65 28 0d 0a 20 20 20 20 20 20  xCreate(..      
2a60: 20 20 20 20 20 20 49 6e 74 50 74 72 20 70 44 62        IntPtr pDb
2a70: 2c 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 49  ,..            I
2a80: 6e 74 50 74 72 20 70 41 75 78 2c 0d 0a 20 20 20  ntPtr pAux,..   
2a90: 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
2aa0: 63 2c 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20  c,..            
2ab0: 49 6e 74 50 74 72 20 61 72 67 76 2c 0d 0a 20 20  IntPtr argv,..  
2ac0: 20 20 20 20 20 20 20 20 20 20 72 65 66 20 49 6e            ref In
2ad0: 74 50 74 72 20 70 56 74 61 62 2c 0d 0a 20 20 20  tPtr pVtab,..   
2ae0: 20 20 20 20 20 20 20 20 20 72 65 66 20 49 6e 74           ref Int
2af0: 50 74 72 20 70 45 72 72 6f 72 0d 0a 20 20 20 20  Ptr pError..    
2b00: 20 20 20 20 20 20 20 20 29 3b 0d 0a 0d 0a 20 20          );....  
2b10: 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f        //////////
2b20: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
2b30: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
2b40: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
2b50: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d  /////////////...
2b60: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 73 75  .        /// <su
2b70: 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20  mmary>..        
2b80: 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e  /// <para><code>
2b90: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20  ..        ///   
2ba0: 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29 28  int (*xConnect)(
2bb0: 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a  sqlite3*, void *
2bc0: 70 41 75 78 2c 0d 0a 20 20 20 20 20 20 20 20 2f  pAux,..        /
2bd0: 2f 2f 20 20 20 20 20 20 20 20 20 20 20 20 20 20  //              
2be0: 20 20 69 6e 74 20 61 72 67 63 2c 20 63 68 61 72    int argc, char
2bf0: 20 2a 2a 61 72 67 76 2c 0d 0a 20 20 20 20 20 20   **argv,..      
2c00: 20 20 2f 2f 2f 20 20 20 20 20 20 20 20 20 20 20    ///           
2c10: 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61       sqlite3_vta
2c20: 62 20 2a 2a 70 70 56 54 61 62 2c 0d 0a 20 20 20  b **ppVTab,..   
2c30: 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 20 20 20       ///        
2c40: 20 20 20 20 20 20 20 20 63 68 61 72 20 2a 2a 70          char **p
2c50: 7a 45 72 72 29 3b 0d 0a 20 20 20 20 20 20 20 20  zErr);..        
2c60: 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72  /// </code></par
2c70: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
2c80: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
2c90: 2f 2f 2f 20 54 68 65 20 78 43 6f 6e 6e 65 63 74  /// The xConnect
2ca0: 20 6d 65 74 68 6f 64 20 69 73 20 76 65 72 79 20   method is very 
2cb0: 73 69 6d 69 6c 61 72 20 74 6f 20 78 43 72 65 61  similar to xCrea
2cc0: 74 65 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  te. ..        //
2cd0: 2f 20 49 74 20 68 61 73 20 74 68 65 20 73 61 6d  / It has the sam
2ce0: 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64  e parameters and
2cf0: 20 63 6f 6e 73 74 72 75 63 74 73 20 61 20 6e 65   constructs a ne
2d00: 77 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 73  w sqlite3_vtab s
2d10: 74 72 75 63 74 75 72 65 20 0d 0a 20 20 20 20 20  tructure ..     
2d20: 20 20 20 2f 2f 2f 20 6a 75 73 74 20 6c 69 6b 65     /// just like
2d30: 20 78 43 72 65 61 74 65 2e 20 0d 0a 20 20 20 20   xCreate. ..    
2d40: 20 20 20 20 2f 2f 2f 20 41 6e 64 20 69 74 20 6d      /// And it m
2d50: 75 73 74 20 61 6c 73 6f 20 63 61 6c 6c 20 73 71  ust also call sq
2d60: 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74  lite3_declare_vt
2d70: 61 62 28 29 20 6c 69 6b 65 20 78 43 72 65 61 74  ab() like xCreat
2d80: 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e...        /// 
2d90: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
2da0: 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20   /// <para>..   
2db0: 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 64 69 66       /// The dif
2dc0: 66 65 72 65 6e 63 65 20 69 73 20 74 68 61 74 20  ference is that 
2dd0: 78 43 6f 6e 6e 65 63 74 20 69 73 20 63 61 6c 6c  xConnect is call
2de0: 65 64 20 74 6f 20 65 73 74 61 62 6c 69 73 68 20  ed to establish 
2df0: 61 20 6e 65 77 20 0d 0a 20 20 20 20 20 20 20 20  a new ..        
2e00: 2f 2f 2f 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  /// connection t
2e10: 6f 20 61 6e 20 65 78 69 73 74 69 6e 67 20 76 69  o an existing vi
2e20: 72 74 75 61 6c 20 74 61 62 6c 65 20 77 68 65 72  rtual table wher
2e30: 65 61 73 20 78 43 72 65 61 74 65 20 69 73 20 63  eas xCreate is c
2e40: 61 6c 6c 65 64 20 0d 0a 20 20 20 20 20 20 20 20  alled ..        
2e50: 2f 2f 2f 20 74 6f 20 63 72 65 61 74 65 20 61 20  /// to create a 
2e60: 6e 65 77 20 76 69 72 74 75 61 6c 20 74 61 62 6c  new virtual tabl
2e70: 65 20 66 72 6f 6d 20 73 63 72 61 74 63 68 2e 0d  e from scratch..
2e80: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
2e90: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
2ea0: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
2eb0: 20 20 2f 2f 2f 20 54 68 65 20 78 43 72 65 61 74    /// The xCreat
2ec0: 65 20 61 6e 64 20 78 43 6f 6e 6e 65 63 74 20 6d  e and xConnect m
2ed0: 65 74 68 6f 64 73 20 61 72 65 20 6f 6e 6c 79 20  ethods are only 
2ee0: 64 69 66 66 65 72 65 6e 74 20 77 68 65 6e 20 74  different when t
2ef0: 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  he..        /// 
2f00: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 68 61  virtual table ha
2f10: 73 20 73 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 62  s some kind of b
2f20: 61 63 6b 69 6e 67 20 73 74 6f 72 65 20 74 68 61  acking store tha
2f30: 74 20 6d 75 73 74 20 62 65 20 69 6e 69 74 69 61  t must be initia
2f40: 6c 69 7a 65 64 20 0d 0a 20 20 20 20 20 20 20 20  lized ..        
2f50: 2f 2f 2f 20 74 68 65 20 66 69 72 73 74 20 74 69  /// the first ti
2f60: 6d 65 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  me the virtual t
2f70: 61 62 6c 65 20 69 73 20 63 72 65 61 74 65 64 2e  able is created.
2f80: 20 54 68 65 20 78 43 72 65 61 74 65 20 6d 65 74   The xCreate met
2f90: 68 6f 64 20 63 72 65 61 74 65 73 20 0d 0a 20 20  hod creates ..  
2fa0: 20 20 20 20 20 20 2f 2f 2f 20 61 6e 64 20 69 6e        /// and in
2fb0: 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 62 61  itializes the ba
2fc0: 63 6b 69 6e 67 20 73 74 6f 72 65 2e 20 54 68 65  cking store. The
2fd0: 20 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64   xConnect method
2fe0: 20 6a 75 73 74 20 63 6f 6e 6e 65 63 74 73 20 0d   just connects .
2ff0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 6f 20  .        /// to 
3000: 61 6e 20 65 78 69 73 74 69 6e 67 20 62 61 63 6b  an existing back
3010: 69 6e 67 20 73 74 6f 72 65 2e 20 20 57 68 65 6e  ing store.  When
3020: 20 78 43 72 65 61 74 65 20 61 6e 64 20 78 43 6f   xCreate and xCo
3030: 6e 6e 65 63 74 20 61 72 65 20 74 68 65 20 73 61  nnect are the sa
3040: 6d 65 2c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  me,..        ///
3050: 20 74 68 65 20 74 61 62 6c 65 20 69 73 20 61 6e   the table is an
3060: 20 65 70 6f 6e 79 6d 6f 75 73 20 76 69 72 74 75   eponymous virtu
3070: 61 6c 20 74 61 62 6c 65 2e 0d 0a 20 20 20 20 20  al table...     
3080: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a     /// </para>..
3090: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
30a0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
30b0: 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 2c 20 63  As an example, c
30c0: 6f 6e 73 69 64 65 72 20 61 20 76 69 72 74 75 61  onsider a virtua
30d0: 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  l table implemen
30e0: 74 61 74 69 6f 6e 20 74 68 61 74 20 0d 0a 20 20  tation that ..  
30f0: 20 20 20 20 20 20 2f 2f 2f 20 70 72 6f 76 69 64        /// provid
3100: 65 73 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63  es read-only acc
3110: 65 73 73 20 74 6f 20 65 78 69 73 74 69 6e 67 20  ess to existing 
3120: 63 6f 6d 6d 61 2d 73 65 70 61 72 61 74 65 64 2d  comma-separated-
3130: 76 61 6c 75 65 20 28 43 53 56 29 0d 0a 20 20 20  value (CSV)..   
3140: 20 20 20 20 20 2f 2f 2f 20 66 69 6c 65 73 20 6f       /// files o
3150: 6e 20 64 69 73 6b 2e 20 54 68 65 72 65 20 69 73  n disk. There is
3160: 20 6e 6f 20 62 61 63 6b 69 6e 67 20 73 74 6f 72   no backing stor
3170: 65 20 74 68 61 74 20 6e 65 65 64 73 20 74 6f 20  e that needs to 
3180: 62 65 20 63 72 65 61 74 65 64 20 0d 0a 20 20 20  be created ..   
3190: 20 20 20 20 20 2f 2f 2f 20 6f 72 20 69 6e 69 74       /// or init
31a0: 69 61 6c 69 7a 65 64 20 66 6f 72 20 73 75 63 68  ialized for such
31b0: 20 61 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65   a virtual table
31c0: 20 28 73 69 6e 63 65 20 74 68 65 20 43 53 56 20   (since the CSV 
31d0: 66 69 6c 65 73 20 61 6c 72 65 61 64 79 20 0d 0a  files already ..
31e0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 65 78 69 73          /// exis
31f0: 74 20 6f 6e 20 64 69 73 6b 29 20 73 6f 20 74 68  t on disk) so th
3200: 65 20 78 43 72 65 61 74 65 20 61 6e 64 20 78 43  e xCreate and xC
3210: 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64 73 20 77  onnect methods w
3220: 69 6c 6c 20 62 65 20 69 64 65 6e 74 69 63 61 6c  ill be identical
3230: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 66   ..        /// f
3240: 6f 72 20 74 68 61 74 20 6d 6f 64 75 6c 65 2e 0d  or that module..
3250: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
3260: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
3270: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
3280: 20 20 2f 2f 2f 20 41 6e 6f 74 68 65 72 20 65 78    /// Another ex
3290: 61 6d 70 6c 65 20 69 73 20 61 20 76 69 72 74 75  ample is a virtu
32a0: 61 6c 20 74 61 62 6c 65 20 74 68 61 74 20 69 6d  al table that im
32b0: 70 6c 65 6d 65 6e 74 73 20 61 20 66 75 6c 6c 2d  plements a full-
32c0: 74 65 78 74 20 69 6e 64 65 78 2e 20 0d 0a 20 20  text index. ..  
32d0: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 43        /// The xC
32e0: 72 65 61 74 65 20 6d 65 74 68 6f 64 20 6d 75 73  reate method mus
32f0: 74 20 63 72 65 61 74 65 20 61 6e 64 20 69 6e 69  t create and ini
3300: 74 69 61 6c 69 7a 65 20 64 61 74 61 20 73 74 72  tialize data str
3310: 75 63 74 75 72 65 73 20 74 6f 20 68 6f 6c 64 20  uctures to hold 
3320: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68  ..        /// th
3330: 65 20 64 69 63 74 69 6f 6e 61 72 79 20 61 6e 64  e dictionary and
3340: 20 70 6f 73 74 69 6e 67 20 6c 69 73 74 73 20 66   posting lists f
3350: 6f 72 20 74 68 61 74 20 69 6e 64 65 78 2e 20 54  or that index. T
3360: 68 65 20 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68  he xConnect meth
3370: 6f 64 2c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  od,..        ///
3380: 20 6f 6e 20 74 68 65 20 6f 74 68 65 72 20 68 61   on the other ha
3390: 6e 64 2c 20 6f 6e 6c 79 20 68 61 73 20 74 6f 20  nd, only has to 
33a0: 6c 6f 63 61 74 65 20 61 6e 64 20 75 73 65 20 61  locate and use a
33b0: 6e 20 65 78 69 73 74 69 6e 67 20 64 69 63 74 69  n existing dicti
33c0: 6f 6e 61 72 79 20 0d 0a 20 20 20 20 20 20 20 20  onary ..        
33d0: 2f 2f 2f 20 61 6e 64 20 70 6f 73 74 69 6e 67 20  /// and posting 
33e0: 6c 69 73 74 73 20 74 68 61 74 20 77 65 72 65 20  lists that were 
33f0: 63 72 65 61 74 65 64 20 62 79 20 61 20 70 72 69  created by a pri
3400: 6f 72 20 78 43 72 65 61 74 65 20 63 61 6c 6c 2e  or xCreate call.
3410: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
3420: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
3430: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20  // <para>..     
3440: 20 20 20 2f 2f 2f 20 54 68 65 20 78 43 6f 6e 6e     /// The xConn
3450: 65 63 74 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  ect method must 
3460: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
3470: 20 69 66 20 69 74 20 69 73 20 73 75 63 63 65 73   if it is succes
3480: 73 66 75 6c 20 0d 0a 20 20 20 20 20 20 20 20 2f  sful ..        /
3490: 2f 2f 20 69 6e 20 63 72 65 61 74 69 6e 67 20 74  // in creating t
34a0: 68 65 20 6e 65 77 20 76 69 72 74 75 61 6c 20 74  he new virtual t
34b0: 61 62 6c 65 2c 20 6f 72 20 53 51 4c 49 54 45 5f  able, or SQLITE_
34c0: 45 52 52 4f 52 20 69 66 20 69 74 20 69 73 20 6e  ERROR if it is n
34d0: 6f 74 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ot ..        ///
34e0: 20 73 75 63 63 65 73 73 66 75 6c 2e 20 49 66 20   successful. If 
34f0: 6e 6f 74 20 73 75 63 63 65 73 73 66 75 6c 2c 20  not successful, 
3500: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 74 61 62  the sqlite3_vtab
3510: 20 73 74 72 75 63 74 75 72 65 20 6d 75 73 74 20   structure must 
3520: 6e 6f 74 20 62 65 20 0d 0a 20 20 20 20 20 20 20  not be ..       
3530: 20 2f 2f 2f 20 61 6c 6c 6f 63 61 74 65 64 2e 20   /// allocated. 
3540: 41 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  An error message
3550: 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20   may optionally 
3560: 62 65 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a  be returned in *
3570: 70 7a 45 72 72 20 69 66 20 0d 0a 20 20 20 20 20  pzErr if ..     
3580: 20 20 20 2f 2f 2f 20 75 6e 73 75 63 63 65 73 73     /// unsuccess
3590: 66 75 6c 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f  ful. ..        /
35a0: 2f 2f 20 53 70 61 63 65 20 74 6f 20 68 6f 6c 64  // Space to hold
35b0: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
35c0: 67 65 20 73 74 72 69 6e 67 20 6d 75 73 74 20 62  ge string must b
35d0: 65 20 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e  e allocated usin
35e0: 67 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 61  g..        /// a
35f0: 6e 20 53 51 4c 69 74 65 20 6d 65 6d 6f 72 79 20  n SQLite memory 
3600: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74  allocation funct
3610: 69 6f 6e 20 6c 69 6b 65 20 0d 0a 20 20 20 20 20  ion like ..     
3620: 20 20 20 2f 2f 2f 20 73 71 6c 69 74 65 33 5f 6d     /// sqlite3_m
3630: 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
3640: 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 73 20  e3_mprintf() as 
3650: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  the SQLite core 
3660: 77 69 6c 6c 0d 0a 20 20 20 20 20 20 20 20 2f 2f  will..        //
3670: 2f 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65  / attempt to fre
3680: 65 20 74 68 65 20 73 70 61 63 65 20 75 73 69 6e  e the space usin
3690: 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  g sqlite3_free()
36a0: 20 61 66 74 65 72 20 74 68 65 20 65 72 72 6f 72   after the error
36b0: 20 68 61 73 0d 0a 20 20 20 20 20 20 20 20 2f 2f   has..        //
36c0: 2f 20 62 65 65 6e 20 72 65 70 6f 72 74 65 64 20  / been reported 
36d0: 75 70 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  up to the applic
36e0: 61 74 69 6f 6e 2e 0d 0a 20 20 20 20 20 20 20 20  ation...        
36f0: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
3700: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
3710: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65  .        /// The
3720: 20 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64   xConnect method
3730: 20 69 73 20 72 65 71 75 69 72 65 64 20 66 6f 72   is required for
3740: 20 65 76 65 72 79 20 76 69 72 74 75 61 6c 20 74   every virtual t
3750: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
3760: 69 6f 6e 2c 20 0d 0a 20 20 20 20 20 20 20 20 2f  ion, ..        /
3770: 2f 2f 20 74 68 6f 75 67 68 20 74 68 65 20 78 43  // though the xC
3780: 72 65 61 74 65 20 61 6e 64 20 78 43 6f 6e 6e 65  reate and xConne
3790: 63 74 20 70 6f 69 6e 74 65 72 73 20 6f 66 20 74  ct pointers of t
37a0: 68 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  he sqlite3_modul
37b0: 65 20 6f 62 6a 65 63 74 0d 0a 20 20 20 20 20 20  e object..      
37c0: 20 20 2f 2f 2f 20 6d 61 79 20 70 6f 69 6e 74 20    /// may point 
37d0: 74 6f 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  to the same func
37e0: 74 69 6f 6e 20 69 66 20 74 68 65 20 76 69 72 74  tion if the virt
37f0: 75 61 6c 20 74 61 62 6c 65 20 64 6f 65 73 20 6e  ual table does n
3800: 6f 74 20 6e 65 65 64 20 74 6f 0d 0a 20 20 20 20  ot need to..    
3810: 20 20 20 20 2f 2f 2f 20 69 6e 69 74 69 61 6c 69      /// initiali
3820: 7a 65 20 62 61 63 6b 69 6e 67 20 73 74 6f 72 65  ze backing store
3830: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
3840: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
3850: 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a  /// </summary>..
3860: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
3870: 61 6d 20 6e 61 6d 65 3d 22 70 44 62 22 3e 0d 0a  am name="pDb">..
3880: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20          /// The 
3890: 6e 61 74 69 76 65 20 64 61 74 61 62 61 73 65 20  native database 
38a0: 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c  connection handl
38b0: 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e...        /// 
38c0: 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20  </param>..      
38d0: 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d    /// <param nam
38e0: 65 3d 22 70 41 75 78 22 3e 0d 0a 20 20 20 20 20  e="pAux">..     
38f0: 20 20 20 2f 2f 2f 20 54 68 65 20 6f 72 69 67 69     /// The origi
3900: 6e 61 6c 20 6e 61 74 69 76 65 20 70 6f 69 6e 74  nal native point
3910: 65 72 20 76 61 6c 75 65 20 74 68 61 74 20 77 61  er value that wa
3920: 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74 68  s provided to th
3930: 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73  e..        /// s
3940: 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
3950: 64 75 6c 65 28 29 2c 20 73 71 6c 69 74 65 33 5f  dule(), sqlite3_
3960: 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32  create_module_v2
3970: 28 29 20 6f 72 0d 0a 20 20 20 20 20 20 20 20 2f  () or..        /
3980: 2f 2f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  // sqlite3_creat
3990: 65 5f 64 69 73 70 6f 73 61 62 6c 65 5f 6d 6f 64  e_disposable_mod
39a0: 75 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 2e  ule() functions.
39b0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
39c0: 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20  param>..        
39d0: 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d  /// <param name=
39e0: 22 61 72 67 63 22 3e 0d 0a 20 20 20 20 20 20 20  "argc">..       
39f0: 20 2f 2f 2f 20 54 68 65 20 6e 75 6d 62 65 72 20   /// The number 
3a00: 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 66 72 6f  of arguments fro
3a10: 6d 20 74 68 65 20 43 52 45 41 54 45 20 56 49 52  m the CREATE VIR
3a20: 54 55 41 4c 20 54 41 42 4c 45 20 73 74 61 74 65  TUAL TABLE state
3a30: 6d 65 6e 74 2e 0d 0a 20 20 20 20 20 20 20 20 2f  ment...        /
3a40: 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20  // </param>..   
3a50: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20       /// <param 
3a60: 6e 61 6d 65 3d 22 61 72 67 76 22 3e 0d 0a 20 20  name="argv">..  
3a70: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 61 72        /// The ar
3a80: 72 61 79 20 6f 66 20 73 74 72 69 6e 67 20 61 72  ray of string ar
3a90: 67 75 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 65  guments from the
3aa0: 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20   CREATE VIRTUAL 
3ab0: 54 41 42 4c 45 0d 0a 20 20 20 20 20 20 20 20 2f  TABLE..        /
3ac0: 2f 2f 20 73 74 61 74 65 6d 65 6e 74 2e 0d 0a 20  // statement... 
3ad0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
3ae0: 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  am>..        ///
3af0: 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 56   <param name="pV
3b00: 74 61 62 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f  tab">..        /
3b10: 2f 2f 20 55 70 6f 6e 20 73 75 63 63 65 73 73 2c  // Upon success,
3b20: 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
3b30: 6d 75 73 74 20 62 65 20 6d 6f 64 69 66 69 65 64  must be modified
3b40: 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65   to point to the
3b50: 20 6e 65 77 6c 79 0d 0a 20 20 20 20 20 20 20 20   newly..        
3b60: 2f 2f 2f 20 63 72 65 61 74 65 64 20 6e 61 74 69  /// created nati
3b70: 76 65 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20  ve sqlite3_vtab 
3b80: 64 65 72 69 76 65 64 20 73 74 72 75 63 74 75 72  derived structur
3b90: 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e...        /// 
3ba0: 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20  </param>..      
3bb0: 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d    /// <param nam
3bc0: 65 3d 22 70 45 72 72 6f 72 22 3e 0d 0a 20 20 20  e="pError">..   
3bd0: 20 20 20 20 20 2f 2f 2f 20 55 70 6f 6e 20 66 61       /// Upon fa
3be0: 69 6c 75 72 65 2c 20 74 68 69 73 20 70 61 72 61  ilure, this para
3bf0: 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 6d 6f  meter must be mo
3c00: 64 69 66 69 65 64 20 74 6f 20 70 6f 69 6e 74 20  dified to point 
3c10: 74 6f 20 74 68 65 20 65 72 72 6f 72 0d 0a 20 20  to the error..  
3c20: 20 20 20 20 20 20 2f 2f 2f 20 6d 65 73 73 61 67        /// messag
3c30: 65 2c 20 77 69 74 68 20 74 68 65 20 75 6e 64 65  e, with the unde
3c40: 72 6c 79 69 6e 67 20 6d 65 6d 6f 72 79 20 68 61  rlying memory ha
3c50: 76 69 6e 67 20 62 65 65 6e 20 6f 62 74 61 69 6e  ving been obtain
3c60: 65 64 20 66 72 6f 6d 20 74 68 65 0d 0a 20 20 20  ed from the..   
3c70: 20 20 20 20 20 2f 2f 2f 20 73 71 6c 69 74 65 33       /// sqlite3
3c80: 5f 6d 61 6c 6c 6f 63 28 29 20 66 75 6e 63 74 69  _malloc() functi
3c90: 6f 6e 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  on...        ///
3ca0: 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20   </param>..     
3cb0: 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72 6e 73 3e     /// <returns>
3cc0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 20  ..        /// A 
3cd0: 73 74 61 6e 64 61 72 64 20 53 51 4c 69 74 65 20  standard SQLite 
3ce0: 72 65 74 75 72 6e 20 63 6f 64 65 2e 0d 0a 20 20  return code...  
3cf0: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72 65 74 75        /// </retu
3d00: 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 53 51  rns>..        SQ
3d10: 4c 69 74 65 45 72 72 6f 72 43 6f 64 65 20 78 43  LiteErrorCode xC
3d20: 6f 6e 6e 65 63 74 28 0d 0a 20 20 20 20 20 20 20  onnect(..       
3d30: 20 20 20 20 20 49 6e 74 50 74 72 20 70 44 62 2c       IntPtr pDb,
3d40: 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 49 6e  ..            In
3d50: 74 50 74 72 20 70 41 75 78 2c 0d 0a 20 20 20 20  tPtr pAux,..    
3d60: 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63          int argc
3d70: 2c 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 49  ,..            I
3d80: 6e 74 50 74 72 20 61 72 67 76 2c 0d 0a 20 20 20  ntPtr argv,..   
3d90: 20 20 20 20 20 20 20 20 20 72 65 66 20 49 6e 74           ref Int
3da0: 50 74 72 20 70 56 74 61 62 2c 0d 0a 20 20 20 20  Ptr pVtab,..    
3db0: 20 20 20 20 20 20 20 20 72 65 66 20 49 6e 74 50          ref IntP
3dc0: 74 72 20 70 45 72 72 6f 72 0d 0a 20 20 20 20 20  tr pError..     
3dd0: 20 20 20 20 20 20 20 29 3b 0d 0a 0d 0a 20 20 20         );....   
3de0: 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f       ///////////
3df0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
3e00: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
3e10: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
3e20: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a  ////////////....
3e30: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 73 75 6d          /// <sum
3e40: 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f  mary>..        /
3e50: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20  // <para>..     
3e60: 20 20 20 2f 2f 2f 20 53 51 4c 69 74 65 20 75 73     /// SQLite us
3e70: 65 73 20 74 68 65 20 78 42 65 73 74 49 6e 64 65  es the xBestInde
3e80: 78 20 6d 65 74 68 6f 64 20 6f 66 20 61 20 76 69  x method of a vi
3e90: 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
3ea0: 6c 65 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 0d  le to determine.
3eb0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65  .        /// the
3ec0: 20 62 65 73 74 20 77 61 79 20 74 6f 20 61 63 63   best way to acc
3ed0: 65 73 73 20 74 68 65 20 76 69 72 74 75 61 6c 20  ess the virtual 
3ee0: 74 61 62 6c 65 2e 20 0d 0a 20 20 20 20 20 20 20  table. ..       
3ef0: 20 2f 2f 2f 20 54 68 65 20 78 42 65 73 74 49 6e   /// The xBestIn
3f00: 64 65 78 20 6d 65 74 68 6f 64 20 68 61 73 20 61  dex method has a
3f10: 20 70 72 6f 74 6f 74 79 70 65 20 6c 69 6b 65 20   prototype like 
3f20: 74 68 69 73 3a 0d 0a 20 20 20 20 20 20 20 20 2f  this:..        /
3f30: 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  // </para>..    
3f40: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63      /// <para><c
3f50: 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ode>..        //
3f60: 2f 20 20 20 69 6e 74 20 28 2a 78 42 65 73 74 49  /   int (*xBestI
3f70: 6e 64 65 78 29 28 73 71 6c 69 74 65 33 5f 76 74  ndex)(sqlite3_vt
3f80: 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74  ab *pVTab, sqlit
3f90: 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b  e3_index_info*);
3fa0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
3fb0: 63 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20  code></para>..  
3fc0: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
3fd0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
3fe0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 63 6f  e SQLite core co
3ff0: 6d 6d 75 6e 69 63 61 74 65 73 20 77 69 74 68 20  mmunicates with 
4000: 74 68 65 20 78 42 65 73 74 49 6e 64 65 78 20 6d  the xBestIndex m
4010: 65 74 68 6f 64 20 62 79 20 66 69 6c 6c 69 6e 67  ethod by filling
4020: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69   ..        /// i
4030: 6e 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64 73  n certain fields
4040: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
4050: 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63  index_info struc
4060: 74 75 72 65 20 61 6e 64 20 70 61 73 73 69 6e 67  ture and passing
4070: 20 61 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f   a ..        ///
4080: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
4090: 20 73 74 72 75 63 74 75 72 65 20 69 6e 74 6f 20   structure into 
40a0: 78 42 65 73 74 49 6e 64 65 78 20 61 73 20 74 68  xBestIndex as th
40b0: 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
40c0: 65 72 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  er. ..        //
40d0: 2f 20 54 68 65 20 78 42 65 73 74 49 6e 64 65 78  / The xBestIndex
40e0: 20 6d 65 74 68 6f 64 20 66 69 6c 6c 73 20 6f 75   method fills ou
40f0: 74 20 6f 74 68 65 72 20 66 69 65 6c 64 73 20 6f  t other fields o
4100: 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65  f this structure
4110: 20 77 68 69 63 68 0d 0a 20 20 20 20 20 20 20 20   which..        
4120: 2f 2f 2f 20 66 6f 72 6d 73 20 74 68 65 20 72 65  /// forms the re
4130: 70 6c 79 2e 20 54 68 65 20 73 71 6c 69 74 65 33  ply. The sqlite3
4140: 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75  _index_info stru
4150: 63 74 75 72 65 20 6c 6f 6f 6b 73 20 6c 69 6b 65  cture looks like
4160: 20 74 68 69 73 3a 0d 0a 20 20 20 20 20 20 20 20   this:..        
4170: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
4180: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c       /// <para><
4190: 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f  code>..        /
41a0: 2f 2f 20 20 20 73 74 72 75 63 74 20 73 71 6c 69  //   struct sqli
41b0: 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b  te3_index_info {
41c0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20  ..        ///   
41d0: 20 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0d 0a    /* Inputs */..
41e0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20          ///     
41f0: 63 6f 6e 73 74 20 69 6e 74 20 6e 43 6f 6e 73 74  const int nConst
4200: 72 61 69 6e 74 3b 20 20 20 20 20 2f 2a 20 4e 75  raint;     /* Nu
4210: 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20  mber of entries 
4220: 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 20 2a  in aConstraint *
4230: 2f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20  /..        ///  
4240: 20 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20     const struct 
4250: 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f  sqlite3_index_co
4260: 6e 73 74 72 61 69 6e 74 20 7b 0d 0a 20 20 20 20  nstraint {..    
4270: 20 20 20 20 2f 2f 2f 20 20 20 20 20 20 20 20 69      ///        i
4280: 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20  nt iColumn;     
4290: 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75           /* Colu
42a0: 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 6e 64 20  mn on left-hand 
42b0: 73 69 64 65 20 6f 66 20 63 6f 6e 73 74 72 61 69  side of constrai
42c0: 6e 74 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20 2f  nt */..        /
42d0: 2f 2f 20 20 20 20 20 20 20 20 75 6e 73 69 67 6e  //        unsign
42e0: 65 64 20 63 68 61 72 20 6f 70 3b 20 20 20 20 20  ed char op;     
42f0: 20 20 20 20 2f 2a 20 43 6f 6e 73 74 72 61 69 6e      /* Constrain
4300: 74 20 6f 70 65 72 61 74 6f 72 20 2a 2f 0d 0a 20  t operator */.. 
4310: 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 20         ///      
4320: 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20    unsigned char 
4330: 75 73 61 62 6c 65 3b 20 20 20 20 20 2f 2a 20 54  usable;     /* T
4340: 72 75 65 20 69 66 20 74 68 69 73 20 63 6f 6e 73  rue if this cons
4350: 74 72 61 69 6e 74 20 69 73 20 75 73 61 62 6c 65  traint is usable
4360: 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f   */..        ///
4370: 20 20 20 20 20 20 20 20 69 6e 74 20 69 54 65 72          int iTer
4380: 6d 4f 66 66 73 65 74 3b 20 20 20 20 20 20 20 20  mOffset;        
4390: 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e    /* Used intern
43a0: 61 6c 6c 79 20 2d 20 78 42 65 73 74 49 6e 64 65  ally - xBestInde
43b0: 78 20 73 68 6f 75 6c 64 20 69 67 6e 6f 72 65 20  x should ignore 
43c0: 2a 2f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  */..        /// 
43d0: 20 20 20 20 7d 20 2a 63 6f 6e 73 74 20 61 43 6f      } *const aCo
43e0: 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 2f  nstraint;      /
43f0: 2a 20 54 61 62 6c 65 20 6f 66 20 57 48 45 52 45  * Table of WHERE
4400: 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69   clause constrai
4410: 6e 74 73 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20  nts */..        
4420: 2f 2f 2f 20 20 20 20 20 63 6f 6e 73 74 20 69 6e  ///     const in
4430: 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20 20 20  t nOrderBy;     
4440: 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
4450: 74 65 72 6d 73 20 69 6e 20 74 68 65 20 4f 52 44  terms in the ORD
4460: 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0d  ER BY clause */.
4470: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20  .        ///    
4480: 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71   const struct sq
4490: 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f 72 64 65  lite3_index_orde
44a0: 72 62 79 20 7b 0d 0a 20 20 20 20 20 20 20 20 2f  rby {..        /
44b0: 2f 2f 20 20 20 20 20 20 20 20 69 6e 74 20 69 43  //        int iC
44c0: 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20  olumn;          
44d0: 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75      /* Column nu
44e0: 6d 62 65 72 20 2a 2f 0d 0a 20 20 20 20 20 20 20  mber */..       
44f0: 20 2f 2f 2f 20 20 20 20 20 20 20 20 75 6e 73 69   ///        unsi
4500: 67 6e 65 64 20 63 68 61 72 20 64 65 73 63 3b 20  gned char desc; 
4510: 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20 66 6f        /* True fo
4520: 72 20 44 45 53 43 2e 20 20 46 61 6c 73 65 20 66  r DESC.  False f
4530: 6f 72 20 41 53 43 2e 20 2a 2f 0d 0a 20 20 20 20  or ASC. */..    
4540: 20 20 20 20 2f 2f 2f 20 20 20 20 20 7d 20 2a 63      ///     } *c
4550: 6f 6e 73 74 20 61 4f 72 64 65 72 42 79 3b 20 20  onst aOrderBy;  
4560: 20 20 20 20 20 20 20 2f 2a 20 54 68 65 20 4f 52         /* The OR
4570: 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f  DER BY clause */
4580: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20  ..        ///   
4590: 20 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f 0d    /* Outputs */.
45a0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20  .        ///    
45b0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
45c0: 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74  index_constraint
45d0: 5f 75 73 61 67 65 20 7b 0d 0a 20 20 20 20 20 20  _usage {..      
45e0: 20 20 2f 2f 2f 20 20 20 20 20 20 20 69 6e 74 20    ///       int 
45f0: 61 72 67 76 49 6e 64 65 78 3b 20 20 20 20 20 20  argvIndex;      
4600: 20 20 20 20 20 2f 2a 20 69 66 20 26 67 74 3b 30       /* if &gt;0
4610: 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20  , constraint is 
4620: 70 61 72 74 20 6f 66 20 61 72 67 76 20 74 6f 20  part of argv to 
4630: 78 46 69 6c 74 65 72 20 2a 2f 0d 0a 20 20 20 20  xFilter */..    
4640: 20 20 20 20 2f 2f 2f 20 20 20 20 20 20 20 75 6e      ///       un
4650: 73 69 67 6e 65 64 20 63 68 61 72 20 6f 6d 69 74  signed char omit
4660: 3b 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f 74  ;      /* Do not
4670: 20 63 6f 64 65 20 61 20 74 65 73 74 20 66 6f 72   code a test for
4680: 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74   this constraint
4690: 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f   */..        ///
46a0: 20 20 20 20 20 7d 20 2a 63 6f 6e 73 74 20 61 43       } *const aC
46b0: 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 3b 0d  onstraintUsage;.
46c0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20  .        ///    
46d0: 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20 20 20   int idxNum;    
46e0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e              /* N
46f0: 75 6d 62 65 72 20 75 73 65 64 20 74 6f 20 69 64  umber used to id
4700: 65 6e 74 69 66 79 20 74 68 65 20 69 6e 64 65 78  entify the index
4710: 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f   */..        ///
4720: 20 20 20 20 20 63 68 61 72 20 2a 69 64 78 53 74       char *idxSt
4730: 72 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  r;              
4740: 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f 73 73 69  /* String, possi
4750: 62 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  bly obtained fro
4760: 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
4770: 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f   */..        ///
4780: 20 20 20 20 20 69 6e 74 20 6e 65 65 64 54 6f 46       int needToF
4790: 72 65 65 49 64 78 53 74 72 3b 20 20 20 20 20 20  reeIdxStr;      
47a0: 2f 2a 20 46 72 65 65 20 69 64 78 53 74 72 20 75  /* Free idxStr u
47b0: 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  sing sqlite3_fre
47c0: 65 28 29 20 69 66 20 74 72 75 65 20 2a 2f 0d 0a  e() if true */..
47d0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20          ///     
47e0: 69 6e 74 20 6f 72 64 65 72 42 79 43 6f 6e 73 75  int orderByConsu
47f0: 6d 65 64 3b 20 20 20 20 20 20 20 2f 2a 20 54 72  med;       /* Tr
4800: 75 65 20 69 66 20 6f 75 74 70 75 74 20 69 73 20  ue if output is 
4810: 61 6c 72 65 61 64 79 20 6f 72 64 65 72 65 64 20  already ordered 
4820: 2a 2f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  */..        /// 
4830: 20 20 20 20 64 6f 75 62 6c 65 20 65 73 74 69 6d      double estim
4840: 61 74 65 64 43 6f 73 74 3b 20 20 20 20 20 20 2f  atedCost;      /
4850: 2a 20 45 73 74 69 6d 61 74 65 64 20 63 6f 73 74  * Estimated cost
4860: 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 20 69   of using this i
4870: 6e 64 65 78 20 2a 2f 0d 0a 20 20 20 20 20 20 20  ndex */..       
4880: 20 2f 2f 2f 20 20 20 20 20 2f 2a 20 46 69 65 6c   ///     /* Fiel
4890: 64 73 20 62 65 6c 6f 77 20 61 72 65 20 6f 6e 6c  ds below are onl
48a0: 79 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 53  y available in S
48b0: 51 4c 69 74 65 20 33 2e 38 2e 32 20 61 6e 64 20  QLite 3.8.2 and 
48c0: 6c 61 74 65 72 20 2a 2f 0d 0a 20 20 20 20 20 20  later */..      
48d0: 20 20 2f 2f 2f 20 20 20 20 20 73 71 6c 69 74 65    ///     sqlite
48e0: 33 5f 69 6e 74 36 34 20 65 73 74 69 6d 61 74 65  3_int64 estimate
48f0: 64 52 6f 77 73 3b 20 20 20 20 2f 2a 20 45 73 74  dRows;    /* Est
4900: 69 6d 61 74 65 64 20 6e 75 6d 62 65 72 20 6f 66  imated number of
4910: 20 72 6f 77 73 20 72 65 74 75 72 6e 65 64 20 2a   rows returned *
4920: 2f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20  /..        ///  
4930: 20 20 20 2f 2a 20 46 69 65 6c 64 73 20 62 65 6c     /* Fields bel
4940: 6f 77 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69  ow are only avai
4950: 6c 61 62 6c 65 20 69 6e 20 53 51 4c 69 74 65 20  lable in SQLite 
4960: 33 2e 39 2e 30 20 61 6e 64 20 6c 61 74 65 72 20  3.9.0 and later 
4970: 2a 2f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  */..        /// 
4980: 20 20 20 20 69 6e 74 20 69 64 78 46 6c 61 67 73      int idxFlags
4990: 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ;              /
49a0: 2a 20 4d 61 73 6b 20 6f 66 20 53 51 4c 49 54 45  * Mask of SQLITE
49b0: 5f 49 4e 44 45 58 5f 53 43 41 4e 5f 2a 20 66 6c  _INDEX_SCAN_* fl
49c0: 61 67 73 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20  ags */..        
49d0: 2f 2f 2f 20 20 20 7d 3b 0d 0a 20 20 20 20 20 20  ///   };..      
49e0: 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70    /// </code></p
49f0: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
4a00: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
4a10: 20 20 2f 2f 2f 20 50 6c 65 61 73 65 20 6e 6f 74    /// Please not
4a20: 65 20 74 68 65 20 77 61 72 6e 69 6e 67 73 20 6f  e the warnings o
4a30: 6e 20 74 68 65 20 22 65 73 74 69 6d 61 74 65 64  n the "estimated
4a40: 52 6f 77 73 22 20 61 6e 64 20 22 69 64 78 46 6c  Rows" and "idxFl
4a50: 61 67 73 22 20 66 69 65 6c 64 2e 0d 0a 20 20 20  ags" field...   
4a60: 20 20 20 20 20 2f 2f 2f 20 54 68 65 73 65 20 66       /// These f
4a70: 69 65 6c 64 73 20 77 65 72 65 20 61 64 64 65 64  ields were added
4a80: 20 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 72   with SQLite ver
4a90: 73 69 6f 6e 73 20 33 2e 38 2e 32 20 61 6e 64 20  sions 3.8.2 and 
4aa0: 33 2e 39 2e 30 2c 20 72 65 73 70 65 63 74 69 76  3.9.0, respectiv
4ab0: 65 6c 79 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f  ely. ..        /
4ac0: 2f 2f 20 41 6e 79 20 65 78 74 65 6e 73 69 6f 6e  // Any extension
4ad0: 20 74 68 61 74 20 72 65 61 64 73 20 6f 72 20 77   that reads or w
4ae0: 72 69 74 65 73 20 74 68 65 73 65 20 66 69 65 6c  rites these fiel
4af0: 64 73 20 6d 75 73 74 20 66 69 72 73 74 20 63 68  ds must first ch
4b00: 65 63 6b 20 74 68 61 74 20 74 68 65 20 0d 0a 20  eck that the .. 
4b10: 20 20 20 20 20 20 20 2f 2f 2f 20 76 65 72 73 69         /// versi
4b20: 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  on of the SQLite
4b30: 20 6c 69 62 72 61 72 79 20 69 6e 20 75 73 65 20   library in use 
4b40: 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  is greater than 
4b50: 6f 72 20 65 71 75 61 6c 20 74 6f 20 33 2e 38 2e  or equal to 3.8.
4b60: 32 20 6f 72 0d 0a 20 20 20 20 20 20 20 20 2f 2f  2 or..        //
4b70: 2f 20 33 2e 39 2e 30 20 2d 20 70 65 72 68 61 70  / 3.9.0 - perhap
4b80: 73 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74  s using a call t
4b90: 6f 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  o sqlite3_versio
4ba0: 6e 28 29 2e 20 54 68 65 20 72 65 73 75 6c 74 20  n(). The result 
4bb0: 6f 66 20 61 74 74 65 6d 70 74 69 6e 67 20 0d 0a  of attempting ..
4bc0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 6f 20 61          /// to a
4bd0: 63 63 65 73 73 20 74 68 65 73 65 20 66 69 65 6c  ccess these fiel
4be0: 64 73 20 69 6e 20 61 6e 20 73 71 6c 69 74 65 33  ds in an sqlite3
4bf0: 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75  _index_info stru
4c00: 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79  cture created by
4c10: 20 61 6e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f   an ..        //
4c20: 2f 20 6f 6c 64 65 72 20 76 65 72 73 69 6f 6e 20  / older version 
4c30: 6f 66 20 53 51 4c 69 74 65 20 61 72 65 20 75 6e  of SQLite are un
4c40: 64 65 66 69 6e 65 64 2e 0d 0a 20 20 20 20 20 20  defined...      
4c50: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
4c60: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
4c70: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 49  >..        /// I
4c80: 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72  n addition, ther
4c90: 65 20 61 72 65 20 73 6f 6d 65 20 64 65 66 69 6e  e are some defin
4ca0: 65 64 20 63 6f 6e 73 74 61 6e 74 73 3a 0d 0a 20  ed constants:.. 
4cb0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
4cc0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
4cd0: 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20  <para><code>..  
4ce0: 20 20 20 20 20 20 2f 2f 2f 20 20 20 23 64 65 66        ///   #def
4cf0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
4d00: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 20  _CONSTRAINT_EQ  
4d10: 20 20 32 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f    2..        ///
4d20: 20 20 20 23 64 65 66 69 6e 65 20 53 51 4c 49 54     #define SQLIT
4d30: 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
4d40: 4e 54 5f 47 54 20 20 20 20 34 0d 0a 20 20 20 20  NT_GT    4..    
4d50: 20 20 20 20 2f 2f 2f 20 20 20 23 64 65 66 69 6e      ///   #defin
4d60: 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
4d70: 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20 20 20 20  ONSTRAINT_LE    
4d80: 38 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20  8..        ///  
4d90: 20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f   #define SQLITE_
4da0: 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
4db0: 5f 4c 54 20 20 20 20 31 36 0d 0a 20 20 20 20 20  _LT    16..     
4dc0: 20 20 20 2f 2f 2f 20 20 20 23 64 65 66 69 6e 65     ///   #define
4dd0: 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f   SQLITE_INDEX_CO
4de0: 4e 53 54 52 41 49 4e 54 5f 47 45 20 20 20 20 33  NSTRAINT_GE    3
4df0: 32 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20  2..        ///  
4e00: 20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f   #define SQLITE_
4e10: 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
4e20: 5f 4d 41 54 43 48 20 36 34 0d 0a 20 20 20 20 20  _MATCH 64..     
4e30: 20 20 20 2f 2f 2f 20 20 20 23 64 65 66 69 6e 65     ///   #define
4e40: 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 53 43   SQLITE_INDEX_SC
4e50: 41 4e 5f 55 4e 49 51 55 45 20 20 20 20 20 20 31  AN_UNIQUE      1
4e60: 20 20 20 20 20 2f 2a 20 53 63 61 6e 20 76 69 73       /* Scan vis
4e70: 69 74 73 20 61 74 20 6d 6f 73 74 20 31 20 72 6f  its at most 1 ro
4e80: 77 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20 2f 2f  w */..        //
4e90: 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e  / </code></para>
4ea0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
4eb0: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
4ec0: 2f 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  / The SQLite cor
4ed0: 65 20 63 61 6c 6c 73 20 74 68 65 20 78 42 65 73  e calls the xBes
4ee0: 74 49 6e 64 65 78 20 6d 65 74 68 6f 64 20 77 68  tIndex method wh
4ef0: 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 69  en it is compili
4f00: 6e 67 20 61 20 71 75 65 72 79 0d 0a 20 20 20 20  ng a query..    
4f10: 20 20 20 20 2f 2f 2f 20 74 68 61 74 20 69 6e 76      /// that inv
4f20: 6f 6c 76 65 73 20 61 20 76 69 72 74 75 61 6c 20  olves a virtual 
4f30: 74 61 62 6c 65 2e 20 49 6e 20 6f 74 68 65 72 20  table. In other 
4f40: 77 6f 72 64 73 2c 20 53 51 4c 69 74 65 20 63 61  words, SQLite ca
4f50: 6c 6c 73 20 74 68 69 73 20 6d 65 74 68 6f 64 20  lls this method 
4f60: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 77 68  ..        /// wh
4f70: 65 6e 20 69 74 20 69 73 20 72 75 6e 6e 69 6e 67  en it is running
4f80: 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
4f90: 28 29 20 6f 72 20 74 68 65 20 65 71 75 69 76 61  () or the equiva
4fa0: 6c 65 6e 74 2e 20 0d 0a 20 20 20 20 20 20 20 20  lent. ..        
4fb0: 2f 2f 2f 20 42 79 20 63 61 6c 6c 69 6e 67 20 74  /// By calling t
4fc0: 68 69 73 20 6d 65 74 68 6f 64 2c 20 74 68 65 20  his method, the 
4fd0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 53 51  ..        /// SQ
4fe0: 4c 69 74 65 20 63 6f 72 65 20 69 73 20 73 61 79  Lite core is say
4ff0: 69 6e 67 20 74 6f 20 74 68 65 20 76 69 72 74 75  ing to the virtu
5000: 61 6c 20 74 61 62 6c 65 20 74 68 61 74 20 69 74  al table that it
5010: 20 6e 65 65 64 73 20 74 6f 20 61 63 63 65 73 73   needs to access
5020: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73   ..        /// s
5030: 6f 6d 65 20 73 75 62 73 65 74 20 6f 66 20 74 68  ome subset of th
5040: 65 20 72 6f 77 73 20 69 6e 20 74 68 65 20 76 69  e rows in the vi
5050: 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20  rtual table and 
5060: 69 74 20 77 61 6e 74 73 20 74 6f 20 6b 6e 6f 77  it wants to know
5070: 20 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f   the..        //
5080: 2f 20 6d 6f 73 74 20 65 66 66 69 63 69 65 6e 74  / most efficient
5090: 20 77 61 79 20 74 6f 20 64 6f 20 74 68 61 74 20   way to do that 
50a0: 61 63 63 65 73 73 2e 20 54 68 65 20 78 42 65 73  access. The xBes
50b0: 74 49 6e 64 65 78 20 6d 65 74 68 6f 64 20 72 65  tIndex method re
50c0: 70 6c 69 65 73 20 0d 0a 20 20 20 20 20 20 20 20  plies ..        
50d0: 2f 2f 2f 20 77 69 74 68 20 69 6e 66 6f 72 6d 61  /// with informa
50e0: 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20 53 51  tion that the SQ
50f0: 4c 69 74 65 20 63 6f 72 65 20 63 61 6e 20 74 68  Lite core can th
5100: 65 6e 20 75 73 65 20 74 6f 20 63 6f 6e 64 75 63  en use to conduc
5110: 74 20 61 6e 20 0d 0a 20 20 20 20 20 20 20 20 2f  t an ..        /
5120: 2f 2f 20 65 66 66 69 63 69 65 6e 74 20 73 65 61  // efficient sea
5130: 72 63 68 20 6f 66 20 74 68 65 20 76 69 72 74 75  rch of the virtu
5140: 61 6c 20 74 61 62 6c 65 2e 0d 0a 20 20 20 20 20  al table...     
5150: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a     /// </para>..
5160: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
5170: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
5180: 57 68 69 6c 65 20 63 6f 6d 70 69 6c 69 6e 67 20  While compiling 
5190: 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 71 75 65  a single SQL que
51a0: 72 79 2c 20 74 68 65 20 53 51 4c 69 74 65 20 63  ry, the SQLite c
51b0: 6f 72 65 20 6d 69 67 68 74 20 63 61 6c 6c 20 0d  ore might call .
51c0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 78 42 65  .        /// xBe
51d0: 73 74 49 6e 64 65 78 20 6d 75 6c 74 69 70 6c 65  stIndex multiple
51e0: 20 74 69 6d 65 73 20 77 69 74 68 20 64 69 66 66   times with diff
51f0: 65 72 65 6e 74 20 73 65 74 74 69 6e 67 73 20 69  erent settings i
5200: 6e 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  n sqlite3_index_
5210: 69 6e 66 6f 2e 0d 0a 20 20 20 20 20 20 20 20 2f  info...        /
5220: 2f 2f 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  // The SQLite co
5230: 72 65 20 77 69 6c 6c 20 74 68 65 6e 20 73 65 6c  re will then sel
5240: 65 63 74 20 74 68 65 20 63 6f 6d 62 69 6e 61 74  ect the combinat
5250: 69 6f 6e 20 74 68 61 74 20 61 70 70 65 61 72 73  ion that appears
5260: 20 74 6f 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f   to ..        //
5270: 2f 20 67 69 76 65 20 74 68 65 20 62 65 73 74 20  / give the best 
5280: 70 65 72 66 6f 72 6d 61 6e 63 65 2e 0d 0a 20 20  performance...  
5290: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61        /// </para
52a0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
52b0: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
52c0: 2f 2f 20 42 65 66 6f 72 65 20 63 61 6c 6c 69 6e  // Before callin
52d0: 67 20 74 68 69 73 20 6d 65 74 68 6f 64 2c 20 74  g this method, t
52e0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 69  he SQLite core i
52f0: 6e 69 74 69 61 6c 69 7a 65 73 20 61 6e 20 69 6e  nitializes an in
5300: 73 74 61 6e 63 65 20 0d 0a 20 20 20 20 20 20 20  stance ..       
5310: 20 2f 2f 2f 20 6f 66 20 74 68 65 20 73 71 6c 69   /// of the sqli
5320: 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73  te3_index_info s
5330: 74 72 75 63 74 75 72 65 20 77 69 74 68 20 69 6e  tructure with in
5340: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
5350: 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  the..        ///
5360: 20 71 75 65 72 79 20 74 68 61 74 20 69 74 20 69   query that it i
5370: 73 20 63 75 72 72 65 6e 74 6c 79 20 74 72 79 69  s currently tryi
5380: 6e 67 20 74 6f 20 70 72 6f 63 65 73 73 2e 20 54  ng to process. T
5390: 68 69 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  his information 
53a0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 64 65  ..        /// de
53b0: 72 69 76 65 73 20 6d 61 69 6e 6c 79 20 66 72 6f  rives mainly fro
53c0: 6d 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 75  m the WHERE clau
53d0: 73 65 20 61 6e 64 20 4f 52 44 45 52 20 42 59 20  se and ORDER BY 
53e0: 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75  or GROUP BY clau
53f0: 73 65 73 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ses ..        //
5400: 2f 20 6f 66 20 74 68 65 20 71 75 65 72 79 2c 20  / of the query, 
5410: 62 75 74 20 61 6c 73 6f 20 66 72 6f 6d 20 61 6e  but also from an
5420: 79 20 4f 4e 20 6f 72 20 55 53 49 4e 47 20 63 6c  y ON or USING cl
5430: 61 75 73 65 73 20 69 66 20 74 68 65 20 71 75 65  auses if the que
5440: 72 79 20 69 73 20 61 20 0d 0a 20 20 20 20 20 20  ry is a ..      
5450: 20 20 2f 2f 2f 20 6a 6f 69 6e 2e 20 54 68 65 20    /// join. The 
5460: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 74 68 61 74  information that
5470: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
5480: 20 70 72 6f 76 69 64 65 73 20 74 6f 20 74 68 65   provides to the
5490: 20 78 42 65 73 74 49 6e 64 65 78 20 0d 0a 20 20   xBestIndex ..  
54a0: 20 20 20 20 20 20 2f 2f 2f 20 6d 65 74 68 6f 64        /// method
54b0: 20 69 73 20 68 65 6c 64 20 69 6e 20 74 68 65 20   is held in the 
54c0: 70 61 72 74 20 6f 66 20 74 68 65 20 73 74 72 75  part of the stru
54d0: 63 74 75 72 65 20 74 68 61 74 20 69 73 20 6d 61  cture that is ma
54e0: 72 6b 65 64 20 61 73 20 22 49 6e 70 75 74 73 22  rked as "Inputs"
54f0: 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  . ..        /// 
5500: 54 68 65 20 22 4f 75 74 70 75 74 73 22 20 73 65  The "Outputs" se
5510: 63 74 69 6f 6e 20 69 73 20 69 6e 69 74 69 61 6c  ction is initial
5520: 69 7a 65 64 20 74 6f 20 7a 65 72 6f 2e 0d 0a 20  ized to zero... 
5530: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
5540: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
5550: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
5560: 2f 2f 2f 20 54 68 65 20 69 6e 66 6f 72 6d 61 74  /// The informat
5570: 69 6f 6e 20 69 6e 20 74 68 65 20 73 71 6c 69 74  ion in the sqlit
5580: 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74  e3_index_info st
5590: 72 75 63 74 75 72 65 20 69 73 20 65 70 68 65 6d  ructure is ephem
55a0: 65 72 61 6c 0d 0a 20 20 20 20 20 20 20 20 2f 2f  eral..        //
55b0: 2f 20 61 6e 64 20 6d 61 79 20 62 65 20 6f 76 65  / and may be ove
55c0: 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c  rwritten or deal
55d0: 6c 6f 63 61 74 65 64 20 61 73 20 73 6f 6f 6e 20  located as soon 
55e0: 61 73 20 74 68 65 20 78 42 65 73 74 49 6e 64 65  as the xBestInde
55f0: 78 20 6d 65 74 68 6f 64 0d 0a 20 20 20 20 20 20  x method..      
5600: 20 20 2f 2f 2f 20 72 65 74 75 72 6e 73 2e 20 20    /// returns.  
5610: 49 66 20 74 68 65 20 78 42 65 73 74 49 6e 64 65  If the xBestInde
5620: 78 20 6d 65 74 68 6f 64 20 6e 65 65 64 73 20 74  x method needs t
5630: 6f 20 72 65 6d 65 6d 62 65 72 20 61 6e 79 20 70  o remember any p
5640: 61 72 74 20 6f 66 20 74 68 65 0d 0a 20 20 20 20  art of the..    
5650: 20 20 20 20 2f 2f 2f 20 73 71 6c 69 74 65 33 5f      /// sqlite3_
5660: 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63  index_info struc
5670: 74 75 72 65 2c 20 69 74 20 73 68 6f 75 6c 64 20  ture, it should 
5680: 6d 61 6b 65 20 61 20 63 6f 70 79 2e 20 20 43 61  make a copy.  Ca
5690: 72 65 20 6d 75 73 74 20 62 65 0d 0a 20 20 20 20  re must be..    
56a0: 20 20 20 20 2f 2f 2f 20 74 61 6b 65 20 74 6f 20      /// take to 
56b0: 73 74 6f 72 65 20 74 68 65 20 63 6f 70 79 20 69  store the copy i
56c0: 6e 20 61 20 70 6c 61 63 65 20 77 68 65 72 65 20  n a place where 
56d0: 69 74 20 77 69 6c 6c 20 62 65 20 64 65 61 6c 6c  it will be deall
56e0: 6f 63 61 74 65 64 2c 20 73 75 63 68 0d 0a 20 20  ocated, such..  
56f0: 20 20 20 20 20 20 2f 2f 2f 20 61 73 20 69 6e 20        /// as in 
5700: 74 68 65 20 69 64 78 53 74 72 20 66 69 65 6c 64  the idxStr field
5710: 20 77 69 74 68 20 6e 65 65 64 54 6f 46 72 65 65   with needToFree
5720: 49 64 78 53 74 72 20 73 65 74 20 74 6f 20 31 2e  IdxStr set to 1.
5730: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
5740: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
5750: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20  // <para>..     
5760: 20 20 20 2f 2f 2f 20 4e 6f 74 65 20 74 68 61 74     /// Note that
5770: 20 78 42 65 73 74 49 6e 64 65 78 20 77 69 6c 6c   xBestIndex will
5780: 20 61 6c 77 61 79 73 20 62 65 20 63 61 6c 6c 65   always be calle
5790: 64 20 62 65 66 6f 72 65 20 78 46 69 6c 74 65 72  d before xFilter
57a0: 2c 20 73 69 6e 63 65 0d 0a 20 20 20 20 20 20 20  , since..       
57b0: 20 2f 2f 2f 20 74 68 65 20 69 64 78 4e 75 6d 20   /// the idxNum 
57c0: 61 6e 64 20 69 64 78 53 74 72 20 6f 75 74 70 75  and idxStr outpu
57d0: 74 73 20 66 72 6f 6d 20 78 42 65 73 74 49 6e 64  ts from xBestInd
57e0: 65 78 20 61 72 65 20 72 65 71 75 69 72 65 64 20  ex are required 
57f0: 69 6e 70 75 74 73 20 74 6f 0d 0a 20 20 20 20 20  inputs to..     
5800: 20 20 20 2f 2f 2f 20 78 46 69 6c 74 65 72 2e 20     /// xFilter. 
5810: 20 48 6f 77 65 76 65 72 2c 20 74 68 65 72 65 20   However, there 
5820: 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20  is no guarantee 
5830: 74 68 61 74 20 78 46 69 6c 74 65 72 20 77 69 6c  that xFilter wil
5840: 6c 20 62 65 20 63 61 6c 6c 65 64 0d 0a 20 20 20  l be called..   
5850: 20 20 20 20 20 2f 2f 2f 20 66 6f 6c 6c 6f 77 69       /// followi
5860: 6e 67 20 61 20 73 75 63 63 65 73 73 66 75 6c 20  ng a successful 
5870: 78 42 65 73 74 49 6e 64 65 78 2e 20 20 0d 0a 20  xBestIndex.  .. 
5880: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
5890: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
58a0: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
58b0: 2f 2f 2f 20 54 68 65 20 78 42 65 73 74 49 6e 64  /// The xBestInd
58c0: 65 78 20 6d 65 74 68 6f 64 20 69 73 20 72 65 71  ex method is req
58d0: 75 69 72 65 64 20 66 6f 72 20 65 76 65 72 79 20  uired for every 
58e0: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d  virtual table im
58f0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0d 0a 20  plementation... 
5900: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
5910: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
5920: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
5930: 2f 2f 2f 20 54 68 65 20 6d 61 69 6e 20 74 68 69  /// The main thi
5940: 6e 67 20 74 68 61 74 20 74 68 65 20 53 51 4c 69  ng that the SQLi
5950: 74 65 20 63 6f 72 65 20 69 73 20 74 72 79 69 6e  te core is tryin
5960: 67 20 74 6f 20 63 6f 6d 6d 75 6e 69 63 61 74 65  g to communicate
5970: 20 74 6f 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f   to ..        //
5980: 2f 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  / the virtual ta
5990: 62 6c 65 20 69 73 20 74 68 65 20 63 6f 6e 73 74  ble is the const
59a0: 72 61 69 6e 74 73 20 74 68 61 74 20 61 72 65 20  raints that are 
59b0: 61 76 61 69 6c 61 62 6c 65 20 74 6f 20 6c 69 6d  available to lim
59c0: 69 74 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  it ..        ///
59d0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
59e0: 6f 77 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f  ows that need to
59f0: 20 62 65 20 73 65 61 72 63 68 65 64 2e 20 54 68   be searched. Th
5a00: 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20  e aConstraint[] 
5a10: 61 72 72 61 79 20 0d 0a 20 20 20 20 20 20 20 20  array ..        
5a20: 2f 2f 2f 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 65  /// contains one
5a30: 20 65 6e 74 72 79 20 66 6f 72 20 65 61 63 68 20   entry for each 
5a40: 63 6f 6e 73 74 72 61 69 6e 74 2e 20 54 68 65 72  constraint. Ther
5a50: 65 20 77 69 6c 6c 20 62 65 20 65 78 61 63 74 6c  e will be exactl
5a60: 79 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  y ..        /// 
5a70: 6e 43 6f 6e 73 74 72 61 69 6e 74 20 65 6e 74 72  nConstraint entr
5a80: 69 65 73 20 69 6e 20 74 68 61 74 20 61 72 72 61  ies in that arra
5a90: 79 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  y...        /// 
5aa0: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
5ab0: 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20   /// <para>..   
5ac0: 20 20 20 20 20 2f 2f 2f 20 45 61 63 68 20 63 6f       /// Each co
5ad0: 6e 73 74 72 61 69 6e 74 20 77 69 6c 6c 20 63 6f  nstraint will co
5ae0: 72 72 65 73 70 6f 6e 64 20 74 6f 20 61 20 74 65  rrespond to a te
5af0: 72 6d 20 69 6e 20 74 68 65 20 57 48 45 52 45 20  rm in the WHERE 
5b00: 63 6c 61 75 73 65 0d 0a 20 20 20 20 20 20 20 20  clause..        
5b10: 2f 2f 2f 20 6f 72 20 69 6e 20 61 20 55 53 49 4e  /// or in a USIN
5b20: 47 20 6f 72 20 4f 4e 20 63 6c 61 75 73 65 20 74  G or ON clause t
5b30: 68 61 74 20 69 73 20 6f 66 20 74 68 65 20 66 6f  hat is of the fo
5b40: 72 6d 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  rm..        /// 
5b50: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
5b60: 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65   /// <para><code
5b70: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20  >..        ///  
5b80: 20 20 20 20 63 6f 6c 75 6d 6e 20 20 4f 50 20 20      column  OP  
5b90: 45 58 50 52 0d 0a 20 20 20 20 20 20 20 20 2f 2f  EXPR..        //
5ba0: 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e  / </code></para>
5bb0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
5bc0: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
5bd0: 2f 20 57 68 65 72 65 20 22 63 6f 6c 75 6d 6e 22  / Where "column"
5be0: 20 69 73 20 61 20 63 6f 6c 75 6d 6e 20 69 6e 20   is a column in 
5bf0: 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
5c00: 65 2c 20 4f 50 20 69 73 20 61 6e 20 6f 70 65 72  e, OP is an oper
5c10: 61 74 6f 72 20 0d 0a 20 20 20 20 20 20 20 20 2f  ator ..        /
5c20: 2f 2f 20 6c 69 6b 65 20 22 3d 22 20 6f 72 20 22  // like "=" or "
5c30: 26 6c 74 3b 22 2c 20 61 6e 64 20 45 58 50 52 20  &lt;", and EXPR 
5c40: 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
5c50: 65 78 70 72 65 73 73 69 6f 6e 2e 20 53 6f 2c 20  expression. So, 
5c60: 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0d 0a 20 20  for example,..  
5c70: 20 20 20 20 20 20 2f 2f 2f 20 69 66 20 74 68 65        /// if the
5c80: 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f   WHERE clause co
5c90: 6e 74 61 69 6e 65 64 20 61 20 74 65 72 6d 20 6c  ntained a term l
5ca0: 69 6b 65 20 74 68 69 73 3a 0d 0a 20 20 20 20 20  ike this:..     
5cb0: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a     /// </para>..
5cc0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
5cd0: 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20  a><code>..      
5ce0: 20 20 2f 2f 2f 20 20 20 20 20 20 61 20 3d 20 35    ///      a = 5
5cf0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
5d00: 63 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20  code></para>..  
5d10: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
5d20: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
5d30: 65 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f  en one of the co
5d40: 6e 73 74 72 61 69 6e 74 73 20 77 6f 75 6c 64 20  nstraints would 
5d50: 62 65 20 6f 6e 20 74 68 65 20 22 61 22 20 63 6f  be on the "a" co
5d60: 6c 75 6d 6e 20 77 69 74 68 20 0d 0a 20 20 20 20  lumn with ..    
5d70: 20 20 20 20 2f 2f 2f 20 6f 70 65 72 61 74 6f 72      /// operator
5d80: 20 22 3d 22 20 61 6e 64 20 61 6e 20 65 78 70 72   "=" and an expr
5d90: 65 73 73 69 6f 6e 20 6f 66 20 22 35 22 2e 20 43  ession of "5". C
5da0: 6f 6e 73 74 72 61 69 6e 74 73 20 6e 65 65 64 20  onstraints need 
5db0: 6e 6f 74 20 68 61 76 65 20 61 0d 0a 20 20 20 20  not have a..    
5dc0: 20 20 20 20 2f 2f 2f 20 6c 69 74 65 72 61 6c 20      /// literal 
5dd0: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
5de0: 66 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 75  f the WHERE clau
5df0: 73 65 2e 20 54 68 65 20 71 75 65 72 79 20 6f 70  se. The query op
5e00: 74 69 6d 69 7a 65 72 20 6d 69 67 68 74 0d 0a 20  timizer might.. 
5e10: 20 20 20 20 20 20 20 2f 2f 2f 20 6d 61 6b 65 20         /// make 
5e20: 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 73 20  transformations 
5e30: 74 6f 20 74 68 65 20 0d 0a 20 20 20 20 20 20 20  to the ..       
5e40: 20 2f 2f 2f 20 57 48 45 52 45 20 63 6c 61 75 73   /// WHERE claus
5e50: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 78  e in order to ex
5e60: 74 72 61 63 74 20 61 73 20 6d 61 6e 79 20 63 6f  tract as many co
5e70: 6e 73 74 72 61 69 6e 74 73 20 0d 0a 20 20 20 20  nstraints ..    
5e80: 20 20 20 20 2f 2f 2f 20 61 73 20 69 74 20 63 61      /// as it ca
5e90: 6e 2e 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70  n. So, for examp
5ea0: 6c 65 2c 20 69 66 20 74 68 65 20 57 48 45 52 45  le, if the WHERE
5eb0: 20 63 6c 61 75 73 65 20 63 6f 6e 74 61 69 6e 65   clause containe
5ec0: 64 20 73 6f 6d 65 74 68 69 6e 67 20 0d 0a 20 20  d something ..  
5ed0: 20 20 20 20 20 20 2f 2f 2f 20 6c 69 6b 65 20 74        /// like t
5ee0: 68 69 73 3a 0d 0a 20 20 20 20 20 20 20 20 2f 2f  his:..        //
5ef0: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  / </para>..     
5f00: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f     /// <para><co
5f10: 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  de>..        ///
5f20: 20 20 20 20 20 20 78 20 42 45 54 57 45 45 4e 20        x BETWEEN 
5f30: 31 30 20 41 4e 44 20 31 30 30 20 41 4e 44 20 39  10 AND 100 AND 9
5f40: 39 39 26 67 74 3b 79 0d 0a 20 20 20 20 20 20 20  99&gt;y..       
5f50: 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61   /// </code></pa
5f60: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
5f70: 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20   <para>..       
5f80: 20 2f 2f 2f 20 54 68 65 20 71 75 65 72 79 20 6f   /// The query o
5f90: 70 74 69 6d 69 7a 65 72 20 6d 69 67 68 74 20 74  ptimizer might t
5fa0: 72 61 6e 73 6c 61 74 65 20 74 68 69 73 20 69 6e  ranslate this in
5fb0: 74 6f 20 74 68 72 65 65 20 73 65 70 61 72 61 74  to three separat
5fc0: 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 3a 0d 0a  e constraints:..
5fd0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
5fe0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
5ff0: 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20   <para><code>.. 
6000: 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 20         ///      
6010: 78 20 26 67 74 3b 3d 20 31 30 0d 0a 20 20 20 20  x &gt;= 10..    
6020: 20 20 20 20 2f 2f 2f 20 20 20 20 20 20 78 20 26      ///      x &
6030: 6c 74 3b 3d 20 31 30 30 0d 0a 20 20 20 20 20 20  lt;= 100..      
6040: 20 20 2f 2f 2f 20 20 20 20 20 20 79 20 26 6c 74    ///      y &lt
6050: 3b 20 39 39 39 0d 0a 20 20 20 20 20 20 20 20 2f  ; 999..        /
6060: 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61  // </code></para
6070: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
6080: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
6090: 2f 2f 20 46 6f 72 20 65 61 63 68 20 63 6f 6e 73  // For each cons
60a0: 74 72 61 69 6e 74 2c 20 74 68 65 20 61 43 6f 6e  traint, the aCon
60b0: 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d  straint[].iColum
60c0: 6e 20 66 69 65 6c 64 20 69 6e 64 69 63 61 74 65  n field indicate
60d0: 73 20 77 68 69 63 68 20 0d 0a 20 20 20 20 20 20  s which ..      
60e0: 20 20 2f 2f 2f 20 63 6f 6c 75 6d 6e 20 61 70 70    /// column app
60f0: 65 61 72 73 20 6f 6e 20 74 68 65 20 6c 65 66 74  ears on the left
6100: 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68  -hand side of th
6110: 65 20 63 6f 6e 73 74 72 61 69 6e 74 2e 0d 0a 20  e constraint... 
6120: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 66         /// The f
6130: 69 72 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  irst column of t
6140: 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
6150: 20 69 73 20 63 6f 6c 75 6d 6e 20 30 2e 20 0d 0a   is column 0. ..
6160: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20          /// The 
6170: 72 6f 77 69 64 20 6f 66 20 74 68 65 20 76 69 72  rowid of the vir
6180: 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20 63 6f  tual table is co
6190: 6c 75 6d 6e 20 2d 31 2e 20 0d 0a 20 20 20 20 20  lumn -1. ..     
61a0: 20 20 20 2f 2f 2f 20 54 68 65 20 61 43 6f 6e 73     /// The aCons
61b0: 74 72 61 69 6e 74 5b 5d 2e 6f 70 20 66 69 65 6c  traint[].op fiel
61c0: 64 20 69 6e 64 69 63 61 74 65 73 20 77 68 69 63  d indicates whic
61d0: 68 20 6f 70 65 72 61 74 6f 72 20 69 73 20 75 73  h operator is us
61e0: 65 64 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ed. ..        //
61f0: 2f 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4e 44  / The SQLITE_IND
6200: 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 2a 20  EX_CONSTRAINT_* 
6210: 63 6f 6e 73 74 61 6e 74 73 20 6d 61 70 20 69 6e  constants map in
6220: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
6230: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e  ..        /// in
6240: 74 6f 20 6f 70 65 72 61 74 6f 72 20 76 61 6c 75  to operator valu
6250: 65 73 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  es...        ///
6260: 20 43 6f 6c 75 6d 6e 73 20 6f 63 63 75 72 20 69   Columns occur i
6270: 6e 20 74 68 65 20 6f 72 64 65 72 20 74 68 65 79  n the order they
6280: 20 77 65 72 65 20 64 65 66 69 6e 65 64 20 62 79   were defined by
6290: 20 74 68 65 20 63 61 6c 6c 20 74 6f 0d 0a 20 20   the call to..  
62a0: 20 20 20 20 20 20 2f 2f 2f 20 73 71 6c 69 74 65        /// sqlite
62b0: 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 29  3_declare_vtab()
62c0: 20 69 6e 20 74 68 65 20 78 43 72 65 61 74 65 20   in the xCreate 
62d0: 6f 72 20 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68  or xConnect meth
62e0: 6f 64 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  od...        ///
62f0: 20 48 69 64 64 65 6e 20 63 6f 6c 75 6d 6e 73 20   Hidden columns 
6300: 61 72 65 20 63 6f 75 6e 74 65 64 20 77 68 65 6e  are counted when
6310: 20 64 65 74 65 72 6d 69 6e 69 6e 67 20 74 68 65   determining the
6320: 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 2e 0d 0a   column index...
6330: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
6340: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
6350: 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20   <para>..       
6360: 20 2f 2f 2f 20 54 68 65 20 61 43 6f 6e 73 74 72   /// The aConstr
6370: 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 63 6f 6e  aint[] array con
6380: 74 61 69 6e 73 20 69 6e 66 6f 72 6d 61 74 69 6f  tains informatio
6390: 6e 20 61 62 6f 75 74 20 61 6c 6c 20 63 6f 6e 73  n about all cons
63a0: 74 72 61 69 6e 74 73 20 0d 0a 20 20 20 20 20 20  traints ..      
63b0: 20 20 2f 2f 2f 20 74 68 61 74 20 61 70 70 6c 79    /// that apply
63c0: 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 20   to the virtual 
63d0: 74 61 62 6c 65 2e 20 42 75 74 20 73 6f 6d 65 20  table. But some 
63e0: 6f 66 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  of the constrain
63f0: 74 73 20 6d 69 67 68 74 0d 0a 20 20 20 20 20 20  ts might..      
6400: 20 20 2f 2f 2f 20 6e 6f 74 20 62 65 20 75 73 61    /// not be usa
6410: 62 6c 65 20 62 65 63 61 75 73 65 20 6f 66 20 74  ble because of t
6420: 68 65 20 77 61 79 20 74 61 62 6c 65 73 20 61 72  he way tables ar
6430: 65 20 6f 72 64 65 72 65 64 20 69 6e 20 61 20 6a  e ordered in a j
6440: 6f 69 6e 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f  oin. ..        /
6450: 2f 2f 20 54 68 65 20 78 42 65 73 74 49 6e 64 65  // The xBestInde
6460: 78 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 74 68  x method must th
6470: 65 72 65 66 6f 72 65 20 6f 6e 6c 79 20 63 6f 6e  erefore only con
6480: 73 69 64 65 72 20 63 6f 6e 73 74 72 61 69 6e 74  sider constraint
6490: 73 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  s ..        /// 
64a0: 74 68 61 74 20 68 61 76 65 20 61 6e 20 61 43 6f  that have an aCo
64b0: 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c  nstraint[].usabl
64c0: 65 20 66 6c 61 67 20 77 68 69 63 68 20 69 73 20  e flag which is 
64d0: 74 72 75 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f  true...        /
64e0: 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  // </para>..    
64f0: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a      /// <para>..
6500: 20 20 20 20 20 20 20 20 2f 2f 2f 20 49 6e 20 61          /// In a
6510: 64 64 69 74 69 6f 6e 20 74 6f 20 57 48 45 52 45  ddition to WHERE
6520: 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69   clause constrai
6530: 6e 74 73 2c 20 74 68 65 20 53 51 4c 69 74 65 20  nts, the SQLite 
6540: 63 6f 72 65 20 61 6c 73 6f 20 0d 0a 20 20 20 20  core also ..    
6550: 20 20 20 20 2f 2f 2f 20 74 65 6c 6c 73 20 74 68      /// tells th
6560: 65 20 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74  e xBestIndex met
6570: 68 6f 64 20 61 62 6f 75 74 20 74 68 65 20 4f 52  hod about the OR
6580: 44 45 52 20 42 59 20 63 6c 61 75 73 65 2e 20 0d  DER BY clause. .
6590: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 28 49 6e  .        /// (In
65a0: 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75   an aggregate qu
65b0: 65 72 79 2c 20 74 68 65 20 53 51 4c 69 74 65 20  ery, the SQLite 
65c0: 63 6f 72 65 20 6d 69 67 68 74 20 70 75 74 20 69  core might put i
65d0: 6e 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73  n GROUP BY claus
65e0: 65 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e ..        /// 
65f0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 20 70  information in p
6600: 6c 61 63 65 20 6f 66 20 74 68 65 20 4f 52 44 45  lace of the ORDE
6610: 52 20 42 59 20 63 6c 61 75 73 65 20 69 6e 66 6f  R BY clause info
6620: 72 6d 61 74 69 6f 6e 2c 20 62 75 74 20 74 68 69  rmation, but thi
6630: 73 20 66 61 63 74 0d 0a 20 20 20 20 20 20 20 20  s fact..        
6640: 2f 2f 2f 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d  /// should not m
6650: 61 6b 65 20 61 6e 79 20 64 69 66 66 65 72 65 6e  ake any differen
6660: 63 65 20 74 6f 20 74 68 65 20 78 42 65 73 74 49  ce to the xBestI
6670: 6e 64 65 78 20 6d 65 74 68 6f 64 2e 29 20 0d 0a  ndex method.) ..
6680: 20 20 20 20 20 20 20 20 2f 2f 2f 20 49 66 20 61          /// If a
6690: 6c 6c 20 74 65 72 6d 73 20 6f 66 20 74 68 65 20  ll terms of the 
66a0: 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20  ORDER BY clause 
66b0: 61 72 65 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74  are columns in t
66c0: 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
66d0: 2c 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  , ..        /// 
66e0: 74 68 65 6e 20 6e 4f 72 64 65 72 42 79 20 77 69  then nOrderBy wi
66f0: 6c 6c 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72  ll be the number
6700: 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 74 68 65   of terms in the
6710: 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
6720: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 61   ..        /// a
6730: 6e 64 20 74 68 65 20 61 4f 72 64 65 72 42 79 5b  nd the aOrderBy[
6740: 5d 20 61 72 72 61 79 20 77 69 6c 6c 20 69 64 65  ] array will ide
6750: 6e 74 69 66 79 20 74 68 65 20 63 6f 6c 75 6d 6e  ntify the column
6760: 20 66 6f 72 20 65 61 63 68 20 74 65 72 6d 20 0d   for each term .
6770: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e 20  .        /// in 
6780: 74 68 65 20 6f 72 64 65 72 20 62 79 20 63 6c 61  the order by cla
6790: 75 73 65 20 61 6e 64 20 77 68 65 74 68 65 72 20  use and whether 
67a0: 6f 72 20 6e 6f 74 20 74 68 61 74 20 63 6f 6c 75  or not that colu
67b0: 6d 6e 20 69 73 20 41 53 43 20 6f 72 20 44 45 53  mn is ASC or DES
67c0: 43 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  C...        /// 
67d0: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
67e0: 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20   /// <para>..   
67f0: 20 20 20 20 20 2f 2f 2f 20 47 69 76 65 6e 20 61       /// Given a
6800: 6c 6c 20 6f 66 20 74 68 65 20 69 6e 66 6f 72 6d  ll of the inform
6810: 61 74 69 6f 6e 20 61 62 6f 76 65 2c 20 74 68 65  ation above, the
6820: 20 6a 6f 62 20 6f 66 20 74 68 65 20 78 42 65 73   job of the xBes
6830: 74 49 6e 64 65 78 20 0d 0a 20 20 20 20 20 20 20  tIndex ..       
6840: 20 2f 2f 2f 20 6d 65 74 68 6f 64 20 69 74 20 74   /// method it t
6850: 6f 20 66 69 67 75 72 65 20 6f 75 74 20 74 68 65  o figure out the
6860: 20 62 65 73 74 20 77 61 79 20 74 6f 20 73 65 61   best way to sea
6870: 72 63 68 20 74 68 65 20 76 69 72 74 75 61 6c 20  rch the virtual 
6880: 74 61 62 6c 65 2e 0d 0a 20 20 20 20 20 20 20 20  table...        
6890: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
68a0: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
68b0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65  .        /// The
68c0: 20 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68   xBestIndex meth
68d0: 6f 64 20 66 69 6c 6c 73 20 74 68 65 20 69 64 78  od fills the idx
68e0: 4e 75 6d 20 61 6e 64 20 69 64 78 53 74 72 20 66  Num and idxStr f
68f0: 69 65 6c 64 73 20 77 69 74 68 20 0d 0a 20 20 20  ields with ..   
6900: 20 20 20 20 20 2f 2f 2f 20 69 6e 66 6f 72 6d 61       /// informa
6910: 74 69 6f 6e 20 74 68 61 74 20 63 6f 6d 6d 75 6e  tion that commun
6920: 69 63 61 74 65 73 20 61 6e 20 69 6e 64 65 78 69  icates an indexi
6930: 6e 67 20 73 74 72 61 74 65 67 79 20 74 6f 20 74  ng strategy to t
6940: 68 65 20 78 46 69 6c 74 65 72 20 0d 0a 20 20 20  he xFilter ..   
6950: 20 20 20 20 20 2f 2f 2f 20 6d 65 74 68 6f 64 2e       /// method.
6960: 20 54 68 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e   The information
6970: 20 69 6e 20 69 64 78 4e 75 6d 20 61 6e 64 20 69   in idxNum and i
6980: 64 78 53 74 72 20 69 73 20 61 72 62 69 74 72 61  dxStr is arbitra
6990: 72 79 20 61 73 20 66 61 72 20 0d 0a 20 20 20 20  ry as far ..    
69a0: 20 20 20 20 2f 2f 2f 20 61 73 20 74 68 65 20 53      /// as the S
69b0: 51 4c 69 74 65 20 63 6f 72 65 20 69 73 20 63 6f  QLite core is co
69c0: 6e 63 65 72 6e 65 64 2e 20 54 68 65 20 53 51 4c  ncerned. The SQL
69d0: 69 74 65 20 63 6f 72 65 20 6a 75 73 74 20 63 6f  ite core just co
69e0: 70 69 65 73 20 74 68 65 20 0d 0a 20 20 20 20 20  pies the ..     
69f0: 20 20 20 2f 2f 2f 20 69 6e 66 6f 72 6d 61 74 69     /// informati
6a00: 6f 6e 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  on through to th
6a10: 65 20 78 46 69 6c 74 65 72 20 6d 65 74 68 6f 64  e xFilter method
6a20: 2e 20 41 6e 79 20 64 65 73 69 72 65 64 20 6d 65  . Any desired me
6a30: 61 6e 69 6e 67 20 63 61 6e 20 0d 0a 20 20 20 20  aning can ..    
6a40: 20 20 20 20 2f 2f 2f 20 62 65 20 61 73 73 69 67      /// be assig
6a50: 6e 65 64 20 74 6f 20 69 64 78 4e 75 6d 20 61 6e  ned to idxNum an
6a60: 64 20 69 64 78 53 74 72 20 61 73 20 6c 6f 6e 67  d idxStr as long
6a70: 20 61 73 20 78 42 65 73 74 49 6e 64 65 78 20 61   as xBestIndex a
6a80: 6e 64 20 78 46 69 6c 74 65 72 20 0d 0a 20 20 20  nd xFilter ..   
6a90: 20 20 20 20 20 2f 2f 2f 20 61 67 72 65 65 20 6f       /// agree o
6aa0: 6e 20 77 68 61 74 20 74 68 61 74 20 6d 65 61 6e  n what that mean
6ab0: 69 6e 67 20 69 73 2e 0d 0a 20 20 20 20 20 20 20  ing is...       
6ac0: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
6ad0: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
6ae0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
6af0: 65 20 69 64 78 53 74 72 20 76 61 6c 75 65 20 6d  e idxStr value m
6b00: 61 79 20 62 65 20 61 20 73 74 72 69 6e 67 20 6f  ay be a string o
6b10: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 6e 20  btained from an 
6b20: 53 51 4c 69 74 65 0d 0a 20 20 20 20 20 20 20 20  SQLite..        
6b30: 2f 2f 2f 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  /// memory alloc
6b40: 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 73  ation function s
6b50: 75 63 68 20 61 73 20 73 71 6c 69 74 65 33 5f 6d  uch as sqlite3_m
6b60: 70 72 69 6e 74 66 28 29 2e 20 0d 0a 20 20 20 20  printf(). ..    
6b70: 20 20 20 20 2f 2f 2f 20 49 66 20 74 68 69 73 20      /// If this 
6b80: 69 73 20 74 68 65 20 63 61 73 65 2c 20 74 68 65  is the case, the
6b90: 6e 20 74 68 65 20 6e 65 65 64 54 6f 46 72 65 65  n the needToFree
6ba0: 49 64 78 53 74 72 20 66 6c 61 67 20 6d 75 73 74  IdxStr flag must
6bb0: 20 62 65 20 73 65 74 20 74 6f 20 0d 0a 20 20 20   be set to ..   
6bc0: 20 20 20 20 20 2f 2f 2f 20 74 72 75 65 20 73 6f       /// true so
6bd0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
6be0: 20 63 6f 72 65 20 77 69 6c 6c 20 6b 6e 6f 77 20   core will know 
6bf0: 74 6f 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  to call sqlite3_
6c00: 66 72 65 65 28 29 20 6f 6e 20 0d 0a 20 20 20 20  free() on ..    
6c10: 20 20 20 20 2f 2f 2f 20 74 68 61 74 20 73 74 72      /// that str
6c20: 69 6e 67 20 77 68 65 6e 20 69 74 20 68 61 73 20  ing when it has 
6c30: 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
6c40: 2c 20 61 6e 64 20 74 68 75 73 20 61 76 6f 69 64  , and thus avoid
6c50: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0d   a memory leak..
6c60: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
6c70: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
6c80: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
6c90: 20 20 2f 2f 2f 20 49 66 20 74 68 65 20 76 69 72    /// If the vir
6ca0: 74 75 61 6c 20 74 61 62 6c 65 20 77 69 6c 6c 20  tual table will 
6cb0: 6f 75 74 70 75 74 20 72 6f 77 73 20 69 6e 20 74  output rows in t
6cc0: 68 65 20 6f 72 64 65 72 20 73 70 65 63 69 66 69  he order specifi
6cd0: 65 64 20 62 79 20 0d 0a 20 20 20 20 20 20 20 20  ed by ..        
6ce0: 2f 2f 2f 20 74 68 65 20 4f 52 44 45 52 20 42 59  /// the ORDER BY
6cf0: 20 63 6c 61 75 73 65 2c 20 74 68 65 6e 20 74 68   clause, then th
6d00: 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65  e orderByConsume
6d10: 64 20 66 6c 61 67 20 6d 61 79 20 62 65 20 73 65  d flag may be se
6d20: 74 20 74 6f 20 0d 0a 20 20 20 20 20 20 20 20 2f  t to ..        /
6d30: 2f 2f 20 74 72 75 65 2e 20 49 66 20 74 68 65 20  // true. If the 
6d40: 6f 75 74 70 75 74 20 69 73 20 6e 6f 74 20 61 75  output is not au
6d50: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74  tomatically in t
6d60: 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72  he correct order
6d70: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74   ..        /// t
6d80: 68 65 6e 20 6f 72 64 65 72 42 79 43 6f 6e 73 75  hen orderByConsu
6d90: 6d 65 64 20 6d 75 73 74 20 62 65 20 6c 65 66 74  med must be left
6da0: 20 69 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20   in its default 
6db0: 66 61 6c 73 65 20 73 65 74 74 69 6e 67 2e 20 0d  false setting. .
6dc0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 69  .        /// Thi
6dd0: 73 20 77 69 6c 6c 20 69 6e 64 69 63 61 74 65 20  s will indicate 
6de0: 74 6f 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  to the SQLite co
6df0: 72 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20  re that it will 
6e00: 6e 65 65 64 20 74 6f 20 64 6f 20 61 20 0d 0a 20  need to do a .. 
6e10: 20 20 20 20 20 20 20 2f 2f 2f 20 73 65 70 61 72         /// separ
6e20: 61 74 65 20 73 6f 72 74 69 6e 67 20 70 61 73 73  ate sorting pass
6e30: 20 6f 76 65 72 20 74 68 65 20 64 61 74 61 20 61   over the data a
6e40: 66 74 65 72 20 69 74 20 63 6f 6d 65 73 20 6f 75  fter it comes ou
6e50: 74 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c  t of the virtual
6e60: 20 74 61 62 6c 65 2e 0d 0a 20 20 20 20 20 20 20   table...       
6e70: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
6e80: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
6e90: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
6ea0: 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 20  e estimatedCost 
6eb0: 66 69 65 6c 64 20 73 68 6f 75 6c 64 20 62 65 20  field should be 
6ec0: 73 65 74 20 74 6f 20 74 68 65 20 65 73 74 69 6d  set to the estim
6ed0: 61 74 65 64 20 6e 75 6d 62 65 72 0d 0a 20 20 20  ated number..   
6ee0: 20 20 20 20 20 2f 2f 2f 20 6f 66 20 64 69 73 6b       /// of disk
6ef0: 20 61 63 63 65 73 73 20 6f 70 65 72 61 74 69 6f   access operatio
6f00: 6e 73 20 72 65 71 75 69 72 65 64 20 74 6f 20 65  ns required to e
6f10: 78 65 63 75 74 65 20 74 68 69 73 20 71 75 65 72  xecute this quer
6f20: 79 20 61 67 61 69 6e 73 74 20 0d 0a 20 20 20 20  y against ..    
6f30: 20 20 20 20 2f 2f 2f 20 74 68 65 20 76 69 72 74      /// the virt
6f40: 75 61 6c 20 74 61 62 6c 65 2e 20 54 68 65 20 53  ual table. The S
6f50: 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20  QLite core will 
6f60: 6f 66 74 65 6e 20 63 61 6c 6c 20 78 42 65 73 74  often call xBest
6f70: 49 6e 64 65 78 20 0d 0a 20 20 20 20 20 20 20 20  Index ..        
6f80: 2f 2f 2f 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  /// multiple tim
6f90: 65 73 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  es with differen
6fa0: 74 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 20 6f  t constraints, o
6fb0: 62 74 61 69 6e 20 6d 75 6c 74 69 70 6c 65 20 63  btain multiple c
6fc0: 6f 73 74 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ost..        ///
6fd0: 20 65 73 74 69 6d 61 74 65 73 2c 20 74 68 65 6e   estimates, then
6fe0: 20 63 68 6f 6f 73 65 20 74 68 65 20 71 75 65 72   choose the quer
6ff0: 79 20 70 6c 61 6e 20 74 68 61 74 20 67 69 76 65  y plan that give
7000: 73 20 74 68 65 20 6c 6f 77 65 73 74 20 65 73 74  s the lowest est
7010: 69 6d 61 74 65 2e 0d 0a 20 20 20 20 20 20 20 20  imate...        
7020: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
7030: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
7040: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 49 66 20  .        /// If 
7050: 74 68 65 20 63 75 72 72 65 6e 74 20 76 65 72 73  the current vers
7060: 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 69 73  ion of SQLite is
7070: 20 33 2e 38 2e 32 20 6f 72 20 67 72 65 61 74 65   3.8.2 or greate
7080: 72 2c 20 74 68 65 20 65 73 74 69 6d 61 74 65 64  r, the estimated
7090: 52 6f 77 73 0d 0a 20 20 20 20 20 20 20 20 2f 2f  Rows..        //
70a0: 2f 20 66 69 65 6c 64 20 6d 61 79 20 62 65 20 73  / field may be s
70b0: 65 74 20 74 6f 20 61 6e 20 65 73 74 69 6d 61 74  et to an estimat
70c0: 65 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  e of the number 
70d0: 6f 66 20 72 6f 77 73 20 72 65 74 75 72 6e 65 64  of rows returned
70e0: 20 62 79 20 74 68 65 0d 0a 20 20 20 20 20 20 20   by the..       
70f0: 20 2f 2f 2f 20 70 72 6f 70 6f 73 65 64 20 71 75   /// proposed qu
7100: 65 72 79 20 70 6c 61 6e 2e 20 49 66 20 74 68 69  ery plan. If thi
7110: 73 20 76 61 6c 75 65 20 69 73 20 6e 6f 74 20 65  s value is not e
7120: 78 70 6c 69 63 69 74 6c 79 20 73 65 74 2c 20 74  xplicitly set, t
7130: 68 65 20 64 65 66 61 75 6c 74 20 0d 0a 20 20 20  he default ..   
7140: 20 20 20 20 20 2f 2f 2f 20 65 73 74 69 6d 61 74       /// estimat
7150: 65 20 6f 66 20 32 35 20 72 6f 77 73 20 69 73 20  e of 25 rows is 
7160: 75 73 65 64 2e 0d 0a 20 20 20 20 20 20 20 20 2f  used...        /
7170: 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  // </para>..    
7180: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a      /// <para>..
7190: 20 20 20 20 20 20 20 20 2f 2f 2f 20 49 66 20 74          /// If t
71a0: 68 65 20 63 75 72 72 65 6e 74 20 76 65 72 73 69  he current versi
71b0: 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20  on of SQLite is 
71c0: 33 2e 39 2e 30 20 6f 72 20 67 72 65 61 74 65 72  3.9.0 or greater
71d0: 2c 20 74 68 65 20 69 64 78 46 6c 61 67 73 20 66  , the idxFlags f
71e0: 69 65 6c 64 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ield..        //
71f0: 2f 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20  / may be set to 
7200: 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 53 43 41  SQLITE_INDEX_SCA
7210: 4e 5f 55 4e 49 51 55 45 20 74 6f 20 69 6e 64 69  N_UNIQUE to indi
7220: 63 61 74 65 20 74 68 61 74 20 74 68 65 20 76 69  cate that the vi
7230: 72 74 75 61 6c 20 74 61 62 6c 65 0d 0a 20 20 20  rtual table..   
7240: 20 20 20 20 20 2f 2f 2f 20 77 69 6c 6c 20 72 65       /// will re
7250: 74 75 72 6e 20 6f 6e 6c 79 20 7a 65 72 6f 20 6f  turn only zero o
7260: 72 20 6f 6e 65 20 72 6f 77 73 20 67 69 76 65 6e  r one rows given
7270: 20 74 68 65 20 69 6e 70 75 74 20 63 6f 6e 73 74   the input const
7280: 72 61 69 6e 74 73 2e 20 20 41 64 64 69 74 69 6f  raints.  Additio
7290: 6e 61 6c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  nal..        ///
72a0: 20 62 69 74 73 20 6f 66 20 74 68 65 20 69 64 78   bits of the idx
72b0: 46 6c 61 67 73 20 66 69 65 6c 64 20 6d 69 67 68  Flags field migh
72c0: 74 20 62 65 20 75 6e 64 65 72 73 74 6f 6f 64 20  t be understood 
72d0: 69 6e 20 6c 61 74 65 72 20 76 65 72 73 69 6f 6e  in later version
72e0: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0d 0a 20 20  s of SQLite...  
72f0: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61        /// </para
7300: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
7310: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
7320: 2f 2f 20 54 68 65 20 61 43 6f 6e 73 74 72 61 69  // The aConstrai
7330: 6e 74 55 73 61 67 65 5b 5d 20 61 72 72 61 79 20  ntUsage[] array 
7340: 63 6f 6e 74 61 69 6e 73 20 6f 6e 65 20 65 6c 65  contains one ele
7350: 6d 65 6e 74 20 66 6f 72 20 65 61 63 68 20 6f 66  ment for each of
7360: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74   ..        /// t
7370: 68 65 20 6e 43 6f 6e 73 74 72 61 69 6e 74 20 63  he nConstraint c
7380: 6f 6e 73 74 72 61 69 6e 74 73 20 69 6e 20 74 68  onstraints in th
7390: 65 20 69 6e 70 75 74 73 20 73 65 63 74 69 6f 6e  e inputs section
73a0: 20 6f 66 20 74 68 65 20 0d 0a 20 20 20 20 20 20   of the ..      
73b0: 20 20 2f 2f 2f 20 73 71 6c 69 74 65 33 5f 69 6e    /// sqlite3_in
73c0: 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75  dex_info structu
73d0: 72 65 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  re. ..        //
73e0: 2f 20 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e  / The aConstrain
73f0: 74 55 73 61 67 65 5b 5d 20 61 72 72 61 79 20 69  tUsage[] array i
7400: 73 20 75 73 65 64 20 62 79 20 78 42 65 73 74 49  s used by xBestI
7410: 6e 64 65 78 20 74 6f 20 74 65 6c 6c 20 74 68 65  ndex to tell the
7420: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 63   ..        /// c
7430: 6f 72 65 20 68 6f 77 20 69 74 20 69 73 20 75 73  ore how it is us
7440: 69 6e 67 20 74 68 65 20 63 6f 6e 73 74 72 61 69  ing the constrai
7450: 6e 74 73 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  nts...        //
7460: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  / </para>..     
7470: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20     /// <para>.. 
7480: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 78         /// The x
7490: 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64  BestIndex method
74a0: 20 6d 61 79 20 73 65 74 20 61 43 6f 6e 73 74 72   may set aConstr
74b0: 61 69 6e 74 55 73 61 67 65 5b 5d 2e 61 72 67 76  aintUsage[].argv
74c0: 49 6e 64 65 78 20 0d 0a 20 20 20 20 20 20 20 20  Index ..        
74d0: 2f 2f 2f 20 65 6e 74 72 69 65 73 20 74 6f 20 76  /// entries to v
74e0: 61 6c 75 65 73 20 67 72 65 61 74 65 72 20 74 68  alues greater th
74f0: 61 6e 20 7a 65 72 6f 2e 20 0d 0a 20 20 20 20 20  an zero. ..     
7500: 20 20 20 2f 2f 2f 20 45 78 61 63 74 6c 79 20 6f     /// Exactly o
7510: 6e 65 20 65 6e 74 72 79 20 73 68 6f 75 6c 64 20  ne entry should 
7520: 62 65 20 73 65 74 20 74 6f 20 31 2c 20 61 6e 6f  be set to 1, ano
7530: 74 68 65 72 20 74 6f 20 32 2c 20 61 6e 6f 74 68  ther to 2, anoth
7540: 65 72 20 74 6f 20 33 2c 20 0d 0a 20 20 20 20 20  er to 3, ..     
7550: 20 20 20 2f 2f 2f 20 61 6e 64 20 73 6f 20 66 6f     /// and so fo
7560: 72 74 68 20 75 70 20 74 6f 20 61 73 20 6d 61 6e  rth up to as man
7570: 79 20 6f 72 20 61 73 20 66 65 77 20 61 73 20 74  y or as few as t
7580: 68 65 20 78 42 65 73 74 49 6e 64 65 78 20 6d 65  he xBestIndex me
7590: 74 68 6f 64 20 77 61 6e 74 73 2e 20 0d 0a 20 20  thod wants. ..  
75a0: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 45 58        /// The EX
75b0: 50 52 20 6f 66 20 74 68 65 20 63 6f 72 72 65 73  PR of the corres
75c0: 70 6f 6e 64 69 6e 67 20 63 6f 6e 73 74 72 61 69  ponding constrai
75d0: 6e 74 73 20 77 69 6c 6c 20 74 68 65 6e 20 62 65  nts will then be
75e0: 20 70 61 73 73 65 64 20 0d 0a 20 20 20 20 20 20   passed ..      
75f0: 20 20 2f 2f 2f 20 69 6e 20 61 73 20 74 68 65 20    /// in as the 
7600: 61 72 67 76 5b 5d 20 70 61 72 61 6d 65 74 65 72  argv[] parameter
7610: 73 20 74 6f 20 78 46 69 6c 74 65 72 2e 0d 0a 20  s to xFilter... 
7620: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
7630: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
7640: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
7650: 2f 2f 2f 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  /// For example,
7660: 20 69 66 20 74 68 65 20 61 43 6f 6e 73 74 72 61   if the aConstra
7670: 69 6e 74 5b 33 5d 2e 61 72 67 76 49 6e 64 65 78  int[3].argvIndex
7680: 20 69 73 20 73 65 74 20 74 6f 20 31 2c 20 74 68   is set to 1, th
7690: 65 6e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  en ..        ///
76a0: 20 77 68 65 6e 20 78 46 69 6c 74 65 72 20 69 73   when xFilter is
76b0: 20 63 61 6c 6c 65 64 2c 20 74 68 65 20 61 72 67   called, the arg
76c0: 76 5b 30 5d 20 70 61 73 73 65 64 20 74 6f 20 78  v[0] passed to x
76d0: 46 69 6c 74 65 72 20 77 69 6c 6c 20 68 61 76 65  Filter will have
76e0: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74   ..        /// t
76f0: 68 65 20 45 58 50 52 20 76 61 6c 75 65 20 6f 66  he EXPR value of
7700: 20 74 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74   the aConstraint
7710: 5b 33 5d 20 63 6f 6e 73 74 72 61 69 6e 74 2e 0d  [3] constraint..
7720: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
7730: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
7740: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
7750: 20 20 2f 2f 2f 20 42 79 20 64 65 66 61 75 6c 74    /// By default
7760: 2c 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  , the SQLite cor
7770: 65 20 64 6f 75 62 6c 65 20 63 68 65 63 6b 73 20  e double checks 
7780: 61 6c 6c 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  all constraints 
7790: 6f 6e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  on ..        ///
77a0: 20 65 61 63 68 20 72 6f 77 20 6f 66 20 74 68 65   each row of the
77b0: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 74   virtual table t
77c0: 68 61 74 20 69 74 20 72 65 63 65 69 76 65 73 2e  hat it receives.
77d0: 20 49 66 20 73 75 63 68 20 61 20 63 68 65 63 6b   If such a check
77e0: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69   ..        /// i
77f0: 73 20 72 65 64 75 6e 64 61 6e 74 2c 20 74 68 65  s redundant, the
7800: 20 78 42 65 73 74 46 69 6c 74 65 72 20 6d 65 74   xBestFilter met
7810: 68 6f 64 20 63 61 6e 20 73 75 70 70 72 65 73 73  hod can suppress
7820: 20 74 68 61 74 20 64 6f 75 62 6c 65 2d 63 68 65   that double-che
7830: 63 6b 20 62 79 20 0d 0a 20 20 20 20 20 20 20 20  ck by ..        
7840: 2f 2f 2f 20 73 65 74 74 69 6e 67 20 61 43 6f 6e  /// setting aCon
7850: 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f  straintUsage[].o
7860: 6d 69 74 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  mit...        //
7870: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  / </para>..     
7880: 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79     /// </summary
7890: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
78a0: 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 56 74 61  param name="pVta
78b0: 62 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  b">..        ///
78c0: 20 54 68 65 20 6e 61 74 69 76 65 20 70 6f 69 6e   The native poin
78d0: 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
78e0: 65 33 5f 76 74 61 62 20 64 65 72 69 76 65 64 20  e3_vtab derived 
78f0: 73 74 72 75 63 74 75 72 65 2e 0d 0a 20 20 20 20  structure...    
7900: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e      /// </param>
7910: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
7920: 61 72 61 6d 20 6e 61 6d 65 3d 22 70 49 6e 64 65  aram name="pInde
7930: 78 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  x">..        ///
7940: 20 54 68 65 20 6e 61 74 69 76 65 20 70 6f 69 6e   The native poin
7950: 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
7960: 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74  e3_index_info st
7970: 72 75 63 74 75 72 65 2e 0d 0a 20 20 20 20 20 20  ructure...      
7980: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a    /// </param>..
7990: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 72 65 74          /// <ret
79a0: 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 2f  urns>..        /
79b0: 2f 2f 20 41 20 73 74 61 6e 64 61 72 64 20 53 51  // A standard SQ
79c0: 4c 69 74 65 20 72 65 74 75 72 6e 20 63 6f 64 65  Lite return code
79d0: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
79e0: 2f 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20  /returns>..     
79f0: 20 20 20 53 51 4c 69 74 65 45 72 72 6f 72 43 6f     SQLiteErrorCo
7a00: 64 65 20 78 42 65 73 74 49 6e 64 65 78 28 0d 0a  de xBestIndex(..
7a10: 20 20 20 20 20 20 20 20 20 20 20 20 49 6e 74 50              IntP
7a20: 74 72 20 70 56 74 61 62 2c 0d 0a 20 20 20 20 20  tr pVtab,..     
7a30: 20 20 20 20 20 20 20 49 6e 74 50 74 72 20 70 49         IntPtr pI
7a40: 6e 64 65 78 0d 0a 20 20 20 20 20 20 20 20 20 20  ndex..          
7a50: 20 20 29 3b 0d 0a 0d 0a 20 20 20 20 20 20 20 20    );....        
7a60: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
7a70: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
7a80: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
7a90: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
7aa0: 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 20  ///////....     
7ab0: 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79 3e     /// <summary>
7ac0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
7ad0: 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20  ara><code>..    
7ae0: 20 20 20 20 2f 2f 2f 20 20 20 69 6e 74 20 28 2a      ///   int (*
7af0: 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c  xDisconnect)(sql
7b00: 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
7b10: 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  );..        /// 
7b20: 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a  </code></para>..
7b30: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
7b40: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
7b50: 54 68 69 73 20 6d 65 74 68 6f 64 20 72 65 6c 65  This method rele
7b60: 61 73 65 73 20 61 20 63 6f 6e 6e 65 63 74 69 6f  ases a connectio
7b70: 6e 20 74 6f 20 61 20 76 69 72 74 75 61 6c 20 74  n to a virtual t
7b80: 61 62 6c 65 2e 20 0d 0a 20 20 20 20 20 20 20 20  able. ..        
7b90: 2f 2f 2f 20 4f 6e 6c 79 20 74 68 65 20 73 71 6c  /// Only the sql
7ba0: 69 74 65 33 5f 76 74 61 62 20 6f 62 6a 65 63 74  ite3_vtab object
7bb0: 20 69 73 20 64 65 73 74 72 6f 79 65 64 2e 0d 0a   is destroyed...
7bc0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20          /// The 
7bd0: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 73  virtual table is
7be0: 20 6e 6f 74 20 64 65 73 74 72 6f 79 65 64 20 61   not destroyed a
7bf0: 6e 64 20 61 6e 79 20 62 61 63 6b 69 6e 67 20 73  nd any backing s
7c00: 74 6f 72 65 20 0d 0a 20 20 20 20 20 20 20 20 2f  tore ..        /
7c10: 2f 2f 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  // associated wi
7c20: 74 68 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  th the virtual t
7c30: 61 62 6c 65 20 70 65 72 73 69 73 74 73 2e 20 0d  able persists. .
7c40: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
7c50: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
7c60: 2f 20 54 68 69 73 20 6d 65 74 68 6f 64 20 75 6e  / This method un
7c70: 64 6f 65 73 20 74 68 65 20 77 6f 72 6b 20 6f 66  does the work of
7c80: 20 78 43 6f 6e 6e 65 63 74 2e 0d 0a 20 20 20 20   xConnect...    
7c90: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a      /// <para>..
7ca0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 69 73          /// This
7cb0: 20 6d 65 74 68 6f 64 20 69 73 20 61 20 64 65 73   method is a des
7cc0: 74 72 75 63 74 6f 72 20 66 6f 72 20 61 20 63 6f  tructor for a co
7cd0: 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20  nnection to the 
7ce0: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 0d 0a  virtual table...
7cf0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 43 6f 6e 74          /// Cont
7d00: 72 61 73 74 20 74 68 69 73 20 6d 65 74 68 6f 64  rast this method
7d10: 20 77 69 74 68 20 78 44 65 73 74 72 6f 79 2e 20   with xDestroy. 
7d20: 20 54 68 65 20 78 44 65 73 74 72 6f 79 20 69 73   The xDestroy is
7d30: 20 61 20 64 65 73 74 72 75 63 74 6f 72 0d 0a 20   a destructor.. 
7d40: 20 20 20 20 20 20 20 2f 2f 2f 20 66 6f 72 20 74         /// for t
7d50: 68 65 20 65 6e 74 69 72 65 20 76 69 72 74 75 61  he entire virtua
7d60: 6c 20 74 61 62 6c 65 2e 0d 0a 20 20 20 20 20 20  l table...      
7d70: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
7d80: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
7d90: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54  >..        /// T
7da0: 68 65 20 78 44 69 73 63 6f 6e 6e 65 63 74 20 6d  he xDisconnect m
7db0: 65 74 68 6f 64 20 69 73 20 72 65 71 75 69 72 65  ethod is require
7dc0: 64 20 66 6f 72 20 65 76 65 72 79 20 76 69 72 74  d for every virt
7dd0: 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
7de0: 65 6e 74 61 74 69 6f 6e 2c 0d 0a 20 20 20 20 20  entation,..     
7df0: 20 20 20 2f 2f 2f 20 74 68 6f 75 67 68 20 69 74     /// though it
7e00: 20 69 73 20 61 63 63 65 70 74 61 62 6c 65 20 66   is acceptable f
7e10: 6f 72 20 74 68 65 20 78 44 69 73 63 6f 6e 6e 65  or the xDisconne
7e20: 63 74 20 61 6e 64 20 78 44 65 73 74 72 6f 79 20  ct and xDestroy 
7e30: 6d 65 74 68 6f 64 73 20 74 6f 20 62 65 0d 0a 20  methods to be.. 
7e40: 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 20 73         /// the s
7e50: 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 69 66 20  ame function if 
7e60: 74 68 61 74 20 6d 61 6b 65 73 20 73 65 6e 73 65  that makes sense
7e70: 20 66 6f 72 20 74 68 65 20 70 61 72 74 69 63 75   for the particu
7e80: 6c 61 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c  lar virtual tabl
7e90: 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e...        /// 
7ea0: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
7eb0: 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d   /// </summary>.
7ec0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
7ed0: 72 61 6d 20 6e 61 6d 65 3d 22 70 56 74 61 62 22  ram name="pVtab"
7ee0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54  >..        /// T
7ef0: 68 65 20 6e 61 74 69 76 65 20 70 6f 69 6e 74 65  he native pointe
7f00: 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
7f10: 5f 76 74 61 62 20 64 65 72 69 76 65 64 20 73 74  _vtab derived st
7f20: 72 75 63 74 75 72 65 2e 0d 0a 20 20 20 20 20 20  ructure...      
7f30: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a    /// </param>..
7f40: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 72 65 74          /// <ret
7f50: 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 2f  urns>..        /
7f60: 2f 2f 20 41 20 73 74 61 6e 64 61 72 64 20 53 51  // A standard SQ
7f70: 4c 69 74 65 20 72 65 74 75 72 6e 20 63 6f 64 65  Lite return code
7f80: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
7f90: 2f 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20  /returns>..     
7fa0: 20 20 20 53 51 4c 69 74 65 45 72 72 6f 72 43 6f     SQLiteErrorCo
7fb0: 64 65 20 78 44 69 73 63 6f 6e 6e 65 63 74 28 0d  de xDisconnect(.
7fc0: 0a 20 20 20 20 20 20 20 20 20 20 20 20 49 6e 74  .            Int
7fd0: 50 74 72 20 70 56 74 61 62 0d 0a 20 20 20 20 20  Ptr pVtab..     
7fe0: 20 20 20 20 20 20 20 29 3b 0d 0a 0d 0a 20 20 20         );....   
7ff0: 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f       ///////////
8000: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8010: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8020: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8030: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a  ////////////....
8040: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 73 75 6d          /// <sum
8050: 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f  mary>..        /
8060: 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d  // <para><code>.
8070: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 69  .        ///   i
8080: 6e 74 20 28 2a 78 44 65 73 74 72 6f 79 29 28 73  nt (*xDestroy)(s
8090: 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
80a0: 61 62 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ab);..        //
80b0: 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e  / </code></para>
80c0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
80d0: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
80e0: 2f 20 54 68 69 73 20 6d 65 74 68 6f 64 20 72 65  / This method re
80f0: 6c 65 61 73 65 73 20 61 20 63 6f 6e 6e 65 63 74  leases a connect
8100: 69 6f 6e 20 74 6f 20 61 20 76 69 72 74 75 61 6c  ion to a virtual
8110: 20 74 61 62 6c 65 2c 20 6a 75 73 74 20 6c 69 6b   table, just lik
8120: 65 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e ..        /// 
8130: 74 68 65 20 78 44 69 73 63 6f 6e 6e 65 63 74 20  the xDisconnect 
8140: 6d 65 74 68 6f 64 2c 20 61 6e 64 20 69 74 20 61  method, and it a
8150: 6c 73 6f 20 64 65 73 74 72 6f 79 73 20 74 68 65  lso destroys the
8160: 20 75 6e 64 65 72 6c 79 69 6e 67 20 0d 0a 20 20   underlying ..  
8170: 20 20 20 20 20 20 2f 2f 2f 20 74 61 62 6c 65 20        /// table 
8180: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
8190: 54 68 69 73 20 6d 65 74 68 6f 64 20 75 6e 64 6f  This method undo
81a0: 65 73 20 74 68 65 20 77 6f 72 6b 20 6f 66 20 78  es the work of x
81b0: 43 72 65 61 74 65 2e 0d 0a 20 20 20 20 20 20 20  Create...       
81c0: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
81d0: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
81e0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
81f0: 65 20 78 44 69 73 63 6f 6e 6e 65 63 74 20 6d 65  e xDisconnect me
8200: 74 68 6f 64 20 69 73 20 63 61 6c 6c 65 64 20 77  thod is called w
8210: 68 65 6e 65 76 65 72 20 61 20 64 61 74 61 62 61  henever a databa
8220: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0d 0a 20  se connection.. 
8230: 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 61 74 20         /// that 
8240: 75 73 65 73 20 61 20 76 69 72 74 75 61 6c 20 74  uses a virtual t
8250: 61 62 6c 65 20 69 73 20 63 6c 6f 73 65 64 2e 20  able is closed. 
8260: 54 68 65 20 78 44 65 73 74 72 6f 79 20 6d 65 74  The xDestroy met
8270: 68 6f 64 20 69 73 20 6f 6e 6c 79 20 0d 0a 20 20  hod is only ..  
8280: 20 20 20 20 20 20 2f 2f 2f 20 63 61 6c 6c 65 64        /// called
8290: 20 77 68 65 6e 20 61 20 44 52 4f 50 20 54 41 42   when a DROP TAB
82a0: 4c 45 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  LE statement is 
82b0: 65 78 65 63 75 74 65 64 20 61 67 61 69 6e 73 74  executed against
82c0: 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
82d0: 6c 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  le...        ///
82e0: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
82f0: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
8300: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 44        /// The xD
8310: 65 73 74 72 6f 79 20 6d 65 74 68 6f 64 20 69 73  estroy method is
8320: 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 65 76   required for ev
8330: 65 72 79 20 76 69 72 74 75 61 6c 20 74 61 62 6c  ery virtual tabl
8340: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
8350: 2c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74  ,..        /// t
8360: 68 6f 75 67 68 20 69 74 20 69 73 20 61 63 63 65  hough it is acce
8370: 70 74 61 62 6c 65 20 66 6f 72 20 74 68 65 20 78  ptable for the x
8380: 44 69 73 63 6f 6e 6e 65 63 74 20 61 6e 64 20 78  Disconnect and x
8390: 44 65 73 74 72 6f 79 20 6d 65 74 68 6f 64 73 20  Destroy methods 
83a0: 74 6f 20 62 65 0d 0a 20 20 20 20 20 20 20 20 2f  to be..        /
83b0: 2f 2f 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  // the same func
83c0: 74 69 6f 6e 20 69 66 20 74 68 61 74 20 6d 61 6b  tion if that mak
83d0: 65 73 20 73 65 6e 73 65 20 66 6f 72 20 74 68 65  es sense for the
83e0: 20 70 61 72 74 69 63 75 6c 61 72 20 76 69 72 74   particular virt
83f0: 75 61 6c 20 74 61 62 6c 65 2e 0d 0a 20 20 20 20  ual table...    
8400: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
8410: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 73  .        /// </s
8420: 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20  ummary>..       
8430: 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65   /// <param name
8440: 3d 22 70 56 74 61 62 22 3e 0d 0a 20 20 20 20 20  ="pVtab">..     
8450: 20 20 20 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76     /// The nativ
8460: 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
8470: 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 64 65   sqlite3_vtab de
8480: 72 69 76 65 64 20 73 74 72 75 63 74 75 72 65 2e  rived structure.
8490: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
84a0: 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20  param>..        
84b0: 2f 2f 2f 20 3c 72 65 74 75 72 6e 73 3e 0d 0a 20  /// <returns>.. 
84c0: 20 20 20 20 20 20 20 2f 2f 2f 20 41 20 73 74 61         /// A sta
84d0: 6e 64 61 72 64 20 53 51 4c 69 74 65 20 72 65 74  ndard SQLite ret
84e0: 75 72 6e 20 63 6f 64 65 2e 0d 0a 20 20 20 20 20  urn code...     
84f0: 20 20 20 2f 2f 2f 20 3c 2f 72 65 74 75 72 6e 73     /// </returns
8500: 3e 0d 0a 20 20 20 20 20 20 20 20 53 51 4c 69 74  >..        SQLit
8510: 65 45 72 72 6f 72 43 6f 64 65 20 78 44 65 73 74  eErrorCode xDest
8520: 72 6f 79 28 0d 0a 20 20 20 20 20 20 20 20 20 20  roy(..          
8530: 20 20 49 6e 74 50 74 72 20 70 56 74 61 62 0d 0a    IntPtr pVtab..
8540: 20 20 20 20 20 20 20 20 20 20 20 20 29 3b 0d 0a              );..
8550: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f  ..        //////
8560: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8570: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8580: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8590: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
85a0: 2f 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  /....        ///
85b0: 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20   <summary>..    
85c0: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63      /// <para><c
85d0: 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ode>..        //
85e0: 2f 20 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /   int (*xOpen)
85f0: 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
8600: 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 76 74  VTab, sqlite3_vt
8610: 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43 75  ab_cursor **ppCu
8620: 72 73 6f 72 29 3b 0d 0a 20 20 20 20 20 20 20 20  rsor);..        
8630: 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72  /// </code></par
8640: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
8650: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
8660: 2f 2f 2f 20 54 68 65 20 78 4f 70 65 6e 20 6d 65  /// The xOpen me
8670: 74 68 6f 64 20 63 72 65 61 74 65 73 20 61 20 6e  thod creates a n
8680: 65 77 20 63 75 72 73 6f 72 20 75 73 65 64 20 66  ew cursor used f
8690: 6f 72 20 61 63 63 65 73 73 69 6e 67 20 28 72 65  or accessing (re
86a0: 61 64 20 61 6e 64 2f 6f 72 0d 0a 20 20 20 20 20  ad and/or..     
86b0: 20 20 20 2f 2f 2f 20 77 72 69 74 69 6e 67 29 20     /// writing) 
86c0: 61 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e  a virtual table.
86d0: 20 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69    A successful i
86e0: 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 69  nvocation of thi
86f0: 73 20 6d 65 74 68 6f 64 20 0d 0a 20 20 20 20 20  s method ..     
8700: 20 20 20 2f 2f 2f 20 77 69 6c 6c 20 61 6c 6c 6f     /// will allo
8710: 63 61 74 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  cate the memory 
8720: 66 6f 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  for the sqlite3_
8730: 76 74 61 62 5f 63 75 72 73 6f 72 20 28 6f 72 20  vtab_cursor (or 
8740: 61 20 73 75 62 63 6c 61 73 73 29 2c 0d 0a 20 20  a subclass),..  
8750: 20 20 20 20 20 20 2f 2f 2f 20 69 6e 69 74 69 61        /// initia
8760: 6c 69 7a 65 20 74 68 65 20 6e 65 77 20 6f 62 6a  lize the new obj
8770: 65 63 74 2c 20 61 6e 64 20 6d 61 6b 65 20 2a 70  ect, and make *p
8780: 70 43 75 72 73 6f 72 20 70 6f 69 6e 74 20 74 6f  pCursor point to
8790: 20 74 68 65 20 6e 65 77 20 6f 62 6a 65 63 74 2e   the new object.
87a0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
87b0: 65 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  e successful cal
87c0: 6c 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 53  l then returns S
87d0: 51 4c 49 54 45 5f 4f 4b 2e 0d 0a 20 20 20 20 20  QLITE_OK...     
87e0: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a     /// </para>..
87f0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
8800: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
8810: 46 6f 72 20 65 76 65 72 79 20 73 75 63 63 65 73  For every succes
8820: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 74 68 69  sful call to thi
8830: 73 20 6d 65 74 68 6f 64 2c 20 74 68 65 20 53 51  s method, the SQ
8840: 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 0d 0a  Lite core will..
8850: 20 20 20 20 20 20 20 20 2f 2f 2f 20 6c 61 74 65          /// late
8860: 72 20 69 6e 76 6f 6b 65 20 74 68 65 20 78 43 6c  r invoke the xCl
8870: 6f 73 65 20 6d 65 74 68 6f 64 20 74 6f 20 64 65  ose method to de
8880: 73 74 72 6f 79 20 0d 0a 20 20 20 20 20 20 20 20  stroy ..        
8890: 2f 2f 2f 20 74 68 65 20 61 6c 6c 6f 63 61 74 65  /// the allocate
88a0: 64 20 63 75 72 73 6f 72 2e 0d 0a 20 20 20 20 20  d cursor...     
88b0: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a     /// </para>..
88c0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
88d0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
88e0: 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  The xOpen method
88f0: 20 6e 65 65 64 20 6e 6f 74 20 69 6e 69 74 69 61   need not initia
8900: 6c 69 7a 65 20 74 68 65 20 70 56 74 61 62 20 66  lize the pVtab f
8910: 69 65 6c 64 20 6f 66 20 74 68 65 0d 0a 20 20 20  ield of the..   
8920: 20 20 20 20 20 2f 2f 2f 20 73 71 6c 69 74 65 33       /// sqlite3
8930: 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73 74 72  _vtab_cursor str
8940: 75 63 74 75 72 65 2e 20 20 54 68 65 20 53 51 4c  ucture.  The SQL
8950: 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 74 61  ite core will ta
8960: 6b 65 20 63 61 72 65 0d 0a 20 20 20 20 20 20 20  ke care..       
8970: 20 2f 2f 2f 20 6f 66 20 74 68 61 74 20 63 68 6f   /// of that cho
8980: 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  re automatically
8990: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
89a0: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
89b0: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20  /// <para>..    
89c0: 20 20 20 20 2f 2f 2f 20 41 20 76 69 72 74 75 61      /// A virtua
89d0: 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  l table implemen
89e0: 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 61  tation must be a
89f0: 62 6c 65 20 74 6f 20 73 75 70 70 6f 72 74 20 61  ble to support a
8a00: 6e 20 61 72 62 69 74 72 61 72 79 0d 0a 20 20 20  n arbitrary..   
8a10: 20 20 20 20 20 2f 2f 2f 20 6e 75 6d 62 65 72 20       /// number 
8a20: 6f 66 20 73 69 6d 75 6c 74 61 6e 65 6f 75 73 6c  of simultaneousl
8a30: 79 20 6f 70 65 6e 20 63 75 72 73 6f 72 73 2e 0d  y open cursors..
8a40: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
8a50: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
8a60: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
8a70: 20 20 2f 2f 2f 20 57 68 65 6e 20 69 6e 69 74 69    /// When initi
8a80: 61 6c 6c 79 20 6f 70 65 6e 65 64 2c 20 74 68 65  ally opened, the
8a90: 20 63 75 72 73 6f 72 20 69 73 20 69 6e 20 61 6e   cursor is in an
8aa0: 20 75 6e 64 65 66 69 6e 65 64 20 73 74 61 74 65   undefined state
8ab0: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54  ...        /// T
8ac0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77  he SQLite core w
8ad0: 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 78  ill invoke the x
8ae0: 46 69 6c 74 65 72 20 6d 65 74 68 6f 64 0d 0a 20  Filter method.. 
8af0: 20 20 20 20 20 20 20 2f 2f 2f 20 6f 6e 20 74 68         /// on th
8b00: 65 20 63 75 72 73 6f 72 20 70 72 69 6f 72 20 74  e cursor prior t
8b10: 6f 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  o any attempt to
8b20: 20 70 6f 73 69 74 69 6f 6e 20 6f 72 20 72 65 61   position or rea
8b30: 64 20 66 72 6f 6d 20 74 68 65 20 63 75 72 73 6f  d from the curso
8b40: 72 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  r...        /// 
8b50: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
8b60: 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20   /// <para>..   
8b70: 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 4f 70       /// The xOp
8b80: 65 6e 20 6d 65 74 68 6f 64 20 69 73 20 72 65 71  en method is req
8b90: 75 69 72 65 64 20 66 6f 72 20 65 76 65 72 79 20  uired for every 
8ba0: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d  virtual table im
8bb0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0d 0a 20  plementation... 
8bc0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
8bd0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
8be0: 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20  </summary>..    
8bf0: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e      /// <param n
8c00: 61 6d 65 3d 22 70 56 74 61 62 22 3e 0d 0a 20 20  ame="pVtab">..  
8c10: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e 61        /// The na
8c20: 74 69 76 65 20 70 6f 69 6e 74 65 72 20 74 6f 20  tive pointer to 
8c30: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 74 61 62  the sqlite3_vtab
8c40: 20 64 65 72 69 76 65 64 20 73 74 72 75 63 74 75   derived structu
8c50: 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  re...        ///
8c60: 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20   </param>..     
8c70: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61     /// <param na
8c80: 6d 65 3d 22 70 43 75 72 73 6f 72 22 3e 0d 0a 20  me="pCursor">.. 
8c90: 20 20 20 20 20 20 20 2f 2f 2f 20 55 70 6f 6e 20         /// Upon 
8ca0: 73 75 63 63 65 73 73 2c 20 74 68 69 73 20 70 61  success, this pa
8cb0: 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20  rameter must be 
8cc0: 6d 6f 64 69 66 69 65 64 20 74 6f 20 70 6f 69 6e  modified to poin
8cd0: 74 20 74 6f 20 74 68 65 20 6e 65 77 6c 79 0d 0a  t to the newly..
8ce0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 63 72 65 61          /// crea
8cf0: 74 65 64 20 6e 61 74 69 76 65 20 73 71 6c 69 74  ted native sqlit
8d00: 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 64  e3_vtab_cursor d
8d10: 65 72 69 76 65 64 20 73 74 72 75 63 74 75 72 65  erived structure
8d20: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
8d30: 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20  /param>..       
8d40: 20 2f 2f 2f 20 3c 72 65 74 75 72 6e 73 3e 0d 0a   /// <returns>..
8d50: 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 20 73 74          /// A st
8d60: 61 6e 64 61 72 64 20 53 51 4c 69 74 65 20 72 65  andard SQLite re
8d70: 74 75 72 6e 20 63 6f 64 65 2e 0d 0a 20 20 20 20  turn code...    
8d80: 20 20 20 20 2f 2f 2f 20 3c 2f 72 65 74 75 72 6e      /// </return
8d90: 73 3e 0d 0a 20 20 20 20 20 20 20 20 53 51 4c 69  s>..        SQLi
8da0: 74 65 45 72 72 6f 72 43 6f 64 65 20 78 4f 70 65  teErrorCode xOpe
8db0: 6e 28 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20  n(..            
8dc0: 49 6e 74 50 74 72 20 70 56 74 61 62 2c 0d 0a 20  IntPtr pVtab,.. 
8dd0: 20 20 20 20 20 20 20 20 20 20 20 72 65 66 20 49             ref I
8de0: 6e 74 50 74 72 20 70 43 75 72 73 6f 72 0d 0a 20  ntPtr pCursor.. 
8df0: 20 20 20 20 20 20 20 20 20 20 20 29 3b 0d 0a 0d             );...
8e00: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f  .        ///////
8e10: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8e20: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8e30: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8e40: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8e50: 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ....        /// 
8e60: 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20  <summary>..     
8e70: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f     /// <para><co
8e80: 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  de>..        ///
8e90: 20 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29     int (*xClose)
8ea0: 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
8eb0: 72 73 6f 72 2a 29 3b 0d 0a 20 20 20 20 20 20 20  rsor*);..       
8ec0: 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61   /// </code></pa
8ed0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
8ee0: 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20   <para>..       
8ef0: 20 2f 2f 2f 20 54 68 65 20 78 43 6c 6f 73 65 20   /// The xClose 
8f00: 6d 65 74 68 6f 64 20 63 6c 6f 73 65 73 20 61 20  method closes a 
8f10: 63 75 72 73 6f 72 20 70 72 65 76 69 6f 75 73 6c  cursor previousl
8f20: 79 20 6f 70 65 6e 65 64 20 62 79 20 0d 0a 20 20  y opened by ..  
8f30: 20 20 20 20 20 20 2f 2f 2f 20 78 4f 70 65 6e 2e        /// xOpen.
8f40: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54   ..        /// T
8f50: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77  he SQLite core w
8f60: 69 6c 6c 20 61 6c 77 61 79 73 20 63 61 6c 6c 20  ill always call 
8f70: 78 43 6c 6f 73 65 20 6f 6e 63 65 20 66 6f 72 20  xClose once for 
8f80: 65 61 63 68 20 63 75 72 73 6f 72 20 6f 70 65 6e  each cursor open
8f90: 65 64 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ed ..        ///
8fa0: 20 75 73 69 6e 67 20 78 4f 70 65 6e 2e 0d 0a 20   using xOpen... 
8fb0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
8fc0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
8fd0: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
8fe0: 2f 2f 2f 20 54 68 69 73 20 6d 65 74 68 6f 64 20  /// This method 
8ff0: 6d 75 73 74 20 72 65 6c 65 61 73 65 20 61 6c 6c  must release all
9000: 20 72 65 73 6f 75 72 63 65 73 20 61 6c 6c 6f 63   resources alloc
9010: 61 74 65 64 20 62 79 20 74 68 65 0d 0a 20 20 20  ated by the..   
9020: 20 20 20 20 20 2f 2f 2f 20 63 6f 72 72 65 73 70       /// corresp
9030: 6f 6e 64 69 6e 67 20 78 4f 70 65 6e 20 63 61 6c  onding xOpen cal
9040: 6c 2e 20 54 68 65 20 72 6f 75 74 69 6e 65 20 77  l. The routine w
9050: 69 6c 6c 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  ill not be calle
9060: 64 20 61 67 61 69 6e 20 65 76 65 6e 20 69 66 20  d again even if 
9070: 69 74 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  it..        /// 
9080: 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72  returns an error
9090: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
90a0: 72 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20  re will not use 
90b0: 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  the..        ///
90c0: 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
90d0: 72 73 6f 72 20 61 67 61 69 6e 20 61 66 74 65 72  rsor again after
90e0: 20 69 74 20 68 61 73 20 62 65 65 6e 20 63 6c 6f   it has been clo
90f0: 73 65 64 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  sed...        //
9100: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  / </para>..     
9110: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20     /// <para>.. 
9120: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 78         /// The x
9130: 43 6c 6f 73 65 20 6d 65 74 68 6f 64 20 69 73 20  Close method is 
9140: 72 65 71 75 69 72 65 64 20 66 6f 72 20 65 76 65  required for eve
9150: 72 79 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ry virtual table
9160: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
9170: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
9180: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
9190: 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a 20  // </summary>.. 
91a0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
91b0: 6d 20 6e 61 6d 65 3d 22 70 43 75 72 73 6f 72 22  m name="pCursor"
91c0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54  >..        /// T
91d0: 68 65 20 6e 61 74 69 76 65 20 70 6f 69 6e 74 65  he native pointe
91e0: 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
91f0: 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 64 65 72  _vtab_cursor der
9200: 69 76 65 64 20 73 74 72 75 63 74 75 72 65 2e 0d  ived structure..
9210: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
9220: 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f  aram>..        /
9230: 2f 2f 20 3c 72 65 74 75 72 6e 73 3e 0d 0a 20 20  // <returns>..  
9240: 20 20 20 20 20 20 2f 2f 2f 20 41 20 73 74 61 6e        /// A stan
9250: 64 61 72 64 20 53 51 4c 69 74 65 20 72 65 74 75  dard SQLite retu
9260: 72 6e 20 63 6f 64 65 2e 0d 0a 20 20 20 20 20 20  rn code...      
9270: 20 20 2f 2f 2f 20 3c 2f 72 65 74 75 72 6e 73 3e    /// </returns>
9280: 0d 0a 20 20 20 20 20 20 20 20 53 51 4c 69 74 65  ..        SQLite
9290: 45 72 72 6f 72 43 6f 64 65 20 78 43 6c 6f 73 65  ErrorCode xClose
92a0: 28 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 49  (..            I
92b0: 6e 74 50 74 72 20 70 43 75 72 73 6f 72 0d 0a 20  ntPtr pCursor.. 
92c0: 20 20 20 20 20 20 20 20 20 20 20 29 3b 0d 0a 0d             );...
92d0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f  .        ///////
92e0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
92f0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
9300: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
9310: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
9320: 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ....        /// 
9330: 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20  <summary>..     
9340: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f     /// <para><co
9350: 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  de>..        ///
9360: 20 20 20 69 6e 74 20 28 2a 78 46 69 6c 74 65 72     int (*xFilter
9370: 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
9380: 75 72 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e  ursor*, int idxN
9390: 75 6d 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  um, const char *
93a0: 69 64 78 53 74 72 2c 0d 0a 20 20 20 20 20 20 20  idxStr,..       
93b0: 20 2f 2f 2f 20 20 20 20 20 20 20 20 20 20 20 20   ///            
93c0: 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 73       int argc, s
93d0: 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61  qlite3_value **a
93e0: 72 67 76 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f  rgv);..        /
93f0: 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61  // </code></para
9400: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
9410: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
9420: 2f 2f 20 54 68 69 73 20 6d 65 74 68 6f 64 20 62  // This method b
9430: 65 67 69 6e 73 20 61 20 73 65 61 72 63 68 20 6f  egins a search o
9440: 66 20 61 20 76 69 72 74 75 61 6c 20 74 61 62 6c  f a virtual tabl
9450: 65 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  e. ..        ///
9460: 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
9470: 65 6e 74 20 69 73 20 61 20 63 75 72 73 6f 72 20  ent is a cursor 
9480: 6f 70 65 6e 65 64 20 62 79 20 78 4f 70 65 6e 2e  opened by xOpen.
9490: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54   ..        /// T
94a0: 68 65 20 6e 65 78 74 20 74 77 6f 20 61 72 67 75  he next two argu
94b0: 6d 65 6e 74 73 20 64 65 66 69 6e 65 20 61 20 70  ments define a p
94c0: 61 72 74 69 63 75 6c 61 72 20 73 65 61 72 63 68  articular search
94d0: 20 69 6e 64 65 78 20 70 72 65 76 69 6f 75 73 6c   index previousl
94e0: 79 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  y ..        /// 
94f0: 63 68 6f 73 65 6e 20 62 79 20 78 42 65 73 74 49  chosen by xBestI
9500: 6e 64 65 78 2e 20 54 68 65 20 73 70 65 63 69 66  ndex. The specif
9510: 69 63 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 69  ic meanings of i
9520: 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 53 74 72  dxNum and idxStr
9530: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 61   ..        /// a
9540: 72 65 20 75 6e 69 6d 70 6f 72 74 61 6e 74 20 61  re unimportant a
9550: 73 20 6c 6f 6e 67 20 61 73 20 78 46 69 6c 74 65  s long as xFilte
9560: 72 20 61 6e 64 20 78 42 65 73 74 49 6e 64 65 78  r and xBestIndex
9570: 20 61 67 72 65 65 20 6f 6e 20 77 68 61 74 20 0d   agree on what .
9580: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 61  .        /// tha
9590: 74 20 6d 65 61 6e 69 6e 67 20 69 73 2e 0d 0a 20  t meaning is... 
95a0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
95b0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
95c0: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
95d0: 2f 2f 2f 20 54 68 65 20 78 42 65 73 74 49 6e 64  /// The xBestInd
95e0: 65 78 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  ex function may 
95f0: 68 61 76 65 20 72 65 71 75 65 73 74 65 64 20 74  have requested t
9600: 68 65 20 76 61 6c 75 65 73 20 6f 66 20 0d 0a 20  he values of .. 
9610: 20 20 20 20 20 20 20 2f 2f 2f 20 63 65 72 74 61         /// certa
9620: 69 6e 20 65 78 70 72 65 73 73 69 6f 6e 73 20 75  in expressions u
9630: 73 69 6e 67 20 74 68 65 20 61 43 6f 6e 73 74 72  sing the aConstr
9640: 61 69 6e 74 55 73 61 67 65 5b 5d 2e 61 72 67 76  aintUsage[].argv
9650: 49 6e 64 65 78 20 76 61 6c 75 65 73 20 0d 0a 20  Index values .. 
9660: 20 20 20 20 20 20 20 2f 2f 2f 20 6f 66 20 74 68         /// of th
9670: 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  e sqlite3_index_
9680: 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65 2e 20  info structure. 
9690: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
96a0: 6f 73 65 20 76 61 6c 75 65 73 20 61 72 65 20 70  ose values are p
96b0: 61 73 73 65 64 20 74 6f 20 78 46 69 6c 74 65 72  assed to xFilter
96c0: 20 75 73 69 6e 67 20 74 68 65 20 61 72 67 63 20   using the argc 
96d0: 61 6e 64 20 61 72 67 76 20 70 61 72 61 6d 65 74  and argv paramet
96e0: 65 72 73 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ers...        //
96f0: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  / </para>..     
9700: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20     /// <para>.. 
9710: 20 20 20 20 20 20 20 2f 2f 2f 20 49 66 20 74 68         /// If th
9720: 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  e virtual table 
9730: 63 6f 6e 74 61 69 6e 73 20 6f 6e 65 20 6f 72 20  contains one or 
9740: 6d 6f 72 65 20 72 6f 77 73 20 74 68 61 74 20 6d  more rows that m
9750: 61 74 63 68 20 74 68 65 0d 0a 20 20 20 20 20 20  atch the..      
9760: 20 20 2f 2f 2f 20 73 65 61 72 63 68 20 63 72 69    /// search cri
9770: 74 65 72 69 61 2c 20 74 68 65 6e 20 74 68 65 20  teria, then the 
9780: 63 75 72 73 6f 72 20 6d 75 73 74 20 62 65 20 6c  cursor must be l
9790: 65 66 74 20 70 6f 69 6e 74 20 61 74 20 74 68 65  eft point at the
97a0: 20 66 69 72 73 74 20 72 6f 77 2e 0d 0a 20 20 20   first row...   
97b0: 20 20 20 20 20 2f 2f 2f 20 53 75 62 73 65 71 75       /// Subsequ
97c0: 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 78 45 6f  ent calls to xEo
97d0: 66 20 6d 75 73 74 20 72 65 74 75 72 6e 20 66 61  f must return fa
97e0: 6c 73 65 20 28 7a 65 72 6f 29 2e 0d 0a 20 20 20  lse (zero)...   
97f0: 20 20 20 20 20 2f 2f 2f 20 49 66 20 74 68 65 72       /// If ther
9800: 65 20 61 72 65 20 6e 6f 20 72 6f 77 73 20 6d 61  e are no rows ma
9810: 74 63 68 2c 20 74 68 65 6e 20 74 68 65 20 63 75  tch, then the cu
9820: 72 73 6f 72 20 6d 75 73 74 20 62 65 20 6c 65 66  rsor must be lef
9830: 74 20 69 6e 20 61 20 73 74 61 74 65 20 0d 0a 20  t in a state .. 
9840: 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 61 74 20         /// that 
9850: 77 69 6c 6c 20 63 61 75 73 65 20 74 68 65 20 78  will cause the x
9860: 45 6f 66 20 74 6f 20 72 65 74 75 72 6e 20 74 72  Eof to return tr
9870: 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 2e 0d 0a  ue (non-zero)...
9880: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20          /// The 
9890: 53 51 4c 69 74 65 20 65 6e 67 69 6e 65 20 77 69  SQLite engine wi
98a0: 6c 6c 20 75 73 65 0d 0a 20 20 20 20 20 20 20 20  ll use..        
98b0: 2f 2f 2f 20 74 68 65 20 78 43 6f 6c 75 6d 6e 20  /// the xColumn 
98c0: 61 6e 64 20 78 52 6f 77 69 64 20 6d 65 74 68 6f  and xRowid metho
98d0: 64 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 61  ds to access tha
98e0: 74 20 72 6f 77 20 63 6f 6e 74 65 6e 74 2e 0d 0a  t row content...
98f0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20          /// The 
9900: 78 4e 65 78 74 20 6d 65 74 68 6f 64 20 77 69 6c  xNext method wil
9910: 6c 20 62 65 20 75 73 65 64 20 74 6f 20 61 64 76  l be used to adv
9920: 61 6e 63 65 20 74 6f 20 74 68 65 20 6e 65 78 74  ance to the next
9930: 20 72 6f 77 2e 0d 0a 20 20 20 20 20 20 20 20 2f   row...        /
9940: 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  // </para>..    
9950: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a      /// <para>..
9960: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 69 73          /// This
9970: 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 72 65 74   method must ret
9980: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
9990: 20 73 75 63 63 65 73 73 66 75 6c 2c 20 6f 72 20   successful, or 
99a0: 61 6e 20 73 71 6c 69 74 65 20 0d 0a 20 20 20 20  an sqlite ..    
99b0: 20 20 20 20 2f 2f 2f 20 65 72 72 6f 72 20 63 6f      /// error co
99c0: 64 65 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f  de if an error o
99d0: 63 63 75 72 73 2e 0d 0a 20 20 20 20 20 20 20 20  ccurs...        
99e0: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
99f0: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
9a00: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65  .        /// The
9a10: 20 78 46 69 6c 74 65 72 20 6d 65 74 68 6f 64 20   xFilter method 
9a20: 69 73 20 72 65 71 75 69 72 65 64 20 66 6f 72 20  is required for 
9a30: 65 76 65 72 79 20 76 69 72 74 75 61 6c 20 74 61  every virtual ta
9a40: 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
9a50: 6f 6e 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  on...        ///
9a60: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
9a70: 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e    /// </summary>
9a80: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
9a90: 61 72 61 6d 20 6e 61 6d 65 3d 22 70 43 75 72 73  aram name="pCurs
9aa0: 6f 72 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  or">..        //
9ab0: 2f 20 54 68 65 20 6e 61 74 69 76 65 20 70 6f 69  / The native poi
9ac0: 6e 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  nter to the sqli
9ad0: 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20  te3_vtab_cursor 
9ae0: 64 65 72 69 76 65 64 20 73 74 72 75 63 74 75 72  derived structur
9af0: 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e...        /// 
9b00: 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20  </param>..      
9b10: 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d    /// <param nam
9b20: 65 3d 22 69 64 78 4e 75 6d 22 3e 0d 0a 20 20 20  e="idxNum">..   
9b30: 20 20 20 20 20 2f 2f 2f 20 4e 75 6d 62 65 72 20       /// Number 
9b40: 75 73 65 64 20 74 6f 20 68 65 6c 70 20 69 64 65  used to help ide
9b50: 6e 74 69 66 79 20 74 68 65 20 73 65 6c 65 63 74  ntify the select
9b60: 65 64 20 69 6e 64 65 78 2e 0d 0a 20 20 20 20 20  ed index...     
9b70: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d     /// </param>.
9b80: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
9b90: 72 61 6d 20 6e 61 6d 65 3d 22 69 64 78 53 74 72  ram name="idxStr
9ba0: 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ">..        /// 
9bb0: 54 68 65 20 6e 61 74 69 76 65 20 70 6f 69 6e 74  The native point
9bc0: 65 72 20 74 6f 20 74 68 65 20 55 54 46 2d 38 20  er to the UTF-8 
9bd0: 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 20 63  encoded string c
9be0: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0d 0a 20  ontaining the.. 
9bf0: 20 20 20 20 20 20 20 2f 2f 2f 20 73 74 72 69 6e         /// strin
9c00: 67 20 75 73 65 64 20 74 6f 20 68 65 6c 70 20 69  g used to help i
9c10: 64 65 6e 74 69 66 79 20 74 68 65 20 73 65 6c 65  dentify the sele
9c20: 63 74 65 64 20 69 6e 64 65 78 2e 0d 0a 20 20 20  cted index...   
9c30: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d       /// </param
9c40: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
9c50: 70 61 72 61 6d 20 6e 61 6d 65 3d 22 61 72 67 63  param name="argc
9c60: 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ">..        /// 
9c70: 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61  The number of na
9c80: 74 69 76 65 20 70 6f 69 6e 74 65 72 73 20 74 6f  tive pointers to
9c90: 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 73   sqlite3_value s
9ca0: 74 72 75 63 74 75 72 65 73 20 73 70 65 63 69 66  tructures specif
9cb0: 69 65 64 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ied..        ///
9cc0: 20 69 6e 20 3c 70 61 72 61 6d 72 65 66 20 6e 61   in <paramref na
9cd0: 6d 65 3d 22 61 72 67 76 22 20 2f 3e 2e 0d 0a 20  me="argv" />... 
9ce0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
9cf0: 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  am>..        ///
9d00: 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 61 72   <param name="ar
9d10: 67 76 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  gv">..        //
9d20: 2f 20 41 6e 20 61 72 72 61 79 20 6f 66 20 6e 61  / An array of na
9d30: 74 69 76 65 20 70 6f 69 6e 74 65 72 73 20 74 6f  tive pointers to
9d40: 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 73   sqlite3_value s
9d50: 74 72 75 63 74 75 72 65 73 20 63 6f 6e 74 61 69  tructures contai
9d60: 6e 69 6e 67 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ning..        //
9d70: 2f 20 66 69 6c 74 65 72 69 6e 67 20 63 72 69 74  / filtering crit
9d80: 65 72 69 61 20 66 6f 72 20 74 68 65 20 73 65 6c  eria for the sel
9d90: 65 63 74 65 64 20 69 6e 64 65 78 2e 0d 0a 20 20  ected index...  
9da0: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61        /// </para
9db0: 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  m>..        /// 
9dc0: 3c 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20  <returns>..     
9dd0: 20 20 20 2f 2f 2f 20 41 20 73 74 61 6e 64 61 72     /// A standar
9de0: 64 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 20  d SQLite return 
9df0: 63 6f 64 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f  code...        /
9e00: 2f 2f 20 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a 20  // </returns>.. 
9e10: 20 20 20 20 20 20 20 53 51 4c 69 74 65 45 72 72         SQLiteErr
9e20: 6f 72 43 6f 64 65 20 78 46 69 6c 74 65 72 28 0d  orCode xFilter(.
9e30: 0a 20 20 20 20 20 20 20 20 20 20 20 20 49 6e 74  .            Int
9e40: 50 74 72 20 70 43 75 72 73 6f 72 2c 0d 0a 20 20  Ptr pCursor,..  
9e50: 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 69 64            int id
9e60: 78 4e 75 6d 2c 0d 0a 20 20 20 20 20 20 20 20 20  xNum,..         
9e70: 20 20 20 49 6e 74 50 74 72 20 69 64 78 53 74 72     IntPtr idxStr
9e80: 2c 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 69  ,..            i
9e90: 6e 74 20 61 72 67 63 2c 0d 0a 20 20 20 20 20 20  nt argc,..      
9ea0: 20 20 20 20 20 20 49 6e 74 50 74 72 20 61 72 67        IntPtr arg
9eb0: 76 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 29  v..            )
9ec0: 3b 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ;....        ///
9ed0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
9ee0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
9ef0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
9f00: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
9f10: 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 20 20 20 20  ////....        
9f20: 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20  /// <summary>.. 
9f30: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
9f40: 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20  ><code>..       
9f50: 20 2f 2f 2f 20 20 20 69 6e 74 20 28 2a 78 4e 65   ///   int (*xNe
9f60: 78 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  xt)(sqlite3_vtab
9f70: 5f 63 75 72 73 6f 72 2a 29 3b 0d 0a 20 20 20 20  _cursor*);..    
9f80: 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c      /// </code><
9f90: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
9fa0: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20  /// <para>..    
9fb0: 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 4e 65 78      /// The xNex
9fc0: 74 20 6d 65 74 68 6f 64 20 61 64 76 61 6e 63 65  t method advance
9fd0: 73 20 61 20 76 69 72 74 75 61 6c 20 74 61 62 6c  s a virtual tabl
9fe0: 65 20 63 75 72 73 6f 72 0d 0a 20 20 20 20 20 20  e cursor..      
9ff0: 20 20 2f 2f 2f 20 74 6f 20 74 68 65 20 6e 65 78    /// to the nex
a000: 74 20 72 6f 77 20 6f 66 20 61 20 72 65 73 75 6c  t row of a resul
a010: 74 20 73 65 74 20 69 6e 69 74 69 61 74 65 64 20  t set initiated 
a020: 62 79 20 78 46 69 6c 74 65 72 2e 20 0d 0a 20 20  by xFilter. ..  
a030: 20 20 20 20 20 20 2f 2f 2f 20 49 66 20 74 68 65        /// If the
a040: 20 63 75 72 73 6f 72 20 69 73 20 61 6c 72 65 61   cursor is alrea
a050: 64 79 20 70 6f 69 6e 74 69 6e 67 20 61 74 20 74  dy pointing at t
a060: 68 65 20 6c 61 73 74 20 72 6f 77 20 77 68 65 6e  he last row when
a070: 20 74 68 69 73 20 0d 0a 20 20 20 20 20 20 20 20   this ..        
a080: 2f 2f 2f 20 72 6f 75 74 69 6e 65 20 69 73 20 63  /// routine is c
a090: 61 6c 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20  alled, then the 
a0a0: 63 75 72 73 6f 72 20 6e 6f 20 6c 6f 6e 67 65 72  cursor no longer
a0b0: 20 70 6f 69 6e 74 73 20 74 6f 20 76 61 6c 69 64   points to valid
a0c0: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 64   ..        /// d
a0d0: 61 74 61 20 61 6e 64 20 61 20 73 75 62 73 65 71  ata and a subseq
a0e0: 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 74 68 65  uent call to the
a0f0: 20 78 45 6f 66 20 6d 65 74 68 6f 64 20 6d 75 73   xEof method mus
a100: 74 20 72 65 74 75 72 6e 20 74 72 75 65 20 28 6e  t return true (n
a110: 6f 6e 2d 7a 65 72 6f 29 2e 20 0d 0a 20 20 20 20  on-zero). ..    
a120: 20 20 20 20 2f 2f 2f 20 49 66 20 74 68 65 20 63      /// If the c
a130: 75 72 73 6f 72 20 69 73 20 73 75 63 63 65 73 73  ursor is success
a140: 66 75 6c 6c 79 20 61 64 76 61 6e 63 65 64 20 74  fully advanced t
a150: 6f 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66  o another row of
a160: 20 63 6f 6e 74 65 6e 74 2c 20 74 68 65 6e 0d 0a   content, then..
a170: 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 75 62 73          /// subs
a180: 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
a190: 78 45 6f 66 20 6d 75 73 74 20 72 65 74 75 72 6e  xEof must return
a1a0: 20 66 61 6c 73 65 20 28 7a 65 72 6f 29 2e 0d 0a   false (zero)...
a1b0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
a1c0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
a1d0: 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20   <para>..       
a1e0: 20 2f 2f 2f 20 54 68 69 73 20 6d 65 74 68 6f 64   /// This method
a1f0: 20 6d 75 73 74 20 72 65 74 75 72 6e 20 53 51 4c   must return SQL
a200: 49 54 45 5f 4f 4b 20 69 66 20 73 75 63 63 65 73  ITE_OK if succes
a210: 73 66 75 6c 2c 20 6f 72 20 61 6e 20 73 71 6c 69  sful, or an sqli
a220: 74 65 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  te ..        ///
a230: 20 65 72 72 6f 72 20 63 6f 64 65 20 69 66 20 61   error code if a
a240: 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0d  n error occurs..
a250: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
a260: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
a270: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
a280: 20 20 2f 2f 2f 20 54 68 65 20 78 4e 65 78 74 20    /// The xNext 
a290: 6d 65 74 68 6f 64 20 69 73 20 72 65 71 75 69 72  method is requir
a2a0: 65 64 20 66 6f 72 20 65 76 65 72 79 20 76 69 72  ed for every vir
a2b0: 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65  tual table imple
a2c0: 6d 65 6e 74 61 74 69 6f 6e 2e 0d 0a 20 20 20 20  mentation...    
a2d0: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
a2e0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 73  .        /// </s
a2f0: 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20  ummary>..       
a300: 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65   /// <param name
a310: 3d 22 70 43 75 72 73 6f 72 22 3e 0d 0a 20 20 20  ="pCursor">..   
a320: 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e 61 74       /// The nat
a330: 69 76 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  ive pointer to t
a340: 68 65 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  he sqlite3_vtab_
a350: 63 75 72 73 6f 72 20 64 65 72 69 76 65 64 20 73  cursor derived s
a360: 74 72 75 63 74 75 72 65 2e 0d 0a 20 20 20 20 20  tructure...     
a370: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d     /// </param>.
a380: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 72 65  .        /// <re
a390: 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20  turns>..        
a3a0: 2f 2f 2f 20 41 20 73 74 61 6e 64 61 72 64 20 53  /// A standard S
a3b0: 51 4c 69 74 65 20 72 65 74 75 72 6e 20 63 6f 64  QLite return cod
a3c0: 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e...        /// 
a3d0: 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20  </returns>..    
a3e0: 20 20 20 20 53 51 4c 69 74 65 45 72 72 6f 72 43      SQLiteErrorC
a3f0: 6f 64 65 20 78 4e 65 78 74 28 0d 0a 20 20 20 20  ode xNext(..    
a400: 20 20 20 20 20 20 20 20 49 6e 74 50 74 72 20 70          IntPtr p
a410: 43 75 72 73 6f 72 0d 0a 20 20 20 20 20 20 20 20  Cursor..        
a420: 20 20 20 20 29 3b 0d 0a 0d 0a 20 20 20 20 20 20      );....      
a430: 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f    //////////////
a440: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
a450: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
a460: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
a470: 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20  /////////....   
a480: 20 20 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72       /// <summar
a490: 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  y>..        /// 
a4a0: 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20  <para><code>..  
a4b0: 20 20 20 20 20 20 2f 2f 2f 20 20 20 69 6e 74 20        ///   int 
a4c0: 28 2a 78 45 6f 66 29 28 73 71 6c 69 74 65 33 5f  (*xEof)(sqlite3_
a4d0: 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0d 0a  vtab_cursor*);..
a4e0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f          /// </co
a4f0: 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  de></para>..    
a500: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a      /// <para>..
a510: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20          /// The 
a520: 78 45 6f 66 20 6d 65 74 68 6f 64 20 6d 75 73 74  xEof method must
a530: 20 72 65 74 75 72 6e 20 66 61 6c 73 65 20 28 7a   return false (z
a540: 65 72 6f 29 20 69 66 20 74 68 65 20 73 70 65 63  ero) if the spec
a550: 69 66 69 65 64 20 63 75 72 73 6f 72 20 0d 0a 20  ified cursor .. 
a560: 20 20 20 20 20 20 20 2f 2f 2f 20 63 75 72 72 65         /// curre
a570: 6e 74 6c 79 20 70 6f 69 6e 74 73 20 74 6f 20 61  ntly points to a
a580: 20 76 61 6c 69 64 20 72 6f 77 20 6f 66 20 64 61   valid row of da
a590: 74 61 2c 20 6f 72 20 74 72 75 65 20 28 6e 6f 6e  ta, or true (non
a5a0: 2d 7a 65 72 6f 29 20 6f 74 68 65 72 77 69 73 65  -zero) otherwise
a5b0: 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  . ..        /// 
a5c0: 54 68 69 73 20 6d 65 74 68 6f 64 20 69 73 20 63  This method is c
a5d0: 61 6c 6c 65 64 20 62 79 20 74 68 65 20 53 51 4c  alled by the SQL
a5e0: 20 65 6e 67 69 6e 65 20 69 6d 6d 65 64 69 61 74   engine immediat
a5f0: 65 6c 79 20 61 66 74 65 72 20 65 61 63 68 20 0d  ely after each .
a600: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 78 46 69  .        /// xFi
a610: 6c 74 65 72 20 61 6e 64 20 78 4e 65 78 74 20 69  lter and xNext i
a620: 6e 76 6f 63 61 74 69 6f 6e 2e 0d 0a 20 20 20 20  nvocation...    
a630: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
a640: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
a650: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
a660: 20 54 68 65 20 78 45 6f 66 20 6d 65 74 68 6f 64   The xEof method
a670: 20 69 73 20 72 65 71 75 69 72 65 64 20 66 6f 72   is required for
a680: 20 65 76 65 72 79 20 76 69 72 74 75 61 6c 20 74   every virtual t
a690: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
a6a0: 69 6f 6e 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ion...        //
a6b0: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  / </para>..     
a6c0: 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79     /// </summary
a6d0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
a6e0: 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 43 75 72  param name="pCur
a6f0: 73 6f 72 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f  sor">..        /
a700: 2f 2f 20 54 68 65 20 6e 61 74 69 76 65 20 70 6f  // The native po
a710: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  inter to the sql
a720: 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
a730: 20 64 65 72 69 76 65 64 20 73 74 72 75 63 74 75   derived structu
a740: 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  re...        ///
a750: 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20   </param>..     
a760: 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72 6e 73 3e     /// <returns>
a770: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 4e 6f  ..        /// No
a780: 6e 2d 7a 65 72 6f 20 69 66 20 6e 6f 20 6d 6f 72  n-zero if no mor
a790: 65 20 72 6f 77 73 20 61 72 65 20 61 76 61 69 6c  e rows are avail
a7a0: 61 62 6c 65 3b 20 7a 65 72 6f 20 6f 74 68 65 72  able; zero other
a7b0: 77 69 73 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f  wise...        /
a7c0: 2f 2f 20 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a 20  // </returns>.. 
a7d0: 20 20 20 20 20 20 20 69 6e 74 20 78 45 6f 66 28         int xEof(
a7e0: 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 49 6e  ..            In
a7f0: 74 50 74 72 20 70 43 75 72 73 6f 72 0d 0a 20 20  tPtr pCursor..  
a800: 20 20 20 20 20 20 20 20 20 20 29 3b 0d 0a 0d 0a            );....
a810: 20 20 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f          ////////
a820: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
a830: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
a840: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
a850: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d  ///////////////.
a860: 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
a870: 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20  summary>..      
a880: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64    /// <para><cod
a890: 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e>..        /// 
a8a0: 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29    int (*xColumn)
a8b0: 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
a8c0: 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63  rsor*, sqlite3_c
a8d0: 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b  ontext*, int N);
a8e0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
a8f0: 63 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20  code></para>..  
a900: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
a910: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
a920: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 69 6e  e SQLite core in
a930: 76 6f 6b 65 73 20 74 68 69 73 20 6d 65 74 68 6f  vokes this metho
a940: 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  d in order to fi
a950: 6e 64 20 74 68 65 20 76 61 6c 75 65 20 66 6f 72  nd the value for
a960: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74   ..        /// t
a970: 68 65 20 4e 2d 74 68 20 63 6f 6c 75 6d 6e 20 6f  he N-th column o
a980: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  f the current ro
a990: 77 2e 20 4e 20 69 73 20 7a 65 72 6f 2d 62 61 73  w. N is zero-bas
a9a0: 65 64 20 73 6f 20 74 68 65 20 66 69 72 73 74 20  ed so the first 
a9b0: 63 6f 6c 75 6d 6e 20 0d 0a 20 20 20 20 20 20 20  column ..       
a9c0: 20 2f 2f 2f 20 69 73 20 6e 75 6d 62 65 72 65 64   /// is numbered
a9d0: 20 30 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f   0. ..        //
a9e0: 2f 20 54 68 65 20 78 43 6f 6c 75 6d 6e 20 6d 65  / The xColumn me
a9f0: 74 68 6f 64 20 6d 61 79 20 72 65 74 75 72 6e 20  thod may return 
aa00: 69 74 73 20 72 65 73 75 6c 74 20 62 61 63 6b 20  its result back 
aa10: 74 6f 20 53 51 4c 69 74 65 20 75 73 69 6e 67 20  to SQLite using 
aa20: 6f 6e 65 20 6f 66 20 74 68 65 0d 0a 20 20 20 20  one of the..    
aa30: 20 20 20 20 2f 2f 2f 20 66 6f 6c 6c 6f 77 69 6e      /// followin
aa40: 67 20 69 6e 74 65 72 66 61 63 65 3a 0d 0a 20 20  g interface:..  
aa50: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61        /// </para
aa60: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
aa70: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
aa80: 2f 2f 20 20 73 71 6c 69 74 65 33 5f 72 65 73 75  //  sqlite3_resu
aa90: 6c 74 5f 62 6c 6f 62 28 29 0d 0a 20 20 20 20 20  lt_blob()..     
aaa0: 20 20 20 2f 2f 2f 20 20 73 71 6c 69 74 65 33 5f     ///  sqlite3_
aab0: 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 0d  result_double().
aac0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 73 71  .        ///  sq
aad0: 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
aae0: 28 29 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ()..        /// 
aaf0: 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
ab00: 69 6e 74 36 34 28 29 0d 0a 20 20 20 20 20 20 20  int64()..       
ab10: 20 2f 2f 2f 20 20 73 71 6c 69 74 65 33 5f 72 65   ///  sqlite3_re
ab20: 73 75 6c 74 5f 6e 75 6c 6c 28 29 0d 0a 20 20 20  sult_null()..   
ab30: 20 20 20 20 20 2f 2f 2f 20 20 73 71 6c 69 74 65       ///  sqlite
ab40: 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 0d  3_result_text().
ab50: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 73 71  .        ///  sq
ab60: 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
ab70: 74 31 36 28 29 0d 0a 20 20 20 20 20 20 20 20 2f  t16()..        /
ab80: 2f 2f 20 20 73 71 6c 69 74 65 33 5f 72 65 73 75  //  sqlite3_resu
ab90: 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 0d 0a 20  lt_text16le().. 
aba0: 20 20 20 20 20 20 20 2f 2f 2f 20 20 73 71 6c 69         ///  sqli
abb0: 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
abc0: 36 62 65 28 29 0d 0a 20 20 20 20 20 20 20 20 2f  6be()..        /
abd0: 2f 2f 20 20 73 71 6c 69 74 65 33 5f 72 65 73 75  //  sqlite3_resu
abe0: 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 0d 0a 20  lt_zeroblob().. 
abf0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
ac00: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
ac10: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
ac20: 2f 2f 2f 20 49 66 20 74 68 65 20 78 43 6f 6c 75  /// If the xColu
ac30: 6d 6e 20 6d 65 74 68 6f 64 20 69 6d 70 6c 65 6d  mn method implem
ac40: 65 6e 74 61 74 69 6f 6e 20 63 61 6c 6c 73 20 6e  entation calls n
ac50: 6f 6e 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74  one of the funct
ac60: 69 6f 6e 73 20 61 62 6f 76 65 2c 0d 0a 20 20 20  ions above,..   
ac70: 20 20 20 20 20 2f 2f 2f 20 74 68 65 6e 20 74 68       /// then th
ac80: 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 63  e value of the c
ac90: 6f 6c 75 6d 6e 20 64 65 66 61 75 6c 74 73 20 74  olumn defaults t
aca0: 6f 20 61 6e 20 53 51 4c 20 4e 55 4c 4c 2e 0d 0a  o an SQL NULL...
acb0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
acc0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
acd0: 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20   <para>..       
ace0: 20 2f 2f 2f 20 54 6f 20 72 61 69 73 65 20 61 6e   /// To raise an
acf0: 20 65 72 72 6f 72 2c 20 74 68 65 20 78 43 6f 6c   error, the xCol
ad00: 75 6d 6e 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c  umn method shoul
ad10: 64 20 75 73 65 20 6f 6e 65 20 6f 66 20 74 68 65  d use one of the
ad20: 20 72 65 73 75 6c 74 5f 74 65 78 74 28 29 20 0d   result_text() .
ad30: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6d 65 74  .        /// met
ad40: 68 6f 64 73 20 74 6f 20 73 65 74 20 74 68 65 20  hods to set the 
ad50: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
ad60: 78 74 2c 20 74 68 65 6e 20 72 65 74 75 72 6e 20  xt, then return 
ad70: 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0d 0a  an appropriate..
ad80: 20 20 20 20 20 20 20 20 2f 2f 2f 20 65 72 72 6f          /// erro
ad90: 72 20 63 6f 64 65 2e 20 20 54 68 65 20 78 43 6f  r code.  The xCo
ada0: 6c 75 6d 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74  lumn method must
adb0: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
adc0: 4b 20 6f 6e 20 73 75 63 63 65 73 73 2e 0d 0a 20  K on success... 
add0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
ade0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
adf0: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
ae00: 2f 2f 2f 20 54 68 65 20 78 43 6f 6c 75 6d 6e 20  /// The xColumn 
ae10: 6d 65 74 68 6f 64 20 69 73 20 72 65 71 75 69 72  method is requir
ae20: 65 64 20 66 6f 72 20 65 76 65 72 79 20 76 69 72  ed for every vir
ae30: 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65  tual table imple
ae40: 6d 65 6e 74 61 74 69 6f 6e 2e 0d 0a 20 20 20 20  mentation...    
ae50: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
ae60: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 73  .        /// </s
ae70: 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20  ummary>..       
ae80: 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65   /// <param name
ae90: 3d 22 70 43 75 72 73 6f 72 22 3e 0d 0a 20 20 20  ="pCursor">..   
aea0: 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e 61 74       /// The nat
aeb0: 69 76 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  ive pointer to t
aec0: 68 65 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  he sqlite3_vtab_
aed0: 63 75 72 73 6f 72 20 64 65 72 69 76 65 64 20 73  cursor derived s
aee0: 74 72 75 63 74 75 72 65 2e 0d 0a 20 20 20 20 20  tructure...     
aef0: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d     /// </param>.
af00: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
af10: 72 61 6d 20 6e 61 6d 65 3d 22 70 43 6f 6e 74 65  ram name="pConte
af20: 78 74 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  xt">..        //
af30: 2f 20 54 68 65 20 6e 61 74 69 76 65 20 70 6f 69  / The native poi
af40: 6e 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  nter to the sqli
af50: 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 74 72 75  te3_context stru
af60: 63 74 75 72 65 20 74 6f 20 62 65 20 75 73 65 64  cture to be used
af70: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 66 6f  ..        /// fo
af80: 72 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65 20  r returning the 
af90: 73 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e  specified column
afa0: 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 53 51   value to the SQ
afb0: 4c 69 74 65 20 63 6f 72 65 0d 0a 20 20 20 20 20  Lite core..     
afc0: 20 20 20 2f 2f 2f 20 6c 69 62 72 61 72 79 2e 0d     /// library..
afd0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
afe0: 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f  aram>..        /
aff0: 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22  // <param name="
b000: 69 6e 64 65 78 22 3e 0d 0a 20 20 20 20 20 20 20  index">..       
b010: 20 2f 2f 2f 20 54 68 65 20 7a 65 72 6f 2d 62 61   /// The zero-ba
b020: 73 65 64 20 69 6e 64 65 78 20 63 6f 72 72 65 73  sed index corres
b030: 70 6f 6e 64 69 6e 67 20 74 6f 20 74 68 65 20 63  ponding to the c
b040: 6f 6c 75 6d 6e 20 63 6f 6e 74 61 69 6e 69 6e 67  olumn containing
b050: 20 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f   the..        //
b060: 2f 20 76 61 6c 75 65 20 74 6f 20 62 65 20 72 65  / value to be re
b070: 74 75 72 6e 65 64 2e 0d 0a 20 20 20 20 20 20 20  turned...       
b080: 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20   /// </param>.. 
b090: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 72 65 74 75         /// <retu
b0a0: 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  rns>..        //
b0b0: 2f 20 41 20 73 74 61 6e 64 61 72 64 20 53 51 4c  / A standard SQL
b0c0: 69 74 65 20 72 65 74 75 72 6e 20 63 6f 64 65 2e  ite return code.
b0d0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
b0e0: 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20  returns>..      
b0f0: 20 20 53 51 4c 69 74 65 45 72 72 6f 72 43 6f 64    SQLiteErrorCod
b100: 65 20 78 43 6f 6c 75 6d 6e 28 0d 0a 20 20 20 20  e xColumn(..    
b110: 20 20 20 20 20 20 20 20 49 6e 74 50 74 72 20 70          IntPtr p
b120: 43 75 72 73 6f 72 2c 0d 0a 20 20 20 20 20 20 20  Cursor,..       
b130: 20 20 20 20 20 49 6e 74 50 74 72 20 70 43 6f 6e       IntPtr pCon
b140: 74 65 78 74 2c 0d 0a 20 20 20 20 20 20 20 20 20  text,..         
b150: 20 20 20 69 6e 74 20 69 6e 64 65 78 0d 0a 20 20     int index..  
b160: 20 20 20 20 20 20 20 20 20 20 29 3b 0d 0a 0d 0a            );....
b170: 20 20 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f          ////////
b180: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
b190: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
b1a0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
b1b0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d  ///////////////.
b1c0: 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
b1d0: 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20  summary>..      
b1e0: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64    /// <para><cod
b1f0: 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e>..        /// 
b200: 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 64 29 28    int (*xRowid)(
b210: 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
b220: 73 6f 72 20 2a 70 43 75 72 2c 20 73 71 6c 69 74  sor *pCur, sqlit
b230: 65 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69 64 29  e_int64 *pRowid)
b240: 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ;..        /// <
b250: 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20  /code></para>.. 
b260: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
b270: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41  >..        /// A
b280: 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
b290: 63 61 74 69 6f 6e 20 6f 66 20 74 68 69 73 20 6d  cation of this m
b2a0: 65 74 68 6f 64 20 77 69 6c 6c 20 63 61 75 73 65  ethod will cause
b2b0: 20 2a 70 52 6f 77 69 64 20 74 6f 20 62 65 0d 0a   *pRowid to be..
b2c0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 66 69 6c 6c          /// fill
b2d0: 65 64 20 77 69 74 68 20 74 68 65 20 72 6f 77 69  ed with the rowi
b2e0: 64 20 6f 66 20 72 6f 77 20 74 68 61 74 20 74 68  d of row that th
b2f0: 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 76  e..        /// v
b300: 69 72 74 75 61 6c 20 74 61 62 6c 65 20 63 75 72  irtual table cur
b310: 73 6f 72 20 70 43 75 72 20 69 73 20 63 75 72 72  sor pCur is curr
b320: 65 6e 74 6c 79 20 70 6f 69 6e 74 69 6e 67 20 61  ently pointing a
b330: 74 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  t...        /// 
b340: 54 68 69 73 20 6d 65 74 68 6f 64 20 72 65 74 75  This method retu
b350: 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 20 6f 6e  rns SQLITE_OK on
b360: 20 73 75 63 63 65 73 73 2e 0d 0a 20 20 20 20 20   success...     
b370: 20 20 20 2f 2f 2f 20 49 74 20 72 65 74 75 72 6e     /// It return
b380: 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
b390: 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 6e 20 66   error code on f
b3a0: 61 69 6c 75 72 65 2e 0d 0a 20 20 20 20 20 20 20  ailure...       
b3b0: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
b3c0: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
b3d0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
b3e0: 65 20 78 52 6f 77 69 64 20 6d 65 74 68 6f 64 20  e xRowid method 
b3f0: 69 73 20 72 65 71 75 69 72 65 64 20 66 6f 72 20  is required for 
b400: 65 76 65 72 79 20 76 69 72 74 75 61 6c 20 74 61  every virtual ta
b410: 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
b420: 6f 6e 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  on...        ///
b430: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
b440: 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e    /// </summary>
b450: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
b460: 61 72 61 6d 20 6e 61 6d 65 3d 22 70 43 75 72 73  aram name="pCurs
b470: 6f 72 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  or">..        //
b480: 2f 20 54 68 65 20 6e 61 74 69 76 65 20 70 6f 69  / The native poi
b490: 6e 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  nter to the sqli
b4a0: 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20  te3_vtab_cursor 
b4b0: 64 65 72 69 76 65 64 20 73 74 72 75 63 74 75 72  derived structur
b4c0: 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e...        /// 
b4d0: 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20  </param>..      
b4e0: 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d    /// <param nam
b4f0: 65 3d 22 72 6f 77 49 64 22 3e 0d 0a 20 20 20 20  e="rowId">..    
b500: 20 20 20 20 2f 2f 2f 20 55 70 6f 6e 20 73 75 63      /// Upon suc
b510: 63 65 73 73 2c 20 74 68 69 73 20 70 61 72 61 6d  cess, this param
b520: 65 74 65 72 20 6d 75 73 74 20 62 65 20 6d 6f 64  eter must be mod
b530: 69 66 69 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e  ified to contain
b540: 20 74 68 65 20 75 6e 69 71 75 65 0d 0a 20 20 20   the unique..   
b550: 20 20 20 20 20 2f 2f 2f 20 69 6e 74 65 67 65 72       /// integer
b560: 20 72 6f 77 20 69 64 65 6e 74 69 66 69 65 72 20   row identifier 
b570: 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  for the current 
b580: 72 6f 77 20 66 6f 72 20 74 68 65 20 73 70 65 63  row for the spec
b590: 69 66 69 65 64 20 63 75 72 73 6f 72 2e 0d 0a 20  ified cursor... 
b5a0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
b5b0: 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  am>..        ///
b5c0: 20 3c 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20   <returns>..    
b5d0: 20 20 20 20 2f 2f 2f 20 41 20 73 74 61 6e 64 61      /// A standa
b5e0: 72 64 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  rd SQLite return
b5f0: 20 63 6f 64 65 2e 0d 0a 20 20 20 20 20 20 20 20   code...        
b600: 2f 2f 2f 20 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a  /// </returns>..
b610: 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 45 72          SQLiteEr
b620: 72 6f 72 43 6f 64 65 20 78 52 6f 77 49 64 28 0d  rorCode xRowId(.
b630: 0a 20 20 20 20 20 20 20 20 20 20 20 20 49 6e 74  .            Int
b640: 50 74 72 20 70 43 75 72 73 6f 72 2c 0d 0a 20 20  Ptr pCursor,..  
b650: 20 20 20 20 20 20 20 20 20 20 72 65 66 20 6c 6f            ref lo
b660: 6e 67 20 72 6f 77 49 64 0d 0a 20 20 20 20 20 20  ng rowId..      
b670: 20 20 20 20 20 20 29 3b 0d 0a 0d 0a 20 20 20 20        );....    
b680: 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f      ////////////
b690: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
b6a0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
b6b0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
b6c0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20  ///////////.... 
b6d0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d         /// <summ
b6e0: 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ary>..        //
b6f0: 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a  / <para><code>..
b700: 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 69 6e          ///   in
b710: 74 20 28 2a 78 55 70 64 61 74 65 29 28 0d 0a 20  t (*xUpdate)(.. 
b720: 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 73         ///     s
b730: 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
b740: 61 62 2c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ab,..        ///
b750: 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 0d 0a       int argc,..
b760: 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20          ///     
b770: 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a  sqlite3_value **
b780: 61 72 67 76 2c 0d 0a 20 20 20 20 20 20 20 20 2f  argv,..        /
b790: 2f 2f 20 20 20 20 20 73 71 6c 69 74 65 5f 69 6e  //     sqlite_in
b7a0: 74 36 34 20 2a 70 52 6f 77 69 64 0d 0a 20 20 20  t64 *pRowid..   
b7b0: 20 20 20 20 20 2f 2f 2f 20 20 20 29 3b 0d 0a 20       ///   );.. 
b7c0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64         /// </cod
b7d0: 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  e></para>..     
b7e0: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20     /// <para>.. 
b7f0: 20 20 20 20 20 20 20 2f 2f 2f 20 41 6c 6c 20 63         /// All c
b800: 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 72 74  hanges to a virt
b810: 75 61 6c 20 74 61 62 6c 65 20 61 72 65 20 6d 61  ual table are ma
b820: 64 65 20 75 73 69 6e 67 20 74 68 65 20 78 55 70  de using the xUp
b830: 64 61 74 65 20 6d 65 74 68 6f 64 2e 0d 0a 20 20  date method...  
b840: 20 20 20 20 20 20 2f 2f 2f 20 54 68 69 73 20 6f        /// This o
b850: 6e 65 20 6d 65 74 68 6f 64 20 63 61 6e 20 62 65  ne method can be
b860: 20 75 73 65 64 20 74 6f 20 69 6e 73 65 72 74 2c   used to insert,
b870: 20 64 65 6c 65 74 65 2c 20 6f 72 20 75 70 64 61   delete, or upda
b880: 74 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  te...        ///
b890: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
b8a0: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
b8b0: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 61 72        /// The ar
b8c0: 67 63 20 70 61 72 61 6d 65 74 65 72 20 73 70 65  gc parameter spe
b8d0: 63 69 66 69 65 73 20 74 68 65 20 6e 75 6d 62 65  cifies the numbe
b8e0: 72 20 6f 66 20 65 6e 74 72 69 65 73 20 69 6e 20  r of entries in 
b8f0: 74 68 65 20 61 72 67 76 20 61 72 72 61 79 2e 20  the argv array. 
b900: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
b910: 65 20 76 61 6c 75 65 20 6f 66 20 61 72 67 63 20  e value of argc 
b920: 77 69 6c 6c 20 62 65 20 31 20 66 6f 72 20 61 20  will be 1 for a 
b930: 70 75 72 65 20 64 65 6c 65 74 65 20 6f 70 65 72  pure delete oper
b940: 61 74 69 6f 6e 20 6f 72 20 4e 2b 32 20 66 6f 72  ation or N+2 for
b950: 20 61 6e 20 69 6e 73 65 72 74 0d 0a 20 20 20 20   an insert..    
b960: 20 20 20 20 2f 2f 2f 20 6f 72 20 72 65 70 6c 61      /// or repla
b970: 63 65 20 6f 72 20 75 70 64 61 74 65 20 77 68 65  ce or update whe
b980: 72 65 20 4e 20 69 73 20 74 68 65 20 6e 75 6d 62  re N is the numb
b990: 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
b9a0: 20 74 68 65 20 74 61 62 6c 65 2e 20 20 0d 0a 20   the table.  .. 
b9b0: 20 20 20 20 20 20 20 2f 2f 2f 20 49 6e 20 74 68         /// In th
b9c0: 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
b9d0: 6e 63 65 2c 20 4e 20 69 6e 63 6c 75 64 65 73 20  nce, N includes 
b9e0: 61 6e 79 20 68 69 64 64 65 6e 20 63 6f 6c 75 6d  any hidden colum
b9f0: 6e 73 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ns...        ///
ba00: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
ba10: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
ba20: 20 20 20 20 20 20 2f 2f 2f 20 45 76 65 72 79 20        /// Every 
ba30: 61 72 67 76 20 65 6e 74 72 79 20 77 69 6c 6c 20  argv entry will 
ba40: 68 61 76 65 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  have a non-NULL 
ba50: 76 61 6c 75 65 20 69 6e 20 43 20 62 75 74 20 6d  value in C but m
ba60: 61 79 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 0d  ay contain the .
ba70: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 53 51 4c  .        /// SQL
ba80: 20 76 61 6c 75 65 20 4e 55 4c 4c 2e 20 20 49 6e   value NULL.  In
ba90: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74   other words, it
baa0: 20 69 73 20 61 6c 77 61 79 73 20 74 72 75 65 20   is always true 
bab0: 74 68 61 74 0d 0a 20 20 20 20 20 20 20 20 2f 2f  that..        //
bac0: 2f 20 3c 74 74 3e 61 72 67 76 5b 69 5d 21 3d 30  / <tt>argv[i]!=0
bad0: 3c 2f 74 74 3e 20 66 6f 72 20 69 20 62 65 74 77  </tt> for i betw
bae0: 65 65 6e 20 30 20 61 6e 64 20 3c 74 74 3e 61 72  een 0 and <tt>ar
baf0: 67 63 2d 31 3c 2f 74 74 3e 2e 0d 0a 20 20 20 20  gc-1</tt>...    
bb00: 20 20 20 20 2f 2f 2f 20 48 6f 77 65 76 65 72 2c      /// However,
bb10: 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65   it might be the
bb20: 20 63 61 73 65 20 74 68 61 74 0d 0a 20 20 20 20   case that..    
bb30: 20 20 20 20 2f 2f 2f 20 3c 74 74 3e 73 71 6c 69      /// <tt>sqli
bb40: 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 61  te3_value_type(a
bb50: 72 67 76 5b 69 5d 29 3d 3d 53 51 4c 49 54 45 5f  rgv[i])==SQLITE_
bb60: 4e 55 4c 4c 3c 2f 74 74 3e 2e 0d 0a 20 20 20 20  NULL</tt>...    
bb70: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
bb80: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
bb90: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
bba0: 20 54 68 65 20 61 72 67 76 5b 30 5d 20 70 61 72   The argv[0] par
bbb0: 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 72 6f  ameter is the ro
bbc0: 77 69 64 20 6f 66 20 61 20 72 6f 77 20 69 6e 20  wid of a row in 
bbd0: 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
bbe0: 65 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e ..        /// 
bbf0: 74 6f 20 62 65 20 64 65 6c 65 74 65 64 2e 20 49  to be deleted. I
bc00: 66 20 61 72 67 76 5b 30 5d 20 69 73 20 61 6e 20  f argv[0] is an 
bc10: 53 51 4c 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e  SQL NULL, then n
bc20: 6f 20 64 65 6c 65 74 69 6f 6e 20 6f 63 63 75 72  o deletion occur
bc30: 73 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  s...        /// 
bc40: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
bc50: 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20   /// <para>..   
bc60: 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 61 72 67       /// The arg
bc70: 76 5b 31 5d 20 70 61 72 61 6d 65 74 65 72 20 69  v[1] parameter i
bc80: 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 61  s the rowid of a
bc90: 20 6e 65 77 20 72 6f 77 20 74 6f 20 62 65 20 69   new row to be i
bca0: 6e 73 65 72 74 65 64 20 0d 0a 20 20 20 20 20 20  nserted ..      
bcb0: 20 20 2f 2f 2f 20 69 6e 74 6f 20 74 68 65 20 76    /// into the v
bcc0: 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 49 66  irtual table. If
bcd0: 20 61 72 67 76 5b 31 5d 20 69 73 20 61 6e 20 53   argv[1] is an S
bce0: 51 4c 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  QL NULL, then th
bcf0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
bd00: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6d   ..        /// m
bd10: 75 73 74 20 63 68 6f 6f 73 65 20 61 20 72 6f 77  ust choose a row
bd20: 69 64 20 66 6f 72 20 74 68 65 20 6e 65 77 6c 79  id for the newly
bd30: 20 69 6e 73 65 72 74 65 64 20 72 6f 77 2e 20 53   inserted row. S
bd40: 75 62 73 65 71 75 65 6e 74 20 61 72 67 76 5b 5d  ubsequent argv[]
bd50: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 65   ..        /// e
bd60: 6e 74 72 69 65 73 20 63 6f 6e 74 61 69 6e 20 76  ntries contain v
bd70: 61 6c 75 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  alues of the col
bd80: 75 6d 6e 73 20 6f 66 20 74 68 65 20 76 69 72 74  umns of the virt
bd90: 75 61 6c 20 74 61 62 6c 65 2c 20 69 6e 20 74 68  ual table, in th
bda0: 65 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e ..        /// 
bdb0: 6f 72 64 65 72 20 74 68 61 74 20 74 68 65 20 63  order that the c
bdc0: 6f 6c 75 6d 6e 73 20 77 65 72 65 20 64 65 63 6c  olumns were decl
bdd0: 61 72 65 64 2e 20 54 68 65 20 6e 75 6d 62 65 72  ared. The number
bde0: 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 77 69 6c 6c   of columns will
bdf0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6d 61  ..        /// ma
be00: 74 63 68 20 74 68 65 20 74 61 62 6c 65 20 64 65  tch the table de
be10: 63 6c 61 72 61 74 69 6f 6e 20 74 68 61 74 20 74  claration that t
be20: 68 65 20 78 43 6f 6e 6e 65 63 74 20 6f 72 20 78  he xConnect or x
be30: 43 72 65 61 74 65 20 6d 65 74 68 6f 64 20 6d 61  Create method ma
be40: 64 65 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  de ..        ///
be50: 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
be60: 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28  e3_declare_vtab(
be70: 29 20 63 61 6c 6c 2e 20 20 41 6c 6c 20 68 69 64  ) call.  All hid
be80: 64 65 6e 20 63 6f 6c 75 6d 6e 73 20 61 72 65 20  den columns are 
be90: 69 6e 63 6c 75 64 65 64 2e 0d 0a 20 20 20 20 20  included...     
bea0: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a     /// </para>..
beb0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
bec0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
bed0: 57 68 65 6e 20 64 6f 69 6e 67 20 61 6e 20 69 6e  When doing an in
bee0: 73 65 72 74 20 77 69 74 68 6f 75 74 20 61 20 72  sert without a r
bef0: 6f 77 69 64 20 28 61 72 67 63 3e 31 2c 20 61 72  owid (argc>1, ar
bf00: 67 76 5b 31 5d 20 69 73 20 61 6e 20 53 51 4c 20  gv[1] is an SQL 
bf10: 4e 55 4c 4c 29 2c 20 74 68 65 20 0d 0a 20 20 20  NULL), the ..   
bf20: 20 20 20 20 20 2f 2f 2f 20 69 6d 70 6c 65 6d 65       /// impleme
bf30: 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 73 65 74  ntation must set
bf40: 20 2a 70 52 6f 77 69 64 20 74 6f 20 74 68 65 20   *pRowid to the 
bf50: 72 6f 77 69 64 20 6f 66 20 74 68 65 20 6e 65 77  rowid of the new
bf60: 6c 79 20 69 6e 73 65 72 74 65 64 20 72 6f 77 3b  ly inserted row;
bf70: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74   ..        /// t
bf80: 68 69 73 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20  his will become 
bf90: 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
bfa0: 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
bfb0: 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
bfc0: 77 69 64 28 29 0d 0a 20 20 20 20 20 20 20 20 2f  wid()..        /
bfd0: 2f 2f 20 66 75 6e 63 74 69 6f 6e 2e 20 53 65 74  // function. Set
bfe0: 74 69 6e 67 20 74 68 69 73 20 76 61 6c 75 65 20  ting this value 
bff0: 69 6e 20 61 6c 6c 20 74 68 65 20 6f 74 68 65 72  in all the other
c000: 20 63 61 73 65 73 20 69 73 20 61 20 68 61 72 6d   cases is a harm
c010: 6c 65 73 73 20 6e 6f 2d 6f 70 3b 0d 0a 20 20 20  less no-op;..   
c020: 20 20 20 20 20 2f 2f 2f 20 74 68 65 20 53 51 4c       /// the SQL
c030: 69 74 65 20 65 6e 67 69 6e 65 20 69 67 6e 6f 72  ite engine ignor
c040: 65 73 20 74 68 65 20 2a 70 52 6f 77 69 64 20 72  es the *pRowid r
c050: 65 74 75 72 6e 20 76 61 6c 75 65 20 69 66 20 61  eturn value if a
c060: 72 67 63 3d 3d 31 20 6f 72 20 0d 0a 20 20 20 20  rgc==1 or ..    
c070: 20 20 20 20 2f 2f 2f 20 61 72 67 76 5b 31 5d 20      /// argv[1] 
c080: 69 73 20 6e 6f 74 20 61 6e 20 53 51 4c 20 4e 55  is not an SQL NU
c090: 4c 4c 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  LL...        ///
c0a0: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
c0b0: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
c0c0: 20 20 20 20 20 20 2f 2f 2f 20 45 61 63 68 20 63        /// Each c
c0d0: 61 6c 6c 20 74 6f 20 78 55 70 64 61 74 65 20 77  all to xUpdate w
c0e0: 69 6c 6c 20 66 61 6c 6c 20 69 6e 74 6f 20 6f 6e  ill fall into on
c0f0: 65 20 6f 66 20 63 61 73 65 73 20 73 68 6f 77 6e  e of cases shown
c100: 20 62 65 6c 6f 77 2e 0d 0a 20 20 20 20 20 20 20   below...       
c110: 20 2f 2f 2f 20 4e 6f 74 20 74 68 61 74 20 72 65   /// Not that re
c120: 66 65 72 65 6e 63 65 73 20 74 6f 20 61 72 67 76  ferences to argv
c130: 5b 69 5d 20 6d 65 61 6e 20 74 68 65 20 53 51 4c  [i] mean the SQL
c140: 20 76 61 6c 75 65 0d 0a 20 20 20 20 20 20 20 20   value..        
c150: 2f 2f 2f 20 68 65 6c 64 20 77 69 74 68 69 6e 20  /// held within 
c160: 74 68 65 20 61 72 67 76 5b 69 5d 20 6f 62 6a 65  the argv[i] obje
c170: 63 74 2c 20 6e 6f 74 20 74 68 65 20 61 72 67 76  ct, not the argv
c180: 5b 69 5d 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  [i]..        ///
c190: 20 6f 62 6a 65 63 74 20 69 74 73 65 6c 66 2e 0d   object itself..
c1a0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
c1b0: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
c1c0: 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a  / <para><code>..
c1d0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 61 72 67 63          /// argc
c1e0: 20 3d 20 31 0d 0a 20 20 20 20 20 20 20 20 2f 2f   = 1..        //
c1f0: 2f 20 54 68 65 20 73 69 6e 67 6c 65 20 72 6f 77  / The single row
c200: 20 77 69 74 68 20 72 6f 77 69 64 20 65 71 75 61   with rowid equa
c210: 6c 20 74 6f 20 61 72 67 76 5b 30 5d 20 69 73 20  l to argv[0] is 
c220: 64 65 6c 65 74 65 64 2e 20 4e 6f 20 69 6e 73 65  deleted. No inse
c230: 72 74 20 6f 63 63 75 72 73 2e 0d 0a 20 20 20 20  rt occurs...    
c240: 20 20 20 20 2f 2f 2f 20 61 72 67 63 20 26 67 74      /// argc &gt
c250: 3b 20 31 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ; 1 ..        //
c260: 2f 20 20 61 72 67 76 5b 30 5d 20 3d 20 4e 55 4c  /  argv[0] = NUL
c270: 4c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41  L..        /// A
c280: 20 6e 65 77 20 72 6f 77 20 69 73 20 69 6e 73 65   new row is inse
c290: 72 74 65 64 20 77 69 74 68 20 61 20 72 6f 77 69  rted with a rowi
c2a0: 64 20 61 72 67 76 5b 31 5d 20 61 6e 64 20 63 6f  d argv[1] and co
c2b0: 6c 75 6d 6e 20 76 61 6c 75 65 73 20 69 6e 0d 0a  lumn values in..
c2c0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20          ///     
c2d0: 20 20 20 61 72 67 76 5b 32 5d 20 61 6e 64 20 66     argv[2] and f
c2e0: 6f 6c 6c 6f 77 69 6e 67 2e 20 20 49 66 20 61 72  ollowing.  If ar
c2f0: 67 76 5b 31 5d 20 69 73 20 61 6e 20 53 51 4c 20  gv[1] is an SQL 
c300: 4e 55 4c 4c 2c 0d 0a 20 20 20 20 20 20 20 20 2f  NULL,..        /
c310: 2f 2f 20 20 20 20 20 20 20 20 74 68 65 20 61 20  //        the a 
c320: 6e 65 77 20 75 6e 69 71 75 65 20 72 6f 77 69 64  new unique rowid
c330: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 61 75   is generated au
c340: 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0d 0a 20 20  tomatically...  
c350: 20 20 20 20 20 20 2f 2f 2f 20 61 72 67 63 20 26        /// argc &
c360: 67 74 3b 20 31 20 0d 0a 20 20 20 20 20 20 20 20  gt; 1 ..        
c370: 2f 2f 2f 20 20 61 72 67 76 5b 30 5d 20 26 23 38  ///  argv[0] &#8
c380: 38 30 30 3b 20 4e 55 4c 4c 20 0d 0a 20 20 20 20  800; NULL ..    
c390: 20 20 20 20 2f 2f 2f 20 20 61 72 67 76 5b 30 5d      ///  argv[0]
c3a0: 20 3d 20 61 72 67 76 5b 31 5d 0d 0a 20 20 20 20   = argv[1]..    
c3b0: 20 20 20 20 2f 2f 2f 20 54 68 65 20 72 6f 77 20      /// The row 
c3c0: 77 69 74 68 20 72 6f 77 69 64 20 61 72 67 76 5b  with rowid argv[
c3d0: 30 5d 20 69 73 20 75 70 64 61 74 65 64 20 77 69  0] is updated wi
c3e0: 74 68 20 6e 65 77 20 76 61 6c 75 65 73 20 0d 0a  th new values ..
c3f0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20          ///     
c400: 20 20 20 69 6e 20 61 72 67 76 5b 32 5d 20 61 6e     in argv[2] an
c410: 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 61 72 61  d following para
c420: 6d 65 74 65 72 73 2e 0d 0a 20 20 20 20 20 20 20  meters...       
c430: 20 2f 2f 2f 20 61 72 67 63 20 26 67 74 3b 20 31   /// argc &gt; 1
c440: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20   ..        ///  
c450: 61 72 67 76 5b 30 5d 20 26 23 38 38 30 30 3b 20  argv[0] &#8800; 
c460: 4e 55 4c 4c 20 0d 0a 20 20 20 20 20 20 20 20 2f  NULL ..        /
c470: 2f 2f 20 20 61 72 67 76 5b 30 5d 20 26 23 38 38  //  argv[0] &#88
c480: 30 30 3b 20 61 72 67 76 5b 31 5d 0d 0a 20 20 20  00; argv[1]..   
c490: 20 20 20 20 20 2f 2f 2f 20 20 54 68 65 20 72 6f       ///  The ro
c4a0: 77 20 77 69 74 68 20 72 6f 77 69 64 20 61 72 67  w with rowid arg
c4b0: 76 5b 30 5d 20 69 73 20 75 70 64 61 74 65 64 20  v[0] is updated 
c4c0: 77 69 74 68 20 72 6f 77 69 64 20 61 72 67 76 5b  with rowid argv[
c4d0: 31 5d 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  1] ..        ///
c4e0: 20 61 6e 64 20 6e 65 77 20 76 61 6c 75 65 73 20   and new values 
c4f0: 69 6e 20 61 72 67 76 5b 32 5d 20 61 6e 64 20 66  in argv[2] and f
c500: 6f 6c 6c 6f 77 69 6e 67 20 70 61 72 61 6d 65 74  ollowing paramet
c510: 65 72 73 2e 20 54 68 69 73 20 77 69 6c 6c 20 6f  ers. This will o
c520: 63 63 75 72 20 0d 0a 20 20 20 20 20 20 20 20 2f  ccur ..        /
c530: 2f 2f 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73  // when an SQL s
c540: 74 61 74 65 6d 65 6e 74 20 75 70 64 61 74 65 73  tatement updates
c550: 20 61 20 72 6f 77 69 64 2c 20 61 73 20 69 6e 20   a rowid, as in 
c560: 74 68 65 20 73 74 61 74 65 6d 65 6e 74 3a 0d 0a  the statement:..
c570: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
c580: 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20  a><code>..      
c590: 20 20 2f 2f 2f 20 20 20 20 55 50 44 41 54 45 20    ///    UPDATE 
c5a0: 74 61 62 6c 65 20 53 45 54 20 72 6f 77 69 64 3d  table SET rowid=
c5b0: 72 6f 77 69 64 2b 31 20 57 48 45 52 45 20 2e 2e  rowid+1 WHERE ..
c5c0: 2e 3b 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  .; ..        ///
c5d0: 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d   </code></para>.
c5e0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63  .        /// </c
c5f0: 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  ode></para>..   
c600: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
c610: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65  .        /// The
c620: 20 78 55 70 64 61 74 65 20 6d 65 74 68 6f 64 20   xUpdate method 
c630: 6d 75 73 74 20 72 65 74 75 72 6e 20 53 51 4c 49  must return SQLI
c640: 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c  TE_OK if and onl
c650: 79 20 69 66 20 69 74 20 69 73 0d 0a 20 20 20 20  y if it is..    
c660: 20 20 20 20 2f 2f 2f 20 73 75 63 63 65 73 73 66      /// successf
c670: 75 6c 2e 20 20 49 66 20 61 20 66 61 69 6c 75 72  ul.  If a failur
c680: 65 20 6f 63 63 75 72 73 2c 20 74 68 65 20 78 55  e occurs, the xU
c690: 70 64 61 74 65 20 6d 75 73 74 20 72 65 74 75 72  pdate must retur
c6a0: 6e 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  n an appropriate
c6b0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 65 72  ..        /// er
c6c0: 72 6f 72 20 63 6f 64 65 2e 20 20 4f 6e 20 61 20  ror code.  On a 
c6d0: 66 61 69 6c 75 72 65 2c 20 74 68 65 20 70 56 54  failure, the pVT
c6e0: 61 62 2d 3e 7a 45 72 72 4d 73 67 20 65 6c 65 6d  ab->zErrMsg elem
c6f0: 65 6e 74 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c  ent may optional
c700: 6c 79 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ly..        /// 
c710: 62 65 20 72 65 70 6c 61 63 65 64 20 77 69 74 68  be replaced with
c720: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
c730: 65 78 74 20 73 74 6f 72 65 64 20 69 6e 20 6d 65  ext stored in me
c740: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 66  mory allocated f
c750: 72 6f 6d 20 53 51 4c 69 74 65 20 0d 0a 20 20 20  rom SQLite ..   
c760: 20 20 20 20 20 2f 2f 2f 20 75 73 69 6e 67 20 66       /// using f
c770: 75 6e 63 74 69 6f 6e 73 20 73 75 63 68 20 61 73  unctions such as
c780: 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
c790: 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6d 61  () or sqlite3_ma
c7a0: 6c 6c 6f 63 28 29 2e 0d 0a 20 20 20 20 20 20 20  lloc()...       
c7b0: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
c7c0: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
c7d0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 49 66  ..        /// If
c7e0: 20 74 68 65 20 78 55 70 64 61 74 65 20 6d 65 74   the xUpdate met
c7f0: 68 6f 64 20 76 69 6f 6c 61 74 65 73 20 73 6f 6d  hod violates som
c800: 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 6f 66 20  e constraint of 
c810: 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
c820: 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 28  e..        /// (
c830: 69 6e 63 6c 75 64 69 6e 67 2c 20 62 75 74 20 6e  including, but n
c840: 6f 74 20 6c 69 6d 69 74 65 64 20 74 6f 2c 20 61  ot limited to, a
c850: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 74 6f  ttempting to sto
c860: 72 65 20 61 20 76 61 6c 75 65 20 6f 66 20 74 68  re a value of th
c870: 65 20 77 72 6f 6e 67 20 0d 0a 20 20 20 20 20 20  e wrong ..      
c880: 20 20 2f 2f 2f 20 64 61 74 61 74 79 70 65 2c 20    /// datatype, 
c890: 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 74  attempting to st
c8a0: 6f 72 65 20 61 20 76 61 6c 75 65 20 74 68 61 74  ore a value that
c8b0: 20 69 73 20 74 6f 6f 0d 0a 20 20 20 20 20 20 20   is too..       
c8c0: 20 2f 2f 2f 20 6c 61 72 67 65 20 6f 72 20 74 6f   /// large or to
c8d0: 6f 20 73 6d 61 6c 6c 2c 20 6f 72 20 61 74 74 65  o small, or atte
c8e0: 6d 70 74 69 6e 67 20 74 6f 20 63 68 61 6e 67 65  mpting to change
c8f0: 20 61 20 72 65 61 64 2d 6f 6e 6c 79 20 76 61 6c   a read-only val
c900: 75 65 29 20 74 68 65 6e 20 74 68 65 0d 0a 20 20  ue) then the..  
c910: 20 20 20 20 20 20 2f 2f 2f 20 78 55 70 64 61 74        /// xUpdat
c920: 65 20 6d 75 73 74 20 66 61 69 6c 20 77 69 74 68  e must fail with
c930: 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
c940: 65 72 72 6f 72 20 63 6f 64 65 2e 0d 0a 20 20 20  error code...   
c950: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e       /// </para>
c960: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
c970: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
c980: 2f 20 54 68 65 72 65 20 6d 69 67 68 74 20 62 65  / There might be
c990: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 71 6c   one or more sql
c9a0: 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
c9b0: 20 6f 62 6a 65 63 74 73 20 6f 70 65 6e 20 61 6e   objects open an
c9c0: 64 20 69 6e 20 75 73 65 20 0d 0a 20 20 20 20 20  d in use ..     
c9d0: 20 20 20 2f 2f 2f 20 6f 6e 20 74 68 65 20 76 69     /// on the vi
c9e0: 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 73 74  rtual table inst
c9f0: 61 6e 63 65 20 61 6e 64 20 70 65 72 68 61 70 73  ance and perhaps
ca00: 20 65 76 65 6e 20 6f 6e 20 74 68 65 20 72 6f 77   even on the row
ca10: 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 0d   of the virtual.
ca20: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 61 62  .        /// tab
ca30: 6c 65 20 77 68 65 6e 20 74 68 65 20 78 55 70 64  le when the xUpd
ca40: 61 74 65 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  ate method is in
ca50: 76 6f 6b 65 64 2e 20 20 54 68 65 20 69 6d 70 6c  voked.  The impl
ca60: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 0d 0a 20  ementation of.. 
ca70: 20 20 20 20 20 20 20 2f 2f 2f 20 78 55 70 64 61         /// xUpda
ca80: 74 65 20 6d 75 73 74 20 62 65 20 70 72 65 70 61  te must be prepa
ca90: 72 65 64 20 66 6f 72 20 61 74 74 65 6d 70 74 73  red for attempts
caa0: 20 74 6f 20 64 65 6c 65 74 65 20 6f 72 20 6d 6f   to delete or mo
cab0: 64 69 66 79 20 72 6f 77 73 20 6f 66 20 74 68 65  dify rows of the
cac0: 20 74 61 62 6c 65 0d 0a 20 20 20 20 20 20 20 20   table..        
cad0: 2f 2f 2f 20 6f 75 74 20 66 72 6f 6d 20 6f 74 68  /// out from oth
cae0: 65 72 20 65 78 69 73 74 69 6e 67 20 63 75 72 73  er existing curs
caf0: 6f 72 73 2e 20 20 49 66 20 74 68 65 20 76 69 72  ors.  If the vir
cb00: 74 75 61 6c 20 74 61 62 6c 65 20 63 61 6e 6e 6f  tual table canno
cb10: 74 20 61 63 63 6f 6d 6d 6f 64 61 74 65 0d 0a 20  t accommodate.. 
cb20: 20 20 20 20 20 20 20 2f 2f 2f 20 73 75 63 68 20         /// such 
cb30: 63 68 61 6e 67 65 73 2c 20 74 68 65 20 78 55 70  changes, the xUp
cb40: 64 61 74 65 20 6d 65 74 68 6f 64 20 6d 75 73 74  date method must
cb50: 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72   return an error
cb60: 20 63 6f 64 65 2e 0d 0a 20 20 20 20 20 20 20 20   code...        
cb70: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
cb80: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
cb90: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65  .        /// The
cba0: 20 78 55 70 64 61 74 65 20 6d 65 74 68 6f 64 20   xUpdate method 
cbb0: 69 73 20 6f 70 74 69 6f 6e 61 6c 2e 0d 0a 20 20  is optional...  
cbc0: 20 20 20 20 20 20 2f 2f 2f 20 49 66 20 74 68 65        /// If the
cbd0: 20 78 55 70 64 61 74 65 20 70 6f 69 6e 74 65 72   xUpdate pointer
cbe0: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f   in the sqlite3_
cbf0: 6d 6f 64 75 6c 65 20 66 6f 72 20 61 20 76 69 72  module for a vir
cc00: 74 75 61 6c 20 74 61 62 6c 65 0d 0a 20 20 20 20  tual table..    
cc10: 20 20 20 20 2f 2f 2f 20 69 73 20 61 20 4e 55 4c      /// is a NUL
cc20: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
cc30: 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
cc40: 65 20 69 73 20 72 65 61 64 2d 6f 6e 6c 79 2e 0d  e is read-only..
cc50: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
cc60: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
cc70: 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a 20 20  / </summary>..  
cc80: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d        /// <param
cc90: 20 6e 61 6d 65 3d 22 70 56 74 61 62 22 3e 0d 0a   name="pVtab">..
cca0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20          /// The 
ccb0: 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72 20 74  native pointer t
ccc0: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 74  o the sqlite3_vt
ccd0: 61 62 20 64 65 72 69 76 65 64 20 73 74 72 75 63  ab derived struc
cce0: 74 75 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f  ture...        /
ccf0: 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20  // </param>..   
cd00: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20       /// <param 
cd10: 6e 61 6d 65 3d 22 61 72 67 63 22 3e 0d 0a 20 20  name="argc">..  
cd20: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e 75        /// The nu
cd30: 6d 62 65 72 20 6f 66 20 6e 65 77 20 6f 72 20 6d  mber of new or m
cd40: 6f 64 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 76  odified column v
cd50: 61 6c 75 65 73 20 63 6f 6e 74 61 69 6e 65 64 20  alues contained 
cd60: 69 6e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  in..        /// 
cd70: 3c 70 61 72 61 6d 72 65 66 20 6e 61 6d 65 3d 22  <paramref name="
cd80: 61 72 67 76 22 20 2f 3e 2e 0d 0a 20 20 20 20 20  argv" />...     
cd90: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d     /// </param>.
cda0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
cdb0: 72 61 6d 20 6e 61 6d 65 3d 22 61 72 67 76 22 3e  ram name="argv">
cdc0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
cdd0: 65 20 61 72 72 61 79 20 6f 66 20 6e 61 74 69 76  e array of nativ
cde0: 65 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 71  e pointers to sq
cdf0: 6c 69 74 65 33 5f 76 61 6c 75 65 20 73 74 72 75  lite3_value stru
ce00: 63 74 75 72 65 73 20 63 6f 6e 74 61 69 6e 69 6e  ctures containin
ce10: 67 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74  g..        /// t
ce20: 68 65 20 6e 65 77 20 6f 72 20 6d 6f 64 69 66 69  he new or modifi
ce30: 65 64 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 73  ed column values
ce40: 2c 20 69 66 20 61 6e 79 2e 0d 0a 20 20 20 20 20  , if any...     
ce50: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d     /// </param>.
ce60: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
ce70: 72 61 6d 20 6e 61 6d 65 3d 22 72 6f 77 49 64 22  ram name="rowId"
ce80: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 55  >..        /// U
ce90: 70 6f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 69  pon success, thi
cea0: 73 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  s parameter must
ceb0: 20 62 65 20 6d 6f 64 69 66 69 65 64 20 74 6f 20   be modified to 
cec0: 63 6f 6e 74 61 69 6e 20 74 68 65 20 75 6e 69 71  contain the uniq
ced0: 75 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ue..        /// 
cee0: 69 6e 74 65 67 65 72 20 72 6f 77 20 69 64 65 6e  integer row iden
cef0: 74 69 66 69 65 72 20 66 6f 72 20 74 68 65 20 72  tifier for the r
cf00: 6f 77 20 74 68 61 74 20 77 61 73 20 69 6e 73 65  ow that was inse
cf10: 72 74 65 64 2c 20 69 66 20 61 6e 79 2e 0d 0a 20  rted, if any... 
cf20: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
cf30: 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  am>..        ///
cf40: 20 3c 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20   <returns>..    
cf50: 20 20 20 20 2f 2f 2f 20 41 20 73 74 61 6e 64 61      /// A standa
cf60: 72 64 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  rd SQLite return
cf70: 20 63 6f 64 65 2e 0d 0a 20 20 20 20 20 20 20 20   code...        
cf80: 2f 2f 2f 20 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a  /// </returns>..
cf90: 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 45 72          SQLiteEr
cfa0: 72 6f 72 43 6f 64 65 20 78 55 70 64 61 74 65 28  rorCode xUpdate(
cfb0: 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 49 6e  ..            In
cfc0: 74 50 74 72 20 70 56 74 61 62 2c 0d 0a 20 20 20  tPtr pVtab,..   
cfd0: 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
cfe0: 63 2c 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20  c,..            
cff0: 49 6e 74 50 74 72 20 61 72 67 76 2c 0d 0a 20 20  IntPtr argv,..  
d000: 20 20 20 20 20 20 20 20 20 20 72 65 66 20 6c 6f            ref lo
d010: 6e 67 20 72 6f 77 49 64 0d 0a 20 20 20 20 20 20  ng rowId..      
d020: 20 20 20 20 20 20 29 3b 0d 0a 0d 0a 20 20 20 20        );....    
d030: 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f      ////////////
d040: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
d050: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
d060: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
d070: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20  ///////////.... 
d080: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d         /// <summ
d090: 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ary>..        //
d0a0: 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a  / <para><code>..
d0b0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 69 6e          ///   in
d0c0: 74 20 28 2a 78 42 65 67 69 6e 29 28 73 71 6c 69  t (*xBegin)(sqli
d0d0: 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
d0e0: 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ;..        /// <
d0f0: 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20  /code></para>.. 
d100: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
d110: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54  >..        /// T
d120: 68 69 73 20 6d 65 74 68 6f 64 20 62 65 67 69 6e  his method begin
d130: 73 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  s a transaction 
d140: 6f 6e 20 61 20 76 69 72 74 75 61 6c 20 74 61 62  on a virtual tab
d150: 6c 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  le...        ///
d160: 20 54 68 69 73 20 69 73 20 6d 65 74 68 6f 64 20   This is method 
d170: 69 73 20 6f 70 74 69 6f 6e 61 6c 2e 20 20 54 68  is optional.  Th
d180: 65 20 78 42 65 67 69 6e 20 70 6f 69 6e 74 65 72  e xBegin pointer
d190: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75   of sqlite3_modu
d1a0: 6c 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  le..        /// 
d1b0: 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0d 0a 20 20  may be NULL...  
d1c0: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61        /// </para
d1d0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
d1e0: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
d1f0: 2f 2f 20 54 68 69 73 20 6d 65 74 68 6f 64 20 69  // This method i
d200: 73 20 61 6c 77 61 79 73 20 66 6f 6c 6c 6f 77 65  s always followe
d210: 64 20 62 79 20 6f 6e 65 20 63 61 6c 6c 20 74 6f  d by one call to
d220: 20 65 69 74 68 65 72 20 74 68 65 0d 0a 20 20 20   either the..   
d230: 20 20 20 20 20 2f 2f 2f 20 78 43 6f 6d 6d 69 74       /// xCommit
d240: 20 6f 72 20 78 52 6f 6c 6c 62 61 63 6b 20 6d 65   or xRollback me
d250: 74 68 6f 64 2e 20 20 56 69 72 74 75 61 6c 20 74  thod.  Virtual t
d260: 61 62 6c 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  able transaction
d270: 73 20 64 6f 0d 0a 20 20 20 20 20 20 20 20 2f 2f  s do..        //
d280: 2f 20 6e 6f 74 20 6e 65 73 74 2c 20 73 6f 20 74  / not nest, so t
d290: 68 65 20 78 42 65 67 69 6e 20 6d 65 74 68 6f 64  he xBegin method
d2a0: 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 69 6e 76   will not be inv
d2b0: 6f 6b 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f  oked more than o
d2c0: 6e 63 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  nce..        ///
d2d0: 20 6f 6e 20 61 20 73 69 6e 67 6c 65 20 76 69 72   on a single vir
d2e0: 74 75 61 6c 20 74 61 62 6c 65 0d 0a 20 20 20 20  tual table..    
d2f0: 20 20 20 20 2f 2f 2f 20 77 69 74 68 6f 75 74 20      /// without 
d300: 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 20 63  an intervening c
d310: 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 78 43  all to either xC
d320: 6f 6d 6d 69 74 20 6f 72 20 78 52 6f 6c 6c 62 61  ommit or xRollba
d330: 63 6b 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ck...        ///
d340: 20 4d 75 6c 74 69 70 6c 65 20 63 61 6c 6c 73 20   Multiple calls 
d350: 74 6f 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73  to other methods
d360: 20 63 61 6e 20 61 6e 64 20 6c 69 6b 65 6c 79 20   can and likely 
d370: 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e 20 62 65  will occur in be
d380: 74 77 65 65 6e 0d 0a 20 20 20 20 20 20 20 20 2f  tween..        /
d390: 2f 2f 20 74 68 65 20 78 42 65 67 69 6e 20 61 6e  // the xBegin an
d3a0: 64 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  d the correspond
d3b0: 69 6e 67 20 78 43 6f 6d 6d 69 74 20 6f 72 20 78  ing xCommit or x
d3c0: 52 6f 6c 6c 62 61 63 6b 2e 0d 0a 20 20 20 20 20  Rollback...     
d3d0: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a     /// </para>..
d3e0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 73 75          /// </su
d3f0: 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20  mmary>..        
d400: 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d  /// <param name=
d410: 22 70 56 74 61 62 22 3e 0d 0a 20 20 20 20 20 20  "pVtab">..      
d420: 20 20 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76 65    /// The native
d430: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
d440: 73 71 6c 69 74 65 33 5f 76 74 61 62 20 64 65 72  sqlite3_vtab der
d450: 69 76 65 64 20 73 74 72 75 63 74 75 72 65 2e 0d  ived structure..
d460: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
d470: 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f  aram>..        /
d480: 2f 2f 20 3c 72 65 74 75 72 6e 73 3e 0d 0a 20 20  // <returns>..  
d490: 20 20 20 20 20 20 2f 2f 2f 20 41 20 73 74 61 6e        /// A stan
d4a0: 64 61 72 64 20 53 51 4c 69 74 65 20 72 65 74 75  dard SQLite retu
d4b0: 72 6e 20 63 6f 64 65 2e 0d 0a 20 20 20 20 20 20  rn code...      
d4c0: 20 20 2f 2f 2f 20 3c 2f 72 65 74 75 72 6e 73 3e    /// </returns>
d4d0: 0d 0a 20 20 20 20 20 20 20 20 53 51 4c 69 74 65  ..        SQLite
d4e0: 45 72 72 6f 72 43 6f 64 65 20 78 42 65 67 69 6e  ErrorCode xBegin
d4f0: 28 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 49  (..            I
d500: 6e 74 50 74 72 20 70 56 74 61 62 0d 0a 20 20 20  ntPtr pVtab..   
d510: 20 20 20 20 20 20 20 20 20 29 3b 0d 0a 0d 0a 20           );.... 
d520: 20 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f         /////////
d530: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
d540: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
d550: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
d560: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a  //////////////..
d570: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 73  ..        /// <s
d580: 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20  ummary>..       
d590: 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65   /// <para><code
d5a0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20  >..        ///  
d5b0: 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71   int (*xSync)(sq
d5c0: 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
d5d0: 62 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  b);..        ///
d5e0: 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d   </code></para>.
d5f0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
d600: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
d610: 20 54 68 69 73 20 6d 65 74 68 6f 64 20 73 69 67   This method sig
d620: 6e 61 6c 73 20 74 68 65 20 73 74 61 72 74 20 6f  nals the start o
d630: 66 20 61 20 74 77 6f 2d 70 68 61 73 65 20 63 6f  f a two-phase co
d640: 6d 6d 69 74 20 6f 6e 20 61 20 76 69 72 74 75 61  mmit on a virtua
d650: 6c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74  l..        /// t
d660: 61 62 6c 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f  able...        /
d670: 2f 2f 20 54 68 69 73 20 69 73 20 6d 65 74 68 6f  // This is metho
d680: 64 20 69 73 20 6f 70 74 69 6f 6e 61 6c 2e 20 20  d is optional.  
d690: 54 68 65 20 78 53 79 6e 63 20 70 6f 69 6e 74 65  The xSync pointe
d6a0: 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d 6f 64  r of sqlite3_mod
d6b0: 75 6c 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ule..        ///
d6c0: 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0d 0a 20   may be NULL... 
d6d0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
d6e0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
d6f0: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
d700: 2f 2f 2f 20 54 68 69 73 20 6d 65 74 68 6f 64 20  /// This method 
d710: 69 73 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 64 20  is only invoked 
d720: 61 66 74 65 72 20 63 61 6c 6c 20 74 6f 20 74 68  after call to th
d730: 65 20 78 42 65 67 69 6e 20 6d 65 74 68 6f 64 20  e xBegin method 
d740: 61 6e 64 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  and..        ///
d750: 20 70 72 69 6f 72 20 74 6f 20 61 6e 20 78 43 6f   prior to an xCo
d760: 6d 6d 69 74 20 6f 72 20 78 52 6f 6c 6c 62 61 63  mmit or xRollbac
d770: 6b 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20  k.  In order to 
d780: 69 6d 70 6c 65 6d 65 6e 74 20 74 77 6f 2d 70 68  implement two-ph
d790: 61 73 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ase..        ///
d7a0: 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20 78 53 79   commit, the xSy
d7b0: 6e 63 20 6d 65 74 68 6f 64 20 6f 6e 20 61 6c 6c  nc method on all
d7c0: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   virtual tables 
d7d0: 69 73 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72  is invoked prior
d7e0: 20 74 6f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f   to..        ///
d7f0: 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 78 43   invoking the xC
d800: 6f 6d 6d 69 74 20 6d 65 74 68 6f 64 20 6f 6e 20  ommit method on 
d810: 61 6e 79 20 76 69 72 74 75 61 6c 20 74 61 62 6c  any virtual tabl
d820: 65 2e 20 20 49 66 20 61 6e 79 20 6f 66 20 74 68  e.  If any of th
d830: 65 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e ..        /// 
d840: 78 53 79 6e 63 20 6d 65 74 68 6f 64 73 20 66 61  xSync methods fa
d850: 69 6c 2c 20 74 68 65 20 65 6e 74 69 72 65 20 74  il, the entire t
d860: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 72 6f  ransaction is ro
d870: 6c 6c 65 64 20 62 61 63 6b 2e 0d 0a 20 20 20 20  lled back...    
d880: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
d890: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 73  .        /// </s
d8a0: 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20  ummary>..       
d8b0: 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65   /// <param name
d8c0: 3d 22 70 56 74 61 62 22 3e 0d 0a 20 20 20 20 20  ="pVtab">..     
d8d0: 20 20 20 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76     /// The nativ
d8e0: 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
d8f0: 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 64 65   sqlite3_vtab de
d900: 72 69 76 65 64 20 73 74 72 75 63 74 75 72 65 2e  rived structure.
d910: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
d920: 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20  param>..        
d930: 2f 2f 2f 20 3c 72 65 74 75 72 6e 73 3e 0d 0a 20  /// <returns>.. 
d940: 20 20 20 20 20 20 20 2f 2f 2f 20 41 20 73 74 61         /// A sta
d950: 6e 64 61 72 64 20 53 51 4c 69 74 65 20 72 65 74  ndard SQLite ret
d960: 75 72 6e 20 63 6f 64 65 2e 0d 0a 20 20 20 20 20  urn code...     
d970: 20 20 20 2f 2f 2f 20 3c 2f 72 65 74 75 72 6e 73     /// </returns
d980: 3e 0d 0a 20 20 20 20 20 20 20 20 53 51 4c 69 74  >..        SQLit
d990: 65 45 72 72 6f 72 43 6f 64 65 20 78 53 79 6e 63  eErrorCode xSync
d9a0: 28 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 49  (..            I
d9b0: 6e 74 50 74 72 20 70 56 74 61 62 0d 0a 20 20 20  ntPtr pVtab..   
d9c0: 20 20 20 20 20 20 20 20 20 29 3b 0d 0a 0d 0a 20           );.... 
d9d0: 20 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f         /////////
d9e0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
d9f0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
da00: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
da10: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a  //////////////..
da20: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 73  ..        /// <s
da30: 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20  ummary>..       
da40: 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65   /// <para><code
da50: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20  >..        ///  
da60: 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28   int (*xCommit)(
da70: 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
da80: 54 61 62 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f  Tab);..        /
da90: 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61  // </code></para
daa0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
dab0: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
dac0: 2f 2f 20 54 68 69 73 20 6d 65 74 68 6f 64 20 63  // This method c
dad0: 61 75 73 65 73 20 61 20 76 69 72 74 75 61 6c 20  auses a virtual 
dae0: 74 61 62 6c 65 20 74 72 61 6e 73 61 63 74 69 6f  table transactio
daf0: 6e 20 74 6f 20 63 6f 6d 6d 69 74 2e 0d 0a 20 20  n to commit...  
db00: 20 20 20 20 20 20 2f 2f 2f 20 54 68 69 73 20 69        /// This i
db10: 73 20 6d 65 74 68 6f 64 20 69 73 20 6f 70 74 69  s method is opti
db20: 6f 6e 61 6c 2e 20 20 54 68 65 20 78 43 6f 6d 6d  onal.  The xComm
db30: 69 74 20 70 6f 69 6e 74 65 72 20 6f 66 20 73 71  it pointer of sq
db40: 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 0d 0a 20 20  lite3_module..  
db50: 20 20 20 20 20 20 2f 2f 2f 20 6d 61 79 20 62 65        /// may be
db60: 20 4e 55 4c 4c 2e 0d 0a 20 20 20 20 20 20 20 20   NULL...        
db70: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
db80: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
db90: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 20 63  .        /// A c
dba0: 61 6c 6c 20 74 6f 20 74 68 69 73 20 6d 65 74 68  all to this meth
dbb0: 6f 64 20 61 6c 77 61 79 73 20 66 6f 6c 6c 6f 77  od always follow
dbc0: 73 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  s a prior call t
dbd0: 6f 20 78 42 65 67 69 6e 20 61 6e 64 0d 0a 20 20  o xBegin and..  
dbe0: 20 20 20 20 20 20 2f 2f 2f 20 78 53 79 6e 63 2e        /// xSync.
dbf0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
dc00: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
dc10: 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a 20  // </summary>.. 
dc20: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
dc30: 6d 20 6e 61 6d 65 3d 22 70 56 74 61 62 22 3e 0d  m name="pVtab">.
dc40: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65  .        /// The
dc50: 20 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72 20   native pointer 
dc60: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  to the sqlite3_v
dc70: 74 61 62 20 64 65 72 69 76 65 64 20 73 74 72 75  tab derived stru
dc80: 63 74 75 72 65 2e 0d 0a 20 20 20 20 20 20 20 20  cture...        
dc90: 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20  /// </param>..  
dca0: 20 20 20 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72        /// <retur
dcb0: 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ns>..        ///
dcc0: 20 41 20 73 74 61 6e 64 61 72 64 20 53 51 4c 69   A standard SQLi
dcd0: 74 65 20 72 65 74 75 72 6e 20 63 6f 64 65 2e 0d  te return code..
dce0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72  .        /// </r
dcf0: 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20  eturns>..       
dd00: 20 53 51 4c 69 74 65 45 72 72 6f 72 43 6f 64 65   SQLiteErrorCode
dd10: 20 78 43 6f 6d 6d 69 74 28 0d 0a 20 20 20 20 20   xCommit(..     
dd20: 20 20 20 20 20 20 20 49 6e 74 50 74 72 20 70 56         IntPtr pV
dd30: 74 61 62 0d 0a 20 20 20 20 20 20 20 20 20 20 20  tab..           
dd40: 20 29 3b 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f   );....        /
dd50: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
dd60: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
dd70: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
dd80: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
dd90: 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 20 20  //////....      
dda0: 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d    /// <summary>.
ddb0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
ddc0: 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20  ra><code>..     
ddd0: 20 20 20 2f 2f 2f 20 20 20 69 6e 74 20 28 2a 78     ///   int (*x
dde0: 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65  Rollback)(sqlite
ddf0: 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0d  3_vtab *pVTab);.
de00: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63  .        /// </c
de10: 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  ode></para>..   
de20: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
de30: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 69  .        /// Thi
de40: 73 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20  s method causes 
de50: 61 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  a virtual table 
de60: 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 72  transaction to r
de70: 6f 6c 6c 62 61 63 6b 2e 0d 0a 20 20 20 20 20 20  ollback...      
de80: 20 20 2f 2f 2f 20 54 68 69 73 20 69 73 20 6d 65    /// This is me
de90: 74 68 6f 64 20 69 73 20 6f 70 74 69 6f 6e 61 6c  thod is optional
dea0: 2e 20 20 54 68 65 20 78 52 6f 6c 6c 62 61 63 6b  .  The xRollback
deb0: 20 70 6f 69 6e 74 65 72 20 6f 66 20 73 71 6c 69   pointer of sqli
dec0: 74 65 33 5f 6d 6f 64 75 6c 65 0d 0a 20 20 20 20  te3_module..    
ded0: 20 20 20 20 2f 2f 2f 20 6d 61 79 20 62 65 20 4e      /// may be N
dee0: 55 4c 4c 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ULL...        //
def0: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  / </para>..     
df00: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20     /// <para>.. 
df10: 20 20 20 20 20 20 20 2f 2f 2f 20 41 20 63 61 6c         /// A cal
df20: 6c 20 74 6f 20 74 68 69 73 20 6d 65 74 68 6f 64  l to this method
df30: 20 61 6c 77 61 79 73 20 66 6f 6c 6c 6f 77 73 20   always follows 
df40: 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20  a prior call to 
df50: 78 42 65 67 69 6e 2e 0d 0a 20 20 20 20 20 20 20  xBegin...       
df60: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
df70: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d        /// </summ
df80: 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ary>..        //
df90: 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70  / <param name="p
dfa0: 56 74 61 62 22 3e 0d 0a 20 20 20 20 20 20 20 20  Vtab">..        
dfb0: 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76 65 20 70  /// The native p
dfc0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 71  ointer to the sq
dfd0: 6c 69 74 65 33 5f 76 74 61 62 20 64 65 72 69 76  lite3_vtab deriv
dfe0: 65 64 20 73 74 72 75 63 74 75 72 65 2e 0d 0a 20  ed structure... 
dff0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
e000: 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  am>..        ///
e010: 20 3c 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20   <returns>..    
e020: 20 20 20 20 2f 2f 2f 20 41 20 73 74 61 6e 64 61      /// A standa
e030: 72 64 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  rd SQLite return
e040: 20 63 6f 64 65 2e 0d 0a 20 20 20 20 20 20 20 20   code...        
e050: 2f 2f 2f 20 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a  /// </returns>..
e060: 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 45 72          SQLiteEr
e070: 72 6f 72 43 6f 64 65 20 78 52 6f 6c 6c 62 61 63  rorCode xRollbac
e080: 6b 28 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20  k(..            
e090: 49 6e 74 50 74 72 20 70 56 74 61 62 0d 0a 20 20  IntPtr pVtab..  
e0a0: 20 20 20 20 20 20 20 20 20 20 29 3b 0d 0a 0d 0a            );....
e0b0: 20 20 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f          ////////
e0c0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
e0d0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
e0e0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
e0f0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d  ///////////////.
e100: 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
e110: 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20  summary>..      
e120: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64    /// <para><cod
e130: 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e>..        /// 
e140: 20 20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e    int (*xFindFun
e150: 63 74 69 6f 6e 29 28 0d 0a 20 20 20 20 20 20 20  ction)(..       
e160: 20 2f 2f 2f 20 20 20 20 20 73 71 6c 69 74 65 33   ///     sqlite3
e170: 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 0d 0a 20  _vtab *pVtab,.. 
e180: 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 69         ///     i
e190: 6e 74 20 6e 41 72 67 2c 0d 0a 20 20 20 20 20 20  nt nArg,..      
e1a0: 20 20 2f 2f 2f 20 20 20 20 20 63 6f 6e 73 74 20    ///     const 
e1b0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0d 0a 20 20  char *zName,..  
e1c0: 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 76 6f        ///     vo
e1d0: 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71  id (**pxFunc)(sq
e1e0: 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
e1f0: 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
e200: 2a 2a 29 2c 0d 0a 20 20 20 20 20 20 20 20 2f 2f  **),..        //
e210: 2f 20 20 20 20 20 76 6f 69 64 20 2a 2a 70 70 41  /     void **ppA
e220: 72 67 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  rg..        /// 
e230: 20 20 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f    );..        //
e240: 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e  / </code></para>
e250: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
e260: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
e270: 2f 20 54 68 69 73 20 6d 65 74 68 6f 64 20 69 73  / This method is
e280: 20 63 61 6c 6c 65 64 20 64 75 72 69 6e 67 20 73   called during s
e290: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
e2a0: 20 74 6f 20 67 69 76 65 20 74 68 65 20 76 69 72   to give the vir
e2b0: 74 75 61 6c 0d 0a 20 20 20 20 20 20 20 20 2f 2f  tual..        //
e2c0: 2f 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  / table implemen
e2d0: 74 61 74 69 6f 6e 20 61 6e 20 6f 70 70 6f 72 74  tation an opport
e2e0: 75 6e 69 74 79 20 74 6f 20 6f 76 65 72 6c 6f 61  unity to overloa
e2f0: 64 20 66 75 6e 63 74 69 6f 6e 73 2e 20 0d 0a 20  d functions. .. 
e300: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 69 73 20         /// This 
e310: 6d 65 74 68 6f 64 20 6d 61 79 20 62 65 20 73 65  method may be se
e320: 74 20 74 6f 20 4e 55 4c 4c 20 69 6e 20 77 68 69  t to NULL in whi
e330: 63 68 20 63 61 73 65 20 6e 6f 20 6f 76 65 72 6c  ch case no overl
e340: 6f 61 64 69 6e 67 20 6f 63 63 75 72 73 2e 0d 0a  oading occurs...
e350: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
e360: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
e370: 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20   <para>..       
e380: 20 2f 2f 2f 20 57 68 65 6e 20 61 20 66 75 6e 63   /// When a func
e390: 74 69 6f 6e 20 75 73 65 73 20 61 20 63 6f 6c 75  tion uses a colu
e3a0: 6d 6e 20 66 72 6f 6d 20 61 20 76 69 72 74 75 61  mn from a virtua
e3b0: 6c 20 74 61 62 6c 65 20 61 73 20 69 74 73 20 66  l table as its f
e3c0: 69 72 73 74 20 0d 0a 20 20 20 20 20 20 20 20 2f  irst ..        /
e3d0: 2f 2f 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 69  // argument, thi
e3e0: 73 20 6d 65 74 68 6f 64 20 69 73 20 63 61 6c 6c  s method is call
e3f0: 65 64 20 74 6f 20 73 65 65 20 69 66 20 74 68 65  ed to see if the
e400: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 77   virtual table w
e410: 6f 75 6c 64 20 0d 0a 20 20 20 20 20 20 20 20 2f  ould ..        /
e420: 2f 2f 20 6c 69 6b 65 20 74 6f 20 6f 76 65 72 6c  // like to overl
e430: 6f 61 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  oad the function
e440: 2e 20 54 68 65 20 66 69 72 73 74 20 74 68 72 65  . The first thre
e450: 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  e parameters are
e460: 20 69 6e 70 75 74 73 3a 20 0d 0a 20 20 20 20 20   inputs: ..     
e470: 20 20 20 2f 2f 2f 20 74 68 65 20 76 69 72 74 75     /// the virtu
e480: 61 6c 20 74 61 62 6c 65 2c 20 74 68 65 20 6e 75  al table, the nu
e490: 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
e4a0: 73 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f  s to the functio
e4b0: 6e 2c 20 61 6e 64 20 74 68 65 20 0d 0a 20 20 20  n, and the ..   
e4c0: 20 20 20 20 20 2f 2f 2f 20 6e 61 6d 65 20 6f 66       /// name of
e4d0: 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2e 20 49   the function. I
e4e0: 66 20 6e 6f 20 6f 76 65 72 6c 6f 61 64 69 6e 67  f no overloading
e4f0: 20 69 73 20 64 65 73 69 72 65 64 2c 20 74 68 69   is desired, thi
e500: 73 20 6d 65 74 68 6f 64 0d 0a 20 20 20 20 20 20  s method..      
e510: 20 20 2f 2f 2f 20 72 65 74 75 72 6e 73 20 30 2e    /// returns 0.
e520: 20 54 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   To overload the
e530: 20 66 75 6e 63 74 69 6f 6e 2c 20 74 68 69 73 20   function, this 
e540: 6d 65 74 68 6f 64 20 77 72 69 74 65 73 20 74 68  method writes th
e550: 65 20 6e 65 77 20 0d 0a 20 20 20 20 20 20 20 20  e new ..        
e560: 2f 2f 2f 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  /// function imp
e570: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f  lementation into
e580: 20 2a 70 78 46 75 6e 63 20 61 6e 64 20 77 72 69   *pxFunc and wri
e590: 74 65 73 20 75 73 65 72 20 64 61 74 61 20 69 6e  tes user data in
e5a0: 74 6f 20 2a 70 70 41 72 67 20 0d 0a 20 20 20 20  to *ppArg ..    
e5b0: 20 20 20 20 2f 2f 2f 20 61 6e 64 20 72 65 74 75      /// and retu
e5c0: 72 6e 73 20 31 2e 0d 0a 20 20 20 20 20 20 20 20  rns 1...        
e5d0: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
e5e0: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
e5f0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 4e 6f 74  .        /// Not
e600: 65 20 74 68 61 74 20 69 6e 66 69 78 20 66 75 6e  e that infix fun
e610: 63 74 69 6f 6e 73 20 28 4c 49 4b 45 2c 20 47 4c  ctions (LIKE, GL
e620: 4f 42 2c 20 52 45 47 45 58 50 2c 20 61 6e 64 20  OB, REGEXP, and 
e630: 4d 41 54 43 48 29 20 72 65 76 65 72 73 65 20 0d  MATCH) reverse .
e640: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65  .        /// the
e650: 20 6f 72 64 65 72 20 6f 66 20 74 68 65 69 72 20   order of their 
e660: 61 72 67 75 6d 65 6e 74 73 2e 20 53 6f 20 22 6c  arguments. So "l
e670: 69 6b 65 28 41 2c 42 29 22 20 69 73 20 65 71 75  ike(A,B)" is equ
e680: 69 76 61 6c 65 6e 74 20 74 6f 20 22 42 20 6c 69  ivalent to "B li
e690: 6b 65 20 41 22 2e 20 0d 0a 20 20 20 20 20 20 20  ke A". ..       
e6a0: 20 2f 2f 2f 20 46 6f 72 20 74 68 65 20 66 6f 72   /// For the for
e6b0: 6d 20 22 42 20 6c 69 6b 65 20 41 22 20 74 68 65  m "B like A" the
e6c0: 20 42 20 74 65 72 6d 20 69 73 20 63 6f 6e 73 69   B term is consi
e6d0: 64 65 72 65 64 20 74 68 65 20 66 69 72 73 74 20  dered the first 
e6e0: 61 72 67 75 6d 65 6e 74 20 0d 0a 20 20 20 20 20  argument ..     
e6f0: 20 20 20 2f 2f 2f 20 74 6f 20 74 68 65 20 66 75     /// to the fu
e700: 6e 63 74 69 6f 6e 2e 20 42 75 74 20 66 6f 72 20  nction. But for 
e710: 22 6c 69 6b 65 28 41 2c 42 29 22 20 74 68 65 20  "like(A,B)" the 
e720: 41 20 74 65 72 6d 20 69 73 20 63 6f 6e 73 69 64  A term is consid
e730: 65 72 65 64 20 74 68 65 20 0d 0a 20 20 20 20 20  ered the ..     
e740: 20 20 20 2f 2f 2f 20 66 69 72 73 74 20 61 72 67     /// first arg
e750: 75 6d 65 6e 74 2e 0d 0a 20 20 20 20 20 20 20 20  ument...        
e760: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
e770: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
e780: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65  .        /// The
e790: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
e7a0: 72 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  r returned by th
e7b0: 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
e7c0: 62 65 20 76 61 6c 69 64 20 66 6f 72 0d 0a 20 20  be valid for..  
e7d0: 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 20 6c 69        /// the li
e7e0: 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20 73 71  fetime of the sq
e7f0: 6c 69 74 65 33 5f 76 74 61 62 20 6f 62 6a 65 63  lite3_vtab objec
e800: 74 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 66  t given in the f
e810: 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0d  irst parameter..
e820: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
e830: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
e840: 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a 20 20  / </summary>..  
e850: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d        /// <param
e860: 20 6e 61 6d 65 3d 22 70 56 74 61 62 22 3e 0d 0a   name="pVtab">..
e870: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20          /// The 
e880: 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72 20 74  native pointer t
e890: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 74  o the sqlite3_vt
e8a0: 61 62 20 64 65 72 69 76 65 64 20 73 74 72 75 63  ab derived struc
e8b0: 74 75 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f  ture...        /
e8c0: 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20  // </param>..   
e8d0: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20       /// <param 
e8e0: 6e 61 6d 65 3d 22 6e 41 72 67 22 3e 0d 0a 20 20  name="nArg">..  
e8f0: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e 75        /// The nu
e900: 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
e910: 73 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f  s to the functio
e920: 6e 20 62 65 69 6e 67 20 73 6f 75 67 68 74 2e 0d  n being sought..
e930: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
e940: 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f  aram>..        /
e950: 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22  // <param name="
e960: 7a 4e 61 6d 65 22 3e 0d 0a 20 20 20 20 20 20 20  zName">..       
e970: 20 2f 2f 2f 20 54 68 65 20 6e 61 6d 65 20 6f 66   /// The name of
e980: 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65   the function be
e990: 69 6e 67 20 73 6f 75 67 68 74 2e 0d 0a 20 20 20  ing sought...   
e9a0: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d       /// </param
e9b0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
e9c0: 70 61 72 61 6d 20 6e 61 6d 65 3d 22 63 61 6c 6c  param name="call
e9d0: 62 61 63 6b 22 3e 0d 0a 20 20 20 20 20 20 20 20  back">..        
e9e0: 2f 2f 2f 20 55 70 6f 6e 20 73 75 63 63 65 73 73  /// Upon success
e9f0: 2c 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  , this parameter
ea00: 20 6d 75 73 74 20 62 65 20 6d 6f 64 69 66 69 65   must be modifie
ea10: 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 74 68 65  d to contain the
ea20: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 64 65  ..        /// de
ea30: 6c 65 67 61 74 65 20 72 65 73 70 6f 6e 73 69 62  legate responsib
ea40: 6c 65 20 66 6f 72 20 69 6d 70 6c 65 6d 65 6e 74  le for implement
ea50: 69 6e 67 20 74 68 65 20 73 70 65 63 69 66 69 65  ing the specifie
ea60: 64 20 66 75 6e 63 74 69 6f 6e 2e 0d 0a 20 20 20  d function...   
ea70: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d       /// </param
ea80: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
ea90: 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 43 6c 69  param name="pCli
eaa0: 65 6e 74 44 61 74 61 22 3e 0d 0a 20 20 20 20 20  entData">..     
eab0: 20 20 20 2f 2f 2f 20 55 70 6f 6e 20 73 75 63 63     /// Upon succ
eac0: 65 73 73 2c 20 74 68 69 73 20 70 61 72 61 6d 65  ess, this parame
ead0: 74 65 72 20 6d 75 73 74 20 62 65 20 6d 6f 64 69  ter must be modi
eae0: 66 69 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  fied to contain 
eaf0: 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  the..        ///
eb00: 20 6e 61 74 69 76 65 20 75 73 65 72 2d 64 61 74   native user-dat
eb10: 61 20 70 6f 69 6e 74 65 72 20 61 73 73 6f 63 69  a pointer associ
eb20: 61 74 65 64 20 77 69 74 68 0d 0a 20 20 20 20 20  ated with..     
eb30: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 72 65 66     /// <paramref
eb40: 20 6e 61 6d 65 3d 22 63 61 6c 6c 62 61 63 6b 22   name="callback"
eb50: 20 2f 3e 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f   />...        //
eb60: 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20  / </param>..    
eb70: 20 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72 6e 73      /// <returns
eb80: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 4e  >..        /// N
eb90: 6f 6e 2d 7a 65 72 6f 20 69 66 20 74 68 65 20 73  on-zero if the s
eba0: 70 65 63 69 66 69 65 64 20 66 75 6e 63 74 69 6f  pecified functio
ebb0: 6e 20 77 61 73 20 66 6f 75 6e 64 3b 20 7a 65 72  n was found; zer
ebc0: 6f 20 6f 74 68 65 72 77 69 73 65 2e 0d 0a 20 20  o otherwise...  
ebd0: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72 65 74 75        /// </retu
ebe0: 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 69 6e  rns>..        in
ebf0: 74 20 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 28  t xFindFunction(
ec00: 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 49 6e  ..            In
ec10: 74 50 74 72 20 70 56 74 61 62 2c 0d 0a 20 20 20  tPtr pVtab,..   
ec20: 20 20 20 20 20 20 20 20 20 69 6e 74 20 6e 41 72           int nAr
ec30: 67 2c 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20  g,..            
ec40: 49 6e 74 50 74 72 20 7a 4e 61 6d 65 2c 0d 0a 20  IntPtr zName,.. 
ec50: 20 20 20 20 20 20 20 20 20 20 20 72 65 66 20 53             ref S
ec60: 51 4c 69 74 65 43 61 6c 6c 62 61 63 6b 20 63 61  QLiteCallback ca
ec70: 6c 6c 62 61 63 6b 2c 0d 0a 20 20 20 20 20 20 20  llback,..       
ec80: 20 20 20 20 20 72 65 66 20 49 6e 74 50 74 72 20       ref IntPtr 
ec90: 70 43 6c 69 65 6e 74 44 61 74 61 0d 0a 20 20 20  pClientData..   
eca0: 20 20 20 20 20 20 20 20 20 29 3b 0d 0a 0d 0a 20           );.... 
ecb0: 20 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f         /////////
ecc0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
ecd0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
ece0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
ecf0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a  //////////////..
ed00: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 73  ..        /// <s
ed10: 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20  ummary>..       
ed20: 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65   /// <para><code
ed30: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20  >..        ///  
ed40: 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28   int (*xRename)(
ed50: 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
ed60: 74 61 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  tab, const char 
ed70: 2a 7a 4e 65 77 29 3b 0d 0a 20 20 20 20 20 20 20  *zNew);..       
ed80: 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61   /// </code></pa
ed90: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
eda0: 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20   <para>..       
edb0: 20 2f 2f 2f 20 54 68 69 73 20 6d 65 74 68 6f 64   /// This method
edc0: 20 70 72 6f 76 69 64 65 73 20 6e 6f 74 69 66 69   provides notifi
edd0: 63 61 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20  cation that the 
ede0: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d  virtual table im
edf0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0d 0a 20 20  plementation..  
ee00: 20 20 20 20 20 20 2f 2f 2f 20 74 68 61 74 20 74        /// that t
ee10: 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
ee20: 20 77 69 6c 6c 20 62 65 20 67 69 76 65 6e 20 61   will be given a
ee30: 20 6e 65 77 20 6e 61 6d 65 2e 20 0d 0a 20 20 20   new name. ..   
ee40: 20 20 20 20 20 2f 2f 2f 20 49 66 20 74 68 69 73       /// If this
ee50: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
ee60: 53 51 4c 49 54 45 5f 4f 4b 20 74 68 65 6e 20 53  SQLITE_OK then S
ee70: 51 4c 69 74 65 20 72 65 6e 61 6d 65 73 20 74 68  QLite renames th
ee80: 65 20 74 61 62 6c 65 2e 0d 0a 20 20 20 20 20 20  e table...      
ee90: 20 20 2f 2f 2f 20 49 66 20 74 68 69 73 20 6d 65    /// If this me
eea0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 6e 20  thod returns an 
eeb0: 65 72 72 6f 72 20 63 6f 64 65 20 74 68 65 6e 20  error code then 
eec0: 74 68 65 20 72 65 6e 61 6d 69 6e 67 20 69 73 20  the renaming is 
eed0: 70 72 65 76 65 6e 74 65 64 2e 0d 0a 20 20 20 20  prevented...    
eee0: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
eef0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
ef00: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
ef10: 20 54 68 65 20 78 52 65 6e 61 6d 65 20 6d 65 74   The xRename met
ef20: 68 6f 64 20 69 73 20 72 65 71 75 69 72 65 64 20  hod is required 
ef30: 66 6f 72 20 65 76 65 72 79 20 76 69 72 74 75 61  for every virtua
ef40: 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  l table implemen
ef50: 74 61 74 69 6f 6e 2e 0d 0a 20 20 20 20 20 20 20  tation...       
ef60: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
ef70: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d        /// </summ
ef80: 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ary>..        //
ef90: 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70  / <param name="p
efa0: 56 74 61 62 22 3e 0d 0a 20 20 20 20 20 20 20 20  Vtab">..        
efb0: 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76 65 20 70  /// The native p
efc0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 71  ointer to the sq
efd0: 6c 69 74 65 33 5f 76 74 61 62 20 64 65 72 69 76  lite3_vtab deriv
efe0: 65 64 20 73 74 72 75 63 74 75 72 65 2e 0d 0a 20  ed structure... 
eff0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
f000: 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  am>..        ///
f010: 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 7a 4e   <param name="zN
f020: 65 77 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ew">..        //
f030: 2f 20 54 68 65 20 6e 61 74 69 76 65 20 70 6f 69  / The native poi
f040: 6e 74 65 72 20 74 6f 20 74 68 65 20 55 54 46 2d  nter to the UTF-
f050: 38 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67  8 encoded string
f060: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
f070: 6e 65 77 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  new..        ///
f080: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 76 69   name for the vi
f090: 72 74 75 61 6c 20 74 61 62 6c 65 2e 0d 0a 20 20  rtual table...  
f0a0: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61        /// </para
f0b0: 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  m>..        /// 
f0c0: 3c 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20  <returns>..     
f0d0: 20 20 20 2f 2f 2f 20 41 20 73 74 61 6e 64 61 72     /// A standar
f0e0: 64 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 20  d SQLite return 
f0f0: 63 6f 64 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f  code...        /
f100: 2f 2f 20 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a 20  // </returns>.. 
f110: 20 20 20 20 20 20 20 53 51 4c 69 74 65 45 72 72         SQLiteErr
f120: 6f 72 43 6f 64 65 20 78 52 65 6e 61 6d 65 28 0d  orCode xRename(.
f130: 0a 20 20 20 20 20 20 20 20 20 20 20 20 49 6e 74  .            Int
f140: 50 74 72 20 70 56 74 61 62 2c 0d 0a 20 20 20 20  Ptr pVtab,..    
f150: 20 20 20 20 20 20 20 20 49 6e 74 50 74 72 20 7a          IntPtr z
f160: 4e 65 77 0d 0a 20 20 20 20 20 20 20 20 20 20 20  New..           
f170: 20 29 3b 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f   );....        /
f180: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
f190: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
f1a0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
f1b0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
f1c0: 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 20 20  //////....      
f1d0: 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d    /// <summary>.
f1e0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
f1f0: 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20  ra><code>..     
f200: 20 20 20 2f 2f 2f 20 20 20 69 6e 74 20 28 2a 78     ///   int (*x
f210: 53 61 76 65 70 6f 69 6e 74 29 28 73 71 6c 69 74  Savepoint)(sqlit
f220: 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20  e3_vtab *pVtab, 
f230: 69 6e 74 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f  int);..        /
f240: 2f 2f 20 20 20 69 6e 74 20 28 2a 78 52 65 6c 65  //   int (*xRele
f250: 61 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ase)(sqlite3_vta
f260: 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 29 3b 0d  b *pVtab, int);.
f270: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 69  .        ///   i
f280: 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 54 6f  nt (*xRollbackTo
f290: 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
f2a0: 70 56 74 61 62 2c 20 69 6e 74 29 3b 0d 0a 20 20  pVtab, int);..  
f2b0: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65        /// </code
f2c0: 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  ></para>..      
f2d0: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
f2e0: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 73 65 20        /// These 
f2f0: 6d 65 74 68 6f 64 73 20 70 72 6f 76 69 64 65 20  methods provide 
f300: 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
f310: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
f320: 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 20   an opportunity 
f330: 74 6f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  to..        /// 
f340: 69 6d 70 6c 65 6d 65 6e 74 20 6e 65 73 74 65 64  implement nested
f350: 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 2e 20 20   transactions.  
f360: 54 68 65 79 20 61 72 65 20 61 6c 77 61 79 73 20  They are always 
f370: 6f 70 74 69 6f 6e 61 6c 20 61 6e 64 20 77 69 6c  optional and wil
f380: 6c 20 6f 6e 6c 79 20 62 65 0d 0a 20 20 20 20 20  l only be..     
f390: 20 20 20 2f 2f 2f 20 63 61 6c 6c 65 64 20 69 6e     /// called in
f3a0: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
f3b0: 33 2e 37 2e 37 20 61 6e 64 20 6c 61 74 65 72 2e  3.7.7 and later.
f3c0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
f3d0: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
f3e0: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20  // <para>..     
f3f0: 20 20 20 2f 2f 2f 20 57 68 65 6e 20 78 53 61 76     /// When xSav
f400: 65 70 6f 69 6e 74 28 58 2c 4e 29 20 69 73 20 69  epoint(X,N) is i
f410: 6e 76 6f 6b 65 64 2c 20 74 68 61 74 20 69 73 20  nvoked, that is 
f420: 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65 20  a signal to the 
f430: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 58 0d  virtual table X.
f440: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 61  .        /// tha
f450: 74 20 69 74 20 73 68 6f 75 6c 64 20 73 61 76 65  t it should save
f460: 20 69 74 73 20 63 75 72 72 65 6e 74 20 73 74 61   its current sta
f470: 74 65 20 61 73 20 73 61 76 65 70 6f 69 6e 74 20  te as savepoint 
f480: 4e 2e 20 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  N.  ..        //
f490: 2f 20 41 20 73 75 62 73 65 71 75 65 6e 74 20 63  / A subsequent c
f4a0: 61 6c 6c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  all..        ///
f4b0: 20 74 6f 20 78 52 6f 6c 6c 62 61 63 6b 54 6f 28   to xRollbackTo(
f4c0: 58 2c 52 29 20 6d 65 61 6e 73 20 74 68 61 74 20  X,R) means that 
f4d0: 74 68 65 20 73 74 61 74 65 20 6f 66 20 74 68 65  the state of the
f4e0: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 73   virtual table s
f4f0: 68 6f 75 6c 64 20 72 65 74 75 72 6e 0d 0a 20 20  hould return..  
f500: 20 20 20 20 20 20 2f 2f 2f 20 74 6f 20 77 68 61        /// to wha
f510: 74 20 69 74 20 77 61 73 20 77 68 65 6e 20 78 53  t it was when xS
f520: 61 76 65 70 6f 69 6e 74 28 58 2c 52 29 20 77 61  avepoint(X,R) wa
f530: 73 20 6c 61 73 74 20 63 61 6c 6c 65 64 2e 20 20  s last called.  
f540: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
f550: 65 20 63 61 6c 6c 0d 0a 20 20 20 20 20 20 20 20  e call..        
f560: 2f 2f 2f 20 74 6f 20 78 52 6f 6c 6c 62 61 63 6b  /// to xRollback
f570: 54 6f 28 58 2c 52 29 20 77 69 6c 6c 20 69 6e 76  To(X,R) will inv
f580: 61 6c 69 64 61 74 65 20 61 6c 6c 20 73 61 76 65  alidate all save
f590: 70 6f 69 6e 74 73 20 77 69 74 68 20 4e 3e 52 3b  points with N>R;
f5a0: 20 6e 6f 6e 65 20 6f 66 20 74 68 65 0d 0a 20 20   none of the..  
f5b0: 20 20 20 20 20 20 2f 2f 2f 20 69 6e 76 61 6c 69        /// invali
f5c0: 64 65 64 20 73 61 76 65 70 6f 69 6e 74 73 20 77  ded savepoints w
f5d0: 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ill be rolled ba
f5e0: 63 6b 20 6f 72 20 72 65 6c 65 61 73 65 64 20 77  ck or released w
f5f0: 69 74 68 6f 75 74 20 66 69 72 73 74 0d 0a 20 20  ithout first..  
f600: 20 20 20 20 20 20 2f 2f 2f 20 62 65 69 6e 67 20        /// being 
f610: 72 65 69 6e 69 74 69 61 6c 69 7a 65 64 20 62 79  reinitialized by
f620: 20 61 20 63 61 6c 6c 20 74 6f 20 78 53 61 76 65   a call to xSave
f630: 70 6f 69 6e 74 28 29 2e 20 20 0d 0a 20 20 20 20  point().  ..    
f640: 20 20 20 20 2f 2f 2f 20 41 20 63 61 6c 6c 20 74      /// A call t
f650: 6f 20 78 52 65 6c 65 61 73 65 28 58 2c 4d 29 20  o xRelease(X,M) 
f660: 69 6e 76 61 6c 69 64 61 74 65 73 20 61 6c 6c 20  invalidates all 
f670: 73 61 76 65 70 6f 69 6e 74 73 20 77 68 65 72 65  savepoints where
f680: 20 4e 3e 3d 4d 2e 0d 0a 20 20 20 20 20 20 20 20   N>=M...        
f690: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
f6a0: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
f6b0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 4e 6f 6e  .        /// Non
f6c0: 65 20 6f 66 20 74 68 65 20 78 53 61 76 65 70 6f  e of the xSavepo
f6d0: 69 6e 74 28 29 2c 20 78 52 65 6c 65 61 73 65 28  int(), xRelease(
f6e0: 29 2c 20 6f 72 20 78 52 6f 6c 6c 62 61 63 6b 54  ), or xRollbackT
f6f0: 6f 28 29 20 6d 65 74 68 6f 64 73 20 77 69 6c 6c  o() methods will
f700: 20 65 76 65 72 0d 0a 20 20 20 20 20 20 20 20 2f   ever..        /
f710: 2f 2f 20 62 65 20 63 61 6c 6c 65 64 20 65 78 63  // be called exc
f720: 65 70 74 20 69 6e 20 62 65 74 77 65 65 6e 20 63  ept in between c
f730: 61 6c 6c 73 20 74 6f 20 78 42 65 67 69 6e 28 29  alls to xBegin()
f740: 20 61 6e 64 20 0d 0a 20 20 20 20 20 20 20 20 2f   and ..        /
f750: 2f 2f 20 65 69 74 68 65 72 20 78 43 6f 6d 6d 69  // either xCommi
f760: 74 28 29 20 6f 72 20 78 52 6f 6c 6c 62 61 63 6b  t() or xRollback
f770: 28 29 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ()...        ///
f780: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
f790: 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e    /// </summary>
f7a0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
f7b0: 61 72 61 6d 20 6e 61 6d 65 3d 22 70 56 74 61 62  aram name="pVtab
f7c0: 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ">..        /// 
f7d0: 54 68 65 20 6e 61 74 69 76 65 20 70 6f 69 6e 74  The native point
f7e0: 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
f7f0: 33 5f 76 74 61 62 20 64 65 72 69 76 65 64 20 73  3_vtab derived s
f800: 74 72 75 63 74 75 72 65 2e 0d 0a 20 20 20 20 20  tructure...     
f810: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d     /// </param>.
f820: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
f830: 72 61 6d 20 6e 61 6d 65 3d 22 69 53 61 76 65 70  ram name="iSavep
f840: 6f 69 6e 74 22 3e 0d 0a 20 20 20 20 20 20 20 20  oint">..        
f850: 2f 2f 2f 20 54 68 69 73 20 69 73 20 61 6e 20 69  /// This is an i
f860: 6e 74 65 67 65 72 20 69 64 65 6e 74 69 66 69 65  nteger identifie
f870: 72 20 75 6e 64 65 72 20 77 68 69 63 68 20 74 68  r under which th
f880: 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  e the current st
f890: 61 74 65 20 6f 66 0d 0a 20 20 20 20 20 20 20 20  ate of..        
f8a0: 2f 2f 2f 20 74 68 65 20 76 69 72 74 75 61 6c 20  /// the virtual 
f8b0: 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  table should be 
f8c0: 73 61 76 65 64 2e 0d 0a 20 20 20 20 20 20 20 20  saved...        
f8d0: 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20  /// </param>..  
f8e0: 20 20 20 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72        /// <retur
f8f0: 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ns>..        ///
f900: 20 41 20 73 74 61 6e 64 61 72 64 20 53 51 4c 69   A standard SQLi
f910: 74 65 20 72 65 74 75 72 6e 20 63 6f 64 65 2e 0d  te return code..
f920: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72  .        /// </r
f930: 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20  eturns>..       
f940: 20 53 51 4c 69 74 65 45 72 72 6f 72 43 6f 64 65   SQLiteErrorCode
f950: 20 78 53 61 76 65 70 6f 69 6e 74 28 0d 0a 20 20   xSavepoint(..  
f960: 20 20 20 20 20 20 20 20 20 20 49 6e 74 50 74 72            IntPtr
f970: 20 70 56 74 61 62 2c 0d 0a 20 20 20 20 20 20 20   pVtab,..       
f980: 20 20 20 20 20 69 6e 74 20 69 53 61 76 65 70 6f       int iSavepo
f990: 69 6e 74 0d 0a 20 20 20 20 20 20 20 20 20 20 20  int..           
f9a0: 20 29 3b 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f   );....        /
f9b0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
f9c0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
f9d0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
f9e0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
f9f0: 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 20 20  //////....      
fa00: 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d    /// <summary>.
fa10: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
fa20: 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20  ra><code>..     
fa30: 20 20 20 2f 2f 2f 20 20 20 69 6e 74 20 28 2a 78     ///   int (*x
fa40: 53 61 76 65 70 6f 69 6e 74 29 28 73 71 6c 69 74  Savepoint)(sqlit
fa50: 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20  e3_vtab *pVtab, 
fa60: 69 6e 74 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f  int);..        /
fa70: 2f 2f 20 20 20 69 6e 74 20 28 2a 78 52 65 6c 65  //   int (*xRele
fa80: 61 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ase)(sqlite3_vta
fa90: 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 29 3b 0d  b *pVtab, int);.
faa0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 69  .        ///   i
fab0: 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 54 6f  nt (*xRollbackTo
fac0: 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
fad0: 70 56 74 61 62 2c 20 69 6e 74 29 3b 0d 0a 20 20  pVtab, int);..  
fae0: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65        /// </code
faf0: 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  ></para>..      
fb00: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
fb10: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 73 65 20        /// These 
fb20: 6d 65 74 68 6f 64 73 20 70 72 6f 76 69 64 65 20  methods provide 
fb30: 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
fb40: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
fb50: 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 20   an opportunity 
fb60: 74 6f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  to..        /// 
fb70: 69 6d 70 6c 65 6d 65 6e 74 20 6e 65 73 74 65 64  implement nested
fb80: 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 2e 20 20   transactions.  
fb90: 54 68 65 79 20 61 72 65 20 61 6c 77 61 79 73 20  They are always 
fba0: 6f 70 74 69 6f 6e 61 6c 20 61 6e 64 20 77 69 6c  optional and wil
fbb0: 6c 20 6f 6e 6c 79 20 62 65 0d 0a 20 20 20 20 20  l only be..     
fbc0: 20 20 20 2f 2f 2f 20 63 61 6c 6c 65 64 20 69 6e     /// called in
fbd0: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
fbe0: 33 2e 37 2e 37 20 61 6e 64 20 6c 61 74 65 72 2e  3.7.7 and later.
fbf0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
fc00: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
fc10: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20  // <para>..     
fc20: 20 20 20 2f 2f 2f 20 57 68 65 6e 20 78 53 61 76     /// When xSav
fc30: 65 70 6f 69 6e 74 28 58 2c 4e 29 20 69 73 20 69  epoint(X,N) is i
fc40: 6e 76 6f 6b 65 64 2c 20 74 68 61 74 20 69 73 20  nvoked, that is 
fc50: 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65 20  a signal to the 
fc60: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 58 0d  virtual table X.
fc70: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 61  .        /// tha
fc80: 74 20 69 74 20 73 68 6f 75 6c 64 20 73 61 76 65  t it should save
fc90: 20 69 74 73 20 63 75 72 72 65 6e 74 20 73 74 61   its current sta
fca0: 74 65 20 61 73 20 73 61 76 65 70 6f 69 6e 74 20  te as savepoint 
fcb0: 4e 2e 20 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  N.  ..        //
fcc0: 2f 20 41 20 73 75 62 73 65 71 75 65 6e 74 20 63  / A subsequent c
fcd0: 61 6c 6c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  all..        ///
fce0: 20 74 6f 20 78 52 6f 6c 6c 62 61 63 6b 54 6f 28   to xRollbackTo(
fcf0: 58 2c 52 29 20 6d 65 61 6e 73 20 74 68 61 74 20  X,R) means that 
fd00: 74 68 65 20 73 74 61 74 65 20 6f 66 20 74 68 65  the state of the
fd10: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 73   virtual table s
fd20: 68 6f 75 6c 64 20 72 65 74 75 72 6e 0d 0a 20 20  hould return..  
fd30: 20 20 20 20 20 20 2f 2f 2f 20 74 6f 20 77 68 61        /// to wha
fd40: 74 20 69 74 20 77 61 73 20 77 68 65 6e 20 78 53  t it was when xS
fd50: 61 76 65 70 6f 69 6e 74 28 58 2c 52 29 20 77 61  avepoint(X,R) wa
fd60: 73 20 6c 61 73 74 20 63 61 6c 6c 65 64 2e 20 20  s last called.  
fd70: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
fd80: 65 20 63 61 6c 6c 0d 0a 20 20 20 20 20 20 20 20  e call..        
fd90: 2f 2f 2f 20 74 6f 20 78 52 6f 6c 6c 62 61 63 6b  /// to xRollback
fda0: 54 6f 28 58 2c 52 29 20 77 69 6c 6c 20 69 6e 76  To(X,R) will inv
fdb0: 61 6c 69 64 61 74 65 20 61 6c 6c 20 73 61 76 65  alidate all save
fdc0: 70 6f 69 6e 74 73 20 77 69 74 68 20 4e 3e 52 3b  points with N>R;
fdd0: 20 6e 6f 6e 65 20 6f 66 20 74 68 65 0d 0a 20 20   none of the..  
fde0: 20 20 20 20 20 20 2f 2f 2f 20 69 6e 76 61 6c 69        /// invali
fdf0: 64 65 64 20 73 61 76 65 70 6f 69 6e 74 73 20 77  ded savepoints w
fe00: 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ill be rolled ba
fe10: 63 6b 20 6f 72 20 72 65 6c 65 61 73 65 64 20 77  ck or released w
fe20: 69 74 68 6f 75 74 20 66 69 72 73 74 0d 0a 20 20  ithout first..  
fe30: 20 20 20 20 20 20 2f 2f 2f 20 62 65 69 6e 67 20        /// being 
fe40: 72 65 69 6e 69 74 69 61 6c 69 7a 65 64 20 62 79  reinitialized by
fe50: 20 61 20 63 61 6c 6c 20 74 6f 20 78 53 61 76 65   a call to xSave
fe60: 70 6f 69 6e 74 28 29 2e 20 20 0d 0a 20 20 20 20  point().  ..    
fe70: 20 20 20 20 2f 2f 2f 20 41 20 63 61 6c 6c 20 74      /// A call t
fe80: 6f 20 78 52 65 6c 65 61 73 65 28 58 2c 4d 29 20  o xRelease(X,M) 
fe90: 69 6e 76 61 6c 69 64 61 74 65 73 20 61 6c 6c 20  invalidates all 
fea0: 73 61 76 65 70 6f 69 6e 74 73 20 77 68 65 72 65  savepoints where
feb0: 20 4e 3e 3d 4d 2e 0d 0a 20 20 20 20 20 20 20 20   N>=M...        
fec0: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
fed0: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
fee0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 4e 6f 6e  .        /// Non
fef0: 65 20 6f 66 20 74 68 65 20 78 53 61 76 65 70 6f  e of the xSavepo
ff00: 69 6e 74 28 29 2c 20 78 52 65 6c 65 61 73 65 28  int(), xRelease(
ff10: 29 2c 20 6f 72 20 78 52 6f 6c 6c 62 61 63 6b 54  ), or xRollbackT
ff20: 6f 28 29 20 6d 65 74 68 6f 64 73 20 77 69 6c 6c  o() methods will
ff30: 20 65 76 65 72 0d 0a 20 20 20 20 20 20 20 20 2f   ever..        /
ff40: 2f 2f 20 62 65 20 63 61 6c 6c 65 64 20 65 78 63  // be called exc
ff50: 65 70 74 20 69 6e 20 62 65 74 77 65 65 6e 20 63  ept in between c
ff60: 61 6c 6c 73 20 74 6f 20 78 42 65 67 69 6e 28 29  alls to xBegin()
ff70: 20 61 6e 64 20 0d 0a 20 20 20 20 20 20 20 20 2f   and ..        /
ff80: 2f 2f 20 65 69 74 68 65 72 20 78 43 6f 6d 6d 69  // either xCommi
ff90: 74 28 29 20 6f 72 20 78 52 6f 6c 6c 62 61 63 6b  t() or xRollback
ffa0: 28 29 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ()...        ///
ffb0: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
ffc0: 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e    /// </summary>
ffd0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
ffe0: 61 72 61 6d 20 6e 61 6d 65 3d 22 70 56 74 61 62  aram name="pVtab
fff0: 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ">..        /// 
10000 54 68 65 20 6e 61 74 69 76 65 20 70 6f 69 6e 74  The native point
10010 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
10020 33 5f 76 74 61 62 20 64 65 72 69 76 65 64 20 73  3_vtab derived s
10030 74 72 75 63 74 75 72 65 2e 0d 0a 20 20 20 20 20  tructure...     
10040 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d     /// </param>.
10050 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
10060 72 61 6d 20 6e 61 6d 65 3d 22 69 53 61 76 65 70  ram name="iSavep
10070 6f 69 6e 74 22 3e 0d 0a 20 20 20 20 20 20 20 20  oint">..        
10080 2f 2f 2f 20 54 68 69 73 20 69 73 20 61 6e 20 69  /// This is an i
10090 6e 74 65 67 65 72 20 75 73 65 64 20 74 6f 20 69  nteger used to i
100a0 6e 64 69 63 61 74 65 20 74 68 61 74 20 61 6e 79  ndicate that any
100b0 20 73 61 76 65 64 20 73 74 61 74 65 73 20 77 69   saved states wi
100c0 74 68 20 61 6e 0d 0a 20 20 20 20 20 20 20 20 2f  th an..        /
100d0 2f 2f 20 69 64 65 6e 74 69 66 69 65 72 20 67 72  // identifier gr
100e0 65 61 74 65 72 20 74 68 61 6e 20 6f 72 20 65 71  eater than or eq
100f0 75 61 6c 20 74 6f 20 74 68 69 73 20 73 68 6f 75  ual to this shou
10100 6c 64 20 62 65 20 64 65 6c 65 74 65 64 20 62 79  ld be deleted by
10110 20 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f   the..        //
10120 2f 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e  / virtual table.
10130 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
10140 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20  param>..        
10150 2f 2f 2f 20 3c 72 65 74 75 72 6e 73 3e 0d 0a 20  /// <returns>.. 
10160 20 20 20 20 20 20 20 2f 2f 2f 20 41 20 73 74 61         /// A sta
10170 6e 64 61 72 64 20 53 51 4c 69 74 65 20 72 65 74  ndard SQLite ret
10180 75 72 6e 20 63 6f 64 65 2e 0d 0a 20 20 20 20 20  urn code...     
10190 20 20 20 2f 2f 2f 20 3c 2f 72 65 74 75 72 6e 73     /// </returns
101a0 3e 0d 0a 20 20 20 20 20 20 20 20 53 51 4c 69 74  >..        SQLit
101b0 65 45 72 72 6f 72 43 6f 64 65 20 78 52 65 6c 65  eErrorCode xRele
101c0 61 73 65 28 0d 0a 20 20 20 20 20 20 20 20 20 20  ase(..          
101d0 20 20 49 6e 74 50 74 72 20 70 56 74 61 62 2c 0d    IntPtr pVtab,.
101e0 0a 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74  .            int
101f0 20 69 53 61 76 65 70 6f 69 6e 74 0d 0a 20 20 20   iSavepoint..   
10200 20 20 20 20 20 20 20 20 20 29 3b 0d 0a 0d 0a 20           );.... 
10210 20 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f         /////////
10220 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
10230 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
10240 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
10250 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a  //////////////..
10260 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 73  ..        /// <s
10270 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20  ummary>..       
10280 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65   /// <para><code
10290 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20  >..        ///  
102a0 20 69 6e 74 20 28 2a 78 53 61 76 65 70 6f 69 6e   int (*xSavepoin
102b0 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  t)(sqlite3_vtab 
102c0 2a 70 56 74 61 62 2c 20 69 6e 74 29 3b 0d 0a 20  *pVtab, int);.. 
102d0 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 69 6e 74         ///   int
102e0 20 28 2a 78 52 65 6c 65 61 73 65 29 28 73 71 6c   (*xRelease)(sql
102f0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62  ite3_vtab *pVtab
10300 2c 20 69 6e 74 29 3b 0d 0a 20 20 20 20 20 20 20  , int);..       
10310 20 2f 2f 2f 20 20 20 69 6e 74 20 28 2a 78 52 6f   ///   int (*xRo
10320 6c 6c 62 61 63 6b 54 6f 29 28 73 71 6c 69 74 65  llbackTo)(sqlite
10330 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69  3_vtab *pVtab, i
10340 6e 74 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f  nt);..        //
10350 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e  / </code></para>
10360 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
10370 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
10380 2f 20 54 68 65 73 65 20 6d 65 74 68 6f 64 73 20  / These methods 
10390 70 72 6f 76 69 64 65 20 74 68 65 20 76 69 72 74  provide the virt
103a0 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
103b0 65 6e 74 61 74 69 6f 6e 20 61 6e 20 6f 70 70 6f  entation an oppo
103c0 72 74 75 6e 69 74 79 20 74 6f 0d 0a 20 20 20 20  rtunity to..    
103d0 20 20 20 20 2f 2f 2f 20 69 6d 70 6c 65 6d 65 6e      /// implemen
103e0 74 20 6e 65 73 74 65 64 20 74 72 61 6e 73 61 63  t nested transac
103f0 74 69 6f 6e 73 2e 20 20 54 68 65 79 20 61 72 65  tions.  They are
10400 20 61 6c 77 61 79 73 20 6f 70 74 69 6f 6e 61 6c   always optional
10410 20 61 6e 64 20 77 69 6c 6c 20 6f 6e 6c 79 20 62   and will only b
10420 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 63  e..        /// c
10430 61 6c 6c 65 64 20 69 6e 20 53 51 4c 69 74 65 20  alled in SQLite 
10440 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 20 61 6e  version 3.7.7 an
10450 64 20 6c 61 74 65 72 2e 0d 0a 20 20 20 20 20 20  d later...      
10460 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
10470 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
10480 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 57  >..        /// W
10490 68 65 6e 20 78 53 61 76 65 70 6f 69 6e 74 28 58  hen xSavepoint(X
104a0 2c 4e 29 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ,N) is invoked, 
104b0 74 68 61 74 20 69 73 20 61 20 73 69 67 6e 61 6c  that is a signal
104c0 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 20   to the virtual 
104d0 74 61 62 6c 65 20 58 0d 0a 20 20 20 20 20 20 20  table X..       
104e0 20 2f 2f 2f 20 74 68 61 74 20 69 74 20 73 68 6f   /// that it sho
104f0 75 6c 64 20 73 61 76 65 20 69 74 73 20 63 75 72  uld save its cur
10500 72 65 6e 74 20 73 74 61 74 65 20 61 73 20 73 61  rent state as sa
10510 76 65 70 6f 69 6e 74 20 4e 2e 20 20 0d 0a 20 20  vepoint N.  ..  
10520 20 20 20 20 20 20 2f 2f 2f 20 41 20 73 75 62 73        /// A subs
10530 65 71 75 65 6e 74 20 63 61 6c 6c 0d 0a 20 20 20  equent call..   
10540 20 20 20 20 20 2f 2f 2f 20 74 6f 20 78 52 6f 6c       /// to xRol
10550 6c 62 61 63 6b 54 6f 28 58 2c 52 29 20 6d 65 61  lbackTo(X,R) mea
10560 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74  ns that the stat
10570 65 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c  e of the virtual
10580 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 72 65   table should re
10590 74 75 72 6e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  turn..        //
105a0 2f 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73  / to what it was
105b0 20 77 68 65 6e 20 78 53 61 76 65 70 6f 69 6e 74   when xSavepoint
105c0 28 58 2c 52 29 20 77 61 73 20 6c 61 73 74 20 63  (X,R) was last c
105d0 61 6c 6c 65 64 2e 20 20 0d 0a 20 20 20 20 20 20  alled.  ..      
105e0 20 20 2f 2f 2f 20 54 68 65 20 63 61 6c 6c 0d 0a    /// The call..
105f0 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 6f 20 78          /// to x
10600 52 6f 6c 6c 62 61 63 6b 54 6f 28 58 2c 52 29 20  RollbackTo(X,R) 
10610 77 69 6c 6c 20 69 6e 76 61 6c 69 64 61 74 65 20  will invalidate 
10620 61 6c 6c 20 73 61 76 65 70 6f 69 6e 74 73 20 77  all savepoints w
10630 69 74 68 20 4e 3e 52 3b 20 6e 6f 6e 65 20 6f 66  ith N>R; none of
10640 20 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f   the..        //
10650 2f 20 69 6e 76 61 6c 69 64 65 64 20 73 61 76 65  / invalided save
10660 70 6f 69 6e 74 73 20 77 69 6c 6c 20 62 65 20 72  points will be r
10670 6f 6c 6c 65 64 20 62 61 63 6b 20 6f 72 20 72 65  olled back or re
10680 6c 65 61 73 65 64 20 77 69 74 68 6f 75 74 20 66  leased without f
10690 69 72 73 74 0d 0a 20 20 20 20 20 20 20 20 2f 2f  irst..        //
106a0 2f 20 62 65 69 6e 67 20 72 65 69 6e 69 74 69 61  / being reinitia
106b0 6c 69 7a 65 64 20 62 79 20 61 20 63 61 6c 6c 20  lized by a call 
106c0 74 6f 20 78 53 61 76 65 70 6f 69 6e 74 28 29 2e  to xSavepoint().
106d0 20 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20    ..        /// 
106e0 41 20 63 61 6c 6c 20 74 6f 20 78 52 65 6c 65 61  A call to xRelea
106f0 73 65 28 58 2c 4d 29 20 69 6e 76 61 6c 69 64 61  se(X,M) invalida
10700 74 65 73 20 61 6c 6c 20 73 61 76 65 70 6f 69 6e  tes all savepoin
10710 74 73 20 77 68 65 72 65 20 4e 3e 3d 4d 2e 0d 0a  ts where N>=M...
10720 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
10730 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
10740 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20   <para>..       
10750 20 2f 2f 2f 20 4e 6f 6e 65 20 6f 66 20 74 68 65   /// None of the
10760 20 78 53 61 76 65 70 6f 69 6e 74 28 29 2c 20 78   xSavepoint(), x
10770 52 65 6c 65 61 73 65 28 29 2c 20 6f 72 20 78 52  Release(), or xR
10780 6f 6c 6c 62 61 63 6b 54 6f 28 29 20 6d 65 74 68  ollbackTo() meth
10790 6f 64 73 20 77 69 6c 6c 20 65 76 65 72 0d 0a 20  ods will ever.. 
107a0 20 20 20 20 20 20 20 2f 2f 2f 20 62 65 20 63 61         /// be ca
107b0 6c 6c 65 64 20 65 78 63 65 70 74 20 69 6e 20 62  lled except in b
107c0 65 74 77 65 65 6e 20 63 61 6c 6c 73 20 74 6f 20  etween calls to 
107d0 78 42 65 67 69 6e 28 29 20 61 6e 64 20 0d 0a 20  xBegin() and .. 
107e0 20 20 20 20 20 20 20 2f 2f 2f 20 65 69 74 68 65         /// eithe
107f0 72 20 78 43 6f 6d 6d 69 74 28 29 20 6f 72 20 78  r xCommit() or x
10800 52 6f 6c 6c 62 61 63 6b 28 29 2e 0d 0a 20 20 20  Rollback()...   
10810 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e       /// </para>
10820 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
10830 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20  summary>..      
10840 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d    /// <param nam
10850 65 3d 22 70 56 74 61 62 22 3e 0d 0a 20 20 20 20  e="pVtab">..    
10860 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e 61 74 69      /// The nati
10870 76 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  ve pointer to th
10880 65 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 64  e sqlite3_vtab d
10890 65 72 69 76 65 64 20 73 74 72 75 63 74 75 72 65  erived structure
108a0 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
108b0 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20  /param>..       
108c0 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65   /// <param name
108d0 3d 22 69 53 61 76 65 70 6f 69 6e 74 22 3e 0d 0a  ="iSavepoint">..
108e0 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 69 73          /// This
108f0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 69   is an integer i
10900 64 65 6e 74 69 66 69 65 72 20 75 73 65 64 20 74  dentifier used t
10910 6f 20 73 70 65 63 69 66 79 20 61 20 73 70 65 63  o specify a spec
10920 69 66 69 63 20 73 61 76 65 64 0d 0a 20 20 20 20  ific saved..    
10930 20 20 20 20 2f 2f 2f 20 73 74 61 74 65 20 66 6f      /// state fo
10940 72 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  r the virtual ta
10950 62 6c 65 20 66 6f 72 20 69 74 20 74 6f 20 72 65  ble for it to re
10960 73 74 6f 72 65 20 69 74 73 65 6c 66 20 62 61 63  store itself bac
10970 6b 20 74 6f 2c 20 77 68 69 63 68 0d 0a 20 20 20  k to, which..   
10980 20 20 20 20 20 2f 2f 2f 20 73 68 6f 75 6c 64 20       /// should 
10990 61 6c 73 6f 20 68 61 76 65 20 74 68 65 20 65 66  also have the ef
109a0 66 65 63 74 20 6f 66 20 64 65 6c 65 74 69 6e 67  fect of deleting
109b0 20 61 6c 6c 20 73 61 76 65 64 20 73 74 61 74 65   all saved state
109c0 73 20 77 69 74 68 20 61 6e 0d 0a 20 20 20 20 20  s with an..     
109d0 20 20 20 2f 2f 2f 20 69 6e 74 65 67 65 72 20 69     /// integer i
109e0 64 65 6e 74 69 66 69 65 72 20 67 72 65 61 74 65  dentifier greate
109f0 72 20 74 68 61 6e 20 74 68 69 73 20 6f 6e 65 2e  r than this one.
10a00 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
10a10 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20  param>..        
10a20 2f 2f 2f 20 3c 72 65 74 75 72 6e 73 3e 0d 0a 20  /// <returns>.. 
10a30 20 20 20 20 20 20 20 2f 2f 2f 20 41 20 73 74 61         /// A sta
10a40 6e 64 61 72 64 20 53 51 4c 69 74 65 20 72 65 74  ndard SQLite ret
10a50 75 72 6e 20 63 6f 64 65 2e 0d 0a 20 20 20 20 20  urn code...     
10a60 20 20 20 2f 2f 2f 20 3c 2f 72 65 74 75 72 6e 73     /// </returns
10a70 3e 0d 0a 20 20 20 20 20 20 20 20 53 51 4c 69 74  >..        SQLit
10a80 65 45 72 72 6f 72 43 6f 64 65 20 78 52 6f 6c 6c  eErrorCode xRoll
10a90 62 61 63 6b 54 6f 28 0d 0a 20 20 20 20 20 20 20  backTo(..       
10aa0 20 20 20 20 20 49 6e 74 50 74 72 20 70 56 74 61       IntPtr pVta
10ab0 62 2c 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20  b,..            
10ac0 69 6e 74 20 69 53 61 76 65 70 6f 69 6e 74 0d 0a  int iSavepoint..
10ad0 20 20 20 20 20 20 20 20 20 20 20 20 29 3b 0d 0a              );..
10ae0 20 20 20 20 7d 0d 0a 20 20 20 20 23 65 6e 64 72      }..    #endr
10af0 65 67 69 6f 6e 0d 0a 7d 0d 0a                    egion..}..