System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 293be00d3fef1a304df8e6846745f0470a5515d6:


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 0d 0a      /// <para>..
0250: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 69 73          /// This
0260: 20 6d 65 74 68 6f 64 20 69 73 20 63 61 6c 6c 65   method is calle
0270: 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 6e 65  d to create a ne
0280: 77 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 61 20  w instance of a 
0290: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 0d 0a 20  virtual table.. 
02a0: 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e 20 72 65         /// in re
02b0: 73 70 6f 6e 73 65 20 74 6f 20 61 20 43 52 45 41  sponse to a CREA
02c0: 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45  TE VIRTUAL TABLE
02d0: 20 73 74 61 74 65 6d 65 6e 74 2e 20 54 68 65 20   statement. The 
02e0: 64 62 20 70 61 72 61 6d 65 74 65 72 0d 0a 20 20  db parameter..  
02f0: 20 20 20 20 20 20 2f 2f 2f 20 69 73 20 61 20 70        /// is a p
0300: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 53 51  ointer to the SQ
0310: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 63 6f  Lite database co
0320: 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 73  nnection that is
0330: 20 65 78 65 63 75 74 69 6e 67 0d 0a 20 20 20 20   executing..    
0340: 20 20 20 20 2f 2f 2f 20 74 68 65 20 43 52 45 41      /// the CREA
0350: 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45  TE VIRTUAL TABLE
0360: 20 73 74 61 74 65 6d 65 6e 74 2e 20 54 68 65 20   statement. The 
0370: 70 41 75 78 20 61 72 67 75 6d 65 6e 74 20 69 73  pAux argument is
0380: 20 74 68 65 20 63 6f 70 79 0d 0a 20 20 20 20 20   the copy..     
0390: 20 20 20 2f 2f 2f 20 6f 66 20 74 68 65 20 63 6c     /// of the cl
03a0: 69 65 6e 74 20 64 61 74 61 20 70 6f 69 6e 74 65  ient data pointe
03b0: 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20 66  r that was the f
03c0: 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
03d0: 6f 20 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f  o the..        /
03e0: 2f 2f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  // sqlite3_creat
03f0: 65 5f 6d 6f 64 75 6c 65 28 29 20 6f 72 20 73 71  e_module() or sq
0400: 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
0410: 75 6c 65 5f 76 32 28 29 20 63 61 6c 6c 20 74 68  ule_v2() call th
0420: 61 74 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  at..        /// 
0430: 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 76  registered the v
0440: 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
0450: 75 6c 65 2e 20 54 68 65 20 61 72 67 76 20 70 61  ule. The argv pa
0460: 72 61 6d 65 74 65 72 20 69 73 20 61 6e 0d 0a 20  rameter is an.. 
0470: 20 20 20 20 20 20 20 2f 2f 2f 20 61 72 72 61 79         /// array
0480: 20 6f 66 20 61 72 67 63 20 70 6f 69 6e 74 65 72   of argc pointer
0490: 73 20 74 6f 20 6e 75 6c 6c 20 74 65 72 6d 69 6e  s to null termin
04a0: 61 74 65 64 20 73 74 72 69 6e 67 73 2e 20 54 68  ated strings. Th
04b0: 65 20 66 69 72 73 74 0d 0a 20 20 20 20 20 20 20  e first..       
04c0: 20 2f 2f 2f 20 73 74 72 69 6e 67 2c 20 61 72 67   /// string, arg
04d0: 76 5b 30 5d 2c 20 69 73 20 74 68 65 20 6e 61 6d  v[0], is the nam
04e0: 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20  e of the module 
04f0: 62 65 69 6e 67 20 69 6e 76 6f 6b 65 64 2e 20 54  being invoked. T
0500: 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  he..        /// 
0510: 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 69 73 20 74  module name is t
0520: 68 65 20 6e 61 6d 65 20 70 72 6f 76 69 64 65 64  he name provided
0530: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
0540: 72 67 75 6d 65 6e 74 20 74 6f 0d 0a 20 20 20 20  rgument to..    
0550: 20 20 20 20 2f 2f 2f 20 73 71 6c 69 74 65 33 5f      /// sqlite3_
0560: 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 20  create_module() 
0570: 61 6e 64 20 61 73 20 74 68 65 20 61 72 67 75 6d  and as the argum
0580: 65 6e 74 20 74 6f 20 74 68 65 20 55 53 49 4e 47  ent to the USING
0590: 20 63 6c 61 75 73 65 20 6f 66 0d 0a 20 20 20 20   clause of..    
05a0: 20 20 20 20 2f 2f 2f 20 74 68 65 20 43 52 45 41      /// the CREA
05b0: 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45  TE VIRTUAL TABLE
05c0: 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
05d0: 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 65 20  is running. The 
05e0: 73 65 63 6f 6e 64 2c 0d 0a 20 20 20 20 20 20 20  second,..       
05f0: 20 2f 2f 2f 20 61 72 67 76 5b 31 5d 2c 20 69 73   /// argv[1], is
0600: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
0610: 20 64 61 74 61 62 61 73 65 20 69 6e 20 77 68 69   database in whi
0620: 63 68 20 74 68 65 20 6e 65 77 20 76 69 72 74 75  ch the new virtu
0630: 61 6c 20 74 61 62 6c 65 0d 0a 20 20 20 20 20 20  al table..      
0640: 20 20 2f 2f 2f 20 69 73 20 62 65 69 6e 67 20 63    /// is being c
0650: 72 65 61 74 65 64 2e 20 54 68 65 20 64 61 74 61  reated. The data
0660: 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22 6d 61  base name is "ma
0670: 69 6e 22 20 66 6f 72 20 74 68 65 20 70 72 69 6d  in" for the prim
0680: 61 72 79 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ary..        ///
0690: 20 64 61 74 61 62 61 73 65 2c 20 6f 72 20 22 74   database, or "t
06a0: 65 6d 70 22 20 66 6f 72 20 54 45 4d 50 20 64 61  emp" for TEMP da
06b0: 74 61 62 61 73 65 2c 20 6f 72 20 74 68 65 20 6e  tabase, or the n
06c0: 61 6d 65 20 67 69 76 65 6e 20 61 74 20 74 68 65  ame given at the
06d0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 65 6e  ..        /// en
06e0: 64 20 6f 66 20 74 68 65 20 41 54 54 41 43 48 20  d of the ATTACH 
06f0: 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 61 74  statement for at
0700: 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
0710: 2e 20 54 68 65 20 74 68 69 72 64 0d 0a 20 20 20  . The third..   
0720: 20 20 20 20 20 2f 2f 2f 20 65 6c 65 6d 65 6e 74       /// element
0730: 20 6f 66 20 74 68 65 20 61 72 72 61 79 2c 20 61   of the array, a
0740: 72 67 76 5b 32 5d 2c 20 69 73 20 74 68 65 20 6e  rgv[2], is the n
0750: 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20 76  ame of the new v
0760: 69 72 74 75 61 6c 0d 0a 20 20 20 20 20 20 20 20  irtual..        
0770: 2f 2f 2f 20 74 61 62 6c 65 2c 20 61 73 20 73 70  /// table, as sp
0780: 65 63 69 66 69 65 64 20 66 6f 6c 6c 6f 77 69 6e  ecified followin
0790: 67 20 74 68 65 20 54 41 42 4c 45 20 6b 65 79 77  g the TABLE keyw
07a0: 6f 72 64 20 69 6e 20 74 68 65 20 43 52 45 41 54  ord in the CREAT
07b0: 45 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 56  E..        /// V
07c0: 49 52 54 55 41 4c 20 54 41 42 4c 45 20 73 74 61  IRTUAL TABLE sta
07d0: 74 65 6d 65 6e 74 2e 20 49 66 20 70 72 65 73 65  tement. If prese
07e0: 6e 74 2c 20 74 68 65 20 66 6f 75 72 74 68 20 61  nt, the fourth a
07f0: 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0d 0a 20  nd subsequent.. 
0800: 20 20 20 20 20 20 20 2f 2f 2f 20 73 74 72 69 6e         /// strin
0810: 67 73 20 69 6e 20 74 68 65 20 61 72 67 76 5b 5d  gs in the argv[]
0820: 20 61 72 72 61 79 20 72 65 70 6f 72 74 20 74 68   array report th
0830: 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  e arguments to t
0840: 68 65 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 0d 0a  he module name..
0850: 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e 20 74          /// in t
0860: 68 65 20 43 52 45 41 54 45 20 56 49 52 54 55 41  he CREATE VIRTUA
0870: 4c 20 54 41 42 4c 45 20 73 74 61 74 65 6d 65 6e  L TABLE statemen
0880: 74 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  t...        /// 
0890: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
08a0: 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20   /// <para>..   
08b0: 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 6a 6f 62       /// The job
08c0: 20 6f 66 20 74 68 69 73 20 6d 65 74 68 6f 64 20   of this method 
08d0: 69 73 20 74 6f 20 63 6f 6e 73 74 72 75 63 74 20  is to construct 
08e0: 74 68 65 20 6e 65 77 20 76 69 72 74 75 61 6c 20  the new virtual 
08f0: 74 61 62 6c 65 20 6f 62 6a 65 63 74 0d 0a 20 20  table object..  
0900: 20 20 20 20 20 20 2f 2f 2f 20 28 61 6e 20 73 71        /// (an sq
0910: 6c 69 74 65 33 5f 76 74 61 62 20 6f 62 6a 65 63  lite3_vtab objec
0920: 74 29 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20  t) and return a 
0930: 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 20 69 6e  pointer to it in
0940: 20 2a 70 70 56 54 61 62 2e 0d 0a 20 20 20 20 20   *ppVTab...     
0950: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a     /// </para>..
0960: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
0970: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
0980: 41 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 74  As part of the t
0990: 61 73 6b 20 6f 66 20 63 72 65 61 74 69 6e 67 20  ask of creating 
09a0: 61 20 6e 65 77 20 73 71 6c 69 74 65 33 5f 76 74  a new sqlite3_vt
09b0: 61 62 20 73 74 72 75 63 74 75 72 65 2c 20 74 68  ab structure, th
09c0: 69 73 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  is..        /// 
09d0: 6d 65 74 68 6f 64 20 6d 75 73 74 20 69 6e 76 6f  method must invo
09e0: 6b 65 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61  ke sqlite3_decla
09f0: 72 65 5f 76 74 61 62 28 29 20 74 6f 20 74 65 6c  re_vtab() to tel
0a00: 6c 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  l the SQLite cor
0a10: 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 61  e..        /// a
0a20: 62 6f 75 74 20 74 68 65 20 63 6f 6c 75 6d 6e 73  bout the columns
0a30: 20 61 6e 64 20 64 61 74 61 74 79 70 65 73 20 69   and datatypes i
0a40: 6e 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  n the virtual ta
0a50: 62 6c 65 2e 20 54 68 65 0d 0a 20 20 20 20 20 20  ble. The..      
0a60: 20 20 2f 2f 2f 20 73 71 6c 69 74 65 33 5f 64 65    /// sqlite3_de
0a70: 63 6c 61 72 65 5f 76 74 61 62 28 29 20 41 50 49  clare_vtab() API
0a80: 20 68 61 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69   has the followi
0a90: 6e 67 20 70 72 6f 74 6f 74 79 70 65 3a 0d 0a 20  ng prototype:.. 
0aa0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
0ab0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
0ac0: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
0ad0: 2f 2f 2f 20 3c 63 6f 64 65 3e 0d 0a 20 20 20 20  /// <code>..    
0ae0: 20 20 20 20 2f 2f 2f 20 69 6e 74 20 73 71 6c 69      /// int sqli
0af0: 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62  te3_declare_vtab
0b00: 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f  (sqlite3 *db, co
0b10: 6e 73 74 20 63 68 61 72 20 2a 7a 43 72 65 61 74  nst char *zCreat
0b20: 65 54 61 62 6c 65 29 0d 0a 20 20 20 20 20 20 20  eTable)..       
0b30: 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 0d 0a 20 20   /// </code>..  
0b40: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61        /// </para
0b50: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
0b60: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
0b70: 2f 2f 20 54 68 65 20 66 69 72 73 74 20 61 72 67  // The first arg
0b80: 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
0b90: 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 29 20  _declare_vtab() 
0ba0: 6d 75 73 74 20 62 65 20 74 68 65 20 73 61 6d 65  must be the same
0bb0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 64 61  ..        /// da
0bc0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
0bd0: 6e 20 70 6f 69 6e 74 65 72 20 61 73 20 74 68 65  n pointer as the
0be0: 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
0bf0: 20 74 6f 20 74 68 69 73 20 6d 65 74 68 6f 64 2e   to this method.
0c00: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
0c10: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
0c20: 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 65 63  t to sqlite3_dec
0c30: 6c 61 72 65 5f 76 74 61 62 28 29 20 6d 75 73 74  lare_vtab() must
0c40: 20 61 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20   a..        /// 
0c50: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
0c60: 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 61  UTF-8 string tha
0c70: 74 20 63 6f 6e 74 61 69 6e 73 20 61 20 77 65 6c  t contains a wel
0c80: 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 0d  l-formed CREATE.
0c90: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 41 42  .        /// TAB
0ca0: 4c 45 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  LE statement tha
0cb0: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 63 6f  t defines the co
0cc0: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 76 69 72  lumns in the vir
0cd0: 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 0d 0a  tual table and..
0ce0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 69          /// thei
0cf0: 72 20 64 61 74 61 20 74 79 70 65 73 2e 20 54 68  r data types. Th
0d00: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61  e name of the ta
0d10: 62 6c 65 20 69 6e 20 74 68 69 73 20 43 52 45 41  ble in this CREA
0d20: 54 45 20 54 41 42 4c 45 0d 0a 20 20 20 20 20 20  TE TABLE..      
0d30: 20 20 2f 2f 2f 20 73 74 61 74 65 6d 65 6e 74 20    /// statement 
0d40: 69 73 20 69 67 6e 6f 72 65 64 2c 20 61 73 20 61  is ignored, as a
0d50: 72 65 20 61 6c 6c 20 63 6f 6e 73 74 72 61 69 6e  re all constrain
0d60: 74 73 2e 20 4f 6e 6c 79 20 74 68 65 20 63 6f 6c  ts. Only the col
0d70: 75 6d 6e 20 6e 61 6d 65 73 0d 0a 20 20 20 20 20  umn names..     
0d80: 20 20 20 2f 2f 2f 20 61 6e 64 20 64 61 74 61 74     /// and datat
0d90: 79 70 65 73 20 6d 61 74 74 65 72 2e 20 54 68 65  ypes matter. The
0da0: 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 73 74   CREATE TABLE st
0db0: 61 74 65 6d 65 6e 74 20 73 74 72 69 6e 67 20 6e  atement string n
0dc0: 65 65 64 20 6e 6f 74 20 74 6f 0d 0a 20 20 20 20  eed not to..    
0dd0: 20 20 20 20 2f 2f 2f 20 62 65 20 68 65 6c 64 20      /// be held 
0de0: 69 6e 20 70 65 72 73 69 73 74 65 6e 74 20 6d 65  in persistent me
0df0: 6d 6f 72 79 2e 20 54 68 65 20 73 74 72 69 6e 67  mory. The string
0e00: 20 63 61 6e 20 62 65 20 64 65 61 6c 6c 6f 63 61   can be dealloca
0e10: 74 65 64 20 61 6e 64 2f 6f 72 0d 0a 20 20 20 20  ted and/or..    
0e20: 20 20 20 20 2f 2f 2f 20 72 65 75 73 65 64 20 61      /// reused a
0e30: 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 73 71  s soon as the sq
0e40: 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74  lite3_declare_vt
0e50: 61 62 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  ab() routine ret
0e60: 75 72 6e 73 2e 0d 0a 20 20 20 20 20 20 20 20 2f  urns...        /
0e70: 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  // </para>..    
0e80: 20 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72      /// </summar
0e90: 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  y>..        /// 
0ea0: 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 44 62  <param name="pDb
0eb0: 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ">..        /// 
0ec0: 54 68 65 20 6e 61 74 69 76 65 20 64 61 74 61 62  The native datab
0ed0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68  ase connection h
0ee0: 61 6e 64 6c 65 2e 0d 0a 20 20 20 20 20 20 20 20  andle...        
0ef0: 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20  /// </param>..  
0f00: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d        /// <param
0f10: 20 6e 61 6d 65 3d 22 70 41 75 78 22 3e 0d 0a 20   name="pAux">.. 
0f20: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 6f         /// The o
0f30: 72 69 67 69 6e 61 6c 20 6e 61 74 69 76 65 20 70  riginal native p
0f40: 6f 69 6e 74 65 72 20 76 61 6c 75 65 20 74 68 61  ointer value tha
0f50: 74 20 77 61 73 20 70 72 6f 76 69 64 65 64 20 74  t was provided t
0f60: 6f 20 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f  o the..        /
0f70: 2f 2f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  // sqlite3_creat
0f80: 65 5f 6d 6f 64 75 6c 65 28 29 2c 20 73 71 6c 69  e_module(), sqli
0f90: 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
0fa0: 65 5f 76 32 28 29 20 6f 72 0d 0a 20 20 20 20 20  e_v2() or..     
0fb0: 20 20 20 2f 2f 2f 20 73 71 6c 69 74 65 33 5f 63     /// sqlite3_c
0fc0: 72 65 61 74 65 5f 64 69 73 70 6f 73 61 62 6c 65  reate_disposable
0fd0: 5f 6d 6f 64 75 6c 65 28 29 20 66 75 6e 63 74 69  _module() functi
0fe0: 6f 6e 73 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ons...        //
0ff0: 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20  / </param>..    
1000: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e      /// <param n
1010: 61 6d 65 3d 22 61 72 67 63 22 3e 0d 0a 20 20 20  ame="argc">..   
1020: 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e 75 6d       /// The num
1030: 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
1040: 20 66 72 6f 6d 20 74 68 65 20 43 52 45 41 54 45   from the CREATE
1050: 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20 73   VIRTUAL TABLE s
1060: 74 61 74 65 6d 65 6e 74 2e 0d 0a 20 20 20 20 20  tatement...     
1070: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d     /// </param>.
1080: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
1090: 72 61 6d 20 6e 61 6d 65 3d 22 61 72 67 76 22 3e  ram name="argv">
10a0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
10b0: 65 20 61 72 72 61 79 20 6f 66 20 73 74 72 69 6e  e array of strin
10c0: 67 20 61 72 67 75 6d 65 6e 74 73 20 66 72 6f 6d  g arguments from
10d0: 20 74 68 65 20 43 52 45 41 54 45 20 56 49 52 54   the CREATE VIRT
10e0: 55 41 4c 20 54 41 42 4c 45 0d 0a 20 20 20 20 20  UAL TABLE..     
10f0: 20 20 20 2f 2f 2f 20 73 74 61 74 65 6d 65 6e 74     /// statement
1100: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
1110: 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20  /param>..       
1120: 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65   /// <param name
1130: 3d 22 70 56 74 61 62 22 3e 0d 0a 20 20 20 20 20  ="pVtab">..     
1140: 20 20 20 2f 2f 2f 20 55 70 6f 6e 20 73 75 63 63     /// Upon succ
1150: 65 73 73 2c 20 74 68 69 73 20 70 61 72 61 6d 65  ess, this parame
1160: 74 65 72 20 6d 75 73 74 20 62 65 20 6d 6f 64 69  ter must be modi
1170: 66 69 65 64 20 74 6f 20 70 6f 69 6e 74 20 74 6f  fied to point to
1180: 20 74 68 65 20 6e 65 77 6c 79 0d 0a 20 20 20 20   the newly..    
1190: 20 20 20 20 2f 2f 2f 20 63 72 65 61 74 65 64 20      /// created 
11a0: 6e 61 74 69 76 65 20 73 71 6c 69 74 65 33 5f 76  native sqlite3_v
11b0: 74 61 62 20 64 65 72 69 76 65 64 20 73 74 72 75  tab derived stru
11c0: 63 74 75 72 65 2e 0d 0a 20 20 20 20 20 20 20 20  cture...        
11d0: 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20  /// </param>..  
11e0: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d        /// <param
11f0: 20 6e 61 6d 65 3d 22 70 45 72 72 6f 72 22 3e 0d   name="pError">.
1200: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 55 70 6f  .        /// Upo
1210: 6e 20 66 61 69 6c 75 72 65 2c 20 74 68 69 73 20  n failure, this 
1220: 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
1230: 65 20 6d 6f 64 69 66 69 65 64 20 74 6f 20 70 6f  e modified to po
1240: 69 6e 74 20 74 6f 20 74 68 65 20 65 72 72 6f 72  int to the error
1250: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6d 65  ..        /// me
1260: 73 73 61 67 65 2c 20 77 69 74 68 20 74 68 65 20  ssage, with the 
1270: 75 6e 64 65 72 6c 79 69 6e 67 20 6d 65 6d 6f 72  underlying memor
1280: 79 20 68 61 76 69 6e 67 20 62 65 65 6e 20 6f 62  y having been ob
1290: 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 68 65 0d  tained from the.
12a0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 71 6c  .        /// sql
12b0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 75  ite3_malloc() fu
12c0: 6e 63 74 69 6f 6e 2e 0d 0a 20 20 20 20 20 20 20  nction...       
12d0: 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20   /// </param>.. 
12e0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 72 65 74 75         /// <retu
12f0: 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  rns>..        //
1300: 2f 20 41 20 73 74 61 6e 64 61 72 64 20 53 51 4c  / A standard SQL
1310: 69 74 65 20 72 65 74 75 72 6e 20 63 6f 64 65 2e  ite return code.
1320: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
1330: 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20  returns>..      
1340: 20 20 53 51 4c 69 74 65 45 72 72 6f 72 43 6f 64    SQLiteErrorCod
1350: 65 20 78 43 72 65 61 74 65 28 0d 0a 20 20 20 20  e xCreate(..    
1360: 20 20 20 20 20 20 20 20 49 6e 74 50 74 72 20 70          IntPtr p
1370: 44 62 2c 0d 0a 20 20 20 20 20 20 20 20 20 20 20  Db,..           
1380: 20 49 6e 74 50 74 72 20 70 41 75 78 2c 0d 0a 20   IntPtr pAux,.. 
1390: 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61             int a
13a0: 72 67 63 2c 0d 0a 20 20 20 20 20 20 20 20 20 20  rgc,..          
13b0: 20 20 49 6e 74 50 74 72 20 61 72 67 76 2c 0d 0a    IntPtr argv,..
13c0: 20 20 20 20 20 20 20 20 20 20 20 20 72 65 66 20              ref 
13d0: 49 6e 74 50 74 72 20 70 56 74 61 62 2c 0d 0a 20  IntPtr pVtab,.. 
13e0: 20 20 20 20 20 20 20 20 20 20 20 72 65 66 20 49             ref I
13f0: 6e 74 50 74 72 20 70 45 72 72 6f 72 0d 0a 20 20  ntPtr pError..  
1400: 20 20 20 20 20 20 20 20 20 20 29 3b 0d 0a 0d 0a            );....
1410: 20 20 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f          ////////
1420: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
1430: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
1440: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
1450: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d  ///////////////.
1460: 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
1470: 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20  summary>..      
1480: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
1490: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 43        /// The xC
14a0: 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64 20 69 73  onnect method is
14b0: 20 76 65 72 79 20 73 69 6d 69 6c 61 72 20 74 6f   very similar to
14c0: 20 78 43 72 65 61 74 65 2e 20 49 74 20 68 61 73   xCreate. It has
14d0: 20 74 68 65 20 73 61 6d 65 0d 0a 20 20 20 20 20   the same..     
14e0: 20 20 20 2f 2f 2f 20 70 61 72 61 6d 65 74 65 72     /// parameter
14f0: 73 20 61 6e 64 20 63 6f 6e 73 74 72 75 63 74 73  s and constructs
1500: 20 61 20 6e 65 77 20 73 71 6c 69 74 65 33 5f 76   a new sqlite3_v
1510: 74 61 62 20 73 74 72 75 63 74 75 72 65 20 6a 75  tab structure ju
1520: 73 74 20 6c 69 6b 65 0d 0a 20 20 20 20 20 20 20  st like..       
1530: 20 2f 2f 2f 20 78 43 72 65 61 74 65 2e 20 41 6e   /// xCreate. An
1540: 64 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 63  d it must also c
1550: 61 6c 6c 20 73 71 6c 69 74 65 33 5f 64 65 63 6c  all sqlite3_decl
1560: 61 72 65 5f 76 74 61 62 28 29 20 6c 69 6b 65 20  are_vtab() like 
1570: 78 43 72 65 61 74 65 2e 0d 0a 20 20 20 20 20 20  xCreate...      
1580: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
1590: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
15a0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54  >..        /// T
15b0: 68 65 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  he difference is
15c0: 20 74 68 61 74 20 78 43 6f 6e 6e 65 63 74 20 69   that xConnect i
15d0: 73 20 63 61 6c 6c 65 64 20 74 6f 20 65 73 74 61  s called to esta
15e0: 62 6c 69 73 68 20 61 20 6e 65 77 0d 0a 20 20 20  blish a new..   
15f0: 20 20 20 20 20 2f 2f 2f 20 63 6f 6e 6e 65 63 74       /// connect
1600: 69 6f 6e 20 74 6f 20 61 6e 20 65 78 69 73 74 69  ion to an existi
1610: 6e 67 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ng virtual table
1620: 20 77 68 65 72 65 61 73 20 78 43 72 65 61 74 65   whereas xCreate
1630: 20 69 73 20 63 61 6c 6c 65 64 0d 0a 20 20 20 20   is called..    
1640: 20 20 20 20 2f 2f 2f 20 74 6f 20 63 72 65 61 74      /// to creat
1650: 65 20 61 20 6e 65 77 20 76 69 72 74 75 61 6c 20  e a new virtual 
1660: 74 61 62 6c 65 20 66 72 6f 6d 20 73 63 72 61 74  table from scrat
1670: 63 68 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ch...        ///
1680: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
1690: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
16a0: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 43        /// The xC
16b0: 72 65 61 74 65 20 61 6e 64 20 78 43 6f 6e 6e 65  reate and xConne
16c0: 63 74 20 6d 65 74 68 6f 64 73 20 61 72 65 20 6f  ct methods are o
16d0: 6e 6c 79 20 64 69 66 66 65 72 65 6e 74 20 77 68  nly different wh
16e0: 65 6e 20 74 68 65 0d 0a 20 20 20 20 20 20 20 20  en the..        
16f0: 2f 2f 2f 20 76 69 72 74 75 61 6c 20 74 61 62 6c  /// virtual tabl
1700: 65 20 68 61 73 20 73 6f 6d 65 20 6b 69 6e 64 20  e has some kind 
1710: 6f 66 20 62 61 63 6b 69 6e 67 20 73 74 6f 72 65  of backing store
1720: 20 74 68 61 74 20 6d 75 73 74 20 62 65 0d 0a 20   that must be.. 
1730: 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e 69 74 69         /// initi
1740: 61 6c 69 7a 65 64 20 74 68 65 20 66 69 72 73 74  alized the first
1750: 20 74 69 6d 65 20 74 68 65 20 76 69 72 74 75 61   time the virtua
1760: 6c 20 74 61 62 6c 65 20 69 73 20 63 72 65 61 74  l table is creat
1770: 65 64 2e 20 54 68 65 0d 0a 20 20 20 20 20 20 20  ed. The..       
1780: 20 2f 2f 2f 20 78 43 72 65 61 74 65 20 6d 65 74   /// xCreate met
1790: 68 6f 64 20 63 72 65 61 74 65 73 20 61 6e 64 20  hod creates and 
17a0: 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20  initializes the 
17b0: 62 61 63 6b 69 6e 67 20 73 74 6f 72 65 2e 20 54  backing store. T
17c0: 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  he..        /// 
17d0: 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64 20  xConnect method 
17e0: 6a 75 73 74 20 63 6f 6e 6e 65 63 74 73 20 74 6f  just connects to
17f0: 20 61 6e 20 65 78 69 73 74 69 6e 67 20 62 61 63   an existing bac
1800: 6b 69 6e 67 20 73 74 6f 72 65 2e 0d 0a 20 20 20  king store...   
1810: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e       /// </para>
1820: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
1830: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
1840: 2f 20 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 2c  / As an example,
1850: 20 63 6f 6e 73 69 64 65 72 20 61 20 76 69 72 74   consider a virt
1860: 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
1870: 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 0d 0a 20  entation that.. 
1880: 20 20 20 20 20 20 20 2f 2f 2f 20 70 72 6f 76 69         /// provi
1890: 64 65 73 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63  des read-only ac
18a0: 63 65 73 73 20 74 6f 20 65 78 69 73 74 69 6e 67  cess to existing
18b0: 20 63 6f 6d 6d 61 2d 73 65 70 61 72 61 74 65 64   comma-separated
18c0: 2d 76 61 6c 75 65 20 28 43 53 56 29 0d 0a 20 20  -value (CSV)..  
18d0: 20 20 20 20 20 20 2f 2f 2f 20 66 69 6c 65 73 20        /// files 
18e0: 6f 6e 20 64 69 73 6b 2e 20 54 68 65 72 65 20 69  on disk. There i
18f0: 73 20 6e 6f 20 62 61 63 6b 69 6e 67 20 73 74 6f  s no backing sto
1900: 72 65 20 74 68 61 74 20 6e 65 65 64 73 20 74 6f  re that needs to
1910: 20 62 65 20 63 72 65 61 74 65 64 0d 0a 20 20 20   be created..   
1920: 20 20 20 20 20 2f 2f 2f 20 6f 72 20 69 6e 69 74       /// or init
1930: 69 61 6c 69 7a 65 64 20 66 6f 72 20 73 75 63 68  ialized for such
1940: 20 61 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65   a virtual table
1950: 20 28 73 69 6e 63 65 20 74 68 65 20 43 53 56 20   (since the CSV 
1960: 66 69 6c 65 73 0d 0a 20 20 20 20 20 20 20 20 2f  files..        /
1970: 2f 2f 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  // already exist
1980: 20 6f 6e 20 64 69 73 6b 29 20 73 6f 20 74 68 65   on disk) so the
1990: 20 78 43 72 65 61 74 65 20 61 6e 64 20 78 43 6f   xCreate and xCo
19a0: 6e 6e 65 63 74 20 6d 65 74 68 6f 64 73 20 77 69  nnect methods wi
19b0: 6c 6c 20 62 65 0d 0a 20 20 20 20 20 20 20 20 2f  ll be..        /
19c0: 2f 2f 20 69 64 65 6e 74 69 63 61 6c 20 66 6f 72  // identical for
19d0: 20 74 68 61 74 20 6d 6f 64 75 6c 65 2e 0d 0a 20   that module... 
19e0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
19f0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
1a00: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
1a10: 2f 2f 2f 20 41 6e 6f 74 68 65 72 20 65 78 61 6d  /// Another exam
1a20: 70 6c 65 20 69 73 20 61 20 76 69 72 74 75 61 6c  ple is a virtual
1a30: 20 74 61 62 6c 65 20 74 68 61 74 20 69 6d 70 6c   table that impl
1a40: 65 6d 65 6e 74 73 20 61 20 66 75 6c 6c 2d 74 65  ements a full-te
1a50: 78 74 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  xt..        /// 
1a60: 69 6e 64 65 78 2e 20 54 68 65 20 78 43 72 65 61  index. The xCrea
1a70: 74 65 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 63  te method must c
1a80: 72 65 61 74 65 20 61 6e 64 20 69 6e 69 74 69 61  reate and initia
1a90: 6c 69 7a 65 20 64 61 74 61 0d 0a 20 20 20 20 20  lize data..     
1aa0: 20 20 20 2f 2f 2f 20 73 74 72 75 63 74 75 72 65     /// structure
1ab0: 73 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 64 69  s to hold the di
1ac0: 63 74 69 6f 6e 61 72 79 20 61 6e 64 20 70 6f 73  ctionary and pos
1ad0: 74 69 6e 67 20 6c 69 73 74 73 20 66 6f 72 20 74  ting lists for t
1ae0: 68 61 74 20 69 6e 64 65 78 2e 0d 0a 20 20 20 20  hat index...    
1af0: 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 43 6f 6e      /// The xCon
1b00: 6e 65 63 74 20 6d 65 74 68 6f 64 2c 20 6f 6e 20  nect method, on 
1b10: 74 68 65 20 6f 74 68 65 72 20 68 61 6e 64 2c 20  the other hand, 
1b20: 6f 6e 6c 79 20 68 61 73 20 74 6f 20 6c 6f 63 61  only has to loca
1b30: 74 65 20 61 6e 64 20 75 73 65 0d 0a 20 20 20 20  te and use..    
1b40: 20 20 20 20 2f 2f 2f 20 61 6e 20 65 78 69 73 74      /// an exist
1b50: 69 6e 67 20 64 69 63 74 69 6f 6e 61 72 79 20 61  ing dictionary a
1b60: 6e 64 20 70 6f 73 74 69 6e 67 20 6c 69 73 74 73  nd posting lists
1b70: 20 74 68 61 74 20 77 65 72 65 20 63 72 65 61 74   that were creat
1b80: 65 64 20 62 79 20 61 0d 0a 20 20 20 20 20 20 20  ed by a..       
1b90: 20 2f 2f 2f 20 70 72 69 6f 72 20 78 43 72 65 61   /// prior xCrea
1ba0: 74 65 20 63 61 6c 6c 2e 0d 0a 20 20 20 20 20 20  te call...      
1bb0: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
1bc0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
1bd0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54  >..        /// T
1be0: 68 65 20 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68  he xConnect meth
1bf0: 6f 64 20 6d 75 73 74 20 72 65 74 75 72 6e 20 53  od must return S
1c00: 51 4c 49 54 45 5f 4f 4b 20 69 66 20 69 74 20 69  QLITE_OK if it i
1c10: 73 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 0d  s successful in.
1c20: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 63 72 65  .        /// cre
1c30: 61 74 69 6e 67 20 74 68 65 20 6e 65 77 20 76 69  ating the new vi
1c40: 72 74 75 61 6c 20 74 61 62 6c 65 2c 20 6f 72 20  rtual table, or 
1c50: 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 69 66 20  SQLITE_ERROR if 
1c60: 69 74 20 69 73 20 6e 6f 74 0d 0a 20 20 20 20 20  it is not..     
1c70: 20 20 20 2f 2f 2f 20 73 75 63 63 65 73 73 66 75     /// successfu
1c80: 6c 2e 20 49 66 20 6e 6f 74 20 73 75 63 63 65 73  l. If not succes
1c90: 73 66 75 6c 2c 20 74 68 65 20 73 71 6c 69 74 65  sful, the sqlite
1ca0: 33 5f 76 74 61 62 20 73 74 72 75 63 74 75 72 65  3_vtab structure
1cb0: 20 6d 75 73 74 20 6e 6f 74 0d 0a 20 20 20 20 20   must not..     
1cc0: 20 20 20 2f 2f 2f 20 62 65 20 61 6c 6c 6f 63 61     /// be alloca
1cd0: 74 65 64 2e 20 41 6e 20 65 72 72 6f 72 20 6d 65  ted. An error me
1ce0: 73 73 61 67 65 20 6d 61 79 20 6f 70 74 69 6f 6e  ssage may option
1cf0: 61 6c 6c 79 20 62 65 20 72 65 74 75 72 6e 65 64  ally be returned
1d00: 20 69 6e 20 2a 70 7a 45 72 72 0d 0a 20 20 20 20   in *pzErr..    
1d10: 20 20 20 20 2f 2f 2f 20 69 66 20 75 6e 73 75 63      /// if unsuc
1d20: 63 65 73 73 66 75 6c 2e 20 53 70 61 63 65 20 74  cessful. Space t
1d30: 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
1d40: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
1d50: 6d 75 73 74 20 62 65 0d 0a 20 20 20 20 20 20 20  must be..       
1d60: 20 2f 2f 2f 20 61 6c 6c 6f 63 61 74 65 64 20 75   /// allocated u
1d70: 73 69 6e 67 20 61 6e 20 53 51 4c 69 74 65 20 6d  sing an SQLite m
1d80: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1d90: 20 66 75 6e 63 74 69 6f 6e 20 6c 69 6b 65 0d 0a   function like..
1da0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 71 6c 69          /// sqli
1db0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
1dc0: 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1dd0: 29 20 61 73 20 74 68 65 20 53 51 4c 69 74 65 20  ) as the SQLite 
1de0: 63 6f 72 65 20 77 69 6c 6c 0d 0a 20 20 20 20 20  core will..     
1df0: 20 20 20 2f 2f 2f 20 61 74 74 65 6d 70 74 20 74     /// attempt t
1e00: 6f 20 66 72 65 65 20 74 68 65 20 73 70 61 63 65  o free the space
1e10: 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 66   using sqlite3_f
1e20: 72 65 65 28 29 20 61 66 74 65 72 20 74 68 65 20  ree() after the 
1e30: 65 72 72 6f 72 20 68 61 73 0d 0a 20 20 20 20 20  error has..     
1e40: 20 20 20 2f 2f 2f 20 62 65 65 6e 20 72 65 70 6f     /// been repo
1e50: 72 74 65 64 20 75 70 20 74 6f 20 74 68 65 20 61  rted up to the a
1e60: 70 70 6c 69 63 61 74 69 6f 6e 2e 0d 0a 20 20 20  pplication...   
1e70: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e       /// </para>
1e80: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
1e90: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
1ea0: 2f 20 54 68 65 20 78 43 6f 6e 6e 65 63 74 20 6d  / The xConnect m
1eb0: 65 74 68 6f 64 20 69 73 20 72 65 71 75 69 72 65  ethod is require
1ec0: 64 20 66 6f 72 20 65 76 65 72 79 20 76 69 72 74  d for every virt
1ed0: 75 61 6c 20 74 61 62 6c 65 0d 0a 20 20 20 20 20  ual table..     
1ee0: 20 20 20 2f 2f 2f 20 69 6d 70 6c 65 6d 65 6e 74     /// implement
1ef0: 61 74 69 6f 6e 2c 20 74 68 6f 75 67 68 20 74 68  ation, though th
1f00: 65 20 78 43 72 65 61 74 65 20 61 6e 64 20 78 43  e xCreate and xC
1f10: 6f 6e 6e 65 63 74 20 70 6f 69 6e 74 65 72 73 20  onnect pointers 
1f20: 6f 66 20 74 68 65 0d 0a 20 20 20 20 20 20 20 20  of the..        
1f30: 2f 2f 2f 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  /// sqlite3_modu
1f40: 6c 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 70 6f  le object may po
1f50: 69 6e 74 20 74 6f 20 74 68 65 20 73 61 6d 65 20  int to the same 
1f60: 66 75 6e 63 74 69 6f 6e 20 74 68 65 20 76 69 72  function the vir
1f70: 74 75 61 6c 0d 0a 20 20 20 20 20 20 20 20 2f 2f  tual..        //
1f80: 2f 20 74 61 62 6c 65 20 64 6f 65 73 20 6e 6f 74  / table does not
1f90: 20 6e 65 65 64 20 74 6f 20 69 6e 69 74 69 61 6c   need to initial
1fa0: 69 7a 65 20 62 61 63 6b 69 6e 67 20 73 74 6f 72  ize backing stor
1fb0: 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e...        /// 
1fc0: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
1fd0: 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d   /// </summary>.
1fe0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
1ff0: 72 61 6d 20 6e 61 6d 65 3d 22 70 44 62 22 3e 0d  ram name="pDb">.
2000: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65  .        /// The
2010: 20 6e 61 74 69 76 65 20 64 61 74 61 62 61 73 65   native database
2020: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64   connection hand
2030: 6c 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  le...        ///
2040: 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20   </param>..     
2050: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61     /// <param na
2060: 6d 65 3d 22 70 41 75 78 22 3e 0d 0a 20 20 20 20  me="pAux">..    
2070: 20 20 20 20 2f 2f 2f 20 54 68 65 20 6f 72 69 67      /// The orig
2080: 69 6e 61 6c 20 6e 61 74 69 76 65 20 70 6f 69 6e  inal native poin
2090: 74 65 72 20 76 61 6c 75 65 20 74 68 61 74 20 77  ter value that w
20a0: 61 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74  as provided to t
20b0: 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  he..        /// 
20c0: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
20d0: 6f 64 75 6c 65 28 29 2c 20 73 71 6c 69 74 65 33  odule(), sqlite3
20e0: 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76  _create_module_v
20f0: 32 28 29 20 6f 72 0d 0a 20 20 20 20 20 20 20 20  2() or..        
2100: 2f 2f 2f 20 73 71 6c 69 74 65 33 5f 63 72 65 61  /// sqlite3_crea
2110: 74 65 5f 64 69 73 70 6f 73 61 62 6c 65 5f 6d 6f  te_disposable_mo
2120: 64 75 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 73  dule() functions
2130: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
2140: 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20  /param>..       
2150: 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65   /// <param name
2160: 3d 22 61 72 67 63 22 3e 0d 0a 20 20 20 20 20 20  ="argc">..      
2170: 20 20 2f 2f 2f 20 54 68 65 20 6e 75 6d 62 65 72    /// The number
2180: 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 66 72   of arguments fr
2190: 6f 6d 20 74 68 65 20 43 52 45 41 54 45 20 56 49  om the CREATE VI
21a0: 52 54 55 41 4c 20 54 41 42 4c 45 20 73 74 61 74  RTUAL TABLE stat
21b0: 65 6d 65 6e 74 2e 0d 0a 20 20 20 20 20 20 20 20  ement...        
21c0: 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20  /// </param>..  
21d0: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d        /// <param
21e0: 20 6e 61 6d 65 3d 22 61 72 67 76 22 3e 0d 0a 20   name="argv">.. 
21f0: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 61         /// The a
2200: 72 72 61 79 20 6f 66 20 73 74 72 69 6e 67 20 61  rray of string a
2210: 72 67 75 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68  rguments from th
2220: 65 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c  e CREATE VIRTUAL
2230: 20 54 41 42 4c 45 0d 0a 20 20 20 20 20 20 20 20   TABLE..        
2240: 2f 2f 2f 20 73 74 61 74 65 6d 65 6e 74 2e 0d 0a  /// statement...
2250: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
2260: 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ram>..        //
2270: 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70  / <param name="p
2280: 56 74 61 62 22 3e 0d 0a 20 20 20 20 20 20 20 20  Vtab">..        
2290: 2f 2f 2f 20 55 70 6f 6e 20 73 75 63 63 65 73 73  /// Upon success
22a0: 2c 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  , this parameter
22b0: 20 6d 75 73 74 20 62 65 20 6d 6f 64 69 66 69 65   must be modifie
22c0: 64 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  d to point to th
22d0: 65 20 6e 65 77 6c 79 0d 0a 20 20 20 20 20 20 20  e newly..       
22e0: 20 2f 2f 2f 20 63 72 65 61 74 65 64 20 6e 61 74   /// created nat
22f0: 69 76 65 20 73 71 6c 69 74 65 33 5f 76 74 61 62  ive sqlite3_vtab
2300: 20 64 65 72 69 76 65 64 20 73 74 72 75 63 74 75   derived structu
2310: 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  re...        ///
2320: 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20   </param>..     
2330: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61     /// <param na
2340: 6d 65 3d 22 70 45 72 72 6f 72 22 3e 0d 0a 20 20  me="pError">..  
2350: 20 20 20 20 20 20 2f 2f 2f 20 55 70 6f 6e 20 66        /// Upon f
2360: 61 69 6c 75 72 65 2c 20 74 68 69 73 20 70 61 72  ailure, this par
2370: 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 6d  ameter must be m
2380: 6f 64 69 66 69 65 64 20 74 6f 20 70 6f 69 6e 74  odified to point
2390: 20 74 6f 20 74 68 65 20 65 72 72 6f 72 0d 0a 20   to the error.. 
23a0: 20 20 20 20 20 20 20 2f 2f 2f 20 6d 65 73 73 61         /// messa
23b0: 67 65 2c 20 77 69 74 68 20 74 68 65 20 75 6e 64  ge, with the und
23c0: 65 72 6c 79 69 6e 67 20 6d 65 6d 6f 72 79 20 68  erlying memory h
23d0: 61 76 69 6e 67 20 62 65 65 6e 20 6f 62 74 61 69  aving been obtai
23e0: 6e 65 64 20 66 72 6f 6d 20 74 68 65 0d 0a 20 20  ned from the..  
23f0: 20 20 20 20 20 20 2f 2f 2f 20 73 71 6c 69 74 65        /// sqlite
2400: 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 75 6e 63 74  3_malloc() funct
2410: 69 6f 6e 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ion...        //
2420: 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20  / </param>..    
2430: 20 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72 6e 73      /// <returns
2440: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41  >..        /// A
2450: 20 73 74 61 6e 64 61 72 64 20 53 51 4c 69 74 65   standard SQLite
2460: 20 72 65 74 75 72 6e 20 63 6f 64 65 2e 0d 0a 20   return code... 
2470: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72 65 74         /// </ret
2480: 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 53  urns>..        S
2490: 51 4c 69 74 65 45 72 72 6f 72 43 6f 64 65 20 78  QLiteErrorCode x
24a0: 43 6f 6e 6e 65 63 74 28 0d 0a 20 20 20 20 20 20  Connect(..      
24b0: 20 20 20 20 20 20 49 6e 74 50 74 72 20 70 44 62        IntPtr pDb
24c0: 2c 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 49  ,..            I
24d0: 6e 74 50 74 72 20 70 41 75 78 2c 0d 0a 20 20 20  ntPtr pAux,..   
24e0: 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
24f0: 63 2c 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20  c,..            
2500: 49 6e 74 50 74 72 20 61 72 67 76 2c 0d 0a 20 20  IntPtr argv,..  
2510: 20 20 20 20 20 20 20 20 20 20 72 65 66 20 49 6e            ref In
2520: 74 50 74 72 20 70 56 74 61 62 2c 0d 0a 20 20 20  tPtr pVtab,..   
2530: 20 20 20 20 20 20 20 20 20 72 65 66 20 49 6e 74           ref Int
2540: 50 74 72 20 70 45 72 72 6f 72 0d 0a 20 20 20 20  Ptr pError..    
2550: 20 20 20 20 20 20 20 20 29 3b 0d 0a 0d 0a 20 20          );....  
2560: 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f        //////////
2570: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
2580: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
2590: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
25a0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d  /////////////...
25b0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 73 75  .        /// <su
25c0: 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20  mmary>..        
25d0: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20  /// <para>..    
25e0: 20 20 20 20 2f 2f 2f 20 53 51 4c 69 74 65 20 75      /// SQLite u
25f0: 73 65 73 20 74 68 65 20 78 42 65 73 74 49 6e 64  ses the xBestInd
2600: 65 78 20 6d 65 74 68 6f 64 20 6f 66 20 61 20 76  ex method of a v
2610: 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
2620: 75 6c 65 20 74 6f 0d 0a 20 20 20 20 20 20 20 20  ule to..        
2630: 2f 2f 2f 20 64 65 74 65 72 6d 69 6e 65 20 74 68  /// determine th
2640: 65 20 62 65 73 74 20 77 61 79 20 74 6f 20 61 63  e best way to ac
2650: 63 65 73 73 20 74 68 65 20 76 69 72 74 75 61 6c  cess the virtual
2660: 20 74 61 62 6c 65 2e 20 54 68 65 20 78 42 65 73   table. The xBes
2670: 74 49 6e 64 65 78 0d 0a 20 20 20 20 20 20 20 20  tIndex..        
2680: 2f 2f 2f 20 6d 65 74 68 6f 64 20 68 61 73 20 61  /// method has a
2690: 20 70 72 6f 74 6f 74 79 70 65 20 6c 69 6b 65 20   prototype like 
26a0: 74 68 69 73 3a 0d 0a 20 20 20 20 20 20 20 20 2f  this:..        /
26b0: 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  // </para>..    
26c0: 20 20 20 20 2f 2f 2f 20 3c 63 6f 64 65 3e 0d 0a      /// <code>..
26d0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e 74 20          /// int 
26e0: 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 71  (*xBestIndex)(sq
26f0: 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
2700: 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  b, sqlite3_index
2710: 5f 69 6e 66 6f 2a 29 3b 0d 0a 20 20 20 20 20 20  _info*);..      
2720: 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 0d 0a 20    /// </code>.. 
2730: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
2740: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54  >..        /// T
2750: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 63  he SQLite core c
2760: 6f 6d 6d 75 6e 69 63 61 74 65 73 20 77 69 74 68  ommunicates with
2770: 20 74 68 65 20 78 42 65 73 74 49 6e 64 65 78 20   the xBestIndex 
2780: 6d 65 74 68 6f 64 20 62 79 20 66 69 6c 6c 69 6e  method by fillin
2790: 67 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69  g..        /// i
27a0: 6e 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64 73  n certain fields
27b0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
27c0: 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63  index_info struc
27d0: 74 75 72 65 20 61 6e 64 20 70 61 73 73 69 6e 67  ture and passing
27e0: 20 61 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20   a..        /// 
27f0: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
2800: 73 74 72 75 63 74 75 72 65 20 69 6e 74 6f 20 78  structure into x
2810: 42 65 73 74 49 6e 64 65 78 20 61 73 20 74 68 65  BestIndex as the
2820: 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2830: 72 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  r...        /// 
2840: 54 68 65 20 78 42 65 73 74 49 6e 64 65 78 20 6d  The xBestIndex m
2850: 65 74 68 6f 64 20 66 69 6c 6c 73 20 6f 75 74 20  ethod fills out 
2860: 6f 74 68 65 72 20 66 69 65 6c 64 73 20 6f 66 20  other fields of 
2870: 74 68 69 73 20 73 74 72 75 63 74 75 72 65 0d 0a  this structure..
2880: 20 20 20 20 20 20 20 20 2f 2f 2f 20 77 68 69 63          /// whic
2890: 68 20 66 6f 72 6d 73 20 74 68 65 20 72 65 70 6c  h forms the repl
28a0: 79 2e 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  y. The sqlite3_i
28b0: 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74  ndex_info struct
28c0: 75 72 65 20 6c 6f 6f 6b 73 20 6c 69 6b 65 0d 0a  ure looks like..
28d0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 69 73          /// this
28e0: 3a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  :..        /// <
28f0: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
2900: 2f 2f 2f 20 3c 63 6f 64 65 3e 0d 0a 20 20 20 20  /// <code>..    
2910: 20 20 20 20 2f 2f 2f 20 20 73 74 72 75 63 74 20      ///  struct 
2920: 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
2930: 66 6f 20 7b 0d 0a 20 20 20 20 20 20 20 20 2f 2f  fo {..        //
2940: 2f 20 20 20 20 2f 2a 20 49 6e 70 75 74 73 20 2a  /    /* Inputs *
2950: 2f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20  /..        ///  
2960: 20 20 63 6f 6e 73 74 20 69 6e 74 20 6e 43 6f 6e    const int nCon
2970: 73 74 72 61 69 6e 74 3b 20 20 20 2f 2a 20 4e 75  straint;   /* Nu
2980: 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20  mber of entries 
2990: 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 20 2a  in aConstraint *
29a0: 2f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20  /..        ///  
29b0: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
29c0: 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e  qlite3_index_con
29d0: 73 74 72 61 69 6e 74 20 7b 0d 0a 20 20 20 20 20  straint {..     
29e0: 20 20 20 2f 2f 2f 20 20 20 20 20 20 20 69 6e 74     ///       int
29f0: 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20   iColumn;       
2a00: 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20     /* Column on 
2a10: 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  left-hand side o
2a20: 66 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20  f..        ///  
2a30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a40: 20 20 20 20 20 20 20 20 20 20 20 20 2a 20 63 6f              * co
2a50: 6e 73 74 72 61 69 6e 74 20 2a 2f 0d 0a 20 20 20  nstraint */..   
2a60: 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 20 20 75       ///       u
2a70: 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b  nsigned char op;
2a80: 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74 72 61 69       /* Constrai
2a90: 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a 2f 0d 0a  nt operator */..
2aa0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20          ///     
2ab0: 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20    unsigned char 
2ac0: 75 73 61 62 6c 65 3b 20 2f 2a 20 54 72 75 65 20  usable; /* True 
2ad0: 69 66 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69  if this constrai
2ae0: 6e 74 20 69 73 20 75 73 61 62 6c 65 20 2a 2f 0d  nt is usable */.
2af0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20  .        ///    
2b00: 20 20 20 69 6e 74 20 69 54 65 72 6d 4f 66 66 73     int iTermOffs
2b10: 65 74 3b 20 20 20 20 20 20 2f 2a 20 55 73 65 64  et;      /* Used
2b20: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42   internally - xB
2b30: 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 0d  estIndex should.
2b40: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20  .        ///    
2b50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b60: 20 20 20 20 20 20 20 20 20 20 2a 20 69 67 6e 6f            * igno
2b70: 72 65 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20 2f  re */..        /
2b80: 2f 2f 20 20 20 20 7d 20 2a 63 6f 6e 73 74 20 61  //    } *const a
2b90: 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 2f  Constraint;    /
2ba0: 2a 20 54 61 62 6c 65 20 6f 66 20 57 48 45 52 45  * Table of WHERE
2bb0: 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69   clause constrai
2bc0: 6e 74 73 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20  nts */..        
2bd0: 2f 2f 2f 20 20 20 20 63 6f 6e 73 74 20 69 6e 74  ///    const int
2be0: 20 6e 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20   nOrderBy;      
2bf0: 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 72  /* Number of ter
2c00: 6d 73 20 69 6e 20 74 68 65 20 4f 52 44 45 52 20  ms in the ORDER 
2c10: 42 59 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  BY..        /// 
2c20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2c30: 20 20 20 20 20 20 20 20 20 20 20 20 20 2a 20 63               * c
2c40: 6c 61 75 73 65 20 2a 2f 0d 0a 20 20 20 20 20 20  lause */..      
2c50: 20 20 2f 2f 2f 20 20 20 20 63 6f 6e 73 74 20 73    ///    const s
2c60: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e  truct sqlite3_in
2c70: 64 65 78 5f 6f 72 64 65 72 62 79 20 7b 0d 0a 20  dex_orderby {.. 
2c80: 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 20         ///      
2c90: 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20   int iColumn;   
2ca0: 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e         /* Column
2cb0: 20 6e 75 6d 62 65 72 20 2a 2f 0d 0a 20 20 20 20   number */..    
2cc0: 20 20 20 20 2f 2f 2f 20 20 20 20 20 20 20 75 6e      ///       un
2cd0: 73 69 67 6e 65 64 20 63 68 61 72 20 64 65 73 63  signed char desc
2ce0: 3b 20 20 20 2f 2a 20 54 72 75 65 20 66 6f 72 20  ;   /* True for 
2cf0: 44 45 53 43 2e 20 20 46 61 6c 73 65 20 66 6f 72  DESC.  False for
2d00: 20 41 53 43 2e 20 2a 2f 0d 0a 20 20 20 20 20 20   ASC. */..      
2d10: 20 20 2f 2f 2f 20 20 20 20 7d 20 2a 63 6f 6e 73    ///    } *cons
2d20: 74 20 61 4f 72 64 65 72 42 79 3b 20 20 20 20 20  t aOrderBy;     
2d30: 20 20 2f 2a 20 54 68 65 20 4f 52 44 45 52 20 42    /* The ORDER B
2d40: 59 20 63 6c 61 75 73 65 20 2a 2f 0d 0a 20 20 20  Y clause */..   
2d50: 20 20 20 20 20 2f 2f 2f 20 20 20 20 2f 2a 20 4f       ///    /* O
2d60: 75 74 70 75 74 73 20 2a 2f 0d 0a 20 20 20 20 20  utputs */..     
2d70: 20 20 20 2f 2f 2f 20 20 20 20 73 74 72 75 63 74     ///    struct
2d80: 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63   sqlite3_index_c
2d90: 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20  onstraint_usage 
2da0: 7b 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20  {..        ///  
2db0: 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64 65      int argvInde
2dc0: 78 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 69 66  x;         /* if
2dd0: 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65   greater than ze
2de0: 72 6f 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20 69  ro, constraint i
2df0: 73 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20  s..        ///  
2e00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e10: 20 20 20 20 20 20 20 20 20 20 20 20 2a 20 70 61              * pa
2e20: 72 74 20 6f 66 20 61 72 67 76 20 74 6f 20 78 46  rt of argv to xF
2e30: 69 6c 74 65 72 20 2a 2f 0d 0a 20 20 20 20 20 20  ilter */..      
2e40: 20 20 2f 2f 2f 20 20 20 20 20 20 75 6e 73 69 67    ///      unsig
2e50: 6e 65 64 20 63 68 61 72 20 6f 6d 69 74 3b 20 20  ned char omit;  
2e60: 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65    /* Do not code
2e70: 20 61 20 74 65 73 74 20 66 6f 72 20 74 68 69 73   a test for this
2e80: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20  ..        ///   
2e90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ea0: 20 20 20 20 20 20 20 20 20 20 20 2a 20 63 6f 6e             * con
2eb0: 73 74 72 61 69 6e 74 20 2a 2f 0d 0a 20 20 20 20  straint */..    
2ec0: 20 20 20 20 2f 2f 2f 20 20 20 20 7d 20 2a 63 6f      ///    } *co
2ed0: 6e 73 74 20 61 43 6f 6e 73 74 72 61 69 6e 74 55  nst aConstraintU
2ee0: 73 61 67 65 3b 0d 0a 20 20 20 20 20 20 20 20 2f  sage;..        /
2ef0: 2f 2f 20 20 20 20 69 6e 74 20 69 64 78 4e 75 6d  //    int idxNum
2f00: 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ;              /
2f10: 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f  * Number used to
2f20: 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e   identify the in
2f30: 64 65 78 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20  dex */..        
2f40: 2f 2f 2f 20 20 20 20 63 68 61 72 20 2a 69 64 78  ///    char *idx
2f50: 53 74 72 3b 20 20 20 20 20 20 20 20 20 20 20 20  Str;            
2f60: 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f 73 73 69  /* String, possi
2f70: 62 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  bly obtained fro
2f80: 6d 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20  m..        ///  
2f90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2fa0: 20 20 20 20 20 20 20 20 20 20 20 20 2a 20 73 71              * sq
2fb0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 2a  lite3_malloc() *
2fc0: 2f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20  /..        ///  
2fd0: 20 20 69 6e 74 20 6e 65 65 64 54 6f 46 72 65 65    int needToFree
2fe0: 49 64 78 53 74 72 3b 20 20 20 20 2f 2a 20 46 72  IdxStr;    /* Fr
2ff0: 65 65 20 69 64 78 53 74 72 20 75 73 69 6e 67 20  ee idxStr using 
3000: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
3010: 66 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20  f..        ///  
3020: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3030: 20 20 20 20 20 20 20 20 20 20 20 20 2a 20 74 72              * tr
3040: 75 65 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20 2f  ue */..        /
3050: 2f 2f 20 20 20 20 69 6e 74 20 6f 72 64 65 72 42  //    int orderB
3060: 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 2f  yConsumed;     /
3070: 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70 75 74  * True if output
3080: 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72 64 65   is already orde
3090: 72 65 64 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20  red */..        
30a0: 2f 2f 2f 20 20 20 20 64 6f 75 62 6c 65 20 65 73  ///    double es
30b0: 74 69 6d 61 74 65 64 43 6f 73 74 3b 20 20 20 20  timatedCost;    
30c0: 2f 2a 20 45 73 74 69 6d 61 74 65 64 20 63 6f 73  /* Estimated cos
30d0: 74 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 20  t of using this 
30e0: 69 6e 64 65 78 20 2a 2f 0d 0a 20 20 20 20 20 20  index */..      
30f0: 20 20 2f 2f 2f 20 20 7d 3b 0d 0a 20 20 20 20 20    ///  };..     
3100: 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 0d 0a     /// </code>..
3110: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
3120: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
3130: 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65  In addition, the
3140: 72 65 20 61 72 65 20 73 6f 6d 65 20 64 65 66 69  re are some defi
3150: 6e 65 64 20 63 6f 6e 73 74 61 6e 74 73 3a 0d 0a  ned constants:..
3160: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
3170: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
3180: 20 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20   <code>..       
3190: 20 2f 2f 2f 20 20 23 64 65 66 69 6e 65 20 53 51   ///  #define SQ
31a0: 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
31b0: 52 41 49 4e 54 5f 45 51 20 20 20 20 32 0d 0a 20  RAINT_EQ    2.. 
31c0: 20 20 20 20 20 20 20 2f 2f 2f 20 20 23 64 65 66         ///  #def
31d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
31e0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20  _CONSTRAINT_GT  
31f0: 20 20 34 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f    4..        ///
3200: 20 20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45    #define SQLITE
3210: 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
3220: 54 5f 4c 45 20 20 20 20 38 0d 0a 20 20 20 20 20  T_LE    8..     
3230: 20 20 20 2f 2f 2f 20 20 23 64 65 66 69 6e 65 20     ///  #define 
3240: 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
3250: 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 20 31 36  STRAINT_LT    16
3260: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 23  ..        ///  #
3270: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
3280: 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47  DEX_CONSTRAINT_G
3290: 45 20 20 20 20 33 32 0d 0a 20 20 20 20 20 20 20  E    32..       
32a0: 20 2f 2f 2f 20 20 23 64 65 66 69 6e 65 20 53 51   ///  #define SQ
32b0: 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
32c0: 52 41 49 4e 54 5f 4d 41 54 43 48 20 36 34 0d 0a  RAINT_MATCH 64..
32d0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f          /// </co
32e0: 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  de>..        ///
32f0: 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20   <para>..       
3300: 20 2f 2f 2f 20 54 68 65 20 53 51 4c 69 74 65 20   /// The SQLite 
3310: 63 6f 72 65 20 63 61 6c 6c 73 20 74 68 65 20 78  core calls the x
3320: 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64  BestIndex method
3330: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70   when it is comp
3340: 69 6c 69 6e 67 20 61 0d 0a 20 20 20 20 20 20 20  iling a..       
3350: 20 2f 2f 2f 20 71 75 65 72 79 20 74 68 61 74 20   /// query that 
3360: 69 6e 76 6f 6c 76 65 73 20 61 20 76 69 72 74 75  involves a virtu
3370: 61 6c 20 74 61 62 6c 65 2e 20 49 6e 20 6f 74 68  al table. In oth
3380: 65 72 20 77 6f 72 64 73 2c 20 53 51 4c 69 74 65  er words, SQLite
3390: 20 63 61 6c 6c 73 0d 0a 20 20 20 20 20 20 20 20   calls..        
33a0: 2f 2f 2f 20 74 68 69 73 20 6d 65 74 68 6f 64 20  /// this method 
33b0: 77 68 65 6e 20 69 74 20 69 73 20 72 75 6e 6e 69  when it is runni
33c0: 6e 67 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ng sqlite3_prepa
33d0: 72 65 28 29 20 6f 72 20 74 68 65 20 65 71 75 69  re() or the equi
33e0: 76 61 6c 65 6e 74 2e 0d 0a 20 20 20 20 20 20 20  valent...       
33f0: 20 2f 2f 2f 20 42 79 20 63 61 6c 6c 69 6e 67 20   /// By calling 
3400: 74 68 69 73 20 6d 65 74 68 6f 64 2c 20 74 68 65  this method, the
3410: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 69 73 20   SQLite core is 
3420: 73 61 79 69 6e 67 20 74 6f 20 74 68 65 20 76 69  saying to the vi
3430: 72 74 75 61 6c 0d 0a 20 20 20 20 20 20 20 20 2f  rtual..        /
3440: 2f 2f 20 74 61 62 6c 65 20 74 68 61 74 20 69 74  // table that it
3450: 20 6e 65 65 64 73 20 74 6f 20 61 63 63 65 73 73   needs to access
3460: 20 73 6f 6d 65 20 73 75 62 73 65 74 20 6f 66 20   some subset of 
3470: 74 68 65 20 72 6f 77 73 20 69 6e 20 74 68 65 0d  the rows in the.
3480: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 76 69 72  .        /// vir
3490: 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 69  tual table and i
34a0: 74 20 77 61 6e 74 73 20 74 6f 20 6b 6e 6f 77 20  t wants to know 
34b0: 74 68 65 20 6d 6f 73 74 20 65 66 66 69 63 69 65  the most efficie
34c0: 6e 74 20 77 61 79 20 74 6f 20 64 6f 0d 0a 20 20  nt way to do..  
34d0: 20 20 20 20 20 20 2f 2f 2f 20 74 68 61 74 20 61        /// that a
34e0: 63 63 65 73 73 2e 20 54 68 65 20 78 42 65 73 74  ccess. The xBest
34f0: 49 6e 64 65 78 20 6d 65 74 68 6f 64 20 72 65 70  Index method rep
3500: 6c 69 65 73 20 77 69 74 68 20 69 6e 66 6f 72 6d  lies with inform
3510: 61 74 69 6f 6e 20 74 68 61 74 0d 0a 20 20 20 20  ation that..    
3520: 20 20 20 20 2f 2f 2f 20 74 68 65 20 53 51 4c 69      /// the SQLi
3530: 74 65 20 63 6f 72 65 20 63 61 6e 20 74 68 65 6e  te core can then
3540: 20 75 73 65 20 74 6f 20 63 6f 6e 64 75 63 74 20   use to conduct 
3550: 61 6e 20 65 66 66 69 63 69 65 6e 74 20 73 65 61  an efficient sea
3560: 72 63 68 20 6f 66 20 74 68 65 0d 0a 20 20 20 20  rch of the..    
3570: 20 20 20 20 2f 2f 2f 20 76 69 72 74 75 61 6c 20      /// virtual 
3580: 74 61 62 6c 65 2e 0d 0a 20 20 20 20 20 20 20 20  table...        
3590: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
35a0: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
35b0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 57 68 69  .        /// Whi
35c0: 6c 65 20 63 6f 6d 70 69 6c 69 6e 67 20 61 20 73  le compiling a s
35d0: 69 6e 67 6c 65 20 53 51 4c 20 71 75 65 72 79 2c  ingle SQL query,
35e0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
35f0: 20 6d 69 67 68 74 20 63 61 6c 6c 0d 0a 20 20 20   might call..   
3600: 20 20 20 20 20 2f 2f 2f 20 78 42 65 73 74 49 6e       /// xBestIn
3610: 64 65 78 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  dex multiple tim
3620: 65 73 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  es with differen
3630: 74 20 73 65 74 74 69 6e 67 73 20 69 6e 0d 0a 20  t settings in.. 
3640: 20 20 20 20 20 20 20 2f 2f 2f 20 73 71 6c 69 74         /// sqlit
3650: 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2e 20 54  e3_index_info. T
3660: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77  he SQLite core w
3670: 69 6c 6c 20 74 68 65 6e 20 73 65 6c 65 63 74 20  ill then select 
3680: 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  the..        ///
3690: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 74 68 61   combination tha
36a0: 74 20 61 70 70 65 61 72 73 20 74 6f 20 67 69 76  t appears to giv
36b0: 65 20 74 68 65 20 62 65 73 74 20 70 65 72 66 6f  e the best perfo
36c0: 72 6d 61 6e 63 65 2e 0d 0a 20 20 20 20 20 20 20  rmance...       
36d0: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
36e0: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
36f0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 42 65  ..        /// Be
3700: 66 6f 72 65 20 63 61 6c 6c 69 6e 67 20 74 68 69  fore calling thi
3710: 73 20 6d 65 74 68 6f 64 2c 20 74 68 65 20 53 51  s method, the SQ
3720: 4c 69 74 65 20 63 6f 72 65 20 69 6e 69 74 69 61  Lite core initia
3730: 6c 69 7a 65 73 20 61 6e 20 69 6e 73 74 61 6e 63  lizes an instanc
3740: 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6f  e..        /// o
3750: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  f the sqlite3_in
3760: 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75  dex_info structu
3770: 72 65 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74  re with informat
3780: 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 0d 0a 20  ion about the.. 
3790: 20 20 20 20 20 20 20 2f 2f 2f 20 71 75 65 72 79         /// query
37a0: 20 74 68 61 74 20 69 74 20 69 73 20 63 75 72 72   that it is curr
37b0: 65 6e 74 6c 79 20 74 72 79 69 6e 67 20 74 6f 20  ently trying to 
37c0: 70 72 6f 63 65 73 73 2e 20 54 68 69 73 20 69 6e  process. This in
37d0: 66 6f 72 6d 61 74 69 6f 6e 0d 0a 20 20 20 20 20  formation..     
37e0: 20 20 20 2f 2f 2f 20 64 65 72 69 76 65 73 20 6d     /// derives m
37f0: 61 69 6e 6c 79 20 66 72 6f 6d 20 74 68 65 20 57  ainly from the W
3800: 48 45 52 45 20 63 6c 61 75 73 65 20 61 6e 64 20  HERE clause and 
3810: 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55  ORDER BY or GROU
3820: 50 20 42 59 0d 0a 20 20 20 20 20 20 20 20 2f 2f  P BY..        //
3830: 2f 20 63 6c 61 75 73 65 73 20 6f 66 20 74 68 65  / clauses of the
3840: 20 71 75 65 72 79 2c 20 62 75 74 20 61 6c 73 6f   query, but also
3850: 20 66 72 6f 6d 20 61 6e 79 20 4f 4e 20 6f 72 20   from any ON or 
3860: 55 53 49 4e 47 20 63 6c 61 75 73 65 73 20 69 66  USING clauses if
3870: 20 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f   the..        //
3880: 2f 20 71 75 65 72 79 20 69 73 20 61 20 6a 6f 69  / query is a joi
3890: 6e 2e 20 54 68 65 20 69 6e 66 6f 72 6d 61 74 69  n. The informati
38a0: 6f 6e 20 74 68 61 74 20 74 68 65 20 53 51 4c 69  on that the SQLi
38b0: 74 65 20 63 6f 72 65 20 70 72 6f 76 69 64 65 73  te core provides
38c0: 20 74 6f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f   to..        ///
38d0: 20 74 68 65 20 78 42 65 73 74 49 6e 64 65 78 20   the xBestIndex 
38e0: 6d 65 74 68 6f 64 20 69 73 20 68 65 6c 64 20 69  method is held i
38f0: 6e 20 74 68 65 20 70 61 72 74 20 6f 66 20 74 68  n the part of th
3900: 65 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74  e structure that
3910: 20 69 73 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f   is..        ///
3920: 20 6d 61 72 6b 65 64 20 61 73 20 22 49 6e 70 75   marked as "Inpu
3930: 74 73 22 2e 20 54 68 65 20 22 4f 75 74 70 75 74  ts". The "Output
3940: 73 22 20 73 65 63 74 69 6f 6e 20 69 73 20 69 6e  s" section is in
3950: 69 74 69 61 6c 69 7a 65 64 20 74 6f 20 7a 65 72  itialized to zer
3960: 6f 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  o...        /// 
3970: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
3980: 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20   /// <para>..   
3990: 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 69 6e 66       /// The inf
39a0: 6f 72 6d 61 74 69 6f 6e 20 69 6e 20 74 68 65 20  ormation in the 
39b0: 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
39c0: 66 6f 20 73 74 72 75 63 74 75 72 65 20 69 73 20  fo structure is 
39d0: 65 70 68 65 6d 65 72 61 6c 0d 0a 20 20 20 20 20  ephemeral..     
39e0: 20 20 20 2f 2f 2f 20 61 6e 64 20 6d 61 79 20 62     /// and may b
39f0: 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72  e overwritten or
3a00: 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 73 20   deallocated as 
3a10: 73 6f 6f 6e 20 61 73 20 74 68 65 20 78 42 65 73  soon as the xBes
3a20: 74 49 6e 64 65 78 0d 0a 20 20 20 20 20 20 20 20  tIndex..        
3a30: 2f 2f 2f 20 6d 65 74 68 6f 64 20 72 65 74 75 72  /// method retur
3a40: 6e 73 2e 20 49 66 20 74 68 65 20 78 42 65 73 74  ns. If the xBest
3a50: 49 6e 64 65 78 20 6d 65 74 68 6f 64 20 6e 65 65  Index method nee
3a60: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 61  ds to remember a
3a70: 6e 79 20 70 61 72 74 0d 0a 20 20 20 20 20 20 20  ny part..       
3a80: 20 2f 2f 2f 20 6f 66 20 74 68 65 20 73 71 6c 69   /// of the sqli
3a90: 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73  te3_index_info s
3aa0: 74 72 75 63 74 75 72 65 2c 20 69 74 20 73 68 6f  tructure, it sho
3ab0: 75 6c 64 20 6d 61 6b 65 20 61 20 63 6f 70 79 2e  uld make a copy.
3ac0: 20 43 61 72 65 0d 0a 20 20 20 20 20 20 20 20 2f   Care..        /
3ad0: 2f 2f 20 6d 75 73 74 20 62 65 20 74 61 6b 65 20  // must be take 
3ae0: 74 6f 20 73 74 6f 72 65 20 74 68 65 20 63 6f 70  to store the cop
3af0: 79 20 69 6e 20 61 20 70 6c 61 63 65 20 77 68 65  y in a place whe
3b00: 72 65 20 69 74 20 77 69 6c 6c 20 62 65 0d 0a 20  re it will be.. 
3b10: 20 20 20 20 20 20 20 2f 2f 2f 20 64 65 61 6c 6c         /// deall
3b20: 6f 63 61 74 65 64 2c 20 73 75 63 68 20 61 73 20  ocated, such as 
3b30: 69 6e 20 74 68 65 20 69 64 78 53 74 72 20 66 69  in the idxStr fi
3b40: 65 6c 64 20 77 69 74 68 20 6e 65 65 64 54 6f 46  eld with needToF
3b50: 72 65 65 49 64 78 53 74 72 20 73 65 74 0d 0a 20  reeIdxStr set.. 
3b60: 20 20 20 20 20 20 20 2f 2f 2f 20 74 6f 20 31 2e         /// to 1.
3b70: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
3b80: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
3b90: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20  // <para>..     
3ba0: 20 20 20 2f 2f 2f 20 4e 6f 74 65 20 74 68 61 74     /// Note that
3bb0: 20 78 42 65 73 74 49 6e 64 65 78 20 77 69 6c 6c   xBestIndex will
3bc0: 20 61 6c 77 61 79 73 20 62 65 20 63 61 6c 6c 65   always be calle
3bd0: 64 20 62 65 66 6f 72 65 20 78 46 69 6c 74 65 72  d before xFilter
3be0: 2c 20 73 69 6e 63 65 0d 0a 20 20 20 20 20 20 20  , since..       
3bf0: 20 2f 2f 2f 20 74 68 65 20 69 64 78 4e 75 6d 20   /// the idxNum 
3c00: 61 6e 64 20 69 64 78 53 74 72 20 6f 75 74 70 75  and idxStr outpu
3c10: 74 73 20 66 72 6f 6d 20 78 42 65 73 74 49 6e 64  ts from xBestInd
3c20: 65 78 20 61 72 65 20 72 65 71 75 69 72 65 64 20  ex are required 
3c30: 69 6e 70 75 74 73 0d 0a 20 20 20 20 20 20 20 20  inputs..        
3c40: 2f 2f 2f 20 74 6f 20 78 46 69 6c 74 65 72 2e 20  /// to xFilter. 
3c50: 48 6f 77 65 76 65 72 2c 20 74 68 65 72 65 20 69  However, there i
3c60: 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74  s no guarantee t
3c70: 68 61 74 20 78 46 69 6c 74 65 72 20 77 69 6c 6c  hat xFilter will
3c80: 20 62 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f   be..        ///
3c90: 20 63 61 6c 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e   called followin
3ca0: 67 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 78  g a successful x
3cb0: 42 65 73 74 49 6e 64 65 78 2e 0d 0a 20 20 20 20  BestIndex...    
3cc0: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
3cd0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
3ce0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
3cf0: 20 54 68 65 20 78 42 65 73 74 49 6e 64 65 78 20   The xBestIndex 
3d00: 6d 65 74 68 6f 64 20 69 73 20 72 65 71 75 69 72  method is requir
3d10: 65 64 20 66 6f 72 20 65 76 65 72 79 20 76 69 72  ed for every vir
3d20: 74 75 61 6c 20 74 61 62 6c 65 0d 0a 20 20 20 20  tual table..    
3d30: 20 20 20 20 2f 2f 2f 20 69 6d 70 6c 65 6d 65 6e      /// implemen
3d40: 74 61 74 69 6f 6e 2e 0d 0a 20 20 20 20 20 20 20  tation...       
3d50: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
3d60: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
3d70: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 32 2e  ..        /// 2.
3d80: 33 2e 31 20 49 6e 70 75 74 73 0d 0a 20 20 20 20  3.1 Inputs..    
3d90: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
3da0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
3db0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
3dc0: 20 54 68 65 20 6d 61 69 6e 20 74 68 69 6e 67 20   The main thing 
3dd0: 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65 20  that the SQLite 
3de0: 63 6f 72 65 20 69 73 20 74 72 79 69 6e 67 20 74  core is trying t
3df0: 6f 20 63 6f 6d 6d 75 6e 69 63 61 74 65 20 74 6f  o communicate to
3e00: 20 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f   the..        //
3e10: 2f 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  / virtual table 
3e20: 69 73 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  is the constrain
3e30: 74 73 20 74 68 61 74 20 61 72 65 20 61 76 61 69  ts that are avai
3e40: 6c 61 62 6c 65 20 74 6f 20 6c 69 6d 69 74 20 74  lable to limit t
3e50: 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  he..        /// 
3e60: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 74  number of rows t
3e70: 68 61 74 20 6e 65 65 64 20 74 6f 20 62 65 20 73  hat need to be s
3e80: 65 61 72 63 68 65 64 2e 20 54 68 65 20 61 43 6f  earched. The aCo
3e90: 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79  nstraint[] array
3ea0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 63 6f  ..        /// co
3eb0: 6e 74 61 69 6e 73 20 6f 6e 65 20 65 6e 74 72 79  ntains one entry
3ec0: 20 66 6f 72 20 65 61 63 68 20 63 6f 6e 73 74 72   for each constr
3ed0: 61 69 6e 74 2e 20 54 68 65 72 65 20 77 69 6c 6c  aint. There will
3ee0: 20 62 65 20 65 78 61 63 74 6c 79 0d 0a 20 20 20   be exactly..   
3ef0: 20 20 20 20 20 2f 2f 2f 20 6e 43 6f 6e 73 74 72       /// nConstr
3f00: 61 69 6e 74 20 65 6e 74 72 69 65 73 20 69 6e 20  aint entries in 
3f10: 74 68 61 74 20 61 72 72 61 79 2e 0d 0a 20 20 20  that array...   
3f20: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e       /// </para>
3f30: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
3f40: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
3f50: 2f 20 45 61 63 68 20 63 6f 6e 73 74 72 61 69 6e  / Each constrain
3f60: 74 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e  t will correspon
3f70: 64 20 74 6f 20 61 20 74 65 72 6d 20 69 6e 20 74  d to a term in t
3f80: 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  he WHERE clause 
3f90: 6f 72 20 69 6e 0d 0a 20 20 20 20 20 20 20 20 2f  or in..        /
3fa0: 2f 2f 20 61 20 55 53 49 4e 47 20 6f 72 20 4f 4e  // a USING or ON
3fb0: 20 63 6c 61 75 73 65 20 74 68 61 74 20 69 73 20   clause that is 
3fc0: 6f 66 20 74 68 65 20 66 6f 72 6d 0d 0a 20 20 20  of the form..   
3fd0: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e       /// </para>
3fe0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 63  ..        /// <c
3ff0: 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ode>..        //
4000: 2f 20 20 20 20 20 63 6f 6c 75 6d 6e 20 4f 50 20  /     column OP 
4010: 45 58 50 52 0d 0a 20 20 20 20 20 20 20 20 2f 2f  EXPR..        //
4020: 2f 20 3c 2f 63 6f 64 65 3e 0d 0a 20 20 20 20 20  / </code>..     
4030: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20     /// <para>.. 
4040: 20 20 20 20 20 20 20 2f 2f 2f 20 57 68 65 72 65         /// Where
4050: 20 22 63 6f 6c 75 6d 6e 22 20 69 73 20 61 20 63   "column" is a c
4060: 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 76 69 72  olumn in the vir
4070: 74 75 61 6c 20 74 61 62 6c 65 2c 20 4f 50 20 69  tual table, OP i
4080: 73 20 61 6e 20 6f 70 65 72 61 74 6f 72 0d 0a 20  s an operator.. 
4090: 20 20 20 20 20 20 20 2f 2f 2f 20 6c 69 6b 65 20         /// like 
40a0: 22 3d 22 20 6f 72 20 22 26 6c 74 3b 22 2c 20 61  "=" or "&lt;", a
40b0: 6e 64 20 45 58 50 52 20 69 73 20 61 6e 20 61 72  nd EXPR is an ar
40c0: 62 69 74 72 61 72 79 20 65 78 70 72 65 73 73 69  bitrary expressi
40d0: 6f 6e 2e 20 53 6f 2c 20 66 6f 72 0d 0a 20 20 20  on. So, for..   
40e0: 20 20 20 20 20 2f 2f 2f 20 65 78 61 6d 70 6c 65       /// example
40f0: 2c 20 69 66 20 74 68 65 20 57 48 45 52 45 20 63  , if the WHERE c
4100: 6c 61 75 73 65 20 63 6f 6e 74 61 69 6e 65 64 20  lause contained 
4110: 61 20 74 65 72 6d 20 6c 69 6b 65 20 74 68 69 73  a term like this
4120: 3a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  :..        /// <
4130: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
4140: 2f 2f 2f 20 3c 63 6f 64 65 3e 0d 0a 20 20 20 20  /// <code>..    
4150: 20 20 20 20 2f 2f 2f 20 20 20 20 20 20 20 20 20      ///         
4160: 20 61 20 3d 20 35 0d 0a 20 20 20 20 20 20 20 20   a = 5..        
4170: 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 0d 0a 20 20 20  /// </code>..   
4180: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
4190: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65  .        /// The
41a0: 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e  n one of the con
41b0: 73 74 72 61 69 6e 74 73 20 77 6f 75 6c 64 20 62  straints would b
41c0: 65 20 6f 6e 20 74 68 65 20 22 61 22 20 63 6f 6c  e on the "a" col
41d0: 75 6d 6e 20 77 69 74 68 0d 0a 20 20 20 20 20 20  umn with..      
41e0: 20 20 2f 2f 2f 20 6f 70 65 72 61 74 6f 72 20 22    /// operator "
41f0: 3d 22 20 61 6e 64 20 61 6e 20 65 78 70 72 65 73  =" and an expres
4200: 73 69 6f 6e 20 6f 66 20 22 35 22 2e 20 43 6f 6e  sion of "5". Con
4210: 73 74 72 61 69 6e 74 73 20 6e 65 65 64 20 6e 6f  straints need no
4220: 74 20 68 61 76 65 20 61 0d 0a 20 20 20 20 20 20  t have a..      
4230: 20 20 2f 2f 2f 20 6c 69 74 65 72 61 6c 20 72 65    /// literal re
4240: 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20  presentation of 
4250: 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65  the WHERE clause
4260: 2e 20 54 68 65 20 71 75 65 72 79 20 6f 70 74 69  . The query opti
4270: 6d 69 7a 65 72 0d 0a 20 20 20 20 20 20 20 20 2f  mizer..        /
4280: 2f 2f 20 6d 69 67 68 74 20 6d 61 6b 65 20 74 72  // might make tr
4290: 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 73 20 74 6f  ansformations to
42a0: 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 73   the WHERE claus
42b0: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 78  e in order to ex
42c0: 74 72 61 63 74 0d 0a 20 20 20 20 20 20 20 20 2f  tract..        /
42d0: 2f 2f 20 61 73 20 6d 61 6e 79 20 63 6f 6e 73 74  // as many const
42e0: 72 61 69 6e 74 73 20 61 73 20 69 74 20 63 61 6e  raints as it can
42f0: 2e 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c  . So, for exampl
4300: 65 2c 20 69 66 20 74 68 65 20 57 48 45 52 45 20  e, if the WHERE 
4310: 63 6c 61 75 73 65 0d 0a 20 20 20 20 20 20 20 20  clause..        
4320: 2f 2f 2f 20 63 6f 6e 74 61 69 6e 65 64 20 73 6f  /// contained so
4330: 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69  mething like thi
4340: 73 3a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  s:..        /// 
4350: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
4360: 20 2f 2f 2f 20 3c 63 6f 64 65 3e 0d 0a 20 20 20   /// <code>..   
4370: 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 20 20 20       ///        
4380: 20 20 78 20 42 45 54 57 45 45 4e 20 31 30 20 41    x BETWEEN 10 A
4390: 4e 44 20 31 30 30 20 41 4e 44 20 39 39 39 26 67  ND 100 AND 999&g
43a0: 74 3b 79 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  t;y..        ///
43b0: 20 3c 2f 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20   </code>..      
43c0: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
43d0: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 71 75        /// The qu
43e0: 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 20 6d 69  ery optimizer mi
43f0: 67 68 74 20 74 72 61 6e 73 6c 61 74 65 20 74 68  ght translate th
4400: 69 73 20 69 6e 74 6f 20 74 68 72 65 65 20 73 65  is into three se
4410: 70 61 72 61 74 65 0d 0a 20 20 20 20 20 20 20 20  parate..        
4420: 2f 2f 2f 20 63 6f 6e 73 74 72 61 69 6e 74 73 3a  /// constraints:
4430: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
4440: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
4450: 2f 2f 20 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20  // <code>..     
4460: 20 20 20 2f 2f 2f 20 20 20 20 20 20 20 20 20 20     ///          
4470: 78 20 26 67 74 3b 3d 20 31 30 0d 0a 20 20 20 20  x &gt;= 10..    
4480: 20 20 20 20 2f 2f 2f 20 20 20 20 20 20 20 20 20      ///         
4490: 20 78 20 26 6c 74 3b 3d 20 31 30 30 0d 0a 20 20   x &lt;= 100..  
44a0: 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 20 20        ///       
44b0: 20 20 20 79 20 26 6c 74 3b 20 39 39 39 0d 0a 20     y &lt; 999.. 
44c0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64         /// </cod
44d0: 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e>..        /// 
44e0: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
44f0: 2f 2f 2f 20 46 6f 72 20 65 61 63 68 20 63 6f 6e  /// For each con
4500: 73 74 72 61 69 6e 74 2c 20 74 68 65 20 61 43 6f  straint, the aCo
4510: 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75  nstraint[].iColu
4520: 6d 6e 20 66 69 65 6c 64 20 69 6e 64 69 63 61 74  mn field indicat
4530: 65 73 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  es..        /// 
4540: 77 68 69 63 68 20 63 6f 6c 75 6d 6e 20 61 70 70  which column app
4550: 65 61 72 73 20 6f 6e 20 74 68 65 20 6c 65 66 74  ears on the left
4560: 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68  -hand side of th
4570: 65 20 63 6f 6e 73 74 72 61 69 6e 74 2e 20 54 68  e constraint. Th
4580: 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 66  e..        /// f
4590: 69 72 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  irst column of t
45a0: 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
45b0: 20 69 73 20 63 6f 6c 75 6d 6e 20 30 2e 20 54 68   is column 0. Th
45c0: 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 0d 0a  e rowid of the..
45d0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 76 69 72 74          /// virt
45e0: 75 61 6c 20 74 61 62 6c 65 20 69 73 20 63 6f 6c  ual table is col
45f0: 75 6d 6e 20 2d 31 2e 20 54 68 65 20 61 43 6f 6e  umn -1. The aCon
4600: 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 20 66 69 65  straint[].op fie
4610: 6c 64 20 69 6e 64 69 63 61 74 65 73 0d 0a 20 20  ld indicates..  
4620: 20 20 20 20 20 20 2f 2f 2f 20 77 68 69 63 68 20        /// which 
4630: 6f 70 65 72 61 74 6f 72 20 69 73 20 75 73 65 64  operator is used
4640: 2e 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4e 44  . The SQLITE_IND
4650: 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 2a 20  EX_CONSTRAINT_* 
4660: 63 6f 6e 73 74 61 6e 74 73 20 6d 61 70 0d 0a 20  constants map.. 
4670: 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e 74 65 67         /// integ
4680: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 74  er constants int
4690: 6f 20 6f 70 65 72 61 74 6f 72 20 76 61 6c 75 65  o operator value
46a0: 73 2e 20 43 6f 6c 75 6d 6e 73 20 6f 63 63 75 72  s. Columns occur
46b0: 20 69 6e 20 74 68 65 20 6f 72 64 65 72 0d 0a 20   in the order.. 
46c0: 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 79 20         /// they 
46d0: 77 65 72 65 20 64 65 66 69 6e 65 64 20 62 79 20  were defined by 
46e0: 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  the call to sqli
46f0: 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62  te3_declare_vtab
4700: 28 29 20 69 6e 20 74 68 65 0d 0a 20 20 20 20 20  () in the..     
4710: 20 20 20 2f 2f 2f 20 78 43 72 65 61 74 65 20 6f     /// xCreate o
4720: 72 20 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68 6f  r xConnect metho
4730: 64 2e 20 48 69 64 64 65 6e 20 63 6f 6c 75 6d 6e  d. Hidden column
4740: 73 20 61 72 65 20 63 6f 75 6e 74 65 64 20 77 68  s are counted wh
4750: 65 6e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  en..        /// 
4760: 64 65 74 65 72 6d 69 6e 69 6e 67 20 74 68 65 20  determining the 
4770: 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 2e 0d 0a 20  column index... 
4780: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
4790: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
47a0: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
47b0: 2f 2f 2f 20 54 68 65 20 61 43 6f 6e 73 74 72 61  /// The aConstra
47c0: 69 6e 74 5b 5d 20 61 72 72 61 79 20 63 6f 6e 74  int[] array cont
47d0: 61 69 6e 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  ains information
47e0: 20 61 62 6f 75 74 20 61 6c 6c 20 63 6f 6e 73 74   about all const
47f0: 72 61 69 6e 74 73 0d 0a 20 20 20 20 20 20 20 20  raints..        
4800: 2f 2f 2f 20 74 68 61 74 20 61 70 70 6c 79 20 74  /// that apply t
4810: 6f 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  o the virtual ta
4820: 62 6c 65 2e 20 42 75 74 20 73 6f 6d 65 20 6f 66  ble. But some of
4830: 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 73   the constraints
4840: 20 6d 69 67 68 74 0d 0a 20 20 20 20 20 20 20 20   might..        
4850: 2f 2f 2f 20 6e 6f 74 20 62 65 20 75 73 61 62 6c  /// not be usabl
4860: 65 20 62 65 63 61 75 73 65 20 6f 66 20 74 68 65  e because of the
4870: 20 77 61 79 20 74 61 62 6c 65 73 20 61 72 65 20   way tables are 
4880: 6f 72 64 65 72 65 64 20 69 6e 20 61 20 6a 6f 69  ordered in a joi
4890: 6e 2e 20 54 68 65 0d 0a 20 20 20 20 20 20 20 20  n. The..        
48a0: 2f 2f 2f 20 78 42 65 73 74 49 6e 64 65 78 20 6d  /// xBestIndex m
48b0: 65 74 68 6f 64 20 6d 75 73 74 20 74 68 65 72 65  ethod must there
48c0: 66 6f 72 65 20 6f 6e 6c 79 20 63 6f 6e 73 69 64  fore only consid
48d0: 65 72 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 74  er constraints t
48e0: 68 61 74 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  hat..        ///
48f0: 20 68 61 76 65 20 61 6e 20 61 43 6f 6e 73 74 72   have an aConstr
4900: 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 66 6c  aint[].usable fl
4910: 61 67 20 77 68 69 63 68 20 69 73 20 74 72 75 65  ag which is true
4920: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
4930: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
4940: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20  /// <para>..    
4950: 20 20 20 20 2f 2f 2f 20 49 6e 20 61 64 64 69 74      /// In addit
4960: 69 6f 6e 20 74 6f 20 57 48 45 52 45 20 63 6c 61  ion to WHERE cla
4970: 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c  use constraints,
4980: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
4990: 20 61 6c 73 6f 20 74 65 6c 6c 73 0d 0a 20 20 20   also tells..   
49a0: 20 20 20 20 20 2f 2f 2f 20 74 68 65 20 78 42 65       /// the xBe
49b0: 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64 20 61  stIndex method a
49c0: 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52 20 42  bout the ORDER B
49d0: 59 20 63 6c 61 75 73 65 2e 20 28 49 6e 20 61 6e  Y clause. (In an
49e0: 20 61 67 67 72 65 67 61 74 65 0d 0a 20 20 20 20   aggregate..    
49f0: 20 20 20 20 2f 2f 2f 20 71 75 65 72 79 2c 20 74      /// query, t
4a00: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6d  he SQLite core m
4a10: 69 67 68 74 20 70 75 74 20 69 6e 20 47 52 4f 55  ight put in GROU
4a20: 50 20 42 59 20 63 6c 61 75 73 65 20 69 6e 66 6f  P BY clause info
4a30: 72 6d 61 74 69 6f 6e 20 69 6e 0d 0a 20 20 20 20  rmation in..    
4a40: 20 20 20 20 2f 2f 2f 20 70 6c 61 63 65 20 6f 66      /// place of
4a50: 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
4a60: 61 75 73 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  ause information
4a70: 2c 20 62 75 74 20 74 68 69 73 20 66 61 63 74 20  , but this fact 
4a80: 73 68 6f 75 6c 64 20 6e 6f 74 0d 0a 20 20 20 20  should not..    
4a90: 20 20 20 20 2f 2f 2f 20 6d 61 6b 65 20 61 6e 79      /// make any
4aa0: 20 64 69 66 66 65 72 65 6e 63 65 20 74 6f 20 74   difference to t
4ab0: 68 65 20 78 42 65 73 74 49 6e 64 65 78 20 6d 65  he xBestIndex me
4ac0: 74 68 6f 64 2e 29 20 49 66 20 61 6c 6c 20 74 65  thod.) If all te
4ad0: 72 6d 73 20 6f 66 20 74 68 65 0d 0a 20 20 20 20  rms of the..    
4ae0: 20 20 20 20 2f 2f 2f 20 4f 52 44 45 52 20 42 59      /// ORDER BY
4af0: 20 63 6c 61 75 73 65 20 61 72 65 20 63 6f 6c 75   clause are colu
4b00: 6d 6e 73 20 69 6e 20 74 68 65 20 76 69 72 74 75  mns in the virtu
4b10: 61 6c 20 74 61 62 6c 65 2c 20 74 68 65 6e 20 6e  al table, then n
4b20: 4f 72 64 65 72 42 79 0d 0a 20 20 20 20 20 20 20  OrderBy..       
4b30: 20 2f 2f 2f 20 77 69 6c 6c 20 62 65 20 74 68 65   /// will be the
4b40: 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   number of terms
4b50: 20 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59   in the ORDER BY
4b60: 20 63 6c 61 75 73 65 20 61 6e 64 20 74 68 65 0d   clause and the.
4b70: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 61 4f 72  .        /// aOr
4b80: 64 65 72 42 79 5b 5d 20 61 72 72 61 79 20 77 69  derBy[] array wi
4b90: 6c 6c 20 69 64 65 6e 74 69 66 79 20 74 68 65 20  ll identify the 
4ba0: 63 6f 6c 75 6d 6e 20 66 6f 72 20 65 61 63 68 20  column for each 
4bb0: 74 65 72 6d 20 69 6e 20 74 68 65 0d 0a 20 20 20  term in the..   
4bc0: 20 20 20 20 20 2f 2f 2f 20 6f 72 64 65 72 20 62       /// order b
4bd0: 79 20 63 6c 61 75 73 65 20 61 6e 64 20 77 68 65  y clause and whe
4be0: 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 61 74  ther or not that
4bf0: 20 63 6f 6c 75 6d 6e 20 69 73 20 41 53 43 20 6f   column is ASC o
4c00: 72 20 44 45 53 43 2e 0d 0a 20 20 20 20 20 20 20  r DESC...       
4c10: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
4c20: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
4c30: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 32 2e  ..        /// 2.
4c40: 33 2e 32 20 4f 75 74 70 75 74 73 0d 0a 20 20 20  3.2 Outputs..   
4c50: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e       /// </para>
4c60: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
4c70: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
4c80: 2f 20 47 69 76 65 6e 20 61 6c 6c 20 6f 66 20 74  / Given all of t
4c90: 68 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  he information a
4ca0: 62 6f 76 65 2c 20 74 68 65 20 6a 6f 62 20 6f 66  bove, the job of
4cb0: 20 74 68 65 20 78 42 65 73 74 49 6e 64 65 78 0d   the xBestIndex.
4cc0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6d 65 74  .        /// met
4cd0: 68 6f 64 20 69 74 20 74 6f 20 66 69 67 75 72 65  hod it to figure
4ce0: 20 6f 75 74 20 74 68 65 20 62 65 73 74 20 77 61   out the best wa
4cf0: 79 20 74 6f 20 73 65 61 72 63 68 20 74 68 65 20  y to search the 
4d00: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 0d 0a  virtual table...
4d10: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
4d20: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
4d30: 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20   <para>..       
4d40: 20 2f 2f 2f 20 54 68 65 20 78 42 65 73 74 49 6e   /// The xBestIn
4d50: 64 65 78 20 6d 65 74 68 6f 64 20 66 69 6c 6c 73  dex method fills
4d60: 20 74 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20   the idxNum and 
4d70: 69 64 78 53 74 72 20 66 69 65 6c 64 73 20 77 69  idxStr fields wi
4d80: 74 68 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  th..        /// 
4d90: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 74 68 61 74  information that
4da0: 20 63 6f 6d 6d 75 6e 69 63 61 74 65 73 20 61 6e   communicates an
4db0: 20 69 6e 64 65 78 69 6e 67 20 73 74 72 61 74 65   indexing strate
4dc0: 67 79 20 74 6f 20 74 68 65 20 78 46 69 6c 74 65  gy to the xFilte
4dd0: 72 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6d  r..        /// m
4de0: 65 74 68 6f 64 2e 20 54 68 65 20 69 6e 66 6f 72  ethod. The infor
4df0: 6d 61 74 69 6f 6e 20 69 6e 20 69 64 78 4e 75 6d  mation in idxNum
4e00: 20 61 6e 64 20 69 64 78 53 74 72 20 69 73 20 61   and idxStr is a
4e10: 72 62 69 74 72 61 72 79 20 61 73 20 66 61 72 20  rbitrary as far 
4e20: 61 73 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  as..        /// 
4e30: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  the SQLite core 
4e40: 69 73 20 63 6f 6e 63 65 72 6e 65 64 2e 20 54 68  is concerned. Th
4e50: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6a 75  e SQLite core ju
4e60: 73 74 20 63 6f 70 69 65 73 20 74 68 65 0d 0a 20  st copies the.. 
4e70: 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e 66 6f 72         /// infor
4e80: 6d 61 74 69 6f 6e 20 74 68 72 6f 75 67 68 20 74  mation through t
4e90: 6f 20 74 68 65 20 78 46 69 6c 74 65 72 20 6d 65  o the xFilter me
4ea0: 74 68 6f 64 2e 20 41 6e 79 20 64 65 73 69 72 65  thod. Any desire
4eb0: 64 20 6d 65 61 6e 69 6e 67 20 63 61 6e 0d 0a 20  d meaning can.. 
4ec0: 20 20 20 20 20 20 20 2f 2f 2f 20 62 65 20 61 73         /// be as
4ed0: 73 69 67 6e 65 64 20 74 6f 20 69 64 78 4e 75 6d  signed to idxNum
4ee0: 20 61 6e 64 20 69 64 78 53 74 72 20 61 73 20 6c   and idxStr as l
4ef0: 6f 6e 67 20 61 73 20 78 42 65 73 74 49 6e 64 65  ong as xBestInde
4f00: 78 20 61 6e 64 20 78 46 69 6c 74 65 72 0d 0a 20  x and xFilter.. 
4f10: 20 20 20 20 20 20 20 2f 2f 2f 20 61 67 72 65 65         /// agree
4f20: 20 6f 6e 20 77 68 61 74 20 74 68 61 74 20 6d 65   on what that me
4f30: 61 6e 69 6e 67 20 69 73 2e 0d 0a 20 20 20 20 20  aning is...     
4f40: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a     /// </para>..
4f50: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
4f60: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
4f70: 54 68 65 20 69 64 78 53 74 72 20 76 61 6c 75 65  The idxStr value
4f80: 20 6d 61 79 20 62 65 20 61 20 73 74 72 69 6e 67   may be a string
4f90: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
4fa0: 6e 20 53 51 4c 69 74 65 20 6d 65 6d 6f 72 79 0d  n SQLite memory.
4fb0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 61 6c 6c  .        /// all
4fc0: 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  ocation function
4fd0: 20 73 75 63 68 20 61 73 20 73 71 6c 69 74 65 33   such as sqlite3
4fe0: 5f 6d 70 72 69 6e 74 66 28 29 2e 20 49 66 20 74  _mprintf(). If t
4ff0: 68 69 73 20 69 73 20 74 68 65 20 63 61 73 65 2c  his is the case,
5000: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68  ..        /// th
5010: 65 6e 20 74 68 65 20 6e 65 65 64 54 6f 46 72 65  en the needToFre
5020: 65 49 64 78 53 74 72 20 66 6c 61 67 20 6d 75 73  eIdxStr flag mus
5030: 74 20 62 65 20 73 65 74 20 74 6f 20 74 72 75 65  t be set to true
5040: 20 73 6f 20 74 68 61 74 20 74 68 65 0d 0a 20 20   so that the..  
5050: 20 20 20 20 20 20 2f 2f 2f 20 53 51 4c 69 74 65        /// SQLite
5060: 20 63 6f 72 65 20 77 69 6c 6c 20 6b 6e 6f 77 20   core will know 
5070: 74 6f 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  to call sqlite3_
5080: 66 72 65 65 28 29 20 6f 6e 20 74 68 61 74 20 73  free() on that s
5090: 74 72 69 6e 67 20 77 68 65 6e 20 69 74 0d 0a 20  tring when it.. 
50a0: 20 20 20 20 20 20 20 2f 2f 2f 20 68 61 73 20 66         /// has f
50b0: 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2c  inished with it,
50c0: 20 61 6e 64 20 74 68 75 73 20 61 76 6f 69 64 20   and thus avoid 
50d0: 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0d 0a  a memory leak...
50e0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
50f0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
5100: 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20   <para>..       
5110: 20 2f 2f 2f 20 49 66 20 74 68 65 20 76 69 72 74   /// If the virt
5120: 75 61 6c 20 74 61 62 6c 65 20 77 69 6c 6c 20 6f  ual table will o
5130: 75 74 70 75 74 20 72 6f 77 73 20 69 6e 20 74 68  utput rows in th
5140: 65 20 6f 72 64 65 72 20 73 70 65 63 69 66 69 65  e order specifie
5150: 64 20 62 79 20 74 68 65 0d 0a 20 20 20 20 20 20  d by the..      
5160: 20 20 2f 2f 2f 20 4f 52 44 45 52 20 42 59 20 63    /// ORDER BY c
5170: 6c 61 75 73 65 2c 20 74 68 65 6e 20 74 68 65 20  lause, then the 
5180: 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 20  orderByConsumed 
5190: 66 6c 61 67 20 6d 61 79 20 62 65 20 73 65 74 20  flag may be set 
51a0: 74 6f 20 74 72 75 65 2e 0d 0a 20 20 20 20 20 20  to true...      
51b0: 20 20 2f 2f 2f 20 49 66 20 74 68 65 20 6f 75 74    /// If the out
51c0: 70 75 74 20 69 73 20 6e 6f 74 20 61 75 74 6f 6d  put is not autom
51d0: 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 65 20  atically in the 
51e0: 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20 74 68  correct order th
51f0: 65 6e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  en..        /// 
5200: 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 20  orderByConsumed 
5210: 6d 75 73 74 20 62 65 20 6c 65 66 74 20 69 6e 20  must be left in 
5220: 69 74 73 20 64 65 66 61 75 6c 74 20 66 61 6c 73  its default fals
5230: 65 20 73 65 74 74 69 6e 67 2e 20 54 68 69 73 0d  e setting. This.
5240: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 77 69 6c  .        /// wil
5250: 6c 20 69 6e 64 69 63 61 74 65 20 74 6f 20 74 68  l indicate to th
5260: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 74 68  e SQLite core th
5270: 61 74 20 69 74 20 77 69 6c 6c 20 6e 65 65 64 20  at it will need 
5280: 74 6f 20 64 6f 20 61 20 73 65 70 61 72 61 74 65  to do a separate
5290: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 6f  ..        /// so
52a0: 72 74 69 6e 67 20 70 61 73 73 20 6f 76 65 72 20  rting pass over 
52b0: 74 68 65 20 64 61 74 61 20 61 66 74 65 72 20 69  the data after i
52c0: 74 20 63 6f 6d 65 73 20 6f 75 74 20 6f 66 20 74  t comes out of t
52d0: 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
52e0: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
52f0: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
5300: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20  /// <para>..    
5310: 20 20 20 20 2f 2f 2f 20 54 68 65 20 65 73 74 69      /// The esti
5320: 6d 61 74 65 64 43 6f 73 74 20 66 69 65 6c 64 20  matedCost field 
5330: 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f  should be set to
5340: 20 74 68 65 20 65 73 74 69 6d 61 74 65 64 20 6e   the estimated n
5350: 75 6d 62 65 72 20 6f 66 0d 0a 20 20 20 20 20 20  umber of..      
5360: 20 20 2f 2f 2f 20 64 69 73 6b 20 61 63 63 65 73    /// disk acces
5370: 73 20 6f 70 65 72 61 74 69 6f 6e 73 20 72 65 71  s operations req
5380: 75 69 72 65 64 20 74 6f 20 65 78 65 63 75 74 65  uired to execute
5390: 20 74 68 69 73 20 71 75 65 72 79 20 61 67 61 69   this query agai
53a0: 6e 73 74 20 74 68 65 0d 0a 20 20 20 20 20 20 20  nst the..       
53b0: 20 2f 2f 2f 20 76 69 72 74 75 61 6c 20 74 61 62   /// virtual tab
53c0: 6c 65 2e 20 54 68 65 20 53 51 4c 69 74 65 20 63  le. The SQLite c
53d0: 6f 72 65 20 77 69 6c 6c 20 6f 66 74 65 6e 20 63  ore will often c
53e0: 61 6c 6c 20 78 42 65 73 74 49 6e 64 65 78 20 6d  all xBestIndex m
53f0: 75 6c 74 69 70 6c 65 0d 0a 20 20 20 20 20 20 20  ultiple..       
5400: 20 2f 2f 2f 20 74 69 6d 65 73 20 77 69 74 68 20   /// times with 
5410: 64 69 66 66 65 72 65 6e 74 20 63 6f 6e 73 74 72  different constr
5420: 61 69 6e 74 73 2c 20 6f 62 74 61 69 6e 20 6d 75  aints, obtain mu
5430: 6c 74 69 70 6c 65 20 63 6f 73 74 20 65 73 74 69  ltiple cost esti
5440: 6d 61 74 65 73 2c 0d 0a 20 20 20 20 20 20 20 20  mates,..        
5450: 2f 2f 2f 20 74 68 65 6e 20 63 68 6f 6f 73 65 20  /// then choose 
5460: 74 68 65 20 71 75 65 72 79 20 70 6c 61 6e 20 74  the query plan t
5470: 68 61 74 20 67 69 76 65 73 20 74 68 65 20 6c 6f  hat gives the lo
5480: 77 65 73 74 20 65 73 74 69 6d 61 74 65 2e 0d 0a  west estimate...
5490: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
54a0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
54b0: 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20   <para>..       
54c0: 20 2f 2f 2f 20 54 68 65 20 61 43 6f 6e 73 74 72   /// The aConstr
54d0: 61 69 6e 74 55 73 61 67 65 5b 5d 20 61 72 72 61  aintUsage[] arra
54e0: 79 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 65 20 65  y contains one e
54f0: 6c 65 6d 65 6e 74 20 66 6f 72 20 65 61 63 68 20  lement for each 
5500: 6f 66 20 74 68 65 0d 0a 20 20 20 20 20 20 20 20  of the..        
5510: 2f 2f 2f 20 6e 43 6f 6e 73 74 72 61 69 6e 74 20  /// nConstraint 
5520: 63 6f 6e 73 74 72 61 69 6e 74 73 20 69 6e 20 74  constraints in t
5530: 68 65 20 69 6e 70 75 74 73 20 73 65 63 74 69 6f  he inputs sectio
5540: 6e 20 6f 66 20 74 68 65 0d 0a 20 20 20 20 20 20  n of the..      
5550: 20 20 2f 2f 2f 20 73 71 6c 69 74 65 33 5f 69 6e    /// sqlite3_in
5560: 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75  dex_info structu
5570: 72 65 2e 20 54 68 65 20 61 43 6f 6e 73 74 72 61  re. The aConstra
5580: 69 6e 74 55 73 61 67 65 5b 5d 20 61 72 72 61 79  intUsage[] array
5590: 20 69 73 20 75 73 65 64 0d 0a 20 20 20 20 20 20   is used..      
55a0: 20 20 2f 2f 2f 20 62 79 20 78 42 65 73 74 49 6e    /// by xBestIn
55b0: 64 65 78 20 74 6f 20 74 65 6c 6c 20 74 68 65 20  dex to tell the 
55c0: 63 6f 72 65 20 68 6f 77 20 69 74 20 69 73 20 75  core how it is u
55d0: 73 69 6e 67 20 74 68 65 20 63 6f 6e 73 74 72 61  sing the constra
55e0: 69 6e 74 73 2e 0d 0a 20 20 20 20 20 20 20 20 2f  ints...        /
55f0: 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  // </para>..    
5600: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a      /// <para>..
5610: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20          /// The 
5620: 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f  xBestIndex metho
5630: 64 20 6d 61 79 20 73 65 74 20 61 43 6f 6e 73 74  d may set aConst
5640: 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e 61 72 67  raintUsage[].arg
5650: 76 49 6e 64 65 78 20 65 6e 74 72 69 65 73 0d 0a  vIndex entries..
5660: 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 6f 20 76          /// to v
5670: 61 6c 75 65 73 20 67 72 65 61 74 65 72 20 74 68  alues greater th
5680: 61 6e 20 6f 6e 65 2e 20 45 78 61 63 74 6c 79 20  an one. Exactly 
5690: 6f 6e 65 20 65 6e 74 72 79 20 73 68 6f 75 6c 64  one entry should
56a0: 20 62 65 20 73 65 74 20 74 6f 20 31 2c 0d 0a 20   be set to 1,.. 
56b0: 20 20 20 20 20 20 20 2f 2f 2f 20 61 6e 6f 74 68         /// anoth
56c0: 65 72 20 74 6f 20 32 2c 20 61 6e 6f 74 68 65 72  er to 2, another
56d0: 20 74 6f 20 33 2c 20 61 6e 64 20 73 6f 20 66 6f   to 3, and so fo
56e0: 72 74 68 20 75 70 20 74 6f 20 61 73 20 6d 61 6e  rth up to as man
56f0: 79 20 6f 72 20 61 73 20 66 65 77 20 61 73 0d 0a  y or as few as..
5700: 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 20          /// the 
5710: 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f  xBestIndex metho
5720: 64 20 77 61 6e 74 73 2e 20 54 68 65 20 45 58 50  d wants. The EXP
5730: 52 20 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70  R of the corresp
5740: 6f 6e 64 69 6e 67 0d 0a 20 20 20 20 20 20 20 20  onding..        
5750: 2f 2f 2f 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  /// constraints 
5760: 77 69 6c 6c 20 74 68 65 6e 20 62 65 20 70 61 73  will then be pas
5770: 73 65 64 20 69 6e 20 61 73 20 74 68 65 20 61 72  sed in as the ar
5780: 67 76 5b 5d 20 70 61 72 61 6d 65 74 65 72 73 20  gv[] parameters 
5790: 74 6f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  to..        /// 
57a0: 78 46 69 6c 74 65 72 2e 0d 0a 20 20 20 20 20 20  xFilter...      
57b0: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
57c0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
57d0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 46  >..        /// F
57e0: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74  or example, if t
57f0: 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 33  he aConstraint[3
5800: 5d 2e 61 72 67 76 49 6e 64 65 78 20 69 73 20 73  ].argvIndex is s
5810: 65 74 20 74 6f 20 31 2c 20 74 68 65 6e 20 77 68  et to 1, then wh
5820: 65 6e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  en..        /// 
5830: 78 46 69 6c 74 65 72 20 69 73 20 63 61 6c 6c 65  xFilter is calle
5840: 64 2c 20 74 68 65 20 61 72 67 76 5b 30 5d 20 70  d, the argv[0] p
5850: 61 73 73 65 64 20 74 6f 20 78 46 69 6c 74 65 72  assed to xFilter
5860: 20 77 69 6c 6c 20 68 61 76 65 20 74 68 65 20 45   will have the E
5870: 58 50 52 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  XPR..        ///
5880: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 43   value of the aC
5890: 6f 6e 73 74 72 61 69 6e 74 5b 33 5d 20 63 6f 6e  onstraint[3] con
58a0: 73 74 72 61 69 6e 74 2e 0d 0a 20 20 20 20 20 20  straint...      
58b0: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
58c0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
58d0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 42  >..        /// B
58e0: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 53  y default, the S
58f0: 51 4c 69 74 65 20 63 6f 72 65 20 64 6f 75 62 6c  QLite core doubl
5900: 65 20 63 68 65 63 6b 73 20 61 6c 6c 20 63 6f 6e  e checks all con
5910: 73 74 72 61 69 6e 74 73 20 6f 6e 20 65 61 63 68  straints on each
5920: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 72 6f  ..        /// ro
5930: 77 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c  w of the virtual
5940: 20 74 61 62 6c 65 20 74 68 61 74 20 69 74 20 72   table that it r
5950: 65 63 65 69 76 65 73 2e 20 49 66 20 73 75 63 68  eceives. If such
5960: 20 61 20 63 68 65 63 6b 20 69 73 0d 0a 20 20 20   a check is..   
5970: 20 20 20 20 20 2f 2f 2f 20 72 65 64 75 6e 64 61       /// redunda
5980: 6e 74 2c 20 74 68 65 20 78 42 65 73 74 46 69 6c  nt, the xBestFil
5990: 74 65 72 20 6d 65 74 68 6f 64 20 63 61 6e 20 73  ter method can s
59a0: 75 70 70 72 65 73 73 20 74 68 61 74 20 64 6f 75  uppress that dou
59b0: 62 6c 65 2d 63 68 65 63 6b 20 62 79 0d 0a 20 20  ble-check by..  
59c0: 20 20 20 20 20 20 2f 2f 2f 20 73 65 74 74 69 6e        /// settin
59d0: 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61  g aConstraintUsa
59e0: 67 65 5b 5d 2e 6f 6d 69 74 2e 0d 0a 20 20 20 20  ge[].omit...    
59f0: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
5a00: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 73  .        /// </s
5a10: 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20  ummary>..       
5a20: 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65   /// <param name
5a30: 3d 22 70 56 74 61 62 22 3e 0d 0a 20 20 20 20 20  ="pVtab">..     
5a40: 20 20 20 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76     /// The nativ
5a50: 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
5a60: 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 64 65   sqlite3_vtab de
5a70: 72 69 76 65 64 20 73 74 72 75 63 74 75 72 65 2e  rived structure.
5a80: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
5a90: 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20  param>..        
5aa0: 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d  /// <param name=
5ab0: 22 70 49 6e 64 65 78 22 3e 0d 0a 20 20 20 20 20  "pIndex">..     
5ac0: 20 20 20 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76     /// The nativ
5ad0: 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
5ae0: 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
5af0: 6e 66 6f 20 73 74 72 75 63 74 75 72 65 2e 0d 0a  nfo structure...
5b00: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
5b10: 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ram>..        //
5b20: 2f 20 3c 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20  / <returns>..   
5b30: 20 20 20 20 20 2f 2f 2f 20 41 20 73 74 61 6e 64       /// A stand
5b40: 61 72 64 20 53 51 4c 69 74 65 20 72 65 74 75 72  ard SQLite retur
5b50: 6e 20 63 6f 64 65 2e 0d 0a 20 20 20 20 20 20 20  n code...       
5b60: 20 2f 2f 2f 20 3c 2f 72 65 74 75 72 6e 73 3e 0d   /// </returns>.
5b70: 0a 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 45  .        SQLiteE
5b80: 72 72 6f 72 43 6f 64 65 20 78 42 65 73 74 49 6e  rrorCode xBestIn
5b90: 64 65 78 28 0d 0a 20 20 20 20 20 20 20 20 20 20  dex(..          
5ba0: 20 20 49 6e 74 50 74 72 20 70 56 74 61 62 2c 0d    IntPtr pVtab,.
5bb0: 0a 20 20 20 20 20 20 20 20 20 20 20 20 49 6e 74  .            Int
5bc0: 50 74 72 20 70 49 6e 64 65 78 0d 0a 20 20 20 20  Ptr pIndex..    
5bd0: 20 20 20 20 20 20 20 20 29 3b 0d 0a 0d 0a 20 20          );....  
5be0: 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f        //////////
5bf0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
5c00: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
5c10: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
5c20: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d  /////////////...
5c30: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 73 75  .        /// <su
5c40: 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20  mmary>..        
5c50: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20  /// <para>..    
5c60: 20 20 20 20 2f 2f 2f 20 54 68 69 73 20 6d 65 74      /// This met
5c70: 68 6f 64 20 72 65 6c 65 61 73 65 73 20 61 20 63  hod releases a c
5c80: 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 61 20 76  onnection to a v
5c90: 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 4f 6e  irtual table. On
5ca0: 6c 79 20 74 68 65 0d 0a 20 20 20 20 20 20 20 20  ly the..        
5cb0: 2f 2f 2f 20 73 71 6c 69 74 65 33 5f 76 74 61 62  /// sqlite3_vtab
5cc0: 20 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74 72   object is destr
5cd0: 6f 79 65 64 2e 20 54 68 65 20 76 69 72 74 75 61  oyed. The virtua
5ce0: 6c 20 74 61 62 6c 65 20 69 73 20 6e 6f 74 0d 0a  l table is not..
5cf0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 64 65 73 74          /// dest
5d00: 72 6f 79 65 64 20 61 6e 64 20 61 6e 79 20 62 61  royed and any ba
5d10: 63 6b 69 6e 67 20 73 74 6f 72 65 20 61 73 73 6f  cking store asso
5d20: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
5d30: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 0d 0a 20  virtual table.. 
5d40: 20 20 20 20 20 20 20 2f 2f 2f 20 70 65 72 73 69         /// persi
5d50: 73 74 73 2e 20 54 68 69 73 20 6d 65 74 68 6f 64  sts. This method
5d60: 20 75 6e 64 6f 65 73 20 74 68 65 20 77 6f 72 6b   undoes the work
5d70: 20 6f 66 20 78 43 6f 6e 6e 65 63 74 2e 0d 0a 20   of xConnect... 
5d80: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
5d90: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
5da0: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
5db0: 2f 2f 2f 20 54 68 69 73 20 6d 65 74 68 6f 64 20  /// This method 
5dc0: 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
5dd0: 66 6f 72 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e  for a connection
5de0: 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 20   to the virtual 
5df0: 74 61 62 6c 65 2e 0d 0a 20 20 20 20 20 20 20 20  table...        
5e00: 2f 2f 2f 20 43 6f 6e 74 72 61 73 74 20 74 68 69  /// Contrast thi
5e10: 73 20 6d 65 74 68 6f 64 20 77 69 74 68 20 78 44  s method with xD
5e20: 65 73 74 72 6f 79 2e 20 54 68 65 20 78 44 65 73  estroy. The xDes
5e30: 74 72 6f 79 20 69 73 20 61 20 64 65 73 74 72 75  troy is a destru
5e40: 63 74 6f 72 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ctor..        //
5e50: 2f 20 66 6f 72 20 74 68 65 20 65 6e 74 69 72 65  / for the entire
5e60: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 0d   virtual table..
5e70: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
5e80: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
5e90: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
5ea0: 20 20 2f 2f 2f 20 54 68 65 20 78 44 69 73 63 6f    /// The xDisco
5eb0: 6e 6e 65 63 74 20 6d 65 74 68 6f 64 20 69 73 20  nnect method is 
5ec0: 72 65 71 75 69 72 65 64 20 66 6f 72 20 65 76 65  required for eve
5ed0: 72 79 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ry virtual table
5ee0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6d  ..        /// im
5ef0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68  plementation, th
5f00: 6f 75 67 68 20 69 74 20 69 73 20 61 63 63 65 70  ough it is accep
5f10: 74 61 62 6c 65 20 66 6f 72 20 74 68 65 20 78 44  table for the xD
5f20: 69 73 63 6f 6e 6e 65 63 74 20 61 6e 64 0d 0a 20  isconnect and.. 
5f30: 20 20 20 20 20 20 20 2f 2f 2f 20 78 44 65 73 74         /// xDest
5f40: 72 6f 79 20 6d 65 74 68 6f 64 73 20 74 6f 20 62  roy methods to b
5f50: 65 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  e the same funct
5f60: 69 6f 6e 20 69 66 20 74 68 61 74 20 6d 61 6b 65  ion if that make
5f70: 73 20 73 65 6e 73 65 20 66 6f 72 0d 0a 20 20 20  s sense for..   
5f80: 20 20 20 20 20 2f 2f 2f 20 74 68 65 20 70 61 72       /// the par
5f90: 74 69 63 75 6c 61 72 20 76 69 72 74 75 61 6c 20  ticular virtual 
5fa0: 74 61 62 6c 65 2e 0d 0a 20 20 20 20 20 20 20 20  table...        
5fb0: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
5fc0: 20 20 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61       /// </summa
5fd0: 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ry>..        ///
5fe0: 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 56   <param name="pV
5ff0: 74 61 62 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f  tab">..        /
6000: 2f 2f 20 54 68 65 20 6e 61 74 69 76 65 20 70 6f  // The native po
6010: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  inter to the sql
6020: 69 74 65 33 5f 76 74 61 62 20 64 65 72 69 76 65  ite3_vtab derive
6030: 64 20 73 74 72 75 63 74 75 72 65 2e 0d 0a 20 20  d structure...  
6040: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61        /// </para
6050: 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  m>..        /// 
6060: 3c 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20  <returns>..     
6070: 20 20 20 2f 2f 2f 20 41 20 73 74 61 6e 64 61 72     /// A standar
6080: 64 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 20  d SQLite return 
6090: 63 6f 64 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f  code...        /
60a0: 2f 2f 20 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a 20  // </returns>.. 
60b0: 20 20 20 20 20 20 20 53 51 4c 69 74 65 45 72 72         SQLiteErr
60c0: 6f 72 43 6f 64 65 20 78 44 69 73 63 6f 6e 6e 65  orCode xDisconne
60d0: 63 74 28 0d 0a 20 20 20 20 20 20 20 20 20 20 20  ct(..           
60e0: 20 49 6e 74 50 74 72 20 70 56 74 61 62 0d 0a 20   IntPtr pVtab.. 
60f0: 20 20 20 20 20 20 20 20 20 20 20 29 3b 0d 0a 0d             );...
6100: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f  .        ///////
6110: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
6120: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
6130: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
6140: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
6150: 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ....        /// 
6160: 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20  <summary>..     
6170: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20     /// <para>.. 
6180: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 69 73 20         /// This 
6190: 6d 65 74 68 6f 64 20 72 65 6c 65 61 73 65 73 20  method releases 
61a0: 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  a connection to 
61b0: 61 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2c  a virtual table,
61c0: 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 0d 0a   just like the..
61d0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 78 44 69 73          /// xDis
61e0: 63 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64 2c 20  connect method, 
61f0: 61 6e 64 20 69 74 20 61 6c 73 6f 20 64 65 73 74  and it also dest
6200: 72 6f 79 73 20 74 68 65 20 75 6e 64 65 72 6c 79  roys the underly
6210: 69 6e 67 20 74 61 62 6c 65 0d 0a 20 20 20 20 20  ing table..     
6220: 20 20 20 2f 2f 2f 20 69 6d 70 6c 65 6d 65 6e 74     /// implement
6230: 61 74 69 6f 6e 2e 20 54 68 69 73 20 6d 65 74 68  ation. This meth
6240: 6f 64 20 75 6e 64 6f 65 73 20 74 68 65 20 77 6f  od undoes the wo
6250: 72 6b 20 6f 66 20 78 43 72 65 61 74 65 2e 0d 0a  rk of xCreate...
6260: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
6270: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
6280: 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20   <para>..       
6290: 20 2f 2f 2f 20 54 68 65 20 78 44 69 73 63 6f 6e   /// The xDiscon
62a0: 6e 65 63 74 20 6d 65 74 68 6f 64 20 69 73 20 63  nect method is c
62b0: 61 6c 6c 65 64 20 77 68 65 6e 65 76 65 72 20 61  alled whenever a
62c0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
62d0: 74 69 6f 6e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  tion..        //
62e0: 2f 20 74 68 61 74 20 75 73 65 73 20 61 20 76 69  / that uses a vi
62f0: 72 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20 63  rtual table is c
6300: 6c 6f 73 65 64 2e 20 54 68 65 20 78 44 65 73 74  losed. The xDest
6310: 72 6f 79 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e  roy method is on
6320: 6c 79 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ly..        /// 
6330: 63 61 6c 6c 65 64 20 77 68 65 6e 20 61 20 44 52  called when a DR
6340: 4f 50 20 54 41 42 4c 45 20 73 74 61 74 65 6d 65  OP TABLE stateme
6350: 6e 74 20 69 73 20 65 78 65 63 75 74 65 64 20 61  nt is executed a
6360: 67 61 69 6e 73 74 20 74 68 65 20 76 69 72 74 75  gainst the virtu
6370: 61 6c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  al..        /// 
6380: 74 61 62 6c 65 2e 0d 0a 20 20 20 20 20 20 20 20  table...        
6390: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
63a0: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
63b0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65  .        /// The
63c0: 20 78 44 65 73 74 72 6f 79 20 6d 65 74 68 6f 64   xDestroy method
63d0: 20 69 73 20 72 65 71 75 69 72 65 64 20 66 6f 72   is required for
63e0: 20 65 76 65 72 79 20 76 69 72 74 75 61 6c 20 74   every virtual t
63f0: 61 62 6c 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f  able..        //
6400: 2f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  / implementation
6410: 2c 20 74 68 6f 75 67 68 20 69 74 20 69 73 20 61  , though it is a
6420: 63 63 65 70 74 61 62 6c 65 20 66 6f 72 20 74 68  cceptable for th
6430: 65 20 78 44 69 73 63 6f 6e 6e 65 63 74 20 61 6e  e xDisconnect an
6440: 64 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 78  d..        /// x
6450: 44 65 73 74 72 6f 79 20 6d 65 74 68 6f 64 73 20  Destroy methods 
6460: 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20 66  to be the same f
6470: 75 6e 63 74 69 6f 6e 20 69 66 20 74 68 61 74 20  unction if that 
6480: 6d 61 6b 65 73 20 73 65 6e 73 65 20 66 6f 72 0d  makes sense for.
6490: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65  .        /// the
64a0: 20 70 61 72 74 69 63 75 6c 61 72 20 76 69 72 74   particular virt
64b0: 75 61 6c 20 74 61 62 6c 65 2e 0d 0a 20 20 20 20  ual table...    
64c0: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
64d0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 73  .        /// </s
64e0: 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20  ummary>..       
64f0: 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65   /// <param name
6500: 3d 22 70 56 74 61 62 22 3e 0d 0a 20 20 20 20 20  ="pVtab">..     
6510: 20 20 20 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76     /// The nativ
6520: 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
6530: 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 64 65   sqlite3_vtab de
6540: 72 69 76 65 64 20 73 74 72 75 63 74 75 72 65 2e  rived structure.
6550: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
6560: 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20  param>..        
6570: 2f 2f 2f 20 3c 72 65 74 75 72 6e 73 3e 0d 0a 20  /// <returns>.. 
6580: 20 20 20 20 20 20 20 2f 2f 2f 20 41 20 73 74 61         /// A sta
6590: 6e 64 61 72 64 20 53 51 4c 69 74 65 20 72 65 74  ndard SQLite ret
65a0: 75 72 6e 20 63 6f 64 65 2e 0d 0a 20 20 20 20 20  urn code...     
65b0: 20 20 20 2f 2f 2f 20 3c 2f 72 65 74 75 72 6e 73     /// </returns
65c0: 3e 0d 0a 20 20 20 20 20 20 20 20 53 51 4c 69 74  >..        SQLit
65d0: 65 45 72 72 6f 72 43 6f 64 65 20 78 44 65 73 74  eErrorCode xDest
65e0: 72 6f 79 28 0d 0a 20 20 20 20 20 20 20 20 20 20  roy(..          
65f0: 20 20 49 6e 74 50 74 72 20 70 56 74 61 62 0d 0a    IntPtr pVtab..
6600: 20 20 20 20 20 20 20 20 20 20 20 20 29 3b 0d 0a              );..
6610: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f  ..        //////
6620: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
6630: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
6640: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
6650: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
6660: 2f 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  /....        ///
6670: 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20   <summary>..    
6680: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a      /// <para>..
6690: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20          /// The 
66a0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 63 72 65  xOpen method cre
66b0: 61 74 65 73 20 61 20 6e 65 77 20 63 75 72 73 6f  ates a new curso
66c0: 72 20 75 73 65 64 20 66 6f 72 20 61 63 63 65 73  r used for acces
66d0: 73 69 6e 67 20 28 72 65 61 64 0d 0a 20 20 20 20  sing (read..    
66e0: 20 20 20 20 2f 2f 2f 20 61 6e 64 2f 6f 72 20 77      /// and/or w
66f0: 72 69 74 69 6e 67 29 20 61 20 76 69 72 74 75 61  riting) a virtua
6700: 6c 20 74 61 62 6c 65 2e 20 41 20 73 75 63 63 65  l table. A succe
6710: 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
6720: 20 6f 66 20 74 68 69 73 0d 0a 20 20 20 20 20 20   of this..      
6730: 20 20 2f 2f 2f 20 6d 65 74 68 6f 64 20 77 69 6c    /// method wil
6740: 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 6d  l allocate the m
6750: 65 6d 6f 72 79 20 66 6f 72 20 74 68 65 20 73 71  emory for the sq
6760: 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
6770: 72 20 28 6f 72 20 61 0d 0a 20 20 20 20 20 20 20  r (or a..       
6780: 20 2f 2f 2f 20 73 75 62 63 6c 61 73 73 29 2c 20   /// subclass), 
6790: 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6e  initialize the n
67a0: 65 77 20 6f 62 6a 65 63 74 2c 20 61 6e 64 20 6d  ew object, and m
67b0: 61 6b 65 20 2a 70 70 43 75 72 73 6f 72 20 70 6f  ake *ppCursor po
67c0: 69 6e 74 20 74 6f 0d 0a 20 20 20 20 20 20 20 20  int to..        
67d0: 2f 2f 2f 20 74 68 65 20 6e 65 77 20 6f 62 6a 65  /// the new obje
67e0: 63 74 2e 20 54 68 65 20 73 75 63 63 65 73 73 66  ct. The successf
67f0: 75 6c 20 63 61 6c 6c 20 74 68 65 6e 20 72 65 74  ul call then ret
6800: 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0d  urns SQLITE_OK..
6810: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
6820: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
6830: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
6840: 20 20 2f 2f 2f 20 46 6f 72 20 65 76 65 72 79 20    /// For every 
6850: 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
6860: 74 6f 20 74 68 69 73 20 6d 65 74 68 6f 64 2c 20  to this method, 
6870: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  the SQLite core 
6880: 77 69 6c 6c 0d 0a 20 20 20 20 20 20 20 20 2f 2f  will..        //
6890: 2f 20 6c 61 74 65 72 20 69 6e 76 6f 6b 65 20 74  / later invoke t
68a0: 68 65 20 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  he xClose method
68b0: 20 74 6f 20 64 65 73 74 72 6f 79 20 74 68 65 20   to destroy the 
68c0: 61 6c 6c 6f 63 61 74 65 64 20 63 75 72 73 6f 72  allocated cursor
68d0: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
68e0: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
68f0: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20  /// <para>..    
6900: 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 4f 70 65      /// The xOpe
6910: 6e 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f  n method need no
6920: 74 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  t initialize the
6930: 20 70 56 74 61 62 20 66 69 65 6c 64 20 6f 66 20   pVtab field of 
6940: 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  the..        ///
6950: 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
6960: 72 73 6f 72 20 73 74 72 75 63 74 75 72 65 2e 20  rsor structure. 
6970: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
6980: 77 69 6c 6c 20 74 61 6b 65 20 63 61 72 65 20 6f  will take care o
6990: 66 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74  f..        /// t
69a0: 68 61 74 20 63 68 6f 72 65 20 61 75 74 6f 6d 61  hat chore automa
69b0: 74 69 63 61 6c 6c 79 2e 0d 0a 20 20 20 20 20 20  tically...      
69c0: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
69d0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
69e0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41  >..        /// A
69f0: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
6a00: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75  mplementation mu
6a10: 73 74 20 62 65 20 61 62 6c 65 20 74 6f 20 73 75  st be able to su
6a20: 70 70 6f 72 74 20 61 6e 20 61 72 62 69 74 72 61  pport an arbitra
6a30: 72 79 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ry..        /// 
6a40: 6e 75 6d 62 65 72 20 6f 66 20 73 69 6d 75 6c 74  number of simult
6a50: 61 6e 65 6f 75 73 6c 79 20 6f 70 65 6e 20 63 75  aneously open cu
6a60: 72 73 6f 72 73 2e 0d 0a 20 20 20 20 20 20 20 20  rsors...        
6a70: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
6a80: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
6a90: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 57 68 65  .        /// Whe
6aa0: 6e 20 69 6e 69 74 69 61 6c 6c 79 20 6f 70 65 6e  n initially open
6ab0: 65 64 2c 20 74 68 65 20 63 75 72 73 6f 72 20 69  ed, the cursor i
6ac0: 73 20 69 6e 20 61 6e 20 75 6e 64 65 66 69 6e 65  s in an undefine
6ad0: 64 20 73 74 61 74 65 2e 20 54 68 65 0d 0a 20 20  d state. The..  
6ae0: 20 20 20 20 20 20 2f 2f 2f 20 53 51 4c 69 74 65        /// SQLite
6af0: 20 63 6f 72 65 20 77 69 6c 6c 20 69 6e 76 6f 6b   core will invok
6b00: 65 20 74 68 65 20 78 46 69 6c 74 65 72 20 6d 65  e the xFilter me
6b10: 74 68 6f 64 20 6f 6e 20 74 68 65 20 63 75 72 73  thod on the curs
6b20: 6f 72 20 70 72 69 6f 72 20 74 6f 0d 0a 20 20 20  or prior to..   
6b30: 20 20 20 20 20 2f 2f 2f 20 61 6e 79 20 61 74 74       /// any att
6b40: 65 6d 70 74 20 74 6f 20 70 6f 73 69 74 69 6f 6e  empt to position
6b50: 20 6f 72 20 72 65 61 64 20 66 72 6f 6d 20 74 68   or read from th
6b60: 65 20 63 75 72 73 6f 72 2e 0d 0a 20 20 20 20 20  e cursor...     
6b70: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a     /// </para>..
6b80: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
6b90: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
6ba0: 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  The xOpen method
6bb0: 20 69 73 20 72 65 71 75 69 72 65 64 20 66 6f 72   is required for
6bc0: 20 65 76 65 72 79 20 76 69 72 74 75 61 6c 20 74   every virtual t
6bd0: 61 62 6c 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f  able..        //
6be0: 2f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  / implementation
6bf0: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
6c00: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
6c10: 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a  /// </summary>..
6c20: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
6c30: 61 6d 20 6e 61 6d 65 3d 22 70 56 74 61 62 22 3e  am name="pVtab">
6c40: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
6c50: 65 20 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72  e native pointer
6c60: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
6c70: 76 74 61 62 20 64 65 72 69 76 65 64 20 73 74 72  vtab derived str
6c80: 75 63 74 75 72 65 2e 0d 0a 20 20 20 20 20 20 20  ucture...       
6c90: 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20   /// </param>.. 
6ca0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
6cb0: 6d 20 6e 61 6d 65 3d 22 70 43 75 72 73 6f 72 22  m name="pCursor"
6cc0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 55  >..        /// U
6cd0: 70 6f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 69  pon success, thi
6ce0: 73 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  s parameter must
6cf0: 20 62 65 20 6d 6f 64 69 66 69 65 64 20 74 6f 20   be modified to 
6d00: 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 6e 65 77  point to the new
6d10: 6c 79 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ly..        /// 
6d20: 63 72 65 61 74 65 64 20 6e 61 74 69 76 65 20 73  created native s
6d30: 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
6d40: 6f 72 20 64 65 72 69 76 65 64 20 73 74 72 75 63  or derived struc
6d50: 74 75 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f  ture...        /
6d60: 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20  // </param>..   
6d70: 20 20 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72 6e       /// <return
6d80: 73 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  s>..        /// 
6d90: 41 20 73 74 61 6e 64 61 72 64 20 53 51 4c 69 74  A standard SQLit
6da0: 65 20 72 65 74 75 72 6e 20 63 6f 64 65 2e 0d 0a  e return code...
6db0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72 65          /// </re
6dc0: 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20  turns>..        
6dd0: 53 51 4c 69 74 65 45 72 72 6f 72 43 6f 64 65 20  SQLiteErrorCode 
6de0: 78 4f 70 65 6e 28 0d 0a 20 20 20 20 20 20 20 20  xOpen(..        
6df0: 20 20 20 20 49 6e 74 50 74 72 20 70 56 74 61 62      IntPtr pVtab
6e00: 2c 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 72  ,..            r
6e10: 65 66 20 49 6e 74 50 74 72 20 70 43 75 72 73 6f  ef IntPtr pCurso
6e20: 72 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 29  r..            )
6e30: 3b 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ;....        ///
6e40: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
6e50: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
6e60: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
6e70: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
6e80: 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 20 20 20 20  ////....        
6e90: 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20  /// <summary>.. 
6ea0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
6eb0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54  >..        /// T
6ec0: 68 65 20 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  he xClose method
6ed0: 20 63 6c 6f 73 65 73 20 61 20 63 75 72 73 6f 72   closes a cursor
6ee0: 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 70 65 6e   previously open
6ef0: 65 64 20 62 79 20 78 4f 70 65 6e 2e 20 54 68 65  ed by xOpen. The
6f00: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 53 51  ..        /// SQ
6f10: 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 61  Lite core will a
6f20: 6c 77 61 79 73 20 63 61 6c 6c 20 78 43 6c 6f 73  lways call xClos
6f30: 65 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  e once for each 
6f40: 63 75 72 73 6f 72 20 6f 70 65 6e 65 64 0d 0a 20  cursor opened.. 
6f50: 20 20 20 20 20 20 20 2f 2f 2f 20 75 73 69 6e 67         /// using
6f60: 20 78 4f 70 65 6e 2e 0d 0a 20 20 20 20 20 20 20   xOpen...       
6f70: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
6f80: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
6f90: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
6fa0: 69 73 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 72  is method must r
6fb0: 65 6c 65 61 73 65 20 61 6c 6c 20 72 65 73 6f 75  elease all resou
6fc0: 72 63 65 73 20 61 6c 6c 6f 63 61 74 65 64 20 62  rces allocated b
6fd0: 79 20 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f  y the..        /
6fe0: 2f 2f 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  // corresponding
6ff0: 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 20 54 68 65   xOpen call. The
7000: 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 6e 6f   routine will no
7010: 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
7020: 6e 20 65 76 65 6e 0d 0a 20 20 20 20 20 20 20 20  n even..        
7030: 2f 2f 2f 20 69 66 20 69 74 20 72 65 74 75 72 6e  /// if it return
7040: 73 20 61 6e 20 65 72 72 6f 72 2e 20 54 68 65 20  s an error. The 
7050: 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c  SQLite core will
7060: 20 6e 6f 74 20 75 73 65 20 74 68 65 0d 0a 20 20   not use the..  
7070: 20 20 20 20 20 20 2f 2f 2f 20 73 71 6c 69 74 65        /// sqlite
7080: 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 61 67  3_vtab_cursor ag
7090: 61 69 6e 20 61 66 74 65 72 20 69 74 20 68 61 73  ain after it has
70a0: 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0d 0a 20   been closed... 
70b0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
70c0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
70d0: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
70e0: 2f 2f 2f 20 54 68 65 20 78 43 6c 6f 73 65 20 6d  /// The xClose m
70f0: 65 74 68 6f 64 20 69 73 20 72 65 71 75 69 72 65  ethod is require
7100: 64 20 66 6f 72 20 65 76 65 72 79 20 76 69 72 74  d for every virt
7110: 75 61 6c 20 74 61 62 6c 65 0d 0a 20 20 20 20 20  ual table..     
7120: 20 20 20 2f 2f 2f 20 69 6d 70 6c 65 6d 65 6e 74     /// implement
7130: 61 74 69 6f 6e 2e 0d 0a 20 20 20 20 20 20 20 20  ation...        
7140: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
7150: 20 20 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61       /// </summa
7160: 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ry>..        ///
7170: 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 43   <param name="pC
7180: 75 72 73 6f 72 22 3e 0d 0a 20 20 20 20 20 20 20  ursor">..       
7190: 20 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76 65 20   /// The native 
71a0: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73  pointer to the s
71b0: 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
71c0: 6f 72 20 64 65 72 69 76 65 64 20 73 74 72 75 63  or derived struc
71d0: 74 75 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f  ture...        /
71e0: 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20  // </param>..   
71f0: 20 20 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72 6e       /// <return
7200: 73 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  s>..        /// 
7210: 41 20 73 74 61 6e 64 61 72 64 20 53 51 4c 69 74  A standard SQLit
7220: 65 20 72 65 74 75 72 6e 20 63 6f 64 65 2e 0d 0a  e return code...
7230: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72 65          /// </re
7240: 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20  turns>..        
7250: 53 51 4c 69 74 65 45 72 72 6f 72 43 6f 64 65 20  SQLiteErrorCode 
7260: 78 43 6c 6f 73 65 28 0d 0a 20 20 20 20 20 20 20  xClose(..       
7270: 20 20 20 20 20 49 6e 74 50 74 72 20 70 43 75 72       IntPtr pCur
7280: 73 6f 72 0d 0a 20 20 20 20 20 20 20 20 20 20 20  sor..           
7290: 20 29 3b 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f   );....        /
72a0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
72b0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
72c0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
72d0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
72e0: 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 20 20  //////....      
72f0: 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d    /// <summary>.
7300: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
7310: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
7320: 20 54 68 69 73 20 6d 65 74 68 6f 64 20 62 65 67   This method beg
7330: 69 6e 73 20 61 20 73 65 61 72 63 68 20 6f 66 20  ins a search of 
7340: 61 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e  a virtual table.
7350: 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
7360: 65 6e 74 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ent..        ///
7370: 20 69 73 20 61 20 63 75 72 73 6f 72 20 6f 70 65   is a cursor ope
7380: 6e 65 64 20 62 79 20 78 4f 70 65 6e 2e 20 54 68  ned by xOpen. Th
7390: 65 20 6e 65 78 74 20 74 77 6f 20 61 72 67 75 6d  e next two argum
73a0: 65 6e 74 20 64 65 66 69 6e 65 20 61 0d 0a 20 20  ent define a..  
73b0: 20 20 20 20 20 20 2f 2f 2f 20 70 61 72 74 69 63        /// partic
73c0: 75 6c 61 72 20 73 65 61 72 63 68 20 69 6e 64 65  ular search inde
73d0: 78 20 70 72 65 76 69 6f 75 73 6c 79 20 63 68 6f  x previously cho
73e0: 73 65 6e 20 62 79 20 78 42 65 73 74 49 6e 64 65  sen by xBestInde
73f0: 78 2e 20 54 68 65 0d 0a 20 20 20 20 20 20 20 20  x. The..        
7400: 2f 2f 2f 20 73 70 65 63 69 66 69 63 20 6d 65 61  /// specific mea
7410: 6e 69 6e 67 73 20 6f 66 20 69 64 78 4e 75 6d 20  nings of idxNum 
7420: 61 6e 64 20 69 64 78 53 74 72 20 61 72 65 20 75  and idxStr are u
7430: 6e 69 6d 70 6f 72 74 61 6e 74 20 61 73 20 6c 6f  nimportant as lo
7440: 6e 67 20 61 73 0d 0a 20 20 20 20 20 20 20 20 2f  ng as..        /
7450: 2f 2f 20 78 46 69 6c 74 65 72 20 61 6e 64 20 78  // xFilter and x
7460: 42 65 73 74 49 6e 64 65 78 20 61 67 72 65 65 20  BestIndex agree 
7470: 6f 6e 20 77 68 61 74 20 74 68 61 74 20 6d 65 61  on what that mea
7480: 6e 69 6e 67 20 69 73 2e 0d 0a 20 20 20 20 20 20  ning is...      
7490: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
74a0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
74b0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54  >..        /// T
74c0: 68 65 20 78 42 65 73 74 49 6e 64 65 78 20 66 75  he xBestIndex fu
74d0: 6e 63 74 69 6f 6e 20 6d 61 79 20 68 61 76 65 20  nction may have 
74e0: 72 65 71 75 65 73 74 65 64 20 74 68 65 20 76 61  requested the va
74f0: 6c 75 65 73 20 6f 66 20 63 65 72 74 61 69 6e 0d  lues of certain.
7500: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 65 78 70  .        /// exp
7510: 72 65 73 73 69 6f 6e 73 20 75 73 69 6e 67 20 74  ressions using t
7520: 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73  he aConstraintUs
7530: 61 67 65 5b 5d 2e 61 72 67 76 49 6e 64 65 78 20  age[].argvIndex 
7540: 76 61 6c 75 65 73 20 6f 66 20 74 68 65 0d 0a 20  values of the.. 
7550: 20 20 20 20 20 20 20 2f 2f 2f 20 73 71 6c 69 74         /// sqlit
7560: 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74  e3_index_info st
7570: 72 75 63 74 75 72 65 2e 20 54 68 6f 73 65 20 76  ructure. Those v
7580: 61 6c 75 65 73 20 61 72 65 20 70 61 73 73 65 64  alues are passed
7590: 20 74 6f 20 78 46 69 6c 74 65 72 0d 0a 20 20 20   to xFilter..   
75a0: 20 20 20 20 20 2f 2f 2f 20 75 73 69 6e 67 20 74       /// using t
75b0: 68 65 20 61 72 67 63 20 61 6e 64 20 61 72 67 76  he argc and argv
75c0: 20 70 61 72 61 6d 65 74 65 72 73 2e 0d 0a 20 20   parameters...  
75d0: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61        /// </para
75e0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
75f0: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
7600: 2f 2f 20 49 66 20 74 68 65 20 76 69 72 74 75 61  // If the virtua
7610: 6c 20 74 61 62 6c 65 20 63 6f 6e 74 61 69 6e 73  l table contains
7620: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 72 6f 77   one or more row
7630: 73 20 74 68 61 74 20 6d 61 74 63 68 20 74 68 65  s that match the
7640: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 65  ..        /// se
7650: 61 72 63 68 20 63 72 69 74 65 72 69 61 2c 20 74  arch criteria, t
7660: 68 65 6e 20 74 68 65 20 63 75 72 73 6f 72 20 6d  hen the cursor m
7670: 75 73 74 20 62 65 20 6c 65 66 74 20 70 6f 69 6e  ust be left poin
7680: 74 20 61 74 20 74 68 65 20 66 69 72 73 74 0d 0a  t at the first..
7690: 20 20 20 20 20 20 20 20 2f 2f 2f 20 72 6f 77 2e          /// row.
76a0: 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   Subsequent call
76b0: 73 20 74 6f 20 78 45 6f 66 20 6d 75 73 74 20 72  s to xEof must r
76c0: 65 74 75 72 6e 20 66 61 6c 73 65 20 28 7a 65 72  eturn false (zer
76d0: 6f 29 2e 20 49 66 20 74 68 65 72 65 0d 0a 20 20  o). If there..  
76e0: 20 20 20 20 20 20 2f 2f 2f 20 61 72 65 20 6e 6f        /// are no
76f0: 20 72 6f 77 73 20 6d 61 74 63 68 2c 20 74 68 65   rows match, the
7700: 6e 20 74 68 65 20 63 75 72 73 6f 72 20 6d 75 73  n the cursor mus
7710: 74 20 62 65 20 6c 65 66 74 20 69 6e 20 61 20 73  t be left in a s
7720: 74 61 74 65 20 74 68 61 74 0d 0a 20 20 20 20 20  tate that..     
7730: 20 20 20 2f 2f 2f 20 77 69 6c 6c 20 63 61 75 73     /// will caus
7740: 65 20 74 68 65 20 78 45 6f 66 20 74 6f 20 72 65  e the xEof to re
7750: 74 75 72 6e 20 74 72 75 65 20 28 6e 6f 6e 2d 7a  turn true (non-z
7760: 65 72 6f 29 2e 20 54 68 65 20 53 51 4c 69 74 65  ero). The SQLite
7770: 20 65 6e 67 69 6e 65 0d 0a 20 20 20 20 20 20 20   engine..       
7780: 20 2f 2f 2f 20 77 69 6c 6c 20 75 73 65 20 74 68   /// will use th
7790: 65 20 78 43 6f 6c 75 6d 6e 20 61 6e 64 20 78 52  e xColumn and xR
77a0: 6f 77 69 64 20 6d 65 74 68 6f 64 73 20 74 6f 20  owid methods to 
77b0: 61 63 63 65 73 73 20 74 68 61 74 20 72 6f 77 20  access that row 
77c0: 63 6f 6e 74 65 6e 74 2e 0d 0a 20 20 20 20 20 20  content...      
77d0: 20 20 2f 2f 2f 20 54 68 65 20 78 4e 65 78 74 20    /// The xNext 
77e0: 6d 65 74 68 6f 64 20 77 69 6c 6c 20 62 65 20 75  method will be u
77f0: 73 65 64 20 74 6f 20 61 64 76 61 6e 63 65 20 74  sed to advance t
7800: 6f 20 74 68 65 20 6e 65 78 74 20 72 6f 77 2e 0d  o the next row..
7810: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
7820: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
7830: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
7840: 20 20 2f 2f 2f 20 54 68 69 73 20 6d 65 74 68 6f    /// This metho
7850: 64 20 6d 75 73 74 20 72 65 74 75 72 6e 20 53 51  d must return SQ
7860: 4c 49 54 45 5f 4f 4b 20 69 66 20 73 75 63 63 65  LITE_OK if succe
7870: 73 73 66 75 6c 2c 20 6f 72 20 61 6e 20 73 71 6c  ssful, or an sql
7880: 69 74 65 20 65 72 72 6f 72 0d 0a 20 20 20 20 20  ite error..     
7890: 20 20 20 2f 2f 2f 20 63 6f 64 65 20 69 66 20 61     /// code if a
78a0: 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0d  n error occurs..
78b0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
78c0: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
78d0: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
78e0: 20 20 2f 2f 2f 20 54 68 65 20 78 46 69 6c 74 65    /// The xFilte
78f0: 72 20 6d 65 74 68 6f 64 20 69 73 20 72 65 71 75  r method is requ
7900: 69 72 65 64 20 66 6f 72 20 65 76 65 72 79 20 76  ired for every v
7910: 69 72 74 75 61 6c 20 74 61 62 6c 65 0d 0a 20 20  irtual table..  
7920: 20 20 20 20 20 20 2f 2f 2f 20 69 6d 70 6c 65 6d        /// implem
7930: 65 6e 74 61 74 69 6f 6e 2e 0d 0a 20 20 20 20 20  entation...     
7940: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a     /// </para>..
7950: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 73 75          /// </su
7960: 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20  mmary>..        
7970: 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d  /// <param name=
7980: 22 70 43 75 72 73 6f 72 22 3e 0d 0a 20 20 20 20  "pCursor">..    
7990: 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e 61 74 69      /// The nati
79a0: 76 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  ve pointer to th
79b0: 65 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  e sqlite3_vtab_c
79c0: 75 72 73 6f 72 20 64 65 72 69 76 65 64 20 73 74  ursor derived st
79d0: 72 75 63 74 75 72 65 2e 0d 0a 20 20 20 20 20 20  ructure...      
79e0: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a    /// </param>..
79f0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
7a00: 61 6d 20 6e 61 6d 65 3d 22 69 64 78 4e 75 6d 22  am name="idxNum"
7a10: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 4e  >..        /// N
7a20: 75 6d 62 65 72 20 75 73 65 64 20 74 6f 20 68 65  umber used to he
7a30: 6c 70 20 69 64 65 6e 74 69 66 79 20 74 68 65 20  lp identify the 
7a40: 73 65 6c 65 63 74 65 64 20 69 6e 64 65 78 2e 0d  selected index..
7a50: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
7a60: 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f  aram>..        /
7a70: 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22  // <param name="
7a80: 69 64 78 53 74 72 22 3e 0d 0a 20 20 20 20 20 20  idxStr">..      
7a90: 20 20 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76 65    /// The native
7aa0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
7ab0: 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 73 74  UTF-8 encoded st
7ac0: 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ring containing 
7ad0: 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  the..        ///
7ae0: 20 73 74 72 69 6e 67 20 75 73 65 64 20 74 6f 20   string used to 
7af0: 68 65 6c 70 20 69 64 65 6e 74 69 66 79 20 74 68  help identify th
7b00: 65 20 73 65 6c 65 63 74 65 64 20 69 6e 64 65 78  e selected index
7b10: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
7b20: 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20  /param>..       
7b30: 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65   /// <param name
7b40: 3d 22 61 72 67 63 22 3e 0d 0a 20 20 20 20 20 20  ="argc">..      
7b50: 20 20 2f 2f 2f 20 54 68 65 20 6e 75 6d 62 65 72    /// The number
7b60: 20 6f 66 20 6e 61 74 69 76 65 20 70 6f 69 6e 74   of native point
7b70: 65 72 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 76  ers to sqlite3_v
7b80: 61 6c 75 65 20 73 74 72 75 63 74 75 72 65 73 20  alue structures 
7b90: 73 70 65 63 69 66 69 65 64 0d 0a 20 20 20 20 20  specified..     
7ba0: 20 20 20 2f 2f 2f 20 69 6e 20 3c 70 61 72 61 6d     /// in <param
7bb0: 72 65 66 20 6e 61 6d 65 3d 22 61 72 67 76 22 20  ref name="argv" 
7bc0: 2f 3e 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  />...        ///
7bd0: 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20   </param>..     
7be0: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61     /// <param na
7bf0: 6d 65 3d 22 61 72 67 76 22 3e 0d 0a 20 20 20 20  me="argv">..    
7c00: 20 20 20 20 2f 2f 2f 20 41 6e 20 61 72 72 61 79      /// An array
7c10: 20 6f 66 20 6e 61 74 69 76 65 20 70 6f 69 6e 74   of native point
7c20: 65 72 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 76  ers to sqlite3_v
7c30: 61 6c 75 65 20 73 74 72 75 63 74 75 72 65 73 20  alue structures 
7c40: 63 6f 6e 74 61 69 6e 69 6e 67 0d 0a 20 20 20 20  containing..    
7c50: 20 20 20 20 2f 2f 2f 20 66 69 6c 74 65 72 69 6e      /// filterin
7c60: 67 20 63 72 69 74 65 72 69 61 20 66 6f 72 20 74  g criteria for t
7c70: 68 65 20 73 65 6c 65 63 74 65 64 20 69 6e 64 65  he selected inde
7c80: 78 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  x...        /// 
7c90: 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20  </param>..      
7ca0: 20 20 2f 2f 2f 20 3c 72 65 74 75 72 6e 73 3e 0d    /// <returns>.
7cb0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 20 73  .        /// A s
7cc0: 74 61 6e 64 61 72 64 20 53 51 4c 69 74 65 20 72  tandard SQLite r
7cd0: 65 74 75 72 6e 20 63 6f 64 65 2e 0d 0a 20 20 20  eturn code...   
7ce0: 20 20 20 20 20 2f 2f 2f 20 3c 2f 72 65 74 75 72       /// </retur
7cf0: 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 53 51 4c  ns>..        SQL
7d00: 69 74 65 45 72 72 6f 72 43 6f 64 65 20 78 46 69  iteErrorCode xFi
7d10: 6c 74 65 72 28 0d 0a 20 20 20 20 20 20 20 20 20  lter(..         
7d20: 20 20 20 49 6e 74 50 74 72 20 70 43 75 72 73 6f     IntPtr pCurso
7d30: 72 2c 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20  r,..            
7d40: 69 6e 74 20 69 64 78 4e 75 6d 2c 0d 0a 20 20 20  int idxNum,..   
7d50: 20 20 20 20 20 20 20 20 20 49 6e 74 50 74 72 20           IntPtr 
7d60: 69 64 78 53 74 72 2c 0d 0a 20 20 20 20 20 20 20  idxStr,..       
7d70: 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 0d 0a       int argc,..
7d80: 20 20 20 20 20 20 20 20 20 20 20 20 49 6e 74 50              IntP
7d90: 74 72 20 61 72 67 76 0d 0a 20 20 20 20 20 20 20  tr argv..       
7da0: 20 20 20 20 20 29 3b 0d 0a 0d 0a 20 20 20 20 20       );....     
7db0: 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f     /////////////
7dc0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
7dd0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
7de0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
7df0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20  //////////....  
7e00: 20 20 20 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61        /// <summa
7e10: 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ry>..        ///
7e20: 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20   <para>..       
7e30: 20 2f 2f 2f 20 54 68 65 20 78 4e 65 78 74 20 6d   /// The xNext m
7e40: 65 74 68 6f 64 20 61 64 76 61 6e 63 65 73 20 61  ethod advances a
7e50: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 63   virtual table c
7e60: 75 72 73 6f 72 20 74 6f 20 74 68 65 20 6e 65 78  ursor to the nex
7e70: 74 20 72 6f 77 20 6f 66 0d 0a 20 20 20 20 20 20  t row of..      
7e80: 20 20 2f 2f 2f 20 61 20 72 65 73 75 6c 74 20 73    /// a result s
7e90: 65 74 20 69 6e 69 74 69 61 74 65 64 20 62 79 20  et initiated by 
7ea0: 78 46 69 6c 74 65 72 2e 20 49 66 20 74 68 65 20  xFilter. If the 
7eb0: 63 75 72 73 6f 72 20 69 73 20 61 6c 72 65 61 64  cursor is alread
7ec0: 79 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 70  y..        /// p
7ed0: 6f 69 6e 74 69 6e 67 20 61 74 20 74 68 65 20 6c  ointing at the l
7ee0: 61 73 74 20 72 6f 77 20 77 68 65 6e 20 74 68 69  ast row when thi
7ef0: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  s routine is cal
7f00: 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 0d 0a 20  led, then the.. 
7f10: 20 20 20 20 20 20 20 2f 2f 2f 20 63 75 72 73 6f         /// curso
7f20: 72 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 6f 69 6e  r no longer poin
7f30: 74 73 20 74 6f 20 76 61 6c 69 64 20 64 61 74 61  ts to valid data
7f40: 20 61 6e 64 20 61 20 73 75 62 73 65 71 75 65 6e   and a subsequen
7f50: 74 20 63 61 6c 6c 20 74 6f 20 74 68 65 0d 0a 20  t call to the.. 
7f60: 20 20 20 20 20 20 20 2f 2f 2f 20 78 45 6f 66 20         /// xEof 
7f70: 6d 65 74 68 6f 64 20 6d 75 73 74 20 72 65 74 75  method must retu
7f80: 72 6e 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  rn true (non-zer
7f90: 6f 29 2e 20 49 66 20 74 68 65 20 63 75 72 73 6f  o). If the curso
7fa0: 72 20 69 73 0d 0a 20 20 20 20 20 20 20 20 2f 2f  r is..        //
7fb0: 2f 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 61  / successfully a
7fc0: 64 76 61 6e 63 65 64 20 74 6f 20 61 6e 6f 74 68  dvanced to anoth
7fd0: 65 72 20 72 6f 77 20 6f 66 20 63 6f 6e 74 65 6e  er row of conten
7fe0: 74 2c 20 74 68 65 6e 20 73 75 62 73 65 71 75 65  t, then subseque
7ff0: 6e 74 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  nt..        /// 
8000: 63 61 6c 6c 73 20 74 6f 20 78 45 6f 66 20 6d 75  calls to xEof mu
8010: 73 74 20 72 65 74 75 72 6e 20 66 61 6c 73 65 20  st return false 
8020: 28 7a 65 72 6f 29 2e 0d 0a 20 20 20 20 20 20 20  (zero)...       
8030: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
8040: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
8050: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
8060: 69 73 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 72  is method must r
8070: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
8080: 69 66 20 73 75 63 63 65 73 73 66 75 6c 2c 20 6f  if successful, o
8090: 72 20 61 6e 20 73 71 6c 69 74 65 20 65 72 72 6f  r an sqlite erro
80a0: 72 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 63  r..        /// c
80b0: 6f 64 65 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ode if an error 
80c0: 6f 63 63 75 72 73 2e 0d 0a 20 20 20 20 20 20 20  occurs...       
80d0: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
80e0: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
80f0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
8100: 65 20 78 4e 65 78 74 20 6d 65 74 68 6f 64 20 69  e xNext method i
8110: 73 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 65  s required for e
8120: 76 65 72 79 20 76 69 72 74 75 61 6c 20 74 61 62  very virtual tab
8130: 6c 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  le..        /// 
8140: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0d  implementation..
8150: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
8160: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
8170: 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a 20 20  / </summary>..  
8180: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d        /// <param
8190: 20 6e 61 6d 65 3d 22 70 43 75 72 73 6f 72 22 3e   name="pCursor">
81a0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
81b0: 65 20 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72  e native pointer
81c0: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
81d0: 76 74 61 62 5f 63 75 72 73 6f 72 20 64 65 72 69  vtab_cursor deri
81e0: 76 65 64 20 73 74 72 75 63 74 75 72 65 2e 0d 0a  ved structure...
81f0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
8200: 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ram>..        //
8210: 2f 20 3c 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20  / <returns>..   
8220: 20 20 20 20 20 2f 2f 2f 20 41 20 73 74 61 6e 64       /// A stand
8230: 61 72 64 20 53 51 4c 69 74 65 20 72 65 74 75 72  ard SQLite retur
8240: 6e 20 63 6f 64 65 2e 0d 0a 20 20 20 20 20 20 20  n code...       
8250: 20 2f 2f 2f 20 3c 2f 72 65 74 75 72 6e 73 3e 0d   /// </returns>.
8260: 0a 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 45  .        SQLiteE
8270: 72 72 6f 72 43 6f 64 65 20 78 4e 65 78 74 28 0d  rrorCode xNext(.
8280: 0a 20 20 20 20 20 20 20 20 20 20 20 20 49 6e 74  .            Int
8290: 50 74 72 20 70 43 75 72 73 6f 72 0d 0a 20 20 20  Ptr pCursor..   
82a0: 20 20 20 20 20 20 20 20 20 29 3b 0d 0a 0d 0a 20           );.... 
82b0: 20 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f         /////////
82c0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
82d0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
82e0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
82f0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a  //////////////..
8300: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 73  ..        /// <s
8310: 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20  ummary>..       
8320: 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20   /// <para>..   
8330: 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 45 6f       /// The xEo
8340: 66 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 72 65  f method must re
8350: 74 75 72 6e 20 66 61 6c 73 65 20 28 7a 65 72 6f  turn false (zero
8360: 29 20 69 66 20 74 68 65 20 73 70 65 63 69 66 69  ) if the specifi
8370: 65 64 20 63 75 72 73 6f 72 0d 0a 20 20 20 20 20  ed cursor..     
8380: 20 20 20 2f 2f 2f 20 63 75 72 72 65 6e 74 6c 79     /// currently
8390: 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 76 61 6c   points to a val
83a0: 69 64 20 72 6f 77 20 6f 66 20 64 61 74 61 2c 20  id row of data, 
83b0: 6f 72 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  or true (non-zer
83c0: 6f 29 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  o)..        /// 
83d0: 6f 74 68 65 72 77 69 73 65 2e 20 54 68 69 73 20  otherwise. This 
83e0: 6d 65 74 68 6f 64 20 69 73 20 63 61 6c 6c 65 64  method is called
83f0: 20 62 79 20 74 68 65 20 53 51 4c 20 65 6e 67 69   by the SQL engi
8400: 6e 65 20 69 6d 6d 65 64 69 61 74 65 6c 79 0d 0a  ne immediately..
8410: 20 20 20 20 20 20 20 20 2f 2f 2f 20 61 66 74 65          /// afte
8420: 72 20 65 61 63 68 20 78 46 69 6c 74 65 72 20 61  r each xFilter a
8430: 6e 64 20 78 4e 65 78 74 20 69 6e 76 6f 63 61 74  nd xNext invocat
8440: 69 6f 6e 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ion...        //
8450: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  / </para>..     
8460: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20     /// <para>.. 
8470: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 78         /// The x
8480: 45 6f 66 20 6d 65 74 68 6f 64 20 69 73 20 72 65  Eof method is re
8490: 71 75 69 72 65 64 20 66 6f 72 20 65 76 65 72 79  quired for every
84a0: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
84b0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0d 0a  mplementation...
84c0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
84d0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
84e0: 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20   </summary>..   
84f0: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20       /// <param 
8500: 6e 61 6d 65 3d 22 70 43 75 72 73 6f 72 22 3e 0d  name="pCursor">.
8510: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65  .        /// The
8520: 20 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72 20   native pointer 
8530: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  to the sqlite3_v
8540: 74 61 62 5f 63 75 72 73 6f 72 20 64 65 72 69 76  tab_cursor deriv
8550: 65 64 20 73 74 72 75 63 74 75 72 65 2e 0d 0a 20  ed structure... 
8560: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
8570: 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  am>..        ///
8580: 20 3c 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20   <returns>..    
8590: 20 20 20 20 2f 2f 2f 20 4e 6f 6e 2d 7a 65 72 6f      /// Non-zero
85a0: 20 69 66 20 6e 6f 20 6d 6f 72 65 20 72 6f 77 73   if no more rows
85b0: 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 3b 20   are available; 
85c0: 7a 65 72 6f 20 6f 74 68 65 72 77 69 73 65 2e 0d  zero otherwise..
85d0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72  .        /// </r
85e0: 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20  eturns>..       
85f0: 20 69 6e 74 20 78 45 6f 66 28 0d 0a 20 20 20 20   int xEof(..    
8600: 20 20 20 20 20 20 20 20 49 6e 74 50 74 72 20 70          IntPtr p
8610: 43 75 72 73 6f 72 0d 0a 20 20 20 20 20 20 20 20  Cursor..        
8620: 20 20 20 20 29 3b 0d 0a 0d 0a 20 20 20 20 20 20      );....      
8630: 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f    //////////////
8640: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8650: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8660: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8670: 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20  /////////....   
8680: 20 20 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72       /// <summar
8690: 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  y>..        /// 
86a0: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
86b0: 2f 2f 2f 20 54 68 65 20 53 51 4c 69 74 65 20 63  /// The SQLite c
86c0: 6f 72 65 20 69 6e 76 6f 6b 65 73 20 74 68 69 73  ore invokes this
86d0: 20 6d 65 74 68 6f 64 20 69 6e 20 6f 72 64 65 72   method in order
86e0: 20 74 6f 20 66 69 6e 64 20 74 68 65 20 76 61 6c   to find the val
86f0: 75 65 20 66 6f 72 0d 0a 20 20 20 20 20 20 20 20  ue for..        
8700: 2f 2f 2f 20 74 68 65 20 4e 2d 74 68 20 63 6f 6c  /// the N-th col
8710: 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  umn of the curre
8720: 6e 74 20 72 6f 77 2e 20 4e 20 69 73 20 7a 65 72  nt row. N is zer
8730: 6f 2d 62 61 73 65 64 20 73 6f 20 74 68 65 20 66  o-based so the f
8740: 69 72 73 74 0d 0a 20 20 20 20 20 20 20 20 2f 2f  irst..        //
8750: 2f 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62  / column is numb
8760: 65 72 65 64 20 30 2e 20 54 68 65 20 78 43 6f 6c  ered 0. The xCol
8770: 75 6d 6e 20 6d 65 74 68 6f 64 20 6d 61 79 20 72  umn method may r
8780: 65 74 75 72 6e 20 69 74 73 20 72 65 73 75 6c 74  eturn its result
8790: 20 62 61 63 6b 0d 0a 20 20 20 20 20 20 20 20 2f   back..        /
87a0: 2f 2f 20 74 6f 20 53 51 4c 69 74 65 20 75 73 69  // to SQLite usi
87b0: 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  ng one of the fo
87c0: 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63  llowing interfac
87d0: 65 3a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e:..        /// 
87e0: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
87f0: 20 2f 2f 2f 20 3c 63 6f 64 65 3e 0d 0a 20 20 20   /// <code>..   
8800: 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 73 71 6c       ///     sql
8810: 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
8820: 28 29 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ()..        /// 
8830: 20 20 20 20 73 71 6c 69 74 65 33 5f 72 65 73 75      sqlite3_resu
8840: 6c 74 5f 64 6f 75 62 6c 65 28 29 0d 0a 20 20 20  lt_double()..   
8850: 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 73 71 6c       ///     sql
8860: 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
8870: 29 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20  )..        ///  
8880: 20 20 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c     sqlite3_resul
8890: 74 5f 69 6e 74 36 34 28 29 0d 0a 20 20 20 20 20  t_int64()..     
88a0: 20 20 20 2f 2f 2f 20 20 20 20 20 73 71 6c 69 74     ///     sqlit
88b0: 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29  e3_result_null()
88c0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20  ..        ///   
88d0: 20 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74    sqlite3_result
88e0: 5f 74 65 78 74 28 29 0d 0a 20 20 20 20 20 20 20  _text()..       
88f0: 20 2f 2f 2f 20 20 20 20 20 73 71 6c 69 74 65 33   ///     sqlite3
8900: 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29  _result_text16()
8910: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20  ..        ///   
8920: 20 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74    sqlite3_result
8930: 5f 74 65 78 74 31 36 6c 65 28 29 0d 0a 20 20 20  _text16le()..   
8940: 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 73 71 6c       ///     sql
8950: 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
8960: 31 36 62 65 28 29 0d 0a 20 20 20 20 20 20 20 20  16be()..        
8970: 2f 2f 2f 20 20 20 20 20 73 71 6c 69 74 65 33 5f  ///     sqlite3_
8980: 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
8990: 29 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  )..        /// <
89a0: 2f 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20 20  /code>..        
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 49 66 20 74 68 65 20 78      /// If the x
89d0: 43 6f 6c 75 6d 6e 20 6d 65 74 68 6f 64 20 69 6d  Column method im
89e0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6c  plementation cal
89f0: 6c 73 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 66  ls none of the f
8a00: 75 6e 63 74 69 6f 6e 73 0d 0a 20 20 20 20 20 20  unctions..      
8a10: 20 20 2f 2f 2f 20 61 62 6f 76 65 2c 20 74 68 65    /// above, the
8a20: 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  n the value of t
8a30: 68 65 20 63 6f 6c 75 6d 6e 20 64 65 66 61 75 6c  he column defaul
8a40: 74 73 20 74 6f 20 61 6e 20 53 51 4c 20 4e 55 4c  ts to an SQL NUL
8a50: 4c 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  L...        /// 
8a60: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
8a70: 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20   /// <para>..   
8a80: 20 20 20 20 20 2f 2f 2f 20 54 6f 20 72 61 69 73       /// To rais
8a90: 65 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 20  e an error, the 
8aa0: 78 43 6f 6c 75 6d 6e 20 6d 65 74 68 6f 64 20 73  xColumn method s
8ab0: 68 6f 75 6c 64 20 75 73 65 20 6f 6e 65 20 6f 66  hould use one of
8ac0: 20 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f   the..        //
8ad0: 2f 20 72 65 73 75 6c 74 5f 74 65 78 74 28 29 20  / result_text() 
8ae0: 6d 65 74 68 6f 64 73 20 74 6f 20 73 65 74 20 74  methods to set t
8af0: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
8b00: 20 74 65 78 74 2c 20 74 68 65 6e 20 72 65 74 75   text, then retu
8b10: 72 6e 20 61 6e 0d 0a 20 20 20 20 20 20 20 20 2f  rn an..        /
8b20: 2f 2f 20 61 70 70 72 6f 70 72 69 61 74 65 20 65  // appropriate e
8b30: 72 72 6f 72 20 63 6f 64 65 2e 20 54 68 65 20 78  rror code. The x
8b40: 43 6f 6c 75 6d 6e 20 6d 65 74 68 6f 64 20 6d 75  Column method mu
8b50: 73 74 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  st return SQLITE
8b60: 5f 4f 4b 20 6f 6e 0d 0a 20 20 20 20 20 20 20 20  _OK on..        
8b70: 2f 2f 2f 20 73 75 63 63 65 73 73 2e 0d 0a 20 20  /// success...  
8b80: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61        /// </para
8b90: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
8ba0: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
8bb0: 2f 2f 20 54 68 65 20 78 43 6f 6c 75 6d 6e 20 6d  // The xColumn m
8bc0: 65 74 68 6f 64 20 69 73 20 72 65 71 75 69 72 65  ethod is require
8bd0: 64 20 66 6f 72 20 65 76 65 72 79 20 76 69 72 74  d for every virt
8be0: 75 61 6c 20 74 61 62 6c 65 0d 0a 20 20 20 20 20  ual table..     
8bf0: 20 20 20 2f 2f 2f 20 69 6d 70 6c 65 6d 65 6e 74     /// implement
8c00: 61 74 69 6f 6e 2e 0d 0a 20 20 20 20 20 20 20 20  ation...        
8c10: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
8c20: 20 20 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61       /// </summa
8c30: 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ry>..        ///
8c40: 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 43   <param name="pC
8c50: 75 72 73 6f 72 22 3e 0d 0a 20 20 20 20 20 20 20  ursor">..       
8c60: 20 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76 65 20   /// The native 
8c70: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73  pointer to the s
8c80: 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
8c90: 6f 72 20 64 65 72 69 76 65 64 20 73 74 72 75 63  or derived struc
8ca0: 74 75 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f  ture...        /
8cb0: 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20  // </param>..   
8cc0: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20       /// <param 
8cd0: 6e 61 6d 65 3d 22 70 43 6f 6e 74 65 78 74 22 3e  name="pContext">
8ce0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
8cf0: 65 20 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72  e native pointer
8d00: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
8d10: 63 6f 6e 74 65 78 74 20 73 74 72 75 63 74 75 72  context structur
8d20: 65 20 74 6f 20 62 65 20 75 73 65 64 0d 0a 20 20  e to be used..  
8d30: 20 20 20 20 20 20 2f 2f 2f 20 66 6f 72 20 72 65        /// for re
8d40: 74 75 72 6e 69 6e 67 20 74 68 65 20 73 70 65 63  turning the spec
8d50: 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 76 61 6c  ified column val
8d60: 75 65 20 74 6f 20 74 68 65 20 53 51 4c 69 74 65  ue to the SQLite
8d70: 20 63 6f 72 65 0d 0a 20 20 20 20 20 20 20 20 2f   core..        /
8d80: 2f 2f 20 6c 69 62 72 61 72 79 2e 0d 0a 20 20 20  // library...   
8d90: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d       /// </param
8da0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
8db0: 70 61 72 61 6d 20 6e 61 6d 65 3d 22 69 6e 64 65  param name="inde
8dc0: 78 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  x">..        ///
8dd0: 20 54 68 65 20 7a 65 72 6f 2d 62 61 73 65 64 20   The zero-based 
8de0: 69 6e 64 65 78 20 63 6f 72 72 65 73 70 6f 6e 64  index correspond
8df0: 69 6e 67 20 74 6f 20 74 68 65 20 63 6f 6c 75 6d  ing to the colum
8e00: 6e 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  n containing the
8e10: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 76 61  ..        /// va
8e20: 6c 75 65 20 74 6f 20 62 65 20 72 65 74 75 72 6e  lue to be return
8e30: 65 64 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ed...        ///
8e40: 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20   </param>..     
8e50: 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72 6e 73 3e     /// <returns>
8e60: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 20  ..        /// A 
8e70: 73 74 61 6e 64 61 72 64 20 53 51 4c 69 74 65 20  standard SQLite 
8e80: 72 65 74 75 72 6e 20 63 6f 64 65 2e 0d 0a 20 20  return code...  
8e90: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72 65 74 75        /// </retu
8ea0: 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 53 51  rns>..        SQ
8eb0: 4c 69 74 65 45 72 72 6f 72 43 6f 64 65 20 78 43  LiteErrorCode xC
8ec0: 6f 6c 75 6d 6e 28 0d 0a 20 20 20 20 20 20 20 20  olumn(..        
8ed0: 20 20 20 20 49 6e 74 50 74 72 20 70 43 75 72 73      IntPtr pCurs
8ee0: 6f 72 2c 0d 0a 20 20 20 20 20 20 20 20 20 20 20  or,..           
8ef0: 20 49 6e 74 50 74 72 20 70 43 6f 6e 74 65 78 74   IntPtr pContext
8f00: 2c 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 69  ,..            i
8f10: 6e 74 20 69 6e 64 65 78 0d 0a 20 20 20 20 20 20  nt index..      
8f20: 20 20 20 20 20 20 29 3b 0d 0a 0d 0a 20 20 20 20        );....    
8f30: 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f      ////////////
8f40: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8f50: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8f60: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8f70: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20  ///////////.... 
8f80: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d         /// <summ
8f90: 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ary>..        //
8fa0: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
8fb0: 20 20 2f 2f 2f 20 41 20 73 75 63 63 65 73 73 66    /// A successf
8fc0: 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ul invocation of
8fd0: 20 74 68 69 73 20 6d 65 74 68 6f 64 20 77 69 6c   this method wil
8fe0: 6c 20 63 61 75 73 65 20 2a 70 52 6f 77 69 64 20  l cause *pRowid 
8ff0: 74 6f 20 62 65 0d 0a 20 20 20 20 20 20 20 20 2f  to be..        /
9000: 2f 2f 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  // filled with t
9010: 68 65 20 72 6f 77 69 64 20 6f 66 20 72 6f 77 20  he rowid of row 
9020: 74 68 61 74 20 74 68 65 20 76 69 72 74 75 61 6c  that the virtual
9030: 20 74 61 62 6c 65 20 63 75 72 73 6f 72 20 70 43   table cursor pC
9040: 75 72 20 69 73 0d 0a 20 20 20 20 20 20 20 20 2f  ur is..        /
9050: 2f 2f 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69  // currently poi
9060: 6e 74 69 6e 67 20 61 74 2e 20 54 68 69 73 20 6d  nting at. This m
9070: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 53 51  ethod returns SQ
9080: 4c 49 54 45 5f 4f 4b 20 6f 6e 20 73 75 63 63 65  LITE_OK on succe
9090: 73 73 2e 20 49 74 0d 0a 20 20 20 20 20 20 20 20  ss. It..        
90a0: 2f 2f 2f 20 72 65 74 75 72 6e 73 20 61 6e 20 61  /// returns an a
90b0: 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72  ppropriate error
90c0: 20 63 6f 64 65 20 6f 6e 20 66 61 69 6c 75 72 65   code on failure
90d0: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
90e0: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
90f0: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20  /// <para>..    
9100: 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 52 6f 77      /// The xRow
9110: 69 64 20 6d 65 74 68 6f 64 20 69 73 20 72 65 71  id method is req
9120: 75 69 72 65 64 20 66 6f 72 20 65 76 65 72 79 20  uired for every 
9130: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 0d 0a 20  virtual table.. 
9140: 20 20 20 20 20 20 20 2f 2f 2f 20 69 6d 70 6c 65         /// imple
9150: 6d 65 6e 74 61 74 69 6f 6e 2e 0d 0a 20 20 20 20  mentation...    
9160: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
9170: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 73  .        /// </s
9180: 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20  ummary>..       
9190: 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65   /// <param name
91a0: 3d 22 70 43 75 72 73 6f 72 22 3e 0d 0a 20 20 20  ="pCursor">..   
91b0: 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e 61 74       /// The nat
91c0: 69 76 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  ive pointer to t
91d0: 68 65 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  he sqlite3_vtab_
91e0: 63 75 72 73 6f 72 20 64 65 72 69 76 65 64 20 73  cursor derived s
91f0: 74 72 75 63 74 75 72 65 2e 0d 0a 20 20 20 20 20  tructure...     
9200: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d     /// </param>.
9210: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
9220: 72 61 6d 20 6e 61 6d 65 3d 22 72 6f 77 49 64 22  ram name="rowId"
9230: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 55  >..        /// U
9240: 70 6f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 69  pon success, thi
9250: 73 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  s parameter must
9260: 20 62 65 20 6d 6f 64 69 66 69 65 64 20 74 6f 20   be modified to 
9270: 63 6f 6e 74 61 69 6e 20 74 68 65 20 75 6e 69 71  contain the uniq
9280: 75 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ue..        /// 
9290: 69 6e 74 65 67 65 72 20 72 6f 77 20 69 64 65 6e  integer row iden
92a0: 74 69 66 69 65 72 20 66 6f 72 20 74 68 65 20 63  tifier for the c
92b0: 75 72 72 65 6e 74 20 72 6f 77 20 66 6f 72 20 74  urrent row for t
92c0: 68 65 20 73 70 65 63 69 66 69 65 64 20 63 75 72  he specified cur
92d0: 73 6f 72 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  sor...        //
92e0: 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20  / </param>..    
92f0: 20 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72 6e 73      /// <returns
9300: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41  >..        /// A
9310: 20 73 74 61 6e 64 61 72 64 20 53 51 4c 69 74 65   standard SQLite
9320: 20 72 65 74 75 72 6e 20 63 6f 64 65 2e 0d 0a 20   return code... 
9330: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72 65 74         /// </ret
9340: 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 53  urns>..        S
9350: 51 4c 69 74 65 45 72 72 6f 72 43 6f 64 65 20 78  QLiteErrorCode x
9360: 52 6f 77 49 64 28 0d 0a 20 20 20 20 20 20 20 20  RowId(..        
9370: 20 20 20 20 49 6e 74 50 74 72 20 70 43 75 72 73      IntPtr pCurs
9380: 6f 72 2c 0d 0a 20 20 20 20 20 20 20 20 20 20 20  or,..           
9390: 20 72 65 66 20 6c 6f 6e 67 20 72 6f 77 49 64 0d   ref long rowId.
93a0: 0a 20 20 20 20 20 20 20 20 20 20 20 20 29 3b 0d  .            );.
93b0: 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 2f 2f  ...        /////
93c0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
93d0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
93e0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
93f0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
9400: 2f 2f 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f  //....        //
9410: 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20  / <summary>..   
9420: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
9430: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 6c 6c  .        /// All
9440: 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69   changes to a vi
9450: 72 74 75 61 6c 20 74 61 62 6c 65 20 61 72 65 20  rtual table are 
9460: 6d 61 64 65 20 75 73 69 6e 67 20 74 68 65 20 78  made using the x
9470: 55 70 64 61 74 65 20 6d 65 74 68 6f 64 2e 0d 0a  Update method...
9480: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 69 73          /// This
9490: 20 6f 6e 65 20 6d 65 74 68 6f 64 20 63 61 6e 20   one method can 
94a0: 62 65 20 75 73 65 64 20 74 6f 20 69 6e 73 65 72  be used to inser
94b0: 74 2c 20 64 65 6c 65 74 65 2c 20 6f 72 20 75 70  t, delete, or up
94c0: 64 61 74 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f  date...        /
94d0: 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  // </para>..    
94e0: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a      /// <para>..
94f0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20          /// The 
9500: 61 72 67 63 20 70 61 72 61 6d 65 74 65 72 20 73  argc parameter s
9510: 70 65 63 69 66 69 65 73 20 74 68 65 20 6e 75 6d  pecifies the num
9520: 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20 69  ber of entries i
9530: 6e 20 74 68 65 20 61 72 67 76 0d 0a 20 20 20 20  n the argv..    
9540: 20 20 20 20 2f 2f 2f 20 61 72 72 61 79 2e 20 54      /// array. T
9550: 68 65 20 76 61 6c 75 65 20 6f 66 20 61 72 67 63  he value of argc
9560: 20 77 69 6c 6c 20 62 65 20 31 20 66 6f 72 20 61   will be 1 for a
9570: 20 70 75 72 65 20 64 65 6c 65 74 65 20 6f 70 65   pure delete ope
9580: 72 61 74 69 6f 6e 20 6f 72 0d 0a 20 20 20 20 20  ration or..     
9590: 20 20 20 2f 2f 2f 20 4e 2b 32 20 66 6f 72 20 61     /// N+2 for a
95a0: 6e 20 69 6e 73 65 72 74 20 6f 72 20 72 65 70 6c  n insert or repl
95b0: 61 63 65 20 6f 72 20 75 70 64 61 74 65 20 77 68  ace or update wh
95c0: 65 72 65 20 4e 20 69 73 20 74 68 65 20 6e 75 6d  ere N is the num
95d0: 62 65 72 20 6f 66 0d 0a 20 20 20 20 20 20 20 20  ber of..        
95e0: 2f 2f 2f 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74  /// columns in t
95f0: 68 65 20 74 61 62 6c 65 2e 20 49 6e 20 74 68 65  he table. In the
9600: 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
9610: 63 65 2c 20 4e 20 69 6e 63 6c 75 64 65 73 20 61  ce, N includes a
9620: 6e 79 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ny..        /// 
9630: 68 69 64 64 65 6e 20 63 6f 6c 75 6d 6e 73 2e 0d  hidden columns..
9640: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
9650: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
9660: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
9670: 20 20 2f 2f 2f 20 45 76 65 72 79 20 61 72 67 76    /// Every argv
9680: 20 65 6e 74 72 79 20 77 69 6c 6c 20 68 61 76 65   entry will have
9690: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 76 61 6c 75   a non-NULL valu
96a0: 65 20 69 6e 20 43 20 62 75 74 20 6d 61 79 20 63  e in C but may c
96b0: 6f 6e 74 61 69 6e 0d 0a 20 20 20 20 20 20 20 20  ontain..        
96c0: 2f 2f 2f 20 74 68 65 20 53 51 4c 20 76 61 6c 75  /// the SQL valu
96d0: 65 20 4e 55 4c 4c 2e 20 49 6e 20 6f 74 68 65 72  e NULL. In other
96e0: 20 77 6f 72 64 73 2c 20 69 74 20 69 73 20 61 6c   words, it is al
96f0: 77 61 79 73 20 74 72 75 65 20 74 68 61 74 0d 0a  ways true that..
9700: 20 20 20 20 20 20 20 20 2f 2f 2f 20 61 72 67 76          /// argv
9710: 5b 69 5d 21 3d 30 20 66 6f 72 20 69 20 62 65 74  [i]!=0 for i bet
9720: 77 65 65 6e 20 30 20 61 6e 64 20 61 72 67 63 2d  ween 0 and argc-
9730: 31 2e 20 48 6f 77 65 76 65 72 2c 20 69 74 20 6d  1. However, it m
9740: 69 67 68 74 20 62 65 20 74 68 65 0d 0a 20 20 20  ight be the..   
9750: 20 20 20 20 20 2f 2f 2f 20 63 61 73 65 20 74 68       /// case th
9760: 61 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  at sqlite3_value
9770: 5f 74 79 70 65 28 61 72 67 76 5b 69 5d 29 3d 3d  _type(argv[i])==
9780: 53 51 4c 49 54 45 5f 4e 55 4c 4c 2e 0d 0a 20 20  SQLITE_NULL...  
9790: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61        /// </para
97a0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
97b0: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
97c0: 2f 2f 20 54 68 65 20 61 72 67 76 5b 30 5d 20 70  // The argv[0] p
97d0: 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
97e0: 72 6f 77 69 64 20 6f 66 20 61 20 72 6f 77 20 69  rowid of a row i
97f0: 6e 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  n the virtual ta
9800: 62 6c 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ble..        ///
9810: 20 74 6f 20 62 65 20 64 65 6c 65 74 65 64 2e 20   to be deleted. 
9820: 49 66 20 61 72 67 76 5b 30 5d 20 69 73 20 61 6e  If argv[0] is an
9830: 20 53 51 4c 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   SQL NULL, then 
9840: 6e 6f 20 64 65 6c 65 74 69 6f 6e 20 6f 63 63 75  no deletion occu
9850: 72 73 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  rs...        ///
9860: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
9870: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
9880: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 61 72        /// The ar
9890: 67 76 5b 31 5d 20 70 61 72 61 6d 65 74 65 72 20  gv[1] parameter 
98a0: 69 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20  is the rowid of 
98b0: 61 20 6e 65 77 20 72 6f 77 20 74 6f 20 62 65 20  a new row to be 
98c0: 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0d 0a 20  inserted into.. 
98d0: 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 20 76         /// the v
98e0: 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 49 66  irtual table. If
98f0: 20 61 72 67 76 5b 31 5d 20 69 73 20 61 6e 20 53   argv[1] is an S
9900: 51 4c 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  QL NULL, then th
9910: 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69  e..        /// i
9920: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75  mplementation mu
9930: 73 74 20 63 68 6f 6f 73 65 20 61 20 72 6f 77 69  st choose a rowi
9940: 64 20 66 6f 72 20 74 68 65 20 6e 65 77 6c 79 20  d for the newly 
9950: 69 6e 73 65 72 74 65 64 20 72 6f 77 2e 0d 0a 20  inserted row... 
9960: 20 20 20 20 20 20 20 2f 2f 2f 20 53 75 62 73 65         /// Subse
9970: 71 75 65 6e 74 20 61 72 67 76 5b 5d 20 65 6e 74  quent argv[] ent
9980: 72 69 65 73 20 63 6f 6e 74 61 69 6e 20 76 61 6c  ries contain val
9990: 75 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  ues of the colum
99a0: 6e 73 20 6f 66 20 74 68 65 0d 0a 20 20 20 20 20  ns of the..     
99b0: 20 20 20 2f 2f 2f 20 76 69 72 74 75 61 6c 20 74     /// virtual t
99c0: 61 62 6c 65 2c 20 69 6e 20 74 68 65 20 6f 72 64  able, in the ord
99d0: 65 72 20 74 68 61 74 20 74 68 65 20 63 6f 6c 75  er that the colu
99e0: 6d 6e 73 20 77 65 72 65 20 64 65 63 6c 61 72 65  mns were declare
99f0: 64 2e 20 54 68 65 0d 0a 20 20 20 20 20 20 20 20  d. The..        
9a00: 2f 2f 2f 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  /// number of co
9a10: 6c 75 6d 6e 73 20 77 69 6c 6c 20 6d 61 74 63 68  lumns will match
9a20: 20 74 68 65 20 74 61 62 6c 65 20 64 65 63 6c 61   the table decla
9a30: 72 61 74 69 6f 6e 20 74 68 61 74 20 74 68 65 0d  ration that the.
9a40: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 78 43 6f  .        /// xCo
9a50: 6e 6e 65 63 74 20 6f 72 20 78 43 72 65 61 74 65  nnect or xCreate
9a60: 20 6d 65 74 68 6f 64 20 6d 61 64 65 20 75 73 69   method made usi
9a70: 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 64  ng the sqlite3_d
9a80: 65 63 6c 61 72 65 5f 76 74 61 62 28 29 0d 0a 20  eclare_vtab().. 
9a90: 20 20 20 20 20 20 20 2f 2f 2f 20 63 61 6c 6c 2e         /// call.
9aa0: 20 41 6c 6c 20 68 69 64 64 65 6e 20 63 6f 6c 75   All hidden colu
9ab0: 6d 6e 73 20 61 72 65 20 69 6e 63 6c 75 64 65 64  mns are included
9ac0: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
9ad0: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
9ae0: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20  /// <para>..    
9af0: 20 20 20 20 2f 2f 2f 20 57 68 65 6e 20 64 6f 69      /// When doi
9b00: 6e 67 20 61 6e 20 69 6e 73 65 72 74 20 77 69 74  ng an insert wit
9b10: 68 6f 75 74 20 61 20 72 6f 77 69 64 20 28 61 72  hout a rowid (ar
9b20: 67 63 3e 31 2c 20 61 72 67 76 5b 31 5d 20 69 73  gc>1, argv[1] is
9b30: 20 61 6e 20 53 51 4c 0d 0a 20 20 20 20 20 20 20   an SQL..       
9b40: 20 2f 2f 2f 20 4e 55 4c 4c 29 2c 20 74 68 65 20   /// NULL), the 
9b50: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
9b60: 75 73 74 20 73 65 74 20 2a 70 52 6f 77 69 64 20  ust set *pRowid 
9b70: 74 6f 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20  to the rowid of 
9b80: 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  the..        ///
9b90: 20 6e 65 77 6c 79 20 69 6e 73 65 72 74 65 64 20   newly inserted 
9ba0: 72 6f 77 3b 20 74 68 69 73 20 77 69 6c 6c 20 62  row; this will b
9bb0: 65 63 6f 6d 65 20 74 68 65 20 76 61 6c 75 65 20  ecome the value 
9bc0: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0d  returned by the.
9bd0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 71 6c  .        /// sql
9be0: 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
9bf0: 5f 72 6f 77 69 64 28 29 20 66 75 6e 63 74 69 6f  _rowid() functio
9c00: 6e 2e 20 53 65 74 74 69 6e 67 20 74 68 69 73 20  n. Setting this 
9c10: 76 61 6c 75 65 20 69 6e 20 61 6c 6c 20 74 68 65  value in all the
9c20: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6f 74  ..        /// ot
9c30: 68 65 72 20 63 61 73 65 73 20 69 73 20 61 20 68  her cases is a h
9c40: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 3b 20 74  armless no-op; t
9c50: 68 65 20 53 51 4c 69 74 65 20 65 6e 67 69 6e 65  he SQLite engine
9c60: 20 69 67 6e 6f 72 65 73 20 74 68 65 0d 0a 20 20   ignores the..  
9c70: 20 20 20 20 20 20 2f 2f 2f 20 2a 70 52 6f 77 69        /// *pRowi
9c80: 64 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  d return value i
9c90: 66 20 61 72 67 63 3d 3d 31 20 6f 72 20 61 72 67  f argc==1 or arg
9ca0: 76 5b 31 5d 20 69 73 20 6e 6f 74 20 61 6e 20 53  v[1] is not an S
9cb0: 51 4c 20 4e 55 4c 4c 2e 0d 0a 20 20 20 20 20 20  QL NULL...      
9cc0: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
9cd0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
9ce0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 45  >..        /// E
9cf0: 61 63 68 20 63 61 6c 6c 20 74 6f 20 78 55 70 64  ach call to xUpd
9d00: 61 74 65 20 77 69 6c 6c 20 66 61 6c 6c 20 69 6e  ate will fall in
9d10: 74 6f 20 6f 6e 65 20 6f 66 20 63 61 73 65 73 20  to one of cases 
9d20: 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 20 4e 6f 74  shown below. Not
9d30: 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74  e..        /// t
9d40: 68 61 74 20 72 65 66 65 72 65 6e 63 65 73 20 74  hat references t
9d50: 6f 20 61 72 67 76 5b 69 5d 20 6d 65 61 6e 20 74  o argv[i] mean t
9d60: 68 65 20 53 51 4c 20 76 61 6c 75 65 20 68 65 6c  he SQL value hel
9d70: 64 20 77 69 74 68 69 6e 20 74 68 65 0d 0a 20 20  d within the..  
9d80: 20 20 20 20 20 20 2f 2f 2f 20 61 72 67 76 5b 69        /// argv[i
9d90: 5d 20 6f 62 6a 65 63 74 2c 20 6e 6f 74 20 74 68  ] object, not th
9da0: 65 20 61 72 67 76 5b 69 5d 20 6f 62 6a 65 63 74  e argv[i] object
9db0: 20 69 74 73 65 6c 66 2e 0d 0a 20 20 20 20 20 20   itself...      
9dc0: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
9dd0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 63 6f 64 65         /// <code
9de0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20  >..        ///  
9df0: 20 20 20 61 72 67 63 20 3d 20 31 0d 0a 20 20 20     argc = 1..   
9e00: 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e       /// </code>
9e10: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
9e20: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
9e30: 2f 20 20 20 20 20 20 20 20 20 54 68 65 20 73 69  /         The si
9e40: 6e 67 6c 65 20 72 6f 77 20 77 69 74 68 20 72 6f  ngle row with ro
9e50: 77 69 64 20 65 71 75 61 6c 20 74 6f 20 61 72 67  wid equal to arg
9e60: 76 5b 30 5d 20 69 73 20 64 65 6c 65 74 65 64 2e  v[0] is deleted.
9e70: 20 4e 6f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f   No..        ///
9e80: 20 20 20 20 20 20 20 20 20 69 6e 73 65 72 74 20           insert 
9e90: 6f 63 63 75 72 73 2e 0d 0a 20 20 20 20 20 20 20  occurs...       
9ea0: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
9eb0: 20 20 20 20 20 20 2f 2f 2f 20 3c 63 6f 64 65 3e        /// <code>
9ec0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20  ..        ///   
9ed0: 20 20 61 72 67 63 20 3e 20 31 0d 0a 20 20 20 20    argc > 1..    
9ee0: 20 20 20 20 2f 2f 2f 20 20 20 20 20 61 72 67 76      ///     argv
9ef0: 5b 30 5d 20 3d 20 4e 55 4c 4c 0d 0a 20 20 20 20  [0] = NULL..    
9f00: 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 0d      /// </code>.
9f10: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
9f20: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
9f30: 20 20 20 20 20 20 20 20 20 41 20 6e 65 77 20 72           A new r
9f40: 6f 77 20 69 73 20 69 6e 73 65 72 74 65 64 20 77  ow is inserted w
9f50: 69 74 68 20 61 20 72 6f 77 69 64 20 61 72 67 76  ith a rowid argv
9f60: 5b 31 5d 20 61 6e 64 20 63 6f 6c 75 6d 6e 0d 0a  [1] and column..
9f70: 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20          ///     
9f80: 20 20 20 20 76 61 6c 75 65 73 20 69 6e 20 61 72      values in ar
9f90: 67 76 5b 32 5d 20 61 6e 64 20 66 6f 6c 6c 6f 77  gv[2] and follow
9fa0: 69 6e 67 2e 20 49 66 20 61 72 67 76 5b 31 5d 20  ing. If argv[1] 
9fb0: 69 73 20 61 6e 20 53 51 4c 20 4e 55 4c 4c 2c 0d  is an SQL NULL,.
9fc0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20  .        ///    
9fd0: 20 20 20 20 20 74 68 65 20 61 20 6e 65 77 20 75       the a new u
9fe0: 6e 69 71 75 65 20 72 6f 77 69 64 20 69 73 20 67  nique rowid is g
9ff0: 65 6e 65 72 61 74 65 64 20 61 75 74 6f 6d 61 74  enerated automat
a000: 69 63 61 6c 6c 79 2e 0d 0a 20 20 20 20 20 20 20  ically...       
a010: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
a020: 20 20 20 20 20 20 2f 2f 2f 20 3c 63 6f 64 65 3e        /// <code>
a030: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20  ..        ///   
a040: 20 20 61 72 67 63 20 3e 20 31 0d 0a 20 20 20 20    argc > 1..    
a050: 20 20 20 20 2f 2f 2f 20 20 20 20 20 61 72 67 76      ///     argv
a060: 5b 30 5d 20 3f 20 4e 55 4c 4c 0d 0a 20 20 20 20  [0] ? NULL..    
a070: 20 20 20 20 2f 2f 2f 20 20 20 20 20 61 72 67 76      ///     argv
a080: 5b 30 5d 20 3d 20 61 72 67 76 5b 31 5d 0d 0a 20  [0] = argv[1].. 
a090: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64         /// </cod
a0a0: 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e>..        /// 
a0b0: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
a0c0: 2f 2f 2f 20 20 20 20 20 20 20 20 20 54 68 65 20  ///         The 
a0d0: 72 6f 77 20 77 69 74 68 20 72 6f 77 69 64 20 61  row with rowid a
a0e0: 72 67 76 5b 30 5d 20 69 73 20 75 70 64 61 74 65  rgv[0] is update
a0f0: 64 20 77 69 74 68 20 6e 65 77 20 76 61 6c 75 65  d with new value
a100: 73 20 69 6e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  s in..        //
a110: 2f 20 20 20 20 20 20 20 20 20 61 72 67 76 5b 32  /         argv[2
a120: 5d 20 61 6e 64 20 66 6f 6c 6c 6f 77 69 6e 67 20  ] and following 
a130: 70 61 72 61 6d 65 74 65 72 73 2e 0d 0a 20 20 20  parameters...   
a140: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e       /// </para>
a150: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 63  ..        /// <c
a160: 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ode>..        //
a170: 2f 20 20 20 20 20 61 72 67 63 20 3e 20 31 0d 0a  /     argc > 1..
a180: 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20          ///     
a190: 61 72 67 76 5b 30 5d 20 3f 20 4e 55 4c 4c 0d 0a  argv[0] ? NULL..
a1a0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20          ///     
a1b0: 61 72 67 76 5b 30 5d 20 3f 20 61 72 67 76 5b 31  argv[0] ? argv[1
a1c0: 5d 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ]..        /// <
a1d0: 2f 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20 20  /code>..        
a1e0: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20  /// <para>..    
a1f0: 20 20 20 20 2f 2f 2f 20 20 20 20 20 20 20 20 20      ///         
a200: 54 68 65 20 72 6f 77 20 77 69 74 68 20 72 6f 77  The row with row
a210: 69 64 20 61 72 67 76 5b 30 5d 20 69 73 20 75 70  id argv[0] is up
a220: 64 61 74 65 64 20 77 69 74 68 20 72 6f 77 69 64  dated with rowid
a230: 20 61 72 67 76 5b 31 5d 0d 0a 20 20 20 20 20 20   argv[1]..      
a240: 20 20 2f 2f 2f 20 20 20 20 20 20 20 20 20 61 6e    ///         an
a250: 64 20 6e 65 77 20 76 61 6c 75 65 73 20 69 6e 20  d new values in 
a260: 61 72 67 76 5b 32 5d 20 61 6e 64 20 66 6f 6c 6c  argv[2] and foll
a270: 6f 77 69 6e 67 20 70 61 72 61 6d 65 74 65 72 73  owing parameters
a280: 2e 20 54 68 69 73 0d 0a 20 20 20 20 20 20 20 20  . This..        
a290: 2f 2f 2f 20 20 20 20 20 20 20 20 20 77 69 6c 6c  ///         will
a2a0: 20 6f 63 63 75 72 20 77 68 65 6e 20 61 6e 20 53   occur when an S
a2b0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 70 64  QL statement upd
a2c0: 61 74 65 73 20 61 20 72 6f 77 69 64 2c 20 61 73  ates a rowid, as
a2d0: 20 69 6e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f   in..        ///
a2e0: 20 20 20 20 20 20 20 20 20 74 68 65 20 73 74 61           the sta
a2f0: 74 65 6d 65 6e 74 3a 0d 0a 20 20 20 20 20 20 20  tement:..       
a300: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
a310: 20 20 20 20 20 20 2f 2f 2f 20 3c 63 6f 64 65 3e        /// <code>
a320: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20  ..        ///   
a330: 20 20 20 20 20 20 20 20 20 20 55 50 44 41 54 45            UPDATE
a340: 20 74 61 62 6c 65 20 53 45 54 20 72 6f 77 69 64   table SET rowid
a350: 3d 72 6f 77 69 64 2b 31 20 57 48 45 52 45 20 2e  =rowid+1 WHERE .
a360: 2e 2e 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ..;..        ///
a370: 20 3c 2f 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20   </code>..      
a380: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
a390: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 55        /// The xU
a3a0: 70 64 61 74 65 20 6d 65 74 68 6f 64 20 6d 75 73  pdate method mus
a3b0: 74 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  t return SQLITE_
a3c0: 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  OK if and only i
a3d0: 66 20 69 74 20 69 73 0d 0a 20 20 20 20 20 20 20  f it is..       
a3e0: 20 2f 2f 2f 20 73 75 63 63 65 73 73 66 75 6c 2e   /// successful.
a3f0: 20 49 66 20 61 20 66 61 69 6c 75 72 65 20 6f 63   If a failure oc
a400: 63 75 72 73 2c 20 74 68 65 20 78 55 70 64 61 74  curs, the xUpdat
a410: 65 20 6d 75 73 74 20 72 65 74 75 72 6e 20 61 6e  e must return an
a420: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 61 70  ..        /// ap
a430: 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20  propriate error 
a440: 63 6f 64 65 2e 20 4f 6e 20 61 20 66 61 69 6c 75  code. On a failu
a450: 72 65 2c 20 74 68 65 20 70 56 54 61 62 2d 3e 7a  re, the pVTab->z
a460: 45 72 72 4d 73 67 20 65 6c 65 6d 65 6e 74 0d 0a  ErrMsg element..
a470: 20 20 20 20 20 20 20 20 2f 2f 2f 20 6d 61 79 20          /// may 
a480: 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 72 65  optionally be re
a490: 70 6c 61 63 65 64 20 77 69 74 68 20 65 72 72 6f  placed with erro
a4a0: 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 73  r message text s
a4b0: 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0d  tored in memory.
a4c0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 61 6c 6c  .        /// all
a4d0: 6f 63 61 74 65 64 20 66 72 6f 6d 20 53 51 4c 69  ocated from SQLi
a4e0: 74 65 20 75 73 69 6e 67 20 66 75 6e 63 74 69 6f  te using functio
a4f0: 6e 73 20 73 75 63 68 20 61 73 20 73 71 6c 69 74  ns such as sqlit
a500: 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 6f 72 0d  e3_mprintf() or.
a510: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 71 6c  .        /// sql
a520: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2e 0d 0a  ite3_malloc()...
a530: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
a540: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
a550: 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20   <para>..       
a560: 20 2f 2f 2f 20 49 66 20 74 68 65 20 78 55 70 64   /// If the xUpd
a570: 61 74 65 20 6d 65 74 68 6f 64 20 76 69 6f 6c 61  ate method viola
a580: 74 65 73 20 73 6f 6d 65 20 63 6f 6e 73 74 72 61  tes some constra
a590: 69 6e 74 20 6f 66 20 74 68 65 20 76 69 72 74 75  int of the virtu
a5a0: 61 6c 20 74 61 62 6c 65 0d 0a 20 20 20 20 20 20  al table..      
a5b0: 20 20 2f 2f 2f 20 28 69 6e 63 6c 75 64 69 6e 67    /// (including
a5c0: 2c 20 62 75 74 20 6e 6f 74 20 6c 69 6d 69 74 65  , but not limite
a5d0: 64 20 74 6f 2c 20 61 74 74 65 6d 70 74 69 6e 67  d to, attempting
a5e0: 20 74 6f 20 73 74 6f 72 65 20 61 20 76 61 6c 75   to store a valu
a5f0: 65 20 6f 66 20 74 68 65 0d 0a 20 20 20 20 20 20  e of the..      
a600: 20 20 2f 2f 2f 20 77 72 6f 6e 67 20 64 61 74 61    /// wrong data
a610: 74 79 70 65 2c 20 61 74 74 65 6d 70 74 69 6e 67  type, attempting
a620: 20 74 6f 20 73 74 6f 72 65 20 61 20 76 61 6c 75   to store a valu
a630: 65 20 74 68 61 74 20 69 73 20 74 6f 6f 20 6c 61  e that is too la
a640: 72 67 65 20 6f 72 0d 0a 20 20 20 20 20 20 20 20  rge or..        
a650: 2f 2f 2f 20 74 6f 6f 20 73 6d 61 6c 6c 2c 20 6f  /// too small, o
a660: 72 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20  r attempting to 
a670: 63 68 61 6e 67 65 20 61 20 72 65 61 64 2d 6f 6e  change a read-on
a680: 6c 79 20 76 61 6c 75 65 29 20 74 68 65 6e 20 74  ly value) then t
a690: 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  he..        /// 
a6a0: 78 55 70 64 61 74 65 20 6d 75 73 74 20 66 61 69  xUpdate must fai
a6b0: 6c 20 77 69 74 68 20 61 6e 20 61 70 70 72 6f 70  l with an approp
a6c0: 72 69 61 74 65 20 65 72 72 6f 72 20 63 6f 64 65  riate error code
a6d0: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
a6e0: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
a6f0: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20  /// <para>..    
a700: 20 20 20 20 2f 2f 2f 20 54 68 65 72 65 20 6d 69      /// There mi
a710: 67 68 74 20 62 65 20 6f 6e 65 20 6f 72 20 6d 6f  ght be one or mo
a720: 72 65 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  re sqlite3_vtab_
a730: 63 75 72 73 6f 72 20 6f 62 6a 65 63 74 73 20 6f  cursor objects o
a740: 70 65 6e 20 61 6e 64 20 69 6e 0d 0a 20 20 20 20  pen and in..    
a750: 20 20 20 20 2f 2f 2f 20 75 73 65 20 6f 6e 20 74      /// use on t
a760: 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
a770: 20 69 6e 73 74 61 6e 63 65 20 61 6e 64 20 70 65   instance and pe
a780: 72 68 61 70 73 20 65 76 65 6e 20 6f 6e 20 74 68  rhaps even on th
a790: 65 20 72 6f 77 20 6f 66 0d 0a 20 20 20 20 20 20  e row of..      
a7a0: 20 20 2f 2f 2f 20 74 68 65 20 76 69 72 74 75 61    /// the virtua
a7b0: 6c 20 74 61 62 6c 65 20 77 68 65 6e 20 74 68 65  l table when the
a7c0: 20 78 55 70 64 61 74 65 20 6d 65 74 68 6f 64 20   xUpdate method 
a7d0: 69 73 20 69 6e 76 6f 6b 65 64 2e 20 54 68 65 0d  is invoked. The.
a7e0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6d 70  .        /// imp
a7f0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78  lementation of x
a800: 55 70 64 61 74 65 20 6d 75 73 74 20 62 65 20 70  Update must be p
a810: 72 65 70 61 72 65 64 20 66 6f 72 20 61 74 74 65  repared for atte
a820: 6d 70 74 73 20 74 6f 20 64 65 6c 65 74 65 0d 0a  mpts to delete..
a830: 20 20 20 20 20 20 20 20 2f 2f 2f 20 6f 72 20 6d          /// or m
a840: 6f 64 69 66 79 20 72 6f 77 73 20 6f 66 20 74 68  odify rows of th
a850: 65 20 74 61 62 6c 65 20 6f 75 74 20 66 72 6f 6d  e table out from
a860: 20 6f 74 68 65 72 20 65 78 69 73 74 69 6e 67 20   other existing 
a870: 63 75 72 73 6f 72 73 2e 20 49 66 20 74 68 65 0d  cursors. If the.
a880: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 76 69 72  .        /// vir
a890: 74 75 61 6c 20 74 61 62 6c 65 20 63 61 6e 6e 6f  tual table canno
a8a0: 74 20 61 63 63 6f 6d 6d 6f 64 61 74 65 20 73 75  t accommodate su
a8b0: 63 68 20 63 68 61 6e 67 65 73 2c 20 74 68 65 20  ch changes, the 
a8c0: 78 55 70 64 61 74 65 20 6d 65 74 68 6f 64 0d 0a  xUpdate method..
a8d0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 6d 75 73 74          /// must
a8e0: 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72   return an error
a8f0: 20 63 6f 64 65 2e 0d 0a 20 20 20 20 20 20 20 20   code...        
a900: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
a910: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
a920: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65  .        /// The
a930: 20 78 55 70 64 61 74 65 20 6d 65 74 68 6f 64 20   xUpdate method 
a940: 69 73 20 6f 70 74 69 6f 6e 61 6c 2e 20 49 66 20  is optional. If 
a950: 74 68 65 20 78 55 70 64 61 74 65 20 70 6f 69 6e  the xUpdate poin
a960: 74 65 72 20 69 6e 20 74 68 65 0d 0a 20 20 20 20  ter in the..    
a970: 20 20 20 20 2f 2f 2f 20 73 71 6c 69 74 65 33 5f      /// sqlite3_
a980: 6d 6f 64 75 6c 65 20 66 6f 72 20 61 20 76 69 72  module for a vir
a990: 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20 61 20  tual table is a 
a9a0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
a9b0: 65 6e 20 74 68 65 0d 0a 20 20 20 20 20 20 20 20  en the..        
a9c0: 2f 2f 2f 20 76 69 72 74 75 61 6c 20 74 61 62 6c  /// virtual tabl
a9d0: 65 20 69 73 20 72 65 61 64 2d 6f 6e 6c 79 2e 0d  e is read-only..
a9e0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
a9f0: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
aa00: 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a 20 20  / </summary>..  
aa10: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d        /// <param
aa20: 20 6e 61 6d 65 3d 22 70 56 74 61 62 22 3e 0d 0a   name="pVtab">..
aa30: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20          /// The 
aa40: 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72 20 74  native pointer t
aa50: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 74  o the sqlite3_vt
aa60: 61 62 20 64 65 72 69 76 65 64 20 73 74 72 75 63  ab derived struc
aa70: 74 75 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f  ture...        /
aa80: 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20  // </param>..   
aa90: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20       /// <param 
aaa0: 6e 61 6d 65 3d 22 61 72 67 63 22 3e 0d 0a 20 20  name="argc">..  
aab0: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e 75        /// The nu
aac0: 6d 62 65 72 20 6f 66 20 6e 65 77 20 6f 72 20 6d  mber of new or m
aad0: 6f 64 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 76  odified column v
aae0: 61 6c 75 65 73 20 63 6f 6e 74 61 69 6e 65 64 20  alues contained 
aaf0: 69 6e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  in..        /// 
ab00: 3c 70 61 72 61 6d 72 65 66 20 6e 61 6d 65 3d 22  <paramref name="
ab10: 61 72 67 76 22 20 2f 3e 2e 0d 0a 20 20 20 20 20  argv" />...     
ab20: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d     /// </param>.
ab30: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
ab40: 72 61 6d 20 6e 61 6d 65 3d 22 61 72 67 76 22 3e  ram name="argv">
ab50: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
ab60: 65 20 61 72 72 61 79 20 6f 66 20 6e 61 74 69 76  e array of nativ
ab70: 65 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 71  e pointers to sq
ab80: 6c 69 74 65 33 5f 76 61 6c 75 65 20 73 74 72 75  lite3_value stru
ab90: 63 74 75 72 65 73 20 63 6f 6e 74 61 69 6e 69 6e  ctures containin
aba0: 67 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74  g..        /// t
abb0: 68 65 20 6e 65 77 20 6f 72 20 6d 6f 64 69 66 69  he new or modifi
abc0: 65 64 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 73  ed column values
abd0: 2c 20 69 66 20 61 6e 79 2e 0d 0a 20 20 20 20 20  , if any...     
abe0: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d     /// </param>.
abf0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
ac00: 72 61 6d 20 6e 61 6d 65 3d 22 72 6f 77 49 64 22  ram name="rowId"
ac10: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 55  >..        /// U
ac20: 70 6f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 69  pon success, thi
ac30: 73 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  s parameter must
ac40: 20 62 65 20 6d 6f 64 69 66 69 65 64 20 74 6f 20   be modified to 
ac50: 63 6f 6e 74 61 69 6e 20 74 68 65 20 75 6e 69 71  contain the uniq
ac60: 75 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ue..        /// 
ac70: 69 6e 74 65 67 65 72 20 72 6f 77 20 69 64 65 6e  integer row iden
ac80: 74 69 66 69 65 72 20 66 6f 72 20 74 68 65 20 72  tifier for the r
ac90: 6f 77 20 74 68 61 74 20 77 61 73 20 69 6e 73 65  ow that was inse
aca0: 72 74 65 64 2c 20 69 66 20 61 6e 79 2e 0d 0a 20  rted, if any... 
acb0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
acc0: 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  am>..        ///
acd0: 20 3c 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20   <returns>..    
ace0: 20 20 20 20 2f 2f 2f 20 41 20 73 74 61 6e 64 61      /// A standa
acf0: 72 64 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  rd SQLite return
ad00: 20 63 6f 64 65 2e 0d 0a 20 20 20 20 20 20 20 20   code...        
ad10: 2f 2f 2f 20 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a  /// </returns>..
ad20: 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 45 72          SQLiteEr
ad30: 72 6f 72 43 6f 64 65 20 78 55 70 64 61 74 65 28  rorCode xUpdate(
ad40: 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 49 6e  ..            In
ad50: 74 50 74 72 20 70 56 74 61 62 2c 0d 0a 20 20 20  tPtr pVtab,..   
ad60: 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
ad70: 63 2c 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20  c,..            
ad80: 49 6e 74 50 74 72 20 61 72 67 76 2c 0d 0a 20 20  IntPtr argv,..  
ad90: 20 20 20 20 20 20 20 20 20 20 72 65 66 20 6c 6f            ref lo
ada0: 6e 67 20 72 6f 77 49 64 0d 0a 20 20 20 20 20 20  ng rowId..      
adb0: 20 20 20 20 20 20 29 3b 0d 0a 0d 0a 20 20 20 20        );....    
adc0: 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f      ////////////
add0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
ade0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
adf0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
ae00: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20  ///////////.... 
ae10: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d         /// <summ
ae20: 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ary>..        //
ae30: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
ae40: 20 20 2f 2f 2f 20 54 68 69 73 20 6d 65 74 68 6f    /// This metho
ae50: 64 20 62 65 67 69 6e 73 20 61 20 74 72 61 6e 73  d begins a trans
ae60: 61 63 74 69 6f 6e 20 6f 6e 20 61 20 76 69 72 74  action on a virt
ae70: 75 61 6c 20 74 61 62 6c 65 2e 20 54 68 69 73 20  ual table. This 
ae80: 69 73 20 6d 65 74 68 6f 64 0d 0a 20 20 20 20 20  is method..     
ae90: 20 20 20 2f 2f 2f 20 69 73 20 6f 70 74 69 6f 6e     /// is option
aea0: 61 6c 2e 20 54 68 65 20 78 42 65 67 69 6e 20 70  al. The xBegin p
aeb0: 6f 69 6e 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ointer of sqlite
aec0: 33 5f 6d 6f 64 75 6c 65 20 6d 61 79 20 62 65 20  3_module may be 
aed0: 4e 55 4c 4c 2e 0d 0a 20 20 20 20 20 20 20 20 2f  NULL...        /
aee0: 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  // </para>..    
aef0: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a      /// <para>..
af00: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 69 73          /// This
af10: 20 6d 65 74 68 6f 64 20 69 73 20 61 6c 77 61 79   method is alway
af20: 73 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6f 6e  s followed by on
af30: 65 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72  e call to either
af40: 20 74 68 65 20 78 43 6f 6d 6d 69 74 20 6f 72 0d   the xCommit or.
af50: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 78 52 6f  .        /// xRo
af60: 6c 6c 62 61 63 6b 20 6d 65 74 68 6f 64 2e 20 56  llback method. V
af70: 69 72 74 75 61 6c 20 74 61 62 6c 65 20 74 72 61  irtual table tra
af80: 6e 73 61 63 74 69 6f 6e 73 20 64 6f 20 6e 6f 74  nsactions do not
af90: 20 6e 65 73 74 2c 20 73 6f 20 74 68 65 0d 0a 20   nest, so the.. 
afa0: 20 20 20 20 20 20 20 2f 2f 2f 20 78 42 65 67 69         /// xBegi
afb0: 6e 20 6d 65 74 68 6f 64 20 77 69 6c 6c 20 6e 6f  n method will no
afc0: 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 6d 6f 72  t be invoked mor
afd0: 65 20 74 68 61 6e 20 6f 6e 63 65 20 6f 6e 20 61  e than once on a
afe0: 20 73 69 6e 67 6c 65 0d 0a 20 20 20 20 20 20 20   single..       
aff0: 20 2f 2f 2f 20 76 69 72 74 75 61 6c 20 74 61 62   /// virtual tab
b000: 6c 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e  le without an in
b010: 74 65 72 76 65 6e 69 6e 67 20 63 61 6c 6c 20 74  tervening call t
b020: 6f 20 65 69 74 68 65 72 20 78 43 6f 6d 6d 69 74  o either xCommit
b030: 20 6f 72 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f   or..        ///
b040: 20 78 52 6f 6c 6c 62 61 63 6b 2e 20 4d 75 6c 74   xRollback. Mult
b050: 69 70 6c 65 20 63 61 6c 6c 73 20 74 6f 20 6f 74  iple calls to ot
b060: 68 65 72 20 6d 65 74 68 6f 64 73 20 63 61 6e 20  her methods can 
b070: 61 6e 64 20 6c 69 6b 65 6c 79 20 77 69 6c 6c 0d  and likely will.
b080: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6f 63 63  .        /// occ
b090: 75 72 20 69 6e 20 62 65 74 77 65 65 6e 20 74 68  ur in between th
b0a0: 65 20 78 42 65 67 69 6e 20 61 6e 64 20 74 68 65  e xBegin and the
b0b0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 78   corresponding x
b0c0: 43 6f 6d 6d 69 74 20 6f 72 0d 0a 20 20 20 20 20  Commit or..     
b0d0: 20 20 20 2f 2f 2f 20 78 52 6f 6c 6c 62 61 63 6b     /// xRollback
b0e0: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
b0f0: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
b100: 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a  /// </summary>..
b110: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
b120: 61 6d 20 6e 61 6d 65 3d 22 70 56 74 61 62 22 3e  am name="pVtab">
b130: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
b140: 65 20 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72  e native pointer
b150: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
b160: 76 74 61 62 20 64 65 72 69 76 65 64 20 73 74 72  vtab derived str
b170: 75 63 74 75 72 65 2e 0d 0a 20 20 20 20 20 20 20  ucture...       
b180: 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20   /// </param>.. 
b190: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 72 65 74 75         /// <retu
b1a0: 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  rns>..        //
b1b0: 2f 20 41 20 73 74 61 6e 64 61 72 64 20 53 51 4c  / A standard SQL
b1c0: 69 74 65 20 72 65 74 75 72 6e 20 63 6f 64 65 2e  ite return code.
b1d0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
b1e0: 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20  returns>..      
b1f0: 20 20 53 51 4c 69 74 65 45 72 72 6f 72 43 6f 64    SQLiteErrorCod
b200: 65 20 78 42 65 67 69 6e 28 0d 0a 20 20 20 20 20  e xBegin(..     
b210: 20 20 20 20 20 20 20 49 6e 74 50 74 72 20 70 56         IntPtr pV
b220: 74 61 62 0d 0a 20 20 20 20 20 20 20 20 20 20 20  tab..           
b230: 20 29 3b 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f   );....        /
b240: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
b250: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
b260: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
b270: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
b280: 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 20 20  //////....      
b290: 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d    /// <summary>.
b2a0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
b2b0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
b2c0: 20 54 68 69 73 20 6d 65 74 68 6f 64 20 73 69 67   This method sig
b2d0: 6e 61 6c 73 20 74 68 65 20 73 74 61 72 74 20 6f  nals the start o
b2e0: 66 20 61 20 74 77 6f 2d 70 68 61 73 65 20 63 6f  f a two-phase co
b2f0: 6d 6d 69 74 20 6f 6e 20 61 20 76 69 72 74 75 61  mmit on a virtua
b300: 6c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74  l..        /// t
b310: 61 62 6c 65 2e 20 54 68 69 73 20 69 73 20 6d 65  able. This is me
b320: 74 68 6f 64 20 69 73 20 6f 70 74 69 6f 6e 61 6c  thod is optional
b330: 2e 20 54 68 65 20 78 53 79 6e 63 20 70 6f 69 6e  . The xSync poin
b340: 74 65 72 20 6f 66 0d 0a 20 20 20 20 20 20 20 20  ter of..        
b350: 2f 2f 2f 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  /// sqlite3_modu
b360: 6c 65 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0d  le may be NULL..
b370: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
b380: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
b390: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
b3a0: 20 20 2f 2f 2f 20 54 68 69 73 20 6d 65 74 68 6f    /// This metho
b3b0: 64 20 69 73 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65  d is only invoke
b3c0: 64 20 61 66 74 65 72 20 63 61 6c 6c 20 74 6f 20  d after call to 
b3d0: 74 68 65 20 78 42 65 67 69 6e 20 6d 65 74 68 6f  the xBegin metho
b3e0: 64 20 61 6e 64 0d 0a 20 20 20 20 20 20 20 20 2f  d and..        /
b3f0: 2f 2f 20 70 72 69 6f 72 20 74 6f 20 61 6e 20 78  // prior to an x
b400: 43 6f 6d 6d 69 74 20 6f 72 20 78 52 6f 6c 6c 62  Commit or xRollb
b410: 61 63 6b 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f  ack. In order to
b420: 20 69 6d 70 6c 65 6d 65 6e 74 20 74 77 6f 2d 70   implement two-p
b430: 68 61 73 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f  hase..        //
b440: 2f 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20 78 53  / commit, the xS
b450: 79 6e 63 20 6d 65 74 68 6f 64 20 6f 6e 20 61 6c  ync method on al
b460: 6c 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73  l virtual tables
b470: 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f   is invoked prio
b480: 72 20 74 6f 0d 0a 20 20 20 20 20 20 20 20 2f 2f  r to..        //
b490: 2f 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 78  / invoking the x
b4a0: 43 6f 6d 6d 69 74 20 6d 65 74 68 6f 64 20 6f 6e  Commit method on
b4b0: 20 61 6e 79 20 76 69 72 74 75 61 6c 20 74 61 62   any virtual tab
b4c0: 6c 65 2e 20 49 66 20 61 6e 79 20 6f 66 20 74 68  le. If any of th
b4d0: 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 78  e..        /// x
b4e0: 53 79 6e 63 20 6d 65 74 68 6f 64 73 20 66 61 69  Sync methods fai
b4f0: 6c 2c 20 74 68 65 20 65 6e 74 69 72 65 20 74 72  l, the entire tr
b500: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 72 6f 6c  ansaction is rol
b510: 6c 65 64 20 62 61 63 6b 2e 0d 0a 20 20 20 20 20  led back...     
b520: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a     /// </para>..
b530: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 73 75          /// </su
b540: 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20  mmary>..        
b550: 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d  /// <param name=
b560: 22 70 56 74 61 62 22 3e 0d 0a 20 20 20 20 20 20  "pVtab">..      
b570: 20 20 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76 65    /// The native
b580: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
b590: 73 71 6c 69 74 65 33 5f 76 74 61 62 20 64 65 72  sqlite3_vtab der
b5a0: 69 76 65 64 20 73 74 72 75 63 74 75 72 65 2e 0d  ived structure..
b5b0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
b5c0: 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f  aram>..        /
b5d0: 2f 2f 20 3c 72 65 74 75 72 6e 73 3e 0d 0a 20 20  // <returns>..  
b5e0: 20 20 20 20 20 20 2f 2f 2f 20 41 20 73 74 61 6e        /// A stan
b5f0: 64 61 72 64 20 53 51 4c 69 74 65 20 72 65 74 75  dard SQLite retu
b600: 72 6e 20 63 6f 64 65 2e 0d 0a 20 20 20 20 20 20  rn code...      
b610: 20 20 2f 2f 2f 20 3c 2f 72 65 74 75 72 6e 73 3e    /// </returns>
b620: 0d 0a 20 20 20 20 20 20 20 20 53 51 4c 69 74 65  ..        SQLite
b630: 45 72 72 6f 72 43 6f 64 65 20 78 53 79 6e 63 28  ErrorCode xSync(
b640: 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 49 6e  ..            In
b650: 74 50 74 72 20 70 56 74 61 62 0d 0a 20 20 20 20  tPtr pVtab..    
b660: 20 20 20 20 20 20 20 20 29 3b 0d 0a 0d 0a 20 20          );....  
b670: 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f        //////////
b680: 2f 2f 2f 2f 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 0d 0a 0d  /////////////...
b6c0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 73 75  .        /// <su
b6d0: 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20  mmary>..        
b6e0: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20  /// <para>..    
b6f0: 20 20 20 20 2f 2f 2f 20 54 68 69 73 20 6d 65 74      /// This met
b700: 68 6f 64 20 63 61 75 73 65 73 20 61 20 76 69 72  hod causes a vir
b710: 74 75 61 6c 20 74 61 62 6c 65 20 74 72 61 6e 73  tual table trans
b720: 61 63 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74  action to commit
b730: 2e 20 54 68 69 73 20 69 73 0d 0a 20 20 20 20 20  . This is..     
b740: 20 20 20 2f 2f 2f 20 6d 65 74 68 6f 64 20 69 73     /// method is
b750: 20 6f 70 74 69 6f 6e 61 6c 2e 20 54 68 65 20 78   optional. The x
b760: 43 6f 6d 6d 69 74 20 70 6f 69 6e 74 65 72 20 6f  Commit pointer o
b770: 66 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  f sqlite3_module
b780: 20 6d 61 79 20 62 65 0d 0a 20 20 20 20 20 20 20   may be..       
b790: 20 2f 2f 2f 20 4e 55 4c 4c 2e 0d 0a 20 20 20 20   /// NULL...    
b7a0: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
b7b0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
b7c0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
b7d0: 20 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20   A call to this 
b7e0: 6d 65 74 68 6f 64 20 61 6c 77 61 79 73 20 66 6f  method always fo
b7f0: 6c 6c 6f 77 73 20 61 20 70 72 69 6f 72 20 63 61  llows a prior ca
b800: 6c 6c 20 74 6f 20 78 42 65 67 69 6e 20 61 6e 64  ll to xBegin and
b810: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 78 53  ..        /// xS
b820: 79 6e 63 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ync...        //
b830: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  / </para>..     
b840: 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79     /// </summary
b850: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
b860: 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 56 74 61  param name="pVta
b870: 62 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  b">..        ///
b880: 20 54 68 65 20 6e 61 74 69 76 65 20 70 6f 69 6e   The native poin
b890: 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
b8a0: 65 33 5f 76 74 61 62 20 64 65 72 69 76 65 64 20  e3_vtab derived 
b8b0: 73 74 72 75 63 74 75 72 65 2e 0d 0a 20 20 20 20  structure...    
b8c0: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e      /// </param>
b8d0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 72  ..        /// <r
b8e0: 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20  eturns>..       
b8f0: 20 2f 2f 2f 20 41 20 73 74 61 6e 64 61 72 64 20   /// A standard 
b900: 53 51 4c 69 74 65 20 72 65 74 75 72 6e 20 63 6f  SQLite return co
b910: 64 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  de...        ///
b920: 20 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20   </returns>..   
b930: 20 20 20 20 20 53 51 4c 69 74 65 45 72 72 6f 72       SQLiteError
b940: 43 6f 64 65 20 78 43 6f 6d 6d 69 74 28 0d 0a 20  Code xCommit(.. 
b950: 20 20 20 20 20 20 20 20 20 20 20 49 6e 74 50 74             IntPt
b960: 72 20 70 56 74 61 62 0d 0a 20 20 20 20 20 20 20  r pVtab..       
b970: 20 20 20 20 20 29 3b 0d 0a 0d 0a 20 20 20 20 20       );....     
b980: 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f     /////////////
b990: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
b9a0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
b9b0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
b9c0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20  //////////....  
b9d0: 20 20 20 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61        /// <summa
b9e0: 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ry>..        ///
b9f0: 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20   <para>..       
ba00: 20 2f 2f 2f 20 54 68 69 73 20 6d 65 74 68 6f 64   /// This method
ba10: 20 63 61 75 73 65 73 20 61 20 76 69 72 74 75 61   causes a virtua
ba20: 6c 20 74 61 62 6c 65 20 74 72 61 6e 73 61 63 74  l table transact
ba30: 69 6f 6e 20 74 6f 20 72 6f 6c 6c 62 61 63 6b 2e  ion to rollback.
ba40: 20 54 68 69 73 20 69 73 0d 0a 20 20 20 20 20 20   This is..      
ba50: 20 20 2f 2f 2f 20 6d 65 74 68 6f 64 20 69 73 20    /// method is 
ba60: 6f 70 74 69 6f 6e 61 6c 2e 20 54 68 65 20 78 52  optional. The xR
ba70: 6f 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20  ollback pointer 
ba80: 6f 66 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  of sqlite3_modul
ba90: 65 20 6d 61 79 20 62 65 0d 0a 20 20 20 20 20 20  e may be..      
baa0: 20 20 2f 2f 2f 20 4e 55 4c 4c 2e 0d 0a 20 20 20    /// NULL...   
bab0: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e       /// </para>
bac0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
bad0: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
bae0: 2f 20 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  / A call to this
baf0: 20 6d 65 74 68 6f 64 20 61 6c 77 61 79 73 20 66   method always f
bb00: 6f 6c 6c 6f 77 73 20 61 20 70 72 69 6f 72 20 63  ollows a prior c
bb10: 61 6c 6c 20 74 6f 20 78 42 65 67 69 6e 2e 0d 0a  all to xBegin...
bb20: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
bb30: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
bb40: 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20   </summary>..   
bb50: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20       /// <param 
bb60: 6e 61 6d 65 3d 22 70 56 74 61 62 22 3e 0d 0a 20  name="pVtab">.. 
bb70: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e         /// The n
bb80: 61 74 69 76 65 20 70 6f 69 6e 74 65 72 20 74 6f  ative pointer to
bb90: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 74 61   the sqlite3_vta
bba0: 62 20 64 65 72 69 76 65 64 20 73 74 72 75 63 74  b derived struct
bbb0: 75 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ure...        //
bbc0: 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20  / </param>..    
bbd0: 20 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72 6e 73      /// <returns
bbe0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41  >..        /// A
bbf0: 20 73 74 61 6e 64 61 72 64 20 53 51 4c 69 74 65   standard SQLite
bc00: 20 72 65 74 75 72 6e 20 63 6f 64 65 2e 0d 0a 20   return code... 
bc10: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72 65 74         /// </ret
bc20: 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 53  urns>..        S
bc30: 51 4c 69 74 65 45 72 72 6f 72 43 6f 64 65 20 78  QLiteErrorCode x
bc40: 52 6f 6c 6c 62 61 63 6b 28 0d 0a 20 20 20 20 20  Rollback(..     
bc50: 20 20 20 20 20 20 20 49 6e 74 50 74 72 20 70 56         IntPtr pV
bc60: 74 61 62 0d 0a 20 20 20 20 20 20 20 20 20 20 20  tab..           
bc70: 20 29 3b 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f   );....        /
bc80: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
bc90: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
bca0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
bcb0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
bcc0: 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 20 20  //////....      
bcd0: 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d    /// <summary>.
bce0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
bcf0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
bd00: 20 54 68 69 73 20 6d 65 74 68 6f 64 20 70 72 6f   This method pro
bd10: 76 69 64 65 73 20 6e 6f 74 69 66 69 63 61 74 69  vides notificati
bd20: 6f 6e 20 74 68 61 74 20 74 68 65 20 76 69 72 74  on that the virt
bd30: 75 61 6c 20 74 61 62 6c 65 0d 0a 20 20 20 20 20  ual table..     
bd40: 20 20 20 2f 2f 2f 20 69 6d 70 6c 65 6d 65 6e 74     /// implement
bd50: 61 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20 76  ation that the v
bd60: 69 72 74 75 61 6c 20 74 61 62 6c 65 20 77 69 6c  irtual table wil
bd70: 6c 20 62 65 20 67 69 76 65 6e 20 61 20 6e 65 77  l be given a new
bd80: 20 6e 61 6d 65 2e 20 49 66 0d 0a 20 20 20 20 20   name. If..     
bd90: 20 20 20 2f 2f 2f 20 74 68 69 73 20 6d 65 74 68     /// this meth
bda0: 6f 64 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  od returns SQLIT
bdb0: 45 5f 4f 4b 20 74 68 65 6e 20 53 51 4c 69 74 65  E_OK then SQLite
bdc0: 20 72 65 6e 61 6d 65 73 20 74 68 65 20 74 61 62   renames the tab
bdd0: 6c 65 2e 20 49 66 0d 0a 20 20 20 20 20 20 20 20  le. If..        
bde0: 2f 2f 2f 20 74 68 69 73 20 6d 65 74 68 6f 64 20  /// this method 
bdf0: 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72  returns an error
be00: 20 63 6f 64 65 20 74 68 65 6e 20 74 68 65 20 72   code then the r
be10: 65 6e 61 6d 69 6e 67 20 69 73 20 70 72 65 76 65  enaming is preve
be20: 6e 74 65 64 2e 0d 0a 20 20 20 20 20 20 20 20 2f  nted...        /
be30: 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  // </para>..    
be40: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a      /// <para>..
be50: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20          /// The 
be60: 78 52 65 6e 61 6d 65 20 6d 65 74 68 6f 64 20 69  xRename method i
be70: 73 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 65  s required for e
be80: 76 65 72 79 20 76 69 72 74 75 61 6c 20 74 61 62  very virtual tab
be90: 6c 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  le..        /// 
bea0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0d  implementation..
beb0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
bec0: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
bed0: 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a 20 20  / </summary>..  
bee0: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d        /// <param
bef0: 20 6e 61 6d 65 3d 22 70 56 74 61 62 22 3e 0d 0a   name="pVtab">..
bf00: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20          /// The 
bf10: 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72 20 74  native pointer t
bf20: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 74  o the sqlite3_vt
bf30: 61 62 20 64 65 72 69 76 65 64 20 73 74 72 75 63  ab derived struc
bf40: 74 75 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f  ture...        /
bf50: 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20  // </param>..   
bf60: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20       /// <param 
bf70: 6e 61 6d 65 3d 22 6e 41 72 67 22 3e 0d 0a 20 20  name="nArg">..  
bf80: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e 75        /// The nu
bf90: 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
bfa0: 73 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f  s to the functio
bfb0: 6e 20 62 65 69 6e 67 20 73 6f 75 67 68 74 2e 0d  n being sought..
bfc0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
bfd0: 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f  aram>..        /
bfe0: 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22  // <param name="
bff0: 7a 4e 61 6d 65 22 3e 0d 0a 20 20 20 20 20 20 20  zName">..       
c000: 20 2f 2f 2f 20 54 68 65 20 6e 61 6d 65 20 6f 66   /// The name of
c010: 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65   the function be
c020: 69 6e 67 20 73 6f 75 67 68 74 2e 0d 0a 20 20 20  ing sought...   
c030: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d       /// </param
c040: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
c050: 70 61 72 61 6d 20 6e 61 6d 65 3d 22 63 61 6c 6c  param name="call
c060: 62 61 63 6b 22 3e 0d 0a 20 20 20 20 20 20 20 20  back">..        
c070: 2f 2f 2f 20 55 70 6f 6e 20 73 75 63 63 65 73 73  /// Upon success
c080: 2c 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  , this parameter
c090: 20 6d 75 73 74 20 62 65 20 6d 6f 64 69 66 69 65   must be modifie
c0a0: 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 74 68 65  d to contain the
c0b0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 64 65  ..        /// de
c0c0: 6c 65 67 61 74 65 20 72 65 73 70 6f 6e 73 69 62  legate responsib
c0d0: 6c 65 20 66 6f 72 20 69 6d 70 6c 65 6d 65 6e 74  le for implement
c0e0: 69 6e 67 20 74 68 65 20 73 70 65 63 69 66 69 65  ing the specifie
c0f0: 64 20 66 75 6e 63 74 69 6f 6e 2e 0d 0a 20 20 20  d function...   
c100: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d       /// </param
c110: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
c120: 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 43 6c 69  param name="pCli
c130: 65 6e 74 44 61 74 61 22 3e 0d 0a 20 20 20 20 20  entData">..     
c140: 20 20 20 2f 2f 2f 20 55 70 6f 6e 20 73 75 63 63     /// Upon succ
c150: 65 73 73 2c 20 74 68 69 73 20 70 61 72 61 6d 65  ess, this parame
c160: 74 65 72 20 6d 75 73 74 20 62 65 20 6d 6f 64 69  ter must be modi
c170: 66 69 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  fied to contain 
c180: 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  the..        ///
c190: 20 6e 61 74 69 76 65 20 75 73 65 72 2d 64 61 74   native user-dat
c1a0: 61 20 70 6f 69 6e 74 65 72 20 61 73 73 6f 63 69  a pointer associ
c1b0: 61 74 65 64 20 77 69 74 68 0d 0a 20 20 20 20 20  ated with..     
c1c0: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 72 65 66     /// <paramref
c1d0: 20 6e 61 6d 65 3d 22 63 61 6c 6c 62 61 63 6b 22   name="callback"
c1e0: 20 2f 3e 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f   />...        //
c1f0: 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20  / </param>..    
c200: 20 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72 6e 73      /// <returns
c210: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 4e  >..        /// N
c220: 6f 6e 2d 7a 65 72 6f 20 69 66 20 74 68 65 20 73  on-zero if the s
c230: 70 65 63 69 66 69 65 64 20 66 75 6e 63 74 69 6f  pecified functio
c240: 6e 20 77 61 73 20 66 6f 75 6e 64 3b 20 7a 65 72  n was found; zer
c250: 6f 20 6f 74 68 65 72 77 69 73 65 2e 0d 0a 20 20  o otherwise...  
c260: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72 65 74 75        /// </retu
c270: 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 69 6e  rns>..        in
c280: 74 20 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 28  t xFindFunction(
c290: 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 49 6e  ..            In
c2a0: 74 50 74 72 20 70 56 74 61 62 2c 0d 0a 20 20 20  tPtr pVtab,..   
c2b0: 20 20 20 20 20 20 20 20 20 69 6e 74 20 6e 41 72           int nAr
c2c0: 67 2c 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20  g,..            
c2d0: 49 6e 74 50 74 72 20 7a 4e 61 6d 65 2c 0d 0a 20  IntPtr zName,.. 
c2e0: 20 20 20 20 20 20 20 20 20 20 20 72 65 66 20 53             ref S
c2f0: 51 4c 69 74 65 43 61 6c 6c 62 61 63 6b 20 63 61  QLiteCallback ca
c300: 6c 6c 62 61 63 6b 2c 0d 0a 20 20 20 20 20 20 20  llback,..       
c310: 20 20 20 20 20 72 65 66 20 49 6e 74 50 74 72 20       ref IntPtr 
c320: 70 43 6c 69 65 6e 74 44 61 74 61 0d 0a 20 20 20  pClientData..   
c330: 20 20 20 20 20 20 20 20 20 29 3b 0d 0a 0d 0a 20           );.... 
c340: 20 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f         /////////
c350: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
c360: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
c370: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
c380: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a  //////////////..
c390: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 73  ..        /// <s
c3a0: 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20  ummary>..       
c3b0: 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20   /// <para>..   
c3c0: 20 20 20 20 20 2f 2f 2f 20 54 68 69 73 20 6d 65       /// This me
c3d0: 74 68 6f 64 20 70 72 6f 76 69 64 65 73 20 6e 6f  thod provides no
c3e0: 74 69 66 69 63 61 74 69 6f 6e 20 74 68 61 74 20  tification that 
c3f0: 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
c400: 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69  e..        /// i
c410: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68  mplementation th
c420: 61 74 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  at the virtual t
c430: 61 62 6c 65 20 77 69 6c 6c 20 62 65 20 67 69 76  able will be giv
c440: 65 6e 20 61 20 6e 65 77 20 6e 61 6d 65 2e 20 49  en a new name. I
c450: 66 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74  f..        /// t
c460: 68 69 73 20 6d 65 74 68 6f 64 20 72 65 74 75 72  his method retur
c470: 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 20 74 68 65  ns SQLITE_OK the
c480: 6e 20 53 51 4c 69 74 65 20 72 65 6e 61 6d 65 73  n SQLite renames
c490: 20 74 68 65 20 74 61 62 6c 65 2e 20 49 66 0d 0a   the table. If..
c4a0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 69 73          /// this
c4b0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
c4c0: 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 74 68  an error code th
c4d0: 65 6e 20 74 68 65 20 72 65 6e 61 6d 69 6e 67 20  en the renaming 
c4e0: 69 73 20 70 72 65 76 65 6e 74 65 64 2e 0d 0a 20  is prevented... 
c4f0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
c500: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
c510: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
c520: 2f 2f 2f 20 54 68 65 20 78 52 65 6e 61 6d 65 20  /// The xRename 
c530: 6d 65 74 68 6f 64 20 69 73 20 72 65 71 75 69 72  method is requir
c540: 65 64 20 66 6f 72 20 65 76 65 72 79 20 76 69 72  ed for every vir
c550: 74 75 61 6c 20 74 61 62 6c 65 0d 0a 20 20 20 20  tual table..    
c560: 20 20 20 20 2f 2f 2f 20 69 6d 70 6c 65 6d 65 6e      /// implemen
c570: 74 61 74 69 6f 6e 2e 0d 0a 20 20 20 20 20 20 20  tation...       
c580: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
c590: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d        /// </summ
c5a0: 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ary>..        //
c5b0: 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70  / <param name="p
c5c0: 56 74 61 62 22 3e 0d 0a 20 20 20 20 20 20 20 20  Vtab">..        
c5d0: 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76 65 20 70  /// The native p
c5e0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 71  ointer to the sq
c5f0: 6c 69 74 65 33 5f 76 74 61 62 20 64 65 72 69 76  lite3_vtab deriv
c600: 65 64 20 73 74 72 75 63 74 75 72 65 2e 0d 0a 20  ed structure... 
c610: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
c620: 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  am>..        ///
c630: 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 7a 4e   <param name="zN
c640: 65 77 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ew">..        //
c650: 2f 20 54 68 65 20 6e 61 74 69 76 65 20 70 6f 69  / The native poi
c660: 6e 74 65 72 20 74 6f 20 74 68 65 20 55 54 46 2d  nter to the UTF-
c670: 38 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67  8 encoded string
c680: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
c690: 6e 65 77 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  new..        ///
c6a0: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 76 69   name for the vi
c6b0: 72 74 75 61 6c 20 74 61 62 6c 65 2e 0d 0a 20 20  rtual table...  
c6c0: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61        /// </para
c6d0: 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  m>..        /// 
c6e0: 3c 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20  <returns>..     
c6f0: 20 20 20 2f 2f 2f 20 41 20 73 74 61 6e 64 61 72     /// A standar
c700: 64 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 20  d SQLite return 
c710: 63 6f 64 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f  code...        /
c720: 2f 2f 20 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a 20  // </returns>.. 
c730: 20 20 20 20 20 20 20 53 51 4c 69 74 65 45 72 72         SQLiteErr
c740: 6f 72 43 6f 64 65 20 78 52 65 6e 61 6d 65 28 0d  orCode xRename(.
c750: 0a 20 20 20 20 20 20 20 20 20 20 20 20 49 6e 74  .            Int
c760: 50 74 72 20 70 56 74 61 62 2c 0d 0a 20 20 20 20  Ptr pVtab,..    
c770: 20 20 20 20 20 20 20 20 49 6e 74 50 74 72 20 7a          IntPtr z
c780: 4e 65 77 0d 0a 20 20 20 20 20 20 20 20 20 20 20  New..           
c790: 20 29 3b 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f   );....        /
c7a0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
c7b0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
c7c0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
c7d0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
c7e0: 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 20 20  //////....      
c7f0: 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d    /// <summary>.
c800: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
c810: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
c820: 20 54 68 65 73 65 20 6d 65 74 68 6f 64 73 20 70   These methods p
c830: 72 6f 76 69 64 65 20 74 68 65 20 76 69 72 74 75  rovide the virtu
c840: 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  al table impleme
c850: 6e 74 61 74 69 6f 6e 20 61 6e 0d 0a 20 20 20 20  ntation an..    
c860: 20 20 20 20 2f 2f 2f 20 6f 70 70 6f 72 74 75 6e      /// opportun
c870: 69 74 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ity to implement
c880: 20 6e 65 73 74 65 64 20 74 72 61 6e 73 61 63 74   nested transact
c890: 69 6f 6e 73 2e 20 54 68 65 79 20 61 72 65 20 61  ions. They are a
c8a0: 6c 77 61 79 73 0d 0a 20 20 20 20 20 20 20 20 2f  lways..        /
c8b0: 2f 2f 20 6f 70 74 69 6f 6e 61 6c 20 61 6e 64 20  // optional and 
c8c0: 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c  will only be cal
c8d0: 6c 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65  led in SQLite ve
c8e0: 72 73 69 6f 6e 20 33 2e 37 2e 37 20 61 6e 64 20  rsion 3.7.7 and 
c8f0: 6c 61 74 65 72 2e 0d 0a 20 20 20 20 20 20 20 20  later...        
c900: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
c910: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
c920: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 57 68 65  .        /// Whe
c930: 6e 20 78 53 61 76 65 70 6f 69 6e 74 28 58 2c 4e  n xSavepoint(X,N
c940: 29 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68  ) is invoked, th
c950: 61 74 20 69 73 20 61 20 73 69 67 6e 61 6c 20 74  at is a signal t
c960: 6f 20 74 68 65 20 76 69 72 74 75 61 6c 0d 0a 20  o the virtual.. 
c970: 20 20 20 20 20 20 20 2f 2f 2f 20 74 61 62 6c 65         /// table
c980: 20 58 20 74 68 61 74 20 69 74 20 73 68 6f 75 6c   X that it shoul
c990: 64 20 73 61 76 65 20 69 74 73 20 63 75 72 72 65  d save its curre
c9a0: 6e 74 20 73 74 61 74 65 20 61 73 20 73 61 76 65  nt state as save
c9b0: 70 6f 69 6e 74 20 4e 2e 20 41 0d 0a 20 20 20 20  point N. A..    
c9c0: 20 20 20 20 2f 2f 2f 20 73 75 62 73 65 71 75 65      /// subseque
c9d0: 6e 74 20 63 61 6c 6c 20 74 6f 20 78 52 6f 6c 6c  nt call to xRoll
c9e0: 62 61 63 6b 54 6f 28 58 2c 52 29 20 6d 65 61 6e  backTo(X,R) mean
c9f0: 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65  s that the state
ca00: 20 6f 66 20 74 68 65 0d 0a 20 20 20 20 20 20 20   of the..       
ca10: 20 2f 2f 2f 20 76 69 72 74 75 61 6c 20 74 61 62   /// virtual tab
ca20: 6c 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  le should return
ca30: 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20   to what it was 
ca40: 77 68 65 6e 20 78 53 61 76 65 70 6f 69 6e 74 28  when xSavepoint(
ca50: 58 2c 52 29 20 77 61 73 0d 0a 20 20 20 20 20 20  X,R) was..      
ca60: 20 20 2f 2f 2f 20 6c 61 73 74 20 63 61 6c 6c 65    /// last calle
ca70: 64 2e 20 54 68 65 20 63 61 6c 6c 20 74 6f 20 78  d. The call to x
ca80: 52 6f 6c 6c 62 61 63 6b 54 6f 28 58 2c 52 29 20  RollbackTo(X,R) 
ca90: 77 69 6c 6c 20 69 6e 76 61 6c 69 64 61 74 65 20  will invalidate 
caa0: 61 6c 6c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  all..        ///
cab0: 20 73 61 76 65 70 6f 69 6e 74 73 20 77 69 74 68   savepoints with
cac0: 20 4e 3e 52 3b 20 6e 6f 6e 65 20 6f 66 20 74 68   N>R; none of th
cad0: 65 20 69 6e 76 61 6c 69 64 65 64 20 73 61 76 65  e invalided save
cae0: 70 6f 69 6e 74 73 20 77 69 6c 6c 20 62 65 0d 0a  points will be..
caf0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 72 6f 6c 6c          /// roll
cb00: 65 64 20 62 61 63 6b 20 6f 72 20 72 65 6c 65 61  ed back or relea
cb10: 73 65 64 20 77 69 74 68 6f 75 74 20 66 69 72 73  sed without firs
cb20: 74 20 62 65 69 6e 67 20 72 65 69 6e 69 74 69 61  t being reinitia
cb30: 6c 69 7a 65 64 20 62 79 20 61 20 63 61 6c 6c 0d  lized by a call.
cb40: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 6f 20  .        /// to 
cb50: 78 53 61 76 65 70 6f 69 6e 74 28 29 2e 20 41 20  xSavepoint(). A 
cb60: 63 61 6c 6c 20 74 6f 20 78 52 65 6c 65 61 73 65  call to xRelease
cb70: 28 58 2c 4d 29 20 69 6e 76 61 6c 69 64 61 74 65  (X,M) invalidate
cb80: 73 20 61 6c 6c 20 73 61 76 65 70 6f 69 6e 74 73  s all savepoints
cb90: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 77 68  ..        /// wh
cba0: 65 72 65 20 4e 3e 3d 4d 2e 0d 0a 20 20 20 20 20  ere N>=M...     
cbb0: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a     /// </para>..
cbc0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
cbd0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
cbe0: 4e 6f 6e 65 20 6f 66 20 74 68 65 20 78 53 61 76  None of the xSav
cbf0: 65 70 6f 69 6e 74 28 29 2c 20 78 52 65 6c 65 61  epoint(), xRelea
cc00: 73 65 28 29 2c 20 6f 72 20 78 52 6f 6c 6c 62 61  se(), or xRollba
cc10: 63 6b 54 6f 28 29 20 6d 65 74 68 6f 64 73 20 77  ckTo() methods w
cc20: 69 6c 6c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ill..        ///
cc30: 20 65 76 65 72 20 62 65 20 63 61 6c 6c 65 64 20   ever be called 
cc40: 65 78 63 65 70 74 20 69 6e 20 62 65 74 77 65 65  except in betwee
cc50: 6e 20 63 61 6c 6c 73 20 74 6f 20 78 42 65 67 69  n calls to xBegi
cc60: 6e 28 29 20 61 6e 64 20 65 69 74 68 65 72 0d 0a  n() and either..
cc70: 20 20 20 20 20 20 20 20 2f 2f 2f 20 78 43 6f 6d          /// xCom
cc80: 6d 69 74 28 29 20 6f 72 20 78 52 6f 6c 6c 62 61  mit() or xRollba
cc90: 63 6b 28 29 2e 0d 0a 20 20 20 20 20 20 20 20 2f  ck()...        /
cca0: 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  // </para>..    
ccb0: 20 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72      /// </summar
ccc0: 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  y>..        /// 
ccd0: 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 56 74  <param name="pVt
cce0: 61 62 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ab">..        //
ccf0: 2f 20 54 68 65 20 6e 61 74 69 76 65 20 70 6f 69  / The native poi
cd00: 6e 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  nter to the sqli
cd10: 74 65 33 5f 76 74 61 62 20 64 65 72 69 76 65 64  te3_vtab derived
cd20: 20 73 74 72 75 63 74 75 72 65 2e 0d 0a 20 20 20   structure...   
cd30: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d       /// </param
cd40: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
cd50: 70 61 72 61 6d 20 6e 61 6d 65 3d 22 69 53 61 76  param name="iSav
cd60: 65 70 6f 69 6e 74 22 3e 0d 0a 20 20 20 20 20 20  epoint">..      
cd70: 20 20 2f 2f 2f 20 54 68 69 73 20 69 73 20 61 6e    /// This is an
cd80: 20 69 6e 74 65 67 65 72 20 69 64 65 6e 74 69 66   integer identif
cd90: 69 65 72 20 75 6e 64 65 72 20 77 68 69 63 68 20  ier under which 
cda0: 74 68 65 20 74 68 65 20 63 75 72 72 65 6e 74 20  the the current 
cdb0: 73 74 61 74 65 20 6f 66 0d 0a 20 20 20 20 20 20  state of..      
cdc0: 20 20 2f 2f 2f 20 74 68 65 20 76 69 72 74 75 61    /// the virtua
cdd0: 6c 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62  l table should b
cde0: 65 20 73 61 76 65 64 2e 0d 0a 20 20 20 20 20 20  e saved...      
cdf0: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a    /// </param>..
ce00: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 72 65 74          /// <ret
ce10: 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 2f  urns>..        /
ce20: 2f 2f 20 41 20 73 74 61 6e 64 61 72 64 20 53 51  // A standard SQ
ce30: 4c 69 74 65 20 72 65 74 75 72 6e 20 63 6f 64 65  Lite return code
ce40: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
ce50: 2f 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20  /returns>..     
ce60: 20 20 20 53 51 4c 69 74 65 45 72 72 6f 72 43 6f     SQLiteErrorCo
ce70: 64 65 20 78 53 61 76 65 70 6f 69 6e 74 28 0d 0a  de xSavepoint(..
ce80: 20 20 20 20 20 20 20 20 20 20 20 20 49 6e 74 50              IntP
ce90: 74 72 20 70 56 74 61 62 2c 0d 0a 20 20 20 20 20  tr pVtab,..     
cea0: 20 20 20 20 20 20 20 69 6e 74 20 69 53 61 76 65         int iSave
ceb0: 70 6f 69 6e 74 0d 0a 20 20 20 20 20 20 20 20 20  point..         
cec0: 20 20 20 29 3b 0d 0a 0d 0a 20 20 20 20 20 20 20     );....       
ced0: 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f   ///////////////
cee0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
cef0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
cf00: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
cf10: 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20  ////////....    
cf20: 20 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79      /// <summary
cf30: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
cf40: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
cf50: 2f 2f 20 54 68 65 73 65 20 6d 65 74 68 6f 64 73  // These methods
cf60: 20 70 72 6f 76 69 64 65 20 74 68 65 20 76 69 72   provide the vir
cf70: 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65  tual table imple
cf80: 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 0d 0a 20 20  mentation an..  
cf90: 20 20 20 20 20 20 2f 2f 2f 20 6f 70 70 6f 72 74        /// opport
cfa0: 75 6e 69 74 79 20 74 6f 20 69 6d 70 6c 65 6d 65  unity to impleme
cfb0: 6e 74 20 6e 65 73 74 65 64 20 74 72 61 6e 73 61  nt nested transa
cfc0: 63 74 69 6f 6e 73 2e 20 54 68 65 79 20 61 72 65  ctions. They are
cfd0: 20 61 6c 77 61 79 73 0d 0a 20 20 20 20 20 20 20   always..       
cfe0: 20 2f 2f 2f 20 6f 70 74 69 6f 6e 61 6c 20 61 6e   /// optional an
cff0: 64 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 20 63  d will only be c
d000: 61 6c 6c 65 64 20 69 6e 20 53 51 4c 69 74 65 20  alled in SQLite 
d010: 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 20 61 6e  version 3.7.7 an
d020: 64 20 6c 61 74 65 72 2e 0d 0a 20 20 20 20 20 20  d later...      
d030: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
d040: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
d050: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 57  >..        /// W
d060: 68 65 6e 20 78 53 61 76 65 70 6f 69 6e 74 28 58  hen xSavepoint(X
d070: 2c 4e 29 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ,N) is invoked, 
d080: 74 68 61 74 20 69 73 20 61 20 73 69 67 6e 61 6c  that is a signal
d090: 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 0d   to the virtual.
d0a0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 61 62  .        /// tab
d0b0: 6c 65 20 58 20 74 68 61 74 20 69 74 20 73 68 6f  le X that it sho
d0c0: 75 6c 64 20 73 61 76 65 20 69 74 73 20 63 75 72  uld save its cur
d0d0: 72 65 6e 74 20 73 74 61 74 65 20 61 73 20 73 61  rent state as sa
d0e0: 76 65 70 6f 69 6e 74 20 4e 2e 20 41 0d 0a 20 20  vepoint N. A..  
d0f0: 20 20 20 20 20 20 2f 2f 2f 20 73 75 62 73 65 71        /// subseq
d100: 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 78 52 6f  uent call to xRo
d110: 6c 6c 62 61 63 6b 54 6f 28 58 2c 52 29 20 6d 65  llbackTo(X,R) me
d120: 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61  ans that the sta
d130: 74 65 20 6f 66 20 74 68 65 0d 0a 20 20 20 20 20  te of the..     
d140: 20 20 20 2f 2f 2f 20 76 69 72 74 75 61 6c 20 74     /// virtual t
d150: 61 62 6c 65 20 73 68 6f 75 6c 64 20 72 65 74 75  able should retu
d160: 72 6e 20 74 6f 20 77 68 61 74 20 69 74 20 77 61  rn to what it wa
d170: 73 20 77 68 65 6e 20 78 53 61 76 65 70 6f 69 6e  s when xSavepoin
d180: 74 28 58 2c 52 29 20 77 61 73 0d 0a 20 20 20 20  t(X,R) was..    
d190: 20 20 20 20 2f 2f 2f 20 6c 61 73 74 20 63 61 6c      /// last cal
d1a0: 6c 65 64 2e 20 54 68 65 20 63 61 6c 6c 20 74 6f  led. The call to
d1b0: 20 78 52 6f 6c 6c 62 61 63 6b 54 6f 28 58 2c 52   xRollbackTo(X,R
d1c0: 29 20 77 69 6c 6c 20 69 6e 76 61 6c 69 64 61 74  ) will invalidat
d1d0: 65 20 61 6c 6c 0d 0a 20 20 20 20 20 20 20 20 2f  e all..        /
d1e0: 2f 2f 20 73 61 76 65 70 6f 69 6e 74 73 20 77 69  // savepoints wi
d1f0: 74 68 20 4e 3e 52 3b 20 6e 6f 6e 65 20 6f 66 20  th N>R; none of 
d200: 74 68 65 20 69 6e 76 61 6c 69 64 65 64 20 73 61  the invalided sa
d210: 76 65 70 6f 69 6e 74 73 20 77 69 6c 6c 20 62 65  vepoints will be
d220: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 72 6f  ..        /// ro
d230: 6c 6c 65 64 20 62 61 63 6b 20 6f 72 20 72 65 6c  lled back or rel
d240: 65 61 73 65 64 20 77 69 74 68 6f 75 74 20 66 69  eased without fi
d250: 72 73 74 20 62 65 69 6e 67 20 72 65 69 6e 69 74  rst being reinit
d260: 69 61 6c 69 7a 65 64 20 62 79 20 61 20 63 61 6c  ialized by a cal
d270: 6c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74  l..        /// t
d280: 6f 20 78 53 61 76 65 70 6f 69 6e 74 28 29 2e 20  o xSavepoint(). 
d290: 41 20 63 61 6c 6c 20 74 6f 20 78 52 65 6c 65 61  A call to xRelea
d2a0: 73 65 28 58 2c 4d 29 20 69 6e 76 61 6c 69 64 61  se(X,M) invalida
d2b0: 74 65 73 20 61 6c 6c 20 73 61 76 65 70 6f 69 6e  tes all savepoin
d2c0: 74 73 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ts..        /// 
d2d0: 77 68 65 72 65 20 4e 3e 3d 4d 2e 0d 0a 20 20 20  where N>=M...   
d2e0: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e       /// </para>
d2f0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
d300: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
d310: 2f 20 4e 6f 6e 65 20 6f 66 20 74 68 65 20 78 53  / None of the xS
d320: 61 76 65 70 6f 69 6e 74 28 29 2c 20 78 52 65 6c  avepoint(), xRel
d330: 65 61 73 65 28 29 2c 20 6f 72 20 78 52 6f 6c 6c  ease(), or xRoll
d340: 62 61 63 6b 54 6f 28 29 20 6d 65 74 68 6f 64 73  backTo() methods
d350: 20 77 69 6c 6c 0d 0a 20 20 20 20 20 20 20 20 2f   will..        /
d360: 2f 2f 20 65 76 65 72 20 62 65 20 63 61 6c 6c 65  // ever be calle
d370: 64 20 65 78 63 65 70 74 20 69 6e 20 62 65 74 77  d except in betw
d380: 65 65 6e 20 63 61 6c 6c 73 20 74 6f 20 78 42 65  een calls to xBe
d390: 67 69 6e 28 29 20 61 6e 64 20 65 69 74 68 65 72  gin() and either
d3a0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 78 43  ..        /// xC
d3b0: 6f 6d 6d 69 74 28 29 20 6f 72 20 78 52 6f 6c 6c  ommit() or xRoll
d3c0: 62 61 63 6b 28 29 2e 0d 0a 20 20 20 20 20 20 20  back()...       
d3d0: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
d3e0: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d        /// </summ
d3f0: 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ary>..        //
d400: 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70  / <param name="p
d410: 56 74 61 62 22 3e 0d 0a 20 20 20 20 20 20 20 20  Vtab">..        
d420: 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76 65 20 70  /// The native p
d430: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 71  ointer to the sq
d440: 6c 69 74 65 33 5f 76 74 61 62 20 64 65 72 69 76  lite3_vtab deriv
d450: 65 64 20 73 74 72 75 63 74 75 72 65 2e 0d 0a 20  ed structure... 
d460: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
d470: 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  am>..        ///
d480: 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 69 53   <param name="iS
d490: 61 76 65 70 6f 69 6e 74 22 3e 0d 0a 20 20 20 20  avepoint">..    
d4a0: 20 20 20 20 2f 2f 2f 20 54 68 69 73 20 69 73 20      /// This is 
d4b0: 61 6e 20 69 6e 74 65 67 65 72 20 75 73 65 64 20  an integer used 
d4c0: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
d4d0: 20 61 6e 79 20 73 61 76 65 64 20 73 74 61 74 65   any saved state
d4e0: 73 20 77 69 74 68 20 61 6e 0d 0a 20 20 20 20 20  s with an..     
d4f0: 20 20 20 2f 2f 2f 20 69 64 65 6e 74 69 66 69 65     /// identifie
d500: 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 6f  r greater than o
d510: 72 20 65 71 75 61 6c 20 74 6f 20 74 68 69 73 20  r equal to this 
d520: 73 68 6f 75 6c 64 20 62 65 20 64 65 6c 65 74 65  should be delete
d530: 64 20 62 79 20 74 68 65 0d 0a 20 20 20 20 20 20  d by the..      
d540: 20 20 2f 2f 2f 20 76 69 72 74 75 61 6c 20 74 61    /// virtual ta
d550: 62 6c 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ble...        //
d560: 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20  / </param>..    
d570: 20 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72 6e 73      /// <returns
d580: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41  >..        /// A
d590: 20 73 74 61 6e 64 61 72 64 20 53 51 4c 69 74 65   standard SQLite
d5a0: 20 72 65 74 75 72 6e 20 63 6f 64 65 2e 0d 0a 20   return code... 
d5b0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72 65 74         /// </ret
d5c0: 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 53  urns>..        S
d5d0: 51 4c 69 74 65 45 72 72 6f 72 43 6f 64 65 20 78  QLiteErrorCode x
d5e0: 52 65 6c 65 61 73 65 28 0d 0a 20 20 20 20 20 20  Release(..      
d5f0: 20 20 20 20 20 20 49 6e 74 50 74 72 20 70 56 74        IntPtr pVt
d600: 61 62 2c 0d 0a 20 20 20 20 20 20 20 20 20 20 20  ab,..           
d610: 20 69 6e 74 20 69 53 61 76 65 70 6f 69 6e 74 0d   int iSavepoint.
d620: 0a 20 20 20 20 20 20 20 20 20 20 20 20 29 3b 0d  .            );.
d630: 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 2f 2f  ...        /////
d640: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
d650: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
d660: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
d670: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
d680: 2f 2f 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f  //....        //
d690: 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20  / <summary>..   
d6a0: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
d6b0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65  .        /// The
d6c0: 73 65 20 6d 65 74 68 6f 64 73 20 70 72 6f 76 69  se methods provi
d6d0: 64 65 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  de the virtual t
d6e0: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
d6f0: 69 6f 6e 20 61 6e 0d 0a 20 20 20 20 20 20 20 20  ion an..        
d700: 2f 2f 2f 20 6f 70 70 6f 72 74 75 6e 69 74 79 20  /// opportunity 
d710: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 6e 65 73  to implement nes
d720: 74 65 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73  ted transactions
d730: 2e 20 54 68 65 79 20 61 72 65 20 61 6c 77 61 79  . They are alway
d740: 73 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6f  s..        /// o
d750: 70 74 69 6f 6e 61 6c 20 61 6e 64 20 77 69 6c 6c  ptional and will
d760: 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
d770: 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  in SQLite versio
d780: 6e 20 33 2e 37 2e 37 20 61 6e 64 20 6c 61 74 65  n 3.7.7 and late
d790: 72 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  r...        /// 
d7a0: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
d7b0: 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20   /// <para>..   
d7c0: 20 20 20 20 20 2f 2f 2f 20 57 68 65 6e 20 78 53       /// When xS
d7d0: 61 76 65 70 6f 69 6e 74 28 58 2c 4e 29 20 69 73  avepoint(X,N) is
d7e0: 20 69 6e 76 6f 6b 65 64 2c 20 74 68 61 74 20 69   invoked, that i
d7f0: 73 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68  s a signal to th
d800: 65 20 76 69 72 74 75 61 6c 0d 0a 20 20 20 20 20  e virtual..     
d810: 20 20 20 2f 2f 2f 20 74 61 62 6c 65 20 58 20 74     /// table X t
d820: 68 61 74 20 69 74 20 73 68 6f 75 6c 64 20 73 61  hat it should sa
d830: 76 65 20 69 74 73 20 63 75 72 72 65 6e 74 20 73  ve its current s
d840: 74 61 74 65 20 61 73 20 73 61 76 65 70 6f 69 6e  tate as savepoin
d850: 74 20 4e 2e 20 41 0d 0a 20 20 20 20 20 20 20 20  t N. A..        
d860: 2f 2f 2f 20 73 75 62 73 65 71 75 65 6e 74 20 63  /// subsequent c
d870: 61 6c 6c 20 74 6f 20 78 52 6f 6c 6c 62 61 63 6b  all to xRollback
d880: 54 6f 28 58 2c 52 29 20 6d 65 61 6e 73 20 74 68  To(X,R) means th
d890: 61 74 20 74 68 65 20 73 74 61 74 65 20 6f 66 20  at the state of 
d8a0: 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  the..        ///
d8b0: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 73   virtual table s
d8c0: 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 6f 20  hould return to 
d8d0: 77 68 61 74 20 69 74 20 77 61 73 20 77 68 65 6e  what it was when
d8e0: 20 78 53 61 76 65 70 6f 69 6e 74 28 58 2c 52 29   xSavepoint(X,R)
d8f0: 20 77 61 73 0d 0a 20 20 20 20 20 20 20 20 2f 2f   was..        //
d900: 2f 20 6c 61 73 74 20 63 61 6c 6c 65 64 2e 20 54  / last called. T
d910: 68 65 20 63 61 6c 6c 20 74 6f 20 78 52 6f 6c 6c  he call to xRoll
d920: 62 61 63 6b 54 6f 28 58 2c 52 29 20 77 69 6c 6c  backTo(X,R) will
d930: 20 69 6e 76 61 6c 69 64 61 74 65 20 61 6c 6c 0d   invalidate all.
d940: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 61 76  .        /// sav
d950: 65 70 6f 69 6e 74 73 20 77 69 74 68 20 4e 3e 52  epoints with N>R
d960: 3b 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 69 6e  ; none of the in
d970: 76 61 6c 69 64 65 64 20 73 61 76 65 70 6f 69 6e  valided savepoin
d980: 74 73 20 77 69 6c 6c 20 62 65 0d 0a 20 20 20 20  ts will be..    
d990: 20 20 20 20 2f 2f 2f 20 72 6f 6c 6c 65 64 20 62      /// rolled b
d9a0: 61 63 6b 20 6f 72 20 72 65 6c 65 61 73 65 64 20  ack or released 
d9b0: 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 62 65  without first be
d9c0: 69 6e 67 20 72 65 69 6e 69 74 69 61 6c 69 7a 65  ing reinitialize
d9d0: 64 20 62 79 20 61 20 63 61 6c 6c 0d 0a 20 20 20  d by a call..   
d9e0: 20 20 20 20 20 2f 2f 2f 20 74 6f 20 78 53 61 76       /// to xSav
d9f0: 65 70 6f 69 6e 74 28 29 2e 20 41 20 63 61 6c 6c  epoint(). A call
da00: 20 74 6f 20 78 52 65 6c 65 61 73 65 28 58 2c 4d   to xRelease(X,M
da10: 29 20 69 6e 76 61 6c 69 64 61 74 65 73 20 61 6c  ) invalidates al
da20: 6c 20 73 61 76 65 70 6f 69 6e 74 73 0d 0a 20 20  l savepoints..  
da30: 20 20 20 20 20 20 2f 2f 2f 20 77 68 65 72 65 20        /// where 
da40: 4e 3e 3d 4d 2e 0d 0a 20 20 20 20 20 20 20 20 2f  N>=M...        /
da50: 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  // </para>..    
da60: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a      /// <para>..
da70: 20 20 20 20 20 20 20 20 2f 2f 2f 20 4e 6f 6e 65          /// None
da80: 20 6f 66 20 74 68 65 20 78 53 61 76 65 70 6f 69   of the xSavepoi
da90: 6e 74 28 29 2c 20 78 52 65 6c 65 61 73 65 28 29  nt(), xRelease()
daa0: 2c 20 6f 72 20 78 52 6f 6c 6c 62 61 63 6b 54 6f  , or xRollbackTo
dab0: 28 29 20 6d 65 74 68 6f 64 73 20 77 69 6c 6c 0d  () methods will.
dac0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 65 76 65  .        /// eve
dad0: 72 20 62 65 20 63 61 6c 6c 65 64 20 65 78 63 65  r be called exce
dae0: 70 74 20 69 6e 20 62 65 74 77 65 65 6e 20 63 61  pt in between ca
daf0: 6c 6c 73 20 74 6f 20 78 42 65 67 69 6e 28 29 20  lls to xBegin() 
db00: 61 6e 64 20 65 69 74 68 65 72 0d 0a 20 20 20 20  and either..    
db10: 20 20 20 20 2f 2f 2f 20 78 43 6f 6d 6d 69 74 28      /// xCommit(
db20: 29 20 6f 72 20 78 52 6f 6c 6c 62 61 63 6b 28 29  ) or xRollback()
db30: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
db40: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
db50: 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a  /// </summary>..
db60: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
db70: 61 6d 20 6e 61 6d 65 3d 22 70 56 74 61 62 22 3e  am name="pVtab">
db80: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
db90: 65 20 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72  e native pointer
dba0: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
dbb0: 76 74 61 62 20 64 65 72 69 76 65 64 20 73 74 72  vtab derived str
dbc0: 75 63 74 75 72 65 2e 0d 0a 20 20 20 20 20 20 20  ucture...       
dbd0: 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20   /// </param>.. 
dbe0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
dbf0: 6d 20 6e 61 6d 65 3d 22 69 53 61 76 65 70 6f 69  m name="iSavepoi
dc00: 6e 74 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  nt">..        //
dc10: 2f 20 54 68 69 73 20 69 73 20 61 6e 20 69 6e 74  / This is an int
dc20: 65 67 65 72 20 69 64 65 6e 74 69 66 69 65 72 20  eger identifier 
dc30: 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20  used to specify 
dc40: 61 20 73 70 65 63 69 66 69 63 20 73 61 76 65 64  a specific saved
dc50: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 74  ..        /// st
dc60: 61 74 65 20 66 6f 72 20 74 68 65 20 76 69 72 74  ate for the virt
dc70: 75 61 6c 20 74 61 62 6c 65 20 66 6f 72 20 69 74  ual table for it
dc80: 20 74 6f 20 72 65 73 74 6f 72 65 20 69 74 73 65   to restore itse
dc90: 6c 66 20 62 61 63 6b 20 74 6f 2c 20 77 68 69 63  lf back to, whic
dca0: 68 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73  h..        /// s
dcb0: 68 6f 75 6c 64 20 61 6c 73 6f 20 68 61 76 65 20  hould also have 
dcc0: 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 64 65  the effect of de
dcd0: 6c 65 74 69 6e 67 20 61 6c 6c 20 73 61 76 65 64  leting all saved
dce0: 20 73 74 61 74 65 73 20 77 69 74 68 20 61 6e 0d   states with an.
dcf0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e 74  .        /// int
dd00: 65 67 65 72 20 69 64 65 6e 74 69 66 69 65 72 20  eger identifier 
dd10: 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 69  greater than thi
dd20: 73 20 6f 6e 65 2e 0d 0a 20 20 20 20 20 20 20 20  s one...        
dd30: 2f 2f 2f 20 3c 6c 69 73 74 20 74 79 70 65 3d 22  /// <list type="
dd40: 22 3e 3c 2f 6c 69 73 74 3e 0d 0a 20 20 20 20 20  "></list>..     
dd50: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d     /// </param>.
dd60: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 72 65  .        /// <re
dd70: 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20  turns>..        
dd80: 2f 2f 2f 20 41 20 73 74 61 6e 64 61 72 64 20 53  /// A standard S
dd90: 51 4c 69 74 65 20 72 65 74 75 72 6e 20 63 6f 64  QLite return cod
dda0: 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e...        /// 
ddb0: 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20  </returns>..    
ddc0: 20 20 20 20 53 51 4c 69 74 65 45 72 72 6f 72 43      SQLiteErrorC
ddd0: 6f 64 65 20 78 52 6f 6c 6c 62 61 63 6b 54 6f 28  ode xRollbackTo(
dde0: 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 49 6e  ..            In
ddf0: 74 50 74 72 20 70 56 74 61 62 2c 0d 0a 20 20 20  tPtr pVtab,..   
de00: 20 20 20 20 20 20 20 20 20 69 6e 74 20 69 53 61           int iSa
de10: 76 65 70 6f 69 6e 74 0d 0a 20 20 20 20 20 20 20  vepoint..       
de20: 20 20 20 20 20 29 3b 0d 0a 20 20 20 20 7d 0d 0a       );..    }..
de30: 20 20 20 20 23 65 6e 64 72 65 67 69 6f 6e 0d 0a      #endregion..
de40: 7d 0d 0a                                         }..