System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 278964143c343d1013e5b6d74018744cee640adb:


0000: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
0010: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0020: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0030: 2a 2a 2a 2a 2a 2a 2a 2a 2a 0d 0a 20 2a 20 41 44  *********.. * AD
0040: 4f 2e 4e 45 54 20 32 2e 30 20 44 61 74 61 20 50  O.NET 2.0 Data P
0050: 72 6f 76 69 64 65 72 20 66 6f 72 20 53 51 4c 69  rovider for SQLi
0060: 74 65 20 56 65 72 73 69 6f 6e 20 33 2e 58 0d 0a  te Version 3.X..
0070: 20 2a 20 57 72 69 74 74 65 6e 20 62 79 20 4a 6f   * Written by Jo
0080: 65 20 4d 69 73 74 61 63 68 6b 69 6e 20 28 6a 6f  e Mistachkin (jo
0090: 65 40 6d 69 73 74 61 63 68 6b 69 6e 2e 63 6f 6d  e@mistachkin.com
00a0: 29 0d 0a 20 2a 0d 0a 20 2a 20 52 65 6c 65 61 73  ).. *.. * Releas
00b0: 65 64 20 74 6f 20 74 68 65 20 70 75 62 6c 69 63  ed to the public
00c0: 20 64 6f 6d 61 69 6e 2c 20 75 73 65 20 61 74 20   domain, use at 
00d0: 79 6f 75 72 20 6f 77 6e 20 72 69 73 6b 21 0d 0a  your own risk!..
00e0: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   ***************
00f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0100: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0110: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0d 0a 0d 0a 6e 61  *********/....na
0120: 6d 65 73 70 61 63 65 20 53 79 73 74 65 6d 2e 44  mespace System.D
0130: 61 74 61 2e 53 51 4c 69 74 65 0d 0a 7b 0d 0a 20  ata.SQLite..{.. 
0140: 20 20 20 23 72 65 67 69 6f 6e 20 49 53 51 4c 69     #region ISQLi
0150: 74 65 4e 61 74 69 76 65 4d 6f 64 75 6c 65 20 49  teNativeModule I
0160: 6e 74 65 72 66 61 63 65 0d 0a 20 20 20 20 2f 2f  nterface..    //
0170: 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20  / <summary>..   
0180: 20 2f 2f 2f 20 54 68 69 73 20 69 6e 74 65 72 66   /// This interf
0190: 61 63 65 20 72 65 70 72 65 73 65 6e 74 73 20 61  ace represents a
01a0: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
01b0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 72  mplementation wr
01c0: 69 74 74 65 6e 20 69 6e 0d 0a 20 20 20 20 2f 2f  itten in..    //
01d0: 2f 20 6e 61 74 69 76 65 20 63 6f 64 65 2e 0d 0a  / native code...
01e0: 20 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72      /// </summar
01f0: 79 3e 0d 0a 20 20 20 20 70 75 62 6c 69 63 20 69  y>..    public i
0200: 6e 74 65 72 66 61 63 65 20 49 53 51 4c 69 74 65  nterface ISQLite
0210: 4e 61 74 69 76 65 4d 6f 64 75 6c 65 0d 0a 20 20  NativeModule..  
0220: 20 20 7b 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f    {..        ///
0230: 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20   <summary>..    
0240: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63      /// <para><c
0250: 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ode>..        //
0260: 2f 20 69 6e 74 20 28 2a 78 43 72 65 61 74 65 29  / int (*xCreate)
0270: 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 76 6f  (sqlite3 *db, vo
0280: 69 64 20 2a 70 41 75 78 2c 0d 0a 20 20 20 20 20  id *pAux,..     
0290: 20 20 20 2f 2f 2f 20 20 20 20 20 20 20 20 20 20     ///          
02a0: 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 68      int argc, ch
02b0: 61 72 20 2a 2a 61 72 67 76 2c 0d 0a 20 20 20 20  ar **argv,..    
02c0: 20 20 20 20 2f 2f 2f 20 20 20 20 20 20 20 20 20      ///         
02d0: 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61       sqlite3_vta
02e0: 62 20 2a 2a 70 70 56 54 61 62 2c 0d 0a 20 20 20  b **ppVTab,..   
02f0: 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 20 20 20       ///        
0300: 20 20 20 20 20 20 63 68 61 72 20 2a 2a 70 7a 45        char **pzE
0310: 72 72 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f  rr);..        //
0320: 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e  / </code></para>
0330: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
0340: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
0350: 2f 20 54 68 65 20 78 43 72 65 61 74 65 20 6d 65  / The xCreate me
0360: 74 68 6f 64 20 69 73 20 63 61 6c 6c 65 64 20 74  thod is called t
0370: 6f 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 69  o create a new i
0380: 6e 73 74 61 6e 63 65 20 6f 66 20 61 20 76 69 72  nstance of a vir
0390: 74 75 61 6c 20 74 61 62 6c 65 20 0d 0a 20 20 20  tual table ..   
03a0: 20 20 20 20 20 2f 2f 2f 20 69 6e 20 72 65 73 70       /// in resp
03b0: 6f 6e 73 65 20 74 6f 20 61 20 43 52 45 41 54 45  onse to a CREATE
03c0: 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20 73   VIRTUAL TABLE s
03d0: 74 61 74 65 6d 65 6e 74 2e 0d 0a 20 20 20 20 20  tatement...     
03e0: 20 20 20 2f 2f 2f 20 49 66 20 74 68 65 20 78 43     /// If the xC
03f0: 72 65 61 74 65 20 6d 65 74 68 6f 64 20 69 73 20  reate method is 
0400: 74 68 65 20 73 61 6d 65 20 70 6f 69 6e 74 65 72  the same pointer
0410: 20 61 73 20 74 68 65 20 78 43 6f 6e 6e 65 63 74   as the xConnect
0420: 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68   method, then th
0430: 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 76  e..        /// v
0440: 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20  irtual table is 
0450: 61 6e 20 65 70 6f 6e 79 6d 6f 75 73 20 76 69 72  an eponymous vir
0460: 74 75 61 6c 20 74 61 62 6c 65 2e 0d 0a 20 20 20  tual table...   
0470: 20 20 20 20 20 2f 2f 2f 20 49 66 20 74 68 65 20       /// If the 
0480: 78 43 72 65 61 74 65 20 6d 65 74 68 6f 64 20 69  xCreate method i
0490: 73 20 6f 6d 69 74 74 65 64 20 28 69 66 20 69 74  s omitted (if it
04a0: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
04b0: 65 72 29 20 74 68 65 6e 20 74 68 65 20 76 69 72  er) then the vir
04c0: 74 75 61 6c 20 0d 0a 20 20 20 20 20 20 20 20 2f  tual ..        /
04d0: 2f 2f 20 74 61 62 6c 65 20 69 73 20 61 6e 20 65  // table is an e
04e0: 70 6f 6e 79 6d 6f 75 73 2d 6f 6e 6c 79 20 76 69  ponymous-only vi
04f0: 72 74 75 61 6c 20 74 61 62 6c 65 2e 0d 0a 20 20  rtual table...  
0500: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61        /// </para
0510: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
0520: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
0530: 2f 2f 20 54 68 65 20 64 62 20 70 61 72 61 6d 65  // The db parame
0540: 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
0550: 20 74 6f 20 74 68 65 20 53 51 4c 69 74 65 20 64   to the SQLite d
0560: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
0570: 6f 6e 20 74 68 61 74 20 0d 0a 20 20 20 20 20 20  on that ..      
0580: 20 20 2f 2f 2f 20 69 73 20 65 78 65 63 75 74 69    /// is executi
0590: 6e 67 20 74 68 65 20 43 52 45 41 54 45 20 56 49  ng the CREATE VI
05a0: 52 54 55 41 4c 20 54 41 42 4c 45 20 73 74 61 74  RTUAL TABLE stat
05b0: 65 6d 65 6e 74 2e 20 0d 0a 20 20 20 20 20 20 20  ement. ..       
05c0: 20 2f 2f 2f 20 54 68 65 20 70 41 75 78 20 61 72   /// The pAux ar
05d0: 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 63 6f  gument is the co
05e0: 70 79 20 6f 66 20 74 68 65 20 63 6c 69 65 6e 74  py of the client
05f0: 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68   data pointer th
0600: 61 74 20 77 61 73 20 74 68 65 20 0d 0a 20 20 20  at was the ..   
0610: 20 20 20 20 20 2f 2f 2f 20 66 6f 75 72 74 68 20       /// fourth 
0620: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
0630: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
0640: 6f 64 75 6c 65 28 29 20 6f 72 0d 0a 20 20 20 20  odule() or..    
0650: 20 20 20 20 2f 2f 2f 20 73 71 6c 69 74 65 33 5f      /// sqlite3_
0660: 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32  create_module_v2
0670: 28 29 20 63 61 6c 6c 20 74 68 61 74 20 72 65 67  () call that reg
0680: 69 73 74 65 72 65 64 20 74 68 65 20 0d 0a 20 20  istered the ..  
0690: 20 20 20 20 20 20 2f 2f 2f 20 76 69 72 74 75 61        /// virtua
06a0: 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 2e 20  l table module. 
06b0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
06c0: 65 20 61 72 67 76 20 70 61 72 61 6d 65 74 65 72  e argv parameter
06d0: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
06e0: 61 72 67 63 20 70 6f 69 6e 74 65 72 73 20 74 6f  argc pointers to
06f0: 20 6e 75 6c 6c 20 74 65 72 6d 69 6e 61 74 65 64   null terminated
0700: 20 73 74 72 69 6e 67 73 2e 20 0d 0a 20 20 20 20   strings. ..    
0710: 20 20 20 20 2f 2f 2f 20 54 68 65 20 66 69 72 73      /// The firs
0720: 74 20 73 74 72 69 6e 67 2c 20 61 72 67 76 5b 30  t string, argv[0
0730: 5d 2c 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ], is the name o
0740: 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 62 65 69  f the module bei
0750: 6e 67 20 69 6e 76 6f 6b 65 64 2e 20 20 20 54 68  ng invoked.   Th
0760: 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6d  e..        /// m
0770: 6f 64 75 6c 65 20 6e 61 6d 65 20 69 73 20 74 68  odule name is th
0780: 65 20 6e 61 6d 65 20 70 72 6f 76 69 64 65 64 20  e name provided 
0790: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
07a0: 67 75 6d 65 6e 74 20 74 6f 20 0d 0a 20 20 20 20  gument to ..    
07b0: 20 20 20 20 2f 2f 2f 20 73 71 6c 69 74 65 33 5f      /// sqlite3_
07c0: 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 20  create_module() 
07d0: 61 6e 64 20 61 73 20 74 68 65 20 61 72 67 75 6d  and as the argum
07e0: 65 6e 74 20 74 6f 20 74 68 65 20 55 53 49 4e 47  ent to the USING
07f0: 20 63 6c 61 75 73 65 20 6f 66 20 74 68 65 0d 0a   clause of the..
0800: 20 20 20 20 20 20 20 20 2f 2f 2f 20 43 52 45 41          /// CREA
0810: 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45  TE VIRTUAL TABLE
0820: 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
0830: 69 73 20 72 75 6e 6e 69 6e 67 2e 0d 0a 20 20 20  is running...   
0840: 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 73 65 63       /// The sec
0850: 6f 6e 64 2c 20 61 72 67 76 5b 31 5d 2c 20 69 73  ond, argv[1], is
0860: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
0870: 20 64 61 74 61 62 61 73 65 20 69 6e 20 77 68 69   database in whi
0880: 63 68 20 74 68 65 20 6e 65 77 20 76 69 72 74 75  ch the new virtu
0890: 61 6c 20 74 61 62 6c 65 20 69 73 20 62 65 69 6e  al table is bein
08a0: 67 20 63 72 65 61 74 65 64 2e 20 54 68 65 20 64  g created. The d
08b0: 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20  atabase name is 
08c0: 22 6d 61 69 6e 22 20 66 6f 72 20 74 68 65 20 70  "main" for the p
08d0: 72 69 6d 61 72 79 20 64 61 74 61 62 61 73 65 2c  rimary database,
08e0: 20 6f 72 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f   or..        ///
08f0: 20 22 74 65 6d 70 22 20 66 6f 72 20 54 45 4d 50   "temp" for TEMP
0900: 20 64 61 74 61 62 61 73 65 2c 20 6f 72 20 74 68   database, or th
0910: 65 20 6e 61 6d 65 20 67 69 76 65 6e 20 61 74 20  e name given at 
0920: 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 41  the end of the A
0930: 54 54 41 43 48 0d 0a 20 20 20 20 20 20 20 20 2f  TTACH..        /
0940: 2f 2f 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72  // statement for
0950: 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
0960: 73 65 73 2e 20 20 54 68 65 20 74 68 69 72 64 20  ses.  The third 
0970: 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61  element of the a
0980: 72 72 61 79 2c 20 61 72 67 76 5b 32 5d 2c 20 0d  rray, argv[2], .
0990: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 73 20  .        /// is 
09a0: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
09b0: 6e 65 77 20 76 69 72 74 75 61 6c 20 74 61 62 6c  new virtual tabl
09c0: 65 2c 20 61 73 20 73 70 65 63 69 66 69 65 64 20  e, as specified 
09d0: 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 65 20 54 41  following the TA
09e0: 42 4c 45 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  BLE..        ///
09f0: 20 6b 65 79 77 6f 72 64 20 69 6e 20 74 68 65 20   keyword in the 
0a00: 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20 54  CREATE VIRTUAL T
0a10: 41 42 4c 45 20 73 74 61 74 65 6d 65 6e 74 2e 0d  ABLE statement..
0a20: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 49 66 20  .        /// If 
0a30: 70 72 65 73 65 6e 74 2c 20 74 68 65 20 66 6f 75  present, the fou
0a40: 72 74 68 20 61 6e 64 20 73 75 62 73 65 71 75 65  rth and subseque
0a50: 6e 74 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68  nt strings in th
0a60: 65 20 61 72 67 76 5b 5d 20 61 72 72 61 79 20 72  e argv[] array r
0a70: 65 70 6f 72 74 20 0d 0a 20 20 20 20 20 20 20 20  eport ..        
0a80: 2f 2f 2f 20 74 68 65 20 61 72 67 75 6d 65 6e 74  /// the argument
0a90: 73 20 74 6f 20 74 68 65 20 6d 6f 64 75 6c 65 20  s to the module 
0aa0: 6e 61 6d 65 20 69 6e 20 74 68 65 20 43 52 45 41  name in the CREA
0ab0: 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45  TE VIRTUAL TABLE
0ac0: 20 73 74 61 74 65 6d 65 6e 74 2e 0d 0a 20 20 20   statement...   
0ad0: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e       /// </para>
0ae0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
0af0: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
0b00: 2f 20 54 68 65 20 6a 6f 62 20 6f 66 20 74 68 69  / The job of thi
0b10: 73 20 6d 65 74 68 6f 64 20 69 73 20 74 6f 20 63  s method is to c
0b20: 6f 6e 73 74 72 75 63 74 20 74 68 65 20 6e 65 77  onstruct the new
0b30: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6f   virtual table o
0b40: 62 6a 65 63 74 0d 0a 20 20 20 20 20 20 20 20 2f  bject..        /
0b50: 2f 2f 20 28 61 6e 20 73 71 6c 69 74 65 33 5f 76  // (an sqlite3_v
0b60: 74 61 62 20 6f 62 6a 65 63 74 29 20 61 6e 64 20  tab object) and 
0b70: 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72  return a pointer
0b80: 20 74 6f 20 69 74 20 69 6e 20 2a 70 70 56 54 61   to it in *ppVTa
0b90: 62 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  b...        /// 
0ba0: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
0bb0: 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20   /// <para>..   
0bc0: 20 20 20 20 20 2f 2f 2f 20 41 73 20 70 61 72 74       /// As part
0bd0: 20 6f 66 20 74 68 65 20 74 61 73 6b 20 6f 66 20   of the task of 
0be0: 63 72 65 61 74 69 6e 67 20 61 20 6e 65 77 20 73  creating a new s
0bf0: 71 6c 69 74 65 33 5f 76 74 61 62 20 73 74 72 75  qlite3_vtab stru
0c00: 63 74 75 72 65 2c 20 74 68 69 73 20 0d 0a 20 20  cture, this ..  
0c10: 20 20 20 20 20 20 2f 2f 2f 20 6d 65 74 68 6f 64        /// method
0c20: 20 3c 75 3e 6d 75 73 74 3c 2f 75 3e 20 69 6e 76   <u>must</u> inv
0c30: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 64 65 63 6c  oke sqlite3_decl
0c40: 61 72 65 5f 76 74 61 62 28 29 20 74 6f 20 74 65  are_vtab() to te
0c50: 6c 6c 20 74 68 65 20 53 51 4c 69 74 65 20 0d 0a  ll the SQLite ..
0c60: 20 20 20 20 20 20 20 20 2f 2f 2f 20 63 6f 72 65          /// core
0c70: 20 61 62 6f 75 74 20 74 68 65 20 63 6f 6c 75 6d   about the colum
0c80: 6e 73 20 61 6e 64 20 64 61 74 61 74 79 70 65 73  ns and datatypes
0c90: 20 69 6e 20 74 68 65 20 76 69 72 74 75 61 6c 20   in the virtual 
0ca0: 74 61 62 6c 65 2e 20 0d 0a 20 20 20 20 20 20 20  table. ..       
0cb0: 20 2f 2f 2f 20 54 68 65 20 73 71 6c 69 74 65 33   /// The sqlite3
0cc0: 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 29 20  _declare_vtab() 
0cd0: 41 50 49 20 68 61 73 20 74 68 65 20 66 6f 6c 6c  API has the foll
0ce0: 6f 77 69 6e 67 20 70 72 6f 74 6f 74 79 70 65 3a  owing prototype:
0cf0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
0d00: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
0d10: 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d  // <para><code>.
0d20: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e 74  .        /// int
0d30: 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 65   sqlite3_declare
0d40: 5f 76 74 61 62 28 73 71 6c 69 74 65 33 20 2a 64  _vtab(sqlite3 *d
0d50: 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  b, const char *z
0d60: 43 72 65 61 74 65 54 61 62 6c 65 29 0d 0a 20 20  CreateTable)..  
0d70: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65        /// </code
0d80: 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  ></para>..      
0d90: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
0da0: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 66 69        /// The fi
0db0: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
0dc0: 73 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f  sqlite3_declare_
0dd0: 76 74 61 62 28 29 20 6d 75 73 74 20 62 65 20 74  vtab() must be t
0de0: 68 65 20 73 61 6d 65 20 0d 0a 20 20 20 20 20 20  he same ..      
0df0: 20 20 2f 2f 2f 20 64 61 74 61 62 61 73 65 20 63    /// database c
0e00: 6f 6e 6e 65 63 74 69 6f 6e 20 70 6f 69 6e 74 65  onnection pointe
0e10: 72 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70  r as the first p
0e20: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 69 73  arameter to this
0e30: 20 6d 65 74 68 6f 64 2e 0d 0a 20 20 20 20 20 20   method...      
0e40: 20 20 2f 2f 2f 20 54 68 65 20 73 65 63 6f 6e 64    /// The second
0e50: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
0e60: 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61  ite3_declare_vta
0e70: 62 28 29 20 6d 75 73 74 20 61 20 7a 65 72 6f 2d  b() must a zero-
0e80: 74 65 72 6d 69 6e 61 74 65 64 20 0d 0a 20 20 20  terminated ..   
0e90: 20 20 20 20 20 2f 2f 2f 20 55 54 46 2d 38 20 73       /// UTF-8 s
0ea0: 74 72 69 6e 67 20 74 68 61 74 20 63 6f 6e 74 61  tring that conta
0eb0: 69 6e 73 20 61 20 77 65 6c 6c 2d 66 6f 72 6d 65  ins a well-forme
0ec0: 64 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 73  d CREATE TABLE s
0ed0: 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 0d 0a  tatement that ..
0ee0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 64 65 66 69          /// defi
0ef0: 6e 65 73 20 74 68 65 20 63 6f 6c 75 6d 6e 73 20  nes the columns 
0f00: 69 6e 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  in the virtual t
0f10: 61 62 6c 65 20 61 6e 64 20 74 68 65 69 72 20 64  able and their d
0f20: 61 74 61 20 74 79 70 65 73 2e 20 0d 0a 20 20 20  ata types. ..   
0f30: 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e 61 6d       /// The nam
0f40: 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 69  e of the table i
0f50: 6e 20 74 68 69 73 20 43 52 45 41 54 45 20 54 41  n this CREATE TA
0f60: 42 4c 45 20 73 74 61 74 65 6d 65 6e 74 20 69 73  BLE statement is
0f70: 20 69 67 6e 6f 72 65 64 2c 20 0d 0a 20 20 20 20   ignored, ..    
0f80: 20 20 20 20 2f 2f 2f 20 61 73 20 61 72 65 20 61      /// as are a
0f90: 6c 6c 20 63 6f 6e 73 74 72 61 69 6e 74 73 2e 20  ll constraints. 
0fa0: 4f 6e 6c 79 20 74 68 65 20 63 6f 6c 75 6d 6e 20  Only the column 
0fb0: 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 61 74 79  names and dataty
0fc0: 70 65 73 20 6d 61 74 74 65 72 2e 0d 0a 20 20 20  pes matter...   
0fd0: 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 43 52 45       /// The CRE
0fe0: 41 54 45 20 54 41 42 4c 45 20 73 74 61 74 65 6d  ATE TABLE statem
0ff0: 65 6e 74 20 73 74 72 69 6e 67 20 6e 65 65 64 20  ent string need 
1000: 6e 6f 74 20 74 6f 20 62 65 20 0d 0a 20 20 20 20  not to be ..    
1010: 20 20 20 20 2f 2f 2f 20 68 65 6c 64 20 69 6e 20      /// held in 
1020: 70 65 72 73 69 73 74 65 6e 74 20 6d 65 6d 6f 72  persistent memor
1030: 79 2e 20 20 54 68 65 20 73 74 72 69 6e 67 20 63  y.  The string c
1040: 61 6e 20 62 65 0d 0a 20 20 20 20 20 20 20 20 2f  an be..        /
1050: 2f 2f 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61  // deallocated a
1060: 6e 64 2f 6f 72 20 72 65 75 73 65 64 20 61 73 20  nd/or reused as 
1070: 73 6f 6f 6e 20 61 73 20 74 68 65 20 73 71 6c 69  soon as the sqli
1080: 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62  te3_declare_vtab
1090: 28 29 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ()..        /// 
10a0: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e  routine returns.
10b0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
10c0: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
10d0: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20  // <para>..     
10e0: 20 20 20 2f 2f 2f 20 54 68 65 20 78 43 72 65 61     /// The xCrea
10f0: 74 65 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e  te method need n
1100: 6f 74 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68  ot initialize th
1110: 65 20 70 4d 6f 64 75 6c 65 2c 20 6e 52 65 66 2c  e pModule, nRef,
1120: 20 61 6e 64 20 7a 45 72 72 4d 73 67 0d 0a 20 20   and zErrMsg..  
1130: 20 20 20 20 20 20 2f 2f 2f 20 66 69 65 6c 64 73        /// fields
1140: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
1150: 76 74 61 62 20 6f 62 6a 65 63 74 2e 20 20 54 68  vtab object.  Th
1160: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69  e SQLite core wi
1170: 6c 6c 20 74 61 6b 65 20 63 61 72 65 20 6f 66 20  ll take care of 
1180: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68  ..        /// th
1190: 61 74 20 63 68 6f 72 65 2e 0d 0a 20 20 20 20 20  at chore...     
11a0: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a     /// </para>..
11b0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
11c0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
11d0: 54 68 65 20 78 43 72 65 61 74 65 20 73 68 6f 75  The xCreate shou
11e0: 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ld return SQLITE
11f0: 5f 4f 4b 20 69 66 20 69 74 20 69 73 20 73 75 63  _OK if it is suc
1200: 63 65 73 73 66 75 6c 20 69 6e 20 0d 0a 20 20 20  cessful in ..   
1210: 20 20 20 20 20 2f 2f 2f 20 63 72 65 61 74 69 6e       /// creatin
1220: 67 20 74 68 65 20 6e 65 77 20 76 69 72 74 75 61  g the new virtua
1230: 6c 20 74 61 62 6c 65 2c 20 6f 72 20 53 51 4c 49  l table, or SQLI
1240: 54 45 5f 45 52 52 4f 52 20 69 66 20 69 74 20 69  TE_ERROR if it i
1250: 73 20 6e 6f 74 20 73 75 63 63 65 73 73 66 75 6c  s not successful
1260: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 49  ...        /// I
1270: 66 20 6e 6f 74 20 73 75 63 63 65 73 73 66 75 6c  f not successful
1280: 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 74  , the sqlite3_vt
1290: 61 62 20 73 74 72 75 63 74 75 72 65 20 6d 75 73  ab structure mus
12a0: 74 20 6e 6f 74 20 62 65 20 61 6c 6c 6f 63 61 74  t not be allocat
12b0: 65 64 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ed. ..        //
12c0: 2f 20 41 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  / An error messa
12d0: 67 65 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c  ge may optionall
12e0: 79 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 6e  y be returned in
12f0: 20 2a 70 7a 45 72 72 20 69 66 20 75 6e 73 75 63   *pzErr if unsuc
1300: 63 65 73 73 66 75 6c 2e 0d 0a 20 20 20 20 20 20  cessful...      
1310: 20 20 2f 2f 2f 20 53 70 61 63 65 20 74 6f 20 68    /// Space to h
1320: 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
1330: 73 73 61 67 65 20 73 74 72 69 6e 67 20 6d 75 73  ssage string mus
1340: 74 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 75  t be allocated u
1350: 73 69 6e 67 0d 0a 20 20 20 20 20 20 20 20 2f 2f  sing..        //
1360: 2f 20 61 6e 20 53 51 4c 69 74 65 20 6d 65 6d 6f  / an SQLite memo
1370: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75  ry allocation fu
1380: 6e 63 74 69 6f 6e 20 6c 69 6b 65 20 0d 0a 20 20  nction like ..  
1390: 20 20 20 20 20 20 2f 2f 2f 20 73 71 6c 69 74 65        /// sqlite
13a0: 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
13b0: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
13c0: 61 73 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  as the SQLite co
13d0: 72 65 20 77 69 6c 6c 0d 0a 20 20 20 20 20 20 20  re will..       
13e0: 20 2f 2f 2f 20 61 74 74 65 6d 70 74 20 74 6f 20   /// attempt to 
13f0: 66 72 65 65 20 74 68 65 20 73 70 61 63 65 20 75  free the space u
1400: 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  sing sqlite3_fre
1410: 65 28 29 20 61 66 74 65 72 20 74 68 65 20 65 72  e() after the er
1420: 72 6f 72 20 68 61 73 0d 0a 20 20 20 20 20 20 20  ror has..       
1430: 20 2f 2f 2f 20 62 65 65 6e 20 72 65 70 6f 72 74   /// been report
1440: 65 64 20 75 70 20 74 6f 20 74 68 65 20 61 70 70  ed up to the app
1450: 6c 69 63 61 74 69 6f 6e 2e 0d 0a 20 20 20 20 20  lication...     
1460: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a     /// </para>..
1470: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
1480: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
1490: 49 66 20 74 68 65 20 78 43 72 65 61 74 65 20 6d  If the xCreate m
14a0: 65 74 68 6f 64 20 69 73 20 6f 6d 69 74 74 65 64  ethod is omitted
14b0: 20 28 6c 65 66 74 20 61 73 20 61 20 4e 55 4c 4c   (left as a NULL
14c0: 20 70 6f 69 6e 74 65 72 29 20 74 68 65 6e 20 74   pointer) then t
14d0: 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  he..        /// 
14e0: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 73  virtual table is
14f0: 20 61 6e 20 65 70 6f 6e 79 6d 6f 75 73 2d 6f 6e   an eponymous-on
1500: 6c 79 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ly virtual table
1510: 2e 20 20 4e 65 77 20 69 6e 73 74 61 6e 63 65 73  .  New instances
1520: 20 6f 66 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f   of..        ///
1530: 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
1540: 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 72 65  le cannot be cre
1550: 61 74 65 64 20 75 73 69 6e 67 20 43 52 45 41 54  ated using CREAT
1560: 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20  E VIRTUAL TABLE 
1570: 61 6e 64 20 74 68 65 0d 0a 20 20 20 20 20 20 20  and the..       
1580: 20 2f 2f 2f 20 76 69 72 74 75 61 6c 20 74 61 62   /// virtual tab
1590: 6c 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75  le can only be u
15a0: 73 65 64 20 76 69 61 20 69 74 73 20 6d 6f 64 75  sed via its modu
15b0: 6c 65 20 6e 61 6d 65 2e 0d 0a 20 20 20 20 20 20  le name...      
15c0: 20 20 2f 2f 2f 20 4e 6f 74 65 20 74 68 61 74 20    /// Note that 
15d0: 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 73 20  SQLite versions 
15e0: 70 72 69 6f 72 20 74 6f 20 33 2e 39 2e 30 20 28  prior to 3.9.0 (
15f0: 32 30 31 35 2d 31 30 2d 31 34 29 20 64 6f 20 6e  2015-10-14) do n
1600: 6f 74 20 75 6e 64 65 72 73 74 61 6e 64 0d 0a 20  ot understand.. 
1610: 20 20 20 20 20 20 20 2f 2f 2f 20 65 70 6f 6e 79         /// epony
1620: 6d 6f 75 73 2d 6f 6e 6c 79 20 76 69 72 74 75 61  mous-only virtua
1630: 6c 20 74 61 62 6c 65 73 20 61 6e 64 20 77 69 6c  l tables and wil
1640: 6c 20 73 65 67 66 61 75 6c 74 20 69 66 20 61 6e  l segfault if an
1650: 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
1660: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 6f  ..        /// to
1670: 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20   CREATE VIRTUAL 
1680: 54 41 42 4c 45 20 6f 6e 20 61 6e 20 65 70 6f 6e  TABLE on an epon
1690: 79 6d 6f 75 73 2d 6f 6e 6c 79 20 76 69 72 74 75  ymous-only virtu
16a0: 61 6c 20 74 61 62 6c 65 20 62 65 63 61 75 73 65  al table because
16b0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68  ..        /// th
16c0: 65 20 78 43 72 65 61 74 65 20 6d 65 74 68 6f 64  e xCreate method
16d0: 20 77 61 73 20 6e 6f 74 20 63 68 65 63 6b 65 64   was not checked
16e0: 20 66 6f 72 20 6e 75 6c 6c 2e 0d 0a 20 20 20 20   for null...    
16f0: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
1700: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
1710: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
1720: 20 49 66 20 74 68 65 20 78 43 72 65 61 74 65 20   If the xCreate 
1730: 6d 65 74 68 6f 64 20 69 73 20 74 68 65 20 65 78  method is the ex
1740: 61 63 74 20 73 61 6d 65 20 70 6f 69 6e 74 65 72  act same pointer
1750: 20 61 73 20 74 68 65 20 78 43 6f 6e 6e 65 63 74   as the xConnect
1760: 20 6d 65 74 68 6f 64 2c 0d 0a 20 20 20 20 20 20   method,..      
1770: 20 20 2f 2f 2f 20 74 68 61 74 20 69 6e 64 69 63    /// that indic
1780: 61 74 65 73 20 74 68 61 74 20 74 68 65 20 76 69  ates that the vi
1790: 72 74 75 61 6c 20 74 61 62 6c 65 20 64 6f 65 73  rtual table does
17a0: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 69   not need to ini
17b0: 74 69 61 6c 69 7a 65 20 62 61 63 6b 69 6e 67 0d  tialize backing.
17c0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 74 6f  .        /// sto
17d0: 72 65 2e 20 20 53 75 63 68 20 61 20 76 69 72 74  re.  Such a virt
17e0: 75 61 6c 20 74 61 62 6c 65 20 63 61 6e 20 62 65  ual table can be
17f0: 20 75 73 65 64 20 61 73 20 61 6e 20 65 70 6f 6e   used as an epon
1800: 79 6d 6f 75 73 20 76 69 72 74 75 61 6c 20 74 61  ymous virtual ta
1810: 62 6c 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ble..        ///
1820: 20 6f 72 20 61 73 20 61 20 6e 61 6d 65 64 20 76   or as a named v
1830: 69 72 74 75 61 6c 20 74 61 62 6c 65 20 75 73 69  irtual table usi
1840: 6e 67 20 43 52 45 41 54 45 20 56 49 52 54 55 41  ng CREATE VIRTUA
1850: 4c 20 54 41 42 4c 45 20 6f 72 20 62 6f 74 68 2e  L TABLE or both.
1860: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
1870: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
1880: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20  // <para>..     
1890: 20 20 20 2f 2f 2f 20 49 66 20 61 20 63 6f 6c 75     /// If a colu
18a0: 6d 6e 20 64 61 74 61 74 79 70 65 20 63 6f 6e 74  mn datatype cont
18b0: 61 69 6e 73 20 74 68 65 20 73 70 65 63 69 61 6c  ains the special
18c0: 20 6b 65 79 77 6f 72 64 20 22 48 49 44 44 45 4e   keyword "HIDDEN
18d0: 22 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 28  "..        /// (
18e0: 69 6e 20 61 6e 79 20 63 6f 6d 62 69 6e 61 74 69  in any combinati
18f0: 6f 6e 20 6f 66 20 75 70 70 65 72 20 61 6e 64 20  on of upper and 
1900: 6c 6f 77 65 72 20 63 61 73 65 20 6c 65 74 74 65  lower case lette
1910: 72 73 29 20 74 68 65 6e 20 74 68 61 74 20 6b 65  rs) then that ke
1920: 79 77 6f 72 64 0d 0a 20 20 20 20 20 20 20 20 2f  yword..        /
1930: 2f 2f 20 69 74 20 69 73 20 6f 6d 69 74 74 65 64  // it is omitted
1940: 20 66 72 6f 6d 20 74 68 65 20 63 6f 6c 75 6d 6e   from the column
1950: 20 64 61 74 61 74 79 70 65 20 6e 61 6d 65 20 61   datatype name a
1960: 6e 64 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73  nd the column is
1970: 20 6d 61 72 6b 65 64 20 0d 0a 20 20 20 20 20 20   marked ..      
1980: 20 20 2f 2f 2f 20 61 73 20 61 20 68 69 64 64 65    /// as a hidde
1990: 6e 20 63 6f 6c 75 6d 6e 20 69 6e 74 65 72 6e 61  n column interna
19a0: 6c 6c 79 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f  lly. ..        /
19b0: 2f 2f 20 41 20 68 69 64 64 65 6e 20 63 6f 6c 75  // A hidden colu
19c0: 6d 6e 20 64 69 66 66 65 72 73 20 66 72 6f 6d 20  mn differs from 
19d0: 61 20 6e 6f 72 6d 61 6c 20 63 6f 6c 75 6d 6e 20  a normal column 
19e0: 69 6e 20 74 68 72 65 65 20 72 65 73 70 65 63 74  in three respect
19f0: 73 3a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  s:..        /// 
1a00: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
1a10: 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20   /// <para>..   
1a20: 20 20 20 20 20 2f 2f 2f 20 3c 21 5b 43 44 41 54       /// <![CDAT
1a30: 41 5b 3c 75 6c 3e 5d 5d 3e 0d 0a 20 20 20 20 20  A[<ul>]]>..     
1a40: 20 20 20 2f 2f 2f 20 3c 21 5b 43 44 41 54 41 5b     /// <![CDATA[
1a50: 3c 6c 69 3e 5d 5d 3e 20 48 69 64 64 65 6e 20 63  <li>]]> Hidden c
1a60: 6f 6c 75 6d 6e 73 20 61 72 65 20 6e 6f 74 20 6c  olumns are not l
1a70: 69 73 74 65 64 20 69 6e 20 74 68 65 20 64 61 74  isted in the dat
1a80: 61 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79  aset returned by
1a90: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20   ..        ///  
1aa0: 20 20 20 20 22 50 52 41 47 4d 41 20 74 61 62 6c      "PRAGMA tabl
1ab0: 65 5f 69 6e 66 6f 22 2c 0d 0a 20 20 20 20 20 20  e_info",..      
1ac0: 20 20 2f 2f 2f 20 3c 21 5b 43 44 41 54 41 5b 3c    /// <![CDATA[<
1ad0: 2f 6c 69 3e 5d 5d 3e 3c 21 5b 43 44 41 54 41 5b  /li>]]><![CDATA[
1ae0: 3c 6c 69 3e 5d 5d 3e 20 48 69 64 64 65 6e 20 63  <li>]]> Hidden c
1af0: 6f 6c 75 6d 6e 73 20 61 72 65 20 6e 6f 74 20 69  olumns are not i
1b00: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 65  ncluded in the e
1b10: 78 70 61 6e 73 69 6f 6e 20 6f 66 20 61 20 22 2a  xpansion of a "*
1b20: 22 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20  "..        ///  
1b30: 20 20 20 20 65 78 70 72 65 73 73 69 6f 6e 20 69      expression i
1b40: 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
1b50: 20 6f 66 20 61 20 53 45 4c 45 43 54 2c 20 61 6e   of a SELECT, an
1b60: 64 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  d..        /// <
1b70: 21 5b 43 44 41 54 41 5b 3c 2f 6c 69 3e 5d 5d 3e  ![CDATA[</li>]]>
1b80: 3c 21 5b 43 44 41 54 41 5b 3c 6c 69 3e 5d 5d 3e  <![CDATA[<li>]]>
1b90: 20 48 69 64 64 65 6e 20 63 6f 6c 75 6d 6e 73 20   Hidden columns 
1ba0: 61 72 65 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64  are not included
1bb0: 20 69 6e 20 74 68 65 20 69 6d 70 6c 69 63 69 74   in the implicit
1bc0: 20 63 6f 6c 75 6d 6e 2d 6c 69 73 74 20 0d 0a 20   column-list .. 
1bd0: 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 20         ///      
1be0: 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45 52  used by an INSER
1bf0: 54 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  T statement that
1c00: 20 6c 61 63 6b 73 20 61 6e 20 65 78 70 6c 69 63   lacks an explic
1c10: 69 74 20 63 6f 6c 75 6d 6e 2d 6c 69 73 74 2e 20  it column-list. 
1c20: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 21  ..        /// <!
1c30: 5b 43 44 41 54 41 5b 3c 2f 6c 69 3e 5d 5d 3e 3c  [CDATA[</li>]]><
1c40: 21 5b 43 44 41 54 41 5b 3c 2f 75 6c 3e 5d 5d 3e  ![CDATA[</ul>]]>
1c50: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
1c60: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
1c70: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20  // <para>..     
1c80: 20 20 20 2f 2f 2f 20 46 6f 72 20 65 78 61 6d 70     /// For examp
1c90: 6c 65 2c 20 69 66 20 74 68 65 20 66 6f 6c 6c 6f  le, if the follo
1ca0: 77 69 6e 67 20 53 51 4c 20 69 73 20 70 61 73 73  wing SQL is pass
1cb0: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 65  ed to sqlite3_de
1cc0: 63 6c 61 72 65 5f 76 74 61 62 28 29 3a 0d 0a 20  clare_vtab():.. 
1cd0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
1ce0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
1cf0: 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20  <para><code>..  
1d00: 20 20 20 20 20 20 2f 2f 2f 20 43 52 45 41 54 45        /// CREATE
1d10: 20 54 41 42 4c 45 20 78 28 61 20 48 49 44 44 45   TABLE x(a HIDDE
1d20: 4e 20 56 41 52 43 48 41 52 28 31 32 29 2c 20 62  N VARCHAR(12), b
1d30: 20 49 4e 54 45 47 45 52 2c 20 63 20 49 4e 54 45   INTEGER, c INTE
1d40: 47 45 52 20 48 69 64 64 65 6e 29 3b 0d 0a 20 20  GER Hidden);..  
1d50: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65        /// </code
1d60: 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  ></para>..      
1d70: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
1d80: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 6e 20 74        /// Then t
1d90: 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
1da0: 20 77 6f 75 6c 64 20 62 65 20 63 72 65 61 74 65   would be create
1db0: 64 20 77 69 74 68 20 74 77 6f 20 68 69 64 64 65  d with two hidde
1dc0: 6e 20 63 6f 6c 75 6d 6e 73 2c 0d 0a 20 20 20 20  n columns,..    
1dd0: 20 20 20 20 2f 2f 2f 20 61 6e 64 20 77 69 74 68      /// and with
1de0: 20 64 61 74 61 74 79 70 65 73 20 6f 66 20 22 56   datatypes of "V
1df0: 41 52 43 48 41 52 28 31 32 29 22 20 61 6e 64 20  ARCHAR(12)" and 
1e00: 22 49 4e 54 45 47 45 52 22 2e 0d 0a 20 20 20 20  "INTEGER"...    
1e10: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
1e20: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
1e30: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
1e40: 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20   An example use 
1e50: 6f 66 20 68 69 64 64 65 6e 20 63 6f 6c 75 6d 6e  of hidden column
1e60: 73 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e  s can be seen in
1e70: 20 74 68 65 20 46 54 53 33 20 76 69 72 74 75 61   the FTS3 virtua
1e80: 6c 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  l ..        /// 
1e90: 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
1ea0: 74 69 6f 6e 2c 20 77 68 65 72 65 20 65 76 65 72  tion, where ever
1eb0: 79 20 46 54 53 20 76 69 72 74 75 61 6c 20 74 61  y FTS virtual ta
1ec0: 62 6c 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ble..        ///
1ed0: 20 63 6f 6e 74 61 69 6e 73 20 61 6e 20 46 54 53   contains an FTS
1ee0: 20 68 69 64 64 65 6e 20 63 6f 6c 75 6d 6e 20 74   hidden column t
1ef0: 68 61 74 20 69 73 20 75 73 65 64 20 74 6f 20 70  hat is used to p
1f00: 61 73 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ass information 
1f10: 66 72 6f 6d 20 74 68 65 0d 0a 20 20 20 20 20 20  from the..      
1f20: 20 20 2f 2f 2f 20 76 69 72 74 75 61 6c 20 74 61    /// virtual ta
1f30: 62 6c 65 20 69 6e 74 6f 20 46 54 53 20 61 75 78  ble into FTS aux
1f40: 69 6c 69 61 72 79 20 66 75 6e 63 74 69 6f 6e 73  iliary functions
1f50: 20 61 6e 64 20 74 6f 20 74 68 65 20 46 54 53 20   and to the FTS 
1f60: 4d 41 54 43 48 20 6f 70 65 72 61 74 6f 72 2e 0d  MATCH operator..
1f70: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
1f80: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
1f90: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
1fa0: 20 20 2f 2f 2f 20 41 20 76 69 72 74 75 61 6c 20    /// A virtual 
1fb0: 74 61 62 6c 65 20 74 68 61 74 20 63 6f 6e 74 61  table that conta
1fc0: 69 6e 73 20 68 69 64 64 65 6e 20 63 6f 6c 75 6d  ins hidden colum
1fd0: 6e 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c  ns can be used l
1fe0: 69 6b 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ike..        ///
1ff0: 20 61 20 74 61 62 6c 65 2d 76 61 6c 75 65 64 20   a table-valued 
2000: 66 75 6e 63 74 69 6f 6e 20 69 6e 20 74 68 65 20  function in the 
2010: 46 52 4f 4d 20 63 6c 61 75 73 65 20 6f 66 20 61  FROM clause of a
2020: 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
2030: 74 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  t...        /// 
2040: 54 68 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  The arguments to
2050: 20 74 68 65 20 74 61 62 6c 65 2d 76 61 6c 75 65   the table-value
2060: 64 20 66 75 6e 63 74 69 6f 6e 20 62 65 63 6f 6d  d function becom
2070: 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 6f 6e  e constraints on
2080: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74   ..        /// t
2090: 68 65 20 48 49 44 44 45 4e 20 63 6f 6c 75 6d 6e  he HIDDEN column
20a0: 73 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c  s of the virtual
20b0: 20 74 61 62 6c 65 2e 0d 0a 20 20 20 20 20 20 20   table...       
20c0: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
20d0: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
20e0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 46 6f  ..        /// Fo
20f0: 72 20 65 78 61 6d 70 6c 65 2c 20 74 68 65 20 22  r example, the "
2100: 67 65 6e 65 72 61 74 65 5f 73 65 72 69 65 73 22  generate_series"
2110: 20 65 78 74 65 6e 73 69 6f 6e 20 28 6c 6f 63 61   extension (loca
2120: 74 65 64 20 69 6e 20 74 68 65 0d 0a 20 20 20 20  ted in the..    
2130: 20 20 20 20 2f 2f 2f 20 65 78 74 2f 6d 69 73 63      /// ext/misc
2140: 2f 73 65 72 69 65 73 2e 63 0d 0a 20 20 20 20 20  /series.c..     
2150: 20 20 20 2f 2f 2f 20 66 69 6c 65 20 69 6e 20 74     /// file in t
2160: 68 65 20 73 6f 75 72 63 65 20 74 72 65 65 29 0d  he source tree).
2170: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6d 70  .        /// imp
2180: 6c 65 6d 65 6e 74 73 20 61 6e 20 65 70 6f 6e 79  lements an epony
2190: 6d 6f 75 73 20 76 69 72 74 75 61 6c 20 74 61 62  mous virtual tab
21a0: 6c 65 20 77 69 74 68 20 74 68 65 20 66 6f 6c 6c  le with the foll
21b0: 6f 77 69 6e 67 20 73 63 68 65 6d 61 3a 0d 0a 20  owing schema:.. 
21c0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
21d0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
21e0: 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20  <para><code>..  
21f0: 20 20 20 20 20 20 2f 2f 2f 20 43 52 45 41 54 45        /// CREATE
2200: 20 54 41 42 4c 45 20 67 65 6e 65 72 61 74 65 5f   TABLE generate_
2210: 73 65 72 69 65 73 28 0d 0a 20 20 20 20 20 20 20  series(..       
2220: 20 2f 2f 2f 20 20 20 76 61 6c 75 65 2c 0d 0a 20   ///   value,.. 
2230: 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 73 74 61         ///   sta
2240: 72 74 20 48 49 44 44 45 4e 2c 0d 0a 20 20 20 20  rt HIDDEN,..    
2250: 20 20 20 20 2f 2f 2f 20 20 20 73 74 6f 70 20 48      ///   stop H
2260: 49 44 44 45 4e 2c 0d 0a 20 20 20 20 20 20 20 20  IDDEN,..        
2270: 2f 2f 2f 20 20 20 73 74 65 70 20 48 49 44 44 45  ///   step HIDDE
2280: 4e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 29  N..        /// )
2290: 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ;..        /// <
22a0: 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20  /code></para>.. 
22b0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
22c0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54  >..        /// T
22d0: 68 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  he sqlite3_modul
22e0: 65 2e 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74  e.xBestIndex met
22f0: 68 6f 64 20 69 6e 20 74 68 65 20 69 6d 70 6c 65  hod in the imple
2300: 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 69  mentation of thi
2310: 73 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74  s..        /// t
2320: 61 62 6c 65 20 63 68 65 63 6b 73 20 66 6f 72 20  able checks for 
2330: 65 71 75 61 6c 69 74 79 20 63 6f 6e 73 74 72 61  equality constra
2340: 69 6e 74 73 20 61 67 61 69 6e 73 74 20 74 68 65  ints against the
2350: 20 48 49 44 44 45 4e 20 63 6f 6c 75 6d 6e 73 2c   HIDDEN columns,
2360: 20 61 6e 64 20 75 73 65 73 0d 0a 20 20 20 20 20   and uses..     
2370: 20 20 20 2f 2f 2f 20 74 68 6f 73 65 20 61 73 20     /// those as 
2380: 69 6e 70 75 74 20 70 61 72 61 6d 65 74 65 72 73  input parameters
2390: 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68   to determine th
23a0: 65 20 72 61 6e 67 65 20 6f 66 20 69 6e 74 65 67  e range of integ
23b0: 65 72 20 22 76 61 6c 75 65 22 20 6f 75 74 70 75  er "value" outpu
23c0: 74 73 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ts..        /// 
23d0: 74 6f 20 67 65 6e 65 72 61 74 65 2e 20 20 52 65  to generate.  Re
23e0: 61 73 6f 6e 61 62 6c 65 20 64 65 66 61 75 6c 74  asonable default
23f0: 73 20 61 72 65 20 75 73 65 64 20 66 6f 72 20 61  s are used for a
2400: 6e 79 20 75 6e 63 6f 6e 73 74 72 61 69 6e 65 64  ny unconstrained
2410: 20 63 6f 6c 75 6d 6e 73 2e 0d 0a 20 20 20 20 20   columns...     
2420: 20 20 20 2f 2f 2f 20 46 6f 72 20 65 78 61 6d 70     /// For examp
2430: 6c 65 2c 20 74 6f 20 6c 69 73 74 20 61 6c 6c 20  le, to list all 
2440: 69 6e 74 65 67 65 72 73 20 62 65 74 77 65 65 6e  integers between
2450: 20 35 20 61 6e 64 20 35 30 3a 0d 0a 20 20 20 20   5 and 50:..    
2460: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
2470: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
2480: 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20  ra><code>..     
2490: 20 20 20 2f 2f 2f 20 53 45 4c 45 43 54 20 76 61     /// SELECT va
24a0: 6c 75 65 20 46 52 4f 4d 20 67 65 6e 65 72 61 74  lue FROM generat
24b0: 65 5f 73 65 72 69 65 73 28 35 2c 35 30 29 3b 0d  e_series(5,50);.
24c0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63  .        /// </c
24d0: 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  ode></para>..   
24e0: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
24f0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65  .        /// The
2500: 20 70 72 65 76 69 6f 75 73 20 71 75 65 72 79 20   previous query 
2510: 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
2520: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 3a 0d   the following:.
2530: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
2540: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
2550: 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a  / <para><code>..
2560: 20 20 20 20 20 20 20 20 2f 2f 2f 20 53 45 4c 45          /// SELE
2570: 43 54 20 76 61 6c 75 65 20 46 52 4f 4d 20 67 65  CT value FROM ge
2580: 6e 65 72 61 74 65 5f 73 65 72 69 65 73 20 57 48  nerate_series WH
2590: 45 52 45 20 73 74 61 72 74 3d 35 20 41 4e 44 20  ERE start=5 AND 
25a0: 73 74 6f 70 3d 35 30 3b 0d 0a 20 20 20 20 20 20  stop=50;..      
25b0: 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70    /// </code></p
25c0: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
25d0: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
25e0: 20 20 2f 2f 2f 20 41 72 67 75 6d 65 6e 74 73 20    /// Arguments 
25f0: 6f 6e 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  on the virtual t
2600: 61 62 6c 65 20 6e 61 6d 65 20 61 72 65 20 6d 61  able name are ma
2610: 74 63 68 65 64 20 74 6f 20 68 69 64 64 65 6e 20  tched to hidden 
2620: 63 6f 6c 75 6d 6e 73 0d 0a 20 20 20 20 20 20 20  columns..       
2630: 20 2f 2f 2f 20 69 6e 20 6f 72 64 65 72 2e 20 20   /// in order.  
2640: 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  The number of ar
2650: 67 75 6d 65 6e 74 73 20 63 61 6e 20 62 65 20 6c  guments can be l
2660: 65 73 73 20 74 68 61 6e 20 74 68 65 0d 0a 20 20  ess than the..  
2670: 20 20 20 20 20 20 2f 2f 2f 20 6e 75 6d 62 65 72        /// number
2680: 20 6f 66 20 68 69 64 64 65 6e 20 63 6f 6c 75 6d   of hidden colum
2690: 6e 73 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73  ns, in which cas
26a0: 65 20 74 68 65 20 6c 61 74 74 65 72 20 68 69 64  e the latter hid
26b0: 64 65 6e 20 63 6f 6c 75 6d 6e 73 20 61 72 65 0d  den columns are.
26c0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 75 6e 63  .        /// unc
26d0: 6f 6e 73 74 72 61 69 6e 65 64 2e 20 20 48 6f 77  onstrained.  How
26e0: 65 76 65 72 2c 20 61 6e 20 65 72 72 6f 72 20 72  ever, an error r
26f0: 65 73 75 6c 74 73 20 69 66 20 74 68 65 72 65 20  esults if there 
2700: 61 72 65 20 6d 6f 72 65 20 61 72 67 75 6d 65 6e  are more argumen
2710: 74 73 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ts..        /// 
2720: 74 68 61 6e 20 74 68 65 72 65 20 61 72 65 20 68  than there are h
2730: 69 64 64 65 6e 20 63 6f 6c 75 6d 6e 73 20 69 6e  idden columns in
2740: 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
2750: 6c 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  le...        ///
2760: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
2770: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
2780: 20 20 20 20 20 20 2f 2f 2f 20 42 65 67 69 6e 6e        /// Beginn
2790: 69 6e 67 20 77 69 74 68 20 53 51 4c 69 74 65 20  ing with SQLite 
27a0: 76 65 72 73 69 6f 6e 20 33 2e 31 34 2e 30 20 28  version 3.14.0 (
27b0: 32 30 31 36 2d 30 38 2d 30 38 29 2c 20 0d 0a 20  2016-08-08), .. 
27c0: 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 20 43         /// the C
27d0: 52 45 41 54 45 20 54 41 42 4c 45 20 73 74 61 74  REATE TABLE stat
27e0: 65 6d 65 6e 74 20 74 68 61 74 0d 0a 20 20 20 20  ement that..    
27f0: 20 20 20 20 2f 2f 2f 20 69 73 20 70 61 73 73 65      /// is passe
2800: 64 20 69 6e 74 6f 20 73 71 6c 69 74 65 33 5f 64  d into sqlite3_d
2810: 65 63 6c 61 72 65 5f 76 74 61 62 28 29 20 6d 61  eclare_vtab() ma
2820: 79 20 63 6f 6e 74 61 69 6e 20 61 20 57 49 54 48  y contain a WITH
2830: 4f 55 54 20 52 4f 57 49 44 20 63 6c 61 75 73 65  OUT ROWID clause
2840: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54  ...        /// T
2850: 68 69 73 20 69 73 20 75 73 65 66 75 6c 20 66 6f  his is useful fo
2860: 72 20 63 61 73 65 73 20 77 68 65 72 65 20 74 68  r cases where th
2870: 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  e virtual table 
2880: 72 6f 77 73 20 0d 0a 20 20 20 20 20 20 20 20 2f  rows ..        /
2890: 2f 2f 20 63 61 6e 6e 6f 74 20 65 61 73 69 6c 79  // cannot easily
28a0: 20 62 65 20 6d 61 70 70 65 64 20 69 6e 74 6f 20   be mapped into 
28b0: 75 6e 69 71 75 65 20 69 6e 74 65 67 65 72 73 2e  unique integers.
28c0: 20 20 41 20 43 52 45 41 54 45 20 54 41 42 4c 45    A CREATE TABLE
28d0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 74  ..        /// st
28e0: 61 74 65 6d 65 6e 74 20 74 68 61 74 20 69 6e 63  atement that inc
28f0: 6c 75 64 65 73 20 57 49 54 48 4f 55 54 20 52 4f  ludes WITHOUT RO
2900: 57 49 44 20 6d 75 73 74 20 64 65 66 69 6e 65 20  WID must define 
2910: 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 75  one or more colu
2920: 6d 6e 73 20 61 73 0d 0a 20 20 20 20 20 20 20 20  mns as..        
2930: 2f 2f 2f 20 74 68 65 20 50 52 49 4d 41 52 59 20  /// the PRIMARY 
2940: 4b 45 59 2e 20 20 45 76 65 72 79 20 63 6f 6c 75  KEY.  Every colu
2950: 6d 6e 20 6f 66 20 74 68 65 20 50 52 49 4d 41 52  mn of the PRIMAR
2960: 59 20 4b 45 59 20 6d 75 73 74 20 69 6e 64 69 76  Y KEY must indiv
2970: 69 64 75 61 6c 6c 79 20 62 65 0d 0a 20 20 20 20  idually be..    
2980: 20 20 20 20 2f 2f 2f 20 4e 4f 54 20 4e 55 4c 4c      /// NOT NULL
2990: 20 61 6e 64 20 61 6c 6c 20 63 6f 6c 75 6d 6e 73   and all columns
29a0: 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6d 75   for each row mu
29b0: 73 74 20 62 65 20 63 6f 6c 6c 65 63 74 69 76 65  st be collective
29c0: 6c 79 20 75 6e 69 71 75 65 2e 0d 0a 20 20 20 20  ly unique...    
29d0: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
29e0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
29f0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
2a00: 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74   Note that SQLit
2a10: 65 20 64 6f 65 73 20 6e 6f 74 20 65 6e 66 6f 72  e does not enfor
2a20: 63 65 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b  ce the PRIMARY K
2a30: 45 59 20 66 6f 72 20 61 20 57 49 54 48 4f 55 54  EY for a WITHOUT
2a40: 20 52 4f 57 49 44 0d 0a 20 20 20 20 20 20 20 20   ROWID..        
2a50: 2f 2f 2f 20 76 69 72 74 75 61 6c 20 74 61 62 6c  /// virtual tabl
2a60: 65 2e 20 20 45 6e 66 6f 72 63 65 6d 65 6e 74 20  e.  Enforcement 
2a70: 69 73 20 74 68 65 20 72 65 73 70 6f 6e 73 69 62  is the responsib
2a80: 69 6c 69 74 79 20 6f 66 20 74 68 65 20 75 6e 64  ility of the und
2a90: 65 72 6c 79 69 6e 67 0d 0a 20 20 20 20 20 20 20  erlying..       
2aa0: 20 2f 2f 2f 20 76 69 72 74 75 61 6c 20 74 61 62   /// virtual tab
2ab0: 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
2ac0: 6e 2e 20 20 42 75 74 20 53 51 4c 69 74 65 20 64  n.  But SQLite d
2ad0: 6f 65 73 20 61 73 73 75 6d 65 20 74 68 61 74 20  oes assume that 
2ae0: 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59 0d  the PRIMARY KEY.
2af0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 63 6f 6e  .        /// con
2b00: 73 74 72 61 69 6e 74 20 69 73 20 76 61 6c 69 64  straint is valid
2b10: 20 2d 20 74 68 61 74 20 74 68 65 20 69 64 65 6e   - that the iden
2b20: 74 69 66 69 65 64 20 63 6f 6c 75 6d 6e 73 20 72  tified columns r
2b30: 65 61 6c 6c 79 20 61 72 65 20 55 4e 49 51 55 45  eally are UNIQUE
2b40: 20 61 6e 64 0d 0a 20 20 20 20 20 20 20 20 2f 2f   and..        //
2b50: 2f 20 4e 4f 54 20 4e 55 4c 4c 20 2d 20 61 6e 64  / NOT NULL - and
2b60: 20 69 74 20 75 73 65 73 20 74 68 61 74 20 61 73   it uses that as
2b70: 73 75 6d 70 74 69 6f 6e 20 74 6f 20 6f 70 74 69  sumption to opti
2b80: 6d 69 7a 65 20 71 75 65 72 69 65 73 20 61 67 61  mize queries aga
2b90: 69 6e 73 74 20 74 68 65 0d 0a 20 20 20 20 20 20  inst the..      
2ba0: 20 20 2f 2f 2f 20 76 69 72 74 75 61 6c 20 74 61    /// virtual ta
2bb0: 62 6c 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ble...        //
2bc0: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  / </para>..     
2bd0: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20     /// <para>.. 
2be0: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 72         /// The r
2bf0: 6f 77 69 64 20 63 6f 6c 75 6d 6e 20 69 73 20 6e  owid column is n
2c00: 6f 74 20 61 63 63 65 73 73 69 62 6c 65 20 6f 6e  ot accessible on
2c10: 20 61 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20   a..        /// 
2c20: 57 49 54 48 4f 55 54 20 52 4f 57 49 44 20 76 69  WITHOUT ROWID vi
2c30: 72 74 75 61 6c 20 74 61 62 6c 65 20 28 6f 66 20  rtual table (of 
2c40: 63 6f 75 72 73 65 29 2e 0d 0a 20 20 20 20 20 20  course)...      
2c50: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
2c60: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
2c70: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54  >..        /// T
2c80: 68 65 20 78 55 70 64 61 74 65 20 6d 65 74 68 6f  he xUpdate metho
2c90: 64 20 77 61 73 20 6f 72 69 67 69 6e 61 6c 6c 79  d was originally
2ca0: 20 64 65 73 69 67 6e 65 64 20 61 72 6f 75 6e 64   designed around
2cb0: 20 68 61 76 69 6e 67 20 61 0d 0a 20 20 20 20 20   having a..     
2cc0: 20 20 20 2f 2f 2f 20 52 4f 57 49 44 20 61 73 20     /// ROWID as 
2cd0: 61 20 73 69 6e 67 6c 65 20 76 61 6c 75 65 2e 20  a single value. 
2ce0: 20 54 68 65 20 78 55 70 64 61 74 65 20 6d 65 74   The xUpdate met
2cf0: 68 6f 64 20 68 61 73 20 62 65 65 6e 20 65 78 70  hod has been exp
2d00: 61 6e 64 65 64 20 74 6f 0d 0a 20 20 20 20 20 20  anded to..      
2d10: 20 20 2f 2f 2f 20 61 63 63 6f 6d 6d 6f 64 61 74    /// accommodat
2d20: 65 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 50  e an arbitrary P
2d30: 52 49 4d 41 52 59 20 4b 45 59 20 69 6e 20 70 6c  RIMARY KEY in pl
2d40: 61 63 65 20 6f 66 20 74 68 65 20 52 4f 57 49 44  ace of the ROWID
2d50: 2c 20 62 75 74 20 74 68 65 0d 0a 20 20 20 20 20  , but the..     
2d60: 20 20 20 2f 2f 2f 20 50 52 49 4d 41 52 59 20 4b     /// PRIMARY K
2d70: 45 59 20 6d 75 73 74 20 73 74 69 6c 6c 20 62 65  EY must still be
2d80: 20 6f 6e 6c 79 20 6f 6e 65 20 63 6f 6c 75 6d 6e   only one column
2d90: 2e 20 20 46 6f 72 20 74 68 69 73 20 72 65 61 73  .  For this reas
2da0: 6f 6e 2c 20 53 51 4c 69 74 65 0d 0a 20 20 20 20  on, SQLite..    
2db0: 20 20 20 20 2f 2f 2f 20 77 69 6c 6c 20 72 65 6a      /// will rej
2dc0: 65 63 74 20 61 6e 79 20 57 49 54 48 4f 55 54 20  ect any WITHOUT 
2dd0: 52 4f 57 49 44 20 76 69 72 74 75 61 6c 20 74 61  ROWID virtual ta
2de0: 62 6c 65 20 74 68 61 74 20 68 61 73 20 6d 6f 72  ble that has mor
2df0: 65 20 74 68 61 6e 20 6f 6e 65 0d 0a 20 20 20 20  e than one..    
2e00: 20 20 20 20 2f 2f 2f 20 50 52 49 4d 41 52 59 20      /// PRIMARY 
2e10: 4b 45 59 20 63 6f 6c 75 6d 6e 20 61 6e 64 20 61  KEY column and a
2e20: 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 55 70 64 61 74   non-NULL xUpdat
2e30: 65 20 6d 65 74 68 6f 64 2e 0d 0a 20 20 20 20 20  e method...     
2e40: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a     /// </para>..
2e50: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 73 75          /// </su
2e60: 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20  mmary>..        
2e70: 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d  /// <param name=
2e80: 22 70 44 62 22 3e 0d 0a 20 20 20 20 20 20 20 20  "pDb">..        
2e90: 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76 65 20 64  /// The native d
2ea0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2eb0: 6f 6e 20 68 61 6e 64 6c 65 2e 0d 0a 20 20 20 20  on handle...    
2ec0: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e      /// </param>
2ed0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
2ee0: 61 72 61 6d 20 6e 61 6d 65 3d 22 70 41 75 78 22  aram name="pAux"
2ef0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54  >..        /// T
2f00: 68 65 20 6f 72 69 67 69 6e 61 6c 20 6e 61 74 69  he original nati
2f10: 76 65 20 70 6f 69 6e 74 65 72 20 76 61 6c 75 65  ve pointer value
2f20: 20 74 68 61 74 20 77 61 73 20 70 72 6f 76 69 64   that was provid
2f30: 65 64 20 74 6f 20 74 68 65 0d 0a 20 20 20 20 20  ed to the..     
2f40: 20 20 20 2f 2f 2f 20 73 71 6c 69 74 65 33 5f 63     /// sqlite3_c
2f50: 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 2c 20  reate_module(), 
2f60: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
2f70: 6f 64 75 6c 65 5f 76 32 28 29 20 6f 72 0d 0a 20  odule_v2() or.. 
2f80: 20 20 20 20 20 20 20 2f 2f 2f 20 73 71 6c 69 74         /// sqlit
2f90: 65 33 5f 63 72 65 61 74 65 5f 64 69 73 70 6f 73  e3_create_dispos
2fa0: 61 62 6c 65 5f 6d 6f 64 75 6c 65 28 29 20 66 75  able_module() fu
2fb0: 6e 63 74 69 6f 6e 73 2e 0d 0a 20 20 20 20 20 20  nctions...      
2fc0: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a    /// </param>..
2fd0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
2fe0: 61 6d 20 6e 61 6d 65 3d 22 61 72 67 63 22 3e 0d  am name="argc">.
2ff0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65  .        /// The
3000: 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
3010: 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 43 52  ents from the CR
3020: 45 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42  EATE VIRTUAL TAB
3030: 4c 45 20 73 74 61 74 65 6d 65 6e 74 2e 0d 0a 20  LE statement... 
3040: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
3050: 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  am>..        ///
3060: 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 61 72   <param name="ar
3070: 67 76 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  gv">..        //
3080: 2f 20 54 68 65 20 61 72 72 61 79 20 6f 66 20 73  / The array of s
3090: 74 72 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20  tring arguments 
30a0: 66 72 6f 6d 20 74 68 65 20 43 52 45 41 54 45 20  from the CREATE 
30b0: 56 49 52 54 55 41 4c 20 54 41 42 4c 45 0d 0a 20  VIRTUAL TABLE.. 
30c0: 20 20 20 20 20 20 20 2f 2f 2f 20 73 74 61 74 65         /// state
30d0: 6d 65 6e 74 2e 0d 0a 20 20 20 20 20 20 20 20 2f  ment...        /
30e0: 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20  // </param>..   
30f0: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20       /// <param 
3100: 6e 61 6d 65 3d 22 70 56 74 61 62 22 3e 0d 0a 20  name="pVtab">.. 
3110: 20 20 20 20 20 20 20 2f 2f 2f 20 55 70 6f 6e 20         /// Upon 
3120: 73 75 63 63 65 73 73 2c 20 74 68 69 73 20 70 61  success, this pa
3130: 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20  rameter must be 
3140: 6d 6f 64 69 66 69 65 64 20 74 6f 20 70 6f 69 6e  modified to poin
3150: 74 20 74 6f 20 74 68 65 20 6e 65 77 6c 79 0d 0a  t to the newly..
3160: 20 20 20 20 20 20 20 20 2f 2f 2f 20 63 72 65 61          /// crea
3170: 74 65 64 20 6e 61 74 69 76 65 20 73 71 6c 69 74  ted native sqlit
3180: 65 33 5f 76 74 61 62 20 64 65 72 69 76 65 64 20  e3_vtab derived 
3190: 73 74 72 75 63 74 75 72 65 2e 0d 0a 20 20 20 20  structure...    
31a0: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e      /// </param>
31b0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
31c0: 61 72 61 6d 20 6e 61 6d 65 3d 22 70 45 72 72 6f  aram name="pErro
31d0: 72 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  r">..        ///
31e0: 20 55 70 6f 6e 20 66 61 69 6c 75 72 65 2c 20 74   Upon failure, t
31f0: 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 6d 75  his parameter mu
3200: 73 74 20 62 65 20 6d 6f 64 69 66 69 65 64 20 74  st be modified t
3210: 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 65  o point to the e
3220: 72 72 6f 72 0d 0a 20 20 20 20 20 20 20 20 2f 2f  rror..        //
3230: 2f 20 6d 65 73 73 61 67 65 2c 20 77 69 74 68 20  / message, with 
3240: 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6d  the underlying m
3250: 65 6d 6f 72 79 20 68 61 76 69 6e 67 20 62 65 65  emory having bee
3260: 6e 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  n obtained from 
3270: 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  the..        ///
3280: 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
3290: 29 20 66 75 6e 63 74 69 6f 6e 2e 0d 0a 20 20 20  ) function...   
32a0: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d       /// </param
32b0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
32c0: 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20  returns>..      
32d0: 20 20 2f 2f 2f 20 41 20 73 74 61 6e 64 61 72 64    /// A standard
32e0: 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 20 63   SQLite return c
32f0: 6f 64 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ode...        //
3300: 2f 20 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a 20 20  / </returns>..  
3310: 20 20 20 20 20 20 53 51 4c 69 74 65 45 72 72 6f        SQLiteErro
3320: 72 43 6f 64 65 20 78 43 72 65 61 74 65 28 0d 0a  rCode xCreate(..
3330: 20 20 20 20 20 20 20 20 20 20 20 20 49 6e 74 50              IntP
3340: 74 72 20 70 44 62 2c 0d 0a 20 20 20 20 20 20 20  tr pDb,..       
3350: 20 20 20 20 20 49 6e 74 50 74 72 20 70 41 75 78       IntPtr pAux
3360: 2c 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 69  ,..            i
3370: 6e 74 20 61 72 67 63 2c 0d 0a 20 20 20 20 20 20  nt argc,..      
3380: 20 20 20 20 20 20 49 6e 74 50 74 72 20 61 72 67        IntPtr arg
3390: 76 2c 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20  v,..            
33a0: 72 65 66 20 49 6e 74 50 74 72 20 70 56 74 61 62  ref IntPtr pVtab
33b0: 2c 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 72  ,..            r
33c0: 65 66 20 49 6e 74 50 74 72 20 70 45 72 72 6f 72  ef IntPtr pError
33d0: 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 29 3b  ..            );
33e0: 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 2f  ....        ////
33f0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
3400: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
3410: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
3420: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
3430: 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f  ///....        /
3440: 2f 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20 20  // <summary>..  
3450: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
3460: 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20 20  <code>..        
3470: 2f 2f 2f 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65  /// int (*xConne
3480: 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ct)(sqlite3*, vo
3490: 69 64 20 2a 70 41 75 78 2c 0d 0a 20 20 20 20 20  id *pAux,..     
34a0: 20 20 20 2f 2f 2f 20 20 20 20 20 20 20 20 20 20     ///          
34b0: 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 68      int argc, ch
34c0: 61 72 20 2a 2a 61 72 67 76 2c 0d 0a 20 20 20 20  ar **argv,..    
34d0: 20 20 20 20 2f 2f 2f 20 20 20 20 20 20 20 20 20      ///         
34e0: 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61       sqlite3_vta
34f0: 62 20 2a 2a 70 70 56 54 61 62 2c 0d 0a 20 20 20  b **ppVTab,..   
3500: 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 20 20 20       ///        
3510: 20 20 20 20 20 20 63 68 61 72 20 2a 2a 70 7a 45        char **pzE
3520: 72 72 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f  rr);..        //
3530: 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e  / </code></para>
3540: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
3550: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
3560: 2f 20 54 68 65 20 78 43 6f 6e 6e 65 63 74 20 6d  / The xConnect m
3570: 65 74 68 6f 64 20 69 73 20 76 65 72 79 20 73 69  ethod is very si
3580: 6d 69 6c 61 72 20 74 6f 20 78 43 72 65 61 74 65  milar to xCreate
3590: 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  . ..        /// 
35a0: 49 74 20 68 61 73 20 74 68 65 20 73 61 6d 65 20  It has the same 
35b0: 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 63  parameters and c
35c0: 6f 6e 73 74 72 75 63 74 73 20 61 20 6e 65 77 20  onstructs a new 
35d0: 73 71 6c 69 74 65 33 5f 76 74 61 62 20 73 74 72  sqlite3_vtab str
35e0: 75 63 74 75 72 65 20 0d 0a 20 20 20 20 20 20 20  ucture ..       
35f0: 20 2f 2f 2f 20 6a 75 73 74 20 6c 69 6b 65 20 78   /// just like x
3600: 43 72 65 61 74 65 2e 20 0d 0a 20 20 20 20 20 20  Create. ..      
3610: 20 20 2f 2f 2f 20 41 6e 64 20 69 74 20 6d 75 73    /// And it mus
3620: 74 20 61 6c 73 6f 20 63 61 6c 6c 20 73 71 6c 69  t also call sqli
3630: 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62  te3_declare_vtab
3640: 28 29 20 6c 69 6b 65 20 78 43 72 65 61 74 65 2e  () like xCreate.
3650: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
3660: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
3670: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20  // <para>..     
3680: 20 20 20 2f 2f 2f 20 54 68 65 20 64 69 66 66 65     /// The diffe
3690: 72 65 6e 63 65 20 69 73 20 74 68 61 74 20 78 43  rence is that xC
36a0: 6f 6e 6e 65 63 74 20 69 73 20 63 61 6c 6c 65 64  onnect is called
36b0: 20 74 6f 20 65 73 74 61 62 6c 69 73 68 20 61 20   to establish a 
36c0: 6e 65 77 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  new ..        //
36d0: 2f 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  / connection to 
36e0: 61 6e 20 65 78 69 73 74 69 6e 67 20 76 69 72 74  an existing virt
36f0: 75 61 6c 20 74 61 62 6c 65 20 77 68 65 72 65 61  ual table wherea
3700: 73 20 78 43 72 65 61 74 65 20 69 73 20 63 61 6c  s xCreate is cal
3710: 6c 65 64 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  led ..        //
3720: 2f 20 74 6f 20 63 72 65 61 74 65 20 61 20 6e 65  / to create a ne
3730: 77 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  w virtual table 
3740: 66 72 6f 6d 20 73 63 72 61 74 63 68 2e 0d 0a 20  from scratch... 
3750: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
3760: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
3770: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
3780: 2f 2f 2f 20 54 68 65 20 78 43 72 65 61 74 65 20  /// The xCreate 
3790: 61 6e 64 20 78 43 6f 6e 6e 65 63 74 20 6d 65 74  and xConnect met
37a0: 68 6f 64 73 20 61 72 65 20 6f 6e 6c 79 20 64 69  hods are only di
37b0: 66 66 65 72 65 6e 74 20 77 68 65 6e 20 74 68 65  fferent when the
37c0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 76 69  ..        /// vi
37d0: 72 74 75 61 6c 20 74 61 62 6c 65 20 68 61 73 20  rtual table has 
37e0: 73 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 62 61 63  some kind of bac
37f0: 6b 69 6e 67 20 73 74 6f 72 65 20 74 68 61 74 20  king store that 
3800: 6d 75 73 74 20 62 65 20 69 6e 69 74 69 61 6c 69  must be initiali
3810: 7a 65 64 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  zed ..        //
3820: 2f 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  / the first time
3830: 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
3840: 6c 65 20 69 73 20 63 72 65 61 74 65 64 2e 20 54  le is created. T
3850: 68 65 20 78 43 72 65 61 74 65 20 6d 65 74 68 6f  he xCreate metho
3860: 64 20 63 72 65 61 74 65 73 20 0d 0a 20 20 20 20  d creates ..    
3870: 20 20 20 20 2f 2f 2f 20 61 6e 64 20 69 6e 69 74      /// and init
3880: 69 61 6c 69 7a 65 73 20 74 68 65 20 62 61 63 6b  ializes the back
3890: 69 6e 67 20 73 74 6f 72 65 2e 20 54 68 65 20 78  ing store. The x
38a0: 43 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64 20 6a  Connect method j
38b0: 75 73 74 20 63 6f 6e 6e 65 63 74 73 20 0d 0a 20  ust connects .. 
38c0: 20 20 20 20 20 20 20 2f 2f 2f 20 74 6f 20 61 6e         /// to an
38d0: 20 65 78 69 73 74 69 6e 67 20 62 61 63 6b 69 6e   existing backin
38e0: 67 20 73 74 6f 72 65 2e 20 20 57 68 65 6e 20 78  g store.  When x
38f0: 43 72 65 61 74 65 20 61 6e 64 20 78 43 6f 6e 6e  Create and xConn
3900: 65 63 74 20 61 72 65 20 74 68 65 20 73 61 6d 65  ect are the same
3910: 2c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74  ,..        /// t
3920: 68 65 20 74 61 62 6c 65 20 69 73 20 61 6e 20 65  he table is an e
3930: 70 6f 6e 79 6d 6f 75 73 20 76 69 72 74 75 61 6c  ponymous virtual
3940: 20 74 61 62 6c 65 2e 0d 0a 20 20 20 20 20 20 20   table...       
3950: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
3960: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
3970: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 73  ..        /// As
3980: 20 61 6e 20 65 78 61 6d 70 6c 65 2c 20 63 6f 6e   an example, con
3990: 73 69 64 65 72 20 61 20 76 69 72 74 75 61 6c 20  sider a virtual 
39a0: 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
39b0: 74 69 6f 6e 20 74 68 61 74 20 0d 0a 20 20 20 20  tion that ..    
39c0: 20 20 20 20 2f 2f 2f 20 70 72 6f 76 69 64 65 73      /// provides
39d0: 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73   read-only acces
39e0: 73 20 74 6f 20 65 78 69 73 74 69 6e 67 20 63 6f  s to existing co
39f0: 6d 6d 61 2d 73 65 70 61 72 61 74 65 64 2d 76 61  mma-separated-va
3a00: 6c 75 65 20 28 43 53 56 29 0d 0a 20 20 20 20 20  lue (CSV)..     
3a10: 20 20 20 2f 2f 2f 20 66 69 6c 65 73 20 6f 6e 20     /// files on 
3a20: 64 69 73 6b 2e 20 54 68 65 72 65 20 69 73 20 6e  disk. There is n
3a30: 6f 20 62 61 63 6b 69 6e 67 20 73 74 6f 72 65 20  o backing store 
3a40: 74 68 61 74 20 6e 65 65 64 73 20 74 6f 20 62 65  that needs to be
3a50: 20 63 72 65 61 74 65 64 20 0d 0a 20 20 20 20 20   created ..     
3a60: 20 20 20 2f 2f 2f 20 6f 72 20 69 6e 69 74 69 61     /// or initia
3a70: 6c 69 7a 65 64 20 66 6f 72 20 73 75 63 68 20 61  lized for such a
3a80: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 28   virtual table (
3a90: 73 69 6e 63 65 20 74 68 65 20 43 53 56 20 66 69  since the CSV fi
3aa0: 6c 65 73 20 61 6c 72 65 61 64 79 20 0d 0a 20 20  les already ..  
3ab0: 20 20 20 20 20 20 2f 2f 2f 20 65 78 69 73 74 20        /// exist 
3ac0: 6f 6e 20 64 69 73 6b 29 20 73 6f 20 74 68 65 20  on disk) so the 
3ad0: 78 43 72 65 61 74 65 20 61 6e 64 20 78 43 6f 6e  xCreate and xCon
3ae0: 6e 65 63 74 20 6d 65 74 68 6f 64 73 20 77 69 6c  nect methods wil
3af0: 6c 20 62 65 20 69 64 65 6e 74 69 63 61 6c 20 0d  l be identical .
3b00: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 66 6f 72  .        /// for
3b10: 20 74 68 61 74 20 6d 6f 64 75 6c 65 2e 0d 0a 20   that module... 
3b20: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
3b30: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
3b40: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
3b50: 2f 2f 2f 20 41 6e 6f 74 68 65 72 20 65 78 61 6d  /// Another exam
3b60: 70 6c 65 20 69 73 20 61 20 76 69 72 74 75 61 6c  ple is a virtual
3b70: 20 74 61 62 6c 65 20 74 68 61 74 20 69 6d 70 6c   table that impl
3b80: 65 6d 65 6e 74 73 20 61 20 66 75 6c 6c 2d 74 65  ements a full-te
3b90: 78 74 20 69 6e 64 65 78 2e 20 0d 0a 20 20 20 20  xt index. ..    
3ba0: 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 43 72 65      /// The xCre
3bb0: 61 74 65 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  ate method must 
3bc0: 63 72 65 61 74 65 20 61 6e 64 20 69 6e 69 74 69  create and initi
3bd0: 61 6c 69 7a 65 20 64 61 74 61 20 73 74 72 75 63  alize data struc
3be0: 74 75 72 65 73 20 74 6f 20 68 6f 6c 64 20 0d 0a  tures to hold ..
3bf0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 20          /// the 
3c00: 64 69 63 74 69 6f 6e 61 72 79 20 61 6e 64 20 70  dictionary and p
3c10: 6f 73 74 69 6e 67 20 6c 69 73 74 73 20 66 6f 72  osting lists for
3c20: 20 74 68 61 74 20 69 6e 64 65 78 2e 20 54 68 65   that index. The
3c30: 20 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64   xConnect method
3c40: 2c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6f  ,..        /// o
3c50: 6e 20 74 68 65 20 6f 74 68 65 72 20 68 61 6e 64  n the other hand
3c60: 2c 20 6f 6e 6c 79 20 68 61 73 20 74 6f 20 6c 6f  , only has to lo
3c70: 63 61 74 65 20 61 6e 64 20 75 73 65 20 61 6e 20  cate and use an 
3c80: 65 78 69 73 74 69 6e 67 20 64 69 63 74 69 6f 6e  existing diction
3c90: 61 72 79 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ary ..        //
3ca0: 2f 20 61 6e 64 20 70 6f 73 74 69 6e 67 20 6c 69  / and posting li
3cb0: 73 74 73 20 74 68 61 74 20 77 65 72 65 20 63 72  sts that were cr
3cc0: 65 61 74 65 64 20 62 79 20 61 20 70 72 69 6f 72  eated by a prior
3cd0: 20 78 43 72 65 61 74 65 20 63 61 6c 6c 2e 0d 0a   xCreate call...
3ce0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
3cf0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
3d00: 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20   <para>..       
3d10: 20 2f 2f 2f 20 54 68 65 20 78 43 6f 6e 6e 65 63   /// The xConnec
3d20: 74 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 72 65  t method must re
3d30: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69  turn SQLITE_OK i
3d40: 66 20 69 74 20 69 73 20 73 75 63 63 65 73 73 66  f it is successf
3d50: 75 6c 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ul ..        ///
3d60: 20 69 6e 20 63 72 65 61 74 69 6e 67 20 74 68 65   in creating the
3d70: 20 6e 65 77 20 76 69 72 74 75 61 6c 20 74 61 62   new virtual tab
3d80: 6c 65 2c 20 6f 72 20 53 51 4c 49 54 45 5f 45 52  le, or SQLITE_ER
3d90: 52 4f 52 20 69 66 20 69 74 20 69 73 20 6e 6f 74  ROR if it is not
3da0: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73   ..        /// s
3db0: 75 63 63 65 73 73 66 75 6c 2e 20 49 66 20 6e 6f  uccessful. If no
3dc0: 74 20 73 75 63 63 65 73 73 66 75 6c 2c 20 74 68  t successful, th
3dd0: 65 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 73  e sqlite3_vtab s
3de0: 74 72 75 63 74 75 72 65 20 6d 75 73 74 20 6e 6f  tructure must no
3df0: 74 20 62 65 20 0d 0a 20 20 20 20 20 20 20 20 2f  t be ..        /
3e00: 2f 2f 20 61 6c 6c 6f 63 61 74 65 64 2e 20 41 6e  // allocated. An
3e10: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 6d   error message m
3e20: 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65  ay optionally be
3e30: 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 7a   returned in *pz
3e40: 45 72 72 20 69 66 20 0d 0a 20 20 20 20 20 20 20  Err if ..       
3e50: 20 2f 2f 2f 20 75 6e 73 75 63 63 65 73 73 66 75   /// unsuccessfu
3e60: 6c 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  l. ..        ///
3e70: 20 53 70 61 63 65 20 74 6f 20 68 6f 6c 64 20 74   Space to hold t
3e80: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
3e90: 20 73 74 72 69 6e 67 20 6d 75 73 74 20 62 65 20   string must be 
3ea0: 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 0d  allocated using.
3eb0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 61 6e 20  .        /// an 
3ec0: 53 51 4c 69 74 65 20 6d 65 6d 6f 72 79 20 61 6c  SQLite memory al
3ed0: 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  location functio
3ee0: 6e 20 6c 69 6b 65 20 0d 0a 20 20 20 20 20 20 20  n like ..       
3ef0: 20 2f 2f 2f 20 73 71 6c 69 74 65 33 5f 6d 61 6c   /// sqlite3_mal
3f00: 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
3f10: 5f 6d 70 72 69 6e 74 66 28 29 20 61 73 20 74 68  _mprintf() as th
3f20: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69  e SQLite core wi
3f30: 6c 6c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ll..        /// 
3f40: 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20  attempt to free 
3f50: 74 68 65 20 73 70 61 63 65 20 75 73 69 6e 67 20  the space using 
3f60: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61  sqlite3_free() a
3f70: 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 68  fter the error h
3f80: 61 73 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  as..        /// 
3f90: 62 65 65 6e 20 72 65 70 6f 72 74 65 64 20 75 70  been reported up
3fa0: 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
3fb0: 69 6f 6e 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ion...        //
3fc0: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  / </para>..     
3fd0: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20     /// <para>.. 
3fe0: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 78         /// The x
3ff0: 43 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64 20 69  Connect method i
4000: 73 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 65  s required for e
4010: 76 65 72 79 20 76 69 72 74 75 61 6c 20 74 61 62  very virtual tab
4020: 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
4030: 6e 2c 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  n, ..        ///
4040: 20 74 68 6f 75 67 68 20 74 68 65 20 78 43 72 65   though the xCre
4050: 61 74 65 20 61 6e 64 20 78 43 6f 6e 6e 65 63 74  ate and xConnect
4060: 20 70 6f 69 6e 74 65 72 73 20 6f 66 20 74 68 65   pointers of the
4070: 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
4080: 6f 62 6a 65 63 74 0d 0a 20 20 20 20 20 20 20 20  object..        
4090: 2f 2f 2f 20 6d 61 79 20 70 6f 69 6e 74 20 74 6f  /// may point to
40a0: 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
40b0: 6f 6e 20 69 66 20 74 68 65 20 76 69 72 74 75 61  on if the virtua
40c0: 6c 20 74 61 62 6c 65 20 64 6f 65 73 20 6e 6f 74  l table does not
40d0: 20 6e 65 65 64 20 74 6f 0d 0a 20 20 20 20 20 20   need to..      
40e0: 20 20 2f 2f 2f 20 69 6e 69 74 69 61 6c 69 7a 65    /// initialize
40f0: 20 62 61 63 6b 69 6e 67 20 73 74 6f 72 65 2e 0d   backing store..
4100: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
4110: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
4120: 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a 20 20  / </summary>..  
4130: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d        /// <param
4140: 20 6e 61 6d 65 3d 22 70 44 62 22 3e 0d 0a 20 20   name="pDb">..  
4150: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e 61        /// The na
4160: 74 69 76 65 20 64 61 74 61 62 61 73 65 20 63 6f  tive database co
4170: 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 2e  nnection handle.
4180: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
4190: 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20  param>..        
41a0: 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d  /// <param name=
41b0: 22 70 41 75 78 22 3e 0d 0a 20 20 20 20 20 20 20  "pAux">..       
41c0: 20 2f 2f 2f 20 54 68 65 20 6f 72 69 67 69 6e 61   /// The origina
41d0: 6c 20 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72  l native pointer
41e0: 20 76 61 6c 75 65 20 74 68 61 74 20 77 61 73 20   value that was 
41f0: 70 72 6f 76 69 64 65 64 20 74 6f 20 74 68 65 0d  provided to the.
4200: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 71 6c  .        /// sql
4210: 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
4220: 6c 65 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 72  le(), sqlite3_cr
4230: 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29  eate_module_v2()
4240: 20 6f 72 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f   or..        ///
4250: 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
4260: 64 69 73 70 6f 73 61 62 6c 65 5f 6d 6f 64 75 6c  disposable_modul
4270: 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 2e 0d 0a  e() functions...
4280: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
4290: 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ram>..        //
42a0: 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 61  / <param name="a
42b0: 72 67 63 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f  rgc">..        /
42c0: 2f 2f 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  // The number of
42d0: 20 61 72 67 75 6d 65 6e 74 73 20 66 72 6f 6d 20   arguments from 
42e0: 74 68 65 20 43 52 45 41 54 45 20 56 49 52 54 55  the CREATE VIRTU
42f0: 41 4c 20 54 41 42 4c 45 20 73 74 61 74 65 6d 65  AL TABLE stateme
4300: 6e 74 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  nt...        ///
4310: 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20   </param>..     
4320: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61     /// <param na
4330: 6d 65 3d 22 61 72 67 76 22 3e 0d 0a 20 20 20 20  me="argv">..    
4340: 20 20 20 20 2f 2f 2f 20 54 68 65 20 61 72 72 61      /// The arra
4350: 79 20 6f 66 20 73 74 72 69 6e 67 20 61 72 67 75  y of string argu
4360: 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 43  ments from the C
4370: 52 45 41 54 45 20 56 49 52 54 55 41 4c 20 54 41  REATE VIRTUAL TA
4380: 42 4c 45 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  BLE..        ///
4390: 20 73 74 61 74 65 6d 65 6e 74 2e 0d 0a 20 20 20   statement...   
43a0: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d       /// </param
43b0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
43c0: 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 56 74 61  param name="pVta
43d0: 62 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  b">..        ///
43e0: 20 55 70 6f 6e 20 73 75 63 63 65 73 73 2c 20 74   Upon success, t
43f0: 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 6d 75  his parameter mu
4400: 73 74 20 62 65 20 6d 6f 64 69 66 69 65 64 20 74  st be modified t
4410: 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 6e  o point to the n
4420: 65 77 6c 79 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ewly..        //
4430: 2f 20 63 72 65 61 74 65 64 20 6e 61 74 69 76 65  / created native
4440: 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 64 65   sqlite3_vtab de
4450: 72 69 76 65 64 20 73 74 72 75 63 74 75 72 65 2e  rived structure.
4460: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
4470: 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20  param>..        
4480: 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d  /// <param name=
4490: 22 70 45 72 72 6f 72 22 3e 0d 0a 20 20 20 20 20  "pError">..     
44a0: 20 20 20 2f 2f 2f 20 55 70 6f 6e 20 66 61 69 6c     /// Upon fail
44b0: 75 72 65 2c 20 74 68 69 73 20 70 61 72 61 6d 65  ure, this parame
44c0: 74 65 72 20 6d 75 73 74 20 62 65 20 6d 6f 64 69  ter must be modi
44d0: 66 69 65 64 20 74 6f 20 70 6f 69 6e 74 20 74 6f  fied to point to
44e0: 20 74 68 65 20 65 72 72 6f 72 0d 0a 20 20 20 20   the error..    
44f0: 20 20 20 20 2f 2f 2f 20 6d 65 73 73 61 67 65 2c      /// message,
4500: 20 77 69 74 68 20 74 68 65 20 75 6e 64 65 72 6c   with the underl
4510: 79 69 6e 67 20 6d 65 6d 6f 72 79 20 68 61 76 69  ying memory havi
4520: 6e 67 20 62 65 65 6e 20 6f 62 74 61 69 6e 65 64  ng been obtained
4530: 20 66 72 6f 6d 20 74 68 65 0d 0a 20 20 20 20 20   from the..     
4540: 20 20 20 2f 2f 2f 20 73 71 6c 69 74 65 33 5f 6d     /// sqlite3_m
4550: 61 6c 6c 6f 63 28 29 20 66 75 6e 63 74 69 6f 6e  alloc() function
4560: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
4570: 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20  /param>..       
4580: 20 2f 2f 2f 20 3c 72 65 74 75 72 6e 73 3e 0d 0a   /// <returns>..
4590: 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 20 73 74          /// A st
45a0: 61 6e 64 61 72 64 20 53 51 4c 69 74 65 20 72 65  andard SQLite re
45b0: 74 75 72 6e 20 63 6f 64 65 2e 0d 0a 20 20 20 20  turn code...    
45c0: 20 20 20 20 2f 2f 2f 20 3c 2f 72 65 74 75 72 6e      /// </return
45d0: 73 3e 0d 0a 20 20 20 20 20 20 20 20 53 51 4c 69  s>..        SQLi
45e0: 74 65 45 72 72 6f 72 43 6f 64 65 20 78 43 6f 6e  teErrorCode xCon
45f0: 6e 65 63 74 28 0d 0a 20 20 20 20 20 20 20 20 20  nect(..         
4600: 20 20 20 49 6e 74 50 74 72 20 70 44 62 2c 0d 0a     IntPtr pDb,..
4610: 20 20 20 20 20 20 20 20 20 20 20 20 49 6e 74 50              IntP
4620: 74 72 20 70 41 75 78 2c 0d 0a 20 20 20 20 20 20  tr pAux,..      
4630: 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 0d        int argc,.
4640: 0a 20 20 20 20 20 20 20 20 20 20 20 20 49 6e 74  .            Int
4650: 50 74 72 20 61 72 67 76 2c 0d 0a 20 20 20 20 20  Ptr argv,..     
4660: 20 20 20 20 20 20 20 72 65 66 20 49 6e 74 50 74         ref IntPt
4670: 72 20 70 56 74 61 62 2c 0d 0a 20 20 20 20 20 20  r pVtab,..      
4680: 20 20 20 20 20 20 72 65 66 20 49 6e 74 50 74 72        ref IntPtr
4690: 20 70 45 72 72 6f 72 0d 0a 20 20 20 20 20 20 20   pError..       
46a0: 20 20 20 20 20 29 3b 0d 0a 0d 0a 20 20 20 20 20       );....     
46b0: 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f     /////////////
46c0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
46d0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
46e0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
46f0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20  //////////....  
4700: 20 20 20 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61        /// <summa
4710: 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ry>..        ///
4720: 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20   <para>..       
4730: 20 2f 2f 2f 20 53 51 4c 69 74 65 20 75 73 65 73   /// SQLite uses
4740: 20 74 68 65 20 78 42 65 73 74 49 6e 64 65 78 20   the xBestIndex 
4750: 6d 65 74 68 6f 64 20 6f 66 20 61 20 76 69 72 74  method of a virt
4760: 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
4770: 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 0d 0a 20   to determine.. 
4780: 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 20 62         /// the b
4790: 65 73 74 20 77 61 79 20 74 6f 20 61 63 63 65 73  est way to acces
47a0: 73 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  s the virtual ta
47b0: 62 6c 65 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f  ble. ..        /
47c0: 2f 2f 20 54 68 65 20 78 42 65 73 74 49 6e 64 65  // The xBestInde
47d0: 78 20 6d 65 74 68 6f 64 20 68 61 73 20 61 20 70  x method has a p
47e0: 72 6f 74 6f 74 79 70 65 20 6c 69 6b 65 20 74 68  rototype like th
47f0: 69 73 3a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  is:..        ///
4800: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
4810: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64    /// <para><cod
4820: 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e>..        /// 
4830: 69 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 65 78  int (*xBestIndex
4840: 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
4850: 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 69  pVTab, sqlite3_i
4860: 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0d 0a 20 20  ndex_info*);..  
4870: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65        /// </code
4880: 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  ></para>..      
4890: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
48a0: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 53 51        /// The SQ
48b0: 4c 69 74 65 20 63 6f 72 65 20 63 6f 6d 6d 75 6e  Lite core commun
48c0: 69 63 61 74 65 73 20 77 69 74 68 20 74 68 65 20  icates with the 
48d0: 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f  xBestIndex metho
48e0: 64 20 62 79 20 66 69 6c 6c 69 6e 67 20 0d 0a 20  d by filling .. 
48f0: 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e 20 63 65         /// in ce
4900: 72 74 61 69 6e 20 66 69 65 6c 64 73 20 6f 66 20  rtain fields of 
4910: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  the sqlite3_inde
4920: 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65  x_info structure
4930: 20 61 6e 64 20 70 61 73 73 69 6e 67 20 61 20 0d   and passing a .
4940: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 70 6f 69  .        /// poi
4950: 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72  nter to that str
4960: 75 63 74 75 72 65 20 69 6e 74 6f 20 78 42 65 73  ucture into xBes
4970: 74 49 6e 64 65 78 20 61 73 20 74 68 65 20 73 65  tIndex as the se
4980: 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
4990: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
49a0: 65 20 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74  e xBestIndex met
49b0: 68 6f 64 20 66 69 6c 6c 73 20 6f 75 74 20 6f 74  hod fills out ot
49c0: 68 65 72 20 66 69 65 6c 64 73 20 6f 66 20 74 68  her fields of th
49d0: 69 73 20 73 74 72 75 63 74 75 72 65 20 77 68 69  is structure whi
49e0: 63 68 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ch..        /// 
49f0: 66 6f 72 6d 73 20 74 68 65 20 72 65 70 6c 79 2e  forms the reply.
4a00: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64   The sqlite3_ind
4a10: 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72  ex_info structur
4a20: 65 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 74 68 69  e looks like thi
4a30: 73 3a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  s:..        /// 
4a40: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
4a50: 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65   /// <para><code
4a60: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73  >..        /// s
4a70: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e  truct sqlite3_in
4a80: 64 65 78 5f 69 6e 66 6f 20 7b 0d 0a 20 20 20 20  dex_info {..    
4a90: 20 20 20 20 2f 2f 2f 20 20 20 2f 2a 20 49 6e 70      ///   /* Inp
4aa0: 75 74 73 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20  uts */..        
4ab0: 2f 2f 2f 20 20 20 63 6f 6e 73 74 20 69 6e 74 20  ///   const int 
4ac0: 6e 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20  nConstraint;    
4ad0: 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65 6e   /* Number of en
4ae0: 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74 72  tries in aConstr
4af0: 61 69 6e 74 20 2a 2f 0d 0a 20 20 20 20 20 20 20  aint */..       
4b00: 20 2f 2f 2f 20 20 20 63 6f 6e 73 74 20 73 74 72   ///   const str
4b10: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
4b20: 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0d 0a  x_constraint {..
4b30: 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20          ///     
4b40: 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20   int iColumn;   
4b50: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f             /* Co
4b60: 6c 75 6d 6e 20 63 6f 6e 73 74 72 61 69 6e 65 64  lumn constrained
4b70: 2e 20 20 2d 31 20 66 6f 72 20 52 4f 57 49 44 20  .  -1 for ROWID 
4b80: 2a 2f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  */..        /// 
4b90: 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68       unsigned ch
4ba0: 61 72 20 6f 70 3b 20 20 20 20 20 20 20 20 20 2f  ar op;         /
4bb0: 2a 20 43 6f 6e 73 74 72 61 69 6e 74 20 6f 70 65  * Constraint ope
4bc0: 72 61 74 6f 72 20 2a 2f 0d 0a 20 20 20 20 20 20  rator */..      
4bd0: 20 20 2f 2f 2f 20 20 20 20 20 20 75 6e 73 69 67    ///      unsig
4be0: 6e 65 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b  ned char usable;
4bf0: 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20       /* True if 
4c00: 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20  this constraint 
4c10: 69 73 20 75 73 61 62 6c 65 20 2a 2f 0d 0a 20 20  is usable */..  
4c20: 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 20 69        ///      i
4c30: 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20  nt iTermOffset; 
4c40: 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64           /* Used
4c50: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42   internally - xB
4c60: 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20  estIndex should 
4c70: 69 67 6e 6f 72 65 20 2a 2f 0d 0a 20 20 20 20 20  ignore */..     
4c80: 20 20 20 2f 2f 2f 20 20 20 7d 20 2a 63 6f 6e 73     ///   } *cons
4c90: 74 20 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20  t aConstraint;  
4ca0: 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f 66 20      /* Table of 
4cb0: 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e  WHERE clause con
4cc0: 73 74 72 61 69 6e 74 73 20 2a 2f 0d 0a 20 20 20  straints */..   
4cd0: 20 20 20 20 20 2f 2f 2f 20 20 20 63 6f 6e 73 74       ///   const
4ce0: 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20   int nOrderBy;  
4cf0: 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
4d00: 6f 66 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20  of terms in the 
4d10: 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20  ORDER BY clause 
4d20: 2a 2f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  */..        /// 
4d30: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
4d40: 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f 72 64  qlite3_index_ord
4d50: 65 72 62 79 20 7b 0d 0a 20 20 20 20 20 20 20 20  erby {..        
4d60: 2f 2f 2f 20 20 20 20 20 20 69 6e 74 20 69 43 6f  ///      int iCo
4d70: 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20  lumn;           
4d80: 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d     /* Column num
4d90: 62 65 72 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20  ber */..        
4da0: 2f 2f 2f 20 20 20 20 20 20 75 6e 73 69 67 6e 65  ///      unsigne
4db0: 64 20 63 68 61 72 20 64 65 73 63 3b 20 20 20 20  d char desc;    
4dc0: 20 20 20 2f 2a 20 54 72 75 65 20 66 6f 72 20 44     /* True for D
4dd0: 45 53 43 2e 20 20 46 61 6c 73 65 20 66 6f 72 20  ESC.  False for 
4de0: 41 53 43 2e 20 2a 2f 0d 0a 20 20 20 20 20 20 20  ASC. */..       
4df0: 20 2f 2f 2f 20 20 20 7d 20 2a 63 6f 6e 73 74 20   ///   } *const 
4e00: 61 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20 20  aOrderBy;       
4e10: 20 20 2f 2a 20 54 68 65 20 4f 52 44 45 52 20 42    /* The ORDER B
4e20: 59 20 63 6c 61 75 73 65 20 2a 2f 0d 0a 20 20 20  Y clause */..   
4e30: 20 20 20 20 20 2f 2f 2f 20 20 20 2f 2a 20 4f 75       ///   /* Ou
4e40: 74 70 75 74 73 20 2a 2f 0d 0a 20 20 20 20 20 20  tputs */..      
4e50: 20 20 2f 2f 2f 20 20 20 73 74 72 75 63 74 20 73    ///   struct s
4e60: 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e  qlite3_index_con
4e70: 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20 7b 0d  straint_usage {.
4e80: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20  .        ///    
4e90: 20 69 6e 74 20 61 72 67 76 49 6e 64 65 78 3b 20   int argvIndex; 
4ea0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 69 66 20            /* if 
4eb0: 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20 69  >0, constraint i
4ec0: 73 20 70 61 72 74 20 6f 66 20 61 72 67 76 20 74  s part of argv t
4ed0: 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0d 0a 20 20  o xFilter */..  
4ee0: 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 75 6e        ///     un
4ef0: 73 69 67 6e 65 64 20 63 68 61 72 20 6f 6d 69 74  signed char omit
4f00: 3b 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f 74  ;      /* Do not
4f10: 20 63 6f 64 65 20 61 20 74 65 73 74 20 66 6f 72   code a test for
4f20: 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74   this constraint
4f30: 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f   */..        ///
4f40: 20 20 20 7d 20 2a 63 6f 6e 73 74 20 61 43 6f 6e     } *const aCon
4f50: 73 74 72 61 69 6e 74 55 73 61 67 65 3b 0d 0a 20  straintUsage;.. 
4f60: 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 69 6e 74         ///   int
4f70: 20 69 64 78 4e 75 6d 3b 20 20 20 20 20 20 20 20   idxNum;        
4f80: 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
4f90: 72 20 75 73 65 64 20 74 6f 20 69 64 65 6e 74 69  r used to identi
4fa0: 66 79 20 74 68 65 20 69 6e 64 65 78 20 2a 2f 0d  fy the index */.
4fb0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 63  .        ///   c
4fc0: 68 61 72 20 2a 69 64 78 53 74 72 3b 20 20 20 20  har *idxStr;    
4fd0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72            /* Str
4fe0: 69 6e 67 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62  ing, possibly ob
4ff0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69  tained from sqli
5000: 74 65 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0d 0a 20  te3_malloc */.. 
5010: 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 69 6e 74         ///   int
5020: 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53 74   needToFreeIdxSt
5030: 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20  r;      /* Free 
5040: 69 64 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c  idxStr using sql
5050: 69 74 65 33 5f 66 72 65 65 28 29 20 69 66 20 74  ite3_free() if t
5060: 72 75 65 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20  rue */..        
5070: 2f 2f 2f 20 20 20 69 6e 74 20 6f 72 64 65 72 42  ///   int orderB
5080: 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20  yConsumed;      
5090: 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70   /* True if outp
50a0: 75 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72  ut is already or
50b0: 64 65 72 65 64 20 2a 2f 0d 0a 20 20 20 20 20 20  dered */..      
50c0: 20 20 2f 2f 2f 20 20 20 64 6f 75 62 6c 65 20 65    ///   double e
50d0: 73 74 69 6d 61 74 65 64 43 6f 73 74 3b 20 20 20  stimatedCost;   
50e0: 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 65 64 20     /* Estimated 
50f0: 63 6f 73 74 20 6f 66 20 75 73 69 6e 67 20 74 68  cost of using th
5100: 69 73 20 69 6e 64 65 78 20 2a 2f 0d 0a 20 20 20  is index */..   
5110: 20 20 20 20 20 2f 2f 2f 20 20 20 3c 21 5b 43 44       ///   <![CD
5120: 41 54 41 5b 3c 62 3e 5d 5d 3e 2f 2a 20 46 69 65  ATA[<b>]]>/* Fie
5130: 6c 64 73 20 62 65 6c 6f 77 20 61 72 65 20 6f 6e  lds below are on
5140: 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ly available in 
5150: 53 51 4c 69 74 65 20 33 2e 38 2e 32 20 61 6e 64  SQLite 3.8.2 and
5160: 20 6c 61 74 65 72 20 2a 2f 3c 21 5b 43 44 41 54   later */<![CDAT
5170: 41 5b 3c 2f 62 3e 5d 5d 3e 0d 0a 20 20 20 20 20  A[</b>]]>..     
5180: 20 20 20 2f 2f 2f 20 20 20 73 71 6c 69 74 65 33     ///   sqlite3
5190: 5f 69 6e 74 36 34 20 65 73 74 69 6d 61 74 65 64  _int64 estimated
51a0: 52 6f 77 73 3b 20 20 20 20 2f 2a 20 45 73 74 69  Rows;    /* Esti
51b0: 6d 61 74 65 64 20 6e 75 6d 62 65 72 20 6f 66 20  mated number of 
51c0: 72 6f 77 73 20 72 65 74 75 72 6e 65 64 20 2a 2f  rows returned */
51d0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20  ..        ///   
51e0: 3c 21 5b 43 44 41 54 41 5b 3c 62 3e 5d 5d 3e 2f  <![CDATA[<b>]]>/
51f0: 2a 20 46 69 65 6c 64 73 20 62 65 6c 6f 77 20 61  * Fields below a
5200: 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  re only availabl
5210: 65 20 69 6e 20 53 51 4c 69 74 65 20 33 2e 39 2e  e in SQLite 3.9.
5220: 30 20 61 6e 64 20 6c 61 74 65 72 20 2a 2f 3c 21  0 and later */<!
5230: 5b 43 44 41 54 41 5b 3c 2f 62 3e 5d 5d 3e 0d 0a  [CDATA[</b>]]>..
5240: 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 69 6e          ///   in
5250: 74 20 69 64 78 46 6c 61 67 73 3b 20 20 20 20 20  t idxFlags;     
5260: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 73 6b           /* Mask
5270: 20 6f 66 20 53 51 4c 49 54 45 5f 49 4e 44 45 58   of SQLITE_INDEX
5280: 5f 53 43 41 4e 5f 2a 20 66 6c 61 67 73 20 2a 2f  _SCAN_* flags */
5290: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20  ..        ///   
52a0: 3c 21 5b 43 44 41 54 41 5b 3c 62 3e 5d 5d 3e 2f  <![CDATA[<b>]]>/
52b0: 2a 20 46 69 65 6c 64 73 20 62 65 6c 6f 77 20 61  * Fields below a
52c0: 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  re only availabl
52d0: 65 20 69 6e 20 53 51 4c 69 74 65 20 33 2e 31 30  e in SQLite 3.10
52e0: 2e 30 20 61 6e 64 20 6c 61 74 65 72 20 2a 2f 3c  .0 and later */<
52f0: 21 5b 43 44 41 54 41 5b 3c 2f 62 3e 5d 5d 3e 0d  ![CDATA[</b>]]>.
5300: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 73  .        ///   s
5310: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 63 6f  qlite3_uint64 co
5320: 6c 55 73 65 64 3b 20 20 20 20 2f 2a 20 49 6e 70  lUsed;    /* Inp
5330: 75 74 3a 20 4d 61 73 6b 20 6f 66 20 63 6f 6c 75  ut: Mask of colu
5340: 6d 6e 73 20 75 73 65 64 20 62 79 20 73 74 61 74  mns used by stat
5350: 65 6d 65 6e 74 20 2a 2f 0d 0a 20 20 20 20 20 20  ement */..      
5360: 20 20 2f 2f 2f 20 7d 3b 0d 0a 20 20 20 20 20 20    /// };..      
5370: 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70    /// </code></p
5380: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
5390: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
53a0: 20 20 2f 2f 2f 20 4e 6f 74 65 20 74 68 65 20 77    /// Note the w
53b0: 61 72 6e 69 6e 67 73 20 6f 6e 20 74 68 65 20 22  arnings on the "
53c0: 65 73 74 69 6d 61 74 65 64 52 6f 77 73 22 2c 20  estimatedRows", 
53d0: 22 69 64 78 46 6c 61 67 73 22 2c 20 61 6e 64 20  "idxFlags", and 
53e0: 63 6f 6c 55 73 65 64 20 66 69 65 6c 64 73 2e 0d  colUsed fields..
53f0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65  .        /// The
5400: 73 65 20 66 69 65 6c 64 73 20 77 65 72 65 20 61  se fields were a
5410: 64 64 65 64 20 77 69 74 68 20 53 51 4c 69 74 65  dded with SQLite
5420: 20 76 65 72 73 69 6f 6e 73 20 33 2e 38 2e 32 2c   versions 3.8.2,
5430: 20 33 2e 39 2e 30 2c 20 61 6e 64 20 33 2e 31 30   3.9.0, and 3.10
5440: 2e 30 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79  .0, respectively
5450: 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  . ..        /// 
5460: 41 6e 79 20 65 78 74 65 6e 73 69 6f 6e 20 74 68  Any extension th
5470: 61 74 20 72 65 61 64 73 20 6f 72 20 77 72 69 74  at reads or writ
5480: 65 73 20 74 68 65 73 65 20 66 69 65 6c 64 73 20  es these fields 
5490: 6d 75 73 74 20 66 69 72 73 74 20 63 68 65 63 6b  must first check
54a0: 20 74 68 61 74 20 74 68 65 20 0d 0a 20 20 20 20   that the ..    
54b0: 20 20 20 20 2f 2f 2f 20 76 65 72 73 69 6f 6e 20      /// version 
54c0: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
54d0: 62 72 61 72 79 20 69 6e 20 75 73 65 20 69 73 20  brary in use is 
54e0: 67 72 65 61 74 65 72 20 74 68 61 6e 20 6f 72 20  greater than or 
54f0: 65 71 75 61 6c 20 74 6f 20 61 70 70 72 6f 70 72  equal to appropr
5500: 69 61 74 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f  iate..        //
5510: 2f 20 76 65 72 73 69 6f 6e 20 2d 20 70 65 72 68  / version - perh
5520: 61 70 73 20 63 6f 6d 70 61 72 69 6e 67 20 74 68  aps comparing th
5530: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
5540: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 69   from sqlite3_li
5550: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
5560: 29 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 61  )..        /// a
5570: 67 61 69 6e 73 74 20 63 6f 6e 73 74 61 6e 74 73  gainst constants
5580: 20 33 30 30 38 30 30 32 2c 20 33 30 30 39 30 30   3008002, 300900
5590: 30 2c 20 61 6e 64 2f 6f 72 20 33 30 31 30 30 30  0, and/or 301000
55a0: 30 2e 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66  0. The result of
55b0: 20 61 74 74 65 6d 70 74 69 6e 67 20 0d 0a 20 20   attempting ..  
55c0: 20 20 20 20 20 20 2f 2f 2f 20 74 6f 20 61 63 63        /// to acc
55d0: 65 73 73 20 74 68 65 73 65 20 66 69 65 6c 64 73  ess these fields
55e0: 20 69 6e 20 61 6e 20 73 71 6c 69 74 65 33 5f 69   in an sqlite3_i
55f0: 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74  ndex_info struct
5600: 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 61  ure created by a
5610: 6e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  n ..        /// 
5620: 6f 6c 64 65 72 20 76 65 72 73 69 6f 6e 20 6f 66  older version of
5630: 20 53 51 4c 69 74 65 20 61 72 65 20 75 6e 64 65   SQLite are unde
5640: 66 69 6e 65 64 2e 0d 0a 20 20 20 20 20 20 20 20  fined...        
5650: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
5660: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
5670: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 49 6e 20  .        /// In 
5680: 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 20  addition, there 
5690: 61 72 65 20 73 6f 6d 65 20 64 65 66 69 6e 65 64  are some defined
56a0: 20 63 6f 6e 73 74 61 6e 74 73 3a 0d 0a 20 20 20   constants:..   
56b0: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e       /// </para>
56c0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
56d0: 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20  ara><code>..    
56e0: 20 20 20 20 2f 2f 2f 20 23 64 65 66 69 6e 65 20      /// #define 
56f0: 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
5700: 53 54 52 41 49 4e 54 5f 45 51 20 20 20 20 20 20  STRAINT_EQ      
5710: 20 20 20 32 0d 0a 20 20 20 20 20 20 20 20 2f 2f     2..        //
5720: 2f 20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  / #define SQLITE
5730: 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
5740: 54 5f 47 54 20 20 20 20 20 20 20 20 20 34 0d 0a  T_GT         4..
5750: 20 20 20 20 20 20 20 20 2f 2f 2f 20 23 64 65 66          /// #def
5760: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
5770: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20 20  _CONSTRAINT_LE  
5780: 20 20 20 20 20 20 20 38 0d 0a 20 20 20 20 20 20         8..      
5790: 20 20 2f 2f 2f 20 23 64 65 66 69 6e 65 20 53 51    /// #define SQ
57a0: 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
57b0: 52 41 49 4e 54 5f 4c 54 20 20 20 20 20 20 20 20  RAINT_LT        
57c0: 31 36 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  16..        /// 
57d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
57e0: 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
57f0: 47 45 20 20 20 20 20 20 20 20 33 32 0d 0a 20 20  GE        32..  
5800: 20 20 20 20 20 20 2f 2f 2f 20 23 64 65 66 69 6e        /// #defin
5810: 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
5820: 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43 48 20  ONSTRAINT_MATCH 
5830: 20 20 20 20 36 34 0d 0a 20 20 20 20 20 20 20 20      64..        
5840: 2f 2f 2f 20 23 64 65 66 69 6e 65 20 53 51 4c 49  /// #define SQLI
5850: 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
5860: 49 4e 54 5f 4c 49 4b 45 20 20 20 20 20 20 36 35  INT_LIKE      65
5870: 20 20 2f 2a 20 33 2e 31 30 2e 30 20 61 6e 64 20    /* 3.10.0 and 
5880: 6c 61 74 65 72 20 2a 2f 0d 0a 20 20 20 20 20 20  later */..      
5890: 20 20 2f 2f 2f 20 23 64 65 66 69 6e 65 20 53 51    /// #define SQ
58a0: 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
58b0: 52 41 49 4e 54 5f 47 4c 4f 42 20 20 20 20 20 20  RAINT_GLOB      
58c0: 36 36 20 20 2f 2a 20 33 2e 31 30 2e 30 20 61 6e  66  /* 3.10.0 an
58d0: 64 20 6c 61 74 65 72 20 2a 2f 0d 0a 20 20 20 20  d later */..    
58e0: 20 20 20 20 2f 2f 2f 20 23 64 65 66 69 6e 65 20      /// #define 
58f0: 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
5900: 53 54 52 41 49 4e 54 5f 52 45 47 45 58 50 20 20  STRAINT_REGEXP  
5910: 20 20 36 37 20 20 2f 2a 20 33 2e 31 30 2e 30 20    67  /* 3.10.0 
5920: 61 6e 64 20 6c 61 74 65 72 20 2a 2f 0d 0a 20 20  and later */..  
5930: 20 20 20 20 20 20 2f 2f 2f 20 23 64 65 66 69 6e        /// #defin
5940: 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
5950: 4f 4e 53 54 52 41 49 4e 54 5f 4e 45 20 20 20 20  ONSTRAINT_NE    
5960: 20 20 20 20 36 38 20 20 2f 2a 20 33 2e 32 31 2e      68  /* 3.21.
5970: 30 20 61 6e 64 20 6c 61 74 65 72 20 2a 2f 0d 0a  0 and later */..
5980: 20 20 20 20 20 20 20 20 2f 2f 2f 20 23 64 65 66          /// #def
5990: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
59a0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 49 53 4e 4f  _CONSTRAINT_ISNO
59b0: 54 20 20 20 20 20 36 39 20 20 2f 2a 20 33 2e 32  T     69  /* 3.2
59c0: 31 2e 30 20 61 6e 64 20 6c 61 74 65 72 20 2a 2f  1.0 and later */
59d0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 23 64  ..        /// #d
59e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
59f0: 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 49 53  EX_CONSTRAINT_IS
5a00: 4e 4f 54 4e 55 4c 4c 20 37 30 20 20 2f 2a 20 33  NOTNULL 70  /* 3
5a10: 2e 32 31 2e 30 20 61 6e 64 20 6c 61 74 65 72 20  .21.0 and later 
5a20: 2a 2f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  */..        /// 
5a30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5a40: 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
5a50: 49 53 4e 55 4c 4c 20 20 20 20 37 31 20 20 2f 2a  ISNULL    71  /*
5a60: 20 33 2e 32 31 2e 30 20 61 6e 64 20 6c 61 74 65   3.21.0 and late
5a70: 72 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20 2f 2f  r */..        //
5a80: 2f 20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  / #define SQLITE
5a90: 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
5aa0: 54 5f 49 53 20 20 20 20 20 20 20 20 37 32 20 20  T_IS        72  
5ab0: 2f 2a 20 33 2e 32 31 2e 30 20 61 6e 64 20 6c 61  /* 3.21.0 and la
5ac0: 74 65 72 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20  ter */..        
5ad0: 2f 2f 2f 20 23 64 65 66 69 6e 65 20 53 51 4c 49  /// #define SQLI
5ae0: 54 45 5f 49 4e 44 45 58 5f 53 43 41 4e 5f 55 4e  TE_INDEX_SCAN_UN
5af0: 49 51 55 45 20 20 20 20 20 20 20 20 20 20 20 31  IQUE           1
5b00: 20 20 2f 2a 20 53 63 61 6e 20 76 69 73 69 74 73    /* Scan visits
5b10: 20 61 74 20 6d 6f 73 74 20 31 20 72 6f 77 20 2a   at most 1 row *
5b20: 2f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  /..        /// <
5b30: 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20  /code></para>.. 
5b40: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
5b50: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54  >..        /// T
5b60: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 63  he SQLite core c
5b70: 61 6c 6c 73 20 74 68 65 20 78 42 65 73 74 49 6e  alls the xBestIn
5b80: 64 65 78 20 6d 65 74 68 6f 64 20 77 68 65 6e 20  dex method when 
5b90: 69 74 20 69 73 20 63 6f 6d 70 69 6c 69 6e 67 20  it is compiling 
5ba0: 61 20 71 75 65 72 79 0d 0a 20 20 20 20 20 20 20  a query..       
5bb0: 20 2f 2f 2f 20 74 68 61 74 20 69 6e 76 6f 6c 76   /// that involv
5bc0: 65 73 20 61 20 76 69 72 74 75 61 6c 20 74 61 62  es a virtual tab
5bd0: 6c 65 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  le. In other wor
5be0: 64 73 2c 20 53 51 4c 69 74 65 20 63 61 6c 6c 73  ds, SQLite calls
5bf0: 20 74 68 69 73 20 6d 65 74 68 6f 64 20 0d 0a 20   this method .. 
5c00: 20 20 20 20 20 20 20 2f 2f 2f 20 77 68 65 6e 20         /// when 
5c10: 69 74 20 69 73 20 72 75 6e 6e 69 6e 67 20 73 71  it is running sq
5c20: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
5c30: 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e  or the equivalen
5c40: 74 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  t. ..        ///
5c50: 20 42 79 20 63 61 6c 6c 69 6e 67 20 74 68 69 73   By calling this
5c60: 20 6d 65 74 68 6f 64 2c 20 74 68 65 20 0d 0a 20   method, the .. 
5c70: 20 20 20 20 20 20 20 2f 2f 2f 20 53 51 4c 69 74         /// SQLit
5c80: 65 20 63 6f 72 65 20 69 73 20 73 61 79 69 6e 67  e core is saying
5c90: 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 20   to the virtual 
5ca0: 74 61 62 6c 65 20 74 68 61 74 20 69 74 20 6e 65  table that it ne
5cb0: 65 64 73 20 74 6f 20 61 63 63 65 73 73 20 0d 0a  eds to access ..
5cc0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 6f 6d 65          /// some
5cd0: 20 73 75 62 73 65 74 20 6f 66 20 74 68 65 20 72   subset of the r
5ce0: 6f 77 73 20 69 6e 20 74 68 65 20 76 69 72 74 75  ows in the virtu
5cf0: 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 69 74 20  al table and it 
5d00: 77 61 6e 74 73 20 74 6f 20 6b 6e 6f 77 20 74 68  wants to know th
5d10: 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6d  e..        /// m
5d20: 6f 73 74 20 65 66 66 69 63 69 65 6e 74 20 77 61  ost efficient wa
5d30: 79 20 74 6f 20 64 6f 20 74 68 61 74 20 61 63 63  y to do that acc
5d40: 65 73 73 2e 20 54 68 65 20 78 42 65 73 74 49 6e  ess. The xBestIn
5d50: 64 65 78 20 6d 65 74 68 6f 64 20 72 65 70 6c 69  dex method repli
5d60: 65 73 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  es ..        ///
5d70: 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f   with informatio
5d80: 6e 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74  n that the SQLit
5d90: 65 20 63 6f 72 65 20 63 61 6e 20 74 68 65 6e 20  e core can then 
5da0: 75 73 65 20 74 6f 20 63 6f 6e 64 75 63 74 20 61  use to conduct a
5db0: 6e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  n ..        /// 
5dc0: 65 66 66 69 63 69 65 6e 74 20 73 65 61 72 63 68  efficient search
5dd0: 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20   of the virtual 
5de0: 74 61 62 6c 65 2e 0d 0a 20 20 20 20 20 20 20 20  table...        
5df0: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
5e00: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
5e10: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 57 68 69  .        /// Whi
5e20: 6c 65 20 63 6f 6d 70 69 6c 69 6e 67 20 61 20 73  le compiling a s
5e30: 69 6e 67 6c 65 20 53 51 4c 20 71 75 65 72 79 2c  ingle SQL query,
5e40: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
5e50: 20 6d 69 67 68 74 20 63 61 6c 6c 20 0d 0a 20 20   might call ..  
5e60: 20 20 20 20 20 20 2f 2f 2f 20 78 42 65 73 74 49        /// xBestI
5e70: 6e 64 65 78 20 6d 75 6c 74 69 70 6c 65 20 74 69  ndex multiple ti
5e80: 6d 65 73 20 77 69 74 68 20 64 69 66 66 65 72 65  mes with differe
5e90: 6e 74 20 73 65 74 74 69 6e 67 73 20 69 6e 20 73  nt settings in s
5ea0: 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
5eb0: 6f 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  o...        /// 
5ec0: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
5ed0: 77 69 6c 6c 20 74 68 65 6e 20 73 65 6c 65 63 74  will then select
5ee0: 20 74 68 65 20 63 6f 6d 62 69 6e 61 74 69 6f 6e   the combination
5ef0: 20 74 68 61 74 20 61 70 70 65 61 72 73 20 74 6f   that appears to
5f00: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 67   ..        /// g
5f10: 69 76 65 20 74 68 65 20 62 65 73 74 20 70 65 72  ive the best per
5f20: 66 6f 72 6d 61 6e 63 65 2e 0d 0a 20 20 20 20 20  formance...     
5f30: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a     /// </para>..
5f40: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
5f50: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
5f60: 42 65 66 6f 72 65 20 63 61 6c 6c 69 6e 67 20 74  Before calling t
5f70: 68 69 73 20 6d 65 74 68 6f 64 2c 20 74 68 65 20  his method, the 
5f80: 53 51 4c 69 74 65 20 63 6f 72 65 20 69 6e 69 74  SQLite core init
5f90: 69 61 6c 69 7a 65 73 20 61 6e 20 69 6e 73 74 61  ializes an insta
5fa0: 6e 63 65 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  nce ..        //
5fb0: 2f 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  / of the sqlite3
5fc0: 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75  _index_info stru
5fd0: 63 74 75 72 65 20 77 69 74 68 20 69 6e 66 6f 72  cture with infor
5fe0: 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
5ff0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 71 75  ..        /// qu
6000: 65 72 79 20 74 68 61 74 20 69 74 20 69 73 20 63  ery that it is c
6010: 75 72 72 65 6e 74 6c 79 20 74 72 79 69 6e 67 20  urrently trying 
6020: 74 6f 20 70 72 6f 63 65 73 73 2e 20 54 68 69 73  to process. This
6030: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 0d 0a 20   information .. 
6040: 20 20 20 20 20 20 20 2f 2f 2f 20 64 65 72 69 76         /// deriv
6050: 65 73 20 6d 61 69 6e 6c 79 20 66 72 6f 6d 20 74  es mainly from t
6060: 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  he WHERE clause 
6070: 61 6e 64 20 4f 52 44 45 52 20 42 59 20 6f 72 20  and ORDER BY or 
6080: 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 73  GROUP BY clauses
6090: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6f   ..        /// o
60a0: 66 20 74 68 65 20 71 75 65 72 79 2c 20 62 75 74  f the query, but
60b0: 20 61 6c 73 6f 20 66 72 6f 6d 20 61 6e 79 20 4f   also from any O
60c0: 4e 20 6f 72 20 55 53 49 4e 47 20 63 6c 61 75 73  N or USING claus
60d0: 65 73 20 69 66 20 74 68 65 20 71 75 65 72 79 20  es if the query 
60e0: 69 73 20 61 20 0d 0a 20 20 20 20 20 20 20 20 2f  is a ..        /
60f0: 2f 2f 20 6a 6f 69 6e 2e 20 54 68 65 20 69 6e 66  // join. The inf
6100: 6f 72 6d 61 74 69 6f 6e 20 74 68 61 74 20 74 68  ormation that th
6110: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 70 72  e SQLite core pr
6120: 6f 76 69 64 65 73 20 74 6f 20 74 68 65 20 78 42  ovides to the xB
6130: 65 73 74 49 6e 64 65 78 20 0d 0a 20 20 20 20 20  estIndex ..     
6140: 20 20 20 2f 2f 2f 20 6d 65 74 68 6f 64 20 69 73     /// method is
6150: 20 68 65 6c 64 20 69 6e 20 74 68 65 20 70 61 72   held in the par
6160: 74 20 6f 66 20 74 68 65 20 73 74 72 75 63 74 75  t of the structu
6170: 72 65 20 74 68 61 74 20 69 73 20 6d 61 72 6b 65  re that is marke
6180: 64 20 61 73 20 22 49 6e 70 75 74 73 22 2e 20 0d  d as "Inputs". .
6190: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65  .        /// The
61a0: 20 22 4f 75 74 70 75 74 73 22 20 73 65 63 74 69   "Outputs" secti
61b0: 6f 6e 20 69 73 20 69 6e 69 74 69 61 6c 69 7a 65  on is initialize
61c0: 64 20 74 6f 20 7a 65 72 6f 2e 0d 0a 20 20 20 20  d to zero...    
61d0: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
61e0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
61f0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
6200: 20 54 68 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e   The information
6210: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f   in the sqlite3_
6220: 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63  index_info struc
6230: 74 75 72 65 20 69 73 20 65 70 68 65 6d 65 72 61  ture is ephemera
6240: 6c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 61  l..        /// a
6250: 6e 64 20 6d 61 79 20 62 65 20 6f 76 65 72 77 72  nd may be overwr
6260: 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  itten or dealloc
6270: 61 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  ated as soon as 
6280: 74 68 65 20 78 42 65 73 74 49 6e 64 65 78 20 6d  the xBestIndex m
6290: 65 74 68 6f 64 0d 0a 20 20 20 20 20 20 20 20 2f  ethod..        /
62a0: 2f 2f 20 72 65 74 75 72 6e 73 2e 20 20 49 66 20  // returns.  If 
62b0: 74 68 65 20 78 42 65 73 74 49 6e 64 65 78 20 6d  the xBestIndex m
62c0: 65 74 68 6f 64 20 6e 65 65 64 73 20 74 6f 20 72  ethod needs to r
62d0: 65 6d 65 6d 62 65 72 20 61 6e 79 20 70 61 72 74  emember any part
62e0: 20 6f 66 20 74 68 65 0d 0a 20 20 20 20 20 20 20   of the..       
62f0: 20 2f 2f 2f 20 73 71 6c 69 74 65 33 5f 69 6e 64   /// sqlite3_ind
6300: 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72  ex_info structur
6310: 65 2c 20 69 74 20 73 68 6f 75 6c 64 20 6d 61 6b  e, it should mak
6320: 65 20 61 20 63 6f 70 79 2e 20 20 43 61 72 65 20  e a copy.  Care 
6330: 6d 75 73 74 20 62 65 0d 0a 20 20 20 20 20 20 20  must be..       
6340: 20 2f 2f 2f 20 74 61 6b 65 20 74 6f 20 73 74 6f   /// take to sto
6350: 72 65 20 74 68 65 20 63 6f 70 79 20 69 6e 20 61  re the copy in a
6360: 20 70 6c 61 63 65 20 77 68 65 72 65 20 69 74 20   place where it 
6370: 77 69 6c 6c 20 62 65 20 64 65 61 6c 6c 6f 63 61  will be dealloca
6380: 74 65 64 2c 20 73 75 63 68 0d 0a 20 20 20 20 20  ted, such..     
6390: 20 20 20 2f 2f 2f 20 61 73 20 69 6e 20 74 68 65     /// as in the
63a0: 20 69 64 78 53 74 72 20 66 69 65 6c 64 20 77 69   idxStr field wi
63b0: 74 68 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78  th needToFreeIdx
63c0: 53 74 72 20 73 65 74 20 74 6f 20 31 2e 0d 0a 20  Str set to 1... 
63d0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
63e0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
63f0: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
6400: 2f 2f 2f 20 4e 6f 74 65 20 74 68 61 74 20 78 42  /// Note that xB
6410: 65 73 74 49 6e 64 65 78 20 77 69 6c 6c 20 61 6c  estIndex will al
6420: 77 61 79 73 20 62 65 20 63 61 6c 6c 65 64 20 62  ways be called b
6430: 65 66 6f 72 65 20 78 46 69 6c 74 65 72 2c 20 73  efore xFilter, s
6440: 69 6e 63 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ince..        //
6450: 2f 20 74 68 65 20 69 64 78 4e 75 6d 20 61 6e 64  / the idxNum and
6460: 20 69 64 78 53 74 72 20 6f 75 74 70 75 74 73 20   idxStr outputs 
6470: 66 72 6f 6d 20 78 42 65 73 74 49 6e 64 65 78 20  from xBestIndex 
6480: 61 72 65 20 72 65 71 75 69 72 65 64 20 69 6e 70  are required inp
6490: 75 74 73 20 74 6f 0d 0a 20 20 20 20 20 20 20 20  uts to..        
64a0: 2f 2f 2f 20 78 46 69 6c 74 65 72 2e 20 20 48 6f  /// xFilter.  Ho
64b0: 77 65 76 65 72 2c 20 74 68 65 72 65 20 69 73 20  wever, there is 
64c0: 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  no guarantee tha
64d0: 74 20 78 46 69 6c 74 65 72 20 77 69 6c 6c 20 62  t xFilter will b
64e0: 65 20 63 61 6c 6c 65 64 0d 0a 20 20 20 20 20 20  e called..      
64f0: 20 20 2f 2f 2f 20 66 6f 6c 6c 6f 77 69 6e 67 20    /// following 
6500: 61 20 73 75 63 63 65 73 73 66 75 6c 20 78 42 65  a successful xBe
6510: 73 74 49 6e 64 65 78 2e 20 20 0d 0a 20 20 20 20  stIndex.  ..    
6520: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
6530: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
6540: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
6550: 20 54 68 65 20 78 42 65 73 74 49 6e 64 65 78 20   The xBestIndex 
6560: 6d 65 74 68 6f 64 20 69 73 20 72 65 71 75 69 72  method is requir
6570: 65 64 20 66 6f 72 20 65 76 65 72 79 20 76 69 72  ed for every vir
6580: 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65  tual table imple
6590: 6d 65 6e 74 61 74 69 6f 6e 2e 0d 0a 20 20 20 20  mentation...    
65a0: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
65b0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
65c0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
65d0: 20 54 68 65 20 6d 61 69 6e 20 74 68 69 6e 67 20   The main thing 
65e0: 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65 20  that the SQLite 
65f0: 63 6f 72 65 20 69 73 20 74 72 79 69 6e 67 20 74  core is trying t
6600: 6f 20 63 6f 6d 6d 75 6e 69 63 61 74 65 20 74 6f  o communicate to
6610: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74   ..        /// t
6620: 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
6630: 20 69 73 20 74 68 65 20 63 6f 6e 73 74 72 61 69   is the constrai
6640: 6e 74 73 20 74 68 61 74 20 61 72 65 20 61 76 61  nts that are ava
6650: 69 6c 61 62 6c 65 20 74 6f 20 6c 69 6d 69 74 20  ilable to limit 
6660: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68  ..        /// th
6670: 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
6680: 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 62 65   that need to be
6690: 20 73 65 61 72 63 68 65 64 2e 20 54 68 65 20 61   searched. The a
66a0: 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72  Constraint[] arr
66b0: 61 79 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ay ..        ///
66c0: 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 65 20 65 6e   contains one en
66d0: 74 72 79 20 66 6f 72 20 65 61 63 68 20 63 6f 6e  try for each con
66e0: 73 74 72 61 69 6e 74 2e 20 54 68 65 72 65 20 77  straint. There w
66f0: 69 6c 6c 20 62 65 20 65 78 61 63 74 6c 79 20 0d  ill be exactly .
6700: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6e 43 6f  .        /// nCo
6710: 6e 73 74 72 61 69 6e 74 20 65 6e 74 72 69 65 73  nstraint entries
6720: 20 69 6e 20 74 68 61 74 20 61 72 72 61 79 2e 0d   in that array..
6730: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
6740: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
6750: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
6760: 20 20 2f 2f 2f 20 45 61 63 68 20 63 6f 6e 73 74    /// Each const
6770: 72 61 69 6e 74 20 77 69 6c 6c 20 63 6f 72 72 65  raint will corre
6780: 73 70 6f 6e 64 20 74 6f 20 61 20 74 65 72 6d 20  spond to a term 
6790: 69 6e 20 74 68 65 20 57 48 45 52 45 20 63 6c 61  in the WHERE cla
67a0: 75 73 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  use..        ///
67b0: 20 6f 72 20 69 6e 20 61 20 55 53 49 4e 47 20 6f   or in a USING o
67c0: 72 20 4f 4e 20 63 6c 61 75 73 65 20 74 68 61 74  r ON clause that
67d0: 20 69 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 0d   is of the form.
67e0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
67f0: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
6800: 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a  / <para><code>..
6810: 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20          ///     
6820: 20 63 6f 6c 75 6d 6e 20 20 4f 50 20 20 45 58 50   column  OP  EXP
6830: 52 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  R..        /// <
6840: 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20  /code></para>.. 
6850: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
6860: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 57  >..        /// W
6870: 68 65 72 65 20 22 63 6f 6c 75 6d 6e 22 20 69 73  here "column" is
6880: 20 61 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65   a column in the
6890: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2c 20   virtual table, 
68a0: 4f 50 20 69 73 20 61 6e 20 6f 70 65 72 61 74 6f  OP is an operato
68b0: 72 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  r ..        /// 
68c0: 6c 69 6b 65 20 22 3d 22 20 6f 72 20 22 26 6c 74  like "=" or "&lt
68d0: 3b 22 2c 20 61 6e 64 20 45 58 50 52 20 69 73 20  ;", and EXPR is 
68e0: 61 6e 20 61 72 62 69 74 72 61 72 79 20 65 78 70  an arbitrary exp
68f0: 72 65 73 73 69 6f 6e 2e 20 53 6f 2c 20 66 6f 72  ression. So, for
6900: 20 65 78 61 6d 70 6c 65 2c 0d 0a 20 20 20 20 20   example,..     
6910: 20 20 20 2f 2f 2f 20 69 66 20 74 68 65 20 57 48     /// if the WH
6920: 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 74 61  ERE clause conta
6930: 69 6e 65 64 20 61 20 74 65 72 6d 20 6c 69 6b 65  ined a term like
6940: 20 74 68 69 73 3a 0d 0a 20 20 20 20 20 20 20 20   this:..        
6950: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
6960: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c       /// <para><
6970: 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f  code>..        /
6980: 2f 2f 20 61 20 3d 20 35 0d 0a 20 20 20 20 20 20  // a = 5..      
6990: 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70    /// </code></p
69a0: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
69b0: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
69c0: 20 20 2f 2f 2f 20 54 68 65 6e 20 6f 6e 65 20 6f    /// Then one o
69d0: 66 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74  f the constraint
69e0: 73 20 77 6f 75 6c 64 20 62 65 20 6f 6e 20 74 68  s would be on th
69f0: 65 20 22 61 22 20 63 6f 6c 75 6d 6e 20 77 69 74  e "a" column wit
6a00: 68 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  h ..        /// 
6a10: 6f 70 65 72 61 74 6f 72 20 22 3d 22 20 61 6e 64  operator "=" and
6a20: 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f   an expression o
6a30: 66 20 22 35 22 2e 20 43 6f 6e 73 74 72 61 69 6e  f "5". Constrain
6a40: 74 73 20 6e 65 65 64 20 6e 6f 74 20 68 61 76 65  ts need not have
6a50: 20 61 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20   a..        /// 
6a60: 6c 69 74 65 72 61 6c 20 72 65 70 72 65 73 65 6e  literal represen
6a70: 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 57 48  tation of the WH
6a80: 45 52 45 20 63 6c 61 75 73 65 2e 20 54 68 65 20  ERE clause. The 
6a90: 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 20  query optimizer 
6aa0: 6d 69 67 68 74 0d 0a 20 20 20 20 20 20 20 20 2f  might..        /
6ab0: 2f 2f 20 6d 61 6b 65 20 74 72 61 6e 73 66 6f 72  // make transfor
6ac0: 6d 61 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 0d  mations to the .
6ad0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 57 48 45  .        /// WHE
6ae0: 52 45 20 63 6c 61 75 73 65 20 69 6e 20 6f 72 64  RE clause in ord
6af0: 65 72 20 74 6f 20 65 78 74 72 61 63 74 20 61 73  er to extract as
6b00: 20 6d 61 6e 79 20 63 6f 6e 73 74 72 61 69 6e 74   many constraint
6b10: 73 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  s ..        /// 
6b20: 61 73 20 69 74 20 63 61 6e 2e 20 53 6f 2c 20 66  as it can. So, f
6b30: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74  or example, if t
6b40: 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  he WHERE clause 
6b50: 63 6f 6e 74 61 69 6e 65 64 20 73 6f 6d 65 74 68  contained someth
6b60: 69 6e 67 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ing ..        //
6b70: 2f 20 6c 69 6b 65 20 74 68 69 73 3a 0d 0a 20 20  / like this:..  
6b80: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61        /// </para
6b90: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
6ba0: 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20  para><code>..   
6bb0: 20 20 20 20 20 2f 2f 2f 20 78 20 42 45 54 57 45       /// x BETWE
6bc0: 45 4e 20 31 30 20 41 4e 44 20 31 30 30 20 41 4e  EN 10 AND 100 AN
6bd0: 44 20 39 39 39 26 67 74 3b 79 0d 0a 20 20 20 20  D 999&gt;y..    
6be0: 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c      /// </code><
6bf0: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
6c00: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20  /// <para>..    
6c10: 20 20 20 20 2f 2f 2f 20 54 68 65 20 71 75 65 72      /// The quer
6c20: 79 20 6f 70 74 69 6d 69 7a 65 72 20 6d 69 67 68  y optimizer migh
6c30: 74 20 74 72 61 6e 73 6c 61 74 65 20 74 68 69 73  t translate this
6c40: 20 69 6e 74 6f 20 74 68 72 65 65 20 73 65 70 61   into three sepa
6c50: 72 61 74 65 20 63 6f 6e 73 74 72 61 69 6e 74 73  rate constraints
6c60: 3a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  :..        /// <
6c70: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
6c80: 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e  /// <para><code>
6c90: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 78 20  ..        /// x 
6ca0: 26 67 74 3b 3d 20 31 30 0d 0a 20 20 20 20 20 20  &gt;= 10..      
6cb0: 20 20 2f 2f 2f 20 78 20 26 6c 74 3b 3d 20 31 30    /// x &lt;= 10
6cc0: 30 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 79  0..        /// y
6cd0: 20 26 6c 74 3b 20 39 39 39 0d 0a 20 20 20 20 20   &lt; 999..     
6ce0: 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f     /// </code></
6cf0: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
6d00: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20  // <para>..     
6d10: 20 20 20 2f 2f 2f 20 46 6f 72 20 65 61 63 68 20     /// For each 
6d20: 63 6f 6e 73 74 72 61 69 6e 74 2c 20 74 68 65 20  constraint, the 
6d30: 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43  aConstraint[].iC
6d40: 6f 6c 75 6d 6e 20 66 69 65 6c 64 20 69 6e 64 69  olumn field indi
6d50: 63 61 74 65 73 20 77 68 69 63 68 20 0d 0a 20 20  cates which ..  
6d60: 20 20 20 20 20 20 2f 2f 2f 20 63 6f 6c 75 6d 6e        /// column
6d70: 20 61 70 70 65 61 72 73 20 6f 6e 20 74 68 65 20   appears on the 
6d80: 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  left-hand side o
6d90: 66 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74  f the constraint
6da0: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54  ...        /// T
6db0: 68 65 20 66 69 72 73 74 20 63 6f 6c 75 6d 6e 20  he first column 
6dc0: 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  of the virtual t
6dd0: 61 62 6c 65 20 69 73 20 63 6f 6c 75 6d 6e 20 30  able is column 0
6de0: 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  . ..        /// 
6df0: 54 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65  The rowid of the
6e00: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
6e10: 73 20 63 6f 6c 75 6d 6e 20 2d 31 2e 20 0d 0a 20  s column -1. .. 
6e20: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 61         /// The a
6e30: 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 20  Constraint[].op 
6e40: 66 69 65 6c 64 20 69 6e 64 69 63 61 74 65 73 20  field indicates 
6e50: 77 68 69 63 68 20 6f 70 65 72 61 74 6f 72 20 69  which operator i
6e60: 73 20 75 73 65 64 2e 20 0d 0a 20 20 20 20 20 20  s used. ..      
6e70: 20 20 2f 2f 2f 20 54 68 65 20 53 51 4c 49 54 45    /// The SQLITE
6e80: 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
6e90: 54 5f 2a 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61  T_* constants ma
6ea0: 70 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  p integer consta
6eb0: 6e 74 73 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  nts ..        //
6ec0: 2f 20 69 6e 74 6f 20 6f 70 65 72 61 74 6f 72 20  / into operator 
6ed0: 76 61 6c 75 65 73 2e 0d 0a 20 20 20 20 20 20 20  values...       
6ee0: 20 2f 2f 2f 20 43 6f 6c 75 6d 6e 73 20 6f 63 63   /// Columns occ
6ef0: 75 72 20 69 6e 20 74 68 65 20 6f 72 64 65 72 20  ur in the order 
6f00: 74 68 65 79 20 77 65 72 65 20 64 65 66 69 6e 65  they were define
6f10: 64 20 62 79 20 74 68 65 20 63 61 6c 6c 20 74 6f  d by the call to
6f20: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 71  ..        /// sq
6f30: 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74  lite3_declare_vt
6f40: 61 62 28 29 20 69 6e 20 74 68 65 20 78 43 72 65  ab() in the xCre
6f50: 61 74 65 20 6f 72 20 78 43 6f 6e 6e 65 63 74 20  ate or xConnect 
6f60: 6d 65 74 68 6f 64 2e 0d 0a 20 20 20 20 20 20 20  method...       
6f70: 20 2f 2f 2f 20 48 69 64 64 65 6e 20 63 6f 6c 75   /// Hidden colu
6f80: 6d 6e 73 20 61 72 65 20 63 6f 75 6e 74 65 64 20  mns are counted 
6f90: 77 68 65 6e 20 64 65 74 65 72 6d 69 6e 69 6e 67  when determining
6fa0: 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 6e 64 65   the column inde
6fb0: 78 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  x...        /// 
6fc0: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
6fd0: 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20   /// <para>..   
6fe0: 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 61 43 6f       /// The aCo
6ff0: 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79  nstraint[] array
7000: 20 63 6f 6e 74 61 69 6e 73 20 69 6e 66 6f 72 6d   contains inform
7010: 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 6c 6c 20  ation about all 
7020: 63 6f 6e 73 74 72 61 69 6e 74 73 20 0d 0a 20 20  constraints ..  
7030: 20 20 20 20 20 20 2f 2f 2f 20 74 68 61 74 20 61        /// that a
7040: 70 70 6c 79 20 74 6f 20 74 68 65 20 76 69 72 74  pply to the virt
7050: 75 61 6c 20 74 61 62 6c 65 2e 20 42 75 74 20 73  ual table. But s
7060: 6f 6d 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74  ome of the const
7070: 72 61 69 6e 74 73 20 6d 69 67 68 74 0d 0a 20 20  raints might..  
7080: 20 20 20 20 20 20 2f 2f 2f 20 6e 6f 74 20 62 65        /// not be
7090: 20 75 73 61 62 6c 65 20 62 65 63 61 75 73 65 20   usable because 
70a0: 6f 66 20 74 68 65 20 77 61 79 20 74 61 62 6c 65  of the way table
70b0: 73 20 61 72 65 20 6f 72 64 65 72 65 64 20 69 6e  s are ordered in
70c0: 20 61 20 6a 6f 69 6e 2e 20 0d 0a 20 20 20 20 20   a join. ..     
70d0: 20 20 20 2f 2f 2f 20 54 68 65 20 78 42 65 73 74     /// The xBest
70e0: 49 6e 64 65 78 20 6d 65 74 68 6f 64 20 6d 75 73  Index method mus
70f0: 74 20 74 68 65 72 65 66 6f 72 65 20 6f 6e 6c 79  t therefore only
7100: 20 63 6f 6e 73 69 64 65 72 20 63 6f 6e 73 74 72   consider constr
7110: 61 69 6e 74 73 20 0d 0a 20 20 20 20 20 20 20 20  aints ..        
7120: 2f 2f 2f 20 74 68 61 74 20 68 61 76 65 20 61 6e  /// that have an
7130: 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75   aConstraint[].u
7140: 73 61 62 6c 65 20 66 6c 61 67 20 77 68 69 63 68  sable flag which
7150: 20 69 73 20 74 72 75 65 2e 0d 0a 20 20 20 20 20   is true...     
7160: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a     /// </para>..
7170: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
7180: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
7190: 49 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 57  In addition to W
71a0: 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73  HERE clause cons
71b0: 74 72 61 69 6e 74 73 2c 20 74 68 65 20 53 51 4c  traints, the SQL
71c0: 69 74 65 20 63 6f 72 65 20 61 6c 73 6f 20 0d 0a  ite core also ..
71d0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 65 6c 6c          /// tell
71e0: 73 20 74 68 65 20 78 42 65 73 74 49 6e 64 65 78  s the xBestIndex
71f0: 20 6d 65 74 68 6f 64 20 61 62 6f 75 74 20 74 68   method about th
7200: 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
7210: 65 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  e. ..        ///
7220: 20 28 49 6e 20 61 6e 20 61 67 67 72 65 67 61 74   (In an aggregat
7230: 65 20 71 75 65 72 79 2c 20 74 68 65 20 53 51 4c  e query, the SQL
7240: 69 74 65 20 63 6f 72 65 20 6d 69 67 68 74 20 70  ite core might p
7250: 75 74 20 69 6e 20 47 52 4f 55 50 20 42 59 20 63  ut in GROUP BY c
7260: 6c 61 75 73 65 20 0d 0a 20 20 20 20 20 20 20 20  lause ..        
7270: 2f 2f 2f 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  /// information 
7280: 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
7290: 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20  ORDER BY clause 
72a0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c 20 62 75 74  information, but
72b0: 20 74 68 69 73 20 66 61 63 74 0d 0a 20 20 20 20   this fact..    
72c0: 20 20 20 20 2f 2f 2f 20 73 68 6f 75 6c 64 20 6e      /// should n
72d0: 6f 74 20 6d 61 6b 65 20 61 6e 79 20 64 69 66 66  ot make any diff
72e0: 65 72 65 6e 63 65 20 74 6f 20 74 68 65 20 78 42  erence to the xB
72f0: 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64 2e  estIndex method.
7300: 29 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ) ..        /// 
7310: 49 66 20 61 6c 6c 20 74 65 72 6d 73 20 6f 66 20  If all terms of 
7320: 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  the ORDER BY cla
7330: 75 73 65 20 61 72 65 20 63 6f 6c 75 6d 6e 73 20  use are columns 
7340: 69 6e 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  in the virtual t
7350: 61 62 6c 65 2c 20 0d 0a 20 20 20 20 20 20 20 20  able, ..        
7360: 2f 2f 2f 20 74 68 65 6e 20 6e 4f 72 64 65 72 42  /// then nOrderB
7370: 79 20 77 69 6c 6c 20 62 65 20 74 68 65 20 6e 75  y will be the nu
7380: 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
7390: 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
73a0: 61 75 73 65 20 0d 0a 20 20 20 20 20 20 20 20 2f  ause ..        /
73b0: 2f 2f 20 61 6e 64 20 74 68 65 20 61 4f 72 64 65  // and the aOrde
73c0: 72 42 79 5b 5d 20 61 72 72 61 79 20 77 69 6c 6c  rBy[] array will
73d0: 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 63 6f   identify the co
73e0: 6c 75 6d 6e 20 66 6f 72 20 65 61 63 68 20 74 65  lumn for each te
73f0: 72 6d 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  rm ..        ///
7400: 20 69 6e 20 74 68 65 20 6f 72 64 65 72 20 62 79   in the order by
7410: 20 63 6c 61 75 73 65 20 61 6e 64 20 77 68 65 74   clause and whet
7420: 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 61 74 20  her or not that 
7430: 63 6f 6c 75 6d 6e 20 69 73 20 41 53 43 20 6f 72  column is ASC or
7440: 20 44 45 53 43 2e 0d 0a 20 20 20 20 20 20 20 20   DESC...        
7450: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
7460: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
7470: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 49 6e 20  .        /// In 
7480: 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
7490: 2e 31 30 2e 30 20 28 32 30 31 36 2d 30 31 2d 30  .10.0 (2016-01-0
74a0: 36 29 20 61 6e 64 20 6c 61 74 65 72 2c 20 0d 0a  6) and later, ..
74b0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 20          /// the 
74c0: 63 6f 6c 55 73 65 64 20 66 69 65 6c 64 20 69 73  colUsed field is
74d0: 20 61 76 61 69 6c 61 62 6c 65 0d 0a 20 20 20 20   available..    
74e0: 20 20 20 20 2f 2f 2f 20 74 6f 20 69 6e 64 69 63      /// to indic
74f0: 61 74 65 20 77 68 69 63 68 20 66 69 65 6c 64 73  ate which fields
7500: 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20   of the virtual 
7510: 74 61 62 6c 65 20 61 72 65 20 61 63 74 75 61 6c  table are actual
7520: 6c 79 20 75 73 65 64 20 62 79 20 74 68 65 0d 0a  ly used by the..
7530: 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 74 61 74          /// stat
7540: 65 6d 65 6e 74 20 62 65 69 6e 67 20 70 72 65 70  ement being prep
7550: 61 72 65 64 2e 20 20 49 66 20 74 68 65 20 6c 6f  ared.  If the lo
7560: 77 65 73 74 20 62 69 74 20 6f 66 20 63 6f 6c 55  west bit of colU
7570: 73 65 64 20 69 73 20 73 65 74 2c 20 74 68 61 74  sed is set, that
7580: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6d 65  ..        /// me
7590: 61 6e 73 20 74 68 61 74 20 74 68 65 20 66 69 72  ans that the fir
75a0: 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 75 73 65  st column is use
75b0: 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 6c  d.  The second l
75c0: 6f 77 65 73 74 20 62 69 74 20 63 6f 72 72 65 73  owest bit corres
75d0: 70 6f 6e 64 73 0d 0a 20 20 20 20 20 20 20 20 2f  ponds..        /
75e0: 2f 2f 20 74 6f 20 74 68 65 20 73 65 63 6f 6e 64  // to the second
75f0: 20 63 6f 6c 75 6d 6e 2e 20 20 41 6e 64 20 73 6f   column.  And so
7600: 20 66 6f 72 74 68 2e 20 20 49 66 20 74 68 65 20   forth.  If the 
7610: 6d 6f 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74  most significant
7620: 20 62 69 74 20 6f 66 0d 0a 20 20 20 20 20 20 20   bit of..       
7630: 20 2f 2f 2f 20 63 6f 6c 55 73 65 64 20 69 73 20   /// colUsed is 
7640: 73 65 74 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  set, that means 
7650: 74 68 61 74 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  that one or more
7660: 20 63 6f 6c 75 6d 6e 73 20 6f 74 68 65 72 20 74   columns other t
7670: 68 61 6e 20 74 68 65 20 0d 0a 20 20 20 20 20 20  han the ..      
7680: 20 20 2f 2f 2f 20 66 69 72 73 74 20 36 33 20 63    /// first 63 c
7690: 6f 6c 75 6d 6e 73 20 61 72 65 20 75 73 65 64 2e  olumns are used.
76a0: 20 20 49 66 20 63 6f 6c 75 6d 6e 20 75 73 61 67    If column usag
76b0: 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  e information is
76c0: 20 6e 65 65 64 65 64 20 62 79 20 74 68 65 0d 0a   needed by the..
76d0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 78 46 69 6c          /// xFil
76e0: 74 65 72 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e  ter method, then
76f0: 20 74 68 65 20 72 65 71 75 69 72 65 64 20 62 69   the required bi
7700: 74 73 20 6d 75 73 74 20 62 65 20 65 6e 63 6f 64  ts must be encod
7710: 65 64 20 69 6e 74 6f 20 65 69 74 68 65 72 0d 0a  ed into either..
7720: 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 20          /// the 
7730: 69 64 78 4e 75 6d 20 6f 72 20 69 64 78 53 74 72  idxNum or idxStr
7740: 20 6f 75 74 70 75 74 20 66 69 65 6c 64 73 2e 0d   output fields..
7750: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
7760: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
7770: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
7780: 20 20 2f 2f 2f 20 47 69 76 65 6e 20 61 6c 6c 20    /// Given all 
7790: 6f 66 20 74 68 65 20 69 6e 66 6f 72 6d 61 74 69  of the informati
77a0: 6f 6e 20 61 62 6f 76 65 2c 20 74 68 65 20 6a 6f  on above, the jo
77b0: 62 20 6f 66 20 74 68 65 20 78 42 65 73 74 49 6e  b of the xBestIn
77c0: 64 65 78 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  dex ..        //
77d0: 2f 20 6d 65 74 68 6f 64 20 69 74 20 74 6f 20 66  / method it to f
77e0: 69 67 75 72 65 20 6f 75 74 20 74 68 65 20 62 65  igure out the be
77f0: 73 74 20 77 61 79 20 74 6f 20 73 65 61 72 63 68  st way to search
7800: 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
7810: 6c 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  le...        ///
7820: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
7830: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
7840: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 42        /// The xB
7850: 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64 20  estIndex method 
7860: 66 69 6c 6c 73 20 74 68 65 20 69 64 78 4e 75 6d  fills the idxNum
7870: 20 61 6e 64 20 69 64 78 53 74 72 20 66 69 65 6c   and idxStr fiel
7880: 64 73 20 77 69 74 68 20 0d 0a 20 20 20 20 20 20  ds with ..      
7890: 20 20 2f 2f 2f 20 69 6e 66 6f 72 6d 61 74 69 6f    /// informatio
78a0: 6e 20 74 68 61 74 20 63 6f 6d 6d 75 6e 69 63 61  n that communica
78b0: 74 65 73 20 61 6e 20 69 6e 64 65 78 69 6e 67 20  tes an indexing 
78c0: 73 74 72 61 74 65 67 79 20 74 6f 20 74 68 65 20  strategy to the 
78d0: 78 46 69 6c 74 65 72 20 0d 0a 20 20 20 20 20 20  xFilter ..      
78e0: 20 20 2f 2f 2f 20 6d 65 74 68 6f 64 2e 20 54 68    /// method. Th
78f0: 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e  e information in
7900: 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 53   idxNum and idxS
7910: 74 72 20 69 73 20 61 72 62 69 74 72 61 72 79 20  tr is arbitrary 
7920: 61 73 20 66 61 72 20 0d 0a 20 20 20 20 20 20 20  as far ..       
7930: 20 2f 2f 2f 20 61 73 20 74 68 65 20 53 51 4c 69   /// as the SQLi
7940: 74 65 20 63 6f 72 65 20 69 73 20 63 6f 6e 63 65  te core is conce
7950: 72 6e 65 64 2e 20 54 68 65 20 53 51 4c 69 74 65  rned. The SQLite
7960: 20 63 6f 72 65 20 6a 75 73 74 20 63 6f 70 69 65   core just copie
7970: 73 20 74 68 65 20 0d 0a 20 20 20 20 20 20 20 20  s the ..        
7980: 2f 2f 2f 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  /// information 
7990: 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 78  through to the x
79a0: 46 69 6c 74 65 72 20 6d 65 74 68 6f 64 2e 20 41  Filter method. A
79b0: 6e 79 20 64 65 73 69 72 65 64 20 6d 65 61 6e 69  ny desired meani
79c0: 6e 67 20 63 61 6e 20 0d 0a 20 20 20 20 20 20 20  ng can ..       
79d0: 20 2f 2f 2f 20 62 65 20 61 73 73 69 67 6e 65 64   /// be assigned
79e0: 20 74 6f 20 69 64 78 4e 75 6d 20 61 6e 64 20 69   to idxNum and i
79f0: 64 78 53 74 72 20 61 73 20 6c 6f 6e 67 20 61 73  dxStr as long as
7a00: 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64 20   xBestIndex and 
7a10: 78 46 69 6c 74 65 72 20 0d 0a 20 20 20 20 20 20  xFilter ..      
7a20: 20 20 2f 2f 2f 20 61 67 72 65 65 20 6f 6e 20 77    /// agree on w
7a30: 68 61 74 20 74 68 61 74 20 6d 65 61 6e 69 6e 67  hat that meaning
7a40: 20 69 73 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f   is...        //
7a50: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  / </para>..     
7a60: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20     /// <para>.. 
7a70: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 69         /// The i
7a80: 64 78 53 74 72 20 76 61 6c 75 65 20 6d 61 79 20  dxStr value may 
7a90: 62 65 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61  be a string obta
7aa0: 69 6e 65 64 20 66 72 6f 6d 20 61 6e 20 53 51 4c  ined from an SQL
7ab0: 69 74 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ite..        ///
7ac0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
7ad0: 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 73 75 63 68  on function such
7ae0: 20 61 73 20 73 71 6c 69 74 65 33 5f 6d 70 72 69   as sqlite3_mpri
7af0: 6e 74 66 28 29 2e 20 0d 0a 20 20 20 20 20 20 20  ntf(). ..       
7b00: 20 2f 2f 2f 20 49 66 20 74 68 69 73 20 69 73 20   /// If this is 
7b10: 74 68 65 20 63 61 73 65 2c 20 74 68 65 6e 20 74  the case, then t
7b20: 68 65 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78  he needToFreeIdx
7b30: 53 74 72 20 66 6c 61 67 20 6d 75 73 74 20 62 65  Str flag must be
7b40: 20 73 65 74 20 74 6f 20 0d 0a 20 20 20 20 20 20   set to ..      
7b50: 20 20 2f 2f 2f 20 74 72 75 65 20 73 6f 20 74 68    /// true so th
7b60: 61 74 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  at the SQLite co
7b70: 72 65 20 77 69 6c 6c 20 6b 6e 6f 77 20 74 6f 20  re will know to 
7b80: 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 66 72 65  call sqlite3_fre
7b90: 65 28 29 20 6f 6e 20 0d 0a 20 20 20 20 20 20 20  e() on ..       
7ba0: 20 2f 2f 2f 20 74 68 61 74 20 73 74 72 69 6e 67   /// that string
7bb0: 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e   when it has fin
7bc0: 69 73 68 65 64 20 77 69 74 68 20 69 74 2c 20 61  ished with it, a
7bd0: 6e 64 20 74 68 75 73 20 61 76 6f 69 64 20 61 20  nd thus avoid a 
7be0: 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0d 0a 20 20  memory leak...  
7bf0: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61        /// </para
7c00: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
7c10: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
7c20: 2f 2f 20 49 66 20 74 68 65 20 76 69 72 74 75 61  // If the virtua
7c30: 6c 20 74 61 62 6c 65 20 77 69 6c 6c 20 6f 75 74  l table will out
7c40: 70 75 74 20 72 6f 77 73 20 69 6e 20 74 68 65 20  put rows in the 
7c50: 6f 72 64 65 72 20 73 70 65 63 69 66 69 65 64 20  order specified 
7c60: 62 79 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  by ..        ///
7c70: 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
7c80: 61 75 73 65 2c 20 74 68 65 6e 20 74 68 65 20 6f  ause, then the o
7c90: 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 20 66  rderByConsumed f
7ca0: 6c 61 67 20 6d 61 79 20 62 65 20 73 65 74 20 74  lag may be set t
7cb0: 6f 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  o ..        /// 
7cc0: 74 72 75 65 2e 20 49 66 20 74 68 65 20 6f 75 74  true. If the out
7cd0: 70 75 74 20 69 73 20 6e 6f 74 20 61 75 74 6f 6d  put is not autom
7ce0: 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 65 20  atically in the 
7cf0: 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20 0d 0a  correct order ..
7d00: 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 6e          /// then
7d10: 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64   orderByConsumed
7d20: 20 6d 75 73 74 20 62 65 20 6c 65 66 74 20 69 6e   must be left in
7d30: 20 69 74 73 20 64 65 66 61 75 6c 74 20 66 61 6c   its default fal
7d40: 73 65 20 73 65 74 74 69 6e 67 2e 20 0d 0a 20 20  se setting. ..  
7d50: 20 20 20 20 20 20 2f 2f 2f 20 54 68 69 73 20 77        /// This w
7d60: 69 6c 6c 20 69 6e 64 69 63 61 74 65 20 74 6f 20  ill indicate to 
7d70: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  the SQLite core 
7d80: 74 68 61 74 20 69 74 20 77 69 6c 6c 20 6e 65 65  that it will nee
7d90: 64 20 74 6f 20 64 6f 20 61 20 0d 0a 20 20 20 20  d to do a ..    
7da0: 20 20 20 20 2f 2f 2f 20 73 65 70 61 72 61 74 65      /// separate
7db0: 20 73 6f 72 74 69 6e 67 20 70 61 73 73 20 6f 76   sorting pass ov
7dc0: 65 72 20 74 68 65 20 64 61 74 61 20 61 66 74 65  er the data afte
7dd0: 72 20 69 74 20 63 6f 6d 65 73 20 6f 75 74 20 6f  r it comes out o
7de0: 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  f the virtual ta
7df0: 62 6c 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ble...        //
7e00: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  / </para>..     
7e10: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20     /// <para>.. 
7e20: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 65         /// The e
7e30: 73 74 69 6d 61 74 65 64 43 6f 73 74 20 66 69 65  stimatedCost fie
7e40: 6c 64 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74  ld should be set
7e50: 20 74 6f 20 74 68 65 20 65 73 74 69 6d 61 74 65   to the estimate
7e60: 64 20 6e 75 6d 62 65 72 0d 0a 20 20 20 20 20 20  d number..      
7e70: 20 20 2f 2f 2f 20 6f 66 20 64 69 73 6b 20 61 63    /// of disk ac
7e80: 63 65 73 73 20 6f 70 65 72 61 74 69 6f 6e 73 20  cess operations 
7e90: 72 65 71 75 69 72 65 64 20 74 6f 20 65 78 65 63  required to exec
7ea0: 75 74 65 20 74 68 69 73 20 71 75 65 72 79 20 61  ute this query a
7eb0: 67 61 69 6e 73 74 20 0d 0a 20 20 20 20 20 20 20  gainst ..       
7ec0: 20 2f 2f 2f 20 74 68 65 20 76 69 72 74 75 61 6c   /// the virtual
7ed0: 20 74 61 62 6c 65 2e 20 54 68 65 20 53 51 4c 69   table. The SQLi
7ee0: 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6f 66 74  te core will oft
7ef0: 65 6e 20 63 61 6c 6c 20 78 42 65 73 74 49 6e 64  en call xBestInd
7f00: 65 78 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ex ..        ///
7f10: 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
7f20: 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 63  with different c
7f30: 6f 6e 73 74 72 61 69 6e 74 73 2c 20 6f 62 74 61  onstraints, obta
7f40: 69 6e 20 6d 75 6c 74 69 70 6c 65 20 63 6f 73 74  in multiple cost
7f50: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 65 73  ..        /// es
7f60: 74 69 6d 61 74 65 73 2c 20 74 68 65 6e 20 63 68  timates, then ch
7f70: 6f 6f 73 65 20 74 68 65 20 71 75 65 72 79 20 70  oose the query p
7f80: 6c 61 6e 20 74 68 61 74 20 67 69 76 65 73 20 74  lan that gives t
7f90: 68 65 20 6c 6f 77 65 73 74 20 65 73 74 69 6d 61  he lowest estima
7fa0: 74 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  te...        ///
7fb0: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
7fc0: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
7fd0: 20 20 20 20 20 20 2f 2f 2f 20 49 66 20 74 68 65        /// If the
7fe0: 20 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f 6e   current version
7ff0: 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 33 2e   of SQLite is 3.
8000: 38 2e 32 20 6f 72 20 67 72 65 61 74 65 72 2c 20  8.2 or greater, 
8010: 74 68 65 20 65 73 74 69 6d 61 74 65 64 52 6f 77  the estimatedRow
8020: 73 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 66  s..        /// f
8030: 69 65 6c 64 20 6d 61 79 20 62 65 20 73 65 74 20  ield may be set 
8040: 74 6f 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  to an estimate o
8050: 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  f the number of 
8060: 72 6f 77 73 20 72 65 74 75 72 6e 65 64 20 62 79  rows returned by
8070: 20 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f   the..        //
8080: 2f 20 70 72 6f 70 6f 73 65 64 20 71 75 65 72 79  / proposed query
8090: 20 70 6c 61 6e 2e 20 49 66 20 74 68 69 73 20 76   plan. If this v
80a0: 61 6c 75 65 20 69 73 20 6e 6f 74 20 65 78 70 6c  alue is not expl
80b0: 69 63 69 74 6c 79 20 73 65 74 2c 20 74 68 65 20  icitly set, the 
80c0: 64 65 66 61 75 6c 74 20 0d 0a 20 20 20 20 20 20  default ..      
80d0: 20 20 2f 2f 2f 20 65 73 74 69 6d 61 74 65 20 6f    /// estimate o
80e0: 66 20 32 35 20 72 6f 77 73 20 69 73 20 75 73 65  f 25 rows is use
80f0: 64 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  d...        /// 
8100: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
8110: 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20   /// <para>..   
8120: 20 20 20 20 20 2f 2f 2f 20 49 66 20 74 68 65 20       /// If the 
8130: 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f 6e 20  current version 
8140: 6f 66 20 53 51 4c 69 74 65 20 69 73 20 33 2e 39  of SQLite is 3.9
8150: 2e 30 20 6f 72 20 67 72 65 61 74 65 72 2c 20 74  .0 or greater, t
8160: 68 65 20 69 64 78 46 6c 61 67 73 20 66 69 65 6c  he idxFlags fiel
8170: 64 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6d  d..        /// m
8180: 61 79 20 62 65 20 73 65 74 20 74 6f 20 53 51 4c  ay be set to SQL
8190: 49 54 45 5f 49 4e 44 45 58 5f 53 43 41 4e 5f 55  ITE_INDEX_SCAN_U
81a0: 4e 49 51 55 45 20 74 6f 20 69 6e 64 69 63 61 74  NIQUE to indicat
81b0: 65 20 74 68 61 74 20 74 68 65 20 76 69 72 74 75  e that the virtu
81c0: 61 6c 20 74 61 62 6c 65 0d 0a 20 20 20 20 20 20  al table..      
81d0: 20 20 2f 2f 2f 20 77 69 6c 6c 20 72 65 74 75 72    /// will retur
81e0: 6e 20 6f 6e 6c 79 20 7a 65 72 6f 20 6f 72 20 6f  n only zero or o
81f0: 6e 65 20 72 6f 77 73 20 67 69 76 65 6e 20 74 68  ne rows given th
8200: 65 20 69 6e 70 75 74 20 63 6f 6e 73 74 72 61 69  e input constrai
8210: 6e 74 73 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  nts.  Additional
8220: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 62 69  ..        /// bi
8230: 74 73 20 6f 66 20 74 68 65 20 69 64 78 46 6c 61  ts of the idxFla
8240: 67 73 20 66 69 65 6c 64 20 6d 69 67 68 74 20 62  gs field might b
8250: 65 20 75 6e 64 65 72 73 74 6f 6f 64 20 69 6e 20  e understood in 
8260: 6c 61 74 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  later versions o
8270: 66 20 53 51 4c 69 74 65 2e 0d 0a 20 20 20 20 20  f SQLite...     
8280: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a     /// </para>..
8290: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
82a0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
82b0: 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 55  The aConstraintU
82c0: 73 61 67 65 5b 5d 20 61 72 72 61 79 20 63 6f 6e  sage[] array con
82d0: 74 61 69 6e 73 20 6f 6e 65 20 65 6c 65 6d 65 6e  tains one elemen
82e0: 74 20 66 6f 72 20 65 61 63 68 20 6f 66 20 0d 0a  t for each of ..
82f0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 20          /// the 
8300: 6e 43 6f 6e 73 74 72 61 69 6e 74 20 63 6f 6e 73  nConstraint cons
8310: 74 72 61 69 6e 74 73 20 69 6e 20 74 68 65 20 69  traints in the i
8320: 6e 70 75 74 73 20 73 65 63 74 69 6f 6e 20 6f 66  nputs section of
8330: 20 74 68 65 20 0d 0a 20 20 20 20 20 20 20 20 2f   the ..        /
8340: 2f 2f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  // sqlite3_index
8350: 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65 2e  _info structure.
8360: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54   ..        /// T
8370: 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73  he aConstraintUs
8380: 61 67 65 5b 5d 20 61 72 72 61 79 20 69 73 20 75  age[] array is u
8390: 73 65 64 20 62 79 20 78 42 65 73 74 49 6e 64 65  sed by xBestInde
83a0: 78 20 74 6f 20 74 65 6c 6c 20 74 68 65 20 0d 0a  x to tell the ..
83b0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 63 6f 72 65          /// core
83c0: 20 68 6f 77 20 69 74 20 69 73 20 75 73 69 6e 67   how it is using
83d0: 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 73   the constraints
83e0: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
83f0: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
8400: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20  /// <para>..    
8410: 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 42 65 73      /// The xBes
8420: 74 49 6e 64 65 78 20 6d 65 74 68 6f 64 20 6d 61  tIndex method ma
8430: 79 20 73 65 74 20 61 43 6f 6e 73 74 72 61 69 6e  y set aConstrain
8440: 74 55 73 61 67 65 5b 5d 2e 61 72 67 76 49 6e 64  tUsage[].argvInd
8450: 65 78 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ex ..        ///
8460: 20 65 6e 74 72 69 65 73 20 74 6f 20 76 61 6c 75   entries to valu
8470: 65 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  es greater than 
8480: 7a 65 72 6f 2e 20 0d 0a 20 20 20 20 20 20 20 20  zero. ..        
8490: 2f 2f 2f 20 45 78 61 63 74 6c 79 20 6f 6e 65 20  /// Exactly one 
84a0: 65 6e 74 72 79 20 73 68 6f 75 6c 64 20 62 65 20  entry should be 
84b0: 73 65 74 20 74 6f 20 31 2c 20 61 6e 6f 74 68 65  set to 1, anothe
84c0: 72 20 74 6f 20 32 2c 20 61 6e 6f 74 68 65 72 20  r to 2, another 
84d0: 74 6f 20 33 2c 20 0d 0a 20 20 20 20 20 20 20 20  to 3, ..        
84e0: 2f 2f 2f 20 61 6e 64 20 73 6f 20 66 6f 72 74 68  /// and so forth
84f0: 20 75 70 20 74 6f 20 61 73 20 6d 61 6e 79 20 6f   up to as many o
8500: 72 20 61 73 20 66 65 77 20 61 73 20 74 68 65 20  r as few as the 
8510: 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f  xBestIndex metho
8520: 64 20 77 61 6e 74 73 2e 20 0d 0a 20 20 20 20 20  d wants. ..     
8530: 20 20 20 2f 2f 2f 20 54 68 65 20 45 58 50 52 20     /// The EXPR 
8540: 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  of the correspon
8550: 64 69 6e 67 20 63 6f 6e 73 74 72 61 69 6e 74 73  ding constraints
8560: 20 77 69 6c 6c 20 74 68 65 6e 20 62 65 20 70 61   will then be pa
8570: 73 73 65 64 20 0d 0a 20 20 20 20 20 20 20 20 2f  ssed ..        /
8580: 2f 2f 20 69 6e 20 61 73 20 74 68 65 20 61 72 67  // in as the arg
8590: 76 5b 5d 20 70 61 72 61 6d 65 74 65 72 73 20 74  v[] parameters t
85a0: 6f 20 78 46 69 6c 74 65 72 2e 0d 0a 20 20 20 20  o xFilter...    
85b0: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
85c0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
85d0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
85e0: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66   For example, if
85f0: 20 74 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74   the aConstraint
8600: 5b 33 5d 2e 61 72 67 76 49 6e 64 65 78 20 69 73  [3].argvIndex is
8610: 20 73 65 74 20 74 6f 20 31 2c 20 74 68 65 6e 20   set to 1, then 
8620: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 77 68  ..        /// wh
8630: 65 6e 20 78 46 69 6c 74 65 72 20 69 73 20 63 61  en xFilter is ca
8640: 6c 6c 65 64 2c 20 74 68 65 20 61 72 67 76 5b 30  lled, the argv[0
8650: 5d 20 70 61 73 73 65 64 20 74 6f 20 78 46 69 6c  ] passed to xFil
8660: 74 65 72 20 77 69 6c 6c 20 68 61 76 65 20 0d 0a  ter will have ..
8670: 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 20          /// the 
8680: 45 58 50 52 20 76 61 6c 75 65 20 6f 66 20 74 68  EXPR value of th
8690: 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 33 5d  e aConstraint[3]
86a0: 20 63 6f 6e 73 74 72 61 69 6e 74 2e 0d 0a 20 20   constraint...  
86b0: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61        /// </para
86c0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
86d0: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
86e0: 2f 2f 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  // By default, t
86f0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 64  he SQLite core d
8700: 6f 75 62 6c 65 20 63 68 65 63 6b 73 20 61 6c 6c  ouble checks all
8710: 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 6f 6e 20   constraints on 
8720: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 65 61  ..        /// ea
8730: 63 68 20 72 6f 77 20 6f 66 20 74 68 65 20 76 69  ch row of the vi
8740: 72 74 75 61 6c 20 74 61 62 6c 65 20 74 68 61 74  rtual table that
8750: 20 69 74 20 72 65 63 65 69 76 65 73 2e 20 49 66   it receives. If
8760: 20 73 75 63 68 20 61 20 63 68 65 63 6b 20 0d 0a   such a check ..
8770: 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 73 20 72          /// is r
8780: 65 64 75 6e 64 61 6e 74 2c 20 74 68 65 20 78 42  edundant, the xB
8790: 65 73 74 46 69 6c 74 65 72 20 6d 65 74 68 6f 64  estFilter method
87a0: 20 63 61 6e 20 73 75 70 70 72 65 73 73 20 74 68   can suppress th
87b0: 61 74 20 64 6f 75 62 6c 65 2d 63 68 65 63 6b 20  at double-check 
87c0: 62 79 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  by ..        ///
87d0: 20 73 65 74 74 69 6e 67 20 61 43 6f 6e 73 74 72   setting aConstr
87e0: 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d 69 74  aintUsage[].omit
87f0: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
8800: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
8810: 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a  /// </summary>..
8820: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
8830: 61 6d 20 6e 61 6d 65 3d 22 70 56 74 61 62 22 3e  am name="pVtab">
8840: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
8850: 65 20 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72  e native pointer
8860: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
8870: 76 74 61 62 20 64 65 72 69 76 65 64 20 73 74 72  vtab derived str
8880: 75 63 74 75 72 65 2e 0d 0a 20 20 20 20 20 20 20  ucture...       
8890: 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20   /// </param>.. 
88a0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
88b0: 6d 20 6e 61 6d 65 3d 22 70 49 6e 64 65 78 22 3e  m name="pIndex">
88c0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
88d0: 65 20 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72  e native pointer
88e0: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
88f0: 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63  index_info struc
8900: 74 75 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f  ture...        /
8910: 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20  // </param>..   
8920: 20 20 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72 6e       /// <return
8930: 73 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  s>..        /// 
8940: 41 20 73 74 61 6e 64 61 72 64 20 53 51 4c 69 74  A standard SQLit
8950: 65 20 72 65 74 75 72 6e 20 63 6f 64 65 2e 0d 0a  e return code...
8960: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72 65          /// </re
8970: 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20  turns>..        
8980: 53 51 4c 69 74 65 45 72 72 6f 72 43 6f 64 65 20  SQLiteErrorCode 
8990: 78 42 65 73 74 49 6e 64 65 78 28 0d 0a 20 20 20  xBestIndex(..   
89a0: 20 20 20 20 20 20 20 20 20 49 6e 74 50 74 72 20           IntPtr 
89b0: 70 56 74 61 62 2c 0d 0a 20 20 20 20 20 20 20 20  pVtab,..        
89c0: 20 20 20 20 49 6e 74 50 74 72 20 70 49 6e 64 65      IntPtr pInde
89d0: 78 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 29  x..            )
89e0: 3b 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ;....        ///
89f0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8a00: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8a10: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8a20: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8a30: 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 20 20 20 20  ////....        
8a40: 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20  /// <summary>.. 
8a50: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
8a60: 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20  ><code>..       
8a70: 20 2f 2f 2f 20 69 6e 74 20 28 2a 78 44 69 73 63   /// int (*xDisc
8a80: 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 5f  onnect)(sqlite3_
8a90: 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0d 0a 20  vtab *pVTab);.. 
8aa0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64         /// </cod
8ab0: 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  e></para>..     
8ac0: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20     /// <para>.. 
8ad0: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 69 73 20         /// This 
8ae0: 6d 65 74 68 6f 64 20 72 65 6c 65 61 73 65 73 20  method releases 
8af0: 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  a connection to 
8b00: 61 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e  a virtual table.
8b10: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 4f   ..        /// O
8b20: 6e 6c 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f  nly the sqlite3_
8b30: 76 74 61 62 20 6f 62 6a 65 63 74 20 69 73 20 64  vtab object is d
8b40: 65 73 74 72 6f 79 65 64 2e 0d 0a 20 20 20 20 20  estroyed...     
8b50: 20 20 20 2f 2f 2f 20 54 68 65 20 76 69 72 74 75     /// The virtu
8b60: 61 6c 20 74 61 62 6c 65 20 69 73 20 6e 6f 74 20  al table is not 
8b70: 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6e  destroyed and an
8b80: 79 20 62 61 63 6b 69 6e 67 20 73 74 6f 72 65 20  y backing store 
8b90: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 61 73  ..        /// as
8ba0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
8bb0: 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  e virtual table 
8bc0: 70 65 72 73 69 73 74 73 2e 20 0d 0a 20 20 20 20  persists. ..    
8bd0: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
8be0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 69  .        /// Thi
8bf0: 73 20 6d 65 74 68 6f 64 20 75 6e 64 6f 65 73 20  s method undoes 
8c00: 74 68 65 20 77 6f 72 6b 20 6f 66 20 78 43 6f 6e  the work of xCon
8c10: 6e 65 63 74 2e 0d 0a 20 20 20 20 20 20 20 20 2f  nect...        /
8c20: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20  // <para>..     
8c30: 20 20 20 2f 2f 2f 20 54 68 69 73 20 6d 65 74 68     /// This meth
8c40: 6f 64 20 69 73 20 61 20 64 65 73 74 72 75 63 74  od is a destruct
8c50: 6f 72 20 66 6f 72 20 61 20 63 6f 6e 6e 65 63 74  or for a connect
8c60: 69 6f 6e 20 74 6f 20 74 68 65 20 76 69 72 74 75  ion to the virtu
8c70: 61 6c 20 74 61 62 6c 65 2e 0d 0a 20 20 20 20 20  al table...     
8c80: 20 20 20 2f 2f 2f 20 43 6f 6e 74 72 61 73 74 20     /// Contrast 
8c90: 74 68 69 73 20 6d 65 74 68 6f 64 20 77 69 74 68  this method with
8ca0: 20 78 44 65 73 74 72 6f 79 2e 20 20 54 68 65 20   xDestroy.  The 
8cb0: 78 44 65 73 74 72 6f 79 20 69 73 20 61 20 64 65  xDestroy is a de
8cc0: 73 74 72 75 63 74 6f 72 0d 0a 20 20 20 20 20 20  structor..      
8cd0: 20 20 2f 2f 2f 20 66 6f 72 20 74 68 65 20 65 6e    /// for the en
8ce0: 74 69 72 65 20 76 69 72 74 75 61 6c 20 74 61 62  tire virtual tab
8cf0: 6c 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  le...        ///
8d00: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
8d10: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
8d20: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 44        /// The xD
8d30: 69 73 63 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64  isconnect method
8d40: 20 69 73 20 72 65 71 75 69 72 65 64 20 66 6f 72   is required for
8d50: 20 65 76 65 72 79 20 76 69 72 74 75 61 6c 20 74   every virtual t
8d60: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
8d70: 69 6f 6e 2c 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ion,..        //
8d80: 2f 20 74 68 6f 75 67 68 20 69 74 20 69 73 20 61  / though it is a
8d90: 63 63 65 70 74 61 62 6c 65 20 66 6f 72 20 74 68  cceptable for th
8da0: 65 20 78 44 69 73 63 6f 6e 6e 65 63 74 20 61 6e  e xDisconnect an
8db0: 64 20 78 44 65 73 74 72 6f 79 20 6d 65 74 68 6f  d xDestroy metho
8dc0: 64 73 20 74 6f 20 62 65 0d 0a 20 20 20 20 20 20  ds to be..      
8dd0: 20 20 2f 2f 2f 20 74 68 65 20 73 61 6d 65 20 66    /// the same f
8de0: 75 6e 63 74 69 6f 6e 20 69 66 20 74 68 61 74 20  unction if that 
8df0: 6d 61 6b 65 73 20 73 65 6e 73 65 20 66 6f 72 20  makes sense for 
8e00: 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 76  the particular v
8e10: 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 0d 0a 20  irtual table... 
8e20: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
8e30: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
8e40: 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20  </summary>..    
8e50: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e      /// <param n
8e60: 61 6d 65 3d 22 70 56 74 61 62 22 3e 0d 0a 20 20  ame="pVtab">..  
8e70: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e 61        /// The na
8e80: 74 69 76 65 20 70 6f 69 6e 74 65 72 20 74 6f 20  tive pointer to 
8e90: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 74 61 62  the sqlite3_vtab
8ea0: 20 64 65 72 69 76 65 64 20 73 74 72 75 63 74 75   derived structu
8eb0: 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  re...        ///
8ec0: 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20   </param>..     
8ed0: 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72 6e 73 3e     /// <returns>
8ee0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 20  ..        /// A 
8ef0: 73 74 61 6e 64 61 72 64 20 53 51 4c 69 74 65 20  standard SQLite 
8f00: 72 65 74 75 72 6e 20 63 6f 64 65 2e 0d 0a 20 20  return code...  
8f10: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72 65 74 75        /// </retu
8f20: 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 53 51  rns>..        SQ
8f30: 4c 69 74 65 45 72 72 6f 72 43 6f 64 65 20 78 44  LiteErrorCode xD
8f40: 69 73 63 6f 6e 6e 65 63 74 28 0d 0a 20 20 20 20  isconnect(..    
8f50: 20 20 20 20 20 20 20 20 49 6e 74 50 74 72 20 70          IntPtr p
8f60: 56 74 61 62 0d 0a 20 20 20 20 20 20 20 20 20 20  Vtab..          
8f70: 20 20 29 3b 0d 0a 0d 0a 20 20 20 20 20 20 20 20    );....        
8f80: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8f90: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8fa0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8fb0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8fc0: 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 20  ///////....     
8fd0: 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79 3e     /// <summary>
8fe0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
8ff0: 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20  ara><code>..    
9000: 20 20 20 20 2f 2f 2f 20 69 6e 74 20 28 2a 78 44      /// int (*xD
9010: 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f  estroy)(sqlite3_
9020: 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0d 0a 20  vtab *pVTab);.. 
9030: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64         /// </cod
9040: 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  e></para>..     
9050: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20     /// <para>.. 
9060: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 69 73 20         /// This 
9070: 6d 65 74 68 6f 64 20 72 65 6c 65 61 73 65 73 20  method releases 
9080: 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  a connection to 
9090: 61 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2c  a virtual table,
90a0: 20 6a 75 73 74 20 6c 69 6b 65 20 0d 0a 20 20 20   just like ..   
90b0: 20 20 20 20 20 2f 2f 2f 20 74 68 65 20 78 44 69       /// the xDi
90c0: 73 63 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64 2c  sconnect method,
90d0: 20 61 6e 64 20 69 74 20 61 6c 73 6f 20 64 65 73   and it also des
90e0: 74 72 6f 79 73 20 74 68 65 20 75 6e 64 65 72 6c  troys the underl
90f0: 79 69 6e 67 20 0d 0a 20 20 20 20 20 20 20 20 2f  ying ..        /
9100: 2f 2f 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  // table impleme
9110: 6e 74 61 74 69 6f 6e 2e 20 54 68 69 73 20 6d 65  ntation. This me
9120: 74 68 6f 64 20 75 6e 64 6f 65 73 20 74 68 65 20  thod undoes the 
9130: 77 6f 72 6b 20 6f 66 20 78 43 72 65 61 74 65 2e  work of xCreate.
9140: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
9150: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
9160: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20  // <para>..     
9170: 20 20 20 2f 2f 2f 20 54 68 65 20 78 44 69 73 63     /// The xDisc
9180: 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64 20 69 73  onnect method is
9190: 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 76 65 72   called whenever
91a0: 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
91b0: 65 63 74 69 6f 6e 0d 0a 20 20 20 20 20 20 20 20  ection..        
91c0: 2f 2f 2f 20 74 68 61 74 20 75 73 65 73 20 61 20  /// that uses a 
91d0: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 73  virtual table is
91e0: 20 63 6c 6f 73 65 64 2e 20 54 68 65 20 78 44 65   closed. The xDe
91f0: 73 74 72 6f 79 20 6d 65 74 68 6f 64 20 69 73 20  stroy method is 
9200: 6f 6e 6c 79 20 0d 0a 20 20 20 20 20 20 20 20 2f  only ..        /
9210: 2f 2f 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 61  // called when a
9220: 20 44 52 4f 50 20 54 41 42 4c 45 20 73 74 61 74   DROP TABLE stat
9230: 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 65  ement is execute
9240: 64 20 61 67 61 69 6e 73 74 20 74 68 65 20 76 69  d against the vi
9250: 72 74 75 61 6c 20 74 61 62 6c 65 2e 0d 0a 20 20  rtual table...  
9260: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61        /// </para
9270: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
9280: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
9290: 2f 2f 20 54 68 65 20 78 44 65 73 74 72 6f 79 20  // The xDestroy 
92a0: 6d 65 74 68 6f 64 20 69 73 20 72 65 71 75 69 72  method is requir
92b0: 65 64 20 66 6f 72 20 65 76 65 72 79 20 76 69 72  ed for every vir
92c0: 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65  tual table imple
92d0: 6d 65 6e 74 61 74 69 6f 6e 2c 0d 0a 20 20 20 20  mentation,..    
92e0: 20 20 20 20 2f 2f 2f 20 74 68 6f 75 67 68 20 69      /// though i
92f0: 74 20 69 73 20 61 63 63 65 70 74 61 62 6c 65 20  t is acceptable 
9300: 66 6f 72 20 74 68 65 20 78 44 69 73 63 6f 6e 6e  for the xDisconn
9310: 65 63 74 20 61 6e 64 20 78 44 65 73 74 72 6f 79  ect and xDestroy
9320: 20 6d 65 74 68 6f 64 73 20 74 6f 20 62 65 0d 0a   methods to be..
9330: 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 20          /// the 
9340: 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 69 66  same function if
9350: 20 74 68 61 74 20 6d 61 6b 65 73 20 73 65 6e 73   that makes sens
9360: 65 20 66 6f 72 20 74 68 65 20 70 61 72 74 69 63  e for the partic
9370: 75 6c 61 72 20 76 69 72 74 75 61 6c 20 74 61 62  ular virtual tab
9380: 6c 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  le...        ///
9390: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
93a0: 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e    /// </summary>
93b0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
93c0: 61 72 61 6d 20 6e 61 6d 65 3d 22 70 56 74 61 62  aram name="pVtab
93d0: 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ">..        /// 
93e0: 54 68 65 20 6e 61 74 69 76 65 20 70 6f 69 6e 74  The native point
93f0: 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
9400: 33 5f 76 74 61 62 20 64 65 72 69 76 65 64 20 73  3_vtab derived s
9410: 74 72 75 63 74 75 72 65 2e 0d 0a 20 20 20 20 20  tructure...     
9420: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d     /// </param>.
9430: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 72 65  .        /// <re
9440: 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20  turns>..        
9450: 2f 2f 2f 20 41 20 73 74 61 6e 64 61 72 64 20 53  /// A standard S
9460: 51 4c 69 74 65 20 72 65 74 75 72 6e 20 63 6f 64  QLite return cod
9470: 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e...        /// 
9480: 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20  </returns>..    
9490: 20 20 20 20 53 51 4c 69 74 65 45 72 72 6f 72 43      SQLiteErrorC
94a0: 6f 64 65 20 78 44 65 73 74 72 6f 79 28 0d 0a 20  ode xDestroy(.. 
94b0: 20 20 20 20 20 20 20 20 20 20 20 49 6e 74 50 74             IntPt
94c0: 72 20 70 56 74 61 62 0d 0a 20 20 20 20 20 20 20  r pVtab..       
94d0: 20 20 20 20 20 29 3b 0d 0a 0d 0a 20 20 20 20 20       );....     
94e0: 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f     /////////////
94f0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
9500: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
9510: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
9520: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20  //////////....  
9530: 20 20 20 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61        /// <summa
9540: 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ry>..        ///
9550: 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20   <para><code>.. 
9560: 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e 74 20 28         /// int (
9570: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
9580: 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c  vtab *pVTab, sql
9590: 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
95a0: 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0d 0a 20   **ppCursor);.. 
95b0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64         /// </cod
95c0: 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  e></para>..     
95d0: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20     /// <para>.. 
95e0: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 78         /// The x
95f0: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 63 72 65 61  Open method crea
9600: 74 65 73 20 61 20 6e 65 77 20 63 75 72 73 6f 72  tes a new cursor
9610: 20 75 73 65 64 20 66 6f 72 20 61 63 63 65 73 73   used for access
9620: 69 6e 67 20 28 72 65 61 64 20 61 6e 64 2f 6f 72  ing (read and/or
9630: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 77 72  ..        /// wr
9640: 69 74 69 6e 67 29 20 61 20 76 69 72 74 75 61 6c  iting) a virtual
9650: 20 74 61 62 6c 65 2e 20 20 41 20 73 75 63 63 65   table.  A succe
9660: 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
9670: 20 6f 66 20 74 68 69 73 20 6d 65 74 68 6f 64 20   of this method 
9680: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 77 69  ..        /// wi
9690: 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20  ll allocate the 
96a0: 6d 65 6d 6f 72 79 20 66 6f 72 20 74 68 65 20 73  memory for the s
96b0: 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
96c0: 6f 72 20 28 6f 72 20 61 20 73 75 62 63 6c 61 73  or (or a subclas
96d0: 73 29 2c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  s),..        ///
96e0: 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   initialize the 
96f0: 6e 65 77 20 6f 62 6a 65 63 74 2c 20 61 6e 64 20  new object, and 
9700: 6d 61 6b 65 20 2a 70 70 43 75 72 73 6f 72 20 70  make *ppCursor p
9710: 6f 69 6e 74 20 74 6f 20 74 68 65 20 6e 65 77 20  oint to the new 
9720: 6f 62 6a 65 63 74 2e 0d 0a 20 20 20 20 20 20 20  object...       
9730: 20 2f 2f 2f 20 54 68 65 20 73 75 63 63 65 73 73   /// The success
9740: 66 75 6c 20 63 61 6c 6c 20 74 68 65 6e 20 72 65  ful call then re
9750: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2e  turns SQLITE_OK.
9760: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
9770: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
9780: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20  // <para>..     
9790: 20 20 20 2f 2f 2f 20 46 6f 72 20 65 76 65 72 79     /// For every
97a0: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
97b0: 20 74 6f 20 74 68 69 73 20 6d 65 74 68 6f 64 2c   to this method,
97c0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
97d0: 20 77 69 6c 6c 0d 0a 20 20 20 20 20 20 20 20 2f   will..        /
97e0: 2f 2f 20 6c 61 74 65 72 20 69 6e 76 6f 6b 65 20  // later invoke 
97f0: 74 68 65 20 78 43 6c 6f 73 65 20 6d 65 74 68 6f  the xClose metho
9800: 64 20 74 6f 20 64 65 73 74 72 6f 79 20 0d 0a 20  d to destroy .. 
9810: 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 20 61         /// the a
9820: 6c 6c 6f 63 61 74 65 64 20 63 75 72 73 6f 72 2e  llocated cursor.
9830: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
9840: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
9850: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20  // <para>..     
9860: 20 20 20 2f 2f 2f 20 54 68 65 20 78 4f 70 65 6e     /// The xOpen
9870: 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74   method need not
9880: 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   initialize the 
9890: 70 56 74 61 62 20 66 69 65 6c 64 20 6f 66 20 74  pVtab field of t
98a0: 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  he..        /// 
98b0: 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
98c0: 73 6f 72 20 73 74 72 75 63 74 75 72 65 2e 20 20  sor structure.  
98d0: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
98e0: 77 69 6c 6c 20 74 61 6b 65 20 63 61 72 65 0d 0a  will take care..
98f0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 6f 66 20 74          /// of t
9900: 68 61 74 20 63 68 6f 72 65 20 61 75 74 6f 6d 61  hat chore automa
9910: 74 69 63 61 6c 6c 79 2e 0d 0a 20 20 20 20 20 20  tically...      
9920: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
9930: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
9940: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41  >..        /// A
9950: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
9960: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75  mplementation mu
9970: 73 74 20 62 65 20 61 62 6c 65 20 74 6f 20 73 75  st be able to su
9980: 70 70 6f 72 74 20 61 6e 20 61 72 62 69 74 72 61  pport an arbitra
9990: 72 79 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ry..        /// 
99a0: 6e 75 6d 62 65 72 20 6f 66 20 73 69 6d 75 6c 74  number of simult
99b0: 61 6e 65 6f 75 73 6c 79 20 6f 70 65 6e 20 63 75  aneously open cu
99c0: 72 73 6f 72 73 2e 0d 0a 20 20 20 20 20 20 20 20  rsors...        
99d0: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
99e0: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
99f0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 57 68 65  .        /// Whe
9a00: 6e 20 69 6e 69 74 69 61 6c 6c 79 20 6f 70 65 6e  n initially open
9a10: 65 64 2c 20 74 68 65 20 63 75 72 73 6f 72 20 69  ed, the cursor i
9a20: 73 20 69 6e 20 61 6e 20 75 6e 64 65 66 69 6e 65  s in an undefine
9a30: 64 20 73 74 61 74 65 2e 0d 0a 20 20 20 20 20 20  d state...      
9a40: 20 20 2f 2f 2f 20 54 68 65 20 53 51 4c 69 74 65    /// The SQLite
9a50: 20 63 6f 72 65 20 77 69 6c 6c 20 69 6e 76 6f 6b   core will invok
9a60: 65 20 74 68 65 20 78 46 69 6c 74 65 72 20 6d 65  e the xFilter me
9a70: 74 68 6f 64 0d 0a 20 20 20 20 20 20 20 20 2f 2f  thod..        //
9a80: 2f 20 6f 6e 20 74 68 65 20 63 75 72 73 6f 72 20  / on the cursor 
9a90: 70 72 69 6f 72 20 74 6f 20 61 6e 79 20 61 74 74  prior to any att
9aa0: 65 6d 70 74 20 74 6f 20 70 6f 73 69 74 69 6f 6e  empt to position
9ab0: 20 6f 72 20 72 65 61 64 20 66 72 6f 6d 20 74 68   or read from th
9ac0: 65 20 63 75 72 73 6f 72 2e 0d 0a 20 20 20 20 20  e cursor...     
9ad0: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a     /// </para>..
9ae0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
9af0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
9b00: 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  The xOpen method
9b10: 20 69 73 20 72 65 71 75 69 72 65 64 20 66 6f 72   is required for
9b20: 20 65 76 65 72 79 20 76 69 72 74 75 61 6c 20 74   every virtual t
9b30: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
9b40: 69 6f 6e 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ion...        //
9b50: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  / </para>..     
9b60: 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79     /// </summary
9b70: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
9b80: 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 56 74 61  param name="pVta
9b90: 62 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  b">..        ///
9ba0: 20 54 68 65 20 6e 61 74 69 76 65 20 70 6f 69 6e   The native poin
9bb0: 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
9bc0: 65 33 5f 76 74 61 62 20 64 65 72 69 76 65 64 20  e3_vtab derived 
9bd0: 73 74 72 75 63 74 75 72 65 2e 0d 0a 20 20 20 20  structure...    
9be0: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e      /// </param>
9bf0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
9c00: 61 72 61 6d 20 6e 61 6d 65 3d 22 70 43 75 72 73  aram name="pCurs
9c10: 6f 72 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  or">..        //
9c20: 2f 20 55 70 6f 6e 20 73 75 63 63 65 73 73 2c 20  / Upon success, 
9c30: 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 6d  this parameter m
9c40: 75 73 74 20 62 65 20 6d 6f 64 69 66 69 65 64 20  ust be modified 
9c50: 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
9c60: 6e 65 77 6c 79 0d 0a 20 20 20 20 20 20 20 20 2f  newly..        /
9c70: 2f 2f 20 63 72 65 61 74 65 64 20 6e 61 74 69 76  // created nativ
9c80: 65 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  e sqlite3_vtab_c
9c90: 75 72 73 6f 72 20 64 65 72 69 76 65 64 20 73 74  ursor derived st
9ca0: 72 75 63 74 75 72 65 2e 0d 0a 20 20 20 20 20 20  ructure...      
9cb0: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a    /// </param>..
9cc0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 72 65 74          /// <ret
9cd0: 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 2f  urns>..        /
9ce0: 2f 2f 20 41 20 73 74 61 6e 64 61 72 64 20 53 51  // A standard SQ
9cf0: 4c 69 74 65 20 72 65 74 75 72 6e 20 63 6f 64 65  Lite return code
9d00: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
9d10: 2f 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20  /returns>..     
9d20: 20 20 20 53 51 4c 69 74 65 45 72 72 6f 72 43 6f     SQLiteErrorCo
9d30: 64 65 20 78 4f 70 65 6e 28 0d 0a 20 20 20 20 20  de xOpen(..     
9d40: 20 20 20 20 20 20 20 49 6e 74 50 74 72 20 70 56         IntPtr pV
9d50: 74 61 62 2c 0d 0a 20 20 20 20 20 20 20 20 20 20  tab,..          
9d60: 20 20 72 65 66 20 49 6e 74 50 74 72 20 70 43 75    ref IntPtr pCu
9d70: 72 73 6f 72 0d 0a 20 20 20 20 20 20 20 20 20 20  rsor..          
9d80: 20 20 29 3b 0d 0a 0d 0a 20 20 20 20 20 20 20 20    );....        
9d90: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
9da0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
9db0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
9dc0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
9dd0: 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 20  ///////....     
9de0: 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79 3e     /// <summary>
9df0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
9e00: 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20  ara><code>..    
9e10: 20 20 20 20 2f 2f 2f 20 69 6e 74 20 28 2a 78 43      /// int (*xC
9e20: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74  lose)(sqlite3_vt
9e30: 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0d 0a 20 20  ab_cursor*);..  
9e40: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65        /// </code
9e50: 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  ></para>..      
9e60: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
9e70: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 43        /// The xC
9e80: 6c 6f 73 65 20 6d 65 74 68 6f 64 20 63 6c 6f 73  lose method clos
9e90: 65 73 20 61 20 63 75 72 73 6f 72 20 70 72 65 76  es a cursor prev
9ea0: 69 6f 75 73 6c 79 20 6f 70 65 6e 65 64 20 62 79  iously opened by
9eb0: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 78   ..        /// x
9ec0: 4f 70 65 6e 2e 20 0d 0a 20 20 20 20 20 20 20 20  Open. ..        
9ed0: 2f 2f 2f 20 54 68 65 20 53 51 4c 69 74 65 20 63  /// The SQLite c
9ee0: 6f 72 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ore will always 
9ef0: 63 61 6c 6c 20 78 43 6c 6f 73 65 20 6f 6e 63 65  call xClose once
9f00: 20 66 6f 72 20 65 61 63 68 20 63 75 72 73 6f 72   for each cursor
9f10: 20 6f 70 65 6e 65 64 20 0d 0a 20 20 20 20 20 20   opened ..      
9f20: 20 20 2f 2f 2f 20 75 73 69 6e 67 20 78 4f 70 65    /// using xOpe
9f30: 6e 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  n...        /// 
9f40: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
9f50: 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20   /// <para>..   
9f60: 20 20 20 20 20 2f 2f 2f 20 54 68 69 73 20 6d 65       /// This me
9f70: 74 68 6f 64 20 6d 75 73 74 20 72 65 6c 65 61 73  thod must releas
9f80: 65 20 61 6c 6c 20 72 65 73 6f 75 72 63 65 73 20  e all resources 
9f90: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 74 68 65  allocated by the
9fa0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 63 6f  ..        /// co
9fb0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 78 4f 70 65  rresponding xOpe
9fc0: 6e 20 63 61 6c 6c 2e 20 54 68 65 20 72 6f 75 74  n call. The rout
9fd0: 69 6e 65 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20  ine will not be 
9fe0: 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 65 76 65  called again eve
9ff0: 6e 20 69 66 20 69 74 0d 0a 20 20 20 20 20 20 20  n if it..       
a000: 20 2f 2f 2f 20 72 65 74 75 72 6e 73 20 61 6e 20   /// returns an 
a010: 65 72 72 6f 72 2e 20 20 54 68 65 20 53 51 4c 69  error.  The SQLi
a020: 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 6f 74  te core will not
a030: 20 75 73 65 20 74 68 65 0d 0a 20 20 20 20 20 20   use the..      
a040: 20 20 2f 2f 2f 20 73 71 6c 69 74 65 33 5f 76 74    /// sqlite3_vt
a050: 61 62 5f 63 75 72 73 6f 72 20 61 67 61 69 6e 20  ab_cursor again 
a060: 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
a070: 6e 20 63 6c 6f 73 65 64 2e 0d 0a 20 20 20 20 20  n closed...     
a080: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a     /// </para>..
a090: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
a0a0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
a0b0: 54 68 65 20 78 43 6c 6f 73 65 20 6d 65 74 68 6f  The xClose metho
a0c0: 64 20 69 73 20 72 65 71 75 69 72 65 64 20 66 6f  d is required fo
a0d0: 72 20 65 76 65 72 79 20 76 69 72 74 75 61 6c 20  r every virtual 
a0e0: 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
a0f0: 74 69 6f 6e 2e 0d 0a 20 20 20 20 20 20 20 20 2f  tion...        /
a100: 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  // </para>..    
a110: 20 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72      /// </summar
a120: 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  y>..        /// 
a130: 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 43 75  <param name="pCu
a140: 72 73 6f 72 22 3e 0d 0a 20 20 20 20 20 20 20 20  rsor">..        
a150: 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76 65 20 70  /// The native p
a160: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 71  ointer to the sq
a170: 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
a180: 72 20 64 65 72 69 76 65 64 20 73 74 72 75 63 74  r derived struct
a190: 75 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ure...        //
a1a0: 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20  / </param>..    
a1b0: 20 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72 6e 73      /// <returns
a1c0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41  >..        /// A
a1d0: 20 73 74 61 6e 64 61 72 64 20 53 51 4c 69 74 65   standard SQLite
a1e0: 20 72 65 74 75 72 6e 20 63 6f 64 65 2e 0d 0a 20   return code... 
a1f0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72 65 74         /// </ret
a200: 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 53  urns>..        S
a210: 51 4c 69 74 65 45 72 72 6f 72 43 6f 64 65 20 78  QLiteErrorCode x
a220: 43 6c 6f 73 65 28 0d 0a 20 20 20 20 20 20 20 20  Close(..        
a230: 20 20 20 20 49 6e 74 50 74 72 20 70 43 75 72 73      IntPtr pCurs
a240: 6f 72 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20  or..            
a250: 29 3b 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f  );....        //
a260: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
a270: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
a280: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
a290: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
a2a0: 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 20 20 20  /////....       
a2b0: 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a   /// <summary>..
a2c0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
a2d0: 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20  a><code>..      
a2e0: 20 20 2f 2f 2f 20 69 6e 74 20 28 2a 78 46 69 6c    /// int (*xFil
a2f0: 74 65 72 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ter)(sqlite3_vta
a300: 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20 69  b_cursor*, int i
a310: 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68 61  dxNum, const cha
a320: 72 20 2a 69 64 78 53 74 72 2c 0d 0a 20 20 20 20  r *idxStr,..    
a330: 20 20 20 20 2f 2f 2f 20 20 20 20 20 20 20 20 20      ///         
a340: 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20        int argc, 
a350: 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a  sqlite3_value **
a360: 61 72 67 76 29 3b 0d 0a 20 20 20 20 20 20 20 20  argv);..        
a370: 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72  /// </code></par
a380: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
a390: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
a3a0: 2f 2f 2f 20 54 68 69 73 20 6d 65 74 68 6f 64 20  /// This method 
a3b0: 62 65 67 69 6e 73 20 61 20 73 65 61 72 63 68 20  begins a search 
a3c0: 6f 66 20 61 20 76 69 72 74 75 61 6c 20 74 61 62  of a virtual tab
a3d0: 6c 65 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  le. ..        //
a3e0: 2f 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  / The first argu
a3f0: 6d 65 6e 74 20 69 73 20 61 20 63 75 72 73 6f 72  ment is a cursor
a400: 20 6f 70 65 6e 65 64 20 62 79 20 78 4f 70 65 6e   opened by xOpen
a410: 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  . ..        /// 
a420: 54 68 65 20 6e 65 78 74 20 74 77 6f 20 61 72 67  The next two arg
a430: 75 6d 65 6e 74 73 20 64 65 66 69 6e 65 20 61 20  uments define a 
a440: 70 61 72 74 69 63 75 6c 61 72 20 73 65 61 72 63  particular searc
a450: 68 20 69 6e 64 65 78 20 70 72 65 76 69 6f 75 73  h index previous
a460: 6c 79 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ly ..        ///
a470: 20 63 68 6f 73 65 6e 20 62 79 20 78 42 65 73 74   chosen by xBest
a480: 49 6e 64 65 78 2e 20 54 68 65 20 73 70 65 63 69  Index. The speci
a490: 66 69 63 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20  fic meanings of 
a4a0: 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 53 74  idxNum and idxSt
a4b0: 72 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  r ..        /// 
a4c0: 61 72 65 20 75 6e 69 6d 70 6f 72 74 61 6e 74 20  are unimportant 
a4d0: 61 73 20 6c 6f 6e 67 20 61 73 20 78 46 69 6c 74  as long as xFilt
a4e0: 65 72 20 61 6e 64 20 78 42 65 73 74 49 6e 64 65  er and xBestInde
a4f0: 78 20 61 67 72 65 65 20 6f 6e 20 77 68 61 74 20  x agree on what 
a500: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68  ..        /// th
a510: 61 74 20 6d 65 61 6e 69 6e 67 20 69 73 2e 0d 0a  at meaning is...
a520: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
a530: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
a540: 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20   <para>..       
a550: 20 2f 2f 2f 20 54 68 65 20 78 42 65 73 74 49 6e   /// The xBestIn
a560: 64 65 78 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  dex function may
a570: 20 68 61 76 65 20 72 65 71 75 65 73 74 65 64 20   have requested 
a580: 74 68 65 20 76 61 6c 75 65 73 20 6f 66 20 0d 0a  the values of ..
a590: 20 20 20 20 20 20 20 20 2f 2f 2f 20 63 65 72 74          /// cert
a5a0: 61 69 6e 20 65 78 70 72 65 73 73 69 6f 6e 73 20  ain expressions 
a5b0: 75 73 69 6e 67 20 74 68 65 20 61 43 6f 6e 73 74  using the aConst
a5c0: 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e 61 72 67  raintUsage[].arg
a5d0: 76 49 6e 64 65 78 20 76 61 6c 75 65 73 20 0d 0a  vIndex values ..
a5e0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 6f 66 20 74          /// of t
a5f0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  he sqlite3_index
a600: 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65 2e  _info structure.
a610: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54   ..        /// T
a620: 68 6f 73 65 20 76 61 6c 75 65 73 20 61 72 65 20  hose values are 
a630: 70 61 73 73 65 64 20 74 6f 20 78 46 69 6c 74 65  passed to xFilte
a640: 72 20 75 73 69 6e 67 20 74 68 65 20 61 72 67 63  r using the argc
a650: 20 61 6e 64 20 61 72 67 76 20 70 61 72 61 6d 65   and argv parame
a660: 74 65 72 73 2e 0d 0a 20 20 20 20 20 20 20 20 2f  ters...        /
a670: 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  // </para>..    
a680: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a      /// <para>..
a690: 20 20 20 20 20 20 20 20 2f 2f 2f 20 49 66 20 74          /// If t
a6a0: 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
a6b0: 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 65 20 6f 72   contains one or
a6c0: 20 6d 6f 72 65 20 72 6f 77 73 20 74 68 61 74 20   more rows that 
a6d0: 6d 61 74 63 68 20 74 68 65 0d 0a 20 20 20 20 20  match the..     
a6e0: 20 20 20 2f 2f 2f 20 73 65 61 72 63 68 20 63 72     /// search cr
a6f0: 69 74 65 72 69 61 2c 20 74 68 65 6e 20 74 68 65  iteria, then the
a700: 20 63 75 72 73 6f 72 20 6d 75 73 74 20 62 65 20   cursor must be 
a710: 6c 65 66 74 20 70 6f 69 6e 74 20 61 74 20 74 68  left point at th
a720: 65 20 66 69 72 73 74 20 72 6f 77 2e 0d 0a 20 20  e first row...  
a730: 20 20 20 20 20 20 2f 2f 2f 20 53 75 62 73 65 71        /// Subseq
a740: 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 78 45  uent calls to xE
a750: 6f 66 20 6d 75 73 74 20 72 65 74 75 72 6e 20 66  of must return f
a760: 61 6c 73 65 20 28 7a 65 72 6f 29 2e 0d 0a 20 20  alse (zero)...  
a770: 20 20 20 20 20 20 2f 2f 2f 20 49 66 20 74 68 65        /// If the
a780: 72 65 20 61 72 65 20 6e 6f 20 72 6f 77 73 20 6d  re are no rows m
a790: 61 74 63 68 2c 20 74 68 65 6e 20 74 68 65 20 63  atch, then the c
a7a0: 75 72 73 6f 72 20 6d 75 73 74 20 62 65 20 6c 65  ursor must be le
a7b0: 66 74 20 69 6e 20 61 20 73 74 61 74 65 20 0d 0a  ft in a state ..
a7c0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 61 74          /// that
a7d0: 20 77 69 6c 6c 20 63 61 75 73 65 20 74 68 65 20   will cause the 
a7e0: 78 45 6f 66 20 74 6f 20 72 65 74 75 72 6e 20 74  xEof to return t
a7f0: 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 2e 0d  rue (non-zero)..
a800: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65  .        /// The
a810: 20 53 51 4c 69 74 65 20 65 6e 67 69 6e 65 20 77   SQLite engine w
a820: 69 6c 6c 20 75 73 65 0d 0a 20 20 20 20 20 20 20  ill use..       
a830: 20 2f 2f 2f 20 74 68 65 20 78 43 6f 6c 75 6d 6e   /// the xColumn
a840: 20 61 6e 64 20 78 52 6f 77 69 64 20 6d 65 74 68   and xRowid meth
a850: 6f 64 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  ods to access th
a860: 61 74 20 72 6f 77 20 63 6f 6e 74 65 6e 74 2e 0d  at row content..
a870: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65  .        /// The
a880: 20 78 4e 65 78 74 20 6d 65 74 68 6f 64 20 77 69   xNext method wi
a890: 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20 61 64  ll be used to ad
a8a0: 76 61 6e 63 65 20 74 6f 20 74 68 65 20 6e 65 78  vance to the nex
a8b0: 74 20 72 6f 77 2e 0d 0a 20 20 20 20 20 20 20 20  t row...        
a8c0: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
a8d0: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
a8e0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 69  .        /// Thi
a8f0: 73 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 72 65  s method must re
a900: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69  turn SQLITE_OK i
a910: 66 20 73 75 63 63 65 73 73 66 75 6c 2c 20 6f 72  f successful, or
a920: 20 61 6e 20 73 71 6c 69 74 65 20 0d 0a 20 20 20   an sqlite ..   
a930: 20 20 20 20 20 2f 2f 2f 20 65 72 72 6f 72 20 63       /// error c
a940: 6f 64 65 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ode if an error 
a950: 6f 63 63 75 72 73 2e 0d 0a 20 20 20 20 20 20 20  occurs...       
a960: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
a970: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
a980: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
a990: 65 20 78 46 69 6c 74 65 72 20 6d 65 74 68 6f 64  e xFilter method
a9a0: 20 69 73 20 72 65 71 75 69 72 65 64 20 66 6f 72   is required for
a9b0: 20 65 76 65 72 79 20 76 69 72 74 75 61 6c 20 74   every virtual t
a9c0: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
a9d0: 69 6f 6e 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ion...        //
a9e0: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  / </para>..     
a9f0: 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79     /// </summary
aa00: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
aa10: 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 43 75 72  param name="pCur
aa20: 73 6f 72 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f  sor">..        /
aa30: 2f 2f 20 54 68 65 20 6e 61 74 69 76 65 20 70 6f  // The native po
aa40: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  inter to the sql
aa50: 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
aa60: 20 64 65 72 69 76 65 64 20 73 74 72 75 63 74 75   derived structu
aa70: 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  re...        ///
aa80: 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20   </param>..     
aa90: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61     /// <param na
aaa0: 6d 65 3d 22 69 64 78 4e 75 6d 22 3e 0d 0a 20 20  me="idxNum">..  
aab0: 20 20 20 20 20 20 2f 2f 2f 20 4e 75 6d 62 65 72        /// Number
aac0: 20 75 73 65 64 20 74 6f 20 68 65 6c 70 20 69 64   used to help id
aad0: 65 6e 74 69 66 79 20 74 68 65 20 73 65 6c 65 63  entify the selec
aae0: 74 65 64 20 69 6e 64 65 78 2e 0d 0a 20 20 20 20  ted index...    
aaf0: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e      /// </param>
ab00: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
ab10: 61 72 61 6d 20 6e 61 6d 65 3d 22 69 64 78 53 74  aram name="idxSt
ab20: 72 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  r">..        ///
ab30: 20 54 68 65 20 6e 61 74 69 76 65 20 70 6f 69 6e   The native poin
ab40: 74 65 72 20 74 6f 20 74 68 65 20 55 54 46 2d 38  ter to the UTF-8
ab50: 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 20   encoded string 
ab60: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0d 0a  containing the..
ab70: 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 74 72 69          /// stri
ab80: 6e 67 20 75 73 65 64 20 74 6f 20 68 65 6c 70 20  ng used to help 
ab90: 69 64 65 6e 74 69 66 79 20 74 68 65 20 73 65 6c  identify the sel
aba0: 65 63 74 65 64 20 69 6e 64 65 78 2e 0d 0a 20 20  ected index...  
abb0: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61        /// </para
abc0: 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  m>..        /// 
abd0: 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 61 72 67  <param name="arg
abe0: 63 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  c">..        ///
abf0: 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e   The number of n
ac00: 61 74 69 76 65 20 70 6f 69 6e 74 65 72 73 20 74  ative pointers t
ac10: 6f 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  o sqlite3_value 
ac20: 73 74 72 75 63 74 75 72 65 73 20 73 70 65 63 69  structures speci
ac30: 66 69 65 64 0d 0a 20 20 20 20 20 20 20 20 2f 2f  fied..        //
ac40: 2f 20 69 6e 20 3c 70 61 72 61 6d 72 65 66 20 6e  / in <paramref n
ac50: 61 6d 65 3d 22 61 72 67 76 22 20 2f 3e 2e 0d 0a  ame="argv" />...
ac60: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
ac70: 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ram>..        //
ac80: 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 61  / <param name="a
ac90: 72 67 76 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f  rgv">..        /
aca0: 2f 2f 20 41 6e 20 61 72 72 61 79 20 6f 66 20 6e  // An array of n
acb0: 61 74 69 76 65 20 70 6f 69 6e 74 65 72 73 20 74  ative pointers t
acc0: 6f 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  o sqlite3_value 
acd0: 73 74 72 75 63 74 75 72 65 73 20 63 6f 6e 74 61  structures conta
ace0: 69 6e 69 6e 67 0d 0a 20 20 20 20 20 20 20 20 2f  ining..        /
acf0: 2f 2f 20 66 69 6c 74 65 72 69 6e 67 20 63 72 69  // filtering cri
ad00: 74 65 72 69 61 20 66 6f 72 20 74 68 65 20 73 65  teria for the se
ad10: 6c 65 63 74 65 64 20 69 6e 64 65 78 2e 0d 0a 20  lected index... 
ad20: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
ad30: 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  am>..        ///
ad40: 20 3c 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20   <returns>..    
ad50: 20 20 20 20 2f 2f 2f 20 41 20 73 74 61 6e 64 61      /// A standa
ad60: 72 64 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  rd SQLite return
ad70: 20 63 6f 64 65 2e 0d 0a 20 20 20 20 20 20 20 20   code...        
ad80: 2f 2f 2f 20 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a  /// </returns>..
ad90: 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 45 72          SQLiteEr
ada0: 72 6f 72 43 6f 64 65 20 78 46 69 6c 74 65 72 28  rorCode xFilter(
adb0: 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 49 6e  ..            In
adc0: 74 50 74 72 20 70 43 75 72 73 6f 72 2c 0d 0a 20  tPtr pCursor,.. 
add0: 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 69             int i
ade0: 64 78 4e 75 6d 2c 0d 0a 20 20 20 20 20 20 20 20  dxNum,..        
adf0: 20 20 20 20 49 6e 74 50 74 72 20 69 64 78 53 74      IntPtr idxSt
ae00: 72 2c 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20  r,..            
ae10: 69 6e 74 20 61 72 67 63 2c 0d 0a 20 20 20 20 20  int argc,..     
ae20: 20 20 20 20 20 20 20 49 6e 74 50 74 72 20 61 72         IntPtr ar
ae30: 67 76 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20  gv..            
ae40: 29 3b 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f  );....        //
ae50: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
ae60: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
ae70: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
ae80: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
ae90: 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 20 20 20  /////....       
aea0: 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a   /// <summary>..
aeb0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
aec0: 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20  a><code>..      
aed0: 20 20 2f 2f 2f 20 69 6e 74 20 28 2a 78 4e 65 78    /// int (*xNex
aee0: 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  t)(sqlite3_vtab_
aef0: 63 75 72 73 6f 72 2a 29 3b 0d 0a 20 20 20 20 20  cursor*);..     
af00: 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f     /// </code></
af10: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
af20: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20  // <para>..     
af30: 20 20 20 2f 2f 2f 20 54 68 65 20 78 4e 65 78 74     /// The xNext
af40: 20 6d 65 74 68 6f 64 20 61 64 76 61 6e 63 65 73   method advances
af50: 20 61 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65   a virtual table
af60: 20 63 75 72 73 6f 72 0d 0a 20 20 20 20 20 20 20   cursor..       
af70: 20 2f 2f 2f 20 74 6f 20 74 68 65 20 6e 65 78 74   /// to the next
af80: 20 72 6f 77 20 6f 66 20 61 20 72 65 73 75 6c 74   row of a result
af90: 20 73 65 74 20 69 6e 69 74 69 61 74 65 64 20 62   set initiated b
afa0: 79 20 78 46 69 6c 74 65 72 2e 20 0d 0a 20 20 20  y xFilter. ..   
afb0: 20 20 20 20 20 2f 2f 2f 20 49 66 20 74 68 65 20       /// If the 
afc0: 63 75 72 73 6f 72 20 69 73 20 61 6c 72 65 61 64  cursor is alread
afd0: 79 20 70 6f 69 6e 74 69 6e 67 20 61 74 20 74 68  y pointing at th
afe0: 65 20 6c 61 73 74 20 72 6f 77 20 77 68 65 6e 20  e last row when 
aff0: 74 68 69 73 20 0d 0a 20 20 20 20 20 20 20 20 2f  this ..        /
b000: 2f 2f 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  // routine is ca
b010: 6c 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 63  lled, then the c
b020: 75 72 73 6f 72 20 6e 6f 20 6c 6f 6e 67 65 72 20  ursor no longer 
b030: 70 6f 69 6e 74 73 20 74 6f 20 76 61 6c 69 64 20  points to valid 
b040: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 64 61  ..        /// da
b050: 74 61 20 61 6e 64 20 61 20 73 75 62 73 65 71 75  ta and a subsequ
b060: 65 6e 74 20 63 61 6c 6c 20 74 6f 20 74 68 65 20  ent call to the 
b070: 78 45 6f 66 20 6d 65 74 68 6f 64 20 6d 75 73 74  xEof method must
b080: 20 72 65 74 75 72 6e 20 74 72 75 65 20 28 6e 6f   return true (no
b090: 6e 2d 7a 65 72 6f 29 2e 20 0d 0a 20 20 20 20 20  n-zero). ..     
b0a0: 20 20 20 2f 2f 2f 20 49 66 20 74 68 65 20 63 75     /// If the cu
b0b0: 72 73 6f 72 20 69 73 20 73 75 63 63 65 73 73 66  rsor is successf
b0c0: 75 6c 6c 79 20 61 64 76 61 6e 63 65 64 20 74 6f  ully advanced to
b0d0: 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66 20   another row of 
b0e0: 63 6f 6e 74 65 6e 74 2c 20 74 68 65 6e 0d 0a 20  content, then.. 
b0f0: 20 20 20 20 20 20 20 2f 2f 2f 20 73 75 62 73 65         /// subse
b100: 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 78  quent calls to x
b110: 45 6f 66 20 6d 75 73 74 20 72 65 74 75 72 6e 20  Eof must return 
b120: 66 61 6c 73 65 20 28 7a 65 72 6f 29 2e 0d 0a 20  false (zero)... 
b130: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
b140: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
b150: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
b160: 2f 2f 2f 20 54 68 69 73 20 6d 65 74 68 6f 64 20  /// This method 
b170: 6d 75 73 74 20 72 65 74 75 72 6e 20 53 51 4c 49  must return SQLI
b180: 54 45 5f 4f 4b 20 69 66 20 73 75 63 63 65 73 73  TE_OK if success
b190: 66 75 6c 2c 20 6f 72 20 61 6e 20 73 71 6c 69 74  ful, or an sqlit
b1a0: 65 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e ..        /// 
b1b0: 65 72 72 6f 72 20 63 6f 64 65 20 69 66 20 61 6e  error code if an
b1c0: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0d 0a   error occurs...
b1d0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
b1e0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
b1f0: 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20   <para>..       
b200: 20 2f 2f 2f 20 54 68 65 20 78 4e 65 78 74 20 6d   /// The xNext m
b210: 65 74 68 6f 64 20 69 73 20 72 65 71 75 69 72 65  ethod is require
b220: 64 20 66 6f 72 20 65 76 65 72 79 20 76 69 72 74  d for every virt
b230: 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
b240: 65 6e 74 61 74 69 6f 6e 2e 0d 0a 20 20 20 20 20  entation...     
b250: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a     /// </para>..
b260: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 73 75          /// </su
b270: 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20  mmary>..        
b280: 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d  /// <param name=
b290: 22 70 43 75 72 73 6f 72 22 3e 0d 0a 20 20 20 20  "pCursor">..    
b2a0: 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e 61 74 69      /// The nati
b2b0: 76 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  ve pointer to th
b2c0: 65 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  e sqlite3_vtab_c
b2d0: 75 72 73 6f 72 20 64 65 72 69 76 65 64 20 73 74  ursor derived st
b2e0: 72 75 63 74 75 72 65 2e 0d 0a 20 20 20 20 20 20  ructure...      
b2f0: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a    /// </param>..
b300: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 72 65 74          /// <ret
b310: 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 2f  urns>..        /
b320: 2f 2f 20 41 20 73 74 61 6e 64 61 72 64 20 53 51  // A standard SQ
b330: 4c 69 74 65 20 72 65 74 75 72 6e 20 63 6f 64 65  Lite return code
b340: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
b350: 2f 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20  /returns>..     
b360: 20 20 20 53 51 4c 69 74 65 45 72 72 6f 72 43 6f     SQLiteErrorCo
b370: 64 65 20 78 4e 65 78 74 28 0d 0a 20 20 20 20 20  de xNext(..     
b380: 20 20 20 20 20 20 20 49 6e 74 50 74 72 20 70 43         IntPtr pC
b390: 75 72 73 6f 72 0d 0a 20 20 20 20 20 20 20 20 20  ursor..         
b3a0: 20 20 20 29 3b 0d 0a 0d 0a 20 20 20 20 20 20 20     );....       
b3b0: 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f   ///////////////
b3c0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
b3d0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
b3e0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
b3f0: 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20  ////////....    
b400: 20 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79      /// <summary
b410: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
b420: 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20  para><code>..   
b430: 20 20 20 20 20 2f 2f 2f 20 69 6e 74 20 28 2a 78       /// int (*x
b440: 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61  Eof)(sqlite3_vta
b450: 62 5f 63 75 72 73 6f 72 2a 29 3b 0d 0a 20 20 20  b_cursor*);..   
b460: 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e       /// </code>
b470: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
b480: 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20   /// <para>..   
b490: 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 45 6f       /// The xEo
b4a0: 66 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 72 65  f method must re
b4b0: 74 75 72 6e 20 66 61 6c 73 65 20 28 7a 65 72 6f  turn false (zero
b4c0: 29 20 69 66 20 74 68 65 20 73 70 65 63 69 66 69  ) if the specifi
b4d0: 65 64 20 63 75 72 73 6f 72 20 0d 0a 20 20 20 20  ed cursor ..    
b4e0: 20 20 20 20 2f 2f 2f 20 63 75 72 72 65 6e 74 6c      /// currentl
b4f0: 79 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 76 61  y points to a va
b500: 6c 69 64 20 72 6f 77 20 6f 66 20 64 61 74 61 2c  lid row of data,
b510: 20 6f 72 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65   or true (non-ze
b520: 72 6f 29 20 6f 74 68 65 72 77 69 73 65 2e 20 0d  ro) otherwise. .
b530: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 69  .        /// Thi
b540: 73 20 6d 65 74 68 6f 64 20 69 73 20 63 61 6c 6c  s method is call
b550: 65 64 20 62 79 20 74 68 65 20 53 51 4c 20 65 6e  ed by the SQL en
b560: 67 69 6e 65 20 69 6d 6d 65 64 69 61 74 65 6c 79  gine immediately
b570: 20 61 66 74 65 72 20 65 61 63 68 20 0d 0a 20 20   after each ..  
b580: 20 20 20 20 20 20 2f 2f 2f 20 78 46 69 6c 74 65        /// xFilte
b590: 72 20 61 6e 64 20 78 4e 65 78 74 20 69 6e 76 6f  r and xNext invo
b5a0: 63 61 74 69 6f 6e 2e 0d 0a 20 20 20 20 20 20 20  cation...       
b5b0: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
b5c0: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
b5d0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
b5e0: 65 20 78 45 6f 66 20 6d 65 74 68 6f 64 20 69 73  e xEof method is
b5f0: 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 65 76   required for ev
b600: 65 72 79 20 76 69 72 74 75 61 6c 20 74 61 62 6c  ery virtual tabl
b610: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
b620: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
b630: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
b640: 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a  /// </summary>..
b650: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
b660: 61 6d 20 6e 61 6d 65 3d 22 70 43 75 72 73 6f 72  am name="pCursor
b670: 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ">..        /// 
b680: 54 68 65 20 6e 61 74 69 76 65 20 70 6f 69 6e 74  The native point
b690: 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
b6a0: 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 64 65  3_vtab_cursor de
b6b0: 72 69 76 65 64 20 73 74 72 75 63 74 75 72 65 2e  rived structure.
b6c0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
b6d0: 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20  param>..        
b6e0: 2f 2f 2f 20 3c 72 65 74 75 72 6e 73 3e 0d 0a 20  /// <returns>.. 
b6f0: 20 20 20 20 20 20 20 2f 2f 2f 20 4e 6f 6e 2d 7a         /// Non-z
b700: 65 72 6f 20 69 66 20 6e 6f 20 6d 6f 72 65 20 72  ero if no more r
b710: 6f 77 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ows are availabl
b720: 65 3b 20 7a 65 72 6f 20 6f 74 68 65 72 77 69 73  e; zero otherwis
b730: 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e...        /// 
b740: 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20  </returns>..    
b750: 20 20 20 20 69 6e 74 20 78 45 6f 66 28 0d 0a 20      int xEof(.. 
b760: 20 20 20 20 20 20 20 20 20 20 20 49 6e 74 50 74             IntPt
b770: 72 20 70 43 75 72 73 6f 72 0d 0a 20 20 20 20 20  r pCursor..     
b780: 20 20 20 20 20 20 20 29 3b 0d 0a 0d 0a 20 20 20         );....   
b790: 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f       ///////////
b7a0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
b7b0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
b7c0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
b7d0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a  ////////////....
b7e0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 73 75 6d          /// <sum
b7f0: 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f  mary>..        /
b800: 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d  // <para><code>.
b810: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e 74  .        /// int
b820: 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69   (*xColumn)(sqli
b830: 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
b840: 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  , sqlite3_contex
b850: 74 2a 2c 20 69 6e 74 20 4e 29 3b 0d 0a 20 20 20  t*, int N);..   
b860: 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e       /// </code>
b870: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
b880: 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20   /// <para>..   
b890: 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 53 51 4c       /// The SQL
b8a0: 69 74 65 20 63 6f 72 65 20 69 6e 76 6f 6b 65 73  ite core invokes
b8b0: 20 74 68 69 73 20 6d 65 74 68 6f 64 20 69 6e 20   this method in 
b8c0: 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68  order to find th
b8d0: 65 20 76 61 6c 75 65 20 66 6f 72 20 0d 0a 20 20  e value for ..  
b8e0: 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 20 4e 2d        /// the N-
b8f0: 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
b900: 20 63 75 72 72 65 6e 74 20 72 6f 77 2e 20 4e 20   current row. N 
b910: 69 73 20 7a 65 72 6f 2d 62 61 73 65 64 20 73 6f  is zero-based so
b920: 20 74 68 65 20 66 69 72 73 74 20 63 6f 6c 75 6d   the first colum
b930: 6e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  n ..        /// 
b940: 69 73 20 6e 75 6d 62 65 72 65 64 20 30 2e 20 0d  is numbered 0. .
b950: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65  .        /// The
b960: 20 78 43 6f 6c 75 6d 6e 20 6d 65 74 68 6f 64 20   xColumn method 
b970: 6d 61 79 20 72 65 74 75 72 6e 20 69 74 73 20 72  may return its r
b980: 65 73 75 6c 74 20 62 61 63 6b 20 74 6f 20 53 51  esult back to SQ
b990: 4c 69 74 65 20 75 73 69 6e 67 20 6f 6e 65 20 6f  Lite using one o
b9a0: 66 20 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f  f the..        /
b9b0: 2f 2f 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74  // following int
b9c0: 65 72 66 61 63 65 3a 0d 0a 20 20 20 20 20 20 20  erface:..       
b9d0: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
b9e0: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
b9f0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 21  ..        /// <!
ba00: 5b 43 44 41 54 41 5b 3c 75 6c 3e 5d 5d 3e 0d 0a  [CDATA[<ul>]]>..
ba10: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 21 5b 43          /// <![C
ba20: 44 41 54 41 5b 3c 6c 69 3e 5d 5d 3e 20 73 71 6c  DATA[<li>]]> sql
ba30: 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
ba40: 28 29 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ()..        /// 
ba50: 3c 21 5b 43 44 41 54 41 5b 3c 2f 6c 69 3e 5d 5d  <![CDATA[</li>]]
ba60: 3e 3c 21 5b 43 44 41 54 41 5b 3c 6c 69 3e 5d 5d  ><![CDATA[<li>]]
ba70: 3e 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  > sqlite3_result
ba80: 5f 64 6f 75 62 6c 65 28 29 0d 0a 20 20 20 20 20  _double()..     
ba90: 20 20 20 2f 2f 2f 20 3c 21 5b 43 44 41 54 41 5b     /// <![CDATA[
baa0: 3c 2f 6c 69 3e 5d 5d 3e 3c 21 5b 43 44 41 54 41  </li>]]><![CDATA
bab0: 5b 3c 6c 69 3e 5d 5d 3e 20 73 71 6c 69 74 65 33  [<li>]]> sqlite3
bac0: 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 0d 0a 20  _result_int().. 
bad0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 21 5b 43 44         /// <![CD
bae0: 41 54 41 5b 3c 2f 6c 69 3e 5d 5d 3e 3c 21 5b 43  ATA[</li>]]><![C
baf0: 44 41 54 41 5b 3c 6c 69 3e 5d 5d 3e 20 73 71 6c  DATA[<li>]]> sql
bb00: 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36  ite3_result_int6
bb10: 34 28 29 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  4()..        ///
bb20: 20 3c 21 5b 43 44 41 54 41 5b 3c 2f 6c 69 3e 5d   <![CDATA[</li>]
bb30: 5d 3e 3c 21 5b 43 44 41 54 41 5b 3c 6c 69 3e 5d  ]><![CDATA[<li>]
bb40: 5d 3e 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ]> sqlite3_resul
bb50: 74 5f 6e 75 6c 6c 28 29 0d 0a 20 20 20 20 20 20  t_null()..      
bb60: 20 20 2f 2f 2f 20 3c 21 5b 43 44 41 54 41 5b 3c    /// <![CDATA[<
bb70: 2f 6c 69 3e 5d 5d 3e 3c 21 5b 43 44 41 54 41 5b  /li>]]><![CDATA[
bb80: 3c 6c 69 3e 5d 5d 3e 20 73 71 6c 69 74 65 33 5f  <li>]]> sqlite3_
bb90: 72 65 73 75 6c 74 5f 74 65 78 74 28 29 0d 0a 20  result_text().. 
bba0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 21 5b 43 44         /// <![CD
bbb0: 41 54 41 5b 3c 2f 6c 69 3e 5d 5d 3e 3c 21 5b 43  ATA[</li>]]><![C
bbc0: 44 41 54 41 5b 3c 6c 69 3e 5d 5d 3e 20 73 71 6c  DATA[<li>]]> sql
bbd0: 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
bbe0: 31 36 28 29 0d 0a 20 20 20 20 20 20 20 20 2f 2f  16()..        //
bbf0: 2f 20 3c 21 5b 43 44 41 54 41 5b 3c 2f 6c 69 3e  / <![CDATA[</li>
bc00: 5d 5d 3e 3c 21 5b 43 44 41 54 41 5b 3c 6c 69 3e  ]]><![CDATA[<li>
bc10: 5d 5d 3e 20 73 71 6c 69 74 65 33 5f 72 65 73 75  ]]> sqlite3_resu
bc20: 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 0d 0a 20  lt_text16le().. 
bc30: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 21 5b 43 44         /// <![CD
bc40: 41 54 41 5b 3c 2f 6c 69 3e 5d 5d 3e 3c 21 5b 43  ATA[</li>]]><![C
bc50: 44 41 54 41 5b 3c 6c 69 3e 5d 5d 3e 20 73 71 6c  DATA[<li>]]> sql
bc60: 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
bc70: 31 36 62 65 28 29 0d 0a 20 20 20 20 20 20 20 20  16be()..        
bc80: 2f 2f 2f 20 3c 21 5b 43 44 41 54 41 5b 3c 2f 6c  /// <![CDATA[</l
bc90: 69 3e 5d 5d 3e 3c 21 5b 43 44 41 54 41 5b 3c 6c  i>]]><![CDATA[<l
bca0: 69 3e 5d 5d 3e 20 73 71 6c 69 74 65 33 5f 72 65  i>]]> sqlite3_re
bcb0: 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 0d  sult_zeroblob().
bcc0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 21 5b  .        /// <![
bcd0: 43 44 41 54 41 5b 3c 2f 6c 69 3e 5d 5d 3e 3c 21  CDATA[</li>]]><!
bce0: 5b 43 44 41 54 41 5b 3c 2f 75 6c 3e 5d 5d 3e 0d  [CDATA[</ul>]]>.
bcf0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
bd00: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
bd10: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
bd20: 20 20 2f 2f 2f 20 49 66 20 74 68 65 20 78 43 6f    /// If the xCo
bd30: 6c 75 6d 6e 20 6d 65 74 68 6f 64 20 69 6d 70 6c  lumn method impl
bd40: 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6c 6c 73  ementation calls
bd50: 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 66 75 6e   none of the fun
bd60: 63 74 69 6f 6e 73 20 61 62 6f 76 65 2c 0d 0a 20  ctions above,.. 
bd70: 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 6e 20         /// then 
bd80: 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
bd90: 20 63 6f 6c 75 6d 6e 20 64 65 66 61 75 6c 74 73   column defaults
bda0: 20 74 6f 20 61 6e 20 53 51 4c 20 4e 55 4c 4c 2e   to an SQL NULL.
bdb0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
bdc0: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
bdd0: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20  // <para>..     
bde0: 20 20 20 2f 2f 2f 20 54 6f 20 72 61 69 73 65 20     /// To raise 
bdf0: 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 20 78 43  an error, the xC
be00: 6f 6c 75 6d 6e 20 6d 65 74 68 6f 64 20 73 68 6f  olumn method sho
be10: 75 6c 64 20 75 73 65 20 6f 6e 65 20 6f 66 20 74  uld use one of t
be20: 68 65 20 72 65 73 75 6c 74 5f 74 65 78 74 28 29  he result_text()
be30: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6d   ..        /// m
be40: 65 74 68 6f 64 73 20 74 6f 20 73 65 74 20 74 68  ethods to set th
be50: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
be60: 74 65 78 74 2c 20 74 68 65 6e 20 72 65 74 75 72  text, then retur
be70: 6e 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  n an appropriate
be80: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 65 72  ..        /// er
be90: 72 6f 72 20 63 6f 64 65 2e 20 20 54 68 65 20 78  ror code.  The x
bea0: 43 6f 6c 75 6d 6e 20 6d 65 74 68 6f 64 20 6d 75  Column method mu
beb0: 73 74 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  st return SQLITE
bec0: 5f 4f 4b 20 6f 6e 20 73 75 63 63 65 73 73 2e 0d  _OK on success..
bed0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
bee0: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
bef0: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
bf00: 20 20 2f 2f 2f 20 54 68 65 20 78 43 6f 6c 75 6d    /// The xColum
bf10: 6e 20 6d 65 74 68 6f 64 20 69 73 20 72 65 71 75  n method is requ
bf20: 69 72 65 64 20 66 6f 72 20 65 76 65 72 79 20 76  ired for every v
bf30: 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70  irtual table imp
bf40: 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0d 0a 20 20  lementation...  
bf50: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61        /// </para
bf60: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
bf70: 2f 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20  /summary>..     
bf80: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61     /// <param na
bf90: 6d 65 3d 22 70 43 75 72 73 6f 72 22 3e 0d 0a 20  me="pCursor">.. 
bfa0: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e         /// The n
bfb0: 61 74 69 76 65 20 70 6f 69 6e 74 65 72 20 74 6f  ative pointer to
bfc0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 74 61   the sqlite3_vta
bfd0: 62 5f 63 75 72 73 6f 72 20 64 65 72 69 76 65 64  b_cursor derived
bfe0: 20 73 74 72 75 63 74 75 72 65 2e 0d 0a 20 20 20   structure...   
bff0: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d       /// </param
c000: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
c010: 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 43 6f 6e  param name="pCon
c020: 74 65 78 74 22 3e 0d 0a 20 20 20 20 20 20 20 20  text">..        
c030: 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76 65 20 70  /// The native p
c040: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 71  ointer to the sq
c050: 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 74  lite3_context st
c060: 72 75 63 74 75 72 65 20 74 6f 20 62 65 20 75 73  ructure to be us
c070: 65 64 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ed..        /// 
c080: 66 6f 72 20 72 65 74 75 72 6e 69 6e 67 20 74 68  for returning th
c090: 65 20 73 70 65 63 69 66 69 65 64 20 63 6f 6c 75  e specified colu
c0a0: 6d 6e 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20  mn value to the 
c0b0: 53 51 4c 69 74 65 20 63 6f 72 65 0d 0a 20 20 20  SQLite core..   
c0c0: 20 20 20 20 20 2f 2f 2f 20 6c 69 62 72 61 72 79       /// library
c0d0: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
c0e0: 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20  /param>..       
c0f0: 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65   /// <param name
c100: 3d 22 69 6e 64 65 78 22 3e 0d 0a 20 20 20 20 20  ="index">..     
c110: 20 20 20 2f 2f 2f 20 54 68 65 20 7a 65 72 6f 2d     /// The zero-
c120: 62 61 73 65 64 20 69 6e 64 65 78 20 63 6f 72 72  based index corr
c130: 65 73 70 6f 6e 64 69 6e 67 20 74 6f 20 74 68 65  esponding to the
c140: 20 63 6f 6c 75 6d 6e 20 63 6f 6e 74 61 69 6e 69   column containi
c150: 6e 67 20 74 68 65 0d 0a 20 20 20 20 20 20 20 20  ng the..        
c160: 2f 2f 2f 20 76 61 6c 75 65 20 74 6f 20 62 65 20  /// value to be 
c170: 72 65 74 75 72 6e 65 64 2e 0d 0a 20 20 20 20 20  returned...     
c180: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d     /// </param>.
c190: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 72 65  .        /// <re
c1a0: 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20  turns>..        
c1b0: 2f 2f 2f 20 41 20 73 74 61 6e 64 61 72 64 20 53  /// A standard S
c1c0: 51 4c 69 74 65 20 72 65 74 75 72 6e 20 63 6f 64  QLite return cod
c1d0: 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e...        /// 
c1e0: 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20  </returns>..    
c1f0: 20 20 20 20 53 51 4c 69 74 65 45 72 72 6f 72 43      SQLiteErrorC
c200: 6f 64 65 20 78 43 6f 6c 75 6d 6e 28 0d 0a 20 20  ode xColumn(..  
c210: 20 20 20 20 20 20 20 20 20 20 49 6e 74 50 74 72            IntPtr
c220: 20 70 43 75 72 73 6f 72 2c 0d 0a 20 20 20 20 20   pCursor,..     
c230: 20 20 20 20 20 20 20 49 6e 74 50 74 72 20 70 43         IntPtr pC
c240: 6f 6e 74 65 78 74 2c 0d 0a 20 20 20 20 20 20 20  ontext,..       
c250: 20 20 20 20 20 69 6e 74 20 69 6e 64 65 78 0d 0a       int index..
c260: 20 20 20 20 20 20 20 20 20 20 20 20 29 3b 0d 0a              );..
c270: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f  ..        //////
c280: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
c290: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
c2a0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
c2b0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
c2c0: 2f 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  /....        ///
c2d0: 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20   <summary>..    
c2e0: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63      /// <para><c
c2f0: 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ode>..        //
c300: 2f 20 69 6e 74 20 28 2a 78 52 6f 77 69 64 29 28  / int (*xRowid)(
c310: 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
c320: 73 6f 72 20 2a 70 43 75 72 2c 20 73 71 6c 69 74  sor *pCur, sqlit
c330: 65 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69 64 29  e_int64 *pRowid)
c340: 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ;..        /// <
c350: 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20  /code></para>.. 
c360: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
c370: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41  >..        /// A
c380: 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
c390: 63 61 74 69 6f 6e 20 6f 66 20 74 68 69 73 20 6d  cation of this m
c3a0: 65 74 68 6f 64 20 77 69 6c 6c 20 63 61 75 73 65  ethod will cause
c3b0: 20 2a 70 52 6f 77 69 64 20 74 6f 20 62 65 0d 0a   *pRowid to be..
c3c0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 66 69 6c 6c          /// fill
c3d0: 65 64 20 77 69 74 68 20 74 68 65 20 72 6f 77 69  ed with the rowi
c3e0: 64 20 6f 66 20 72 6f 77 20 74 68 61 74 20 74 68  d of row that th
c3f0: 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 76  e..        /// v
c400: 69 72 74 75 61 6c 20 74 61 62 6c 65 20 63 75 72  irtual table cur
c410: 73 6f 72 20 70 43 75 72 20 69 73 20 63 75 72 72  sor pCur is curr
c420: 65 6e 74 6c 79 20 70 6f 69 6e 74 69 6e 67 20 61  ently pointing a
c430: 74 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  t...        /// 
c440: 54 68 69 73 20 6d 65 74 68 6f 64 20 72 65 74 75  This method retu
c450: 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 20 6f 6e  rns SQLITE_OK on
c460: 20 73 75 63 63 65 73 73 2e 0d 0a 20 20 20 20 20   success...     
c470: 20 20 20 2f 2f 2f 20 49 74 20 72 65 74 75 72 6e     /// It return
c480: 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
c490: 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 6e 20 66   error code on f
c4a0: 61 69 6c 75 72 65 2e 0d 0a 20 20 20 20 20 20 20  ailure...       
c4b0: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
c4c0: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
c4d0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
c4e0: 65 20 78 52 6f 77 69 64 20 6d 65 74 68 6f 64 20  e xRowid method 
c4f0: 69 73 20 72 65 71 75 69 72 65 64 20 66 6f 72 20  is required for 
c500: 65 76 65 72 79 20 76 69 72 74 75 61 6c 20 74 61  every virtual ta
c510: 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
c520: 6f 6e 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  on...        ///
c530: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
c540: 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e    /// </summary>
c550: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
c560: 61 72 61 6d 20 6e 61 6d 65 3d 22 70 43 75 72 73  aram name="pCurs
c570: 6f 72 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  or">..        //
c580: 2f 20 54 68 65 20 6e 61 74 69 76 65 20 70 6f 69  / The native poi
c590: 6e 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  nter to the sqli
c5a0: 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20  te3_vtab_cursor 
c5b0: 64 65 72 69 76 65 64 20 73 74 72 75 63 74 75 72  derived structur
c5c0: 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e...        /// 
c5d0: 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20  </param>..      
c5e0: 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d    /// <param nam
c5f0: 65 3d 22 72 6f 77 49 64 22 3e 0d 0a 20 20 20 20  e="rowId">..    
c600: 20 20 20 20 2f 2f 2f 20 55 70 6f 6e 20 73 75 63      /// Upon suc
c610: 63 65 73 73 2c 20 74 68 69 73 20 70 61 72 61 6d  cess, this param
c620: 65 74 65 72 20 6d 75 73 74 20 62 65 20 6d 6f 64  eter must be mod
c630: 69 66 69 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e  ified to contain
c640: 20 74 68 65 20 75 6e 69 71 75 65 0d 0a 20 20 20   the unique..   
c650: 20 20 20 20 20 2f 2f 2f 20 69 6e 74 65 67 65 72       /// integer
c660: 20 72 6f 77 20 69 64 65 6e 74 69 66 69 65 72 20   row identifier 
c670: 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  for the current 
c680: 72 6f 77 20 66 6f 72 20 74 68 65 20 73 70 65 63  row for the spec
c690: 69 66 69 65 64 20 63 75 72 73 6f 72 2e 0d 0a 20  ified cursor... 
c6a0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
c6b0: 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  am>..        ///
c6c0: 20 3c 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20   <returns>..    
c6d0: 20 20 20 20 2f 2f 2f 20 41 20 73 74 61 6e 64 61      /// A standa
c6e0: 72 64 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  rd SQLite return
c6f0: 20 63 6f 64 65 2e 0d 0a 20 20 20 20 20 20 20 20   code...        
c700: 2f 2f 2f 20 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a  /// </returns>..
c710: 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 45 72          SQLiteEr
c720: 72 6f 72 43 6f 64 65 20 78 52 6f 77 49 64 28 0d  rorCode xRowId(.
c730: 0a 20 20 20 20 20 20 20 20 20 20 20 20 49 6e 74  .            Int
c740: 50 74 72 20 70 43 75 72 73 6f 72 2c 0d 0a 20 20  Ptr pCursor,..  
c750: 20 20 20 20 20 20 20 20 20 20 72 65 66 20 6c 6f            ref lo
c760: 6e 67 20 72 6f 77 49 64 0d 0a 20 20 20 20 20 20  ng rowId..      
c770: 20 20 20 20 20 20 29 3b 0d 0a 0d 0a 20 20 20 20        );....    
c780: 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f      ////////////
c790: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 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 0d 0a 0d 0a 20  ///////////.... 
c7d0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d         /// <summ
c7e0: 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ary>..        //
c7f0: 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a  / <para><code>..
c800: 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e 74 20          /// int 
c810: 28 2a 78 55 70 64 61 74 65 29 28 0d 0a 20 20 20  (*xUpdate)(..   
c820: 20 20 20 20 20 2f 2f 2f 20 20 20 73 71 6c 69 74       ///   sqlit
c830: 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 0d  e3_vtab *pVTab,.
c840: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 69  .        ///   i
c850: 6e 74 20 61 72 67 63 2c 0d 0a 20 20 20 20 20 20  nt argc,..      
c860: 20 20 2f 2f 2f 20 20 20 73 71 6c 69 74 65 33 5f    ///   sqlite3_
c870: 76 61 6c 75 65 20 2a 2a 61 72 67 76 2c 0d 0a 20  value **argv,.. 
c880: 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 73 71 6c         ///   sql
c890: 69 74 65 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69  ite_int64 *pRowi
c8a0: 64 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 29  d..        /// )
c8b0: 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ;..        /// <
c8c0: 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20  /code></para>.. 
c8d0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
c8e0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41  >..        /// A
c8f0: 6c 6c 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ll changes to a 
c900: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61 72  virtual table ar
c910: 65 20 6d 61 64 65 20 75 73 69 6e 67 20 74 68 65  e made using the
c920: 20 78 55 70 64 61 74 65 20 6d 65 74 68 6f 64 2e   xUpdate method.
c930: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
c940: 69 73 20 6f 6e 65 20 6d 65 74 68 6f 64 20 63 61  is one method ca
c950: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6e 73  n be used to ins
c960: 65 72 74 2c 20 64 65 6c 65 74 65 2c 20 6f 72 20  ert, delete, or 
c970: 75 70 64 61 74 65 2e 0d 0a 20 20 20 20 20 20 20  update...       
c980: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
c990: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
c9a0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
c9b0: 65 20 61 72 67 63 20 70 61 72 61 6d 65 74 65 72  e argc parameter
c9c0: 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 6e   specifies the n
c9d0: 75 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73  umber of entries
c9e0: 20 69 6e 20 74 68 65 20 61 72 67 76 20 61 72 72   in the argv arr
c9f0: 61 79 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ay. ..        //
ca00: 2f 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 61  / The value of a
ca10: 72 67 63 20 77 69 6c 6c 20 62 65 20 31 20 66 6f  rgc will be 1 fo
ca20: 72 20 61 20 70 75 72 65 20 64 65 6c 65 74 65 20  r a pure delete 
ca30: 6f 70 65 72 61 74 69 6f 6e 20 6f 72 20 4e 2b 32  operation or N+2
ca40: 20 66 6f 72 20 61 6e 20 69 6e 73 65 72 74 0d 0a   for an insert..
ca50: 20 20 20 20 20 20 20 20 2f 2f 2f 20 6f 72 20 72          /// or r
ca60: 65 70 6c 61 63 65 20 6f 72 20 75 70 64 61 74 65  eplace or update
ca70: 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
ca80: 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
ca90: 73 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 20  s in the table. 
caa0: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 49   ..        /// I
cab0: 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  n the previous s
cac0: 65 6e 74 65 6e 63 65 2c 20 4e 20 69 6e 63 6c 75  entence, N inclu
cad0: 64 65 73 20 61 6e 79 20 68 69 64 64 65 6e 20 63  des any hidden c
cae0: 6f 6c 75 6d 6e 73 2e 0d 0a 20 20 20 20 20 20 20  olumns...       
caf0: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
cb00: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
cb10: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 45 76  ..        /// Ev
cb20: 65 72 79 20 61 72 67 76 20 65 6e 74 72 79 20 77  ery argv entry w
cb30: 69 6c 6c 20 68 61 76 65 20 61 20 6e 6f 6e 2d 4e  ill have a non-N
cb40: 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 43 20 62  ULL value in C b
cb50: 75 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 74  ut may contain t
cb60: 68 65 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  he ..        ///
cb70: 20 53 51 4c 20 76 61 6c 75 65 20 4e 55 4c 4c 2e   SQL value NULL.
cb80: 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
cb90: 2c 20 69 74 20 69 73 20 61 6c 77 61 79 73 20 74  , it is always t
cba0: 72 75 65 20 74 68 61 74 0d 0a 20 20 20 20 20 20  rue that..      
cbb0: 20 20 2f 2f 2f 20 3c 21 5b 43 44 41 54 41 5b 3c    /// <![CDATA[<
cbc0: 74 74 3e 5d 5d 3e 61 72 67 76 5b 69 5d 21 3d 30  tt>]]>argv[i]!=0
cbd0: 3c 21 5b 43 44 41 54 41 5b 3c 2f 74 74 3e 5d 5d  <![CDATA[</tt>]]
cbe0: 3e 20 66 6f 72 20 3c 21 5b 43 44 41 54 41 5b 3c  > for <![CDATA[<
cbf0: 62 3e 5d 5d 3e 69 3c 21 5b 43 44 41 54 41 5b 3c  b>]]>i<![CDATA[<
cc00: 2f 62 3e 5d 5d 3e 20 62 65 74 77 65 65 6e 20 30  /b>]]> between 0
cc10: 20 61 6e 64 20 3c 21 5b 43 44 41 54 41 5b 3c 74   and <![CDATA[<t
cc20: 74 3e 5d 5d 3e 61 72 67 63 2d 31 3c 21 5b 43 44  t>]]>argc-1<![CD
cc30: 41 54 41 5b 3c 2f 74 74 3e 5d 5d 3e 2e 0d 0a 20  ATA[</tt>]]>... 
cc40: 20 20 20 20 20 20 20 2f 2f 2f 20 48 6f 77 65 76         /// Howev
cc50: 65 72 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20  er, it might be 
cc60: 74 68 65 20 63 61 73 65 20 74 68 61 74 0d 0a 20  the case that.. 
cc70: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 21 5b 43 44         /// <![CD
cc80: 41 54 41 5b 3c 74 74 3e 5d 5d 3e 73 71 6c 69 74  ATA[<tt>]]>sqlit
cc90: 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 61 72  e3_value_type(ar
cca0: 67 76 5b 69 5d 29 3d 3d 53 51 4c 49 54 45 5f 4e  gv[i])==SQLITE_N
ccb0: 55 4c 4c 3c 21 5b 43 44 41 54 41 5b 3c 2f 74 74  ULL<![CDATA[</tt
ccc0: 3e 5d 5d 3e 2e 0d 0a 20 20 20 20 20 20 20 20 2f  >]]>...        /
ccd0: 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  // </para>..    
cce0: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a      /// <para>..
ccf0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20          /// The 
cd00: 61 72 67 76 5b 30 5d 20 70 61 72 61 6d 65 74 65  argv[0] paramete
cd10: 72 20 69 73 20 74 68 65 20 72 6f 77 69 64 20 6f  r is the rowid o
cd20: 66 20 61 20 72 6f 77 20 69 6e 20 74 68 65 20 76  f a row in the v
cd30: 69 72 74 75 61 6c 20 74 61 62 6c 65 20 0d 0a 20  irtual table .. 
cd40: 20 20 20 20 20 20 20 2f 2f 2f 20 74 6f 20 62 65         /// to be
cd50: 20 64 65 6c 65 74 65 64 2e 20 49 66 20 61 72 67   deleted. If arg
cd60: 76 5b 30 5d 20 69 73 20 61 6e 20 53 51 4c 20 4e  v[0] is an SQL N
cd70: 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 64 65 6c  ULL, then no del
cd80: 65 74 69 6f 6e 20 6f 63 63 75 72 73 2e 0d 0a 20  etion occurs... 
cd90: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
cda0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
cdb0: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
cdc0: 2f 2f 2f 20 54 68 65 20 61 72 67 76 5b 31 5d 20  /// The argv[1] 
cdd0: 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
cde0: 20 72 6f 77 69 64 20 6f 66 20 61 20 6e 65 77 20   rowid of a new 
cdf0: 72 6f 77 20 74 6f 20 62 65 20 69 6e 73 65 72 74  row to be insert
ce00: 65 64 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ed ..        ///
ce10: 20 69 6e 74 6f 20 74 68 65 20 76 69 72 74 75 61   into the virtua
ce20: 6c 20 74 61 62 6c 65 2e 20 49 66 20 61 72 67 76  l table. If argv
ce30: 5b 31 5d 20 69 73 20 61 6e 20 53 51 4c 20 4e 55  [1] is an SQL NU
ce40: 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 69 6d 70  LL, then the imp
ce50: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 0d 0a 20 20  lementation ..  
ce60: 20 20 20 20 20 20 2f 2f 2f 20 6d 75 73 74 20 63        /// must c
ce70: 68 6f 6f 73 65 20 61 20 72 6f 77 69 64 20 66 6f  hoose a rowid fo
ce80: 72 20 74 68 65 20 6e 65 77 6c 79 20 69 6e 73 65  r the newly inse
ce90: 72 74 65 64 20 72 6f 77 2e 20 53 75 62 73 65 71  rted row. Subseq
cea0: 75 65 6e 74 20 61 72 67 76 5b 5d 20 0d 0a 20 20  uent argv[] ..  
ceb0: 20 20 20 20 20 20 2f 2f 2f 20 65 6e 74 72 69 65        /// entrie
cec0: 73 20 63 6f 6e 74 61 69 6e 20 76 61 6c 75 65 73  s contain values
ced0: 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 20   of the columns 
cee0: 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  of the virtual t
cef0: 61 62 6c 65 2c 20 69 6e 20 74 68 65 20 0d 0a 20  able, in the .. 
cf00: 20 20 20 20 20 20 20 2f 2f 2f 20 6f 72 64 65 72         /// order
cf10: 20 74 68 61 74 20 74 68 65 20 63 6f 6c 75 6d 6e   that the column
cf20: 73 20 77 65 72 65 20 64 65 63 6c 61 72 65 64 2e  s were declared.
cf30: 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   The number of c
cf40: 6f 6c 75 6d 6e 73 20 77 69 6c 6c 0d 0a 20 20 20  olumns will..   
cf50: 20 20 20 20 20 2f 2f 2f 20 6d 61 74 63 68 20 74       /// match t
cf60: 68 65 20 74 61 62 6c 65 20 64 65 63 6c 61 72 61  he table declara
cf70: 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20 78 43  tion that the xC
cf80: 6f 6e 6e 65 63 74 20 6f 72 20 78 43 72 65 61 74  onnect or xCreat
cf90: 65 20 6d 65 74 68 6f 64 20 6d 61 64 65 20 0d 0a  e method made ..
cfa0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 75 73 69 6e          /// usin
cfb0: 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 64 65  g the sqlite3_de
cfc0: 63 6c 61 72 65 5f 76 74 61 62 28 29 20 63 61 6c  clare_vtab() cal
cfd0: 6c 2e 20 20 41 6c 6c 20 68 69 64 64 65 6e 20 63  l.  All hidden c
cfe0: 6f 6c 75 6d 6e 73 20 61 72 65 20 69 6e 63 6c 75  olumns are inclu
cff0: 64 65 64 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ded...        //
d000: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  / </para>..     
d010: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20     /// <para>.. 
d020: 20 20 20 20 20 20 20 2f 2f 2f 20 57 68 65 6e 20         /// When 
d030: 64 6f 69 6e 67 20 61 6e 20 69 6e 73 65 72 74 20  doing an insert 
d040: 77 69 74 68 6f 75 74 20 61 20 72 6f 77 69 64 20  without a rowid 
d050: 28 61 72 67 63 3e 31 2c 20 61 72 67 76 5b 31 5d  (argc>1, argv[1]
d060: 20 69 73 20 61 6e 20 53 51 4c 20 4e 55 4c 4c 29   is an SQL NULL)
d070: 2c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6f  ,..        /// o
d080: 6e 20 61 20 76 69 72 74 75 61 6c 20 74 61 62 6c  n a virtual tabl
d090: 65 20 74 68 61 74 20 75 73 65 73 20 52 4f 57 49  e that uses ROWI
d0a0: 44 20 28 62 75 74 20 6e 6f 74 20 6f 6e 20 61 20  D (but not on a 
d0b0: 57 49 54 48 4f 55 54 20 52 4f 57 49 44 20 76 69  WITHOUT ROWID vi
d0c0: 72 74 75 61 6c 20 74 61 62 6c 65 2c 0d 0a 20 20  rtual table,..  
d0d0: 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 20 69 6d        /// the im
d0e0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73  plementation mus
d0f0: 74 20 73 65 74 20 2a 70 52 6f 77 69 64 20 74 6f  t set *pRowid to
d100: 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68   the rowid of th
d110: 65 20 6e 65 77 6c 79 20 69 6e 73 65 72 74 65 64  e newly inserted
d120: 20 72 6f 77 3b 20 0d 0a 20 20 20 20 20 20 20 20   row; ..        
d130: 2f 2f 2f 20 74 68 69 73 20 77 69 6c 6c 20 62 65  /// this will be
d140: 63 6f 6d 65 20 74 68 65 20 76 61 6c 75 65 20 72  come the value r
d150: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73  eturned by the s
d160: 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
d170: 72 74 5f 72 6f 77 69 64 28 29 0d 0a 20 20 20 20  rt_rowid()..    
d180: 20 20 20 20 2f 2f 2f 20 66 75 6e 63 74 69 6f 6e      /// function
d190: 2e 20 53 65 74 74 69 6e 67 20 74 68 69 73 20 76  . Setting this v
d1a0: 61 6c 75 65 20 69 6e 20 61 6c 6c 20 74 68 65 20  alue in all the 
d1b0: 6f 74 68 65 72 20 63 61 73 65 73 20 69 73 20 61  other cases is a
d1c0: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 3b   harmless no-op;
d1d0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68  ..        /// th
d1e0: 65 20 53 51 4c 69 74 65 20 65 6e 67 69 6e 65 20  e SQLite engine 
d1f0: 69 67 6e 6f 72 65 73 20 74 68 65 20 2a 70 52 6f  ignores the *pRo
d200: 77 69 64 20 72 65 74 75 72 6e 20 76 61 6c 75 65  wid return value
d210: 20 69 66 20 61 72 67 63 3d 3d 31 20 6f 72 20 0d   if argc==1 or .
d220: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 61 72 67  .        /// arg
d230: 76 5b 31 5d 20 69 73 20 6e 6f 74 20 61 6e 20 53  v[1] is not an S
d240: 51 4c 20 4e 55 4c 4c 2e 0d 0a 20 20 20 20 20 20  QL NULL...      
d250: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
d260: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
d270: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 45  >..        /// E
d280: 61 63 68 20 63 61 6c 6c 20 74 6f 20 78 55 70 64  ach call to xUpd
d290: 61 74 65 20 77 69 6c 6c 20 66 61 6c 6c 20 69 6e  ate will fall in
d2a0: 74 6f 20 6f 6e 65 20 6f 66 20 63 61 73 65 73 20  to one of cases 
d2b0: 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0d 0a 20 20  shown below...  
d2c0: 20 20 20 20 20 20 2f 2f 2f 20 4e 6f 74 20 74 68        /// Not th
d2d0: 61 74 20 72 65 66 65 72 65 6e 63 65 73 20 74 6f  at references to
d2e0: 20 3c 21 5b 43 44 41 54 41 5b 3c 62 3e 5d 5d 3e   <![CDATA[<b>]]>
d2f0: 61 72 67 76 5b 69 5d 3c 21 5b 43 44 41 54 41 5b  argv[i]<![CDATA[
d300: 3c 2f 62 3e 5d 5d 3e 20 6d 65 61 6e 20 74 68 65  </b>]]> mean the
d310: 20 53 51 4c 20 76 61 6c 75 65 0d 0a 20 20 20 20   SQL value..    
d320: 20 20 20 20 2f 2f 2f 20 68 65 6c 64 20 77 69 74      /// held wit
d330: 68 69 6e 20 74 68 65 20 61 72 67 76 5b 69 5d 20  hin the argv[i] 
d340: 6f 62 6a 65 63 74 2c 20 6e 6f 74 20 74 68 65 20  object, not the 
d350: 61 72 67 76 5b 69 5d 0d 0a 20 20 20 20 20 20 20  argv[i]..       
d360: 20 2f 2f 2f 20 6f 62 6a 65 63 74 20 69 74 73 65   /// object itse
d370: 6c 66 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  lf...        ///
d380: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
d390: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64    /// <para><cod
d3a0: 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e>..        /// 
d3b0: 3c 21 5b 43 44 41 54 41 5b 3c 64 6c 3e 5d 5d 3e  <![CDATA[<dl>]]>
d3c0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 21  ..        /// <!
d3d0: 5b 43 44 41 54 41 5b 3c 64 74 3e 5d 5d 3e 3c 21  [CDATA[<dt>]]><!
d3e0: 5b 43 44 41 54 41 5b 3c 62 3e 5d 5d 3e 61 72 67  [CDATA[<b>]]>arg
d3f0: 63 20 3d 20 31 20 3c 21 5b 43 44 41 54 41 5b 3c  c = 1 <![CDATA[<
d400: 62 72 3e 5d 5d 3e 20 61 72 67 76 5b 30 5d 20 26  br>]]> argv[0] &
d410: 23 38 38 30 30 3b 20 4e 55 4c 4c 3c 21 5b 43 44  #8800; NULL<![CD
d420: 41 54 41 5b 3c 2f 62 3e 5d 5d 3e 0d 0a 20 20 20  ATA[</b>]]>..   
d430: 20 20 20 20 20 2f 2f 2f 20 3c 21 5b 43 44 41 54       /// <![CDAT
d440: 41 5b 3c 2f 64 74 3e 5d 5d 3e 3c 21 5b 43 44 41  A[</dt>]]><![CDA
d450: 54 41 5b 3c 64 64 3e 5d 5d 3e 0d 0a 20 20 20 20  TA[<dd>]]>..    
d460: 20 20 20 20 2f 2f 2f 20 54 68 65 20 73 69 6e 67      /// The sing
d470: 6c 65 20 72 6f 77 20 77 69 74 68 20 72 6f 77 69  le row with rowi
d480: 64 20 6f 72 20 50 52 49 4d 41 52 59 20 4b 45 59  d or PRIMARY KEY
d490: 20 65 71 75 61 6c 20 74 6f 20 61 72 67 76 5b 30   equal to argv[0
d4a0: 5d 20 69 73 20 64 65 6c 65 74 65 64 2e 20 0d 0a  ] is deleted. ..
d4b0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 4e 6f 20 69          /// No i
d4c0: 6e 73 65 72 74 20 6f 63 63 75 72 73 2e 0d 0a 20  nsert occurs... 
d4d0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 21 5b 43 44         /// <![CD
d4e0: 41 54 41 5b 3c 2f 64 64 3e 5d 5d 3e 3c 21 5b 43  ATA[</dd>]]><![C
d4f0: 44 41 54 41 5b 3c 64 74 3e 5d 5d 3e 3c 21 5b 43  DATA[<dt>]]><![C
d500: 44 41 54 41 5b 3c 62 3e 5d 5d 3e 61 72 67 63 20  DATA[<b>]]>argc 
d510: 26 67 74 3b 20 31 20 3c 21 5b 43 44 41 54 41 5b  &gt; 1 <![CDATA[
d520: 3c 62 72 3e 5d 5d 3e 20 61 72 67 76 5b 30 5d 20  <br>]]> argv[0] 
d530: 3d 20 4e 55 4c 4c 3c 21 5b 43 44 41 54 41 5b 3c  = NULL<![CDATA[<
d540: 2f 62 3e 5d 5d 3e 0d 0a 20 20 20 20 20 20 20 20  /b>]]>..        
d550: 2f 2f 2f 20 3c 21 5b 43 44 41 54 41 5b 3c 2f 64  /// <![CDATA[</d
d560: 74 3e 5d 5d 3e 3c 21 5b 43 44 41 54 41 5b 3c 64  t>]]><![CDATA[<d
d570: 64 3e 5d 5d 3e 0d 0a 20 20 20 20 20 20 20 20 2f  d>]]>..        /
d580: 2f 2f 20 41 20 6e 65 77 20 72 6f 77 20 69 73 20  // A new row is 
d590: 69 6e 73 65 72 74 65 64 20 77 69 74 68 20 63 6f  inserted with co
d5a0: 6c 75 6d 6e 20 76 61 6c 75 65 73 20 74 61 6b 65  lumn values take
d5b0: 6e 20 66 72 6f 6d 0d 0a 20 20 20 20 20 20 20 20  n from..        
d5c0: 2f 2f 2f 20 61 72 67 76 5b 32 5d 20 61 6e 64 20  /// argv[2] and 
d5d0: 66 6f 6c 6c 6f 77 69 6e 67 2e 20 20 49 6e 20 61  following.  In a
d5e0: 20 72 6f 77 69 64 20 76 69 72 74 75 61 6c 20 74   rowid virtual t
d5f0: 61 62 6c 65 2c 20 69 66 20 61 72 67 76 5b 31 5d  able, if argv[1]
d600: 20 69 73 20 61 6e 20 53 51 4c 20 4e 55 4c 4c 2c   is an SQL NULL,
d610: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68  ..        /// th
d620: 65 6e 20 61 20 6e 65 77 20 75 6e 69 71 75 65 20  en a new unique 
d630: 72 6f 77 69 64 20 69 73 20 67 65 6e 65 72 61 74  rowid is generat
d640: 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
d650: 2e 20 20 54 68 65 20 61 72 67 76 5b 31 5d 20 77  .  The argv[1] w
d660: 69 6c 6c 20 62 65 20 4e 55 4c 4c 0d 0a 20 20 20  ill be NULL..   
d670: 20 20 20 20 20 2f 2f 2f 20 66 6f 72 20 61 20 57       /// for a W
d680: 49 54 48 4f 55 54 20 52 4f 57 49 44 20 76 69 72  ITHOUT ROWID vir
d690: 74 75 61 6c 20 74 61 62 6c 65 2c 20 69 6e 20 77  tual table, in w
d6a0: 68 69 63 68 20 63 61 73 65 20 74 68 65 20 69 6d  hich case the im
d6b0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
d6c0: 75 6c 64 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  uld..        ///
d6d0: 20 74 61 6b 65 20 74 68 65 20 50 52 49 4d 41 52   take the PRIMAR
d6e0: 59 20 4b 45 59 20 76 61 6c 75 65 20 66 72 6f 6d  Y KEY value from
d6f0: 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65   the appropriate
d700: 20 63 6f 6c 75 6d 6e 20 69 6e 20 61 72 67 76 5b   column in argv[
d710: 32 5d 20 61 6e 64 20 66 6f 6c 6c 6f 77 69 6e 67  2] and following
d720: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
d730: 21 5b 43 44 41 54 41 5b 3c 2f 64 64 3e 5d 5d 3e  ![CDATA[</dd>]]>
d740: 3c 21 5b 43 44 41 54 41 5b 3c 64 74 3e 5d 5d 3e  <![CDATA[<dt>]]>
d750: 3c 21 5b 43 44 41 54 41 5b 3c 62 3e 5d 5d 3e 61  <![CDATA[<b>]]>a
d760: 72 67 63 20 26 67 74 3b 20 31 20 3c 21 5b 43 44  rgc &gt; 1 <![CD
d770: 41 54 41 5b 3c 62 72 3e 5d 5d 3e 20 61 72 67 76  ATA[<br>]]> argv
d780: 5b 30 5d 20 26 23 38 38 30 30 3b 20 4e 55 4c 4c  [0] &#8800; NULL
d790: 20 3c 21 5b 43 44 41 54 41 5b 3c 62 72 3e 5d 5d   <![CDATA[<br>]]
d7a0: 3e 20 61 72 67 76 5b 30 5d 20 3d 20 61 72 67 76  > argv[0] = argv
d7b0: 5b 31 5d 3c 21 5b 43 44 41 54 41 5b 3c 2f 62 3e  [1]<![CDATA[</b>
d7c0: 5d 5d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ]]>..        ///
d7d0: 20 3c 21 5b 43 44 41 54 41 5b 3c 2f 64 74 3e 5d   <![CDATA[</dt>]
d7e0: 5d 3e 3c 21 5b 43 44 41 54 41 5b 3c 64 64 3e 5d  ]><![CDATA[<dd>]
d7f0: 5d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ]>..        /// 
d800: 54 68 65 20 72 6f 77 20 77 69 74 68 20 72 6f 77  The row with row
d810: 69 64 20 6f 72 20 50 52 49 4d 41 52 59 20 4b 45  id or PRIMARY KE
d820: 59 20 61 72 67 76 5b 30 5d 20 69 73 20 75 70 64  Y argv[0] is upd
d830: 61 74 65 64 20 77 69 74 68 20 6e 65 77 20 76 61  ated with new va
d840: 6c 75 65 73 20 0d 0a 20 20 20 20 20 20 20 20 2f  lues ..        /
d850: 2f 2f 20 69 6e 20 61 72 67 76 5b 32 5d 20 61 6e  // in argv[2] an
d860: 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 61 72 61  d following para
d870: 6d 65 74 65 72 73 2e 0d 0a 20 20 20 20 20 20 20  meters...       
d880: 20 2f 2f 2f 20 3c 21 5b 43 44 41 54 41 5b 3c 2f   /// <![CDATA[</
d890: 64 64 3e 5d 5d 3e 3c 21 5b 43 44 41 54 41 5b 3c  dd>]]><![CDATA[<
d8a0: 64 74 3e 5d 5d 3e 3c 21 5b 43 44 41 54 41 5b 3c  dt>]]><![CDATA[<
d8b0: 62 3e 5d 5d 3e 61 72 67 63 20 26 67 74 3b 20 31  b>]]>argc &gt; 1
d8c0: 20 3c 21 5b 43 44 41 54 41 5b 3c 62 72 3e 5d 5d   <![CDATA[<br>]]
d8d0: 3e 20 61 72 67 76 5b 30 5d 20 26 23 38 38 30 30  > argv[0] &#8800
d8e0: 3b 20 4e 55 4c 4c 20 3c 21 5b 43 44 41 54 41 5b  ; NULL <![CDATA[
d8f0: 3c 62 72 3e 5d 5d 3e 20 61 72 67 76 5b 30 5d 20  <br>]]> argv[0] 
d900: 26 23 38 38 30 30 3b 20 61 72 67 76 5b 31 5d 3c  &#8800; argv[1]<
d910: 21 5b 43 44 41 54 41 5b 3c 2f 62 3e 5d 5d 3e 0d  ![CDATA[</b>]]>.
d920: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 21 5b  .        /// <![
d930: 43 44 41 54 41 5b 3c 2f 64 74 3e 5d 5d 3e 3c 21  CDATA[</dt>]]><!
d940: 5b 43 44 41 54 41 5b 3c 64 64 3e 5d 5d 3e 20 54  [CDATA[<dd>]]> T
d950: 68 65 20 72 6f 77 20 77 69 74 68 20 72 6f 77 69  he row with rowi
d960: 64 20 6f 72 20 50 52 49 4d 41 52 59 20 4b 45 59  d or PRIMARY KEY
d970: 20 61 72 67 76 5b 30 5d 20 69 73 20 75 70 64 61   argv[0] is upda
d980: 74 65 64 20 77 69 74 68 20 0d 0a 20 20 20 20 20  ted with ..     
d990: 20 20 20 2f 2f 2f 20 74 68 65 20 72 6f 77 69 64     /// the rowid
d9a0: 20 6f 72 20 50 52 49 4d 41 52 59 20 4b 45 59 20   or PRIMARY KEY 
d9b0: 69 6e 20 61 72 67 76 5b 31 5d 20 0d 0a 20 20 20  in argv[1] ..   
d9c0: 20 20 20 20 20 2f 2f 2f 20 61 6e 64 20 6e 65 77       /// and new
d9d0: 20 76 61 6c 75 65 73 20 69 6e 20 61 72 67 76 5b   values in argv[
d9e0: 32 5d 20 61 6e 64 20 66 6f 6c 6c 6f 77 69 6e 67  2] and following
d9f0: 20 70 61 72 61 6d 65 74 65 72 73 2e 20 54 68 69   parameters. Thi
da00: 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 0d 0a 20  s will occur .. 
da10: 20 20 20 20 20 20 20 2f 2f 2f 20 77 68 65 6e 20         /// when 
da20: 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
da30: 20 75 70 64 61 74 65 73 20 61 20 72 6f 77 69 64   updates a rowid
da40: 2c 20 61 73 20 69 6e 20 74 68 65 20 73 74 61 74  , as in the stat
da50: 65 6d 65 6e 74 3a 0d 0a 20 20 20 20 20 20 20 20  ement:..        
da60: 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e  /// <para><code>
da70: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20  ..        ///   
da80: 20 55 50 44 41 54 45 20 74 61 62 6c 65 20 53 45   UPDATE table SE
da90: 54 20 72 6f 77 69 64 3d 72 6f 77 69 64 2b 31 20  T rowid=rowid+1 
daa0: 57 48 45 52 45 20 2e 2e 2e 3b 20 0d 0a 20 20 20  WHERE ...; ..   
dab0: 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e       /// </code>
dac0: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
dad0: 20 2f 2f 2f 20 3c 21 5b 43 44 41 54 41 5b 3c 2f   /// <![CDATA[</
dae0: 64 64 3e 5d 5d 3e 3c 21 5b 43 44 41 54 41 5b 3c  dd>]]><![CDATA[<
daf0: 2f 64 6c 3e 5d 5d 3e 0d 0a 20 20 20 20 20 20 20  /dl>]]>..       
db00: 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61   /// </code></pa
db10: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
db20: 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20   <para>..       
db30: 20 2f 2f 2f 20 54 68 65 20 78 55 70 64 61 74 65   /// The xUpdate
db40: 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 72 65 74   method must ret
db50: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
db60: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 69 74 20   and only if it 
db70: 69 73 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  is..        /// 
db80: 73 75 63 63 65 73 73 66 75 6c 2e 20 20 49 66 20  successful.  If 
db90: 61 20 66 61 69 6c 75 72 65 20 6f 63 63 75 72 73  a failure occurs
dba0: 2c 20 74 68 65 20 78 55 70 64 61 74 65 20 6d 75  , the xUpdate mu
dbb0: 73 74 20 72 65 74 75 72 6e 20 61 6e 20 61 70 70  st return an app
dbc0: 72 6f 70 72 69 61 74 65 0d 0a 20 20 20 20 20 20  ropriate..      
dbd0: 20 20 2f 2f 2f 20 65 72 72 6f 72 20 63 6f 64 65    /// error code
dbe0: 2e 20 20 4f 6e 20 61 20 66 61 69 6c 75 72 65 2c  .  On a failure,
dbf0: 20 74 68 65 20 70 56 54 61 62 2d 3e 7a 45 72 72   the pVTab->zErr
dc00: 4d 73 67 20 65 6c 65 6d 65 6e 74 20 6d 61 79 20  Msg element may 
dc10: 6f 70 74 69 6f 6e 61 6c 6c 79 0d 0a 20 20 20 20  optionally..    
dc20: 20 20 20 20 2f 2f 2f 20 62 65 20 72 65 70 6c 61      /// be repla
dc30: 63 65 64 20 77 69 74 68 20 65 72 72 6f 72 20 6d  ced with error m
dc40: 65 73 73 61 67 65 20 74 65 78 74 20 73 74 6f 72  essage text stor
dc50: 65 64 20 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  ed in memory all
dc60: 6f 63 61 74 65 64 20 66 72 6f 6d 20 53 51 4c 69  ocated from SQLi
dc70: 74 65 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  te ..        ///
dc80: 20 75 73 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73   using functions
dc90: 20 73 75 63 68 20 61 73 20 73 71 6c 69 74 65 33   such as sqlite3
dca0: 5f 6d 70 72 69 6e 74 66 28 29 20 6f 72 20 73 71  _mprintf() or sq
dcb0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2e 0d  lite3_malloc()..
dcc0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
dcd0: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
dce0: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
dcf0: 20 20 2f 2f 2f 20 49 66 20 74 68 65 20 78 55 70    /// If the xUp
dd00: 64 61 74 65 20 6d 65 74 68 6f 64 20 76 69 6f 6c  date method viol
dd10: 61 74 65 73 20 73 6f 6d 65 20 63 6f 6e 73 74 72  ates some constr
dd20: 61 69 6e 74 20 6f 66 20 74 68 65 20 76 69 72 74  aint of the virt
dd30: 75 61 6c 20 74 61 62 6c 65 0d 0a 20 20 20 20 20  ual table..     
dd40: 20 20 20 2f 2f 2f 20 28 69 6e 63 6c 75 64 69 6e     /// (includin
dd50: 67 2c 20 62 75 74 20 6e 6f 74 20 6c 69 6d 69 74  g, but not limit
dd60: 65 64 20 74 6f 2c 20 61 74 74 65 6d 70 74 69 6e  ed to, attemptin
dd70: 67 20 74 6f 20 73 74 6f 72 65 20 61 20 76 61 6c  g to store a val
dd80: 75 65 20 6f 66 20 74 68 65 20 77 72 6f 6e 67 20  ue of the wrong 
dd90: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 64 61  ..        /// da
dda0: 74 61 74 79 70 65 2c 20 61 74 74 65 6d 70 74 69  tatype, attempti
ddb0: 6e 67 20 74 6f 20 73 74 6f 72 65 20 61 20 76 61  ng to store a va
ddc0: 6c 75 65 20 74 68 61 74 20 69 73 20 74 6f 6f 0d  lue that is too.
ddd0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6c 61 72  .        /// lar
dde0: 67 65 20 6f 72 20 74 6f 6f 20 73 6d 61 6c 6c 2c  ge or too small,
ddf0: 20 6f 72 20 61 74 74 65 6d 70 74 69 6e 67 20 74   or attempting t
de00: 6f 20 63 68 61 6e 67 65 20 61 20 72 65 61 64 2d  o change a read-
de10: 6f 6e 6c 79 20 76 61 6c 75 65 29 20 74 68 65 6e  only value) then
de20: 20 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f   the..        //
de30: 2f 20 78 55 70 64 61 74 65 20 6d 75 73 74 20 66  / xUpdate must f
de40: 61 69 6c 20 77 69 74 68 20 61 6e 20 61 70 70 72  ail with an appr
de50: 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 63 6f  opriate error co
de60: 64 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  de...        ///
de70: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
de80: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
de90: 20 20 20 20 20 20 2f 2f 2f 20 49 66 20 74 68 65        /// If the
dea0: 20 78 55 70 64 61 74 65 20 6d 65 74 68 6f 64 20   xUpdate method 
deb0: 69 73 20 70 65 72 66 6f 72 6d 69 6e 67 20 61 6e  is performing an
dec0: 20 55 50 44 41 54 45 2c 20 74 68 65 6e 0d 0a 20   UPDATE, then.. 
ded0: 20 20 20 20 20 20 20 2f 2f 2f 20 73 71 6c 69 74         /// sqlit
dee0: 65 33 5f 76 61 6c 75 65 5f 6e 6f 63 68 61 6e 67  e3_value_nochang
def0: 65 28 58 29 20 63 61 6e 20 62 65 20 75 73 65 64  e(X) can be used
df00: 20 74 6f 20 64 69 73 63 6f 76 65 72 20 77 68 69   to discover whi
df10: 63 68 20 63 6f 6c 75 6d 6e 73 0d 0a 20 20 20 20  ch columns..    
df20: 20 20 20 20 2f 2f 2f 20 6f 66 20 74 68 65 20 76      /// of the v
df30: 69 72 74 75 61 6c 20 74 61 62 6c 65 20 77 65 72  irtual table wer
df40: 65 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66  e actually modif
df50: 69 65 64 20 62 79 20 74 68 65 20 55 50 44 41 54  ied by the UPDAT
df60: 45 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73  E..        /// s
df70: 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 65 20 73  tatement.  The s
df80: 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 6f 63  qlite3_value_noc
df90: 68 61 6e 67 65 28 58 29 20 69 6e 74 65 72 66 61  hange(X) interfa
dfa0: 63 65 20 72 65 74 75 72 6e 73 0d 0a 20 20 20 20  ce returns..    
dfb0: 20 20 20 20 2f 2f 2f 20 74 72 75 65 20 66 6f 72      /// true for
dfc0: 20 63 6f 6c 75 6d 6e 73 20 74 68 61 74 20 64 6f   columns that do
dfd0: 20 6e 6f 74 20 63 68 61 6e 67 65 2e 0d 0a 20 20   not change...  
dfe0: 20 20 20 20 20 20 2f 2f 2f 20 4f 6e 20 65 76 65        /// On eve
dff0: 72 79 20 55 50 44 41 54 45 2c 20 53 51 4c 69 74  ry UPDATE, SQLit
e000: 65 20 77 69 6c 6c 20 66 69 72 73 74 20 69 6e 76  e will first inv
e010: 6f 6b 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  oke..        ///
e020: 20 78 43 6f 6c 75 6d 6e 20 73 65 70 61 72 61 74   xColumn separat
e030: 65 6c 79 20 66 6f 72 20 65 61 63 68 20 75 6e 63  ely for each unc
e040: 68 61 6e 67 69 6e 67 20 63 6f 6c 75 6d 6e 20 69  hanging column i
e050: 6e 20 74 68 65 20 74 61 62 6c 65 20 74 6f 20 0d  n the table to .
e060: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6f 62 74  .        /// obt
e070: 61 69 6e 20 74 68 65 20 76 61 6c 75 65 20 66 6f  ain the value fo
e080: 72 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2e 20 20  r that column.  
e090: 54 68 65 20 78 43 6f 6c 75 6d 6e 20 6d 65 74 68  The xColumn meth
e0a0: 6f 64 20 63 61 6e 0d 0a 20 20 20 20 20 20 20 20  od can..        
e0b0: 2f 2f 2f 20 63 68 65 63 6b 20 74 6f 20 73 65 65  /// check to see
e0c0: 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   if the column i
e0d0: 73 20 75 6e 63 68 61 6e 67 65 64 20 61 74 20 74  s unchanged at t
e0e0: 68 65 20 53 51 4c 20 6c 65 76 65 6c 0d 0a 20 20  he SQL level..  
e0f0: 20 20 20 20 20 20 2f 2f 2f 20 62 79 20 69 6e 76        /// by inv
e100: 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 76 74  oking sqlite3_vt
e110: 61 62 5f 6e 6f 63 68 61 6e 67 65 28 29 2e 20 20  ab_nochange().  
e120: 49 66 20 78 43 6f 6c 75 6d 6e 20 73 65 65 73 20  If xColumn sees 
e130: 74 68 61 74 0d 0a 20 20 20 20 20 20 20 20 2f 2f  that..        //
e140: 2f 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  / the column is 
e150: 6e 6f 74 20 62 65 69 6e 67 20 6d 6f 64 69 66 69  not being modifi
e160: 65 64 2c 20 69 74 20 73 68 6f 75 6c 64 20 72 65  ed, it should re
e170: 74 75 72 6e 20 77 69 74 68 6f 75 74 20 73 65 74  turn without set
e180: 74 69 6e 67 20 0d 0a 20 20 20 20 20 20 20 20 2f  ting ..        /
e190: 2f 2f 20 61 20 72 65 73 75 6c 74 20 75 73 69 6e  // a result usin
e1a0: 67 20 6f 6e 65 20 6f 66 20 74 68 65 20 73 71 6c  g one of the sql
e1b0: 69 74 65 33 5f 72 65 73 75 6c 74 5f 78 78 78 78  ite3_result_xxxx
e1c0: 78 28 29 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  x()..        ///
e1d0: 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 4f 6e   interfaces.  On
e1e0: 6c 79 20 69 6e 20 74 68 61 74 20 63 61 73 65 20  ly in that case 
e1f0: 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 6f  sqlite3_value_no
e200: 63 68 61 6e 67 65 28 29 20 77 69 6c 6c 20 62 65  change() will be
e210: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 72  ..        /// tr
e220: 75 65 20 77 69 74 68 69 6e 20 74 68 65 20 78 55  ue within the xU
e230: 70 64 61 74 65 20 6d 65 74 68 6f 64 2e 20 20 49  pdate method.  I
e240: 66 20 78 43 6f 6c 75 6d 6e 20 64 6f 65 73 0d 0a  f xColumn does..
e250: 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e 76 6f          /// invo
e260: 6b 65 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73  ke one or more s
e270: 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 78 78  qlite3_result_xx
e280: 78 78 78 28 29 0d 0a 20 20 20 20 20 20 20 20 2f  xxx()..        /
e290: 2f 2f 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  // interfaces, t
e2a0: 68 65 6e 20 53 51 4c 69 74 65 20 75 6e 64 65 72  hen SQLite under
e2b0: 73 74 61 6e 64 73 20 74 68 61 74 20 61 73 20 61  stands that as a
e2c0: 20 63 68 61 6e 67 65 20 69 6e 20 74 68 65 20 76   change in the v
e2d0: 61 6c 75 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f  alue..        //
e2e0: 2f 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  / of the column 
e2f0: 61 6e 64 20 74 68 65 20 73 71 6c 69 74 65 33 5f  and the sqlite3_
e300: 76 61 6c 75 65 5f 6e 6f 63 68 61 6e 67 65 28 29  value_nochange()
e310: 20 63 61 6c 6c 20 66 6f 72 20 74 68 61 74 0d 0a   call for that..
e320: 20 20 20 20 20 20 20 20 2f 2f 2f 20 63 6f 6c 75          /// colu
e330: 6d 6e 20 77 69 74 68 69 6e 20 78 55 70 64 61 74  mn within xUpdat
e340: 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 66 61  e will return fa
e350: 6c 73 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  lse...        //
e360: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  / </para>..     
e370: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20     /// <para>.. 
e380: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 72 65         /// There
e390: 20 6d 69 67 68 74 20 62 65 20 6f 6e 65 20 6f 72   might be one or
e3a0: 20 6d 6f 72 65 20 73 71 6c 69 74 65 33 5f 76 74   more sqlite3_vt
e3b0: 61 62 5f 63 75 72 73 6f 72 20 6f 62 6a 65 63 74  ab_cursor object
e3c0: 73 20 6f 70 65 6e 20 61 6e 64 20 69 6e 20 75 73  s open and in us
e3d0: 65 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e ..        /// 
e3e0: 6f 6e 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  on the virtual t
e3f0: 61 62 6c 65 20 69 6e 73 74 61 6e 63 65 20 61 6e  able instance an
e400: 64 20 70 65 72 68 61 70 73 20 65 76 65 6e 20 6f  d perhaps even o
e410: 6e 20 74 68 65 20 72 6f 77 20 6f 66 20 74 68 65  n the row of the
e420: 20 76 69 72 74 75 61 6c 0d 0a 20 20 20 20 20 20   virtual..      
e430: 20 20 2f 2f 2f 20 74 61 62 6c 65 20 77 68 65 6e    /// table when
e440: 20 74 68 65 20 78 55 70 64 61 74 65 20 6d 65 74   the xUpdate met
e450: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  hod is invoked. 
e460: 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
e470: 69 6f 6e 20 6f 66 0d 0a 20 20 20 20 20 20 20 20  ion of..        
e480: 2f 2f 2f 20 78 55 70 64 61 74 65 20 6d 75 73 74  /// xUpdate must
e490: 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72   be prepared for
e4a0: 20 61 74 74 65 6d 70 74 73 20 74 6f 20 64 65 6c   attempts to del
e4b0: 65 74 65 20 6f 72 20 6d 6f 64 69 66 79 20 72 6f  ete or modify ro
e4c0: 77 73 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0d  ws of the table.
e4d0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6f 75 74  .        /// out
e4e0: 20 66 72 6f 6d 20 6f 74 68 65 72 20 65 78 69 73   from other exis
e4f0: 74 69 6e 67 20 63 75 72 73 6f 72 73 2e 20 20 49  ting cursors.  I
e500: 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  f the virtual ta
e510: 62 6c 65 20 63 61 6e 6e 6f 74 20 61 63 63 6f 6d  ble cannot accom
e520: 6d 6f 64 61 74 65 0d 0a 20 20 20 20 20 20 20 20  modate..        
e530: 2f 2f 2f 20 73 75 63 68 20 63 68 61 6e 67 65 73  /// such changes
e540: 2c 20 74 68 65 20 78 55 70 64 61 74 65 20 6d 65  , the xUpdate me
e550: 74 68 6f 64 20 6d 75 73 74 20 72 65 74 75 72 6e  thod must return
e560: 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 2e 0d   an error code..
e570: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
e580: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
e590: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
e5a0: 20 20 2f 2f 2f 20 54 68 65 20 78 55 70 64 61 74    /// The xUpdat
e5b0: 65 20 6d 65 74 68 6f 64 20 69 73 20 6f 70 74 69  e method is opti
e5c0: 6f 6e 61 6c 2e 0d 0a 20 20 20 20 20 20 20 20 2f  onal...        /
e5d0: 2f 2f 20 49 66 20 74 68 65 20 78 55 70 64 61 74  // If the xUpdat
e5e0: 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65  e pointer in the
e5f0: 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
e600: 66 6f 72 20 61 20 76 69 72 74 75 61 6c 20 74 61  for a virtual ta
e610: 62 6c 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ble..        ///
e620: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
e630: 65 72 2c 20 74 68 65 6e 20 74 68 65 20 76 69 72  er, then the vir
e640: 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20 72 65  tual table is re
e650: 61 64 2d 6f 6e 6c 79 2e 0d 0a 20 20 20 20 20 20  ad-only...      
e660: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
e670: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d         /// </sum
e680: 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f  mary>..        /
e690: 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22  // <param name="
e6a0: 70 56 74 61 62 22 3e 0d 0a 20 20 20 20 20 20 20  pVtab">..       
e6b0: 20 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76 65 20   /// The native 
e6c0: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73  pointer to the s
e6d0: 71 6c 69 74 65 33 5f 76 74 61 62 20 64 65 72 69  qlite3_vtab deri
e6e0: 76 65 64 20 73 74 72 75 63 74 75 72 65 2e 0d 0a  ved structure...
e6f0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
e700: 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ram>..        //
e710: 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 61  / <param name="a
e720: 72 67 63 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f  rgc">..        /
e730: 2f 2f 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  // The number of
e740: 20 6e 65 77 20 6f 72 20 6d 6f 64 69 66 69 65 64   new or modified
e750: 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 20 63   column values c
e760: 6f 6e 74 61 69 6e 65 64 20 69 6e 0d 0a 20 20 20  ontained in..   
e770: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 72       /// <paramr
e780: 65 66 20 6e 61 6d 65 3d 22 61 72 67 76 22 20 2f  ef name="argv" /
e790: 3e 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  >...        /// 
e7a0: 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20  </param>..      
e7b0: 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d    /// <param nam
e7c0: 65 3d 22 61 72 67 76 22 3e 0d 0a 20 20 20 20 20  e="argv">..     
e7d0: 20 20 20 2f 2f 2f 20 54 68 65 20 61 72 72 61 79     /// The array
e7e0: 20 6f 66 20 6e 61 74 69 76 65 20 70 6f 69 6e 74   of native point
e7f0: 65 72 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 76  ers to sqlite3_v
e800: 61 6c 75 65 20 73 74 72 75 63 74 75 72 65 73 20  alue structures 
e810: 63 6f 6e 74 61 69 6e 69 6e 67 0d 0a 20 20 20 20  containing..    
e820: 20 20 20 20 2f 2f 2f 20 74 68 65 20 6e 65 77 20      /// the new 
e830: 6f 72 20 6d 6f 64 69 66 69 65 64 20 63 6f 6c 75  or modified colu
e840: 6d 6e 20 76 61 6c 75 65 73 2c 20 69 66 20 61 6e  mn values, if an
e850: 79 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  y...        /// 
e860: 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20  </param>..      
e870: 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d    /// <param nam
e880: 65 3d 22 72 6f 77 49 64 22 3e 0d 0a 20 20 20 20  e="rowId">..    
e890: 20 20 20 20 2f 2f 2f 20 55 70 6f 6e 20 73 75 63      /// Upon suc
e8a0: 63 65 73 73 2c 20 74 68 69 73 20 70 61 72 61 6d  cess, this param
e8b0: 65 74 65 72 20 6d 75 73 74 20 62 65 20 6d 6f 64  eter must be mod
e8c0: 69 66 69 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e  ified to contain
e8d0: 20 74 68 65 20 75 6e 69 71 75 65 0d 0a 20 20 20   the unique..   
e8e0: 20 20 20 20 20 2f 2f 2f 20 69 6e 74 65 67 65 72       /// integer
e8f0: 20 72 6f 77 20 69 64 65 6e 74 69 66 69 65 72 20   row identifier 
e900: 66 6f 72 20 74 68 65 20 72 6f 77 20 74 68 61 74  for the row that
e910: 20 77 61 73 20 69 6e 73 65 72 74 65 64 2c 20 69   was inserted, i
e920: 66 20 61 6e 79 2e 0d 0a 20 20 20 20 20 20 20 20  f any...        
e930: 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20  /// </param>..  
e940: 20 20 20 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72        /// <retur
e950: 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ns>..        ///
e960: 20 41 20 73 74 61 6e 64 61 72 64 20 53 51 4c 69   A standard SQLi
e970: 74 65 20 72 65 74 75 72 6e 20 63 6f 64 65 2e 0d  te return code..
e980: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72  .        /// </r
e990: 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20  eturns>..       
e9a0: 20 53 51 4c 69 74 65 45 72 72 6f 72 43 6f 64 65   SQLiteErrorCode
e9b0: 20 78 55 70 64 61 74 65 28 0d 0a 20 20 20 20 20   xUpdate(..     
e9c0: 20 20 20 20 20 20 20 49 6e 74 50 74 72 20 70 56         IntPtr pV
e9d0: 74 61 62 2c 0d 0a 20 20 20 20 20 20 20 20 20 20  tab,..          
e9e0: 20 20 69 6e 74 20 61 72 67 63 2c 0d 0a 20 20 20    int argc,..   
e9f0: 20 20 20 20 20 20 20 20 20 49 6e 74 50 74 72 20           IntPtr 
ea00: 61 72 67 76 2c 0d 0a 20 20 20 20 20 20 20 20 20  argv,..         
ea10: 20 20 20 72 65 66 20 6c 6f 6e 67 20 72 6f 77 49     ref long rowI
ea20: 64 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 29  d..            )
ea30: 3b 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ;....        ///
ea40: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
ea50: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
ea60: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
ea70: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
ea80: 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 20 20 20 20  ////....        
ea90: 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20  /// <summary>.. 
eaa0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
eab0: 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20  ><code>..       
eac0: 20 2f 2f 2f 20 69 6e 74 20 28 2a 78 42 65 67 69   /// int (*xBegi
ead0: 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  n)(sqlite3_vtab 
eae0: 2a 70 56 54 61 62 29 3b 0d 0a 20 20 20 20 20 20  *pVTab);..      
eaf0: 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70    /// </code></p
eb00: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
eb10: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
eb20: 20 20 2f 2f 2f 20 54 68 69 73 20 6d 65 74 68 6f    /// This metho
eb30: 64 20 62 65 67 69 6e 73 20 61 20 74 72 61 6e 73  d begins a trans
eb40: 61 63 74 69 6f 6e 20 6f 6e 20 61 20 76 69 72 74  action on a virt
eb50: 75 61 6c 20 74 61 62 6c 65 2e 0d 0a 20 20 20 20  ual table...    
eb60: 20 20 20 20 2f 2f 2f 20 54 68 69 73 20 69 73 20      /// This is 
eb70: 6d 65 74 68 6f 64 20 69 73 20 6f 70 74 69 6f 6e  method is option
eb80: 61 6c 2e 20 20 54 68 65 20 78 42 65 67 69 6e 20  al.  The xBegin 
eb90: 70 6f 69 6e 74 65 72 20 6f 66 20 73 71 6c 69 74  pointer of sqlit
eba0: 65 33 5f 6d 6f 64 75 6c 65 0d 0a 20 20 20 20 20  e3_module..     
ebb0: 20 20 20 2f 2f 2f 20 6d 61 79 20 62 65 20 4e 55     /// may be NU
ebc0: 4c 4c 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  LL...        ///
ebd0: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
ebe0: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
ebf0: 20 20 20 20 20 20 2f 2f 2f 20 54 68 69 73 20 6d        /// This m
ec00: 65 74 68 6f 64 20 69 73 20 61 6c 77 61 79 73 20  ethod is always 
ec10: 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6f 6e 65 20  followed by one 
ec20: 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 74  call to either t
ec30: 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  he..        /// 
ec40: 78 43 6f 6d 6d 69 74 20 6f 72 20 78 52 6f 6c 6c  xCommit or xRoll
ec50: 62 61 63 6b 20 6d 65 74 68 6f 64 2e 20 20 56 69  back method.  Vi
ec60: 72 74 75 61 6c 20 74 61 62 6c 65 20 74 72 61 6e  rtual table tran
ec70: 73 61 63 74 69 6f 6e 73 20 64 6f 0d 0a 20 20 20  sactions do..   
ec80: 20 20 20 20 20 2f 2f 2f 20 6e 6f 74 20 6e 65 73       /// not nes
ec90: 74 2c 20 73 6f 20 74 68 65 20 78 42 65 67 69 6e  t, so the xBegin
eca0: 20 6d 65 74 68 6f 64 20 77 69 6c 6c 20 6e 6f 74   method will not
ecb0: 20 62 65 20 69 6e 76 6f 6b 65 64 20 6d 6f 72 65   be invoked more
ecc0: 20 74 68 61 6e 20 6f 6e 63 65 0d 0a 20 20 20 20   than once..    
ecd0: 20 20 20 20 2f 2f 2f 20 6f 6e 20 61 20 73 69 6e      /// on a sin
ece0: 67 6c 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  gle virtual tabl
ecf0: 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 77  e..        /// w
ed00: 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76  ithout an interv
ed10: 65 6e 69 6e 67 20 63 61 6c 6c 20 74 6f 20 65 69  ening call to ei
ed20: 74 68 65 72 20 78 43 6f 6d 6d 69 74 20 6f 72 20  ther xCommit or 
ed30: 78 52 6f 6c 6c 62 61 63 6b 2e 0d 0a 20 20 20 20  xRollback...    
ed40: 20 20 20 20 2f 2f 2f 20 4d 75 6c 74 69 70 6c 65      /// Multiple
ed50: 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20   calls to other 
ed60: 6d 65 74 68 6f 64 73 20 63 61 6e 20 61 6e 64 20  methods can and 
ed70: 6c 69 6b 65 6c 79 20 77 69 6c 6c 20 6f 63 63 75  likely will occu
ed80: 72 20 69 6e 20 62 65 74 77 65 65 6e 0d 0a 20 20  r in between..  
ed90: 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 20 78 42        /// the xB
eda0: 65 67 69 6e 20 61 6e 64 20 74 68 65 20 63 6f 72  egin and the cor
edb0: 72 65 73 70 6f 6e 64 69 6e 67 20 78 43 6f 6d 6d  responding xComm
edc0: 69 74 20 6f 72 20 78 52 6f 6c 6c 62 61 63 6b 2e  it or xRollback.
edd0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
ede0: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
edf0: 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a 20  // </summary>.. 
ee00: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
ee10: 6d 20 6e 61 6d 65 3d 22 70 56 74 61 62 22 3e 0d  m name="pVtab">.
ee20: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65  .        /// The
ee30: 20 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72 20   native pointer 
ee40: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  to the sqlite3_v
ee50: 74 61 62 20 64 65 72 69 76 65 64 20 73 74 72 75  tab derived stru
ee60: 63 74 75 72 65 2e 0d 0a 20 20 20 20 20 20 20 20  cture...        
ee70: 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20  /// </param>..  
ee80: 20 20 20 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72        /// <retur
ee90: 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ns>..        ///
eea0: 20 41 20 73 74 61 6e 64 61 72 64 20 53 51 4c 69   A standard SQLi
eeb0: 74 65 20 72 65 74 75 72 6e 20 63 6f 64 65 2e 0d  te return code..
eec0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72  .        /// </r
eed0: 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20  eturns>..       
eee0: 20 53 51 4c 69 74 65 45 72 72 6f 72 43 6f 64 65   SQLiteErrorCode
eef0: 20 78 42 65 67 69 6e 28 0d 0a 20 20 20 20 20 20   xBegin(..      
ef00: 20 20 20 20 20 20 49 6e 74 50 74 72 20 70 56 74        IntPtr pVt
ef10: 61 62 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20  ab..            
ef20: 29 3b 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f  );....        //
ef30: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
ef40: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
ef50: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
ef60: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
ef70: 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 20 20 20  /////....       
ef80: 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a   /// <summary>..
ef90: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
efa0: 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20  a><code>..      
efb0: 20 20 2f 2f 2f 20 69 6e 74 20 28 2a 78 53 79 6e    /// int (*xSyn
efc0: 63 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  c)(sqlite3_vtab 
efd0: 2a 70 56 54 61 62 29 3b 0d 0a 20 20 20 20 20 20  *pVTab);..      
efe0: 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70    /// </code></p
eff0: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
f000: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
f010: 20 20 2f 2f 2f 20 54 68 69 73 20 6d 65 74 68 6f    /// This metho
f020: 64 20 73 69 67 6e 61 6c 73 20 74 68 65 20 73 74  d signals the st
f030: 61 72 74 20 6f 66 20 61 20 74 77 6f 2d 70 68 61  art of a two-pha
f040: 73 65 20 63 6f 6d 6d 69 74 20 6f 6e 20 61 20 76  se commit on a v
f050: 69 72 74 75 61 6c 0d 0a 20 20 20 20 20 20 20 20  irtual..        
f060: 2f 2f 2f 20 74 61 62 6c 65 2e 0d 0a 20 20 20 20  /// table...    
f070: 20 20 20 20 2f 2f 2f 20 54 68 69 73 20 69 73 20      /// This is 
f080: 6d 65 74 68 6f 64 20 69 73 20 6f 70 74 69 6f 6e  method is option
f090: 61 6c 2e 20 20 54 68 65 20 78 53 79 6e 63 20 70  al.  The xSync p
f0a0: 6f 69 6e 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ointer of sqlite
f0b0: 33 5f 6d 6f 64 75 6c 65 0d 0a 20 20 20 20 20 20  3_module..      
f0c0: 20 20 2f 2f 2f 20 6d 61 79 20 62 65 20 4e 55 4c    /// may be NUL
f0d0: 4c 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  L...        /// 
f0e0: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
f0f0: 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20   /// <para>..   
f100: 20 20 20 20 20 2f 2f 2f 20 54 68 69 73 20 6d 65       /// This me
f110: 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 69 6e 76  thod is only inv
f120: 6f 6b 65 64 20 61 66 74 65 72 20 63 61 6c 6c 20  oked after call 
f130: 74 6f 20 74 68 65 20 78 42 65 67 69 6e 20 6d 65  to the xBegin me
f140: 74 68 6f 64 20 61 6e 64 0d 0a 20 20 20 20 20 20  thod and..      
f150: 20 20 2f 2f 2f 20 70 72 69 6f 72 20 74 6f 20 61    /// prior to a
f160: 6e 20 78 43 6f 6d 6d 69 74 20 6f 72 20 78 52 6f  n xCommit or xRo
f170: 6c 6c 62 61 63 6b 2e 20 20 49 6e 20 6f 72 64 65  llback.  In orde
f180: 72 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  r to implement t
f190: 77 6f 2d 70 68 61 73 65 0d 0a 20 20 20 20 20 20  wo-phase..      
f1a0: 20 20 2f 2f 2f 20 63 6f 6d 6d 69 74 2c 20 74 68    /// commit, th
f1b0: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 6f  e xSync method o
f1c0: 6e 20 61 6c 6c 20 76 69 72 74 75 61 6c 20 74 61  n all virtual ta
f1d0: 62 6c 65 73 20 69 73 20 69 6e 76 6f 6b 65 64 20  bles is invoked 
f1e0: 70 72 69 6f 72 20 74 6f 0d 0a 20 20 20 20 20 20  prior to..      
f1f0: 20 20 2f 2f 2f 20 69 6e 76 6f 6b 69 6e 67 20 74    /// invoking t
f200: 68 65 20 78 43 6f 6d 6d 69 74 20 6d 65 74 68 6f  he xCommit metho
f210: 64 20 6f 6e 20 61 6e 79 20 76 69 72 74 75 61 6c  d on any virtual
f220: 20 74 61 62 6c 65 2e 20 20 49 66 20 61 6e 79 20   table.  If any 
f230: 6f 66 20 74 68 65 20 0d 0a 20 20 20 20 20 20 20  of the ..       
f240: 20 2f 2f 2f 20 78 53 79 6e 63 20 6d 65 74 68 6f   /// xSync metho
f250: 64 73 20 66 61 69 6c 2c 20 74 68 65 20 65 6e 74  ds fail, the ent
f260: 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  ire transaction 
f270: 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0d  is rolled back..
f280: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
f290: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
f2a0: 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a 20 20  / </summary>..  
f2b0: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d        /// <param
f2c0: 20 6e 61 6d 65 3d 22 70 56 74 61 62 22 3e 0d 0a   name="pVtab">..
f2d0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20          /// The 
f2e0: 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72 20 74  native pointer t
f2f0: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 74  o the sqlite3_vt
f300: 61 62 20 64 65 72 69 76 65 64 20 73 74 72 75 63  ab derived struc
f310: 74 75 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f  ture...        /
f320: 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20  // </param>..   
f330: 20 20 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72 6e       /// <return
f340: 73 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  s>..        /// 
f350: 41 20 73 74 61 6e 64 61 72 64 20 53 51 4c 69 74  A standard SQLit
f360: 65 20 72 65 74 75 72 6e 20 63 6f 64 65 2e 0d 0a  e return code...
f370: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72 65          /// </re
f380: 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20  turns>..        
f390: 53 51 4c 69 74 65 45 72 72 6f 72 43 6f 64 65 20  SQLiteErrorCode 
f3a0: 78 53 79 6e 63 28 0d 0a 20 20 20 20 20 20 20 20  xSync(..        
f3b0: 20 20 20 20 49 6e 74 50 74 72 20 70 56 74 61 62      IntPtr pVtab
f3c0: 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 29 3b  ..            );
f3d0: 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 2f  ....        ////
f3e0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
f3f0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
f400: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
f410: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
f420: 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f  ///....        /
f430: 2f 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20 20  // <summary>..  
f440: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
f450: 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20 20  <code>..        
f460: 2f 2f 2f 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69  /// int (*xCommi
f470: 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  t)(sqlite3_vtab 
f480: 2a 70 56 54 61 62 29 3b 0d 0a 20 20 20 20 20 20  *pVTab);..      
f490: 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70    /// </code></p
f4a0: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
f4b0: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
f4c0: 20 20 2f 2f 2f 20 54 68 69 73 20 6d 65 74 68 6f    /// This metho
f4d0: 64 20 63 61 75 73 65 73 20 61 20 76 69 72 74 75  d causes a virtu
f4e0: 61 6c 20 74 61 62 6c 65 20 74 72 61 6e 73 61 63  al table transac
f4f0: 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 2e 0d  tion to commit..
f500: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 69  .        /// Thi
f510: 73 20 69 73 20 6d 65 74 68 6f 64 20 69 73 20 6f  s is method is o
f520: 70 74 69 6f 6e 61 6c 2e 20 20 54 68 65 20 78 43  ptional.  The xC
f530: 6f 6d 6d 69 74 20 70 6f 69 6e 74 65 72 20 6f 66  ommit pointer of
f540: 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 0d   sqlite3_module.
f550: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6d 61 79  .        /// may
f560: 20 62 65 20 4e 55 4c 4c 2e 0d 0a 20 20 20 20 20   be NULL...     
f570: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a     /// </para>..
f580: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
f590: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
f5a0: 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 6d  A call to this m
f5b0: 65 74 68 6f 64 20 61 6c 77 61 79 73 20 66 6f 6c  ethod always fol
f5c0: 6c 6f 77 73 20 61 20 70 72 69 6f 72 20 63 61 6c  lows a prior cal
f5d0: 6c 20 74 6f 20 78 42 65 67 69 6e 20 61 6e 64 0d  l to xBegin and.
f5e0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 78 53 79  .        /// xSy
f5f0: 6e 63 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  nc...        ///
f600: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
f610: 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e    /// </summary>
f620: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
f630: 61 72 61 6d 20 6e 61 6d 65 3d 22 70 56 74 61 62  aram name="pVtab
f640: 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ">..        /// 
f650: 54 68 65 20 6e 61 74 69 76 65 20 70 6f 69 6e 74  The native point
f660: 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
f670: 33 5f 76 74 61 62 20 64 65 72 69 76 65 64 20 73  3_vtab derived s
f680: 74 72 75 63 74 75 72 65 2e 0d 0a 20 20 20 20 20  tructure...     
f690: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d     /// </param>.
f6a0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 72 65  .        /// <re
f6b0: 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20  turns>..        
f6c0: 2f 2f 2f 20 41 20 73 74 61 6e 64 61 72 64 20 53  /// A standard S
f6d0: 51 4c 69 74 65 20 72 65 74 75 72 6e 20 63 6f 64  QLite return cod
f6e0: 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e...        /// 
f6f0: 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20  </returns>..    
f700: 20 20 20 20 53 51 4c 69 74 65 45 72 72 6f 72 43      SQLiteErrorC
f710: 6f 64 65 20 78 43 6f 6d 6d 69 74 28 0d 0a 20 20  ode xCommit(..  
f720: 20 20 20 20 20 20 20 20 20 20 49 6e 74 50 74 72            IntPtr
f730: 20 70 56 74 61 62 0d 0a 20 20 20 20 20 20 20 20   pVtab..        
f740: 20 20 20 20 29 3b 0d 0a 0d 0a 20 20 20 20 20 20      );....      
f750: 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f    //////////////
f760: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
f770: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
f780: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
f790: 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20  /////////....   
f7a0: 20 20 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72       /// <summar
f7b0: 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  y>..        /// 
f7c0: 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20  <para><code>..  
f7d0: 20 20 20 20 20 20 2f 2f 2f 20 69 6e 74 20 28 2a        /// int (*
f7e0: 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74  xRollback)(sqlit
f7f0: 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
f800: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
f810: 63 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20  code></para>..  
f820: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
f830: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
f840: 69 73 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73  is method causes
f850: 20 61 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65   a virtual table
f860: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20   transaction to 
f870: 72 6f 6c 6c 62 61 63 6b 2e 0d 0a 20 20 20 20 20  rollback...     
f880: 20 20 20 2f 2f 2f 20 54 68 69 73 20 69 73 20 6d     /// This is m
f890: 65 74 68 6f 64 20 69 73 20 6f 70 74 69 6f 6e 61  ethod is optiona
f8a0: 6c 2e 20 20 54 68 65 20 78 52 6f 6c 6c 62 61 63  l.  The xRollbac
f8b0: 6b 20 70 6f 69 6e 74 65 72 20 6f 66 20 73 71 6c  k pointer of sql
f8c0: 69 74 65 33 5f 6d 6f 64 75 6c 65 0d 0a 20 20 20  ite3_module..   
f8d0: 20 20 20 20 20 2f 2f 2f 20 6d 61 79 20 62 65 20       /// may be 
f8e0: 4e 55 4c 4c 2e 0d 0a 20 20 20 20 20 20 20 20 2f  NULL...        /
f8f0: 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  // </para>..    
f900: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a      /// <para>..
f910: 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 20 63 61          /// A ca
f920: 6c 6c 20 74 6f 20 74 68 69 73 20 6d 65 74 68 6f  ll to this metho
f930: 64 20 61 6c 77 61 79 73 20 66 6f 6c 6c 6f 77 73  d always follows
f940: 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f   a prior call to
f950: 20 78 42 65 67 69 6e 2e 0d 0a 20 20 20 20 20 20   xBegin...      
f960: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
f970: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d         /// </sum
f980: 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f  mary>..        /
f990: 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22  // <param name="
f9a0: 70 56 74 61 62 22 3e 0d 0a 20 20 20 20 20 20 20  pVtab">..       
f9b0: 20 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76 65 20   /// The native 
f9c0: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73  pointer to the s
f9d0: 71 6c 69 74 65 33 5f 76 74 61 62 20 64 65 72 69  qlite3_vtab deri
f9e0: 76 65 64 20 73 74 72 75 63 74 75 72 65 2e 0d 0a  ved structure...
f9f0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
fa00: 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ram>..        //
fa10: 2f 20 3c 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20  / <returns>..   
fa20: 20 20 20 20 20 2f 2f 2f 20 41 20 73 74 61 6e 64       /// A stand
fa30: 61 72 64 20 53 51 4c 69 74 65 20 72 65 74 75 72  ard SQLite retur
fa40: 6e 20 63 6f 64 65 2e 0d 0a 20 20 20 20 20 20 20  n code...       
fa50: 20 2f 2f 2f 20 3c 2f 72 65 74 75 72 6e 73 3e 0d   /// </returns>.
fa60: 0a 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 45  .        SQLiteE
fa70: 72 72 6f 72 43 6f 64 65 20 78 52 6f 6c 6c 62 61  rrorCode xRollba
fa80: 63 6b 28 0d 0a 20 20 20 20 20 20 20 20 20 20 20  ck(..           
fa90: 20 49 6e 74 50 74 72 20 70 56 74 61 62 0d 0a 20   IntPtr pVtab.. 
faa0: 20 20 20 20 20 20 20 20 20 20 20 29 3b 0d 0a 0d             );...
fab0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f  .        ///////
fac0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
fad0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
fae0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
faf0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
fb00: 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ....        /// 
fb10: 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20  <summary>..     
fb20: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f     /// <para><co
fb30: 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  de>..        ///
fb40: 20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63   int (*xFindFunc
fb50: 74 69 6f 6e 29 28 0d 0a 20 20 20 20 20 20 20 20  tion)(..        
fb60: 2f 2f 2f 20 20 20 73 71 6c 69 74 65 33 5f 76 74  ///   sqlite3_vt
fb70: 61 62 20 2a 70 56 74 61 62 2c 0d 0a 20 20 20 20  ab *pVtab,..    
fb80: 20 20 20 20 2f 2f 2f 20 20 20 69 6e 74 20 6e 41      ///   int nA
fb90: 72 67 2c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  rg,..        ///
fba0: 20 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a     const char *z
fbb0: 4e 61 6d 65 2c 0d 0a 20 20 20 20 20 20 20 20 2f  Name,..        /
fbc0: 2f 2f 20 20 20 76 6f 69 64 20 28 2a 2a 70 78 46  //   void (**pxF
fbd0: 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
fbe0: 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
fbf0: 33 5f 76 61 6c 75 65 2a 2a 29 2c 0d 0a 20 20 20  3_value**),..   
fc00: 20 20 20 20 20 2f 2f 2f 20 20 20 76 6f 69 64 20       ///   void 
fc10: 2a 2a 70 70 41 72 67 0d 0a 20 20 20 20 20 20 20  **ppArg..       
fc20: 20 2f 2f 2f 20 29 3b 0d 0a 20 20 20 20 20 20 20   /// );..       
fc30: 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61   /// </code></pa
fc40: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
fc50: 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20   <para>..       
fc60: 20 2f 2f 2f 20 54 68 69 73 20 6d 65 74 68 6f 64   /// This method
fc70: 20 69 73 20 63 61 6c 6c 65 64 20 64 75 72 69 6e   is called durin
fc80: 67 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  g sqlite3_prepar
fc90: 65 28 29 20 74 6f 20 67 69 76 65 20 74 68 65 20  e() to give the 
fca0: 76 69 72 74 75 61 6c 0d 0a 20 20 20 20 20 20 20  virtual..       
fcb0: 20 2f 2f 2f 20 74 61 62 6c 65 20 69 6d 70 6c 65   /// table imple
fcc0: 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 20 6f 70 70  mentation an opp
fcd0: 6f 72 74 75 6e 69 74 79 20 74 6f 20 6f 76 65 72  ortunity to over
fce0: 6c 6f 61 64 20 66 75 6e 63 74 69 6f 6e 73 2e 20  load functions. 
fcf0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
fd00: 69 73 20 6d 65 74 68 6f 64 20 6d 61 79 20 62 65  is method may be
fd10: 20 73 65 74 20 74 6f 20 4e 55 4c 4c 20 69 6e 20   set to NULL in 
fd20: 77 68 69 63 68 20 63 61 73 65 20 6e 6f 20 6f 76  which case no ov
fd30: 65 72 6c 6f 61 64 69 6e 67 20 6f 63 63 75 72 73  erloading occurs
fd40: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
fd50: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
fd60: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20  /// <para>..    
fd70: 20 20 20 20 2f 2f 2f 20 57 68 65 6e 20 61 20 66      /// When a f
fd80: 75 6e 63 74 69 6f 6e 20 75 73 65 73 20 61 20 63  unction uses a c
fd90: 6f 6c 75 6d 6e 20 66 72 6f 6d 20 61 20 76 69 72  olumn from a vir
fda0: 74 75 61 6c 20 74 61 62 6c 65 20 61 73 20 69 74  tual table as it
fdb0: 73 20 66 69 72 73 74 20 0d 0a 20 20 20 20 20 20  s first ..      
fdc0: 20 20 2f 2f 2f 20 61 72 67 75 6d 65 6e 74 2c 20    /// argument, 
fdd0: 74 68 69 73 20 6d 65 74 68 6f 64 20 69 73 20 63  this method is c
fde0: 61 6c 6c 65 64 20 74 6f 20 73 65 65 20 69 66 20  alled to see if 
fdf0: 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
fe00: 65 20 77 6f 75 6c 64 20 0d 0a 20 20 20 20 20 20  e would ..      
fe10: 20 20 2f 2f 2f 20 6c 69 6b 65 20 74 6f 20 6f 76    /// like to ov
fe20: 65 72 6c 6f 61 64 20 74 68 65 20 66 75 6e 63 74  erload the funct
fe30: 69 6f 6e 2e 20 54 68 65 20 66 69 72 73 74 20 74  ion. The first t
fe40: 68 72 65 65 20 70 61 72 61 6d 65 74 65 72 73 20  hree parameters 
fe50: 61 72 65 20 69 6e 70 75 74 73 3a 20 0d 0a 20 20  are inputs: ..  
fe60: 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 20 76 69        /// the vi
fe70: 72 74 75 61 6c 20 74 61 62 6c 65 2c 20 74 68 65  rtual table, the
fe80: 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
fe90: 65 6e 74 73 20 74 6f 20 74 68 65 20 66 75 6e 63  ents to the func
fea0: 74 69 6f 6e 2c 20 61 6e 64 20 74 68 65 20 0d 0a  tion, and the ..
feb0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 6e 61 6d 65          /// name
fec0: 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
fed0: 2e 20 49 66 20 6e 6f 20 6f 76 65 72 6c 6f 61 64  . If no overload
fee0: 69 6e 67 20 69 73 20 64 65 73 69 72 65 64 2c 20  ing is desired, 
fef0: 74 68 69 73 20 6d 65 74 68 6f 64 0d 0a 20 20 20  this method..   
ff00: 20 20 20 20 20 2f 2f 2f 20 72 65 74 75 72 6e 73       /// returns
ff10: 20 30 2e 20 54 6f 20 6f 76 65 72 6c 6f 61 64 20   0. To overload 
ff20: 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 74 68  the function, th
ff30: 69 73 20 6d 65 74 68 6f 64 20 77 72 69 74 65 73  is method writes
ff40: 20 74 68 65 20 6e 65 77 20 0d 0a 20 20 20 20 20   the new ..     
ff50: 20 20 20 2f 2f 2f 20 66 75 6e 63 74 69 6f 6e 20     /// function 
ff60: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
ff70: 6e 74 6f 20 2a 70 78 46 75 6e 63 20 61 6e 64 20  nto *pxFunc and 
ff80: 77 72 69 74 65 73 20 75 73 65 72 20 64 61 74 61  writes user data
ff90: 20 69 6e 74 6f 20 2a 70 70 41 72 67 20 0d 0a 20   into *ppArg .. 
ffa0: 20 20 20 20 20 20 20 2f 2f 2f 20 61 6e 64 20 72         /// and r
ffb0: 65 74 75 72 6e 73 20 31 2e 0d 0a 20 20 20 20 20  eturns 1...     
ffc0: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a     /// </para>..
ffd0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
ffe0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
fff0: 4e 6f 74 65 20 74 68 61 74 20 69 6e 66 69 78 20  Note that infix 
10000 66 75 6e 63 74 69 6f 6e 73 20 28 4c 49 4b 45 2c  functions (LIKE,
10010 20 47 4c 4f 42 2c 20 52 45 47 45 58 50 2c 20 61   GLOB, REGEXP, a
10020 6e 64 20 4d 41 54 43 48 29 20 72 65 76 65 72 73  nd MATCH) revers
10030 65 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e ..        /// 
10040 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65  the order of the
10050 69 72 20 61 72 67 75 6d 65 6e 74 73 2e 20 53 6f  ir arguments. So
10060 20 22 6c 69 6b 65 28 41 2c 42 29 22 20 69 73 20   "like(A,B)" is 
10070 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 22 42  equivalent to "B
10080 20 6c 69 6b 65 20 41 22 2e 20 0d 0a 20 20 20 20   like A". ..    
10090 20 20 20 20 2f 2f 2f 20 46 6f 72 20 74 68 65 20      /// For the 
100a0 66 6f 72 6d 20 22 42 20 6c 69 6b 65 20 41 22 20  form "B like A" 
100b0 74 68 65 20 42 20 74 65 72 6d 20 69 73 20 63 6f  the B term is co
100c0 6e 73 69 64 65 72 65 64 20 74 68 65 20 66 69 72  nsidered the fir
100d0 73 74 20 61 72 67 75 6d 65 6e 74 20 0d 0a 20 20  st argument ..  
100e0 20 20 20 20 20 20 2f 2f 2f 20 74 6f 20 74 68 65        /// to the
100f0 20 66 75 6e 63 74 69 6f 6e 2e 20 42 75 74 20 66   function. But f
10100 6f 72 20 22 6c 69 6b 65 28 41 2c 42 29 22 20 74  or "like(A,B)" t
10110 68 65 20 41 20 74 65 72 6d 20 69 73 20 63 6f 6e  he A term is con
10120 73 69 64 65 72 65 64 20 74 68 65 20 0d 0a 20 20  sidered the ..  
10130 20 20 20 20 20 20 2f 2f 2f 20 66 69 72 73 74 20        /// first 
10140 61 72 67 75 6d 65 6e 74 2e 0d 0a 20 20 20 20 20  argument...     
10150 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a     /// </para>..
10160 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
10170 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
10180 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  The function poi
10190 6e 74 65 72 20 72 65 74 75 72 6e 65 64 20 62 79  nter returned by
101a0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   this routine mu
101b0 73 74 20 62 65 20 76 61 6c 69 64 20 66 6f 72 0d  st be valid for.
101c0 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65  .        /// the
101d0 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65   lifetime of the
101e0 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 6f 62   sqlite3_vtab ob
101f0 6a 65 63 74 20 67 69 76 65 6e 20 69 6e 20 74 68  ject given in th
10200 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
10210 72 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  r...        /// 
10220 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
10230 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d   /// </summary>.
10240 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
10250 72 61 6d 20 6e 61 6d 65 3d 22 70 56 74 61 62 22  ram name="pVtab"
10260 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54  >..        /// T
10270 68 65 20 6e 61 74 69 76 65 20 70 6f 69 6e 74 65  he native pointe
10280 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
10290 5f 76 74 61 62 20 64 65 72 69 76 65 64 20 73 74  _vtab derived st
102a0 72 75 63 74 75 72 65 2e 0d 0a 20 20 20 20 20 20  ructure...      
102b0 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a    /// </param>..
102c0 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
102d0 61 6d 20 6e 61 6d 65 3d 22 6e 41 72 67 22 3e 0d  am name="nArg">.
102e0 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65  .        /// The
102f0 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
10300 65 6e 74 73 20 74 6f 20 74 68 65 20 66 75 6e 63  ents to the func
10310 74 69 6f 6e 20 62 65 69 6e 67 20 73 6f 75 67 68  tion being sough
10320 74 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  t...        /// 
10330 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20  </param>..      
10340 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d    /// <param nam
10350 65 3d 22 7a 4e 61 6d 65 22 3e 0d 0a 20 20 20 20  e="zName">..    
10360 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e 61 6d 65      /// The name
10370 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
10380 20 62 65 69 6e 67 20 73 6f 75 67 68 74 2e 0d 0a   being sought...
10390 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
103a0 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ram>..        //
103b0 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 63  / <param name="c
103c0 61 6c 6c 62 61 63 6b 22 3e 0d 0a 20 20 20 20 20  allback">..     
103d0 20 20 20 2f 2f 2f 20 55 70 6f 6e 20 73 75 63 63     /// Upon succ
103e0 65 73 73 2c 20 74 68 69 73 20 70 61 72 61 6d 65  ess, this parame
103f0 74 65 72 20 6d 75 73 74 20 62 65 20 6d 6f 64 69  ter must be modi
10400 66 69 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  fied to contain 
10410 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  the..        ///
10420 20 64 65 6c 65 67 61 74 65 20 72 65 73 70 6f 6e   delegate respon
10430 73 69 62 6c 65 20 66 6f 72 20 69 6d 70 6c 65 6d  sible for implem
10440 65 6e 74 69 6e 67 20 74 68 65 20 73 70 65 63 69  enting the speci
10450 66 69 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0d 0a  fied function...
10460 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
10470 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ram>..        //
10480 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70  / <param name="p
10490 43 6c 69 65 6e 74 44 61 74 61 22 3e 0d 0a 20 20  ClientData">..  
104a0 20 20 20 20 20 20 2f 2f 2f 20 55 70 6f 6e 20 73        /// Upon s
104b0 75 63 63 65 73 73 2c 20 74 68 69 73 20 70 61 72  uccess, this par
104c0 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 6d  ameter must be m
104d0 6f 64 69 66 69 65 64 20 74 6f 20 63 6f 6e 74 61  odified to conta
104e0 69 6e 20 74 68 65 0d 0a 20 20 20 20 20 20 20 20  in the..        
104f0 2f 2f 2f 20 6e 61 74 69 76 65 20 75 73 65 72 2d  /// native user-
10500 64 61 74 61 20 70 6f 69 6e 74 65 72 20 61 73 73  data pointer ass
10510 6f 63 69 61 74 65 64 20 77 69 74 68 0d 0a 20 20  ociated with..  
10520 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d        /// <param
10530 72 65 66 20 6e 61 6d 65 3d 22 63 61 6c 6c 62 61  ref name="callba
10540 63 6b 22 20 2f 3e 2e 0d 0a 20 20 20 20 20 20 20  ck" />...       
10550 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20   /// </param>.. 
10560 20 20 20 20 20 20 20 2f 2f 2f 20 3c 72 65 74 75         /// <retu
10570 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  rns>..        //
10580 2f 20 4e 6f 6e 2d 7a 65 72 6f 20 69 66 20 74 68  / Non-zero if th
10590 65 20 73 70 65 63 69 66 69 65 64 20 66 75 6e 63  e specified func
105a0 74 69 6f 6e 20 77 61 73 20 66 6f 75 6e 64 3b 20  tion was found; 
105b0 7a 65 72 6f 20 6f 74 68 65 72 77 69 73 65 2e 0d  zero otherwise..
105c0 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72  .        /// </r
105d0 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20  eturns>..       
105e0 20 69 6e 74 20 78 46 69 6e 64 46 75 6e 63 74 69   int xFindFuncti
105f0 6f 6e 28 0d 0a 20 20 20 20 20 20 20 20 20 20 20  on(..           
10600 20 49 6e 74 50 74 72 20 70 56 74 61 62 2c 0d 0a   IntPtr pVtab,..
10610 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
10620 6e 41 72 67 2c 0d 0a 20 20 20 20 20 20 20 20 20  nArg,..         
10630 20 20 20 49 6e 74 50 74 72 20 7a 4e 61 6d 65 2c     IntPtr zName,
10640 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 72 65  ..            re
10650 66 20 53 51 4c 69 74 65 43 61 6c 6c 62 61 63 6b  f SQLiteCallback
10660 20 63 61 6c 6c 62 61 63 6b 2c 0d 0a 20 20 20 20   callback,..    
10670 20 20 20 20 20 20 20 20 72 65 66 20 49 6e 74 50          ref IntP
10680 74 72 20 70 43 6c 69 65 6e 74 44 61 74 61 0d 0a  tr pClientData..
10690 20 20 20 20 20 20 20 20 20 20 20 20 29 3b 0d 0a              );..
106a0 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f  ..        //////
106b0 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
106c0 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
106d0 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
106e0 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
106f0 2f 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  /....        ///
10700 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20   <summary>..    
10710 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63      /// <para><c
10720 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ode>..        //
10730 2f 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29  / int (*xRename)
10740 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
10750 56 74 61 62 2c 20 63 6f 6e 73 74 20 63 68 61 72  Vtab, const char
10760 20 2a 7a 4e 65 77 29 3b 0d 0a 20 20 20 20 20 20   *zNew);..      
10770 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70    /// </code></p
10780 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
10790 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
107a0 20 20 2f 2f 2f 20 54 68 69 73 20 6d 65 74 68 6f    /// This metho
107b0 64 20 70 72 6f 76 69 64 65 73 20 6e 6f 74 69 66  d provides notif
107c0 69 63 61 74 69 6f 6e 20 74 68 61 74 20 74 68 65  ication that the
107d0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
107e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0d 0a 20  mplementation.. 
107f0 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 61 74 20         /// that 
10800 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
10810 65 20 77 69 6c 6c 20 62 65 20 67 69 76 65 6e 20  e will be given 
10820 61 20 6e 65 77 20 6e 61 6d 65 2e 20 0d 0a 20 20  a new name. ..  
10830 20 20 20 20 20 20 2f 2f 2f 20 49 66 20 74 68 69        /// If thi
10840 73 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  s method returns
10850 20 53 51 4c 49 54 45 5f 4f 4b 20 74 68 65 6e 20   SQLITE_OK then 
10860 53 51 4c 69 74 65 20 72 65 6e 61 6d 65 73 20 74  SQLite renames t
10870 68 65 20 74 61 62 6c 65 2e 0d 0a 20 20 20 20 20  he table...     
10880 20 20 20 2f 2f 2f 20 49 66 20 74 68 69 73 20 6d     /// If this m
10890 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 6e  ethod returns an
108a0 20 65 72 72 6f 72 20 63 6f 64 65 20 74 68 65 6e   error code then
108b0 20 74 68 65 20 72 65 6e 61 6d 69 6e 67 20 69 73   the renaming is
108c0 20 70 72 65 76 65 6e 74 65 64 2e 0d 0a 20 20 20   prevented...   
108d0 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e       /// </para>
108e0 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
108f0 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
10900 2f 20 54 68 65 20 78 52 65 6e 61 6d 65 20 6d 65  / The xRename me
10910 74 68 6f 64 20 69 73 20 72 65 71 75 69 72 65 64  thod is required
10920 20 66 6f 72 20 65 76 65 72 79 20 76 69 72 74 75   for every virtu
10930 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  al table impleme
10940 6e 74 61 74 69 6f 6e 2e 0d 0a 20 20 20 20 20 20  ntation...      
10950 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
10960 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d         /// </sum
10970 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f  mary>..        /
10980 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22  // <param name="
10990 70 56 74 61 62 22 3e 0d 0a 20 20 20 20 20 20 20  pVtab">..       
109a0 20 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76 65 20   /// The native 
109b0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73  pointer to the s
109c0 71 6c 69 74 65 33 5f 76 74 61 62 20 64 65 72 69  qlite3_vtab deri
109d0 76 65 64 20 73 74 72 75 63 74 75 72 65 2e 0d 0a  ved structure...
109e0 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
109f0 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ram>..        //
10a00 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 7a  / <param name="z
10a10 4e 65 77 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f  New">..        /
10a20 2f 2f 20 54 68 65 20 6e 61 74 69 76 65 20 70 6f  // The native po
10a30 69 6e 74 65 72 20 74 6f 20 74 68 65 20 55 54 46  inter to the UTF
10a40 2d 38 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e  -8 encoded strin
10a50 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  g containing the
10a60 20 6e 65 77 0d 0a 20 20 20 20 20 20 20 20 2f 2f   new..        //
10a70 2f 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 76  / name for the v
10a80 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 0d 0a 20  irtual table... 
10a90 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
10aa0 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  am>..        ///
10ab0 20 3c 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20   <returns>..    
10ac0 20 20 20 20 2f 2f 2f 20 41 20 73 74 61 6e 64 61      /// A standa
10ad0 72 64 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  rd SQLite return
10ae0 20 63 6f 64 65 2e 0d 0a 20 20 20 20 20 20 20 20   code...        
10af0 2f 2f 2f 20 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a  /// </returns>..
10b00 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 45 72          SQLiteEr
10b10 72 6f 72 43 6f 64 65 20 78 52 65 6e 61 6d 65 28  rorCode xRename(
10b20 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 49 6e  ..            In
10b30 74 50 74 72 20 70 56 74 61 62 2c 0d 0a 20 20 20  tPtr pVtab,..   
10b40 20 20 20 20 20 20 20 20 20 49 6e 74 50 74 72 20           IntPtr 
10b50 7a 4e 65 77 0d 0a 20 20 20 20 20 20 20 20 20 20  zNew..          
10b60 20 20 29 3b 0d 0a 0d 0a 20 20 20 20 20 20 20 20    );....        
10b70 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
10b80 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
10b90 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
10ba0 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
10bb0 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 20  ///////....     
10bc0 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79 3e     /// <summary>
10bd0 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
10be0 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20  ara><code>..    
10bf0 20 20 20 20 2f 2f 2f 20 69 6e 74 20 28 2a 78 53      /// int (*xS
10c00 61 76 65 70 6f 69 6e 74 29 28 73 71 6c 69 74 65  avepoint)(sqlite
10c10 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69  3_vtab *pVtab, i
10c20 6e 74 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f  nt);..        //
10c30 2f 20 69 6e 74 20 28 2a 78 52 65 6c 65 61 73 65  / int (*xRelease
10c40 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
10c50 70 56 74 61 62 2c 20 69 6e 74 29 3b 0d 0a 20 20  pVtab, int);..  
10c60 20 20 20 20 20 20 2f 2f 2f 20 69 6e 74 20 28 2a        /// int (*
10c70 78 52 6f 6c 6c 62 61 63 6b 54 6f 29 28 73 71 6c  xRollbackTo)(sql
10c80 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62  ite3_vtab *pVtab
10c90 2c 20 69 6e 74 29 3b 0d 0a 20 20 20 20 20 20 20  , int);..       
10ca0 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61   /// </code></pa
10cb0 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
10cc0 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20   <para>..       
10cd0 20 2f 2f 2f 20 54 68 65 73 65 20 6d 65 74 68 6f   /// These metho
10ce0 64 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 76  ds provide the v
10cf0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70  irtual table imp
10d00 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 20 6f  lementation an o
10d10 70 70 6f 72 74 75 6e 69 74 79 20 74 6f 0d 0a 20  pportunity to.. 
10d20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6d 70 6c 65         /// imple
10d30 6d 65 6e 74 20 6e 65 73 74 65 64 20 74 72 61 6e  ment nested tran
10d40 73 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 79 20  sactions.  They 
10d50 61 72 65 20 61 6c 77 61 79 73 20 6f 70 74 69 6f  are always optio
10d60 6e 61 6c 20 61 6e 64 20 77 69 6c 6c 20 6f 6e 6c  nal and will onl
10d70 79 20 62 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f  y be..        //
10d80 2f 20 63 61 6c 6c 65 64 20 69 6e 20 53 51 4c 69  / called in SQLi
10d90 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37  te version 3.7.7
10da0 20 28 32 30 31 31 2d 30 36 2d 32 33 29 20 61 6e   (2011-06-23) an
10db0 64 20 6c 61 74 65 72 2e 0d 0a 20 20 20 20 20 20  d later...      
10dc0 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
10dd0 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
10de0 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 57  >..        /// W
10df0 68 65 6e 20 78 53 61 76 65 70 6f 69 6e 74 28 58  hen xSavepoint(X
10e00 2c 4e 29 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ,N) is invoked, 
10e10 74 68 61 74 20 69 73 20 61 20 73 69 67 6e 61 6c  that is a signal
10e20 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 20   to the virtual 
10e30 74 61 62 6c 65 20 58 0d 0a 20 20 20 20 20 20 20  table X..       
10e40 20 2f 2f 2f 20 74 68 61 74 20 69 74 20 73 68 6f   /// that it sho
10e50 75 6c 64 20 73 61 76 65 20 69 74 73 20 63 75 72  uld save its cur
10e60 72 65 6e 74 20 73 74 61 74 65 20 61 73 20 73 61  rent state as sa
10e70 76 65 70 6f 69 6e 74 20 4e 2e 20 20 0d 0a 20 20  vepoint N.  ..  
10e80 20 20 20 20 20 20 2f 2f 2f 20 41 20 73 75 62 73        /// A subs
10e90 65 71 75 65 6e 74 20 63 61 6c 6c 0d 0a 20 20 20  equent call..   
10ea0 20 20 20 20 20 2f 2f 2f 20 74 6f 20 78 52 6f 6c       /// to xRol
10eb0 6c 62 61 63 6b 54 6f 28 58 2c 52 29 20 6d 65 61  lbackTo(X,R) mea
10ec0 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74  ns that the stat
10ed0 65 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c  e of the virtual
10ee0 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 72 65   table should re
10ef0 74 75 72 6e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  turn..        //
10f00 2f 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73  / to what it was
10f10 20 77 68 65 6e 20 78 53 61 76 65 70 6f 69 6e 74   when xSavepoint
10f20 28 58 2c 52 29 20 77 61 73 20 6c 61 73 74 20 63  (X,R) was last c
10f30 61 6c 6c 65 64 2e 20 20 0d 0a 20 20 20 20 20 20  alled.  ..      
10f40 20 20 2f 2f 2f 20 54 68 65 20 63 61 6c 6c 0d 0a    /// The call..
10f50 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 6f 20 78          /// to x
10f60 52 6f 6c 6c 62 61 63 6b 54 6f 28 58 2c 52 29 20  RollbackTo(X,R) 
10f70 77 69 6c 6c 20 69 6e 76 61 6c 69 64 61 74 65 20  will invalidate 
10f80 61 6c 6c 20 73 61 76 65 70 6f 69 6e 74 73 20 77  all savepoints w
10f90 69 74 68 20 4e 3e 52 3b 20 6e 6f 6e 65 20 6f 66  ith N>R; none of
10fa0 20 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f   the..        //
10fb0 2f 20 69 6e 76 61 6c 69 64 65 64 20 73 61 76 65  / invalided save
10fc0 70 6f 69 6e 74 73 20 77 69 6c 6c 20 62 65 20 72  points will be r
10fd0 6f 6c 6c 65 64 20 62 61 63 6b 20 6f 72 20 72 65  olled back or re
10fe0 6c 65 61 73 65 64 20 77 69 74 68 6f 75 74 20 66  leased without f
10ff0 69 72 73 74 0d 0a 20 20 20 20 20 20 20 20 2f 2f  irst..        //
11000 2f 20 62 65 69 6e 67 20 72 65 69 6e 69 74 69 61  / being reinitia
11010 6c 69 7a 65 64 20 62 79 20 61 20 63 61 6c 6c 20  lized by a call 
11020 74 6f 20 78 53 61 76 65 70 6f 69 6e 74 28 29 2e  to xSavepoint().
11030 20 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20    ..        /// 
11040 41 20 63 61 6c 6c 20 74 6f 20 78 52 65 6c 65 61  A call to xRelea
11050 73 65 28 58 2c 4d 29 20 69 6e 76 61 6c 69 64 61  se(X,M) invalida
11060 74 65 73 20 61 6c 6c 20 73 61 76 65 70 6f 69 6e  tes all savepoin
11070 74 73 20 77 68 65 72 65 20 4e 3e 3d 4d 2e 0d 0a  ts where N>=M...
11080 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
11090 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
110a0 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20   <para>..       
110b0 20 2f 2f 2f 20 4e 6f 6e 65 20 6f 66 20 74 68 65   /// None of the
110c0 20 78 53 61 76 65 70 6f 69 6e 74 28 29 2c 20 78   xSavepoint(), x
110d0 52 65 6c 65 61 73 65 28 29 2c 20 6f 72 20 78 52  Release(), or xR
110e0 6f 6c 6c 62 61 63 6b 54 6f 28 29 20 6d 65 74 68  ollbackTo() meth
110f0 6f 64 73 20 77 69 6c 6c 20 65 76 65 72 0d 0a 20  ods will ever.. 
11100 20 20 20 20 20 20 20 2f 2f 2f 20 62 65 20 63 61         /// be ca
11110 6c 6c 65 64 20 65 78 63 65 70 74 20 69 6e 20 62  lled except in b
11120 65 74 77 65 65 6e 20 63 61 6c 6c 73 20 74 6f 20  etween calls to 
11130 78 42 65 67 69 6e 28 29 20 61 6e 64 20 0d 0a 20  xBegin() and .. 
11140 20 20 20 20 20 20 20 2f 2f 2f 20 65 69 74 68 65         /// eithe
11150 72 20 78 43 6f 6d 6d 69 74 28 29 20 6f 72 20 78  r xCommit() or x
11160 52 6f 6c 6c 62 61 63 6b 28 29 2e 0d 0a 20 20 20  Rollback()...   
11170 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e       /// </para>
11180 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
11190 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20  summary>..      
111a0 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d    /// <param nam
111b0 65 3d 22 70 56 74 61 62 22 3e 0d 0a 20 20 20 20  e="pVtab">..    
111c0 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e 61 74 69      /// The nati
111d0 76 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  ve pointer to th
111e0 65 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 64  e sqlite3_vtab d
111f0 65 72 69 76 65 64 20 73 74 72 75 63 74 75 72 65  erived structure
11200 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
11210 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20  /param>..       
11220 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65   /// <param name
11230 3d 22 69 53 61 76 65 70 6f 69 6e 74 22 3e 0d 0a  ="iSavepoint">..
11240 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 69 73          /// This
11250 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 69   is an integer i
11260 64 65 6e 74 69 66 69 65 72 20 75 6e 64 65 72 20  dentifier under 
11270 77 68 69 63 68 20 74 68 65 20 74 68 65 20 63 75  which the the cu
11280 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0d 0a  rrent state of..
11290 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 20          /// the 
112a0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 73 68  virtual table sh
112b0 6f 75 6c 64 20 62 65 20 73 61 76 65 64 2e 0d 0a  ould be saved...
112c0 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
112d0 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ram>..        //
112e0 2f 20 3c 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20  / <returns>..   
112f0 20 20 20 20 20 2f 2f 2f 20 41 20 73 74 61 6e 64       /// A stand
11300 61 72 64 20 53 51 4c 69 74 65 20 72 65 74 75 72  ard SQLite retur
11310 6e 20 63 6f 64 65 2e 0d 0a 20 20 20 20 20 20 20  n code...       
11320 20 2f 2f 2f 20 3c 2f 72 65 74 75 72 6e 73 3e 0d   /// </returns>.
11330 0a 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 45  .        SQLiteE
11340 72 72 6f 72 43 6f 64 65 20 78 53 61 76 65 70 6f  rrorCode xSavepo
11350 69 6e 74 28 0d 0a 20 20 20 20 20 20 20 20 20 20  int(..          
11360 20 20 49 6e 74 50 74 72 20 70 56 74 61 62 2c 0d    IntPtr pVtab,.
11370 0a 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74  .            int
11380 20 69 53 61 76 65 70 6f 69 6e 74 0d 0a 20 20 20   iSavepoint..   
11390 20 20 20 20 20 20 20 20 20 29 3b 0d 0a 0d 0a 20           );.... 
113a0 20 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f         /////////
113b0 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
113c0 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
113d0 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
113e0 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a  //////////////..
113f0 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 73  ..        /// <s
11400 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20  ummary>..       
11410 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65   /// <para><code
11420 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69  >..        /// i
11430 6e 74 20 28 2a 78 53 61 76 65 70 6f 69 6e 74 29  nt (*xSavepoint)
11440 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
11450 56 74 61 62 2c 20 69 6e 74 29 3b 0d 0a 20 20 20  Vtab, int);..   
11460 20 20 20 20 20 2f 2f 2f 20 69 6e 74 20 28 2a 78       /// int (*x
11470 52 65 6c 65 61 73 65 29 28 73 71 6c 69 74 65 33  Release)(sqlite3
11480 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e  _vtab *pVtab, in
11490 74 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  t);..        ///
114a0 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b   int (*xRollback
114b0 54 6f 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  To)(sqlite3_vtab
114c0 20 2a 70 56 74 61 62 2c 20 69 6e 74 29 3b 0d 0a   *pVtab, int);..
114d0 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f          /// </co
114e0 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  de></para>..    
114f0 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a      /// <para>..
11500 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 73          /// Thes
11510 65 20 6d 65 74 68 6f 64 73 20 70 72 6f 76 69 64  e methods provid
11520 65 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  e the virtual ta
11530 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
11540 6f 6e 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74  on an opportunit
11550 79 20 74 6f 0d 0a 20 20 20 20 20 20 20 20 2f 2f  y to..        //
11560 2f 20 69 6d 70 6c 65 6d 65 6e 74 20 6e 65 73 74  / implement nest
11570 65 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 2e  ed transactions.
11580 20 20 54 68 65 79 20 61 72 65 20 61 6c 77 61 79    They are alway
11590 73 20 6f 70 74 69 6f 6e 61 6c 20 61 6e 64 20 77  s optional and w
115a0 69 6c 6c 20 6f 6e 6c 79 20 62 65 0d 0a 20 20 20  ill only be..   
115b0 20 20 20 20 20 2f 2f 2f 20 63 61 6c 6c 65 64 20       /// called 
115c0 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  in SQLite versio
115d0 6e 20 33 2e 37 2e 37 20 28 32 30 31 31 2d 30 36  n 3.7.7 (2011-06
115e0 2d 32 33 29 20 61 6e 64 20 6c 61 74 65 72 2e 0d  -23) and later..
115f0 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
11600 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
11610 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
11620 20 20 2f 2f 2f 20 57 68 65 6e 20 78 53 61 76 65    /// When xSave
11630 70 6f 69 6e 74 28 58 2c 4e 29 20 69 73 20 69 6e  point(X,N) is in
11640 76 6f 6b 65 64 2c 20 74 68 61 74 20 69 73 20 61  voked, that is a
11650 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65 20 76   signal to the v
11660 69 72 74 75 61 6c 20 74 61 62 6c 65 20 58 0d 0a  irtual table X..
11670 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 61 74          /// that
11680 20 69 74 20 73 68 6f 75 6c 64 20 73 61 76 65 20   it should save 
11690 69 74 73 20 63 75 72 72 65 6e 74 20 73 74 61 74  its current stat
116a0 65 20 61 73 20 73 61 76 65 70 6f 69 6e 74 20 4e  e as savepoint N
116b0 2e 20 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  .  ..        ///
116c0 20 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61   A subsequent ca
116d0 6c 6c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ll..        /// 
116e0 74 6f 20 78 52 6f 6c 6c 62 61 63 6b 54 6f 28 58  to xRollbackTo(X
116f0 2c 52 29 20 6d 65 61 6e 73 20 74 68 61 74 20 74  ,R) means that t
11700 68 65 20 73 74 61 74 65 20 6f 66 20 74 68 65 20  he state of the 
11710 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 73 68  virtual table sh
11720 6f 75 6c 64 20 72 65 74 75 72 6e 0d 0a 20 20 20  ould return..   
11730 20 20 20 20 20 2f 2f 2f 20 74 6f 20 77 68 61 74       /// to what
11740 20 69 74 20 77 61 73 20 77 68 65 6e 20 78 53 61   it was when xSa
11750 76 65 70 6f 69 6e 74 28 58 2c 52 29 20 77 61 73  vepoint(X,R) was
11760 20 6c 61 73 74 20 63 61 6c 6c 65 64 2e 20 20 0d   last called.  .
11770 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65  .        /// The
11780 20 63 61 6c 6c 0d 0a 20 20 20 20 20 20 20 20 2f   call..        /
11790 2f 2f 20 74 6f 20 78 52 6f 6c 6c 62 61 63 6b 54  // to xRollbackT
117a0 6f 28 58 2c 52 29 20 77 69 6c 6c 20 69 6e 76 61  o(X,R) will inva
117b0 6c 69 64 61 74 65 20 61 6c 6c 20 73 61 76 65 70  lidate all savep
117c0 6f 69 6e 74 73 20 77 69 74 68 20 4e 3e 52 3b 20  oints with N>R; 
117d0 6e 6f 6e 65 20 6f 66 20 74 68 65 0d 0a 20 20 20  none of the..   
117e0 20 20 20 20 20 2f 2f 2f 20 69 6e 76 61 6c 69 64       /// invalid
117f0 65 64 20 73 61 76 65 70 6f 69 6e 74 73 20 77 69  ed savepoints wi
11800 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ll be rolled bac
11810 6b 20 6f 72 20 72 65 6c 65 61 73 65 64 20 77 69  k or released wi
11820 74 68 6f 75 74 20 66 69 72 73 74 0d 0a 20 20 20  thout first..   
11830 20 20 20 20 20 2f 2f 2f 20 62 65 69 6e 67 20 72       /// being r
11840 65 69 6e 69 74 69 61 6c 69 7a 65 64 20 62 79 20  einitialized by 
11850 61 20 63 61 6c 6c 20 74 6f 20 78 53 61 76 65 70  a call to xSavep
11860 6f 69 6e 74 28 29 2e 20 20 0d 0a 20 20 20 20 20  oint().  ..     
11870 20 20 20 2f 2f 2f 20 41 20 63 61 6c 6c 20 74 6f     /// A call to
11880 20 78 52 65 6c 65 61 73 65 28 58 2c 4d 29 20 69   xRelease(X,M) i
11890 6e 76 61 6c 69 64 61 74 65 73 20 61 6c 6c 20 73  nvalidates all s
118a0 61 76 65 70 6f 69 6e 74 73 20 77 68 65 72 65 20  avepoints where 
118b0 4e 3e 3d 4d 2e 0d 0a 20 20 20 20 20 20 20 20 2f  N>=M...        /
118c0 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  // </para>..    
118d0 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a      /// <para>..
118e0 20 20 20 20 20 20 20 20 2f 2f 2f 20 4e 6f 6e 65          /// None
118f0 20 6f 66 20 74 68 65 20 78 53 61 76 65 70 6f 69   of the xSavepoi
11900 6e 74 28 29 2c 20 78 52 65 6c 65 61 73 65 28 29  nt(), xRelease()
11910 2c 20 6f 72 20 78 52 6f 6c 6c 62 61 63 6b 54 6f  , or xRollbackTo
11920 28 29 20 6d 65 74 68 6f 64 73 20 77 69 6c 6c 20  () methods will 
11930 65 76 65 72 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ever..        //
11940 2f 20 62 65 20 63 61 6c 6c 65 64 20 65 78 63 65  / be called exce
11950 70 74 20 69 6e 20 62 65 74 77 65 65 6e 20 63 61  pt in between ca
11960 6c 6c 73 20 74 6f 20 78 42 65 67 69 6e 28 29 20  lls to xBegin() 
11970 61 6e 64 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  and ..        //
11980 2f 20 65 69 74 68 65 72 20 78 43 6f 6d 6d 69 74  / either xCommit
11990 28 29 20 6f 72 20 78 52 6f 6c 6c 62 61 63 6b 28  () or xRollback(
119a0 29 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  )...        /// 
119b0 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
119c0 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d   /// </summary>.
119d0 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
119e0 72 61 6d 20 6e 61 6d 65 3d 22 70 56 74 61 62 22  ram name="pVtab"
119f0 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54  >..        /// T
11a00 68 65 20 6e 61 74 69 76 65 20 70 6f 69 6e 74 65  he native pointe
11a10 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
11a20 5f 76 74 61 62 20 64 65 72 69 76 65 64 20 73 74  _vtab derived st
11a30 72 75 63 74 75 72 65 2e 0d 0a 20 20 20 20 20 20  ructure...      
11a40 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a    /// </param>..
11a50 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
11a60 61 6d 20 6e 61 6d 65 3d 22 69 53 61 76 65 70 6f  am name="iSavepo
11a70 69 6e 74 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f  int">..        /
11a80 2f 2f 20 54 68 69 73 20 69 73 20 61 6e 20 69 6e  // This is an in
11a90 74 65 67 65 72 20 75 73 65 64 20 74 6f 20 69 6e  teger used to in
11aa0 64 69 63 61 74 65 20 74 68 61 74 20 61 6e 79 20  dicate that any 
11ab0 73 61 76 65 64 20 73 74 61 74 65 73 20 77 69 74  saved states wit
11ac0 68 20 61 6e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  h an..        //
11ad0 2f 20 69 64 65 6e 74 69 66 69 65 72 20 67 72 65  / identifier gre
11ae0 61 74 65 72 20 74 68 61 6e 20 6f 72 20 65 71 75  ater than or equ
11af0 61 6c 20 74 6f 20 74 68 69 73 20 73 68 6f 75 6c  al to this shoul
11b00 64 20 62 65 20 64 65 6c 65 74 65 64 20 62 79 20  d be deleted by 
11b10 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  the..        ///
11b20 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 0d   virtual table..
11b30 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
11b40 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f  aram>..        /
11b50 2f 2f 20 3c 72 65 74 75 72 6e 73 3e 0d 0a 20 20  // <returns>..  
11b60 20 20 20 20 20 20 2f 2f 2f 20 41 20 73 74 61 6e        /// A stan
11b70 64 61 72 64 20 53 51 4c 69 74 65 20 72 65 74 75  dard SQLite retu
11b80 72 6e 20 63 6f 64 65 2e 0d 0a 20 20 20 20 20 20  rn code...      
11b90 20 20 2f 2f 2f 20 3c 2f 72 65 74 75 72 6e 73 3e    /// </returns>
11ba0 0d 0a 20 20 20 20 20 20 20 20 53 51 4c 69 74 65  ..        SQLite
11bb0 45 72 72 6f 72 43 6f 64 65 20 78 52 65 6c 65 61  ErrorCode xRelea
11bc0 73 65 28 0d 0a 20 20 20 20 20 20 20 20 20 20 20  se(..           
11bd0 20 49 6e 74 50 74 72 20 70 56 74 61 62 2c 0d 0a   IntPtr pVtab,..
11be0 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
11bf0 69 53 61 76 65 70 6f 69 6e 74 0d 0a 20 20 20 20  iSavepoint..    
11c00 20 20 20 20 20 20 20 20 29 3b 0d 0a 0d 0a 20 20          );....  
11c10 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f        //////////
11c20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
11c30 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
11c40 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
11c50 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d  /////////////...
11c60 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 73 75  .        /// <su
11c70 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20  mmary>..        
11c80 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e  /// <para><code>
11c90 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e  ..        /// in
11ca0 74 20 28 2a 78 53 61 76 65 70 6f 69 6e 74 29 28  t (*xSavepoint)(
11cb0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
11cc0 74 61 62 2c 20 69 6e 74 29 3b 0d 0a 20 20 20 20  tab, int);..    
11cd0 20 20 20 20 2f 2f 2f 20 69 6e 74 20 28 2a 78 52      /// int (*xR
11ce0 65 6c 65 61 73 65 29 28 73 71 6c 69 74 65 33 5f  elease)(sqlite3_
11cf0 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74  vtab *pVtab, int
11d00 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  );..        /// 
11d10 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 54  int (*xRollbackT
11d20 6f 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  o)(sqlite3_vtab 
11d30 2a 70 56 74 61 62 2c 20 69 6e 74 29 3b 0d 0a 20  *pVtab, int);.. 
11d40 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64         /// </cod
11d50 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  e></para>..     
11d60 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20     /// <para>.. 
11d70 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 73 65         /// These
11d80 20 6d 65 74 68 6f 64 73 20 70 72 6f 76 69 64 65   methods provide
11d90 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
11da0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
11db0 6e 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79  n an opportunity
11dc0 20 74 6f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f   to..        ///
11dd0 20 69 6d 70 6c 65 6d 65 6e 74 20 6e 65 73 74 65   implement neste
11de0 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 2e 20  d transactions. 
11df0 20 54 68 65 79 20 61 72 65 20 61 6c 77 61 79 73   They are always
11e00 20 6f 70 74 69 6f 6e 61 6c 20 61 6e 64 20 77 69   optional and wi
11e10 6c 6c 20 6f 6e 6c 79 20 62 65 0d 0a 20 20 20 20  ll only be..    
11e20 20 20 20 20 2f 2f 2f 20 63 61 6c 6c 65 64 20 69      /// called i
11e30 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
11e40 20 33 2e 37 2e 37 20 28 32 30 31 31 2d 30 36 2d   3.7.7 (2011-06-
11e50 32 33 29 20 61 6e 64 20 6c 61 74 65 72 2e 0d 0a  23) and later...
11e60 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
11e70 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
11e80 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20   <para>..       
11e90 20 2f 2f 2f 20 57 68 65 6e 20 78 53 61 76 65 70   /// When xSavep
11ea0 6f 69 6e 74 28 58 2c 4e 29 20 69 73 20 69 6e 76  oint(X,N) is inv
11eb0 6f 6b 65 64 2c 20 74 68 61 74 20 69 73 20 61 20  oked, that is a 
11ec0 73 69 67 6e 61 6c 20 74 6f 20 74 68 65 20 76 69  signal to the vi
11ed0 72 74 75 61 6c 20 74 61 62 6c 65 20 58 0d 0a 20  rtual table X.. 
11ee0 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 61 74 20         /// that 
11ef0 69 74 20 73 68 6f 75 6c 64 20 73 61 76 65 20 69  it should save i
11f00 74 73 20 63 75 72 72 65 6e 74 20 73 74 61 74 65  ts current state
11f10 20 61 73 20 73 61 76 65 70 6f 69 6e 74 20 4e 2e   as savepoint N.
11f20 20 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20    ..        /// 
11f30 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  A subsequent cal
11f40 6c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74  l..        /// t
11f50 6f 20 78 52 6f 6c 6c 62 61 63 6b 54 6f 28 58 2c  o xRollbackTo(X,
11f60 52 29 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  R) means that th
11f70 65 20 73 74 61 74 65 20 6f 66 20 74 68 65 20 76  e state of the v
11f80 69 72 74 75 61 6c 20 74 61 62 6c 65 20 73 68 6f  irtual table sho
11f90 75 6c 64 20 72 65 74 75 72 6e 0d 0a 20 20 20 20  uld return..    
11fa0 20 20 20 20 2f 2f 2f 20 74 6f 20 77 68 61 74 20      /// to what 
11fb0 69 74 20 77 61 73 20 77 68 65 6e 20 78 53 61 76  it was when xSav
11fc0 65 70 6f 69 6e 74 28 58 2c 52 29 20 77 61 73 20  epoint(X,R) was 
11fd0 6c 61 73 74 20 63 61 6c 6c 65 64 2e 20 20 0d 0a  last called.  ..
11fe0 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20          /// The 
11ff0 63 61 6c 6c 0d 0a 20 20 20 20 20 20 20 20 2f 2f  call..        //
12000 2f 20 74 6f 20 78 52 6f 6c 6c 62 61 63 6b 54 6f  / to xRollbackTo
12010 28 58 2c 52 29 20 77 69 6c 6c 20 69 6e 76 61 6c  (X,R) will inval
12020 69 64 61 74 65 20 61 6c 6c 20 73 61 76 65 70 6f  idate all savepo
12030 69 6e 74 73 20 77 69 74 68 20 4e 3e 52 3b 20 6e  ints with N>R; n
12040 6f 6e 65 20 6f 66 20 74 68 65 0d 0a 20 20 20 20  one of the..    
12050 20 20 20 20 2f 2f 2f 20 69 6e 76 61 6c 69 64 65      /// invalide
12060 64 20 73 61 76 65 70 6f 69 6e 74 73 20 77 69 6c  d savepoints wil
12070 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  l be rolled back
12080 20 6f 72 20 72 65 6c 65 61 73 65 64 20 77 69 74   or released wit
12090 68 6f 75 74 20 66 69 72 73 74 0d 0a 20 20 20 20  hout first..    
120a0 20 20 20 20 2f 2f 2f 20 62 65 69 6e 67 20 72 65      /// being re
120b0 69 6e 69 74 69 61 6c 69 7a 65 64 20 62 79 20 61  initialized by a
120c0 20 63 61 6c 6c 20 74 6f 20 78 53 61 76 65 70 6f   call to xSavepo
120d0 69 6e 74 28 29 2e 20 20 0d 0a 20 20 20 20 20 20  int().  ..      
120e0 20 20 2f 2f 2f 20 41 20 63 61 6c 6c 20 74 6f 20    /// A call to 
120f0 78 52 65 6c 65 61 73 65 28 58 2c 4d 29 20 69 6e  xRelease(X,M) in
12100 76 61 6c 69 64 61 74 65 73 20 61 6c 6c 20 73 61  validates all sa
12110 76 65 70 6f 69 6e 74 73 20 77 68 65 72 65 20 4e  vepoints where N
12120 3e 3d 4d 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  >=M...        //
12130 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  / </para>..     
12140 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20     /// <para>.. 
12150 20 20 20 20 20 20 20 2f 2f 2f 20 4e 6f 6e 65 20         /// None 
12160 6f 66 20 74 68 65 20 78 53 61 76 65 70 6f 69 6e  of the xSavepoin
12170 74 28 29 2c 20 78 52 65 6c 65 61 73 65 28 29 2c  t(), xRelease(),
12180 20 6f 72 20 78 52 6f 6c 6c 62 61 63 6b 54 6f 28   or xRollbackTo(
12190 29 20 6d 65 74 68 6f 64 73 20 77 69 6c 6c 20 65  ) methods will e
121a0 76 65 72 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ver..        ///
121b0 20 62 65 20 63 61 6c 6c 65 64 20 65 78 63 65 70   be called excep
121c0 74 20 69 6e 20 62 65 74 77 65 65 6e 20 63 61 6c  t in between cal
121d0 6c 73 20 74 6f 20 78 42 65 67 69 6e 28 29 20 61  ls to xBegin() a
121e0 6e 64 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  nd ..        ///
121f0 20 65 69 74 68 65 72 20 78 43 6f 6d 6d 69 74 28   either xCommit(
12200 29 20 6f 72 20 78 52 6f 6c 6c 62 61 63 6b 28 29  ) or xRollback()
12210 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
12220 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
12230 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a  /// </summary>..
12240 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
12250 61 6d 20 6e 61 6d 65 3d 22 70 56 74 61 62 22 3e  am name="pVtab">
12260 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
12270 65 20 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72  e native pointer
12280 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
12290 76 74 61 62 20 64 65 72 69 76 65 64 20 73 74 72  vtab derived str
122a0 75 63 74 75 72 65 2e 0d 0a 20 20 20 20 20 20 20  ucture...       
122b0 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20   /// </param>.. 
122c0 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
122d0 6d 20 6e 61 6d 65 3d 22 69 53 61 76 65 70 6f 69  m name="iSavepoi
122e0 6e 74 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  nt">..        //
122f0 2f 20 54 68 69 73 20 69 73 20 61 6e 20 69 6e 74  / This is an int
12300 65 67 65 72 20 69 64 65 6e 74 69 66 69 65 72 20  eger identifier 
12310 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20  used to specify 
12320 61 20 73 70 65 63 69 66 69 63 20 73 61 76 65 64  a specific saved
12330 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 74  ..        /// st
12340 61 74 65 20 66 6f 72 20 74 68 65 20 76 69 72 74  ate for the virt
12350 75 61 6c 20 74 61 62 6c 65 20 66 6f 72 20 69 74  ual table for it
12360 20 74 6f 20 72 65 73 74 6f 72 65 20 69 74 73 65   to restore itse
12370 6c 66 20 62 61 63 6b 20 74 6f 2c 20 77 68 69 63  lf back to, whic
12380 68 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73  h..        /// s
12390 68 6f 75 6c 64 20 61 6c 73 6f 20 68 61 76 65 20  hould also have 
123a0 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 64 65  the effect of de
123b0 6c 65 74 69 6e 67 20 61 6c 6c 20 73 61 76 65 64  leting all saved
123c0 20 73 74 61 74 65 73 20 77 69 74 68 20 61 6e 0d   states with an.
123d0 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e 74  .        /// int
123e0 65 67 65 72 20 69 64 65 6e 74 69 66 69 65 72 20  eger identifier 
123f0 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 69  greater than thi
12400 73 20 6f 6e 65 2e 0d 0a 20 20 20 20 20 20 20 20  s one...        
12410 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20  /// </param>..  
12420 20 20 20 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72        /// <retur
12430 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ns>..        ///
12440 20 41 20 73 74 61 6e 64 61 72 64 20 53 51 4c 69   A standard SQLi
12450 74 65 20 72 65 74 75 72 6e 20 63 6f 64 65 2e 0d  te return code..
12460 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72  .        /// </r
12470 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20  eturns>..       
12480 20 53 51 4c 69 74 65 45 72 72 6f 72 43 6f 64 65   SQLiteErrorCode
12490 20 78 52 6f 6c 6c 62 61 63 6b 54 6f 28 0d 0a 20   xRollbackTo(.. 
124a0 20 20 20 20 20 20 20 20 20 20 20 49 6e 74 50 74             IntPt
124b0 72 20 70 56 74 61 62 2c 0d 0a 20 20 20 20 20 20  r pVtab,..      
124c0 20 20 20 20 20 20 69 6e 74 20 69 53 61 76 65 70        int iSavep
124d0 6f 69 6e 74 0d 0a 20 20 20 20 20 20 20 20 20 20  oint..          
124e0 20 20 29 3b 0d 0a 20 20 20 20 7d 0d 0a 20 20 20    );..    }..   
124f0 20 23 65 6e 64 72 65 67 69 6f 6e 0d 0a 7d 0d 0a   #endregion..}..