System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact e31057fa4d35b71932d76078ba11e5fad8649823:


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 64  prior to 3.9.0 d
15f0: 6f 20 6e 6f 74 20 75 6e 64 65 72 73 74 61 6e 64  o not understand
1600: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 65 70  ..        /// ep
1610: 6f 6e 79 6d 6f 75 73 2d 6f 6e 6c 79 20 76 69 72  onymous-only vir
1620: 74 75 61 6c 20 74 61 62 6c 65 73 20 61 6e 64 20  tual tables and 
1630: 77 69 6c 6c 20 73 65 67 66 61 75 6c 74 20 69 66  will segfault if
1640: 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d   an attempt is m
1650: 61 64 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ade..        ///
1660: 20 74 6f 20 43 52 45 41 54 45 20 56 49 52 54 55   to CREATE VIRTU
1670: 41 4c 20 54 41 42 4c 45 20 6f 6e 20 61 6e 20 65  AL TABLE on an e
1680: 70 6f 6e 79 6d 6f 75 73 2d 6f 6e 6c 79 20 76 69  ponymous-only vi
1690: 72 74 75 61 6c 20 74 61 62 6c 65 20 62 65 63 61  rtual table beca
16a0: 75 73 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  use..        ///
16b0: 20 74 68 65 20 78 43 72 65 61 74 65 20 6d 65 74   the xCreate met
16c0: 68 6f 64 20 77 61 73 20 6e 6f 74 20 63 68 65 63  hod was not chec
16d0: 6b 65 64 20 66 6f 72 20 6e 75 6c 6c 2e 0d 0a 20  ked for null... 
16e0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
16f0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
1700: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
1710: 2f 2f 2f 20 49 66 20 74 68 65 20 78 43 72 65 61  /// If the xCrea
1720: 74 65 20 6d 65 74 68 6f 64 20 69 73 20 74 68 65  te method is the
1730: 20 65 78 61 63 74 20 73 61 6d 65 20 70 6f 69 6e   exact same poin
1740: 74 65 72 20 61 73 20 74 68 65 20 78 43 6f 6e 6e  ter as the xConn
1750: 65 63 74 20 6d 65 74 68 6f 64 2c 0d 0a 20 20 20  ect method,..   
1760: 20 20 20 20 20 2f 2f 2f 20 74 68 61 74 20 69 6e       /// that in
1770: 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65  dicates that the
1780: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 64   virtual table d
1790: 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
17a0: 69 6e 69 74 69 61 6c 69 7a 65 20 62 61 63 6b 69  initialize backi
17b0: 6e 67 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ng..        /// 
17c0: 73 74 6f 72 65 2e 20 20 53 75 63 68 20 61 20 76  store.  Such a v
17d0: 69 72 74 75 61 6c 20 74 61 62 6c 65 20 63 61 6e  irtual table can
17e0: 20 62 65 20 75 73 65 64 20 61 73 20 61 6e 20 65   be used as an e
17f0: 70 6f 6e 79 6d 6f 75 73 20 76 69 72 74 75 61 6c  ponymous virtual
1800: 20 74 61 62 6c 65 0d 0a 20 20 20 20 20 20 20 20   table..        
1810: 2f 2f 2f 20 6f 72 20 61 73 20 61 20 6e 61 6d 65  /// or as a name
1820: 64 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  d virtual table 
1830: 75 73 69 6e 67 20 43 52 45 41 54 45 20 56 49 52  using CREATE VIR
1840: 54 55 41 4c 20 54 41 42 4c 45 20 6f 72 20 62 6f  TUAL TABLE or bo
1850: 74 68 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  th...        ///
1860: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
1870: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
1880: 20 20 20 20 20 20 2f 2f 2f 20 49 66 20 61 20 63        /// If a c
1890: 6f 6c 75 6d 6e 20 64 61 74 61 74 79 70 65 20 63  olumn datatype c
18a0: 6f 6e 74 61 69 6e 73 20 74 68 65 20 73 70 65 63  ontains the spec
18b0: 69 61 6c 20 6b 65 79 77 6f 72 64 20 22 48 49 44  ial keyword "HID
18c0: 44 45 4e 22 0d 0a 20 20 20 20 20 20 20 20 2f 2f  DEN"..        //
18d0: 2f 20 28 69 6e 20 61 6e 79 20 63 6f 6d 62 69 6e  / (in any combin
18e0: 61 74 69 6f 6e 20 6f 66 20 75 70 70 65 72 20 61  ation of upper a
18f0: 6e 64 20 6c 6f 77 65 72 20 63 61 73 65 20 6c 65  nd lower case le
1900: 74 74 65 72 73 29 20 74 68 65 6e 20 74 68 61 74  tters) then that
1910: 20 6b 65 79 77 6f 72 64 0d 0a 20 20 20 20 20 20   keyword..      
1920: 20 20 2f 2f 2f 20 69 74 20 69 73 20 6f 6d 69 74    /// it is omit
1930: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 63 6f 6c  ted from the col
1940: 75 6d 6e 20 64 61 74 61 74 79 70 65 20 6e 61 6d  umn datatype nam
1950: 65 20 61 6e 64 20 74 68 65 20 63 6f 6c 75 6d 6e  e and the column
1960: 20 69 73 20 6d 61 72 6b 65 64 20 0d 0a 20 20 20   is marked ..   
1970: 20 20 20 20 20 2f 2f 2f 20 61 73 20 61 20 68 69       /// as a hi
1980: 64 64 65 6e 20 63 6f 6c 75 6d 6e 20 69 6e 74 65  dden column inte
1990: 72 6e 61 6c 6c 79 2e 20 0d 0a 20 20 20 20 20 20  rnally. ..      
19a0: 20 20 2f 2f 2f 20 41 20 68 69 64 64 65 6e 20 63    /// A hidden c
19b0: 6f 6c 75 6d 6e 20 64 69 66 66 65 72 73 20 66 72  olumn differs fr
19c0: 6f 6d 20 61 20 6e 6f 72 6d 61 6c 20 63 6f 6c 75  om a normal colu
19d0: 6d 6e 20 69 6e 20 74 68 72 65 65 20 72 65 73 70  mn in three resp
19e0: 65 63 74 73 3a 0d 0a 20 20 20 20 20 20 20 20 2f  ects:..        /
19f0: 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  // </para>..    
1a00: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a      /// <para>..
1a10: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 21 5b 43          /// <![C
1a20: 44 41 54 41 5b 3c 75 6c 3e 5d 5d 3e 0d 0a 20 20  DATA[<ul>]]>..  
1a30: 20 20 20 20 20 20 2f 2f 2f 20 3c 21 5b 43 44 41        /// <![CDA
1a40: 54 41 5b 3c 6c 69 3e 5d 5d 3e 20 48 69 64 64 65  TA[<li>]]> Hidde
1a50: 6e 20 63 6f 6c 75 6d 6e 73 20 61 72 65 20 6e 6f  n columns are no
1a60: 74 20 6c 69 73 74 65 64 20 69 6e 20 74 68 65 20  t listed in the 
1a70: 64 61 74 61 73 65 74 20 72 65 74 75 72 6e 65 64  dataset returned
1a80: 20 62 79 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f   by ..        //
1a90: 2f 20 20 20 20 20 20 22 50 52 41 47 4d 41 20 74  /      "PRAGMA t
1aa0: 61 62 6c 65 5f 69 6e 66 6f 22 2c 0d 0a 20 20 20  able_info",..   
1ab0: 20 20 20 20 20 2f 2f 2f 20 3c 21 5b 43 44 41 54       /// <![CDAT
1ac0: 41 5b 3c 2f 6c 69 3e 5d 5d 3e 3c 21 5b 43 44 41  A[</li>]]><![CDA
1ad0: 54 41 5b 3c 6c 69 3e 5d 5d 3e 20 48 69 64 64 65  TA[<li>]]> Hidde
1ae0: 6e 20 63 6f 6c 75 6d 6e 73 20 61 72 65 20 6e 6f  n columns are no
1af0: 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  t included in th
1b00: 65 20 65 78 70 61 6e 73 69 6f 6e 20 6f 66 20 61  e expansion of a
1b10: 20 22 2a 22 0d 0a 20 20 20 20 20 20 20 20 2f 2f   "*"..        //
1b20: 2f 20 20 20 20 20 20 65 78 70 72 65 73 73 69 6f  /      expressio
1b30: 6e 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  n in the result 
1b40: 73 65 74 20 6f 66 20 61 20 53 45 4c 45 43 54 2c  set of a SELECT,
1b50: 20 61 6e 64 0d 0a 20 20 20 20 20 20 20 20 2f 2f   and..        //
1b60: 2f 20 3c 21 5b 43 44 41 54 41 5b 3c 2f 6c 69 3e  / <![CDATA[</li>
1b70: 5d 5d 3e 3c 21 5b 43 44 41 54 41 5b 3c 6c 69 3e  ]]><![CDATA[<li>
1b80: 5d 5d 3e 20 48 69 64 64 65 6e 20 63 6f 6c 75 6d  ]]> Hidden colum
1b90: 6e 73 20 61 72 65 20 6e 6f 74 20 69 6e 63 6c 75  ns are not inclu
1ba0: 64 65 64 20 69 6e 20 74 68 65 20 69 6d 70 6c 69  ded in the impli
1bb0: 63 69 74 20 63 6f 6c 75 6d 6e 2d 6c 69 73 74 20  cit column-list 
1bc0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20  ..        ///   
1bd0: 20 20 20 75 73 65 64 20 62 79 20 61 6e 20 49 4e     used by an IN
1be0: 53 45 52 54 20 73 74 61 74 65 6d 65 6e 74 20 74  SERT statement t
1bf0: 68 61 74 20 6c 61 63 6b 73 20 61 6e 20 65 78 70  hat lacks an exp
1c00: 6c 69 63 69 74 20 63 6f 6c 75 6d 6e 2d 6c 69 73  licit column-lis
1c10: 74 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  t. ..        ///
1c20: 20 3c 21 5b 43 44 41 54 41 5b 3c 2f 6c 69 3e 5d   <![CDATA[</li>]
1c30: 5d 3e 3c 21 5b 43 44 41 54 41 5b 3c 2f 75 6c 3e  ]><![CDATA[</ul>
1c40: 5d 5d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ]]>..        ///
1c50: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
1c60: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
1c70: 20 20 20 20 20 20 2f 2f 2f 20 46 6f 72 20 65 78        /// For ex
1c80: 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 66 6f  ample, if the fo
1c90: 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 69 73 20 70  llowing SQL is p
1ca0: 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33  assed to sqlite3
1cb0: 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 29 3a  _declare_vtab():
1cc0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
1cd0: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
1ce0: 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d  // <para><code>.
1cf0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 43 52 45  .        /// CRE
1d00: 41 54 45 20 54 41 42 4c 45 20 78 28 61 20 48 49  ATE TABLE x(a HI
1d10: 44 44 45 4e 20 56 41 52 43 48 41 52 28 31 32 29  DDEN VARCHAR(12)
1d20: 2c 20 62 20 49 4e 54 45 47 45 52 2c 20 63 20 49  , b INTEGER, c I
1d30: 4e 54 45 47 45 52 20 48 69 64 64 65 6e 29 3b 0d  NTEGER Hidden);.
1d40: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63  .        /// </c
1d50: 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  ode></para>..   
1d60: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
1d70: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65  .        /// The
1d80: 6e 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  n the virtual ta
1d90: 62 6c 65 20 77 6f 75 6c 64 20 62 65 20 63 72 65  ble would be cre
1da0: 61 74 65 64 20 77 69 74 68 20 74 77 6f 20 68 69  ated with two hi
1db0: 64 64 65 6e 20 63 6f 6c 75 6d 6e 73 2c 0d 0a 20  dden columns,.. 
1dc0: 20 20 20 20 20 20 20 2f 2f 2f 20 61 6e 64 20 77         /// and w
1dd0: 69 74 68 20 64 61 74 61 74 79 70 65 73 20 6f 66  ith datatypes of
1de0: 20 22 56 41 52 43 48 41 52 28 31 32 29 22 20 61   "VARCHAR(12)" a
1df0: 6e 64 20 22 49 4e 54 45 47 45 52 22 2e 0d 0a 20  nd "INTEGER"... 
1e00: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
1e10: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
1e20: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
1e30: 2f 2f 2f 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  /// An example u
1e40: 73 65 20 6f 66 20 68 69 64 64 65 6e 20 63 6f 6c  se of hidden col
1e50: 75 6d 6e 73 20 63 61 6e 20 62 65 20 73 65 65 6e  umns can be seen
1e60: 20 69 6e 20 74 68 65 20 46 54 53 33 20 76 69 72   in the FTS3 vir
1e70: 74 75 61 6c 20 0d 0a 20 20 20 20 20 20 20 20 2f  tual ..        /
1e80: 2f 2f 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  // table impleme
1e90: 6e 74 61 74 69 6f 6e 2c 20 77 68 65 72 65 20 65  ntation, where e
1ea0: 76 65 72 79 20 46 54 53 20 76 69 72 74 75 61 6c  very FTS virtual
1eb0: 20 74 61 62 6c 65 0d 0a 20 20 20 20 20 20 20 20   table..        
1ec0: 2f 2f 2f 20 63 6f 6e 74 61 69 6e 73 20 61 6e 20  /// contains an 
1ed0: 46 54 53 20 68 69 64 64 65 6e 20 63 6f 6c 75 6d  FTS hidden colum
1ee0: 6e 20 74 68 61 74 20 69 73 20 75 73 65 64 20 74  n that is used t
1ef0: 6f 20 70 61 73 73 20 69 6e 66 6f 72 6d 61 74 69  o pass informati
1f00: 6f 6e 20 66 72 6f 6d 20 74 68 65 0d 0a 20 20 20  on from the..   
1f10: 20 20 20 20 20 2f 2f 2f 20 76 69 72 74 75 61 6c       /// virtual
1f20: 20 74 61 62 6c 65 20 69 6e 74 6f 20 46 54 53 20   table into FTS 
1f30: 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63 74 69  auxiliary functi
1f40: 6f 6e 73 20 61 6e 64 20 74 6f 20 74 68 65 20 46  ons and to the F
1f50: 54 53 20 4d 41 54 43 48 20 6f 70 65 72 61 74 6f  TS MATCH operato
1f60: 72 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  r...        /// 
1f70: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
1f80: 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20   /// <para>..   
1f90: 20 20 20 20 20 2f 2f 2f 20 41 20 76 69 72 74 75       /// A virtu
1fa0: 61 6c 20 74 61 62 6c 65 20 74 68 61 74 20 63 6f  al table that co
1fb0: 6e 74 61 69 6e 73 20 68 69 64 64 65 6e 20 63 6f  ntains hidden co
1fc0: 6c 75 6d 6e 73 20 63 61 6e 20 62 65 20 75 73 65  lumns can be use
1fd0: 64 20 6c 69 6b 65 0d 0a 20 20 20 20 20 20 20 20  d like..        
1fe0: 2f 2f 2f 20 61 20 74 61 62 6c 65 2d 76 61 6c 75  /// a table-valu
1ff0: 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 6e 20 74  ed function in t
2000: 68 65 20 46 52 4f 4d 20 63 6c 61 75 73 65 20 6f  he FROM clause o
2010: 66 20 61 20 53 45 4c 45 43 54 20 73 74 61 74 65  f a SELECT state
2020: 6d 65 6e 74 2e 0d 0a 20 20 20 20 20 20 20 20 2f  ment...        /
2030: 2f 2f 20 54 68 65 20 61 72 67 75 6d 65 6e 74 73  // The arguments
2040: 20 74 6f 20 74 68 65 20 74 61 62 6c 65 2d 76 61   to the table-va
2050: 6c 75 65 64 20 66 75 6e 63 74 69 6f 6e 20 62 65  lued function be
2060: 63 6f 6d 65 20 63 6f 6e 73 74 72 61 69 6e 74 73  come constraints
2070: 20 6f 6e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f   on ..        //
2080: 2f 20 74 68 65 20 48 49 44 44 45 4e 20 63 6f 6c  / the HIDDEN col
2090: 75 6d 6e 73 20 6f 66 20 74 68 65 20 76 69 72 74  umns of the virt
20a0: 75 61 6c 20 74 61 62 6c 65 2e 0d 0a 20 20 20 20  ual table...    
20b0: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
20c0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
20d0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
20e0: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 68   For example, th
20f0: 65 20 22 67 65 6e 65 72 61 74 65 5f 73 65 72 69  e "generate_seri
2100: 65 73 22 20 65 78 74 65 6e 73 69 6f 6e 20 28 6c  es" extension (l
2110: 6f 63 61 74 65 64 20 69 6e 20 74 68 65 0d 0a 20  ocated in the.. 
2120: 20 20 20 20 20 20 20 2f 2f 2f 20 65 78 74 2f 6d         /// ext/m
2130: 69 73 63 2f 73 65 72 69 65 73 2e 63 0d 0a 20 20  isc/series.c..  
2140: 20 20 20 20 20 20 2f 2f 2f 20 66 69 6c 65 20 69        /// file i
2150: 6e 20 74 68 65 20 73 6f 75 72 63 65 20 74 72 65  n the source tre
2160: 65 29 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e)..        /// 
2170: 69 6d 70 6c 65 6d 65 6e 74 73 20 61 6e 20 65 70  implements an ep
2180: 6f 6e 79 6d 6f 75 73 20 76 69 72 74 75 61 6c 20  onymous virtual 
2190: 74 61 62 6c 65 20 77 69 74 68 20 74 68 65 20 66  table with the f
21a0: 6f 6c 6c 6f 77 69 6e 67 20 73 63 68 65 6d 61 3a  ollowing schema:
21b0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
21c0: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
21d0: 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d  // <para><code>.
21e0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 43 52 45  .        /// CRE
21f0: 41 54 45 20 54 41 42 4c 45 20 67 65 6e 65 72 61  ATE TABLE genera
2200: 74 65 5f 73 65 72 69 65 73 28 0d 0a 20 20 20 20  te_series(..    
2210: 20 20 20 20 2f 2f 2f 20 20 20 76 61 6c 75 65 2c      ///   value,
2220: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20  ..        ///   
2230: 73 74 61 72 74 20 48 49 44 44 45 4e 2c 0d 0a 20  start HIDDEN,.. 
2240: 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 73 74 6f         ///   sto
2250: 70 20 48 49 44 44 45 4e 2c 0d 0a 20 20 20 20 20  p HIDDEN,..     
2260: 20 20 20 2f 2f 2f 20 20 20 73 74 65 70 20 48 49     ///   step HI
2270: 44 44 45 4e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  DDEN..        //
2280: 2f 20 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f  / );..        //
2290: 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e  / </code></para>
22a0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
22b0: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
22c0: 2f 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 6f  / The sqlite3_mo
22d0: 64 75 6c 65 2e 78 42 65 73 74 49 6e 64 65 78 20  dule.xBestIndex 
22e0: 6d 65 74 68 6f 64 20 69 6e 20 74 68 65 20 69 6d  method in the im
22f0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2300: 74 68 69 73 0d 0a 20 20 20 20 20 20 20 20 2f 2f  this..        //
2310: 2f 20 74 61 62 6c 65 20 63 68 65 63 6b 73 20 66  / table checks f
2320: 6f 72 20 65 71 75 61 6c 69 74 79 20 63 6f 6e 73  or equality cons
2330: 74 72 61 69 6e 74 73 20 61 67 61 69 6e 73 74 20  traints against 
2340: 74 68 65 20 48 49 44 44 45 4e 20 63 6f 6c 75 6d  the HIDDEN colum
2350: 6e 73 2c 20 61 6e 64 20 75 73 65 73 0d 0a 20 20  ns, and uses..  
2360: 20 20 20 20 20 20 2f 2f 2f 20 74 68 6f 73 65 20        /// those 
2370: 61 73 20 69 6e 70 75 74 20 70 61 72 61 6d 65 74  as input paramet
2380: 65 72 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ers to determine
2390: 20 74 68 65 20 72 61 6e 67 65 20 6f 66 20 69 6e   the range of in
23a0: 74 65 67 65 72 20 22 76 61 6c 75 65 22 20 6f 75  teger "value" ou
23b0: 74 70 75 74 73 0d 0a 20 20 20 20 20 20 20 20 2f  tputs..        /
23c0: 2f 2f 20 74 6f 20 67 65 6e 65 72 61 74 65 2e 20  // to generate. 
23d0: 20 52 65 61 73 6f 6e 61 62 6c 65 20 64 65 66 61   Reasonable defa
23e0: 75 6c 74 73 20 61 72 65 20 75 73 65 64 20 66 6f  ults are used fo
23f0: 72 20 61 6e 79 20 75 6e 63 6f 6e 73 74 72 61 69  r any unconstrai
2400: 6e 65 64 20 63 6f 6c 75 6d 6e 73 2e 0d 0a 20 20  ned columns...  
2410: 20 20 20 20 20 20 2f 2f 2f 20 46 6f 72 20 65 78        /// For ex
2420: 61 6d 70 6c 65 2c 20 74 6f 20 6c 69 73 74 20 61  ample, to list a
2430: 6c 6c 20 69 6e 74 65 67 65 72 73 20 62 65 74 77  ll integers betw
2440: 65 65 6e 20 35 20 61 6e 64 20 35 30 3a 0d 0a 20  een 5 and 50:.. 
2450: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
2460: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
2470: 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20  <para><code>..  
2480: 20 20 20 20 20 20 2f 2f 2f 20 53 45 4c 45 43 54        /// SELECT
2490: 20 76 61 6c 75 65 20 46 52 4f 4d 20 67 65 6e 65   value FROM gene
24a0: 72 61 74 65 5f 73 65 72 69 65 73 28 35 2c 35 30  rate_series(5,50
24b0: 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  );..        /// 
24c0: 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a  </code></para>..
24d0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
24e0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
24f0: 54 68 65 20 70 72 65 76 69 6f 75 73 20 71 75 65  The previous que
2500: 72 79 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  ry is equivalent
2510: 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   to the followin
2520: 67 3a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  g:..        /// 
2530: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
2540: 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65   /// <para><code
2550: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 53  >..        /// S
2560: 45 4c 45 43 54 20 76 61 6c 75 65 20 46 52 4f 4d  ELECT value FROM
2570: 20 67 65 6e 65 72 61 74 65 5f 73 65 72 69 65 73   generate_series
2580: 20 57 48 45 52 45 20 73 74 61 72 74 3d 35 20 41   WHERE start=5 A
2590: 4e 44 20 73 74 6f 70 3d 35 30 3b 0d 0a 20 20 20  ND stop=50;..   
25a0: 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e       /// </code>
25b0: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
25c0: 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20   /// <para>..   
25d0: 20 20 20 20 20 2f 2f 2f 20 41 72 67 75 6d 65 6e       /// Argumen
25e0: 74 73 20 6f 6e 20 74 68 65 20 76 69 72 74 75 61  ts on the virtua
25f0: 6c 20 74 61 62 6c 65 20 6e 61 6d 65 20 61 72 65  l table name are
2600: 20 6d 61 74 63 68 65 64 20 74 6f 20 68 69 64 64   matched to hidd
2610: 65 6e 20 63 6f 6c 75 6d 6e 73 0d 0a 20 20 20 20  en columns..    
2620: 20 20 20 20 2f 2f 2f 20 69 6e 20 6f 72 64 65 72      /// in order
2630: 2e 20 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  .  The number of
2640: 20 61 72 67 75 6d 65 6e 74 73 20 63 61 6e 20 62   arguments can b
2650: 65 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 0d  e less than the.
2660: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6e 75 6d  .        /// num
2670: 62 65 72 20 6f 66 20 68 69 64 64 65 6e 20 63 6f  ber of hidden co
2680: 6c 75 6d 6e 73 2c 20 69 6e 20 77 68 69 63 68 20  lumns, in which 
2690: 63 61 73 65 20 74 68 65 20 6c 61 74 74 65 72 20  case the latter 
26a0: 68 69 64 64 65 6e 20 63 6f 6c 75 6d 6e 73 20 61  hidden columns a
26b0: 72 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  re..        /// 
26c0: 75 6e 63 6f 6e 73 74 72 61 69 6e 65 64 2e 20 20  unconstrained.  
26d0: 48 6f 77 65 76 65 72 2c 20 61 6e 20 65 72 72 6f  However, an erro
26e0: 72 20 72 65 73 75 6c 74 73 20 69 66 20 74 68 65  r results if the
26f0: 72 65 20 61 72 65 20 6d 6f 72 65 20 61 72 67 75  re are more argu
2700: 6d 65 6e 74 73 0d 0a 20 20 20 20 20 20 20 20 2f  ments..        /
2710: 2f 2f 20 74 68 61 6e 20 74 68 65 72 65 20 61 72  // than there ar
2720: 65 20 68 69 64 64 65 6e 20 63 6f 6c 75 6d 6e 73  e hidden columns
2730: 20 69 6e 20 74 68 65 20 76 69 72 74 75 61 6c 20   in the virtual 
2740: 74 61 62 6c 65 2e 0d 0a 20 20 20 20 20 20 20 20  table...        
2750: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
2760: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
2770: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 42 65 67  .        /// Beg
2780: 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69  inning with SQLi
2790: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 31 34 2e  te version 3.14.
27a0: 30 20 28 32 30 31 36 2d 30 38 2d 30 38 29 2c 20  0 (2016-08-08), 
27b0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68  ..        /// th
27c0: 65 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 73  e CREATE TABLE s
27d0: 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0d 0a 20  tatement that.. 
27e0: 20 20 20 20 20 20 20 2f 2f 2f 20 69 73 20 70 61         /// is pa
27f0: 73 73 65 64 20 69 6e 74 6f 20 73 71 6c 69 74 65  ssed into sqlite
2800: 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 29  3_declare_vtab()
2810: 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 20 57   may contain a W
2820: 49 54 48 4f 55 54 20 52 4f 57 49 44 20 63 6c 61  ITHOUT ROWID cla
2830: 75 73 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  use...        //
2840: 2f 20 54 68 69 73 20 69 73 20 75 73 65 66 75 6c  / This is useful
2850: 20 66 6f 72 20 63 61 73 65 73 20 77 68 65 72 65   for cases where
2860: 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
2870: 6c 65 20 72 6f 77 73 20 0d 0a 20 20 20 20 20 20  le rows ..      
2880: 20 20 2f 2f 2f 20 63 61 6e 6e 6f 74 20 65 61 73    /// cannot eas
2890: 69 6c 79 20 62 65 20 6d 61 70 70 65 64 20 69 6e  ily be mapped in
28a0: 74 6f 20 75 6e 69 71 75 65 20 69 6e 74 65 67 65  to unique intege
28b0: 72 73 2e 20 20 41 20 43 52 45 41 54 45 20 54 41  rs.  A CREATE TA
28c0: 42 4c 45 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  BLE..        ///
28d0: 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
28e0: 69 6e 63 6c 75 64 65 73 20 57 49 54 48 4f 55 54  includes WITHOUT
28f0: 20 52 4f 57 49 44 20 6d 75 73 74 20 64 65 66 69   ROWID must defi
2900: 6e 65 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63  ne one or more c
2910: 6f 6c 75 6d 6e 73 20 61 73 0d 0a 20 20 20 20 20  olumns as..     
2920: 20 20 20 2f 2f 2f 20 74 68 65 20 50 52 49 4d 41     /// the PRIMA
2930: 52 59 20 4b 45 59 2e 20 20 45 76 65 72 79 20 63  RY KEY.  Every c
2940: 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 50 52 49  olumn of the PRI
2950: 4d 41 52 59 20 4b 45 59 20 6d 75 73 74 20 69 6e  MARY KEY must in
2960: 64 69 76 69 64 75 61 6c 6c 79 20 62 65 0d 0a 20  dividually be.. 
2970: 20 20 20 20 20 20 20 2f 2f 2f 20 4e 4f 54 20 4e         /// NOT N
2980: 55 4c 4c 20 61 6e 64 20 61 6c 6c 20 63 6f 6c 75  ULL and all colu
2990: 6d 6e 73 20 66 6f 72 20 65 61 63 68 20 72 6f 77  mns for each row
29a0: 20 6d 75 73 74 20 62 65 20 63 6f 6c 6c 65 63 74   must be collect
29b0: 69 76 65 6c 79 20 75 6e 69 71 75 65 2e 0d 0a 20  ively unique... 
29c0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
29d0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
29e0: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
29f0: 2f 2f 2f 20 4e 6f 74 65 20 74 68 61 74 20 53 51  /// Note that SQ
2a00: 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 65 6e  Lite does not en
2a10: 66 6f 72 63 65 20 74 68 65 20 50 52 49 4d 41 52  force the PRIMAR
2a20: 59 20 4b 45 59 20 66 6f 72 20 61 20 57 49 54 48  Y KEY for a WITH
2a30: 4f 55 54 20 52 4f 57 49 44 0d 0a 20 20 20 20 20  OUT ROWID..     
2a40: 20 20 20 2f 2f 2f 20 76 69 72 74 75 61 6c 20 74     /// virtual t
2a50: 61 62 6c 65 2e 20 20 45 6e 66 6f 72 63 65 6d 65  able.  Enforceme
2a60: 6e 74 20 69 73 20 74 68 65 20 72 65 73 70 6f 6e  nt is the respon
2a70: 73 69 62 69 6c 69 74 79 20 6f 66 20 74 68 65 20  sibility of the 
2a80: 75 6e 64 65 72 6c 79 69 6e 67 0d 0a 20 20 20 20  underlying..    
2a90: 20 20 20 20 2f 2f 2f 20 76 69 72 74 75 61 6c 20      /// virtual 
2aa0: 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
2ab0: 74 69 6f 6e 2e 20 20 42 75 74 20 53 51 4c 69 74  tion.  But SQLit
2ac0: 65 20 64 6f 65 73 20 61 73 73 75 6d 65 20 74 68  e does assume th
2ad0: 61 74 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b  at the PRIMARY K
2ae0: 45 59 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  EY..        /// 
2af0: 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 76 61  constraint is va
2b00: 6c 69 64 20 2d 20 74 68 61 74 20 74 68 65 20 69  lid - that the i
2b10: 64 65 6e 74 69 66 69 65 64 20 63 6f 6c 75 6d 6e  dentified column
2b20: 73 20 72 65 61 6c 6c 79 20 61 72 65 20 55 4e 49  s really are UNI
2b30: 51 55 45 20 61 6e 64 0d 0a 20 20 20 20 20 20 20  QUE and..       
2b40: 20 2f 2f 2f 20 4e 4f 54 20 4e 55 4c 4c 20 2d 20   /// NOT NULL - 
2b50: 61 6e 64 20 69 74 20 75 73 65 73 20 74 68 61 74  and it uses that
2b60: 20 61 73 73 75 6d 70 74 69 6f 6e 20 74 6f 20 6f   assumption to o
2b70: 70 74 69 6d 69 7a 65 20 71 75 65 72 69 65 73 20  ptimize queries 
2b80: 61 67 61 69 6e 73 74 20 74 68 65 0d 0a 20 20 20  against the..   
2b90: 20 20 20 20 20 2f 2f 2f 20 76 69 72 74 75 61 6c       /// virtual
2ba0: 20 74 61 62 6c 65 2e 0d 0a 20 20 20 20 20 20 20   table...       
2bb0: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
2bc0: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
2bd0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
2be0: 65 20 72 6f 77 69 64 20 63 6f 6c 75 6d 6e 20 69  e rowid column i
2bf0: 73 20 6e 6f 74 20 61 63 63 65 73 73 69 62 6c 65  s not accessible
2c00: 20 6f 6e 20 61 0d 0a 20 20 20 20 20 20 20 20 2f   on a..        /
2c10: 2f 2f 20 57 49 54 48 4f 55 54 20 52 4f 57 49 44  // WITHOUT ROWID
2c20: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 28   virtual table (
2c30: 6f 66 20 63 6f 75 72 73 65 29 2e 20 20 46 75 72  of course).  Fur
2c40: 74 68 65 72 6d 6f 72 65 2c 20 73 69 6e 63 65 20  thermore, since 
2c50: 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  the..        ///
2c60: 20 78 55 70 64 61 74 65 20 6d 65 74 68 6f 64 20   xUpdate method 
2c70: 64 65 70 65 6e 64 73 20 6f 6e 20 68 61 76 69 6e  depends on havin
2c80: 67 20 61 20 76 61 6c 69 64 20 72 6f 77 69 64 2c  g a valid rowid,
2c90: 20 74 68 65 20 78 55 70 64 61 74 65 20 6d 65 74   the xUpdate met
2ca0: 68 6f 64 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  hod ..        //
2cb0: 2f 20 6d 75 73 74 20 62 65 20 4e 55 4c 4c 20 66  / must be NULL f
2cc0: 6f 72 20 61 20 57 49 54 48 4f 55 54 20 52 4f 57  or a WITHOUT ROW
2cd0: 49 44 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ID virtual table
2ce0: 2e 20 20 54 68 61 74 20 69 6e 20 74 75 72 6e 20  .  That in turn 
2cf0: 6d 65 61 6e 73 20 74 68 61 74 0d 0a 20 20 20 20  means that..    
2d00: 20 20 20 20 2f 2f 2f 20 57 49 54 48 4f 55 54 20      /// WITHOUT 
2d10: 52 4f 57 49 44 20 76 69 72 74 75 61 6c 20 74 61  ROWID virtual ta
2d20: 62 6c 65 73 20 6d 75 73 74 20 62 65 20 72 65 61  bles must be rea
2d30: 64 2d 6f 6e 6c 79 2e 0d 0a 20 20 20 20 20 20 20  d-only...       
2d40: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
2d50: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d        /// </summ
2d60: 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ary>..        //
2d70: 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70  / <param name="p
2d80: 44 62 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  Db">..        //
2d90: 2f 20 54 68 65 20 6e 61 74 69 76 65 20 64 61 74  / The native dat
2da0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2db0: 20 68 61 6e 64 6c 65 2e 0d 0a 20 20 20 20 20 20   handle...      
2dc0: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a    /// </param>..
2dd0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
2de0: 61 6d 20 6e 61 6d 65 3d 22 70 41 75 78 22 3e 0d  am name="pAux">.
2df0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65  .        /// The
2e00: 20 6f 72 69 67 69 6e 61 6c 20 6e 61 74 69 76 65   original native
2e10: 20 70 6f 69 6e 74 65 72 20 76 61 6c 75 65 20 74   pointer value t
2e20: 68 61 74 20 77 61 73 20 70 72 6f 76 69 64 65 64  hat was provided
2e30: 20 74 6f 20 74 68 65 0d 0a 20 20 20 20 20 20 20   to the..       
2e40: 20 2f 2f 2f 20 73 71 6c 69 74 65 33 5f 63 72 65   /// sqlite3_cre
2e50: 61 74 65 5f 6d 6f 64 75 6c 65 28 29 2c 20 73 71  ate_module(), sq
2e60: 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
2e70: 75 6c 65 5f 76 32 28 29 20 6f 72 0d 0a 20 20 20  ule_v2() or..   
2e80: 20 20 20 20 20 2f 2f 2f 20 73 71 6c 69 74 65 33       /// sqlite3
2e90: 5f 63 72 65 61 74 65 5f 64 69 73 70 6f 73 61 62  _create_disposab
2ea0: 6c 65 5f 6d 6f 64 75 6c 65 28 29 20 66 75 6e 63  le_module() func
2eb0: 74 69 6f 6e 73 2e 0d 0a 20 20 20 20 20 20 20 20  tions...        
2ec0: 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20  /// </param>..  
2ed0: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d        /// <param
2ee0: 20 6e 61 6d 65 3d 22 61 72 67 63 22 3e 0d 0a 20   name="argc">.. 
2ef0: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e         /// The n
2f00: 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
2f10: 74 73 20 66 72 6f 6d 20 74 68 65 20 43 52 45 41  ts from the CREA
2f20: 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45  TE VIRTUAL TABLE
2f30: 20 73 74 61 74 65 6d 65 6e 74 2e 0d 0a 20 20 20   statement...   
2f40: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d       /// </param
2f50: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
2f60: 70 61 72 61 6d 20 6e 61 6d 65 3d 22 61 72 67 76  param name="argv
2f70: 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ">..        /// 
2f80: 54 68 65 20 61 72 72 61 79 20 6f 66 20 73 74 72  The array of str
2f90: 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 66 72  ing arguments fr
2fa0: 6f 6d 20 74 68 65 20 43 52 45 41 54 45 20 56 49  om the CREATE VI
2fb0: 52 54 55 41 4c 20 54 41 42 4c 45 0d 0a 20 20 20  RTUAL TABLE..   
2fc0: 20 20 20 20 20 2f 2f 2f 20 73 74 61 74 65 6d 65       /// stateme
2fd0: 6e 74 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  nt...        ///
2fe0: 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20   </param>..     
2ff0: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61     /// <param na
3000: 6d 65 3d 22 70 56 74 61 62 22 3e 0d 0a 20 20 20  me="pVtab">..   
3010: 20 20 20 20 20 2f 2f 2f 20 55 70 6f 6e 20 73 75       /// Upon su
3020: 63 63 65 73 73 2c 20 74 68 69 73 20 70 61 72 61  ccess, this para
3030: 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 6d 6f  meter must be mo
3040: 64 69 66 69 65 64 20 74 6f 20 70 6f 69 6e 74 20  dified to point 
3050: 74 6f 20 74 68 65 20 6e 65 77 6c 79 0d 0a 20 20  to the newly..  
3060: 20 20 20 20 20 20 2f 2f 2f 20 63 72 65 61 74 65        /// create
3070: 64 20 6e 61 74 69 76 65 20 73 71 6c 69 74 65 33  d native sqlite3
3080: 5f 76 74 61 62 20 64 65 72 69 76 65 64 20 73 74  _vtab derived st
3090: 72 75 63 74 75 72 65 2e 0d 0a 20 20 20 20 20 20  ructure...      
30a0: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a    /// </param>..
30b0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
30c0: 61 6d 20 6e 61 6d 65 3d 22 70 45 72 72 6f 72 22  am name="pError"
30d0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 55  >..        /// U
30e0: 70 6f 6e 20 66 61 69 6c 75 72 65 2c 20 74 68 69  pon failure, thi
30f0: 73 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  s parameter must
3100: 20 62 65 20 6d 6f 64 69 66 69 65 64 20 74 6f 20   be modified to 
3110: 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 65 72 72  point to the err
3120: 6f 72 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  or..        /// 
3130: 6d 65 73 73 61 67 65 2c 20 77 69 74 68 20 74 68  message, with th
3140: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6d 65 6d  e underlying mem
3150: 6f 72 79 20 68 61 76 69 6e 67 20 62 65 65 6e 20  ory having been 
3160: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 68  obtained from th
3170: 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73  e..        /// s
3180: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
3190: 66 75 6e 63 74 69 6f 6e 2e 0d 0a 20 20 20 20 20  function...     
31a0: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d     /// </param>.
31b0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 72 65  .        /// <re
31c0: 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20  turns>..        
31d0: 2f 2f 2f 20 41 20 73 74 61 6e 64 61 72 64 20 53  /// A standard S
31e0: 51 4c 69 74 65 20 72 65 74 75 72 6e 20 63 6f 64  QLite return cod
31f0: 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e...        /// 
3200: 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20  </returns>..    
3210: 20 20 20 20 53 51 4c 69 74 65 45 72 72 6f 72 43      SQLiteErrorC
3220: 6f 64 65 20 78 43 72 65 61 74 65 28 0d 0a 20 20  ode xCreate(..  
3230: 20 20 20 20 20 20 20 20 20 20 49 6e 74 50 74 72            IntPtr
3240: 20 70 44 62 2c 0d 0a 20 20 20 20 20 20 20 20 20   pDb,..         
3250: 20 20 20 49 6e 74 50 74 72 20 70 41 75 78 2c 0d     IntPtr pAux,.
3260: 0a 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74  .            int
3270: 20 61 72 67 63 2c 0d 0a 20 20 20 20 20 20 20 20   argc,..        
3280: 20 20 20 20 49 6e 74 50 74 72 20 61 72 67 76 2c      IntPtr argv,
3290: 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 72 65  ..            re
32a0: 66 20 49 6e 74 50 74 72 20 70 56 74 61 62 2c 0d  f IntPtr pVtab,.
32b0: 0a 20 20 20 20 20 20 20 20 20 20 20 20 72 65 66  .            ref
32c0: 20 49 6e 74 50 74 72 20 70 45 72 72 6f 72 0d 0a   IntPtr pError..
32d0: 20 20 20 20 20 20 20 20 20 20 20 20 29 3b 0d 0a              );..
32e0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f  ..        //////
32f0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
3300: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
3310: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
3320: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
3330: 2f 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  /....        ///
3340: 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20   <summary>..    
3350: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63      /// <para><c
3360: 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ode>..        //
3370: 2f 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74  / int (*xConnect
3380: 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  )(sqlite3*, void
3390: 20 2a 70 41 75 78 2c 0d 0a 20 20 20 20 20 20 20   *pAux,..       
33a0: 20 2f 2f 2f 20 20 20 20 20 20 20 20 20 20 20 20   ///            
33b0: 20 20 69 6e 74 20 61 72 67 63 2c 20 63 68 61 72    int argc, char
33c0: 20 2a 2a 61 72 67 76 2c 0d 0a 20 20 20 20 20 20   **argv,..      
33d0: 20 20 2f 2f 2f 20 20 20 20 20 20 20 20 20 20 20    ///           
33e0: 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20     sqlite3_vtab 
33f0: 2a 2a 70 70 56 54 61 62 2c 0d 0a 20 20 20 20 20  **ppVTab,..     
3400: 20 20 20 2f 2f 2f 20 20 20 20 20 20 20 20 20 20     ///          
3410: 20 20 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72      char **pzErr
3420: 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  );..        /// 
3430: 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a  </code></para>..
3440: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
3450: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
3460: 54 68 65 20 78 43 6f 6e 6e 65 63 74 20 6d 65 74  The xConnect met
3470: 68 6f 64 20 69 73 20 76 65 72 79 20 73 69 6d 69  hod is very simi
3480: 6c 61 72 20 74 6f 20 78 43 72 65 61 74 65 2e 20  lar to xCreate. 
3490: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 49 74  ..        /// It
34a0: 20 68 61 73 20 74 68 65 20 73 61 6d 65 20 70 61   has the same pa
34b0: 72 61 6d 65 74 65 72 73 20 61 6e 64 20 63 6f 6e  rameters and con
34c0: 73 74 72 75 63 74 73 20 61 20 6e 65 77 20 73 71  structs a new sq
34d0: 6c 69 74 65 33 5f 76 74 61 62 20 73 74 72 75 63  lite3_vtab struc
34e0: 74 75 72 65 20 0d 0a 20 20 20 20 20 20 20 20 2f  ture ..        /
34f0: 2f 2f 20 6a 75 73 74 20 6c 69 6b 65 20 78 43 72  // just like xCr
3500: 65 61 74 65 2e 20 0d 0a 20 20 20 20 20 20 20 20  eate. ..        
3510: 2f 2f 2f 20 41 6e 64 20 69 74 20 6d 75 73 74 20  /// And it must 
3520: 61 6c 73 6f 20 63 61 6c 6c 20 73 71 6c 69 74 65  also call sqlite
3530: 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 29  3_declare_vtab()
3540: 20 6c 69 6b 65 20 78 43 72 65 61 74 65 2e 0d 0a   like xCreate...
3550: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
3560: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
3570: 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20   <para>..       
3580: 20 2f 2f 2f 20 54 68 65 20 64 69 66 66 65 72 65   /// The differe
3590: 6e 63 65 20 69 73 20 74 68 61 74 20 78 43 6f 6e  nce is that xCon
35a0: 6e 65 63 74 20 69 73 20 63 61 6c 6c 65 64 20 74  nect is called t
35b0: 6f 20 65 73 74 61 62 6c 69 73 68 20 61 20 6e 65  o establish a ne
35c0: 77 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  w ..        /// 
35d0: 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 61 6e  connection to an
35e0: 20 65 78 69 73 74 69 6e 67 20 76 69 72 74 75 61   existing virtua
35f0: 6c 20 74 61 62 6c 65 20 77 68 65 72 65 61 73 20  l table whereas 
3600: 78 43 72 65 61 74 65 20 69 73 20 63 61 6c 6c 65  xCreate is calle
3610: 64 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  d ..        /// 
3620: 74 6f 20 63 72 65 61 74 65 20 61 20 6e 65 77 20  to create a new 
3630: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 66 72  virtual table fr
3640: 6f 6d 20 73 63 72 61 74 63 68 2e 0d 0a 20 20 20  om scratch...   
3650: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e       /// </para>
3660: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
3670: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
3680: 2f 20 54 68 65 20 78 43 72 65 61 74 65 20 61 6e  / The xCreate an
3690: 64 20 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68 6f  d xConnect metho
36a0: 64 73 20 61 72 65 20 6f 6e 6c 79 20 64 69 66 66  ds are only diff
36b0: 65 72 65 6e 74 20 77 68 65 6e 20 74 68 65 0d 0a  erent when the..
36c0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 76 69 72 74          /// virt
36d0: 75 61 6c 20 74 61 62 6c 65 20 68 61 73 20 73 6f  ual table has so
36e0: 6d 65 20 6b 69 6e 64 20 6f 66 20 62 61 63 6b 69  me kind of backi
36f0: 6e 67 20 73 74 6f 72 65 20 74 68 61 74 20 6d 75  ng store that mu
3700: 73 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65  st be initialize
3710: 64 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  d ..        /// 
3720: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  the first time t
3730: 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
3740: 20 69 73 20 63 72 65 61 74 65 64 2e 20 54 68 65   is created. The
3750: 20 78 43 72 65 61 74 65 20 6d 65 74 68 6f 64 20   xCreate method 
3760: 63 72 65 61 74 65 73 20 0d 0a 20 20 20 20 20 20  creates ..      
3770: 20 20 2f 2f 2f 20 61 6e 64 20 69 6e 69 74 69 61    /// and initia
3780: 6c 69 7a 65 73 20 74 68 65 20 62 61 63 6b 69 6e  lizes the backin
3790: 67 20 73 74 6f 72 65 2e 20 54 68 65 20 78 43 6f  g store. The xCo
37a0: 6e 6e 65 63 74 20 6d 65 74 68 6f 64 20 6a 75 73  nnect method jus
37b0: 74 20 63 6f 6e 6e 65 63 74 73 20 0d 0a 20 20 20  t connects ..   
37c0: 20 20 20 20 20 2f 2f 2f 20 74 6f 20 61 6e 20 65       /// to an e
37d0: 78 69 73 74 69 6e 67 20 62 61 63 6b 69 6e 67 20  xisting backing 
37e0: 73 74 6f 72 65 2e 20 20 57 68 65 6e 20 78 43 72  store.  When xCr
37f0: 65 61 74 65 20 61 6e 64 20 78 43 6f 6e 6e 65 63  eate and xConnec
3800: 74 20 61 72 65 20 74 68 65 20 73 61 6d 65 2c 0d  t are the same,.
3810: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65  .        /// the
3820: 20 74 61 62 6c 65 20 69 73 20 61 6e 20 65 70 6f   table is an epo
3830: 6e 79 6d 6f 75 73 20 76 69 72 74 75 61 6c 20 74  nymous virtual t
3840: 61 62 6c 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f  able...        /
3850: 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  // </para>..    
3860: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a      /// <para>..
3870: 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 73 20 61          /// As a
3880: 6e 20 65 78 61 6d 70 6c 65 2c 20 63 6f 6e 73 69  n example, consi
3890: 64 65 72 20 61 20 76 69 72 74 75 61 6c 20 74 61  der a virtual ta
38a0: 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
38b0: 6f 6e 20 74 68 61 74 20 0d 0a 20 20 20 20 20 20  on that ..      
38c0: 20 20 2f 2f 2f 20 70 72 6f 76 69 64 65 73 20 72    /// provides r
38d0: 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 20  ead-only access 
38e0: 74 6f 20 65 78 69 73 74 69 6e 67 20 63 6f 6d 6d  to existing comm
38f0: 61 2d 73 65 70 61 72 61 74 65 64 2d 76 61 6c 75  a-separated-valu
3900: 65 20 28 43 53 56 29 0d 0a 20 20 20 20 20 20 20  e (CSV)..       
3910: 20 2f 2f 2f 20 66 69 6c 65 73 20 6f 6e 20 64 69   /// files on di
3920: 73 6b 2e 20 54 68 65 72 65 20 69 73 20 6e 6f 20  sk. There is no 
3930: 62 61 63 6b 69 6e 67 20 73 74 6f 72 65 20 74 68  backing store th
3940: 61 74 20 6e 65 65 64 73 20 74 6f 20 62 65 20 63  at needs to be c
3950: 72 65 61 74 65 64 20 0d 0a 20 20 20 20 20 20 20  reated ..       
3960: 20 2f 2f 2f 20 6f 72 20 69 6e 69 74 69 61 6c 69   /// or initiali
3970: 7a 65 64 20 66 6f 72 20 73 75 63 68 20 61 20 76  zed for such a v
3980: 69 72 74 75 61 6c 20 74 61 62 6c 65 20 28 73 69  irtual table (si
3990: 6e 63 65 20 74 68 65 20 43 53 56 20 66 69 6c 65  nce the CSV file
39a0: 73 20 61 6c 72 65 61 64 79 20 0d 0a 20 20 20 20  s already ..    
39b0: 20 20 20 20 2f 2f 2f 20 65 78 69 73 74 20 6f 6e      /// exist on
39c0: 20 64 69 73 6b 29 20 73 6f 20 74 68 65 20 78 43   disk) so the xC
39d0: 72 65 61 74 65 20 61 6e 64 20 78 43 6f 6e 6e 65  reate and xConne
39e0: 63 74 20 6d 65 74 68 6f 64 73 20 77 69 6c 6c 20  ct methods will 
39f0: 62 65 20 69 64 65 6e 74 69 63 61 6c 20 0d 0a 20  be identical .. 
3a00: 20 20 20 20 20 20 20 2f 2f 2f 20 66 6f 72 20 74         /// for t
3a10: 68 61 74 20 6d 6f 64 75 6c 65 2e 0d 0a 20 20 20  hat module...   
3a20: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e       /// </para>
3a30: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
3a40: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
3a50: 2f 20 41 6e 6f 74 68 65 72 20 65 78 61 6d 70 6c  / Another exampl
3a60: 65 20 69 73 20 61 20 76 69 72 74 75 61 6c 20 74  e is a virtual t
3a70: 61 62 6c 65 20 74 68 61 74 20 69 6d 70 6c 65 6d  able that implem
3a80: 65 6e 74 73 20 61 20 66 75 6c 6c 2d 74 65 78 74  ents a full-text
3a90: 20 69 6e 64 65 78 2e 20 0d 0a 20 20 20 20 20 20   index. ..      
3aa0: 20 20 2f 2f 2f 20 54 68 65 20 78 43 72 65 61 74    /// The xCreat
3ab0: 65 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 63 72  e method must cr
3ac0: 65 61 74 65 20 61 6e 64 20 69 6e 69 74 69 61 6c  eate and initial
3ad0: 69 7a 65 20 64 61 74 61 20 73 74 72 75 63 74 75  ize data structu
3ae0: 72 65 73 20 74 6f 20 68 6f 6c 64 20 0d 0a 20 20  res to hold ..  
3af0: 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 20 64 69        /// the di
3b00: 63 74 69 6f 6e 61 72 79 20 61 6e 64 20 70 6f 73  ctionary and pos
3b10: 74 69 6e 67 20 6c 69 73 74 73 20 66 6f 72 20 74  ting lists for t
3b20: 68 61 74 20 69 6e 64 65 78 2e 20 54 68 65 20 78  hat index. The x
3b30: 43 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64 2c 0d  Connect method,.
3b40: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6f 6e 20  .        /// on 
3b50: 74 68 65 20 6f 74 68 65 72 20 68 61 6e 64 2c 20  the other hand, 
3b60: 6f 6e 6c 79 20 68 61 73 20 74 6f 20 6c 6f 63 61  only has to loca
3b70: 74 65 20 61 6e 64 20 75 73 65 20 61 6e 20 65 78  te and use an ex
3b80: 69 73 74 69 6e 67 20 64 69 63 74 69 6f 6e 61 72  isting dictionar
3b90: 79 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  y ..        /// 
3ba0: 61 6e 64 20 70 6f 73 74 69 6e 67 20 6c 69 73 74  and posting list
3bb0: 73 20 74 68 61 74 20 77 65 72 65 20 63 72 65 61  s that were crea
3bc0: 74 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 78  ted by a prior x
3bd0: 43 72 65 61 74 65 20 63 61 6c 6c 2e 0d 0a 20 20  Create call...  
3be0: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61        /// </para
3bf0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
3c00: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
3c10: 2f 2f 20 54 68 65 20 78 43 6f 6e 6e 65 63 74 20  // The xConnect 
3c20: 6d 65 74 68 6f 64 20 6d 75 73 74 20 72 65 74 75  method must retu
3c30: 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
3c40: 69 74 20 69 73 20 73 75 63 63 65 73 73 66 75 6c  it is successful
3c50: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69   ..        /// i
3c60: 6e 20 63 72 65 61 74 69 6e 67 20 74 68 65 20 6e  n creating the n
3c70: 65 77 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ew virtual table
3c80: 2c 20 6f 72 20 53 51 4c 49 54 45 5f 45 52 52 4f  , or SQLITE_ERRO
3c90: 52 20 69 66 20 69 74 20 69 73 20 6e 6f 74 20 0d  R if it is not .
3ca0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 75 63  .        /// suc
3cb0: 63 65 73 73 66 75 6c 2e 20 49 66 20 6e 6f 74 20  cessful. If not 
3cc0: 73 75 63 63 65 73 73 66 75 6c 2c 20 74 68 65 20  successful, the 
3cd0: 73 71 6c 69 74 65 33 5f 76 74 61 62 20 73 74 72  sqlite3_vtab str
3ce0: 75 63 74 75 72 65 20 6d 75 73 74 20 6e 6f 74 20  ucture must not 
3cf0: 62 65 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  be ..        ///
3d00: 20 61 6c 6c 6f 63 61 74 65 64 2e 20 41 6e 20 65   allocated. An e
3d10: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 6d 61 79  rror message may
3d20: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 72   optionally be r
3d30: 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 7a 45 72  eturned in *pzEr
3d40: 72 20 69 66 20 0d 0a 20 20 20 20 20 20 20 20 2f  r if ..        /
3d50: 2f 2f 20 75 6e 73 75 63 63 65 73 73 66 75 6c 2e  // unsuccessful.
3d60: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 53   ..        /// S
3d70: 70 61 63 65 20 74 6f 20 68 6f 6c 64 20 74 68 65  pace to hold the
3d80: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3d90: 74 72 69 6e 67 20 6d 75 73 74 20 62 65 20 61 6c  tring must be al
3da0: 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 0d 0a 20  located using.. 
3db0: 20 20 20 20 20 20 20 2f 2f 2f 20 61 6e 20 53 51         /// an SQ
3dc0: 4c 69 74 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  Lite memory allo
3dd0: 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  cation function 
3de0: 6c 69 6b 65 20 0d 0a 20 20 20 20 20 20 20 20 2f  like ..        /
3df0: 2f 2f 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  // sqlite3_mallo
3e00: 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6d  c() or sqlite3_m
3e10: 70 72 69 6e 74 66 28 29 20 61 73 20 74 68 65 20  printf() as the 
3e20: 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c  SQLite core will
3e30: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 61 74  ..        /// at
3e40: 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68  tempt to free th
3e50: 65 20 73 70 61 63 65 20 75 73 69 6e 67 20 73 71  e space using sq
3e60: 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61 66 74  lite3_free() aft
3e70: 65 72 20 74 68 65 20 65 72 72 6f 72 20 68 61 73  er the error has
3e80: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 62 65  ..        /// be
3e90: 65 6e 20 72 65 70 6f 72 74 65 64 20 75 70 20 74  en reported up t
3ea0: 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
3eb0: 6e 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  n...        /// 
3ec0: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
3ed0: 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20   /// <para>..   
3ee0: 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 43 6f       /// The xCo
3ef0: 6e 6e 65 63 74 20 6d 65 74 68 6f 64 20 69 73 20  nnect method is 
3f00: 72 65 71 75 69 72 65 64 20 66 6f 72 20 65 76 65  required for eve
3f10: 72 79 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ry virtual table
3f20: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c   implementation,
3f30: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74   ..        /// t
3f40: 68 6f 75 67 68 20 74 68 65 20 78 43 72 65 61 74  hough the xCreat
3f50: 65 20 61 6e 64 20 78 43 6f 6e 6e 65 63 74 20 70  e and xConnect p
3f60: 6f 69 6e 74 65 72 73 20 6f 66 20 74 68 65 20 73  ointers of the s
3f70: 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 6f 62  qlite3_module ob
3f80: 6a 65 63 74 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ject..        //
3f90: 2f 20 6d 61 79 20 70 6f 69 6e 74 20 74 6f 20 74  / may point to t
3fa0: 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
3fb0: 20 69 66 20 74 68 65 20 76 69 72 74 75 61 6c 20   if the virtual 
3fc0: 74 61 62 6c 65 20 64 6f 65 73 20 6e 6f 74 20 6e  table does not n
3fd0: 65 65 64 20 74 6f 0d 0a 20 20 20 20 20 20 20 20  eed to..        
3fe0: 2f 2f 2f 20 69 6e 69 74 69 61 6c 69 7a 65 20 62  /// initialize b
3ff0: 61 63 6b 69 6e 67 20 73 74 6f 72 65 2e 0d 0a 20  acking store... 
4000: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
4010: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
4020: 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20  </summary>..    
4030: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e      /// <param n
4040: 61 6d 65 3d 22 70 44 62 22 3e 0d 0a 20 20 20 20  ame="pDb">..    
4050: 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e 61 74 69      /// The nati
4060: 76 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ve database conn
4070: 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 2e 0d 0a  ection handle...
4080: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
4090: 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ram>..        //
40a0: 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70  / <param name="p
40b0: 41 75 78 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f  Aux">..        /
40c0: 2f 2f 20 54 68 65 20 6f 72 69 67 69 6e 61 6c 20  // The original 
40d0: 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72 20 76  native pointer v
40e0: 61 6c 75 65 20 74 68 61 74 20 77 61 73 20 70 72  alue that was pr
40f0: 6f 76 69 64 65 64 20 74 6f 20 74 68 65 0d 0a 20  ovided to the.. 
4100: 20 20 20 20 20 20 20 2f 2f 2f 20 73 71 6c 69 74         /// sqlit
4110: 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
4120: 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 72 65 61  (), sqlite3_crea
4130: 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 20 6f  te_module_v2() o
4140: 72 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73  r..        /// s
4150: 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 64 69  qlite3_create_di
4160: 73 70 6f 73 61 62 6c 65 5f 6d 6f 64 75 6c 65 28  sposable_module(
4170: 29 20 66 75 6e 63 74 69 6f 6e 73 2e 0d 0a 20 20  ) functions...  
4180: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61        /// </para
4190: 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  m>..        /// 
41a0: 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 61 72 67  <param name="arg
41b0: 63 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  c">..        ///
41c0: 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   The number of a
41d0: 72 67 75 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68  rguments from th
41e0: 65 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c  e CREATE VIRTUAL
41f0: 20 54 41 42 4c 45 20 73 74 61 74 65 6d 65 6e 74   TABLE statement
4200: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
4210: 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20  /param>..       
4220: 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65   /// <param name
4230: 3d 22 61 72 67 76 22 3e 0d 0a 20 20 20 20 20 20  ="argv">..      
4240: 20 20 2f 2f 2f 20 54 68 65 20 61 72 72 61 79 20    /// The array 
4250: 6f 66 20 73 74 72 69 6e 67 20 61 72 67 75 6d 65  of string argume
4260: 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 43 52 45  nts from the CRE
4270: 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c  ATE VIRTUAL TABL
4280: 45 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73  E..        /// s
4290: 74 61 74 65 6d 65 6e 74 2e 0d 0a 20 20 20 20 20  tatement...     
42a0: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d     /// </param>.
42b0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
42c0: 72 61 6d 20 6e 61 6d 65 3d 22 70 56 74 61 62 22  ram name="pVtab"
42d0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 55  >..        /// U
42e0: 70 6f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 69  pon success, thi
42f0: 73 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  s parameter must
4300: 20 62 65 20 6d 6f 64 69 66 69 65 64 20 74 6f 20   be modified to 
4310: 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 6e 65 77  point to the new
4320: 6c 79 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ly..        /// 
4330: 63 72 65 61 74 65 64 20 6e 61 74 69 76 65 20 73  created native s
4340: 71 6c 69 74 65 33 5f 76 74 61 62 20 64 65 72 69  qlite3_vtab deri
4350: 76 65 64 20 73 74 72 75 63 74 75 72 65 2e 0d 0a  ved structure...
4360: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
4370: 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ram>..        //
4380: 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70  / <param name="p
4390: 45 72 72 6f 72 22 3e 0d 0a 20 20 20 20 20 20 20  Error">..       
43a0: 20 2f 2f 2f 20 55 70 6f 6e 20 66 61 69 6c 75 72   /// Upon failur
43b0: 65 2c 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  e, this paramete
43c0: 72 20 6d 75 73 74 20 62 65 20 6d 6f 64 69 66 69  r must be modifi
43d0: 65 64 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74  ed to point to t
43e0: 68 65 20 65 72 72 6f 72 0d 0a 20 20 20 20 20 20  he error..      
43f0: 20 20 2f 2f 2f 20 6d 65 73 73 61 67 65 2c 20 77    /// message, w
4400: 69 74 68 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ith the underlyi
4410: 6e 67 20 6d 65 6d 6f 72 79 20 68 61 76 69 6e 67  ng memory having
4420: 20 62 65 65 6e 20 6f 62 74 61 69 6e 65 64 20 66   been obtained f
4430: 72 6f 6d 20 74 68 65 0d 0a 20 20 20 20 20 20 20  rom the..       
4440: 20 2f 2f 2f 20 73 71 6c 69 74 65 33 5f 6d 61 6c   /// sqlite3_mal
4450: 6c 6f 63 28 29 20 66 75 6e 63 74 69 6f 6e 2e 0d  loc() function..
4460: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
4470: 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f  aram>..        /
4480: 2f 2f 20 3c 72 65 74 75 72 6e 73 3e 0d 0a 20 20  // <returns>..  
4490: 20 20 20 20 20 20 2f 2f 2f 20 41 20 73 74 61 6e        /// A stan
44a0: 64 61 72 64 20 53 51 4c 69 74 65 20 72 65 74 75  dard SQLite retu
44b0: 72 6e 20 63 6f 64 65 2e 0d 0a 20 20 20 20 20 20  rn code...      
44c0: 20 20 2f 2f 2f 20 3c 2f 72 65 74 75 72 6e 73 3e    /// </returns>
44d0: 0d 0a 20 20 20 20 20 20 20 20 53 51 4c 69 74 65  ..        SQLite
44e0: 45 72 72 6f 72 43 6f 64 65 20 78 43 6f 6e 6e 65  ErrorCode xConne
44f0: 63 74 28 0d 0a 20 20 20 20 20 20 20 20 20 20 20  ct(..           
4500: 20 49 6e 74 50 74 72 20 70 44 62 2c 0d 0a 20 20   IntPtr pDb,..  
4510: 20 20 20 20 20 20 20 20 20 20 49 6e 74 50 74 72            IntPtr
4520: 20 70 41 75 78 2c 0d 0a 20 20 20 20 20 20 20 20   pAux,..        
4530: 20 20 20 20 69 6e 74 20 61 72 67 63 2c 0d 0a 20      int argc,.. 
4540: 20 20 20 20 20 20 20 20 20 20 20 49 6e 74 50 74             IntPt
4550: 72 20 61 72 67 76 2c 0d 0a 20 20 20 20 20 20 20  r argv,..       
4560: 20 20 20 20 20 72 65 66 20 49 6e 74 50 74 72 20       ref IntPtr 
4570: 70 56 74 61 62 2c 0d 0a 20 20 20 20 20 20 20 20  pVtab,..        
4580: 20 20 20 20 72 65 66 20 49 6e 74 50 74 72 20 70      ref IntPtr p
4590: 45 72 72 6f 72 0d 0a 20 20 20 20 20 20 20 20 20  Error..         
45a0: 20 20 20 29 3b 0d 0a 0d 0a 20 20 20 20 20 20 20     );....       
45b0: 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f   ///////////////
45c0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
45d0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
45e0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
45f0: 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20  ////////....    
4600: 20 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79      /// <summary
4610: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
4620: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
4630: 2f 2f 20 53 51 4c 69 74 65 20 75 73 65 73 20 74  // SQLite uses t
4640: 68 65 20 78 42 65 73 74 49 6e 64 65 78 20 6d 65  he xBestIndex me
4650: 74 68 6f 64 20 6f 66 20 61 20 76 69 72 74 75 61  thod of a virtua
4660: 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20 74  l table module t
4670: 6f 20 64 65 74 65 72 6d 69 6e 65 0d 0a 20 20 20  o determine..   
4680: 20 20 20 20 20 2f 2f 2f 20 74 68 65 20 62 65 73       /// the bes
4690: 74 20 77 61 79 20 74 6f 20 61 63 63 65 73 73 20  t way to access 
46a0: 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
46b0: 65 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  e. ..        ///
46c0: 20 54 68 65 20 78 42 65 73 74 49 6e 64 65 78 20   The xBestIndex 
46d0: 6d 65 74 68 6f 64 20 68 61 73 20 61 20 70 72 6f  method has a pro
46e0: 74 6f 74 79 70 65 20 6c 69 6b 65 20 74 68 69 73  totype like this
46f0: 3a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  :..        /// <
4700: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
4710: 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e  /// <para><code>
4720: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e  ..        /// in
4730: 74 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28  t (*xBestIndex)(
4740: 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
4750: 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64  Tab, sqlite3_ind
4760: 65 78 5f 69 6e 66 6f 2a 29 3b 0d 0a 20 20 20 20  ex_info*);..    
4770: 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c      /// </code><
4780: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
4790: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20  /// <para>..    
47a0: 20 20 20 20 2f 2f 2f 20 54 68 65 20 53 51 4c 69      /// The SQLi
47b0: 74 65 20 63 6f 72 65 20 63 6f 6d 6d 75 6e 69 63  te core communic
47c0: 61 74 65 73 20 77 69 74 68 20 74 68 65 20 78 42  ates with the xB
47d0: 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64 20  estIndex method 
47e0: 62 79 20 66 69 6c 6c 69 6e 67 20 0d 0a 20 20 20  by filling ..   
47f0: 20 20 20 20 20 2f 2f 2f 20 69 6e 20 63 65 72 74       /// in cert
4800: 61 69 6e 20 66 69 65 6c 64 73 20 6f 66 20 74 68  ain fields of th
4810: 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  e sqlite3_index_
4820: 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20 61  info structure a
4830: 6e 64 20 70 61 73 73 69 6e 67 20 61 20 0d 0a 20  nd passing a .. 
4840: 20 20 20 20 20 20 20 2f 2f 2f 20 70 6f 69 6e 74         /// point
4850: 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 75 63  er to that struc
4860: 74 75 72 65 20 69 6e 74 6f 20 78 42 65 73 74 49  ture into xBestI
4870: 6e 64 65 78 20 61 73 20 74 68 65 20 73 65 63 6f  ndex as the seco
4880: 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 0d 0a  nd parameter. ..
4890: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20          /// The 
48a0: 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f  xBestIndex metho
48b0: 64 20 66 69 6c 6c 73 20 6f 75 74 20 6f 74 68 65  d fills out othe
48c0: 72 20 66 69 65 6c 64 73 20 6f 66 20 74 68 69 73  r fields of this
48d0: 20 73 74 72 75 63 74 75 72 65 20 77 68 69 63 68   structure which
48e0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 66 6f  ..        /// fo
48f0: 72 6d 73 20 74 68 65 20 72 65 70 6c 79 2e 20 54  rms the reply. T
4900: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  he sqlite3_index
4910: 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20  _info structure 
4920: 6c 6f 6f 6b 73 20 6c 69 6b 65 20 74 68 69 73 3a  looks like this:
4930: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
4940: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
4950: 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d  // <para><code>.
4960: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 74 72  .        /// str
4970: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
4980: 78 5f 69 6e 66 6f 20 7b 0d 0a 20 20 20 20 20 20  x_info {..      
4990: 20 20 2f 2f 2f 20 20 20 2f 2a 20 49 6e 70 75 74    ///   /* Input
49a0: 73 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20 2f 2f  s */..        //
49b0: 2f 20 20 20 63 6f 6e 73 74 20 69 6e 74 20 6e 43  /   const int nC
49c0: 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 2f  onstraint;     /
49d0: 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65 6e 74 72  * Number of entr
49e0: 69 65 73 20 69 6e 20 61 43 6f 6e 73 74 72 61 69  ies in aConstrai
49f0: 6e 74 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20 2f  nt */..        /
4a00: 2f 2f 20 20 20 63 6f 6e 73 74 20 73 74 72 75 63  //   const struc
4a10: 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
4a20: 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0d 0a 20 20  constraint {..  
4a30: 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 20 69        ///      i
4a40: 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20  nt iColumn;     
4a50: 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75           /* Colu
4a60: 6d 6e 20 63 6f 6e 73 74 72 61 69 6e 65 64 2e 20  mn constrained. 
4a70: 20 2d 31 20 66 6f 72 20 52 4f 57 49 44 20 2a 2f   -1 for ROWID */
4a80: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20  ..        ///   
4a90: 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72     unsigned char
4aa0: 20 6f 70 3b 20 20 20 20 20 20 20 20 20 2f 2a 20   op;         /* 
4ab0: 43 6f 6e 73 74 72 61 69 6e 74 20 6f 70 65 72 61  Constraint opera
4ac0: 74 6f 72 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20  tor */..        
4ad0: 2f 2f 2f 20 20 20 20 20 20 75 6e 73 69 67 6e 65  ///      unsigne
4ae0: 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20  d char usable;  
4af0: 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68     /* True if th
4b00: 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73  is constraint is
4b10: 20 75 73 61 62 6c 65 20 2a 2f 0d 0a 20 20 20 20   usable */..    
4b20: 20 20 20 20 2f 2f 2f 20 20 20 20 20 20 69 6e 74      ///      int
4b30: 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20 20   iTermOffset;   
4b40: 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69         /* Used i
4b50: 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65 73  nternally - xBes
4b60: 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69 67  tIndex should ig
4b70: 6e 6f 72 65 20 2a 2f 0d 0a 20 20 20 20 20 20 20  nore */..       
4b80: 20 2f 2f 2f 20 20 20 7d 20 2a 63 6f 6e 73 74 20   ///   } *const 
4b90: 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20  aConstraint;    
4ba0: 20 20 2f 2a 20 54 61 62 6c 65 20 6f 66 20 57 48    /* Table of WH
4bb0: 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74  ERE clause const
4bc0: 72 61 69 6e 74 73 20 2a 2f 0d 0a 20 20 20 20 20  raints */..     
4bd0: 20 20 20 2f 2f 2f 20 20 20 63 6f 6e 73 74 20 69     ///   const i
4be0: 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20 20  nt nOrderBy;    
4bf0: 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
4c00: 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20 4f 52   terms in the OR
4c10: 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f  DER BY clause */
4c20: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20  ..        ///   
4c30: 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c  const struct sql
4c40: 69 74 65 33 5f 69 6e 64 65 78 5f 6f 72 64 65 72  ite3_index_order
4c50: 62 79 20 7b 0d 0a 20 20 20 20 20 20 20 20 2f 2f  by {..        //
4c60: 2f 20 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75  /      int iColu
4c70: 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  mn;             
4c80: 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65   /* Column numbe
4c90: 72 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20 2f 2f  r */..        //
4ca0: 2f 20 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20  /      unsigned 
4cb0: 63 68 61 72 20 64 65 73 63 3b 20 20 20 20 20 20  char desc;      
4cc0: 20 2f 2a 20 54 72 75 65 20 66 6f 72 20 44 45 53   /* True for DES
4cd0: 43 2e 20 20 46 61 6c 73 65 20 66 6f 72 20 41 53  C.  False for AS
4ce0: 43 2e 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20 2f  C. */..        /
4cf0: 2f 2f 20 20 20 7d 20 2a 63 6f 6e 73 74 20 61 4f  //   } *const aO
4d00: 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20  rderBy;         
4d10: 2f 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59 20  /* The ORDER BY 
4d20: 63 6c 61 75 73 65 20 2a 2f 0d 0a 20 20 20 20 20  clause */..     
4d30: 20 20 20 2f 2f 2f 20 20 20 2f 2a 20 4f 75 74 70     ///   /* Outp
4d40: 75 74 73 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20  uts */..        
4d50: 2f 2f 2f 20 20 20 73 74 72 75 63 74 20 73 71 6c  ///   struct sql
4d60: 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74  ite3_index_const
4d70: 72 61 69 6e 74 5f 75 73 61 67 65 20 7b 0d 0a 20  raint_usage {.. 
4d80: 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 69         ///     i
4d90: 6e 74 20 61 72 67 76 49 6e 64 65 78 3b 20 20 20  nt argvIndex;   
4da0: 20 20 20 20 20 20 20 20 2f 2a 20 69 66 20 3e 30          /* if >0
4db0: 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20  , constraint is 
4dc0: 70 61 72 74 20 6f 66 20 61 72 67 76 20 74 6f 20  part of argv to 
4dd0: 78 46 69 6c 74 65 72 20 2a 2f 0d 0a 20 20 20 20  xFilter */..    
4de0: 20 20 20 20 2f 2f 2f 20 20 20 20 20 75 6e 73 69      ///     unsi
4df0: 67 6e 65 64 20 63 68 61 72 20 6f 6d 69 74 3b 20  gned char omit; 
4e00: 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63       /* Do not c
4e10: 6f 64 65 20 61 20 74 65 73 74 20 66 6f 72 20 74  ode a test for t
4e20: 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a  his constraint *
4e30: 2f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20  /..        ///  
4e40: 20 7d 20 2a 63 6f 6e 73 74 20 61 43 6f 6e 73 74   } *const aConst
4e50: 72 61 69 6e 74 55 73 61 67 65 3b 0d 0a 20 20 20  raintUsage;..   
4e60: 20 20 20 20 20 2f 2f 2f 20 20 20 69 6e 74 20 69       ///   int i
4e70: 64 78 4e 75 6d 3b 20 20 20 20 20 20 20 20 20 20  dxNum;          
4e80: 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
4e90: 75 73 65 64 20 74 6f 20 69 64 65 6e 74 69 66 79  used to identify
4ea0: 20 74 68 65 20 69 6e 64 65 78 20 2a 2f 0d 0a 20   the index */.. 
4eb0: 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 63 68 61         ///   cha
4ec0: 72 20 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20  r *idxStr;      
4ed0: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e          /* Strin
4ee0: 67 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61  g, possibly obta
4ef0: 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
4f00: 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0d 0a 20 20 20  3_malloc */..   
4f10: 20 20 20 20 20 2f 2f 2f 20 20 20 69 6e 74 20 6e       ///   int n
4f20: 65 65 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b  eedToFreeIdxStr;
4f30: 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64        /* Free id
4f40: 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74  xStr using sqlit
4f50: 65 33 5f 66 72 65 65 28 29 20 69 66 20 74 72 75  e3_free() if tru
4f60: 65 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20 2f 2f  e */..        //
4f70: 2f 20 20 20 69 6e 74 20 6f 72 64 65 72 42 79 43  /   int orderByC
4f80: 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20 20 2f  onsumed;       /
4f90: 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70 75 74  * True if output
4fa0: 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72 64 65   is already orde
4fb0: 72 65 64 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20  red */..        
4fc0: 2f 2f 2f 20 20 20 64 6f 75 62 6c 65 20 65 73 74  ///   double est
4fd0: 69 6d 61 74 65 64 43 6f 73 74 3b 20 20 20 20 20  imatedCost;     
4fe0: 20 2f 2a 20 45 73 74 69 6d 61 74 65 64 20 63 6f   /* Estimated co
4ff0: 73 74 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73  st of using this
5000: 20 69 6e 64 65 78 20 2a 2f 0d 0a 20 20 20 20 20   index */..     
5010: 20 20 20 2f 2f 2f 20 20 20 3c 21 5b 43 44 41 54     ///   <![CDAT
5020: 41 5b 3c 62 3e 5d 5d 3e 2f 2a 20 46 69 65 6c 64  A[<b>]]>/* Field
5030: 73 20 62 65 6c 6f 77 20 61 72 65 20 6f 6e 6c 79  s below are only
5040: 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 53 51   available in SQ
5050: 4c 69 74 65 20 33 2e 38 2e 32 20 61 6e 64 20 6c  Lite 3.8.2 and l
5060: 61 74 65 72 20 2a 2f 3c 21 5b 43 44 41 54 41 5b  ater */<![CDATA[
5070: 3c 2f 62 3e 5d 5d 3e 0d 0a 20 20 20 20 20 20 20  </b>]]>..       
5080: 20 2f 2f 2f 20 20 20 73 71 6c 69 74 65 33 5f 69   ///   sqlite3_i
5090: 6e 74 36 34 20 65 73 74 69 6d 61 74 65 64 52 6f  nt64 estimatedRo
50a0: 77 73 3b 20 20 20 20 2f 2a 20 45 73 74 69 6d 61  ws;    /* Estima
50b0: 74 65 64 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  ted number of ro
50c0: 77 73 20 72 65 74 75 72 6e 65 64 20 2a 2f 0d 0a  ws returned */..
50d0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 3c 21          ///   <!
50e0: 5b 43 44 41 54 41 5b 3c 62 3e 5d 5d 3e 2f 2a 20  [CDATA[<b>]]>/* 
50f0: 46 69 65 6c 64 73 20 62 65 6c 6f 77 20 61 72 65  Fields below are
5100: 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
5110: 69 6e 20 53 51 4c 69 74 65 20 33 2e 39 2e 30 20  in SQLite 3.9.0 
5120: 61 6e 64 20 6c 61 74 65 72 20 2a 2f 3c 21 5b 43  and later */<![C
5130: 44 41 54 41 5b 3c 2f 62 3e 5d 5d 3e 0d 0a 20 20  DATA[</b>]]>..  
5140: 20 20 20 20 20 20 2f 2f 2f 20 20 20 69 6e 74 20        ///   int 
5150: 69 64 78 46 6c 61 67 73 3b 20 20 20 20 20 20 20  idxFlags;       
5160: 20 20 20 20 20 20 20 2f 2a 20 4d 61 73 6b 20 6f         /* Mask o
5170: 66 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 53  f SQLITE_INDEX_S
5180: 43 41 4e 5f 2a 20 66 6c 61 67 73 20 2a 2f 0d 0a  CAN_* flags */..
5190: 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 3c 21          ///   <!
51a0: 5b 43 44 41 54 41 5b 3c 62 3e 5d 5d 3e 2f 2a 20  [CDATA[<b>]]>/* 
51b0: 46 69 65 6c 64 73 20 62 65 6c 6f 77 20 61 72 65  Fields below are
51c0: 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
51d0: 69 6e 20 53 51 4c 69 74 65 20 33 2e 31 30 2e 30  in SQLite 3.10.0
51e0: 20 61 6e 64 20 6c 61 74 65 72 20 2a 2f 3c 21 5b   and later */<![
51f0: 43 44 41 54 41 5b 3c 2f 62 3e 5d 5d 3e 0d 0a 20  CDATA[</b>]]>.. 
5200: 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 73 71 6c         ///   sql
5210: 69 74 65 33 5f 75 69 6e 74 36 34 20 63 6f 6c 55  ite3_uint64 colU
5220: 73 65 64 3b 20 20 20 20 2f 2a 20 49 6e 70 75 74  sed;    /* Input
5230: 3a 20 4d 61 73 6b 20 6f 66 20 63 6f 6c 75 6d 6e  : Mask of column
5240: 73 20 75 73 65 64 20 62 79 20 73 74 61 74 65 6d  s used by statem
5250: 65 6e 74 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20  ent */..        
5260: 2f 2f 2f 20 7d 3b 0d 0a 20 20 20 20 20 20 20 20  /// };..        
5270: 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72  /// </code></par
5280: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
5290: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
52a0: 2f 2f 2f 20 4e 6f 74 65 20 74 68 65 20 77 61 72  /// Note the war
52b0: 6e 69 6e 67 73 20 6f 6e 20 74 68 65 20 22 65 73  nings on the "es
52c0: 74 69 6d 61 74 65 64 52 6f 77 73 22 2c 20 22 69  timatedRows", "i
52d0: 64 78 46 6c 61 67 73 22 2c 20 61 6e 64 20 63 6f  dxFlags", and co
52e0: 6c 55 73 65 64 20 66 69 65 6c 64 73 2e 0d 0a 20  lUsed fields... 
52f0: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 73 65         /// These
5300: 20 66 69 65 6c 64 73 20 77 65 72 65 20 61 64 64   fields were add
5310: 65 64 20 77 69 74 68 20 53 51 4c 69 74 65 20 76  ed with SQLite v
5320: 65 72 73 69 6f 6e 73 20 33 2e 38 2e 32 2c 20 33  ersions 3.8.2, 3
5330: 2e 39 2e 30 2c 20 61 6e 64 20 33 2e 31 30 2e 30  .9.0, and 3.10.0
5340: 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  , respectively. 
5350: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 6e  ..        /// An
5360: 79 20 65 78 74 65 6e 73 69 6f 6e 20 74 68 61 74  y extension that
5370: 20 72 65 61 64 73 20 6f 72 20 77 72 69 74 65 73   reads or writes
5380: 20 74 68 65 73 65 20 66 69 65 6c 64 73 20 6d 75   these fields mu
5390: 73 74 20 66 69 72 73 74 20 63 68 65 63 6b 20 74  st first check t
53a0: 68 61 74 20 74 68 65 20 0d 0a 20 20 20 20 20 20  hat the ..      
53b0: 20 20 2f 2f 2f 20 76 65 72 73 69 6f 6e 20 6f 66    /// version of
53c0: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
53d0: 61 72 79 20 69 6e 20 75 73 65 20 69 73 20 67 72  ary in use is gr
53e0: 65 61 74 65 72 20 74 68 61 6e 20 6f 72 20 65 71  eater than or eq
53f0: 75 61 6c 20 74 6f 20 61 70 70 72 6f 70 72 69 61  ual to appropria
5400: 74 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  te..        /// 
5410: 76 65 72 73 69 6f 6e 20 2d 20 70 65 72 68 61 70  version - perhap
5420: 73 20 63 6f 6d 70 61 72 69 6e 67 20 74 68 65 20  s comparing the 
5430: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 66  value returned f
5440: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  rom sqlite3_libv
5450: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 0d  ersion_number().
5460: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 61 67 61  .        /// aga
5470: 69 6e 73 74 20 63 6f 6e 73 74 61 6e 74 73 20 33  inst constants 3
5480: 30 30 38 30 30 32 2c 20 33 30 30 39 30 30 30 2c  008002, 3009000,
5490: 20 61 6e 64 2f 6f 72 20 33 30 31 30 30 30 30 2e   and/or 3010000.
54a0: 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 61   The result of a
54b0: 74 74 65 6d 70 74 69 6e 67 20 0d 0a 20 20 20 20  ttempting ..    
54c0: 20 20 20 20 2f 2f 2f 20 74 6f 20 61 63 63 65 73      /// to acces
54d0: 73 20 74 68 65 73 65 20 66 69 65 6c 64 73 20 69  s these fields i
54e0: 6e 20 61 6e 20 73 71 6c 69 74 65 33 5f 69 6e 64  n an sqlite3_ind
54f0: 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72  ex_info structur
5500: 65 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20  e created by an 
5510: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6f 6c  ..        /// ol
5520: 64 65 72 20 76 65 72 73 69 6f 6e 20 6f 66 20 53  der version of S
5530: 51 4c 69 74 65 20 61 72 65 20 75 6e 64 65 66 69  QLite are undefi
5540: 6e 65 64 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ned...        //
5550: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  / </para>..     
5560: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20     /// <para>.. 
5570: 20 20 20 20 20 20 20 2f 2f 2f 20 49 6e 20 61 64         /// In ad
5580: 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 20 61 72  dition, there ar
5590: 65 20 73 6f 6d 65 20 64 65 66 69 6e 65 64 20 63  e some defined c
55a0: 6f 6e 73 74 61 6e 74 73 3a 0d 0a 20 20 20 20 20  onstants:..     
55b0: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a     /// </para>..
55c0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
55d0: 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20  a><code>..      
55e0: 20 20 2f 2f 2f 20 23 64 65 66 69 6e 65 20 53 51    /// #define SQ
55f0: 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
5600: 52 41 49 4e 54 5f 45 51 20 20 20 20 20 20 32 0d  RAINT_EQ      2.
5610: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 23 64 65  .        /// #de
5620: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
5630: 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20  X_CONSTRAINT_GT 
5640: 20 20 20 20 20 34 0d 0a 20 20 20 20 20 20 20 20       4..        
5650: 2f 2f 2f 20 23 64 65 66 69 6e 65 20 53 51 4c 49  /// #define SQLI
5660: 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
5670: 49 4e 54 5f 4c 45 20 20 20 20 20 20 38 0d 0a 20  INT_LE      8.. 
5680: 20 20 20 20 20 20 20 2f 2f 2f 20 23 64 65 66 69         /// #defi
5690: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
56a0: 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20  CONSTRAINT_LT   
56b0: 20 20 31 36 0d 0a 20 20 20 20 20 20 20 20 2f 2f    16..        //
56c0: 2f 20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  / #define SQLITE
56d0: 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
56e0: 54 5f 47 45 20 20 20 20 20 33 32 0d 0a 20 20 20  T_GE     32..   
56f0: 20 20 20 20 20 2f 2f 2f 20 23 64 65 66 69 6e 65       /// #define
5700: 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f   SQLITE_INDEX_CO
5710: 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43 48 20 20  NSTRAINT_MATCH  
5720: 36 34 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  64..        /// 
5730: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5740: 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
5750: 4c 49 4b 45 20 20 20 36 35 20 20 20 20 20 2f 2a  LIKE   65     /*
5760: 20 33 2e 31 30 2e 30 20 61 6e 64 20 6c 61 74 65   3.10.0 and late
5770: 72 20 6f 6e 6c 79 20 2a 2f 0d 0a 20 20 20 20 20  r only */..     
5780: 20 20 20 2f 2f 2f 20 23 64 65 66 69 6e 65 20 53     /// #define S
5790: 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
57a0: 54 52 41 49 4e 54 5f 47 4c 4f 42 20 20 20 36 36  TRAINT_GLOB   66
57b0: 20 20 20 20 20 2f 2a 20 33 2e 31 30 2e 30 20 61       /* 3.10.0 a
57c0: 6e 64 20 6c 61 74 65 72 20 6f 6e 6c 79 20 2a 2f  nd later only */
57d0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 23 64  ..        /// #d
57e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
57f0: 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 45  EX_CONSTRAINT_RE
5800: 47 45 58 50 20 36 37 20 20 20 20 20 2f 2a 20 33  GEXP 67     /* 3
5810: 2e 31 30 2e 30 20 61 6e 64 20 6c 61 74 65 72 20  .10.0 and later 
5820: 6f 6e 6c 79 20 2a 2f 0d 0a 20 20 20 20 20 20 20  only */..       
5830: 20 2f 2f 2f 20 23 64 65 66 69 6e 65 20 53 51 4c   /// #define SQL
5840: 49 54 45 5f 49 4e 44 45 58 5f 53 43 41 4e 5f 55  ITE_INDEX_SCAN_U
5850: 4e 49 51 55 45 20 20 20 20 20 20 20 20 31 20 20  NIQUE        1  
5860: 20 20 20 2f 2a 20 53 63 61 6e 20 76 69 73 69 74     /* Scan visit
5870: 73 20 61 74 20 6d 6f 73 74 20 31 20 72 6f 77 20  s at most 1 row 
5880: 2a 2f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  */..        /// 
5890: 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a  </code></para>..
58a0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
58b0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
58c0: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
58d0: 63 61 6c 6c 73 20 74 68 65 20 78 42 65 73 74 49  calls the xBestI
58e0: 6e 64 65 78 20 6d 65 74 68 6f 64 20 77 68 65 6e  ndex method when
58f0: 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 69 6e 67   it is compiling
5900: 20 61 20 71 75 65 72 79 0d 0a 20 20 20 20 20 20   a query..      
5910: 20 20 2f 2f 2f 20 74 68 61 74 20 69 6e 76 6f 6c    /// that invol
5920: 76 65 73 20 61 20 76 69 72 74 75 61 6c 20 74 61  ves a virtual ta
5930: 62 6c 65 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  ble. In other wo
5940: 72 64 73 2c 20 53 51 4c 69 74 65 20 63 61 6c 6c  rds, SQLite call
5950: 73 20 74 68 69 73 20 6d 65 74 68 6f 64 20 0d 0a  s this method ..
5960: 20 20 20 20 20 20 20 20 2f 2f 2f 20 77 68 65 6e          /// when
5970: 20 69 74 20 69 73 20 72 75 6e 6e 69 6e 67 20 73   it is running s
5980: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
5990: 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65   or the equivale
59a0: 6e 74 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  nt. ..        //
59b0: 2f 20 42 79 20 63 61 6c 6c 69 6e 67 20 74 68 69  / By calling thi
59c0: 73 20 6d 65 74 68 6f 64 2c 20 74 68 65 20 0d 0a  s method, the ..
59d0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 53 51 4c 69          /// SQLi
59e0: 74 65 20 63 6f 72 65 20 69 73 20 73 61 79 69 6e  te core is sayin
59f0: 67 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c  g to the virtual
5a00: 20 74 61 62 6c 65 20 74 68 61 74 20 69 74 20 6e   table that it n
5a10: 65 65 64 73 20 74 6f 20 61 63 63 65 73 73 20 0d  eeds to access .
5a20: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 6f 6d  .        /// som
5a30: 65 20 73 75 62 73 65 74 20 6f 66 20 74 68 65 20  e subset of the 
5a40: 72 6f 77 73 20 69 6e 20 74 68 65 20 76 69 72 74  rows in the virt
5a50: 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 69 74  ual table and it
5a60: 20 77 61 6e 74 73 20 74 6f 20 6b 6e 6f 77 20 74   wants to know t
5a70: 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  he..        /// 
5a80: 6d 6f 73 74 20 65 66 66 69 63 69 65 6e 74 20 77  most efficient w
5a90: 61 79 20 74 6f 20 64 6f 20 74 68 61 74 20 61 63  ay to do that ac
5aa0: 63 65 73 73 2e 20 54 68 65 20 78 42 65 73 74 49  cess. The xBestI
5ab0: 6e 64 65 78 20 6d 65 74 68 6f 64 20 72 65 70 6c  ndex method repl
5ac0: 69 65 73 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ies ..        //
5ad0: 2f 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69  / with informati
5ae0: 6f 6e 20 74 68 61 74 20 74 68 65 20 53 51 4c 69  on that the SQLi
5af0: 74 65 20 63 6f 72 65 20 63 61 6e 20 74 68 65 6e  te core can then
5b00: 20 75 73 65 20 74 6f 20 63 6f 6e 64 75 63 74 20   use to conduct 
5b10: 61 6e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  an ..        ///
5b20: 20 65 66 66 69 63 69 65 6e 74 20 73 65 61 72 63   efficient searc
5b30: 68 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c  h of the virtual
5b40: 20 74 61 62 6c 65 2e 0d 0a 20 20 20 20 20 20 20   table...       
5b50: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
5b60: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
5b70: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 57 68  ..        /// Wh
5b80: 69 6c 65 20 63 6f 6d 70 69 6c 69 6e 67 20 61 20  ile compiling a 
5b90: 73 69 6e 67 6c 65 20 53 51 4c 20 71 75 65 72 79  single SQL query
5ba0: 2c 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  , the SQLite cor
5bb0: 65 20 6d 69 67 68 74 20 63 61 6c 6c 20 0d 0a 20  e might call .. 
5bc0: 20 20 20 20 20 20 20 2f 2f 2f 20 78 42 65 73 74         /// xBest
5bd0: 49 6e 64 65 78 20 6d 75 6c 74 69 70 6c 65 20 74  Index multiple t
5be0: 69 6d 65 73 20 77 69 74 68 20 64 69 66 66 65 72  imes with differ
5bf0: 65 6e 74 20 73 65 74 74 69 6e 67 73 20 69 6e 20  ent settings in 
5c00: 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
5c10: 66 6f 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  fo...        ///
5c20: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
5c30: 20 77 69 6c 6c 20 74 68 65 6e 20 73 65 6c 65 63   will then selec
5c40: 74 20 74 68 65 20 63 6f 6d 62 69 6e 61 74 69 6f  t the combinatio
5c50: 6e 20 74 68 61 74 20 61 70 70 65 61 72 73 20 74  n that appears t
5c60: 6f 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  o ..        /// 
5c70: 67 69 76 65 20 74 68 65 20 62 65 73 74 20 70 65  give the best pe
5c80: 72 66 6f 72 6d 61 6e 63 65 2e 0d 0a 20 20 20 20  rformance...    
5c90: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
5ca0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
5cb0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
5cc0: 20 42 65 66 6f 72 65 20 63 61 6c 6c 69 6e 67 20   Before calling 
5cd0: 74 68 69 73 20 6d 65 74 68 6f 64 2c 20 74 68 65  this method, the
5ce0: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 69 6e 69   SQLite core ini
5cf0: 74 69 61 6c 69 7a 65 73 20 61 6e 20 69 6e 73 74  tializes an inst
5d00: 61 6e 63 65 20 0d 0a 20 20 20 20 20 20 20 20 2f  ance ..        /
5d10: 2f 2f 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  // of the sqlite
5d20: 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72  3_index_info str
5d30: 75 63 74 75 72 65 20 77 69 74 68 20 69 6e 66 6f  ucture with info
5d40: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68  rmation about th
5d50: 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 71  e..        /// q
5d60: 75 65 72 79 20 74 68 61 74 20 69 74 20 69 73 20  uery that it is 
5d70: 63 75 72 72 65 6e 74 6c 79 20 74 72 79 69 6e 67  currently trying
5d80: 20 74 6f 20 70 72 6f 63 65 73 73 2e 20 54 68 69   to process. Thi
5d90: 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 0d 0a  s information ..
5da0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 64 65 72 69          /// deri
5db0: 76 65 73 20 6d 61 69 6e 6c 79 20 66 72 6f 6d 20  ves mainly from 
5dc0: 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65  the WHERE clause
5dd0: 20 61 6e 64 20 4f 52 44 45 52 20 42 59 20 6f 72   and ORDER BY or
5de0: 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65   GROUP BY clause
5df0: 73 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  s ..        /// 
5e00: 6f 66 20 74 68 65 20 71 75 65 72 79 2c 20 62 75  of the query, bu
5e10: 74 20 61 6c 73 6f 20 66 72 6f 6d 20 61 6e 79 20  t also from any 
5e20: 4f 4e 20 6f 72 20 55 53 49 4e 47 20 63 6c 61 75  ON or USING clau
5e30: 73 65 73 20 69 66 20 74 68 65 20 71 75 65 72 79  ses if the query
5e40: 20 69 73 20 61 20 0d 0a 20 20 20 20 20 20 20 20   is a ..        
5e50: 2f 2f 2f 20 6a 6f 69 6e 2e 20 54 68 65 20 69 6e  /// join. The in
5e60: 66 6f 72 6d 61 74 69 6f 6e 20 74 68 61 74 20 74  formation that t
5e70: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 70  he SQLite core p
5e80: 72 6f 76 69 64 65 73 20 74 6f 20 74 68 65 20 78  rovides to the x
5e90: 42 65 73 74 49 6e 64 65 78 20 0d 0a 20 20 20 20  BestIndex ..    
5ea0: 20 20 20 20 2f 2f 2f 20 6d 65 74 68 6f 64 20 69      /// method i
5eb0: 73 20 68 65 6c 64 20 69 6e 20 74 68 65 20 70 61  s held in the pa
5ec0: 72 74 20 6f 66 20 74 68 65 20 73 74 72 75 63 74  rt of the struct
5ed0: 75 72 65 20 74 68 61 74 20 69 73 20 6d 61 72 6b  ure that is mark
5ee0: 65 64 20 61 73 20 22 49 6e 70 75 74 73 22 2e 20  ed as "Inputs". 
5ef0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
5f00: 65 20 22 4f 75 74 70 75 74 73 22 20 73 65 63 74  e "Outputs" sect
5f10: 69 6f 6e 20 69 73 20 69 6e 69 74 69 61 6c 69 7a  ion is initializ
5f20: 65 64 20 74 6f 20 7a 65 72 6f 2e 0d 0a 20 20 20  ed to zero...   
5f30: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e       /// </para>
5f40: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
5f50: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
5f60: 2f 20 54 68 65 20 69 6e 66 6f 72 6d 61 74 69 6f  / The informatio
5f70: 6e 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  n in the sqlite3
5f80: 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75  _index_info stru
5f90: 63 74 75 72 65 20 69 73 20 65 70 68 65 6d 65 72  cture is ephemer
5fa0: 61 6c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  al..        /// 
5fb0: 61 6e 64 20 6d 61 79 20 62 65 20 6f 76 65 72 77  and may be overw
5fc0: 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f  ritten or deallo
5fd0: 63 61 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  cated as soon as
5fe0: 20 74 68 65 20 78 42 65 73 74 49 6e 64 65 78 20   the xBestIndex 
5ff0: 6d 65 74 68 6f 64 0d 0a 20 20 20 20 20 20 20 20  method..        
6000: 2f 2f 2f 20 72 65 74 75 72 6e 73 2e 20 20 49 66  /// returns.  If
6010: 20 74 68 65 20 78 42 65 73 74 49 6e 64 65 78 20   the xBestIndex 
6020: 6d 65 74 68 6f 64 20 6e 65 65 64 73 20 74 6f 20  method needs to 
6030: 72 65 6d 65 6d 62 65 72 20 61 6e 79 20 70 61 72  remember any par
6040: 74 20 6f 66 20 74 68 65 0d 0a 20 20 20 20 20 20  t of the..      
6050: 20 20 2f 2f 2f 20 73 71 6c 69 74 65 33 5f 69 6e    /// sqlite3_in
6060: 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75  dex_info structu
6070: 72 65 2c 20 69 74 20 73 68 6f 75 6c 64 20 6d 61  re, it should ma
6080: 6b 65 20 61 20 63 6f 70 79 2e 20 20 43 61 72 65  ke a copy.  Care
6090: 20 6d 75 73 74 20 62 65 0d 0a 20 20 20 20 20 20   must be..      
60a0: 20 20 2f 2f 2f 20 74 61 6b 65 20 74 6f 20 73 74    /// take to st
60b0: 6f 72 65 20 74 68 65 20 63 6f 70 79 20 69 6e 20  ore the copy in 
60c0: 61 20 70 6c 61 63 65 20 77 68 65 72 65 20 69 74  a place where it
60d0: 20 77 69 6c 6c 20 62 65 20 64 65 61 6c 6c 6f 63   will be dealloc
60e0: 61 74 65 64 2c 20 73 75 63 68 0d 0a 20 20 20 20  ated, such..    
60f0: 20 20 20 20 2f 2f 2f 20 61 73 20 69 6e 20 74 68      /// as in th
6100: 65 20 69 64 78 53 74 72 20 66 69 65 6c 64 20 77  e idxStr field w
6110: 69 74 68 20 6e 65 65 64 54 6f 46 72 65 65 49 64  ith needToFreeId
6120: 78 53 74 72 20 73 65 74 20 74 6f 20 31 2e 0d 0a  xStr set to 1...
6130: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
6140: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
6150: 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20   <para>..       
6160: 20 2f 2f 2f 20 4e 6f 74 65 20 74 68 61 74 20 78   /// Note that x
6170: 42 65 73 74 49 6e 64 65 78 20 77 69 6c 6c 20 61  BestIndex will a
6180: 6c 77 61 79 73 20 62 65 20 63 61 6c 6c 65 64 20  lways be called 
6190: 62 65 66 6f 72 65 20 78 46 69 6c 74 65 72 2c 20  before xFilter, 
61a0: 73 69 6e 63 65 0d 0a 20 20 20 20 20 20 20 20 2f  since..        /
61b0: 2f 2f 20 74 68 65 20 69 64 78 4e 75 6d 20 61 6e  // the idxNum an
61c0: 64 20 69 64 78 53 74 72 20 6f 75 74 70 75 74 73  d idxStr outputs
61d0: 20 66 72 6f 6d 20 78 42 65 73 74 49 6e 64 65 78   from xBestIndex
61e0: 20 61 72 65 20 72 65 71 75 69 72 65 64 20 69 6e   are required in
61f0: 70 75 74 73 20 74 6f 0d 0a 20 20 20 20 20 20 20  puts to..       
6200: 20 2f 2f 2f 20 78 46 69 6c 74 65 72 2e 20 20 48   /// xFilter.  H
6210: 6f 77 65 76 65 72 2c 20 74 68 65 72 65 20 69 73  owever, there is
6220: 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68   no guarantee th
6230: 61 74 20 78 46 69 6c 74 65 72 20 77 69 6c 6c 20  at xFilter will 
6240: 62 65 20 63 61 6c 6c 65 64 0d 0a 20 20 20 20 20  be called..     
6250: 20 20 20 2f 2f 2f 20 66 6f 6c 6c 6f 77 69 6e 67     /// following
6260: 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 78 42   a successful xB
6270: 65 73 74 49 6e 64 65 78 2e 20 20 0d 0a 20 20 20  estIndex.  ..   
6280: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e       /// </para>
6290: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
62a0: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
62b0: 2f 20 54 68 65 20 78 42 65 73 74 49 6e 64 65 78  / The xBestIndex
62c0: 20 6d 65 74 68 6f 64 20 69 73 20 72 65 71 75 69   method is requi
62d0: 72 65 64 20 66 6f 72 20 65 76 65 72 79 20 76 69  red for every vi
62e0: 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c  rtual table impl
62f0: 65 6d 65 6e 74 61 74 69 6f 6e 2e 0d 0a 20 20 20  ementation...   
6300: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e       /// </para>
6310: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
6320: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
6330: 2f 20 54 68 65 20 6d 61 69 6e 20 74 68 69 6e 67  / The main thing
6340: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
6350: 20 63 6f 72 65 20 69 73 20 74 72 79 69 6e 67 20   core is trying 
6360: 74 6f 20 63 6f 6d 6d 75 6e 69 63 61 74 65 20 74  to communicate t
6370: 6f 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  o ..        /// 
6380: 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
6390: 65 20 69 73 20 74 68 65 20 63 6f 6e 73 74 72 61  e is the constra
63a0: 69 6e 74 73 20 74 68 61 74 20 61 72 65 20 61 76  ints that are av
63b0: 61 69 6c 61 62 6c 65 20 74 6f 20 6c 69 6d 69 74  ailable to limit
63c0: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74   ..        /// t
63d0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
63e0: 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 62  s that need to b
63f0: 65 20 73 65 61 72 63 68 65 64 2e 20 54 68 65 20  e searched. The 
6400: 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72  aConstraint[] ar
6410: 72 61 79 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ray ..        //
6420: 2f 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 65 20 65  / contains one e
6430: 6e 74 72 79 20 66 6f 72 20 65 61 63 68 20 63 6f  ntry for each co
6440: 6e 73 74 72 61 69 6e 74 2e 20 54 68 65 72 65 20  nstraint. There 
6450: 77 69 6c 6c 20 62 65 20 65 78 61 63 74 6c 79 20  will be exactly 
6460: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6e 43  ..        /// nC
6470: 6f 6e 73 74 72 61 69 6e 74 20 65 6e 74 72 69 65  onstraint entrie
6480: 73 20 69 6e 20 74 68 61 74 20 61 72 72 61 79 2e  s in that array.
6490: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
64a0: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
64b0: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20  // <para>..     
64c0: 20 20 20 2f 2f 2f 20 45 61 63 68 20 63 6f 6e 73     /// Each cons
64d0: 74 72 61 69 6e 74 20 77 69 6c 6c 20 63 6f 72 72  traint will corr
64e0: 65 73 70 6f 6e 64 20 74 6f 20 61 20 74 65 72 6d  espond to a term
64f0: 20 69 6e 20 74 68 65 20 57 48 45 52 45 20 63 6c   in the WHERE cl
6500: 61 75 73 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ause..        //
6510: 2f 20 6f 72 20 69 6e 20 61 20 55 53 49 4e 47 20  / or in a USING 
6520: 6f 72 20 4f 4e 20 63 6c 61 75 73 65 20 74 68 61  or ON clause tha
6530: 74 20 69 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  t is of the form
6540: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
6550: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
6560: 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d  // <para><code>.
6570: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20  .        ///    
6580: 20 20 63 6f 6c 75 6d 6e 20 20 4f 50 20 20 45 58    column  OP  EX
6590: 50 52 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  PR..        /// 
65a0: 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a  </code></para>..
65b0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
65c0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
65d0: 57 68 65 72 65 20 22 63 6f 6c 75 6d 6e 22 20 69  Where "column" i
65e0: 73 20 61 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68  s a column in th
65f0: 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2c  e virtual table,
6600: 20 4f 50 20 69 73 20 61 6e 20 6f 70 65 72 61 74   OP is an operat
6610: 6f 72 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  or ..        ///
6620: 20 6c 69 6b 65 20 22 3d 22 20 6f 72 20 22 26 6c   like "=" or "&l
6630: 74 3b 22 2c 20 61 6e 64 20 45 58 50 52 20 69 73  t;", and EXPR is
6640: 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 65 78   an arbitrary ex
6650: 70 72 65 73 73 69 6f 6e 2e 20 53 6f 2c 20 66 6f  pression. So, fo
6660: 72 20 65 78 61 6d 70 6c 65 2c 0d 0a 20 20 20 20  r example,..    
6670: 20 20 20 20 2f 2f 2f 20 69 66 20 74 68 65 20 57      /// if the W
6680: 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 74  HERE clause cont
6690: 61 69 6e 65 64 20 61 20 74 65 72 6d 20 6c 69 6b  ained a term lik
66a0: 65 20 74 68 69 73 3a 0d 0a 20 20 20 20 20 20 20  e this:..       
66b0: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
66c0: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
66d0: 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20 20  <code>..        
66e0: 2f 2f 2f 20 61 20 3d 20 35 0d 0a 20 20 20 20 20  /// a = 5..     
66f0: 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f     /// </code></
6700: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
6710: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20  // <para>..     
6720: 20 20 20 2f 2f 2f 20 54 68 65 6e 20 6f 6e 65 20     /// Then one 
6730: 6f 66 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  of the constrain
6740: 74 73 20 77 6f 75 6c 64 20 62 65 20 6f 6e 20 74  ts would be on t
6750: 68 65 20 22 61 22 20 63 6f 6c 75 6d 6e 20 77 69  he "a" column wi
6760: 74 68 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  th ..        ///
6770: 20 6f 70 65 72 61 74 6f 72 20 22 3d 22 20 61 6e   operator "=" an
6780: 64 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20  d an expression 
6790: 6f 66 20 22 35 22 2e 20 43 6f 6e 73 74 72 61 69  of "5". Constrai
67a0: 6e 74 73 20 6e 65 65 64 20 6e 6f 74 20 68 61 76  nts need not hav
67b0: 65 20 61 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  e a..        ///
67c0: 20 6c 69 74 65 72 61 6c 20 72 65 70 72 65 73 65   literal represe
67d0: 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 57  ntation of the W
67e0: 48 45 52 45 20 63 6c 61 75 73 65 2e 20 54 68 65  HERE clause. The
67f0: 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72   query optimizer
6800: 20 6d 69 67 68 74 0d 0a 20 20 20 20 20 20 20 20   might..        
6810: 2f 2f 2f 20 6d 61 6b 65 20 74 72 61 6e 73 66 6f  /// make transfo
6820: 72 6d 61 74 69 6f 6e 73 20 74 6f 20 74 68 65 20  rmations to the 
6830: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 57 48  ..        /// WH
6840: 45 52 45 20 63 6c 61 75 73 65 20 69 6e 20 6f 72  ERE clause in or
6850: 64 65 72 20 74 6f 20 65 78 74 72 61 63 74 20 61  der to extract a
6860: 73 20 6d 61 6e 79 20 63 6f 6e 73 74 72 61 69 6e  s many constrain
6870: 74 73 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ts ..        ///
6880: 20 61 73 20 69 74 20 63 61 6e 2e 20 53 6f 2c 20   as it can. So, 
6890: 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  for example, if 
68a0: 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65  the WHERE clause
68b0: 20 63 6f 6e 74 61 69 6e 65 64 20 73 6f 6d 65 74   contained somet
68c0: 68 69 6e 67 20 0d 0a 20 20 20 20 20 20 20 20 2f  hing ..        /
68d0: 2f 2f 20 6c 69 6b 65 20 74 68 69 73 3a 0d 0a 20  // like this:.. 
68e0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
68f0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
6900: 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20  <para><code>..  
6910: 20 20 20 20 20 20 2f 2f 2f 20 78 20 42 45 54 57        /// x BETW
6920: 45 45 4e 20 31 30 20 41 4e 44 20 31 30 30 20 41  EEN 10 AND 100 A
6930: 4e 44 20 39 39 39 26 67 74 3b 79 0d 0a 20 20 20  ND 999&gt;y..   
6940: 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e       /// </code>
6950: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
6960: 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20   /// <para>..   
6970: 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 71 75 65       /// The que
6980: 72 79 20 6f 70 74 69 6d 69 7a 65 72 20 6d 69 67  ry optimizer mig
6990: 68 74 20 74 72 61 6e 73 6c 61 74 65 20 74 68 69  ht translate thi
69a0: 73 20 69 6e 74 6f 20 74 68 72 65 65 20 73 65 70  s into three sep
69b0: 61 72 61 74 65 20 63 6f 6e 73 74 72 61 69 6e 74  arate constraint
69c0: 73 3a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  s:..        /// 
69d0: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
69e0: 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65   /// <para><code
69f0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 78  >..        /// x
6a00: 20 26 67 74 3b 3d 20 31 30 0d 0a 20 20 20 20 20   &gt;= 10..     
6a10: 20 20 20 2f 2f 2f 20 78 20 26 6c 74 3b 3d 20 31     /// x &lt;= 1
6a20: 30 30 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  00..        /// 
6a30: 79 20 26 6c 74 3b 20 39 39 39 0d 0a 20 20 20 20  y &lt; 999..    
6a40: 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c      /// </code><
6a50: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
6a60: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20  /// <para>..    
6a70: 20 20 20 20 2f 2f 2f 20 46 6f 72 20 65 61 63 68      /// For each
6a80: 20 63 6f 6e 73 74 72 61 69 6e 74 2c 20 74 68 65   constraint, the
6a90: 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69   aConstraint[].i
6aa0: 43 6f 6c 75 6d 6e 20 66 69 65 6c 64 20 69 6e 64  Column field ind
6ab0: 69 63 61 74 65 73 20 77 68 69 63 68 20 0d 0a 20  icates which .. 
6ac0: 20 20 20 20 20 20 20 2f 2f 2f 20 63 6f 6c 75 6d         /// colum
6ad0: 6e 20 61 70 70 65 61 72 73 20 6f 6e 20 74 68 65  n appears on the
6ae0: 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20   left-hand side 
6af0: 6f 66 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  of the constrain
6b00: 74 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  t...        /// 
6b10: 54 68 65 20 66 69 72 73 74 20 63 6f 6c 75 6d 6e  The first column
6b20: 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20   of the virtual 
6b30: 74 61 62 6c 65 20 69 73 20 63 6f 6c 75 6d 6e 20  table is column 
6b40: 30 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  0. ..        ///
6b50: 20 54 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68   The rowid of th
6b60: 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  e virtual table 
6b70: 69 73 20 63 6f 6c 75 6d 6e 20 2d 31 2e 20 0d 0a  is column -1. ..
6b80: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20          /// The 
6b90: 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70  aConstraint[].op
6ba0: 20 66 69 65 6c 64 20 69 6e 64 69 63 61 74 65 73   field indicates
6bb0: 20 77 68 69 63 68 20 6f 70 65 72 61 74 6f 72 20   which operator 
6bc0: 69 73 20 75 73 65 64 2e 20 0d 0a 20 20 20 20 20  is used. ..     
6bd0: 20 20 20 2f 2f 2f 20 54 68 65 20 53 51 4c 49 54     /// The SQLIT
6be0: 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
6bf0: 4e 54 5f 2a 20 63 6f 6e 73 74 61 6e 74 73 20 6d  NT_* constants m
6c00: 61 70 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  ap integer const
6c10: 61 6e 74 73 20 0d 0a 20 20 20 20 20 20 20 20 2f  ants ..        /
6c20: 2f 2f 20 69 6e 74 6f 20 6f 70 65 72 61 74 6f 72  // into operator
6c30: 20 76 61 6c 75 65 73 2e 0d 0a 20 20 20 20 20 20   values...      
6c40: 20 20 2f 2f 2f 20 43 6f 6c 75 6d 6e 73 20 6f 63    /// Columns oc
6c50: 63 75 72 20 69 6e 20 74 68 65 20 6f 72 64 65 72  cur in the order
6c60: 20 74 68 65 79 20 77 65 72 65 20 64 65 66 69 6e   they were defin
6c70: 65 64 20 62 79 20 74 68 65 20 63 61 6c 6c 20 74  ed by the call t
6c80: 6f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73  o..        /// s
6c90: 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76  qlite3_declare_v
6ca0: 74 61 62 28 29 20 69 6e 20 74 68 65 20 78 43 72  tab() in the xCr
6cb0: 65 61 74 65 20 6f 72 20 78 43 6f 6e 6e 65 63 74  eate or xConnect
6cc0: 20 6d 65 74 68 6f 64 2e 0d 0a 20 20 20 20 20 20   method...      
6cd0: 20 20 2f 2f 2f 20 48 69 64 64 65 6e 20 63 6f 6c    /// Hidden col
6ce0: 75 6d 6e 73 20 61 72 65 20 63 6f 75 6e 74 65 64  umns are counted
6cf0: 20 77 68 65 6e 20 64 65 74 65 72 6d 69 6e 69 6e   when determinin
6d00: 67 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 6e 64  g the column ind
6d10: 65 78 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ex...        ///
6d20: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
6d30: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
6d40: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 61 43        /// The aC
6d50: 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61  onstraint[] arra
6d60: 79 20 63 6f 6e 74 61 69 6e 73 20 69 6e 66 6f 72  y contains infor
6d70: 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 6c 6c  mation about all
6d80: 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 0d 0a 20   constraints .. 
6d90: 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 61 74 20         /// that 
6da0: 61 70 70 6c 79 20 74 6f 20 74 68 65 20 76 69 72  apply to the vir
6db0: 74 75 61 6c 20 74 61 62 6c 65 2e 20 42 75 74 20  tual table. But 
6dc0: 73 6f 6d 65 20 6f 66 20 74 68 65 20 63 6f 6e 73  some of the cons
6dd0: 74 72 61 69 6e 74 73 20 6d 69 67 68 74 0d 0a 20  traints might.. 
6de0: 20 20 20 20 20 20 20 2f 2f 2f 20 6e 6f 74 20 62         /// not b
6df0: 65 20 75 73 61 62 6c 65 20 62 65 63 61 75 73 65  e usable because
6e00: 20 6f 66 20 74 68 65 20 77 61 79 20 74 61 62 6c   of the way tabl
6e10: 65 73 20 61 72 65 20 6f 72 64 65 72 65 64 20 69  es are ordered i
6e20: 6e 20 61 20 6a 6f 69 6e 2e 20 0d 0a 20 20 20 20  n a join. ..    
6e30: 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 42 65 73      /// The xBes
6e40: 74 49 6e 64 65 78 20 6d 65 74 68 6f 64 20 6d 75  tIndex method mu
6e50: 73 74 20 74 68 65 72 65 66 6f 72 65 20 6f 6e 6c  st therefore onl
6e60: 79 20 63 6f 6e 73 69 64 65 72 20 63 6f 6e 73 74  y consider const
6e70: 72 61 69 6e 74 73 20 0d 0a 20 20 20 20 20 20 20  raints ..       
6e80: 20 2f 2f 2f 20 74 68 61 74 20 68 61 76 65 20 61   /// that have a
6e90: 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e  n aConstraint[].
6ea0: 75 73 61 62 6c 65 20 66 6c 61 67 20 77 68 69 63  usable flag whic
6eb0: 68 20 69 73 20 74 72 75 65 2e 0d 0a 20 20 20 20  h is true...    
6ec0: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
6ed0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
6ee0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
6ef0: 20 49 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20   In addition to 
6f00: 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e  WHERE clause con
6f10: 73 74 72 61 69 6e 74 73 2c 20 74 68 65 20 53 51  straints, the SQ
6f20: 4c 69 74 65 20 63 6f 72 65 20 61 6c 73 6f 20 0d  Lite core also .
6f30: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 65 6c  .        /// tel
6f40: 6c 73 20 74 68 65 20 78 42 65 73 74 49 6e 64 65  ls the xBestInde
6f50: 78 20 6d 65 74 68 6f 64 20 61 62 6f 75 74 20 74  x method about t
6f60: 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  he ORDER BY clau
6f70: 73 65 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  se. ..        //
6f80: 2f 20 28 49 6e 20 61 6e 20 61 67 67 72 65 67 61  / (In an aggrega
6f90: 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 53 51  te query, the SQ
6fa0: 4c 69 74 65 20 63 6f 72 65 20 6d 69 67 68 74 20  Lite core might 
6fb0: 70 75 74 20 69 6e 20 47 52 4f 55 50 20 42 59 20  put in GROUP BY 
6fc0: 63 6c 61 75 73 65 20 0d 0a 20 20 20 20 20 20 20  clause ..       
6fd0: 20 2f 2f 2f 20 69 6e 66 6f 72 6d 61 74 69 6f 6e   /// information
6fe0: 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
6ff0: 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
7000: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c 20 62 75   information, bu
7010: 74 20 74 68 69 73 20 66 61 63 74 0d 0a 20 20 20  t this fact..   
7020: 20 20 20 20 20 2f 2f 2f 20 73 68 6f 75 6c 64 20       /// should 
7030: 6e 6f 74 20 6d 61 6b 65 20 61 6e 79 20 64 69 66  not make any dif
7040: 66 65 72 65 6e 63 65 20 74 6f 20 74 68 65 20 78  ference to the x
7050: 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64  BestIndex method
7060: 2e 29 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  .) ..        ///
7070: 20 49 66 20 61 6c 6c 20 74 65 72 6d 73 20 6f 66   If all terms of
7080: 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
7090: 61 75 73 65 20 61 72 65 20 63 6f 6c 75 6d 6e 73  ause are columns
70a0: 20 69 6e 20 74 68 65 20 76 69 72 74 75 61 6c 20   in the virtual 
70b0: 74 61 62 6c 65 2c 20 0d 0a 20 20 20 20 20 20 20  table, ..       
70c0: 20 2f 2f 2f 20 74 68 65 6e 20 6e 4f 72 64 65 72   /// then nOrder
70d0: 42 79 20 77 69 6c 6c 20 62 65 20 74 68 65 20 6e  By will be the n
70e0: 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
70f0: 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  n the ORDER BY c
7100: 6c 61 75 73 65 20 0d 0a 20 20 20 20 20 20 20 20  lause ..        
7110: 2f 2f 2f 20 61 6e 64 20 74 68 65 20 61 4f 72 64  /// and the aOrd
7120: 65 72 42 79 5b 5d 20 61 72 72 61 79 20 77 69 6c  erBy[] array wil
7130: 6c 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 63  l identify the c
7140: 6f 6c 75 6d 6e 20 66 6f 72 20 65 61 63 68 20 74  olumn for each t
7150: 65 72 6d 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  erm ..        //
7160: 2f 20 69 6e 20 74 68 65 20 6f 72 64 65 72 20 62  / in the order b
7170: 79 20 63 6c 61 75 73 65 20 61 6e 64 20 77 68 65  y clause and whe
7180: 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 61 74  ther or not that
7190: 20 63 6f 6c 75 6d 6e 20 69 73 20 41 53 43 20 6f   column is ASC o
71a0: 72 20 44 45 53 43 2e 0d 0a 20 20 20 20 20 20 20  r DESC...       
71b0: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
71c0: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
71d0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 49 6e  ..        /// In
71e0: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
71f0: 33 2e 31 30 2e 30 20 28 32 30 31 36 2d 30 31 2d  3.10.0 (2016-01-
7200: 30 36 29 20 61 6e 64 20 6c 61 74 65 72 2c 20 0d  06) and later, .
7210: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65  .        /// the
7220: 20 63 6f 6c 55 73 65 64 20 66 69 65 6c 64 20 69   colUsed field i
7230: 73 20 61 76 61 69 6c 61 62 6c 65 0d 0a 20 20 20  s available..   
7240: 20 20 20 20 20 2f 2f 2f 20 74 6f 20 69 6e 64 69       /// to indi
7250: 63 61 74 65 20 77 68 69 63 68 20 66 69 65 6c 64  cate which field
7260: 73 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c  s of the virtual
7270: 20 74 61 62 6c 65 20 61 72 65 20 61 63 74 75 61   table are actua
7280: 6c 6c 79 20 75 73 65 64 20 62 79 20 74 68 65 0d  lly used by the.
7290: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 74 61  .        /// sta
72a0: 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 70 72 65  tement being pre
72b0: 70 61 72 65 64 2e 20 20 49 66 20 74 68 65 20 6c  pared.  If the l
72c0: 6f 77 65 73 74 20 62 69 74 20 6f 66 20 63 6f 6c  owest bit of col
72d0: 55 73 65 64 20 69 73 20 73 65 74 2c 20 74 68 61  Used is set, tha
72e0: 74 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6d  t..        /// m
72f0: 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 66 69  eans that the fi
7300: 72 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 75 73  rst column is us
7310: 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ed.  The second 
7320: 6c 6f 77 65 73 74 20 62 69 74 20 63 6f 72 72 65  lowest bit corre
7330: 73 70 6f 6e 64 73 0d 0a 20 20 20 20 20 20 20 20  sponds..        
7340: 2f 2f 2f 20 74 6f 20 74 68 65 20 73 65 63 6f 6e  /// to the secon
7350: 64 20 63 6f 6c 75 6d 6e 2e 20 20 41 6e 64 20 73  d column.  And s
7360: 6f 20 66 6f 72 74 68 2e 20 20 49 66 20 74 68 65  o forth.  If the
7370: 20 6d 6f 73 74 20 73 69 67 6e 69 66 69 63 61 6e   most significan
7380: 74 20 62 69 74 20 6f 66 0d 0a 20 20 20 20 20 20  t bit of..      
7390: 20 20 2f 2f 2f 20 63 6f 6c 55 73 65 64 20 69 73    /// colUsed is
73a0: 20 73 65 74 2c 20 74 68 61 74 20 6d 65 61 6e 73   set, that means
73b0: 20 74 68 61 74 20 6f 6e 65 20 6f 72 20 6d 6f 72   that one or mor
73c0: 65 20 63 6f 6c 75 6d 6e 73 20 6f 74 68 65 72 20  e columns other 
73d0: 74 68 61 6e 20 74 68 65 20 0d 0a 20 20 20 20 20  than the ..     
73e0: 20 20 20 2f 2f 2f 20 66 69 72 73 74 20 36 33 20     /// first 63 
73f0: 63 6f 6c 75 6d 6e 73 20 61 72 65 20 75 73 65 64  columns are used
7400: 2e 20 20 49 66 20 63 6f 6c 75 6d 6e 20 75 73 61  .  If column usa
7410: 67 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ge information i
7420: 73 20 6e 65 65 64 65 64 20 62 79 20 74 68 65 0d  s needed by the.
7430: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 78 46 69  .        /// xFi
7440: 6c 74 65 72 20 6d 65 74 68 6f 64 2c 20 74 68 65  lter method, the
7450: 6e 20 74 68 65 20 72 65 71 75 69 72 65 64 20 62  n the required b
7460: 69 74 73 20 6d 75 73 74 20 62 65 20 65 6e 63 6f  its must be enco
7470: 64 65 64 20 69 6e 74 6f 20 65 69 74 68 65 72 0d  ded into either.
7480: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65  .        /// the
7490: 20 69 64 78 4e 75 6d 20 6f 72 20 69 64 78 53 74   idxNum or idxSt
74a0: 72 20 6f 75 74 70 75 74 20 66 69 65 6c 64 73 2e  r output fields.
74b0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
74c0: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
74d0: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20  // <para>..     
74e0: 20 20 20 2f 2f 2f 20 47 69 76 65 6e 20 61 6c 6c     /// Given all
74f0: 20 6f 66 20 74 68 65 20 69 6e 66 6f 72 6d 61 74   of the informat
7500: 69 6f 6e 20 61 62 6f 76 65 2c 20 74 68 65 20 6a  ion above, the j
7510: 6f 62 20 6f 66 20 74 68 65 20 78 42 65 73 74 49  ob of the xBestI
7520: 6e 64 65 78 20 0d 0a 20 20 20 20 20 20 20 20 2f  ndex ..        /
7530: 2f 2f 20 6d 65 74 68 6f 64 20 69 74 20 74 6f 20  // method it to 
7540: 66 69 67 75 72 65 20 6f 75 74 20 74 68 65 20 62  figure out the b
7550: 65 73 74 20 77 61 79 20 74 6f 20 73 65 61 72 63  est way to searc
7560: 68 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  h the virtual ta
7570: 62 6c 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ble...        //
7580: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  / </para>..     
7590: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20     /// <para>.. 
75a0: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 78         /// The x
75b0: 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64  BestIndex method
75c0: 20 66 69 6c 6c 73 20 74 68 65 20 69 64 78 4e 75   fills the idxNu
75d0: 6d 20 61 6e 64 20 69 64 78 53 74 72 20 66 69 65  m and idxStr fie
75e0: 6c 64 73 20 77 69 74 68 20 0d 0a 20 20 20 20 20  lds with ..     
75f0: 20 20 20 2f 2f 2f 20 69 6e 66 6f 72 6d 61 74 69     /// informati
7600: 6f 6e 20 74 68 61 74 20 63 6f 6d 6d 75 6e 69 63  on that communic
7610: 61 74 65 73 20 61 6e 20 69 6e 64 65 78 69 6e 67  ates an indexing
7620: 20 73 74 72 61 74 65 67 79 20 74 6f 20 74 68 65   strategy to the
7630: 20 78 46 69 6c 74 65 72 20 0d 0a 20 20 20 20 20   xFilter ..     
7640: 20 20 20 2f 2f 2f 20 6d 65 74 68 6f 64 2e 20 54     /// method. T
7650: 68 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  he information i
7660: 6e 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78  n idxNum and idx
7670: 53 74 72 20 69 73 20 61 72 62 69 74 72 61 72 79  Str is arbitrary
7680: 20 61 73 20 66 61 72 20 0d 0a 20 20 20 20 20 20   as far ..      
7690: 20 20 2f 2f 2f 20 61 73 20 74 68 65 20 53 51 4c    /// as the SQL
76a0: 69 74 65 20 63 6f 72 65 20 69 73 20 63 6f 6e 63  ite core is conc
76b0: 65 72 6e 65 64 2e 20 54 68 65 20 53 51 4c 69 74  erned. The SQLit
76c0: 65 20 63 6f 72 65 20 6a 75 73 74 20 63 6f 70 69  e core just copi
76d0: 65 73 20 74 68 65 20 0d 0a 20 20 20 20 20 20 20  es the ..       
76e0: 20 2f 2f 2f 20 69 6e 66 6f 72 6d 61 74 69 6f 6e   /// information
76f0: 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
7700: 78 46 69 6c 74 65 72 20 6d 65 74 68 6f 64 2e 20  xFilter method. 
7710: 41 6e 79 20 64 65 73 69 72 65 64 20 6d 65 61 6e  Any desired mean
7720: 69 6e 67 20 63 61 6e 20 0d 0a 20 20 20 20 20 20  ing can ..      
7730: 20 20 2f 2f 2f 20 62 65 20 61 73 73 69 67 6e 65    /// be assigne
7740: 64 20 74 6f 20 69 64 78 4e 75 6d 20 61 6e 64 20  d to idxNum and 
7750: 69 64 78 53 74 72 20 61 73 20 6c 6f 6e 67 20 61  idxStr as long a
7760: 73 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64  s xBestIndex and
7770: 20 78 46 69 6c 74 65 72 20 0d 0a 20 20 20 20 20   xFilter ..     
7780: 20 20 20 2f 2f 2f 20 61 67 72 65 65 20 6f 6e 20     /// agree on 
7790: 77 68 61 74 20 74 68 61 74 20 6d 65 61 6e 69 6e  what that meanin
77a0: 67 20 69 73 2e 0d 0a 20 20 20 20 20 20 20 20 2f  g is...        /
77b0: 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  // </para>..    
77c0: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a      /// <para>..
77d0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20          /// The 
77e0: 69 64 78 53 74 72 20 76 61 6c 75 65 20 6d 61 79  idxStr value may
77f0: 20 62 65 20 61 20 73 74 72 69 6e 67 20 6f 62 74   be a string obt
7800: 61 69 6e 65 64 20 66 72 6f 6d 20 61 6e 20 53 51  ained from an SQ
7810: 4c 69 74 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f  Lite..        //
7820: 2f 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  / memory allocat
7830: 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 73 75 63  ion function suc
7840: 68 20 61 73 20 73 71 6c 69 74 65 33 5f 6d 70 72  h as sqlite3_mpr
7850: 69 6e 74 66 28 29 2e 20 0d 0a 20 20 20 20 20 20  intf(). ..      
7860: 20 20 2f 2f 2f 20 49 66 20 74 68 69 73 20 69 73    /// If this is
7870: 20 74 68 65 20 63 61 73 65 2c 20 74 68 65 6e 20   the case, then 
7880: 74 68 65 20 6e 65 65 64 54 6f 46 72 65 65 49 64  the needToFreeId
7890: 78 53 74 72 20 66 6c 61 67 20 6d 75 73 74 20 62  xStr flag must b
78a0: 65 20 73 65 74 20 74 6f 20 0d 0a 20 20 20 20 20  e set to ..     
78b0: 20 20 20 2f 2f 2f 20 74 72 75 65 20 73 6f 20 74     /// true so t
78c0: 68 61 74 20 74 68 65 20 53 51 4c 69 74 65 20 63  hat the SQLite c
78d0: 6f 72 65 20 77 69 6c 6c 20 6b 6e 6f 77 20 74 6f  ore will know to
78e0: 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 66 72   call sqlite3_fr
78f0: 65 65 28 29 20 6f 6e 20 0d 0a 20 20 20 20 20 20  ee() on ..      
7900: 20 20 2f 2f 2f 20 74 68 61 74 20 73 74 72 69 6e    /// that strin
7910: 67 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69  g when it has fi
7920: 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2c 20  nished with it, 
7930: 61 6e 64 20 74 68 75 73 20 61 76 6f 69 64 20 61  and thus avoid a
7940: 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0d 0a 20   memory leak... 
7950: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
7960: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
7970: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
7980: 2f 2f 2f 20 49 66 20 74 68 65 20 76 69 72 74 75  /// If the virtu
7990: 61 6c 20 74 61 62 6c 65 20 77 69 6c 6c 20 6f 75  al table will ou
79a0: 74 70 75 74 20 72 6f 77 73 20 69 6e 20 74 68 65  tput rows in the
79b0: 20 6f 72 64 65 72 20 73 70 65 63 69 66 69 65 64   order specified
79c0: 20 62 79 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f   by ..        //
79d0: 2f 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  / the ORDER BY c
79e0: 6c 61 75 73 65 2c 20 74 68 65 6e 20 74 68 65 20  lause, then the 
79f0: 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 20  orderByConsumed 
7a00: 66 6c 61 67 20 6d 61 79 20 62 65 20 73 65 74 20  flag may be set 
7a10: 74 6f 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  to ..        ///
7a20: 20 74 72 75 65 2e 20 49 66 20 74 68 65 20 6f 75   true. If the ou
7a30: 74 70 75 74 20 69 73 20 6e 6f 74 20 61 75 74 6f  tput is not auto
7a40: 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 65  matically in the
7a50: 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20 0d   correct order .
7a60: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65  .        /// the
7a70: 6e 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65  n orderByConsume
7a80: 64 20 6d 75 73 74 20 62 65 20 6c 65 66 74 20 69  d must be left i
7a90: 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 66 61  n its default fa
7aa0: 6c 73 65 20 73 65 74 74 69 6e 67 2e 20 0d 0a 20  lse setting. .. 
7ab0: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 69 73 20         /// This 
7ac0: 77 69 6c 6c 20 69 6e 64 69 63 61 74 65 20 74 6f  will indicate to
7ad0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
7ae0: 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 6e 65   that it will ne
7af0: 65 64 20 74 6f 20 64 6f 20 61 20 0d 0a 20 20 20  ed to do a ..   
7b00: 20 20 20 20 20 2f 2f 2f 20 73 65 70 61 72 61 74       /// separat
7b10: 65 20 73 6f 72 74 69 6e 67 20 70 61 73 73 20 6f  e sorting pass o
7b20: 76 65 72 20 74 68 65 20 64 61 74 61 20 61 66 74  ver the data aft
7b30: 65 72 20 69 74 20 63 6f 6d 65 73 20 6f 75 74 20  er it comes out 
7b40: 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  of the virtual t
7b50: 61 62 6c 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f  able...        /
7b60: 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  // </para>..    
7b70: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a      /// <para>..
7b80: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20          /// The 
7b90: 65 73 74 69 6d 61 74 65 64 43 6f 73 74 20 66 69  estimatedCost fi
7ba0: 65 6c 64 20 73 68 6f 75 6c 64 20 62 65 20 73 65  eld should be se
7bb0: 74 20 74 6f 20 74 68 65 20 65 73 74 69 6d 61 74  t to the estimat
7bc0: 65 64 20 6e 75 6d 62 65 72 0d 0a 20 20 20 20 20  ed number..     
7bd0: 20 20 20 2f 2f 2f 20 6f 66 20 64 69 73 6b 20 61     /// of disk a
7be0: 63 63 65 73 73 20 6f 70 65 72 61 74 69 6f 6e 73  ccess operations
7bf0: 20 72 65 71 75 69 72 65 64 20 74 6f 20 65 78 65   required to exe
7c00: 63 75 74 65 20 74 68 69 73 20 71 75 65 72 79 20  cute this query 
7c10: 61 67 61 69 6e 73 74 20 0d 0a 20 20 20 20 20 20  against ..      
7c20: 20 20 2f 2f 2f 20 74 68 65 20 76 69 72 74 75 61    /// the virtua
7c30: 6c 20 74 61 62 6c 65 2e 20 54 68 65 20 53 51 4c  l table. The SQL
7c40: 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6f 66  ite core will of
7c50: 74 65 6e 20 63 61 6c 6c 20 78 42 65 73 74 49 6e  ten call xBestIn
7c60: 64 65 78 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  dex ..        //
7c70: 2f 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  / multiple times
7c80: 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20   with different 
7c90: 63 6f 6e 73 74 72 61 69 6e 74 73 2c 20 6f 62 74  constraints, obt
7ca0: 61 69 6e 20 6d 75 6c 74 69 70 6c 65 20 63 6f 73  ain multiple cos
7cb0: 74 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 65  t..        /// e
7cc0: 73 74 69 6d 61 74 65 73 2c 20 74 68 65 6e 20 63  stimates, then c
7cd0: 68 6f 6f 73 65 20 74 68 65 20 71 75 65 72 79 20  hoose the query 
7ce0: 70 6c 61 6e 20 74 68 61 74 20 67 69 76 65 73 20  plan that gives 
7cf0: 74 68 65 20 6c 6f 77 65 73 74 20 65 73 74 69 6d  the lowest estim
7d00: 61 74 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ate...        //
7d10: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  / </para>..     
7d20: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20     /// <para>.. 
7d30: 20 20 20 20 20 20 20 2f 2f 2f 20 49 66 20 74 68         /// If th
7d40: 65 20 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f  e current versio
7d50: 6e 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 33  n of SQLite is 3
7d60: 2e 38 2e 32 20 6f 72 20 67 72 65 61 74 65 72 2c  .8.2 or greater,
7d70: 20 74 68 65 20 65 73 74 69 6d 61 74 65 64 52 6f   the estimatedRo
7d80: 77 73 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ws..        /// 
7d90: 66 69 65 6c 64 20 6d 61 79 20 62 65 20 73 65 74  field may be set
7da0: 20 74 6f 20 61 6e 20 65 73 74 69 6d 61 74 65 20   to an estimate 
7db0: 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
7dc0: 20 72 6f 77 73 20 72 65 74 75 72 6e 65 64 20 62   rows returned b
7dd0: 79 20 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f  y the..        /
7de0: 2f 2f 20 70 72 6f 70 6f 73 65 64 20 71 75 65 72  // proposed quer
7df0: 79 20 70 6c 61 6e 2e 20 49 66 20 74 68 69 73 20  y plan. If this 
7e00: 76 61 6c 75 65 20 69 73 20 6e 6f 74 20 65 78 70  value is not exp
7e10: 6c 69 63 69 74 6c 79 20 73 65 74 2c 20 74 68 65  licitly set, the
7e20: 20 64 65 66 61 75 6c 74 20 0d 0a 20 20 20 20 20   default ..     
7e30: 20 20 20 2f 2f 2f 20 65 73 74 69 6d 61 74 65 20     /// estimate 
7e40: 6f 66 20 32 35 20 72 6f 77 73 20 69 73 20 75 73  of 25 rows is us
7e50: 65 64 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ed...        ///
7e60: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
7e70: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
7e80: 20 20 20 20 20 20 2f 2f 2f 20 49 66 20 74 68 65        /// If the
7e90: 20 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f 6e   current version
7ea0: 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 33 2e   of SQLite is 3.
7eb0: 39 2e 30 20 6f 72 20 67 72 65 61 74 65 72 2c 20  9.0 or greater, 
7ec0: 74 68 65 20 69 64 78 46 6c 61 67 73 20 66 69 65  the idxFlags fie
7ed0: 6c 64 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ld..        /// 
7ee0: 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 53 51  may be set to SQ
7ef0: 4c 49 54 45 5f 49 4e 44 45 58 5f 53 43 41 4e 5f  LITE_INDEX_SCAN_
7f00: 55 4e 49 51 55 45 20 74 6f 20 69 6e 64 69 63 61  UNIQUE to indica
7f10: 74 65 20 74 68 61 74 20 74 68 65 20 76 69 72 74  te that the virt
7f20: 75 61 6c 20 74 61 62 6c 65 0d 0a 20 20 20 20 20  ual table..     
7f30: 20 20 20 2f 2f 2f 20 77 69 6c 6c 20 72 65 74 75     /// will retu
7f40: 72 6e 20 6f 6e 6c 79 20 7a 65 72 6f 20 6f 72 20  rn only zero or 
7f50: 6f 6e 65 20 72 6f 77 73 20 67 69 76 65 6e 20 74  one rows given t
7f60: 68 65 20 69 6e 70 75 74 20 63 6f 6e 73 74 72 61  he input constra
7f70: 69 6e 74 73 2e 20 20 41 64 64 69 74 69 6f 6e 61  ints.  Additiona
7f80: 6c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 62  l..        /// b
7f90: 69 74 73 20 6f 66 20 74 68 65 20 69 64 78 46 6c  its of the idxFl
7fa0: 61 67 73 20 66 69 65 6c 64 20 6d 69 67 68 74 20  ags field might 
7fb0: 62 65 20 75 6e 64 65 72 73 74 6f 6f 64 20 69 6e  be understood in
7fc0: 20 6c 61 74 65 72 20 76 65 72 73 69 6f 6e 73 20   later versions 
7fd0: 6f 66 20 53 51 4c 69 74 65 2e 0d 0a 20 20 20 20  of SQLite...    
7fe0: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
7ff0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
8000: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
8010: 20 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74   The aConstraint
8020: 55 73 61 67 65 5b 5d 20 61 72 72 61 79 20 63 6f  Usage[] array co
8030: 6e 74 61 69 6e 73 20 6f 6e 65 20 65 6c 65 6d 65  ntains one eleme
8040: 6e 74 20 66 6f 72 20 65 61 63 68 20 6f 66 20 0d  nt for each of .
8050: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65  .        /// the
8060: 20 6e 43 6f 6e 73 74 72 61 69 6e 74 20 63 6f 6e   nConstraint con
8070: 73 74 72 61 69 6e 74 73 20 69 6e 20 74 68 65 20  straints in the 
8080: 69 6e 70 75 74 73 20 73 65 63 74 69 6f 6e 20 6f  inputs section o
8090: 66 20 74 68 65 20 0d 0a 20 20 20 20 20 20 20 20  f the ..        
80a0: 2f 2f 2f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  /// sqlite3_inde
80b0: 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65  x_info structure
80c0: 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  . ..        /// 
80d0: 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 55  The aConstraintU
80e0: 73 61 67 65 5b 5d 20 61 72 72 61 79 20 69 73 20  sage[] array is 
80f0: 75 73 65 64 20 62 79 20 78 42 65 73 74 49 6e 64  used by xBestInd
8100: 65 78 20 74 6f 20 74 65 6c 6c 20 74 68 65 20 0d  ex to tell the .
8110: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 63 6f 72  .        /// cor
8120: 65 20 68 6f 77 20 69 74 20 69 73 20 75 73 69 6e  e how it is usin
8130: 67 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74  g the constraint
8140: 73 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  s...        /// 
8150: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
8160: 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20   /// <para>..   
8170: 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 42 65       /// The xBe
8180: 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64 20 6d  stIndex method m
8190: 61 79 20 73 65 74 20 61 43 6f 6e 73 74 72 61 69  ay set aConstrai
81a0: 6e 74 55 73 61 67 65 5b 5d 2e 61 72 67 76 49 6e  ntUsage[].argvIn
81b0: 64 65 78 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  dex ..        //
81c0: 2f 20 65 6e 74 72 69 65 73 20 74 6f 20 76 61 6c  / entries to val
81d0: 75 65 73 20 67 72 65 61 74 65 72 20 74 68 61 6e  ues greater than
81e0: 20 7a 65 72 6f 2e 20 0d 0a 20 20 20 20 20 20 20   zero. ..       
81f0: 20 2f 2f 2f 20 45 78 61 63 74 6c 79 20 6f 6e 65   /// Exactly one
8200: 20 65 6e 74 72 79 20 73 68 6f 75 6c 64 20 62 65   entry should be
8210: 20 73 65 74 20 74 6f 20 31 2c 20 61 6e 6f 74 68   set to 1, anoth
8220: 65 72 20 74 6f 20 32 2c 20 61 6e 6f 74 68 65 72  er to 2, another
8230: 20 74 6f 20 33 2c 20 0d 0a 20 20 20 20 20 20 20   to 3, ..       
8240: 20 2f 2f 2f 20 61 6e 64 20 73 6f 20 66 6f 72 74   /// and so fort
8250: 68 20 75 70 20 74 6f 20 61 73 20 6d 61 6e 79 20  h up to as many 
8260: 6f 72 20 61 73 20 66 65 77 20 61 73 20 74 68 65  or as few as the
8270: 20 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68   xBestIndex meth
8280: 6f 64 20 77 61 6e 74 73 2e 20 0d 0a 20 20 20 20  od wants. ..    
8290: 20 20 20 20 2f 2f 2f 20 54 68 65 20 45 58 50 52      /// The EXPR
82a0: 20 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f   of the correspo
82b0: 6e 64 69 6e 67 20 63 6f 6e 73 74 72 61 69 6e 74  nding constraint
82c0: 73 20 77 69 6c 6c 20 74 68 65 6e 20 62 65 20 70  s will then be p
82d0: 61 73 73 65 64 20 0d 0a 20 20 20 20 20 20 20 20  assed ..        
82e0: 2f 2f 2f 20 69 6e 20 61 73 20 74 68 65 20 61 72  /// in as the ar
82f0: 67 76 5b 5d 20 70 61 72 61 6d 65 74 65 72 73 20  gv[] parameters 
8300: 74 6f 20 78 46 69 6c 74 65 72 2e 0d 0a 20 20 20  to xFilter...   
8310: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e       /// </para>
8320: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
8330: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
8340: 2f 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  / For example, i
8350: 66 20 74 68 65 20 61 43 6f 6e 73 74 72 61 69 6e  f the aConstrain
8360: 74 5b 33 5d 2e 61 72 67 76 49 6e 64 65 78 20 69  t[3].argvIndex i
8370: 73 20 73 65 74 20 74 6f 20 31 2c 20 74 68 65 6e  s set to 1, then
8380: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 77   ..        /// w
8390: 68 65 6e 20 78 46 69 6c 74 65 72 20 69 73 20 63  hen xFilter is c
83a0: 61 6c 6c 65 64 2c 20 74 68 65 20 61 72 67 76 5b  alled, the argv[
83b0: 30 5d 20 70 61 73 73 65 64 20 74 6f 20 78 46 69  0] passed to xFi
83c0: 6c 74 65 72 20 77 69 6c 6c 20 68 61 76 65 20 0d  lter will have .
83d0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65  .        /// the
83e0: 20 45 58 50 52 20 76 61 6c 75 65 20 6f 66 20 74   EXPR value of t
83f0: 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 33  he aConstraint[3
8400: 5d 20 63 6f 6e 73 74 72 61 69 6e 74 2e 0d 0a 20  ] constraint... 
8410: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
8420: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
8430: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
8440: 2f 2f 2f 20 42 79 20 64 65 66 61 75 6c 74 2c 20  /// By default, 
8450: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  the SQLite core 
8460: 64 6f 75 62 6c 65 20 63 68 65 63 6b 73 20 61 6c  double checks al
8470: 6c 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 6f 6e  l constraints on
8480: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 65   ..        /// e
8490: 61 63 68 20 72 6f 77 20 6f 66 20 74 68 65 20 76  ach row of the v
84a0: 69 72 74 75 61 6c 20 74 61 62 6c 65 20 74 68 61  irtual table tha
84b0: 74 20 69 74 20 72 65 63 65 69 76 65 73 2e 20 49  t it receives. I
84c0: 66 20 73 75 63 68 20 61 20 63 68 65 63 6b 20 0d  f such a check .
84d0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 73 20  .        /// is 
84e0: 72 65 64 75 6e 64 61 6e 74 2c 20 74 68 65 20 78  redundant, the x
84f0: 42 65 73 74 46 69 6c 74 65 72 20 6d 65 74 68 6f  BestFilter metho
8500: 64 20 63 61 6e 20 73 75 70 70 72 65 73 73 20 74  d can suppress t
8510: 68 61 74 20 64 6f 75 62 6c 65 2d 63 68 65 63 6b  hat double-check
8520: 20 62 79 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f   by ..        //
8530: 2f 20 73 65 74 74 69 6e 67 20 61 43 6f 6e 73 74  / setting aConst
8540: 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d 69  raintUsage[].omi
8550: 74 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  t...        /// 
8560: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
8570: 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d   /// </summary>.
8580: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
8590: 72 61 6d 20 6e 61 6d 65 3d 22 70 56 74 61 62 22  ram name="pVtab"
85a0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54  >..        /// T
85b0: 68 65 20 6e 61 74 69 76 65 20 70 6f 69 6e 74 65  he native pointe
85c0: 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
85d0: 5f 76 74 61 62 20 64 65 72 69 76 65 64 20 73 74  _vtab derived st
85e0: 72 75 63 74 75 72 65 2e 0d 0a 20 20 20 20 20 20  ructure...      
85f0: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a    /// </param>..
8600: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
8610: 61 6d 20 6e 61 6d 65 3d 22 70 49 6e 64 65 78 22  am name="pIndex"
8620: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54  >..        /// T
8630: 68 65 20 6e 61 74 69 76 65 20 70 6f 69 6e 74 65  he native pointe
8640: 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
8650: 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75  _index_info stru
8660: 63 74 75 72 65 2e 0d 0a 20 20 20 20 20 20 20 20  cture...        
8670: 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20  /// </param>..  
8680: 20 20 20 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72        /// <retur
8690: 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ns>..        ///
86a0: 20 41 20 73 74 61 6e 64 61 72 64 20 53 51 4c 69   A standard SQLi
86b0: 74 65 20 72 65 74 75 72 6e 20 63 6f 64 65 2e 0d  te return code..
86c0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72  .        /// </r
86d0: 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20  eturns>..       
86e0: 20 53 51 4c 69 74 65 45 72 72 6f 72 43 6f 64 65   SQLiteErrorCode
86f0: 20 78 42 65 73 74 49 6e 64 65 78 28 0d 0a 20 20   xBestIndex(..  
8700: 20 20 20 20 20 20 20 20 20 20 49 6e 74 50 74 72            IntPtr
8710: 20 70 56 74 61 62 2c 0d 0a 20 20 20 20 20 20 20   pVtab,..       
8720: 20 20 20 20 20 49 6e 74 50 74 72 20 70 49 6e 64       IntPtr pInd
8730: 65 78 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20  ex..            
8740: 29 3b 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f  );....        //
8750: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8760: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8770: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8780: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8790: 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 20 20 20  /////....       
87a0: 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a   /// <summary>..
87b0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
87c0: 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20  a><code>..      
87d0: 20 20 2f 2f 2f 20 69 6e 74 20 28 2a 78 44 69 73    /// int (*xDis
87e0: 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33  connect)(sqlite3
87f0: 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0d 0a  _vtab *pVTab);..
8800: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f          /// </co
8810: 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  de></para>..    
8820: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a      /// <para>..
8830: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 69 73          /// This
8840: 20 6d 65 74 68 6f 64 20 72 65 6c 65 61 73 65 73   method releases
8850: 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f   a connection to
8860: 20 61 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65   a virtual table
8870: 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  . ..        /// 
8880: 4f 6e 6c 79 20 74 68 65 20 73 71 6c 69 74 65 33  Only the sqlite3
8890: 5f 76 74 61 62 20 6f 62 6a 65 63 74 20 69 73 20  _vtab object is 
88a0: 64 65 73 74 72 6f 79 65 64 2e 0d 0a 20 20 20 20  destroyed...    
88b0: 20 20 20 20 2f 2f 2f 20 54 68 65 20 76 69 72 74      /// The virt
88c0: 75 61 6c 20 74 61 62 6c 65 20 69 73 20 6e 6f 74  ual table is not
88d0: 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61   destroyed and a
88e0: 6e 79 20 62 61 63 6b 69 6e 67 20 73 74 6f 72 65  ny backing store
88f0: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 61   ..        /// a
8900: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
8910: 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
8920: 20 70 65 72 73 69 73 74 73 2e 20 0d 0a 20 20 20   persists. ..   
8930: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e       /// </para>
8940: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
8950: 69 73 20 6d 65 74 68 6f 64 20 75 6e 64 6f 65 73  is method undoes
8960: 20 74 68 65 20 77 6f 72 6b 20 6f 66 20 78 43 6f   the work of xCo
8970: 6e 6e 65 63 74 2e 0d 0a 20 20 20 20 20 20 20 20  nnect...        
8980: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20  /// <para>..    
8990: 20 20 20 20 2f 2f 2f 20 54 68 69 73 20 6d 65 74      /// This met
89a0: 68 6f 64 20 69 73 20 61 20 64 65 73 74 72 75 63  hod is a destruc
89b0: 74 6f 72 20 66 6f 72 20 61 20 63 6f 6e 6e 65 63  tor for a connec
89c0: 74 69 6f 6e 20 74 6f 20 74 68 65 20 76 69 72 74  tion to the virt
89d0: 75 61 6c 20 74 61 62 6c 65 2e 0d 0a 20 20 20 20  ual table...    
89e0: 20 20 20 20 2f 2f 2f 20 43 6f 6e 74 72 61 73 74      /// Contrast
89f0: 20 74 68 69 73 20 6d 65 74 68 6f 64 20 77 69 74   this method wit
8a00: 68 20 78 44 65 73 74 72 6f 79 2e 20 20 54 68 65  h xDestroy.  The
8a10: 20 78 44 65 73 74 72 6f 79 20 69 73 20 61 20 64   xDestroy is a d
8a20: 65 73 74 72 75 63 74 6f 72 0d 0a 20 20 20 20 20  estructor..     
8a30: 20 20 20 2f 2f 2f 20 66 6f 72 20 74 68 65 20 65     /// for the e
8a40: 6e 74 69 72 65 20 76 69 72 74 75 61 6c 20 74 61  ntire virtual ta
8a50: 62 6c 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ble...        //
8a60: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  / </para>..     
8a70: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20     /// <para>.. 
8a80: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 78         /// The x
8a90: 44 69 73 63 6f 6e 6e 65 63 74 20 6d 65 74 68 6f  Disconnect metho
8aa0: 64 20 69 73 20 72 65 71 75 69 72 65 64 20 66 6f  d is required fo
8ab0: 72 20 65 76 65 72 79 20 76 69 72 74 75 61 6c 20  r every virtual 
8ac0: 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
8ad0: 74 69 6f 6e 2c 0d 0a 20 20 20 20 20 20 20 20 2f  tion,..        /
8ae0: 2f 2f 20 74 68 6f 75 67 68 20 69 74 20 69 73 20  // though it is 
8af0: 61 63 63 65 70 74 61 62 6c 65 20 66 6f 72 20 74  acceptable for t
8b00: 68 65 20 78 44 69 73 63 6f 6e 6e 65 63 74 20 61  he xDisconnect a
8b10: 6e 64 20 78 44 65 73 74 72 6f 79 20 6d 65 74 68  nd xDestroy meth
8b20: 6f 64 73 20 74 6f 20 62 65 0d 0a 20 20 20 20 20  ods to be..     
8b30: 20 20 20 2f 2f 2f 20 74 68 65 20 73 61 6d 65 20     /// the same 
8b40: 66 75 6e 63 74 69 6f 6e 20 69 66 20 74 68 61 74  function if that
8b50: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 66 6f 72   makes sense for
8b60: 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
8b70: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 0d 0a  virtual table...
8b80: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
8b90: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
8ba0: 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20   </summary>..   
8bb0: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20       /// <param 
8bc0: 6e 61 6d 65 3d 22 70 56 74 61 62 22 3e 0d 0a 20  name="pVtab">.. 
8bd0: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e         /// The n
8be0: 61 74 69 76 65 20 70 6f 69 6e 74 65 72 20 74 6f  ative pointer to
8bf0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 74 61   the sqlite3_vta
8c00: 62 20 64 65 72 69 76 65 64 20 73 74 72 75 63 74  b derived struct
8c10: 75 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ure...        //
8c20: 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20  / </param>..    
8c30: 20 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72 6e 73      /// <returns
8c40: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41  >..        /// A
8c50: 20 73 74 61 6e 64 61 72 64 20 53 51 4c 69 74 65   standard SQLite
8c60: 20 72 65 74 75 72 6e 20 63 6f 64 65 2e 0d 0a 20   return code... 
8c70: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72 65 74         /// </ret
8c80: 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 53  urns>..        S
8c90: 51 4c 69 74 65 45 72 72 6f 72 43 6f 64 65 20 78  QLiteErrorCode x
8ca0: 44 69 73 63 6f 6e 6e 65 63 74 28 0d 0a 20 20 20  Disconnect(..   
8cb0: 20 20 20 20 20 20 20 20 20 49 6e 74 50 74 72 20           IntPtr 
8cc0: 70 56 74 61 62 0d 0a 20 20 20 20 20 20 20 20 20  pVtab..         
8cd0: 20 20 20 29 3b 0d 0a 0d 0a 20 20 20 20 20 20 20     );....       
8ce0: 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f   ///////////////
8cf0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8d00: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8d10: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8d20: 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20  ////////....    
8d30: 20 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79      /// <summary
8d40: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
8d50: 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20  para><code>..   
8d60: 20 20 20 20 20 2f 2f 2f 20 69 6e 74 20 28 2a 78       /// int (*x
8d70: 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33  Destroy)(sqlite3
8d80: 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0d 0a  _vtab *pVTab);..
8d90: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f          /// </co
8da0: 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  de></para>..    
8db0: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a      /// <para>..
8dc0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 69 73          /// This
8dd0: 20 6d 65 74 68 6f 64 20 72 65 6c 65 61 73 65 73   method releases
8de0: 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f   a connection to
8df0: 20 61 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65   a virtual table
8e00: 2c 20 6a 75 73 74 20 6c 69 6b 65 20 0d 0a 20 20  , just like ..  
8e10: 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 20 78 44        /// the xD
8e20: 69 73 63 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64  isconnect method
8e30: 2c 20 61 6e 64 20 69 74 20 61 6c 73 6f 20 64 65  , and it also de
8e40: 73 74 72 6f 79 73 20 74 68 65 20 75 6e 64 65 72  stroys the under
8e50: 6c 79 69 6e 67 20 0d 0a 20 20 20 20 20 20 20 20  lying ..        
8e60: 2f 2f 2f 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  /// table implem
8e70: 65 6e 74 61 74 69 6f 6e 2e 20 54 68 69 73 20 6d  entation. This m
8e80: 65 74 68 6f 64 20 75 6e 64 6f 65 73 20 74 68 65  ethod undoes the
8e90: 20 77 6f 72 6b 20 6f 66 20 78 43 72 65 61 74 65   work of xCreate
8ea0: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
8eb0: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
8ec0: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20  /// <para>..    
8ed0: 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 44 69 73      /// The xDis
8ee0: 63 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64 20 69  connect method i
8ef0: 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 76 65  s called wheneve
8f00: 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  r a database con
8f10: 6e 65 63 74 69 6f 6e 0d 0a 20 20 20 20 20 20 20  nection..       
8f20: 20 2f 2f 2f 20 74 68 61 74 20 75 73 65 73 20 61   /// that uses a
8f30: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
8f40: 73 20 63 6c 6f 73 65 64 2e 20 54 68 65 20 78 44  s closed. The xD
8f50: 65 73 74 72 6f 79 20 6d 65 74 68 6f 64 20 69 73  estroy method is
8f60: 20 6f 6e 6c 79 20 0d 0a 20 20 20 20 20 20 20 20   only ..        
8f70: 2f 2f 2f 20 63 61 6c 6c 65 64 20 77 68 65 6e 20  /// called when 
8f80: 61 20 44 52 4f 50 20 54 41 42 4c 45 20 73 74 61  a DROP TABLE sta
8f90: 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74  tement is execut
8fa0: 65 64 20 61 67 61 69 6e 73 74 20 74 68 65 20 76  ed against the v
8fb0: 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 0d 0a 20  irtual table... 
8fc0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
8fd0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
8fe0: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
8ff0: 2f 2f 2f 20 54 68 65 20 78 44 65 73 74 72 6f 79  /// The xDestroy
9000: 20 6d 65 74 68 6f 64 20 69 73 20 72 65 71 75 69   method is requi
9010: 72 65 64 20 66 6f 72 20 65 76 65 72 79 20 76 69  red for every vi
9020: 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c  rtual table impl
9030: 65 6d 65 6e 74 61 74 69 6f 6e 2c 0d 0a 20 20 20  ementation,..   
9040: 20 20 20 20 20 2f 2f 2f 20 74 68 6f 75 67 68 20       /// though 
9050: 69 74 20 69 73 20 61 63 63 65 70 74 61 62 6c 65  it is acceptable
9060: 20 66 6f 72 20 74 68 65 20 78 44 69 73 63 6f 6e   for the xDiscon
9070: 6e 65 63 74 20 61 6e 64 20 78 44 65 73 74 72 6f  nect and xDestro
9080: 79 20 6d 65 74 68 6f 64 73 20 74 6f 20 62 65 0d  y methods to be.
9090: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65  .        /// the
90a0: 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 69   same function i
90b0: 66 20 74 68 61 74 20 6d 61 6b 65 73 20 73 65 6e  f that makes sen
90c0: 73 65 20 66 6f 72 20 74 68 65 20 70 61 72 74 69  se for the parti
90d0: 63 75 6c 61 72 20 76 69 72 74 75 61 6c 20 74 61  cular virtual ta
90e0: 62 6c 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ble...        //
90f0: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  / </para>..     
9100: 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79     /// </summary
9110: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
9120: 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 56 74 61  param name="pVta
9130: 62 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  b">..        ///
9140: 20 54 68 65 20 6e 61 74 69 76 65 20 70 6f 69 6e   The native poin
9150: 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
9160: 65 33 5f 76 74 61 62 20 64 65 72 69 76 65 64 20  e3_vtab derived 
9170: 73 74 72 75 63 74 75 72 65 2e 0d 0a 20 20 20 20  structure...    
9180: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e      /// </param>
9190: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 72  ..        /// <r
91a0: 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20  eturns>..       
91b0: 20 2f 2f 2f 20 41 20 73 74 61 6e 64 61 72 64 20   /// A standard 
91c0: 53 51 4c 69 74 65 20 72 65 74 75 72 6e 20 63 6f  SQLite return co
91d0: 64 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  de...        ///
91e0: 20 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20   </returns>..   
91f0: 20 20 20 20 20 53 51 4c 69 74 65 45 72 72 6f 72       SQLiteError
9200: 43 6f 64 65 20 78 44 65 73 74 72 6f 79 28 0d 0a  Code xDestroy(..
9210: 20 20 20 20 20 20 20 20 20 20 20 20 49 6e 74 50              IntP
9220: 74 72 20 70 56 74 61 62 0d 0a 20 20 20 20 20 20  tr pVtab..      
9230: 20 20 20 20 20 20 29 3b 0d 0a 0d 0a 20 20 20 20        );....    
9240: 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f      ////////////
9250: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
9260: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
9270: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
9280: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20  ///////////.... 
9290: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d         /// <summ
92a0: 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ary>..        //
92b0: 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a  / <para><code>..
92c0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e 74 20          /// int 
92d0: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
92e0: 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71  _vtab *pVTab, sq
92f0: 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
9300: 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0d 0a  r **ppCursor);..
9310: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f          /// </co
9320: 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  de></para>..    
9330: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a      /// <para>..
9340: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20          /// The 
9350: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 63 72 65  xOpen method cre
9360: 61 74 65 73 20 61 20 6e 65 77 20 63 75 72 73 6f  ates a new curso
9370: 72 20 75 73 65 64 20 66 6f 72 20 61 63 63 65 73  r used for acces
9380: 73 69 6e 67 20 28 72 65 61 64 20 61 6e 64 2f 6f  sing (read and/o
9390: 72 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 77  r..        /// w
93a0: 72 69 74 69 6e 67 29 20 61 20 76 69 72 74 75 61  riting) a virtua
93b0: 6c 20 74 61 62 6c 65 2e 20 20 41 20 73 75 63 63  l table.  A succ
93c0: 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f  essful invocatio
93d0: 6e 20 6f 66 20 74 68 69 73 20 6d 65 74 68 6f 64  n of this method
93e0: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 77   ..        /// w
93f0: 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  ill allocate the
9400: 20 6d 65 6d 6f 72 79 20 66 6f 72 20 74 68 65 20   memory for the 
9410: 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
9420: 73 6f 72 20 28 6f 72 20 61 20 73 75 62 63 6c 61  sor (or a subcla
9430: 73 73 29 2c 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ss),..        //
9440: 2f 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  / initialize the
9450: 20 6e 65 77 20 6f 62 6a 65 63 74 2c 20 61 6e 64   new object, and
9460: 20 6d 61 6b 65 20 2a 70 70 43 75 72 73 6f 72 20   make *ppCursor 
9470: 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 6e 65 77  point to the new
9480: 20 6f 62 6a 65 63 74 2e 0d 0a 20 20 20 20 20 20   object...      
9490: 20 20 2f 2f 2f 20 54 68 65 20 73 75 63 63 65 73    /// The succes
94a0: 73 66 75 6c 20 63 61 6c 6c 20 74 68 65 6e 20 72  sful call then r
94b0: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b  eturns SQLITE_OK
94c0: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
94d0: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
94e0: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20  /// <para>..    
94f0: 20 20 20 20 2f 2f 2f 20 46 6f 72 20 65 76 65 72      /// For ever
9500: 79 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  y successful cal
9510: 6c 20 74 6f 20 74 68 69 73 20 6d 65 74 68 6f 64  l to this method
9520: 2c 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  , the SQLite cor
9530: 65 20 77 69 6c 6c 0d 0a 20 20 20 20 20 20 20 20  e will..        
9540: 2f 2f 2f 20 6c 61 74 65 72 20 69 6e 76 6f 6b 65  /// later invoke
9550: 20 74 68 65 20 78 43 6c 6f 73 65 20 6d 65 74 68   the xClose meth
9560: 6f 64 20 74 6f 20 64 65 73 74 72 6f 79 20 0d 0a  od to destroy ..
9570: 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 20          /// the 
9580: 61 6c 6c 6f 63 61 74 65 64 20 63 75 72 73 6f 72  allocated cursor
9590: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
95a0: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
95b0: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20  /// <para>..    
95c0: 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 4f 70 65      /// The xOpe
95d0: 6e 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f  n method need no
95e0: 74 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  t initialize the
95f0: 20 70 56 74 61 62 20 66 69 65 6c 64 20 6f 66 20   pVtab field of 
9600: 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  the..        ///
9610: 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
9620: 72 73 6f 72 20 73 74 72 75 63 74 75 72 65 2e 20  rsor structure. 
9630: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
9640: 20 77 69 6c 6c 20 74 61 6b 65 20 63 61 72 65 0d   will take care.
9650: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6f 66 20  .        /// of 
9660: 74 68 61 74 20 63 68 6f 72 65 20 61 75 74 6f 6d  that chore autom
9670: 61 74 69 63 61 6c 6c 79 2e 0d 0a 20 20 20 20 20  atically...     
9680: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a     /// </para>..
9690: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
96a0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
96b0: 41 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  A virtual table 
96c0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
96d0: 75 73 74 20 62 65 20 61 62 6c 65 20 74 6f 20 73  ust be able to s
96e0: 75 70 70 6f 72 74 20 61 6e 20 61 72 62 69 74 72  upport an arbitr
96f0: 61 72 79 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ary..        ///
9700: 20 6e 75 6d 62 65 72 20 6f 66 20 73 69 6d 75 6c   number of simul
9710: 74 61 6e 65 6f 75 73 6c 79 20 6f 70 65 6e 20 63  taneously open c
9720: 75 72 73 6f 72 73 2e 0d 0a 20 20 20 20 20 20 20  ursors...       
9730: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
9740: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
9750: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 57 68  ..        /// Wh
9760: 65 6e 20 69 6e 69 74 69 61 6c 6c 79 20 6f 70 65  en initially ope
9770: 6e 65 64 2c 20 74 68 65 20 63 75 72 73 6f 72 20  ned, the cursor 
9780: 69 73 20 69 6e 20 61 6e 20 75 6e 64 65 66 69 6e  is in an undefin
9790: 65 64 20 73 74 61 74 65 2e 0d 0a 20 20 20 20 20  ed state...     
97a0: 20 20 20 2f 2f 2f 20 54 68 65 20 53 51 4c 69 74     /// The SQLit
97b0: 65 20 63 6f 72 65 20 77 69 6c 6c 20 69 6e 76 6f  e core will invo
97c0: 6b 65 20 74 68 65 20 78 46 69 6c 74 65 72 20 6d  ke the xFilter m
97d0: 65 74 68 6f 64 0d 0a 20 20 20 20 20 20 20 20 2f  ethod..        /
97e0: 2f 2f 20 6f 6e 20 74 68 65 20 63 75 72 73 6f 72  // on the cursor
97f0: 20 70 72 69 6f 72 20 74 6f 20 61 6e 79 20 61 74   prior to any at
9800: 74 65 6d 70 74 20 74 6f 20 70 6f 73 69 74 69 6f  tempt to positio
9810: 6e 20 6f 72 20 72 65 61 64 20 66 72 6f 6d 20 74  n or read from t
9820: 68 65 20 63 75 72 73 6f 72 2e 0d 0a 20 20 20 20  he cursor...    
9830: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
9840: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
9850: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
9860: 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   The xOpen metho
9870: 64 20 69 73 20 72 65 71 75 69 72 65 64 20 66 6f  d is required fo
9880: 72 20 65 76 65 72 79 20 76 69 72 74 75 61 6c 20  r every virtual 
9890: 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
98a0: 74 69 6f 6e 2e 0d 0a 20 20 20 20 20 20 20 20 2f  tion...        /
98b0: 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  // </para>..    
98c0: 20 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72      /// </summar
98d0: 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  y>..        /// 
98e0: 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 56 74  <param name="pVt
98f0: 61 62 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ab">..        //
9900: 2f 20 54 68 65 20 6e 61 74 69 76 65 20 70 6f 69  / The native poi
9910: 6e 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  nter to the sqli
9920: 74 65 33 5f 76 74 61 62 20 64 65 72 69 76 65 64  te3_vtab derived
9930: 20 73 74 72 75 63 74 75 72 65 2e 0d 0a 20 20 20   structure...   
9940: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d       /// </param
9950: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
9960: 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 43 75 72  param name="pCur
9970: 73 6f 72 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f  sor">..        /
9980: 2f 2f 20 55 70 6f 6e 20 73 75 63 63 65 73 73 2c  // Upon success,
9990: 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
99a0: 6d 75 73 74 20 62 65 20 6d 6f 64 69 66 69 65 64  must be modified
99b0: 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65   to point to the
99c0: 20 6e 65 77 6c 79 0d 0a 20 20 20 20 20 20 20 20   newly..        
99d0: 2f 2f 2f 20 63 72 65 61 74 65 64 20 6e 61 74 69  /// created nati
99e0: 76 65 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  ve sqlite3_vtab_
99f0: 63 75 72 73 6f 72 20 64 65 72 69 76 65 64 20 73  cursor derived s
9a00: 74 72 75 63 74 75 72 65 2e 0d 0a 20 20 20 20 20  tructure...     
9a10: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d     /// </param>.
9a20: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 72 65  .        /// <re
9a30: 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20  turns>..        
9a40: 2f 2f 2f 20 41 20 73 74 61 6e 64 61 72 64 20 53  /// A standard S
9a50: 51 4c 69 74 65 20 72 65 74 75 72 6e 20 63 6f 64  QLite return cod
9a60: 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e...        /// 
9a70: 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20  </returns>..    
9a80: 20 20 20 20 53 51 4c 69 74 65 45 72 72 6f 72 43      SQLiteErrorC
9a90: 6f 64 65 20 78 4f 70 65 6e 28 0d 0a 20 20 20 20  ode xOpen(..    
9aa0: 20 20 20 20 20 20 20 20 49 6e 74 50 74 72 20 70          IntPtr p
9ab0: 56 74 61 62 2c 0d 0a 20 20 20 20 20 20 20 20 20  Vtab,..         
9ac0: 20 20 20 72 65 66 20 49 6e 74 50 74 72 20 70 43     ref IntPtr pC
9ad0: 75 72 73 6f 72 0d 0a 20 20 20 20 20 20 20 20 20  ursor..         
9ae0: 20 20 20 29 3b 0d 0a 0d 0a 20 20 20 20 20 20 20     );....       
9af0: 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f   ///////////////
9b00: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
9b10: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
9b20: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
9b30: 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20  ////////....    
9b40: 20 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79      /// <summary
9b50: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
9b60: 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20  para><code>..   
9b70: 20 20 20 20 20 2f 2f 2f 20 69 6e 74 20 28 2a 78       /// int (*x
9b80: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76  Close)(sqlite3_v
9b90: 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0d 0a 20  tab_cursor*);.. 
9ba0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64         /// </cod
9bb0: 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  e></para>..     
9bc0: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20     /// <para>.. 
9bd0: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 78         /// The x
9be0: 43 6c 6f 73 65 20 6d 65 74 68 6f 64 20 63 6c 6f  Close method clo
9bf0: 73 65 73 20 61 20 63 75 72 73 6f 72 20 70 72 65  ses a cursor pre
9c00: 76 69 6f 75 73 6c 79 20 6f 70 65 6e 65 64 20 62  viously opened b
9c10: 79 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  y ..        /// 
9c20: 78 4f 70 65 6e 2e 20 0d 0a 20 20 20 20 20 20 20  xOpen. ..       
9c30: 20 2f 2f 2f 20 54 68 65 20 53 51 4c 69 74 65 20   /// The SQLite 
9c40: 63 6f 72 65 20 77 69 6c 6c 20 61 6c 77 61 79 73  core will always
9c50: 20 63 61 6c 6c 20 78 43 6c 6f 73 65 20 6f 6e 63   call xClose onc
9c60: 65 20 66 6f 72 20 65 61 63 68 20 63 75 72 73 6f  e for each curso
9c70: 72 20 6f 70 65 6e 65 64 20 0d 0a 20 20 20 20 20  r opened ..     
9c80: 20 20 20 2f 2f 2f 20 75 73 69 6e 67 20 78 4f 70     /// using xOp
9c90: 65 6e 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  en...        ///
9ca0: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
9cb0: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
9cc0: 20 20 20 20 20 20 2f 2f 2f 20 54 68 69 73 20 6d        /// This m
9cd0: 65 74 68 6f 64 20 6d 75 73 74 20 72 65 6c 65 61  ethod must relea
9ce0: 73 65 20 61 6c 6c 20 72 65 73 6f 75 72 63 65 73  se all resources
9cf0: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 74 68   allocated by th
9d00: 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 63  e..        /// c
9d10: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 78 4f 70  orresponding xOp
9d20: 65 6e 20 63 61 6c 6c 2e 20 54 68 65 20 72 6f 75  en call. The rou
9d30: 74 69 6e 65 20 77 69 6c 6c 20 6e 6f 74 20 62 65  tine will not be
9d40: 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 65 76   called again ev
9d50: 65 6e 20 69 66 20 69 74 0d 0a 20 20 20 20 20 20  en if it..      
9d60: 20 20 2f 2f 2f 20 72 65 74 75 72 6e 73 20 61 6e    /// returns an
9d70: 20 65 72 72 6f 72 2e 20 20 54 68 65 20 53 51 4c   error.  The SQL
9d80: 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 6f  ite core will no
9d90: 74 20 75 73 65 20 74 68 65 0d 0a 20 20 20 20 20  t use the..     
9da0: 20 20 20 2f 2f 2f 20 73 71 6c 69 74 65 33 5f 76     /// sqlite3_v
9db0: 74 61 62 5f 63 75 72 73 6f 72 20 61 67 61 69 6e  tab_cursor again
9dc0: 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
9dd0: 65 6e 20 63 6c 6f 73 65 64 2e 0d 0a 20 20 20 20  en closed...    
9de0: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
9df0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
9e00: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
9e10: 20 54 68 65 20 78 43 6c 6f 73 65 20 6d 65 74 68   The xClose meth
9e20: 6f 64 20 69 73 20 72 65 71 75 69 72 65 64 20 66  od is required f
9e30: 6f 72 20 65 76 65 72 79 20 76 69 72 74 75 61 6c  or every virtual
9e40: 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74   table implement
9e50: 61 74 69 6f 6e 2e 0d 0a 20 20 20 20 20 20 20 20  ation...        
9e60: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
9e70: 20 20 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61       /// </summa
9e80: 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ry>..        ///
9e90: 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 43   <param name="pC
9ea0: 75 72 73 6f 72 22 3e 0d 0a 20 20 20 20 20 20 20  ursor">..       
9eb0: 20 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76 65 20   /// The native 
9ec0: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73  pointer to the s
9ed0: 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
9ee0: 6f 72 20 64 65 72 69 76 65 64 20 73 74 72 75 63  or derived struc
9ef0: 74 75 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f  ture...        /
9f00: 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20  // </param>..   
9f10: 20 20 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72 6e       /// <return
9f20: 73 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  s>..        /// 
9f30: 41 20 73 74 61 6e 64 61 72 64 20 53 51 4c 69 74  A standard SQLit
9f40: 65 20 72 65 74 75 72 6e 20 63 6f 64 65 2e 0d 0a  e return code...
9f50: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72 65          /// </re
9f60: 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20  turns>..        
9f70: 53 51 4c 69 74 65 45 72 72 6f 72 43 6f 64 65 20  SQLiteErrorCode 
9f80: 78 43 6c 6f 73 65 28 0d 0a 20 20 20 20 20 20 20  xClose(..       
9f90: 20 20 20 20 20 49 6e 74 50 74 72 20 70 43 75 72       IntPtr pCur
9fa0: 73 6f 72 0d 0a 20 20 20 20 20 20 20 20 20 20 20  sor..           
9fb0: 20 29 3b 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f   );....        /
9fc0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
9fd0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
9fe0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
9ff0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
a000: 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 20 20  //////....      
a010: 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d    /// <summary>.
a020: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
a030: 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20  ra><code>..     
a040: 20 20 20 2f 2f 2f 20 69 6e 74 20 28 2a 78 46 69     /// int (*xFi
a050: 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f 76 74  lter)(sqlite3_vt
a060: 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20  ab_cursor*, int 
a070: 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68  idxNum, const ch
a080: 61 72 20 2a 69 64 78 53 74 72 2c 0d 0a 20 20 20  ar *idxStr,..   
a090: 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 20 20 20       ///        
a0a0: 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c         int argc,
a0b0: 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a   sqlite3_value *
a0c0: 2a 61 72 67 76 29 3b 0d 0a 20 20 20 20 20 20 20  *argv);..       
a0d0: 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61   /// </code></pa
a0e0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
a0f0: 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20   <para>..       
a100: 20 2f 2f 2f 20 54 68 69 73 20 6d 65 74 68 6f 64   /// This method
a110: 20 62 65 67 69 6e 73 20 61 20 73 65 61 72 63 68   begins a search
a120: 20 6f 66 20 61 20 76 69 72 74 75 61 6c 20 74 61   of a virtual ta
a130: 62 6c 65 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f  ble. ..        /
a140: 2f 2f 20 54 68 65 20 66 69 72 73 74 20 61 72 67  // The first arg
a150: 75 6d 65 6e 74 20 69 73 20 61 20 63 75 72 73 6f  ument is a curso
a160: 72 20 6f 70 65 6e 65 64 20 62 79 20 78 4f 70 65  r opened by xOpe
a170: 6e 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  n. ..        ///
a180: 20 54 68 65 20 6e 65 78 74 20 74 77 6f 20 61 72   The next two ar
a190: 67 75 6d 65 6e 74 73 20 64 65 66 69 6e 65 20 61  guments define a
a1a0: 20 70 61 72 74 69 63 75 6c 61 72 20 73 65 61 72   particular sear
a1b0: 63 68 20 69 6e 64 65 78 20 70 72 65 76 69 6f 75  ch index previou
a1c0: 73 6c 79 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  sly ..        //
a1d0: 2f 20 63 68 6f 73 65 6e 20 62 79 20 78 42 65 73  / chosen by xBes
a1e0: 74 49 6e 64 65 78 2e 20 54 68 65 20 73 70 65 63  tIndex. The spec
a1f0: 69 66 69 63 20 6d 65 61 6e 69 6e 67 73 20 6f 66  ific meanings of
a200: 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 53   idxNum and idxS
a210: 74 72 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  tr ..        ///
a220: 20 61 72 65 20 75 6e 69 6d 70 6f 72 74 61 6e 74   are unimportant
a230: 20 61 73 20 6c 6f 6e 67 20 61 73 20 78 46 69 6c   as long as xFil
a240: 74 65 72 20 61 6e 64 20 78 42 65 73 74 49 6e 64  ter and xBestInd
a250: 65 78 20 61 67 72 65 65 20 6f 6e 20 77 68 61 74  ex agree on what
a260: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74   ..        /// t
a270: 68 61 74 20 6d 65 61 6e 69 6e 67 20 69 73 2e 0d  hat meaning is..
a280: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
a290: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
a2a0: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
a2b0: 20 20 2f 2f 2f 20 54 68 65 20 78 42 65 73 74 49    /// The xBestI
a2c0: 6e 64 65 78 20 66 75 6e 63 74 69 6f 6e 20 6d 61  ndex function ma
a2d0: 79 20 68 61 76 65 20 72 65 71 75 65 73 74 65 64  y have requested
a2e0: 20 74 68 65 20 76 61 6c 75 65 73 20 6f 66 20 0d   the values of .
a2f0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 63 65 72  .        /// cer
a300: 74 61 69 6e 20 65 78 70 72 65 73 73 69 6f 6e 73  tain expressions
a310: 20 75 73 69 6e 67 20 74 68 65 20 61 43 6f 6e 73   using the aCons
a320: 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e 61 72  traintUsage[].ar
a330: 67 76 49 6e 64 65 78 20 76 61 6c 75 65 73 20 0d  gvIndex values .
a340: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6f 66 20  .        /// of 
a350: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  the sqlite3_inde
a360: 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65  x_info structure
a370: 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  . ..        /// 
a380: 54 68 6f 73 65 20 76 61 6c 75 65 73 20 61 72 65  Those values are
a390: 20 70 61 73 73 65 64 20 74 6f 20 78 46 69 6c 74   passed to xFilt
a3a0: 65 72 20 75 73 69 6e 67 20 74 68 65 20 61 72 67  er using the arg
a3b0: 63 20 61 6e 64 20 61 72 67 76 20 70 61 72 61 6d  c and argv param
a3c0: 65 74 65 72 73 2e 0d 0a 20 20 20 20 20 20 20 20  eters...        
a3d0: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
a3e0: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
a3f0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 49 66 20  .        /// If 
a400: 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
a410: 65 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 65 20 6f  e contains one o
a420: 72 20 6d 6f 72 65 20 72 6f 77 73 20 74 68 61 74  r more rows that
a430: 20 6d 61 74 63 68 20 74 68 65 0d 0a 20 20 20 20   match the..    
a440: 20 20 20 20 2f 2f 2f 20 73 65 61 72 63 68 20 63      /// search c
a450: 72 69 74 65 72 69 61 2c 20 74 68 65 6e 20 74 68  riteria, then th
a460: 65 20 63 75 72 73 6f 72 20 6d 75 73 74 20 62 65  e cursor must be
a470: 20 6c 65 66 74 20 70 6f 69 6e 74 20 61 74 20 74   left point at t
a480: 68 65 20 66 69 72 73 74 20 72 6f 77 2e 0d 0a 20  he first row... 
a490: 20 20 20 20 20 20 20 2f 2f 2f 20 53 75 62 73 65         /// Subse
a4a0: 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 78  quent calls to x
a4b0: 45 6f 66 20 6d 75 73 74 20 72 65 74 75 72 6e 20  Eof must return 
a4c0: 66 61 6c 73 65 20 28 7a 65 72 6f 29 2e 0d 0a 20  false (zero)... 
a4d0: 20 20 20 20 20 20 20 2f 2f 2f 20 49 66 20 74 68         /// If th
a4e0: 65 72 65 20 61 72 65 20 6e 6f 20 72 6f 77 73 20  ere are no rows 
a4f0: 6d 61 74 63 68 2c 20 74 68 65 6e 20 74 68 65 20  match, then the 
a500: 63 75 72 73 6f 72 20 6d 75 73 74 20 62 65 20 6c  cursor must be l
a510: 65 66 74 20 69 6e 20 61 20 73 74 61 74 65 20 0d  eft in a state .
a520: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 61  .        /// tha
a530: 74 20 77 69 6c 6c 20 63 61 75 73 65 20 74 68 65  t will cause the
a540: 20 78 45 6f 66 20 74 6f 20 72 65 74 75 72 6e 20   xEof to return 
a550: 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 2e  true (non-zero).
a560: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
a570: 65 20 53 51 4c 69 74 65 20 65 6e 67 69 6e 65 20  e SQLite engine 
a580: 77 69 6c 6c 20 75 73 65 0d 0a 20 20 20 20 20 20  will use..      
a590: 20 20 2f 2f 2f 20 74 68 65 20 78 43 6f 6c 75 6d    /// the xColum
a5a0: 6e 20 61 6e 64 20 78 52 6f 77 69 64 20 6d 65 74  n and xRowid met
a5b0: 68 6f 64 73 20 74 6f 20 61 63 63 65 73 73 20 74  hods to access t
a5c0: 68 61 74 20 72 6f 77 20 63 6f 6e 74 65 6e 74 2e  hat row content.
a5d0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
a5e0: 65 20 78 4e 65 78 74 20 6d 65 74 68 6f 64 20 77  e xNext method w
a5f0: 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20 61  ill be used to a
a600: 64 76 61 6e 63 65 20 74 6f 20 74 68 65 20 6e 65  dvance to the ne
a610: 78 74 20 72 6f 77 2e 0d 0a 20 20 20 20 20 20 20  xt row...       
a620: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
a630: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
a640: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
a650: 69 73 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 72  is method must r
a660: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
a670: 69 66 20 73 75 63 63 65 73 73 66 75 6c 2c 20 6f  if successful, o
a680: 72 20 61 6e 20 73 71 6c 69 74 65 20 0d 0a 20 20  r an sqlite ..  
a690: 20 20 20 20 20 20 2f 2f 2f 20 65 72 72 6f 72 20        /// error 
a6a0: 63 6f 64 65 20 69 66 20 61 6e 20 65 72 72 6f 72  code if an error
a6b0: 20 6f 63 63 75 72 73 2e 0d 0a 20 20 20 20 20 20   occurs...      
a6c0: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
a6d0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
a6e0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54  >..        /// T
a6f0: 68 65 20 78 46 69 6c 74 65 72 20 6d 65 74 68 6f  he xFilter metho
a700: 64 20 69 73 20 72 65 71 75 69 72 65 64 20 66 6f  d is required fo
a710: 72 20 65 76 65 72 79 20 76 69 72 74 75 61 6c 20  r every virtual 
a720: 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
a730: 74 69 6f 6e 2e 0d 0a 20 20 20 20 20 20 20 20 2f  tion...        /
a740: 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  // </para>..    
a750: 20 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72      /// </summar
a760: 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  y>..        /// 
a770: 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 43 75  <param name="pCu
a780: 72 73 6f 72 22 3e 0d 0a 20 20 20 20 20 20 20 20  rsor">..        
a790: 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76 65 20 70  /// The native p
a7a0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 71  ointer to the sq
a7b0: 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
a7c0: 72 20 64 65 72 69 76 65 64 20 73 74 72 75 63 74  r derived struct
a7d0: 75 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ure...        //
a7e0: 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20  / </param>..    
a7f0: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e      /// <param n
a800: 61 6d 65 3d 22 69 64 78 4e 75 6d 22 3e 0d 0a 20  ame="idxNum">.. 
a810: 20 20 20 20 20 20 20 2f 2f 2f 20 4e 75 6d 62 65         /// Numbe
a820: 72 20 75 73 65 64 20 74 6f 20 68 65 6c 70 20 69  r used to help i
a830: 64 65 6e 74 69 66 79 20 74 68 65 20 73 65 6c 65  dentify the sele
a840: 63 74 65 64 20 69 6e 64 65 78 2e 0d 0a 20 20 20  cted index...   
a850: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d       /// </param
a860: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
a870: 70 61 72 61 6d 20 6e 61 6d 65 3d 22 69 64 78 53  param name="idxS
a880: 74 72 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  tr">..        //
a890: 2f 20 54 68 65 20 6e 61 74 69 76 65 20 70 6f 69  / The native poi
a8a0: 6e 74 65 72 20 74 6f 20 74 68 65 20 55 54 46 2d  nter to the UTF-
a8b0: 38 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67  8 encoded string
a8c0: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0d   containing the.
a8d0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 74 72  .        /// str
a8e0: 69 6e 67 20 75 73 65 64 20 74 6f 20 68 65 6c 70  ing used to help
a8f0: 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 73 65   identify the se
a900: 6c 65 63 74 65 64 20 69 6e 64 65 78 2e 0d 0a 20  lected index... 
a910: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
a920: 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  am>..        ///
a930: 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 61 72   <param name="ar
a940: 67 63 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  gc">..        //
a950: 2f 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  / The number of 
a960: 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72 73 20  native pointers 
a970: 74 6f 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  to sqlite3_value
a980: 20 73 74 72 75 63 74 75 72 65 73 20 73 70 65 63   structures spec
a990: 69 66 69 65 64 0d 0a 20 20 20 20 20 20 20 20 2f  ified..        /
a9a0: 2f 2f 20 69 6e 20 3c 70 61 72 61 6d 72 65 66 20  // in <paramref 
a9b0: 6e 61 6d 65 3d 22 61 72 67 76 22 20 2f 3e 2e 0d  name="argv" />..
a9c0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
a9d0: 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f  aram>..        /
a9e0: 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22  // <param name="
a9f0: 61 72 67 76 22 3e 0d 0a 20 20 20 20 20 20 20 20  argv">..        
aa00: 2f 2f 2f 20 41 6e 20 61 72 72 61 79 20 6f 66 20  /// An array of 
aa10: 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72 73 20  native pointers 
aa20: 74 6f 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  to sqlite3_value
aa30: 20 73 74 72 75 63 74 75 72 65 73 20 63 6f 6e 74   structures cont
aa40: 61 69 6e 69 6e 67 0d 0a 20 20 20 20 20 20 20 20  aining..        
aa50: 2f 2f 2f 20 66 69 6c 74 65 72 69 6e 67 20 63 72  /// filtering cr
aa60: 69 74 65 72 69 61 20 66 6f 72 20 74 68 65 20 73  iteria for the s
aa70: 65 6c 65 63 74 65 64 20 69 6e 64 65 78 2e 0d 0a  elected index...
aa80: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
aa90: 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ram>..        //
aaa0: 2f 20 3c 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20  / <returns>..   
aab0: 20 20 20 20 20 2f 2f 2f 20 41 20 73 74 61 6e 64       /// A stand
aac0: 61 72 64 20 53 51 4c 69 74 65 20 72 65 74 75 72  ard SQLite retur
aad0: 6e 20 63 6f 64 65 2e 0d 0a 20 20 20 20 20 20 20  n code...       
aae0: 20 2f 2f 2f 20 3c 2f 72 65 74 75 72 6e 73 3e 0d   /// </returns>.
aaf0: 0a 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 45  .        SQLiteE
ab00: 72 72 6f 72 43 6f 64 65 20 78 46 69 6c 74 65 72  rrorCode xFilter
ab10: 28 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 49  (..            I
ab20: 6e 74 50 74 72 20 70 43 75 72 73 6f 72 2c 0d 0a  ntPtr pCursor,..
ab30: 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
ab40: 69 64 78 4e 75 6d 2c 0d 0a 20 20 20 20 20 20 20  idxNum,..       
ab50: 20 20 20 20 20 49 6e 74 50 74 72 20 69 64 78 53       IntPtr idxS
ab60: 74 72 2c 0d 0a 20 20 20 20 20 20 20 20 20 20 20  tr,..           
ab70: 20 69 6e 74 20 61 72 67 63 2c 0d 0a 20 20 20 20   int argc,..    
ab80: 20 20 20 20 20 20 20 20 49 6e 74 50 74 72 20 61          IntPtr a
ab90: 72 67 76 0d 0a 20 20 20 20 20 20 20 20 20 20 20  rgv..           
aba0: 20 29 3b 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f   );....        /
abb0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
abc0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
abd0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
abe0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
abf0: 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 20 20  //////....      
ac00: 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d    /// <summary>.
ac10: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
ac20: 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20  ra><code>..     
ac30: 20 20 20 2f 2f 2f 20 69 6e 74 20 28 2a 78 4e 65     /// int (*xNe
ac40: 78 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  xt)(sqlite3_vtab
ac50: 5f 63 75 72 73 6f 72 2a 29 3b 0d 0a 20 20 20 20  _cursor*);..    
ac60: 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c      /// </code><
ac70: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
ac80: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20  /// <para>..    
ac90: 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 4e 65 78      /// The xNex
aca0: 74 20 6d 65 74 68 6f 64 20 61 64 76 61 6e 63 65  t method advance
acb0: 73 20 61 20 76 69 72 74 75 61 6c 20 74 61 62 6c  s a virtual tabl
acc0: 65 20 63 75 72 73 6f 72 0d 0a 20 20 20 20 20 20  e cursor..      
acd0: 20 20 2f 2f 2f 20 74 6f 20 74 68 65 20 6e 65 78    /// to the nex
ace0: 74 20 72 6f 77 20 6f 66 20 61 20 72 65 73 75 6c  t row of a resul
acf0: 74 20 73 65 74 20 69 6e 69 74 69 61 74 65 64 20  t set initiated 
ad00: 62 79 20 78 46 69 6c 74 65 72 2e 20 0d 0a 20 20  by xFilter. ..  
ad10: 20 20 20 20 20 20 2f 2f 2f 20 49 66 20 74 68 65        /// If the
ad20: 20 63 75 72 73 6f 72 20 69 73 20 61 6c 72 65 61   cursor is alrea
ad30: 64 79 20 70 6f 69 6e 74 69 6e 67 20 61 74 20 74  dy pointing at t
ad40: 68 65 20 6c 61 73 74 20 72 6f 77 20 77 68 65 6e  he last row when
ad50: 20 74 68 69 73 20 0d 0a 20 20 20 20 20 20 20 20   this ..        
ad60: 2f 2f 2f 20 72 6f 75 74 69 6e 65 20 69 73 20 63  /// routine is c
ad70: 61 6c 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20  alled, then the 
ad80: 63 75 72 73 6f 72 20 6e 6f 20 6c 6f 6e 67 65 72  cursor no longer
ad90: 20 70 6f 69 6e 74 73 20 74 6f 20 76 61 6c 69 64   points to valid
ada0: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 64   ..        /// d
adb0: 61 74 61 20 61 6e 64 20 61 20 73 75 62 73 65 71  ata and a subseq
adc0: 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 74 68 65  uent call to the
add0: 20 78 45 6f 66 20 6d 65 74 68 6f 64 20 6d 75 73   xEof method mus
ade0: 74 20 72 65 74 75 72 6e 20 74 72 75 65 20 28 6e  t return true (n
adf0: 6f 6e 2d 7a 65 72 6f 29 2e 20 0d 0a 20 20 20 20  on-zero). ..    
ae00: 20 20 20 20 2f 2f 2f 20 49 66 20 74 68 65 20 63      /// If the c
ae10: 75 72 73 6f 72 20 69 73 20 73 75 63 63 65 73 73  ursor is success
ae20: 66 75 6c 6c 79 20 61 64 76 61 6e 63 65 64 20 74  fully advanced t
ae30: 6f 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66  o another row of
ae40: 20 63 6f 6e 74 65 6e 74 2c 20 74 68 65 6e 0d 0a   content, then..
ae50: 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 75 62 73          /// subs
ae60: 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
ae70: 78 45 6f 66 20 6d 75 73 74 20 72 65 74 75 72 6e  xEof must return
ae80: 20 66 61 6c 73 65 20 28 7a 65 72 6f 29 2e 0d 0a   false (zero)...
ae90: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
aea0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
aeb0: 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20   <para>..       
aec0: 20 2f 2f 2f 20 54 68 69 73 20 6d 65 74 68 6f 64   /// This method
aed0: 20 6d 75 73 74 20 72 65 74 75 72 6e 20 53 51 4c   must return SQL
aee0: 49 54 45 5f 4f 4b 20 69 66 20 73 75 63 63 65 73  ITE_OK if succes
aef0: 73 66 75 6c 2c 20 6f 72 20 61 6e 20 73 71 6c 69  sful, or an sqli
af00: 74 65 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  te ..        ///
af10: 20 65 72 72 6f 72 20 63 6f 64 65 20 69 66 20 61   error code if a
af20: 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0d  n error occurs..
af30: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
af40: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
af50: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
af60: 20 20 2f 2f 2f 20 54 68 65 20 78 4e 65 78 74 20    /// The xNext 
af70: 6d 65 74 68 6f 64 20 69 73 20 72 65 71 75 69 72  method is requir
af80: 65 64 20 66 6f 72 20 65 76 65 72 79 20 76 69 72  ed for every vir
af90: 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65  tual table imple
afa0: 6d 65 6e 74 61 74 69 6f 6e 2e 0d 0a 20 20 20 20  mentation...    
afb0: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
afc0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 73  .        /// </s
afd0: 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20  ummary>..       
afe0: 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65   /// <param name
aff0: 3d 22 70 43 75 72 73 6f 72 22 3e 0d 0a 20 20 20  ="pCursor">..   
b000: 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e 61 74       /// The nat
b010: 69 76 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  ive pointer to t
b020: 68 65 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  he sqlite3_vtab_
b030: 63 75 72 73 6f 72 20 64 65 72 69 76 65 64 20 73  cursor derived s
b040: 74 72 75 63 74 75 72 65 2e 0d 0a 20 20 20 20 20  tructure...     
b050: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d     /// </param>.
b060: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 72 65  .        /// <re
b070: 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20  turns>..        
b080: 2f 2f 2f 20 41 20 73 74 61 6e 64 61 72 64 20 53  /// A standard S
b090: 51 4c 69 74 65 20 72 65 74 75 72 6e 20 63 6f 64  QLite return cod
b0a0: 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e...        /// 
b0b0: 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20  </returns>..    
b0c0: 20 20 20 20 53 51 4c 69 74 65 45 72 72 6f 72 43      SQLiteErrorC
b0d0: 6f 64 65 20 78 4e 65 78 74 28 0d 0a 20 20 20 20  ode xNext(..    
b0e0: 20 20 20 20 20 20 20 20 49 6e 74 50 74 72 20 70          IntPtr p
b0f0: 43 75 72 73 6f 72 0d 0a 20 20 20 20 20 20 20 20  Cursor..        
b100: 20 20 20 20 29 3b 0d 0a 0d 0a 20 20 20 20 20 20      );....      
b110: 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f    //////////////
b120: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
b130: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
b140: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
b150: 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20  /////////....   
b160: 20 20 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72       /// <summar
b170: 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  y>..        /// 
b180: 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20  <para><code>..  
b190: 20 20 20 20 20 20 2f 2f 2f 20 69 6e 74 20 28 2a        /// int (*
b1a0: 78 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74  xEof)(sqlite3_vt
b1b0: 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0d 0a 20 20  ab_cursor*);..  
b1c0: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65        /// </code
b1d0: 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  ></para>..      
b1e0: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
b1f0: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 45        /// The xE
b200: 6f 66 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 72  of method must r
b210: 65 74 75 72 6e 20 66 61 6c 73 65 20 28 7a 65 72  eturn false (zer
b220: 6f 29 20 69 66 20 74 68 65 20 73 70 65 63 69 66  o) if the specif
b230: 69 65 64 20 63 75 72 73 6f 72 20 0d 0a 20 20 20  ied cursor ..   
b240: 20 20 20 20 20 2f 2f 2f 20 63 75 72 72 65 6e 74       /// current
b250: 6c 79 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 76  ly points to a v
b260: 61 6c 69 64 20 72 6f 77 20 6f 66 20 64 61 74 61  alid row of data
b270: 2c 20 6f 72 20 74 72 75 65 20 28 6e 6f 6e 2d 7a  , or true (non-z
b280: 65 72 6f 29 20 6f 74 68 65 72 77 69 73 65 2e 20  ero) otherwise. 
b290: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
b2a0: 69 73 20 6d 65 74 68 6f 64 20 69 73 20 63 61 6c  is method is cal
b2b0: 6c 65 64 20 62 79 20 74 68 65 20 53 51 4c 20 65  led by the SQL e
b2c0: 6e 67 69 6e 65 20 69 6d 6d 65 64 69 61 74 65 6c  ngine immediatel
b2d0: 79 20 61 66 74 65 72 20 65 61 63 68 20 0d 0a 20  y after each .. 
b2e0: 20 20 20 20 20 20 20 2f 2f 2f 20 78 46 69 6c 74         /// xFilt
b2f0: 65 72 20 61 6e 64 20 78 4e 65 78 74 20 69 6e 76  er and xNext inv
b300: 6f 63 61 74 69 6f 6e 2e 0d 0a 20 20 20 20 20 20  ocation...      
b310: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
b320: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
b330: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54  >..        /// T
b340: 68 65 20 78 45 6f 66 20 6d 65 74 68 6f 64 20 69  he xEof method i
b350: 73 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 65  s required for e
b360: 76 65 72 79 20 76 69 72 74 75 61 6c 20 74 61 62  very virtual tab
b370: 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
b380: 6e 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  n...        /// 
b390: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
b3a0: 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d   /// </summary>.
b3b0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
b3c0: 72 61 6d 20 6e 61 6d 65 3d 22 70 43 75 72 73 6f  ram name="pCurso
b3d0: 72 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  r">..        ///
b3e0: 20 54 68 65 20 6e 61 74 69 76 65 20 70 6f 69 6e   The native poin
b3f0: 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
b400: 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 64  e3_vtab_cursor d
b410: 65 72 69 76 65 64 20 73 74 72 75 63 74 75 72 65  erived structure
b420: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
b430: 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20  /param>..       
b440: 20 2f 2f 2f 20 3c 72 65 74 75 72 6e 73 3e 0d 0a   /// <returns>..
b450: 20 20 20 20 20 20 20 20 2f 2f 2f 20 4e 6f 6e 2d          /// Non-
b460: 7a 65 72 6f 20 69 66 20 6e 6f 20 6d 6f 72 65 20  zero if no more 
b470: 72 6f 77 73 20 61 72 65 20 61 76 61 69 6c 61 62  rows are availab
b480: 6c 65 3b 20 7a 65 72 6f 20 6f 74 68 65 72 77 69  le; zero otherwi
b490: 73 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  se...        ///
b4a0: 20 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20   </returns>..   
b4b0: 20 20 20 20 20 69 6e 74 20 78 45 6f 66 28 0d 0a       int xEof(..
b4c0: 20 20 20 20 20 20 20 20 20 20 20 20 49 6e 74 50              IntP
b4d0: 74 72 20 70 43 75 72 73 6f 72 0d 0a 20 20 20 20  tr pCursor..    
b4e0: 20 20 20 20 20 20 20 20 29 3b 0d 0a 0d 0a 20 20          );....  
b4f0: 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f        //////////
b500: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
b510: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
b520: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
b530: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d  /////////////...
b540: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 73 75  .        /// <su
b550: 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20  mmary>..        
b560: 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e  /// <para><code>
b570: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e  ..        /// in
b580: 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c  t (*xColumn)(sql
b590: 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
b5a0: 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  *, sqlite3_conte
b5b0: 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0d 0a 20 20  xt*, int N);..  
b5c0: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65        /// </code
b5d0: 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  ></para>..      
b5e0: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
b5f0: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 53 51        /// The SQ
b600: 4c 69 74 65 20 63 6f 72 65 20 69 6e 76 6f 6b 65  Lite core invoke
b610: 73 20 74 68 69 73 20 6d 65 74 68 6f 64 20 69 6e  s this method in
b620: 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74   order to find t
b630: 68 65 20 76 61 6c 75 65 20 66 6f 72 20 0d 0a 20  he value for .. 
b640: 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 20 4e         /// the N
b650: 2d 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  -th column of th
b660: 65 20 63 75 72 72 65 6e 74 20 72 6f 77 2e 20 4e  e current row. N
b670: 20 69 73 20 7a 65 72 6f 2d 62 61 73 65 64 20 73   is zero-based s
b680: 6f 20 74 68 65 20 66 69 72 73 74 20 63 6f 6c 75  o the first colu
b690: 6d 6e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  mn ..        ///
b6a0: 20 69 73 20 6e 75 6d 62 65 72 65 64 20 30 2e 20   is numbered 0. 
b6b0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
b6c0: 65 20 78 43 6f 6c 75 6d 6e 20 6d 65 74 68 6f 64  e xColumn method
b6d0: 20 6d 61 79 20 72 65 74 75 72 6e 20 69 74 73 20   may return its 
b6e0: 72 65 73 75 6c 74 20 62 61 63 6b 20 74 6f 20 53  result back to S
b6f0: 51 4c 69 74 65 20 75 73 69 6e 67 20 6f 6e 65 20  QLite using one 
b700: 6f 66 20 74 68 65 0d 0a 20 20 20 20 20 20 20 20  of the..        
b710: 2f 2f 2f 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  /// following in
b720: 74 65 72 66 61 63 65 3a 0d 0a 20 20 20 20 20 20  terface:..      
b730: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
b740: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
b750: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
b760: 21 5b 43 44 41 54 41 5b 3c 75 6c 3e 5d 5d 3e 0d  ![CDATA[<ul>]]>.
b770: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 21 5b  .        /// <![
b780: 43 44 41 54 41 5b 3c 6c 69 3e 5d 5d 3e 20 73 71  CDATA[<li>]]> sq
b790: 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
b7a0: 62 28 29 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  b()..        ///
b7b0: 20 3c 21 5b 43 44 41 54 41 5b 3c 2f 6c 69 3e 5d   <![CDATA[</li>]
b7c0: 5d 3e 3c 21 5b 43 44 41 54 41 5b 3c 6c 69 3e 5d  ]><![CDATA[<li>]
b7d0: 5d 3e 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ]> sqlite3_resul
b7e0: 74 5f 64 6f 75 62 6c 65 28 29 0d 0a 20 20 20 20  t_double()..    
b7f0: 20 20 20 20 2f 2f 2f 20 3c 21 5b 43 44 41 54 41      /// <![CDATA
b800: 5b 3c 2f 6c 69 3e 5d 5d 3e 3c 21 5b 43 44 41 54  [</li>]]><![CDAT
b810: 41 5b 3c 6c 69 3e 5d 5d 3e 20 73 71 6c 69 74 65  A[<li>]]> sqlite
b820: 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 0d 0a  3_result_int()..
b830: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 21 5b 43          /// <![C
b840: 44 41 54 41 5b 3c 2f 6c 69 3e 5d 5d 3e 3c 21 5b  DATA[</li>]]><![
b850: 43 44 41 54 41 5b 3c 6c 69 3e 5d 5d 3e 20 73 71  CDATA[<li>]]> sq
b860: 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
b870: 36 34 28 29 0d 0a 20 20 20 20 20 20 20 20 2f 2f  64()..        //
b880: 2f 20 3c 21 5b 43 44 41 54 41 5b 3c 2f 6c 69 3e  / <![CDATA[</li>
b890: 5d 5d 3e 3c 21 5b 43 44 41 54 41 5b 3c 6c 69 3e  ]]><![CDATA[<li>
b8a0: 5d 5d 3e 20 73 71 6c 69 74 65 33 5f 72 65 73 75  ]]> sqlite3_resu
b8b0: 6c 74 5f 6e 75 6c 6c 28 29 0d 0a 20 20 20 20 20  lt_null()..     
b8c0: 20 20 20 2f 2f 2f 20 3c 21 5b 43 44 41 54 41 5b     /// <![CDATA[
b8d0: 3c 2f 6c 69 3e 5d 5d 3e 3c 21 5b 43 44 41 54 41  </li>]]><![CDATA
b8e0: 5b 3c 6c 69 3e 5d 5d 3e 20 73 71 6c 69 74 65 33  [<li>]]> sqlite3
b8f0: 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 0d 0a  _result_text()..
b900: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 21 5b 43          /// <![C
b910: 44 41 54 41 5b 3c 2f 6c 69 3e 5d 5d 3e 3c 21 5b  DATA[</li>]]><![
b920: 43 44 41 54 41 5b 3c 6c 69 3e 5d 5d 3e 20 73 71  CDATA[<li>]]> sq
b930: 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
b940: 74 31 36 28 29 0d 0a 20 20 20 20 20 20 20 20 2f  t16()..        /
b950: 2f 2f 20 3c 21 5b 43 44 41 54 41 5b 3c 2f 6c 69  // <![CDATA[</li
b960: 3e 5d 5d 3e 3c 21 5b 43 44 41 54 41 5b 3c 6c 69  >]]><![CDATA[<li
b970: 3e 5d 5d 3e 20 73 71 6c 69 74 65 33 5f 72 65 73  >]]> sqlite3_res
b980: 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 0d 0a  ult_text16le()..
b990: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 21 5b 43          /// <![C
b9a0: 44 41 54 41 5b 3c 2f 6c 69 3e 5d 5d 3e 3c 21 5b  DATA[</li>]]><![
b9b0: 43 44 41 54 41 5b 3c 6c 69 3e 5d 5d 3e 20 73 71  CDATA[<li>]]> sq
b9c0: 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
b9d0: 74 31 36 62 65 28 29 0d 0a 20 20 20 20 20 20 20  t16be()..       
b9e0: 20 2f 2f 2f 20 3c 21 5b 43 44 41 54 41 5b 3c 2f   /// <![CDATA[</
b9f0: 6c 69 3e 5d 5d 3e 3c 21 5b 43 44 41 54 41 5b 3c  li>]]><![CDATA[<
ba00: 6c 69 3e 5d 5d 3e 20 73 71 6c 69 74 65 33 5f 72  li>]]> sqlite3_r
ba10: 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29  esult_zeroblob()
ba20: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 21  ..        /// <!
ba30: 5b 43 44 41 54 41 5b 3c 2f 6c 69 3e 5d 5d 3e 3c  [CDATA[</li>]]><
ba40: 21 5b 43 44 41 54 41 5b 3c 2f 75 6c 3e 5d 5d 3e  ![CDATA[</ul>]]>
ba50: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
ba60: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
ba70: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20  // <para>..     
ba80: 20 20 20 2f 2f 2f 20 49 66 20 74 68 65 20 78 43     /// If the xC
ba90: 6f 6c 75 6d 6e 20 6d 65 74 68 6f 64 20 69 6d 70  olumn method imp
baa0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6c 6c  lementation call
bab0: 73 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 66 75  s none of the fu
bac0: 6e 63 74 69 6f 6e 73 20 61 62 6f 76 65 2c 0d 0a  nctions above,..
bad0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 6e          /// then
bae0: 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
baf0: 65 20 63 6f 6c 75 6d 6e 20 64 65 66 61 75 6c 74  e column default
bb00: 73 20 74 6f 20 61 6e 20 53 51 4c 20 4e 55 4c 4c  s to an SQL NULL
bb10: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
bb20: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
bb30: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20  /// <para>..    
bb40: 20 20 20 20 2f 2f 2f 20 54 6f 20 72 61 69 73 65      /// To raise
bb50: 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 20 78   an error, the x
bb60: 43 6f 6c 75 6d 6e 20 6d 65 74 68 6f 64 20 73 68  Column method sh
bb70: 6f 75 6c 64 20 75 73 65 20 6f 6e 65 20 6f 66 20  ould use one of 
bb80: 74 68 65 20 72 65 73 75 6c 74 5f 74 65 78 74 28  the result_text(
bb90: 29 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ) ..        /// 
bba0: 6d 65 74 68 6f 64 73 20 74 6f 20 73 65 74 20 74  methods to set t
bbb0: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
bbc0: 20 74 65 78 74 2c 20 74 68 65 6e 20 72 65 74 75   text, then retu
bbd0: 72 6e 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  rn an appropriat
bbe0: 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 65  e..        /// e
bbf0: 72 72 6f 72 20 63 6f 64 65 2e 20 20 54 68 65 20  rror code.  The 
bc00: 78 43 6f 6c 75 6d 6e 20 6d 65 74 68 6f 64 20 6d  xColumn method m
bc10: 75 73 74 20 72 65 74 75 72 6e 20 53 51 4c 49 54  ust return SQLIT
bc20: 45 5f 4f 4b 20 6f 6e 20 73 75 63 63 65 73 73 2e  E_OK on success.
bc30: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
bc40: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
bc50: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20  // <para>..     
bc60: 20 20 20 2f 2f 2f 20 54 68 65 20 78 43 6f 6c 75     /// The xColu
bc70: 6d 6e 20 6d 65 74 68 6f 64 20 69 73 20 72 65 71  mn method is req
bc80: 75 69 72 65 64 20 66 6f 72 20 65 76 65 72 79 20  uired for every 
bc90: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d  virtual table im
bca0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0d 0a 20  plementation... 
bcb0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
bcc0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
bcd0: 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20  </summary>..    
bce0: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e      /// <param n
bcf0: 61 6d 65 3d 22 70 43 75 72 73 6f 72 22 3e 0d 0a  ame="pCursor">..
bd00: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20          /// The 
bd10: 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72 20 74  native pointer t
bd20: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 74  o the sqlite3_vt
bd30: 61 62 5f 63 75 72 73 6f 72 20 64 65 72 69 76 65  ab_cursor derive
bd40: 64 20 73 74 72 75 63 74 75 72 65 2e 0d 0a 20 20  d structure...  
bd50: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61        /// </para
bd60: 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  m>..        /// 
bd70: 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 43 6f  <param name="pCo
bd80: 6e 74 65 78 74 22 3e 0d 0a 20 20 20 20 20 20 20  ntext">..       
bd90: 20 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76 65 20   /// The native 
bda0: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73  pointer to the s
bdb0: 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73  qlite3_context s
bdc0: 74 72 75 63 74 75 72 65 20 74 6f 20 62 65 20 75  tructure to be u
bdd0: 73 65 64 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  sed..        ///
bde0: 20 66 6f 72 20 72 65 74 75 72 6e 69 6e 67 20 74   for returning t
bdf0: 68 65 20 73 70 65 63 69 66 69 65 64 20 63 6f 6c  he specified col
be00: 75 6d 6e 20 76 61 6c 75 65 20 74 6f 20 74 68 65  umn value to the
be10: 20 53 51 4c 69 74 65 20 63 6f 72 65 0d 0a 20 20   SQLite core..  
be20: 20 20 20 20 20 20 2f 2f 2f 20 6c 69 62 72 61 72        /// librar
be30: 79 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  y...        /// 
be40: 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20  </param>..      
be50: 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d    /// <param nam
be60: 65 3d 22 69 6e 64 65 78 22 3e 0d 0a 20 20 20 20  e="index">..    
be70: 20 20 20 20 2f 2f 2f 20 54 68 65 20 7a 65 72 6f      /// The zero
be80: 2d 62 61 73 65 64 20 69 6e 64 65 78 20 63 6f 72  -based index cor
be90: 72 65 73 70 6f 6e 64 69 6e 67 20 74 6f 20 74 68  responding to th
bea0: 65 20 63 6f 6c 75 6d 6e 20 63 6f 6e 74 61 69 6e  e column contain
beb0: 69 6e 67 20 74 68 65 0d 0a 20 20 20 20 20 20 20  ing the..       
bec0: 20 2f 2f 2f 20 76 61 6c 75 65 20 74 6f 20 62 65   /// value to be
bed0: 20 72 65 74 75 72 6e 65 64 2e 0d 0a 20 20 20 20   returned...    
bee0: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e      /// </param>
bef0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 72  ..        /// <r
bf00: 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20  eturns>..       
bf10: 20 2f 2f 2f 20 41 20 73 74 61 6e 64 61 72 64 20   /// A standard 
bf20: 53 51 4c 69 74 65 20 72 65 74 75 72 6e 20 63 6f  SQLite return co
bf30: 64 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  de...        ///
bf40: 20 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20   </returns>..   
bf50: 20 20 20 20 20 53 51 4c 69 74 65 45 72 72 6f 72       SQLiteError
bf60: 43 6f 64 65 20 78 43 6f 6c 75 6d 6e 28 0d 0a 20  Code xColumn(.. 
bf70: 20 20 20 20 20 20 20 20 20 20 20 49 6e 74 50 74             IntPt
bf80: 72 20 70 43 75 72 73 6f 72 2c 0d 0a 20 20 20 20  r pCursor,..    
bf90: 20 20 20 20 20 20 20 20 49 6e 74 50 74 72 20 70          IntPtr p
bfa0: 43 6f 6e 74 65 78 74 2c 0d 0a 20 20 20 20 20 20  Context,..      
bfb0: 20 20 20 20 20 20 69 6e 74 20 69 6e 64 65 78 0d        int index.
bfc0: 0a 20 20 20 20 20 20 20 20 20 20 20 20 29 3b 0d  .            );.
bfd0: 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 2f 2f  ...        /////
bfe0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
bff0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
c000: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
c010: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
c020: 2f 2f 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f  //....        //
c030: 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20  / <summary>..   
c040: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c       /// <para><
c050: 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f  code>..        /
c060: 2f 2f 20 69 6e 74 20 28 2a 78 52 6f 77 69 64 29  // int (*xRowid)
c070: 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
c080: 72 73 6f 72 20 2a 70 43 75 72 2c 20 73 71 6c 69  rsor *pCur, sqli
c090: 74 65 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69 64  te_int64 *pRowid
c0a0: 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  );..        /// 
c0b0: 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a  </code></para>..
c0c0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
c0d0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
c0e0: 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76  A successful inv
c0f0: 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 69 73 20  ocation of this 
c100: 6d 65 74 68 6f 64 20 77 69 6c 6c 20 63 61 75 73  method will caus
c110: 65 20 2a 70 52 6f 77 69 64 20 74 6f 20 62 65 0d  e *pRowid to be.
c120: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 66 69 6c  .        /// fil
c130: 6c 65 64 20 77 69 74 68 20 74 68 65 20 72 6f 77  led with the row
c140: 69 64 20 6f 66 20 72 6f 77 20 74 68 61 74 20 74  id of row that t
c150: 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  he..        /// 
c160: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 63 75  virtual table cu
c170: 72 73 6f 72 20 70 43 75 72 20 69 73 20 63 75 72  rsor pCur is cur
c180: 72 65 6e 74 6c 79 20 70 6f 69 6e 74 69 6e 67 20  rently pointing 
c190: 61 74 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  at...        ///
c1a0: 20 54 68 69 73 20 6d 65 74 68 6f 64 20 72 65 74   This method ret
c1b0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 20 6f  urns SQLITE_OK o
c1c0: 6e 20 73 75 63 63 65 73 73 2e 0d 0a 20 20 20 20  n success...    
c1d0: 20 20 20 20 2f 2f 2f 20 49 74 20 72 65 74 75 72      /// It retur
c1e0: 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  ns an appropriat
c1f0: 65 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 6e 20  e error code on 
c200: 66 61 69 6c 75 72 65 2e 0d 0a 20 20 20 20 20 20  failure...      
c210: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
c220: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
c230: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54  >..        /// T
c240: 68 65 20 78 52 6f 77 69 64 20 6d 65 74 68 6f 64  he xRowid method
c250: 20 69 73 20 72 65 71 75 69 72 65 64 20 66 6f 72   is required for
c260: 20 65 76 65 72 79 20 76 69 72 74 75 61 6c 20 74   every virtual t
c270: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
c280: 69 6f 6e 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ion...        //
c290: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  / </para>..     
c2a0: 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79     /// </summary
c2b0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
c2c0: 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 43 75 72  param name="pCur
c2d0: 73 6f 72 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f  sor">..        /
c2e0: 2f 2f 20 54 68 65 20 6e 61 74 69 76 65 20 70 6f  // The native po
c2f0: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  inter to the sql
c300: 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
c310: 20 64 65 72 69 76 65 64 20 73 74 72 75 63 74 75   derived structu
c320: 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  re...        ///
c330: 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20   </param>..     
c340: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61     /// <param na
c350: 6d 65 3d 22 72 6f 77 49 64 22 3e 0d 0a 20 20 20  me="rowId">..   
c360: 20 20 20 20 20 2f 2f 2f 20 55 70 6f 6e 20 73 75       /// Upon su
c370: 63 63 65 73 73 2c 20 74 68 69 73 20 70 61 72 61  ccess, this para
c380: 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 6d 6f  meter must be mo
c390: 64 69 66 69 65 64 20 74 6f 20 63 6f 6e 74 61 69  dified to contai
c3a0: 6e 20 74 68 65 20 75 6e 69 71 75 65 0d 0a 20 20  n the unique..  
c3b0: 20 20 20 20 20 20 2f 2f 2f 20 69 6e 74 65 67 65        /// intege
c3c0: 72 20 72 6f 77 20 69 64 65 6e 74 69 66 69 65 72  r row identifier
c3d0: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
c3e0: 20 72 6f 77 20 66 6f 72 20 74 68 65 20 73 70 65   row for the spe
c3f0: 63 69 66 69 65 64 20 63 75 72 73 6f 72 2e 0d 0a  cified cursor...
c400: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
c410: 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ram>..        //
c420: 2f 20 3c 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20  / <returns>..   
c430: 20 20 20 20 20 2f 2f 2f 20 41 20 73 74 61 6e 64       /// A stand
c440: 61 72 64 20 53 51 4c 69 74 65 20 72 65 74 75 72  ard SQLite retur
c450: 6e 20 63 6f 64 65 2e 0d 0a 20 20 20 20 20 20 20  n code...       
c460: 20 2f 2f 2f 20 3c 2f 72 65 74 75 72 6e 73 3e 0d   /// </returns>.
c470: 0a 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 45  .        SQLiteE
c480: 72 72 6f 72 43 6f 64 65 20 78 52 6f 77 49 64 28  rrorCode xRowId(
c490: 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 49 6e  ..            In
c4a0: 74 50 74 72 20 70 43 75 72 73 6f 72 2c 0d 0a 20  tPtr pCursor,.. 
c4b0: 20 20 20 20 20 20 20 20 20 20 20 72 65 66 20 6c             ref l
c4c0: 6f 6e 67 20 72 6f 77 49 64 0d 0a 20 20 20 20 20  ong rowId..     
c4d0: 20 20 20 20 20 20 20 29 3b 0d 0a 0d 0a 20 20 20         );....   
c4e0: 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f       ///////////
c4f0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
c500: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
c510: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
c520: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a  ////////////....
c530: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 73 75 6d          /// <sum
c540: 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f  mary>..        /
c550: 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d  // <para><code>.
c560: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e 74  .        /// int
c570: 20 28 2a 78 55 70 64 61 74 65 29 28 0d 0a 20 20   (*xUpdate)(..  
c580: 20 20 20 20 20 20 2f 2f 2f 20 20 20 73 71 6c 69        ///   sqli
c590: 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c  te3_vtab *pVTab,
c5a0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20  ..        ///   
c5b0: 69 6e 74 20 61 72 67 63 2c 0d 0a 20 20 20 20 20  int argc,..     
c5c0: 20 20 20 2f 2f 2f 20 20 20 73 71 6c 69 74 65 33     ///   sqlite3
c5d0: 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 2c 0d 0a  _value **argv,..
c5e0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 73 71          ///   sq
c5f0: 6c 69 74 65 5f 69 6e 74 36 34 20 2a 70 52 6f 77  lite_int64 *pRow
c600: 69 64 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  id..        /// 
c610: 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  );..        /// 
c620: 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a  </code></para>..
c630: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
c640: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
c650: 41 6c 6c 20 63 68 61 6e 67 65 73 20 74 6f 20 61  All changes to a
c660: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61   virtual table a
c670: 72 65 20 6d 61 64 65 20 75 73 69 6e 67 20 74 68  re made using th
c680: 65 20 78 55 70 64 61 74 65 20 6d 65 74 68 6f 64  e xUpdate method
c690: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54  ...        /// T
c6a0: 68 69 73 20 6f 6e 65 20 6d 65 74 68 6f 64 20 63  his one method c
c6b0: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6e  an be used to in
c6c0: 73 65 72 74 2c 20 64 65 6c 65 74 65 2c 20 6f 72  sert, delete, or
c6d0: 20 75 70 64 61 74 65 2e 0d 0a 20 20 20 20 20 20   update...      
c6e0: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
c6f0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
c700: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54  >..        /// T
c710: 68 65 20 61 72 67 63 20 70 61 72 61 6d 65 74 65  he argc paramete
c720: 72 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  r specifies the 
c730: 6e 75 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65  number of entrie
c740: 73 20 69 6e 20 74 68 65 20 61 72 67 76 20 61 72  s in the argv ar
c750: 72 61 79 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f  ray. ..        /
c760: 2f 2f 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20  // The value of 
c770: 61 72 67 63 20 77 69 6c 6c 20 62 65 20 31 20 66  argc will be 1 f
c780: 6f 72 20 61 20 70 75 72 65 20 64 65 6c 65 74 65  or a pure delete
c790: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 72 20 4e 2b   operation or N+
c7a0: 32 20 66 6f 72 20 61 6e 20 69 6e 73 65 72 74 0d  2 for an insert.
c7b0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6f 72 20  .        /// or 
c7c0: 72 65 70 6c 61 63 65 20 6f 72 20 75 70 64 61 74  replace or updat
c7d0: 65 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  e where N is the
c7e0: 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
c7f0: 6e 73 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2e  ns in the table.
c800: 20 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20    ..        /// 
c810: 49 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  In the previous 
c820: 73 65 6e 74 65 6e 63 65 2c 20 4e 20 69 6e 63 6c  sentence, N incl
c830: 75 64 65 73 20 61 6e 79 20 68 69 64 64 65 6e 20  udes any hidden 
c840: 63 6f 6c 75 6d 6e 73 2e 0d 0a 20 20 20 20 20 20  columns...      
c850: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
c860: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
c870: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 45  >..        /// E
c880: 76 65 72 79 20 61 72 67 76 20 65 6e 74 72 79 20  very argv entry 
c890: 77 69 6c 6c 20 68 61 76 65 20 61 20 6e 6f 6e 2d  will have a non-
c8a0: 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 43 20  NULL value in C 
c8b0: 62 75 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  but may contain 
c8c0: 74 68 65 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  the ..        //
c8d0: 2f 20 53 51 4c 20 76 61 6c 75 65 20 4e 55 4c 4c  / SQL value NULL
c8e0: 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
c8f0: 73 2c 20 69 74 20 69 73 20 61 6c 77 61 79 73 20  s, it is always 
c900: 74 72 75 65 20 74 68 61 74 0d 0a 20 20 20 20 20  true that..     
c910: 20 20 20 2f 2f 2f 20 3c 21 5b 43 44 41 54 41 5b     /// <![CDATA[
c920: 3c 74 74 3e 5d 5d 3e 61 72 67 76 5b 69 5d 21 3d  <tt>]]>argv[i]!=
c930: 30 3c 21 5b 43 44 41 54 41 5b 3c 2f 74 74 3e 5d  0<![CDATA[</tt>]
c940: 5d 3e 20 66 6f 72 20 3c 21 5b 43 44 41 54 41 5b  ]> for <![CDATA[
c950: 3c 62 3e 5d 5d 3e 69 3c 21 5b 43 44 41 54 41 5b  <b>]]>i<![CDATA[
c960: 3c 2f 62 3e 5d 5d 3e 20 62 65 74 77 65 65 6e 20  </b>]]> between 
c970: 30 20 61 6e 64 20 3c 21 5b 43 44 41 54 41 5b 3c  0 and <![CDATA[<
c980: 74 74 3e 5d 5d 3e 61 72 67 63 2d 31 3c 21 5b 43  tt>]]>argc-1<![C
c990: 44 41 54 41 5b 3c 2f 74 74 3e 5d 5d 3e 2e 0d 0a  DATA[</tt>]]>...
c9a0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 48 6f 77 65          /// Howe
c9b0: 76 65 72 2c 20 69 74 20 6d 69 67 68 74 20 62 65  ver, it might be
c9c0: 20 74 68 65 20 63 61 73 65 20 74 68 61 74 0d 0a   the case that..
c9d0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 21 5b 43          /// <![C
c9e0: 44 41 54 41 5b 3c 74 74 3e 5d 5d 3e 73 71 6c 69  DATA[<tt>]]>sqli
c9f0: 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 61  te3_value_type(a
ca00: 72 67 76 5b 69 5d 29 3d 3d 53 51 4c 49 54 45 5f  rgv[i])==SQLITE_
ca10: 4e 55 4c 4c 3c 21 5b 43 44 41 54 41 5b 3c 2f 74  NULL<![CDATA[</t
ca20: 74 3e 5d 5d 3e 2e 0d 0a 20 20 20 20 20 20 20 20  t>]]>...        
ca30: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
ca40: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
ca50: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65  .        /// The
ca60: 20 61 72 67 76 5b 30 5d 20 70 61 72 61 6d 65 74   argv[0] paramet
ca70: 65 72 20 69 73 20 74 68 65 20 72 6f 77 69 64 20  er is the rowid 
ca80: 6f 66 20 61 20 72 6f 77 20 69 6e 20 74 68 65 20  of a row in the 
ca90: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 0d 0a  virtual table ..
caa0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 6f 20 62          /// to b
cab0: 65 20 64 65 6c 65 74 65 64 2e 20 49 66 20 61 72  e deleted. If ar
cac0: 67 76 5b 30 5d 20 69 73 20 61 6e 20 53 51 4c 20  gv[0] is an SQL 
cad0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 64 65  NULL, then no de
cae0: 6c 65 74 69 6f 6e 20 6f 63 63 75 72 73 2e 0d 0a  letion occurs...
caf0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
cb00: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
cb10: 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20   <para>..       
cb20: 20 2f 2f 2f 20 54 68 65 20 61 72 67 76 5b 31 5d   /// The argv[1]
cb30: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
cb40: 65 20 72 6f 77 69 64 20 6f 66 20 61 20 6e 65 77  e rowid of a new
cb50: 20 72 6f 77 20 74 6f 20 62 65 20 69 6e 73 65 72   row to be inser
cb60: 74 65 64 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ted ..        //
cb70: 2f 20 69 6e 74 6f 20 74 68 65 20 76 69 72 74 75  / into the virtu
cb80: 61 6c 20 74 61 62 6c 65 2e 20 49 66 20 61 72 67  al table. If arg
cb90: 76 5b 31 5d 20 69 73 20 61 6e 20 53 51 4c 20 4e  v[1] is an SQL N
cba0: 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 69 6d  ULL, then the im
cbb0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 0d 0a 20  plementation .. 
cbc0: 20 20 20 20 20 20 20 2f 2f 2f 20 6d 75 73 74 20         /// must 
cbd0: 63 68 6f 6f 73 65 20 61 20 72 6f 77 69 64 20 66  choose a rowid f
cbe0: 6f 72 20 74 68 65 20 6e 65 77 6c 79 20 69 6e 73  or the newly ins
cbf0: 65 72 74 65 64 20 72 6f 77 2e 20 53 75 62 73 65  erted row. Subse
cc00: 71 75 65 6e 74 20 61 72 67 76 5b 5d 20 0d 0a 20  quent argv[] .. 
cc10: 20 20 20 20 20 20 20 2f 2f 2f 20 65 6e 74 72 69         /// entri
cc20: 65 73 20 63 6f 6e 74 61 69 6e 20 76 61 6c 75 65  es contain value
cc30: 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
cc40: 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20   of the virtual 
cc50: 74 61 62 6c 65 2c 20 69 6e 20 74 68 65 20 0d 0a  table, in the ..
cc60: 20 20 20 20 20 20 20 20 2f 2f 2f 20 6f 72 64 65          /// orde
cc70: 72 20 74 68 61 74 20 74 68 65 20 63 6f 6c 75 6d  r that the colum
cc80: 6e 73 20 77 65 72 65 20 64 65 63 6c 61 72 65 64  ns were declared
cc90: 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  . The number of 
cca0: 63 6f 6c 75 6d 6e 73 20 77 69 6c 6c 0d 0a 20 20  columns will..  
ccb0: 20 20 20 20 20 20 2f 2f 2f 20 6d 61 74 63 68 20        /// match 
ccc0: 74 68 65 20 74 61 62 6c 65 20 64 65 63 6c 61 72  the table declar
ccd0: 61 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20 78  ation that the x
cce0: 43 6f 6e 6e 65 63 74 20 6f 72 20 78 43 72 65 61  Connect or xCrea
ccf0: 74 65 20 6d 65 74 68 6f 64 20 6d 61 64 65 20 0d  te method made .
cd00: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 75 73 69  .        /// usi
cd10: 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 64  ng the sqlite3_d
cd20: 65 63 6c 61 72 65 5f 76 74 61 62 28 29 20 63 61  eclare_vtab() ca
cd30: 6c 6c 2e 20 20 41 6c 6c 20 68 69 64 64 65 6e 20  ll.  All hidden 
cd40: 63 6f 6c 75 6d 6e 73 20 61 72 65 20 69 6e 63 6c  columns are incl
cd50: 75 64 65 64 2e 0d 0a 20 20 20 20 20 20 20 20 2f  uded...        /
cd60: 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  // </para>..    
cd70: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a      /// <para>..
cd80: 20 20 20 20 20 20 20 20 2f 2f 2f 20 57 68 65 6e          /// When
cd90: 20 64 6f 69 6e 67 20 61 6e 20 69 6e 73 65 72 74   doing an insert
cda0: 20 77 69 74 68 6f 75 74 20 61 20 72 6f 77 69 64   without a rowid
cdb0: 20 28 61 72 67 63 3e 31 2c 20 61 72 67 76 5b 31   (argc>1, argv[1
cdc0: 5d 20 69 73 20 61 6e 20 53 51 4c 20 4e 55 4c 4c  ] is an SQL NULL
cdd0: 29 2c 20 74 68 65 20 0d 0a 20 20 20 20 20 20 20  ), the ..       
cde0: 20 2f 2f 2f 20 69 6d 70 6c 65 6d 65 6e 74 61 74   /// implementat
cdf0: 69 6f 6e 20 6d 75 73 74 20 73 65 74 20 2a 70 52  ion must set *pR
ce00: 6f 77 69 64 20 74 6f 20 74 68 65 20 72 6f 77 69  owid to the rowi
ce10: 64 20 6f 66 20 74 68 65 20 6e 65 77 6c 79 20 69  d of the newly i
ce20: 6e 73 65 72 74 65 64 20 72 6f 77 3b 20 0d 0a 20  nserted row; .. 
ce30: 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 69 73 20         /// this 
ce40: 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20  will become the 
ce50: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
ce60: 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6c 61  y the sqlite3_la
ce70: 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
ce80: 29 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 66  )..        /// f
ce90: 75 6e 63 74 69 6f 6e 2e 20 53 65 74 74 69 6e 67  unction. Setting
cea0: 20 74 68 69 73 20 76 61 6c 75 65 20 69 6e 20 61   this value in a
ceb0: 6c 6c 20 74 68 65 20 6f 74 68 65 72 20 63 61 73  ll the other cas
cec0: 65 73 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  es is a harmless
ced0: 20 6e 6f 2d 6f 70 3b 0d 0a 20 20 20 20 20 20 20   no-op;..       
cee0: 20 2f 2f 2f 20 74 68 65 20 53 51 4c 69 74 65 20   /// the SQLite 
cef0: 65 6e 67 69 6e 65 20 69 67 6e 6f 72 65 73 20 74  engine ignores t
cf00: 68 65 20 2a 70 52 6f 77 69 64 20 72 65 74 75 72  he *pRowid retur
cf10: 6e 20 76 61 6c 75 65 20 69 66 20 61 72 67 63 3d  n value if argc=
cf20: 3d 31 20 6f 72 20 0d 0a 20 20 20 20 20 20 20 20  =1 or ..        
cf30: 2f 2f 2f 20 61 72 67 76 5b 31 5d 20 69 73 20 6e  /// argv[1] is n
cf40: 6f 74 20 61 6e 20 53 51 4c 20 4e 55 4c 4c 2e 0d  ot an SQL NULL..
cf50: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
cf60: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
cf70: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
cf80: 20 20 2f 2f 2f 20 45 61 63 68 20 63 61 6c 6c 20    /// Each call 
cf90: 74 6f 20 78 55 70 64 61 74 65 20 77 69 6c 6c 20  to xUpdate will 
cfa0: 66 61 6c 6c 20 69 6e 74 6f 20 6f 6e 65 20 6f 66  fall into one of
cfb0: 20 63 61 73 65 73 20 73 68 6f 77 6e 20 62 65 6c   cases shown bel
cfc0: 6f 77 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ow...        ///
cfd0: 20 4e 6f 74 20 74 68 61 74 20 72 65 66 65 72 65   Not that refere
cfe0: 6e 63 65 73 20 74 6f 20 3c 21 5b 43 44 41 54 41  nces to <![CDATA
cff0: 5b 3c 62 3e 5d 5d 3e 61 72 67 76 5b 69 5d 3c 21  [<b>]]>argv[i]<!
d000: 5b 43 44 41 54 41 5b 3c 2f 62 3e 5d 5d 3e 20 6d  [CDATA[</b>]]> m
d010: 65 61 6e 20 74 68 65 20 53 51 4c 20 76 61 6c 75  ean the SQL valu
d020: 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 68  e..        /// h
d030: 65 6c 64 20 77 69 74 68 69 6e 20 74 68 65 20 61  eld within the a
d040: 72 67 76 5b 69 5d 20 6f 62 6a 65 63 74 2c 20 6e  rgv[i] object, n
d050: 6f 74 20 74 68 65 20 61 72 67 76 5b 69 5d 0d 0a  ot the argv[i]..
d060: 20 20 20 20 20 20 20 20 2f 2f 2f 20 6f 62 6a 65          /// obje
d070: 63 74 20 69 74 73 65 6c 66 2e 0d 0a 20 20 20 20  ct itself...    
d080: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
d090: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
d0a0: 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20  ra><code>..     
d0b0: 20 20 20 2f 2f 2f 20 3c 21 5b 43 44 41 54 41 5b     /// <![CDATA[
d0c0: 3c 64 6c 3e 5d 5d 3e 0d 0a 20 20 20 20 20 20 20  <dl>]]>..       
d0d0: 20 2f 2f 2f 20 3c 21 5b 43 44 41 54 41 5b 3c 64   /// <![CDATA[<d
d0e0: 74 3e 5d 5d 3e 3c 21 5b 43 44 41 54 41 5b 3c 62  t>]]><![CDATA[<b
d0f0: 3e 5d 5d 3e 61 72 67 63 20 3d 20 31 3c 21 5b 43  >]]>argc = 1<![C
d100: 44 41 54 41 5b 3c 2f 62 3e 5d 5d 3e 0d 0a 20 20  DATA[</b>]]>..  
d110: 20 20 20 20 20 20 2f 2f 2f 20 3c 21 5b 43 44 41        /// <![CDA
d120: 54 41 5b 3c 2f 64 74 3e 5d 5d 3e 3c 21 5b 43 44  TA[</dt>]]><![CD
d130: 41 54 41 5b 3c 64 64 3e 5d 5d 3e 54 68 65 20 73  ATA[<dd>]]>The s
d140: 69 6e 67 6c 65 20 72 6f 77 20 77 69 74 68 20 72  ingle row with r
d150: 6f 77 69 64 20 65 71 75 61 6c 20 74 6f 20 61 72  owid equal to ar
d160: 67 76 5b 30 5d 20 69 73 20 64 65 6c 65 74 65 64  gv[0] is deleted
d170: 2e 20 4e 6f 20 69 6e 73 65 72 74 20 6f 63 63 75  . No insert occu
d180: 72 73 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  rs...        ///
d190: 20 3c 21 5b 43 44 41 54 41 5b 3c 2f 64 64 3e 5d   <![CDATA[</dd>]
d1a0: 5d 3e 3c 21 5b 43 44 41 54 41 5b 3c 64 74 3e 5d  ]><![CDATA[<dt>]
d1b0: 5d 3e 3c 21 5b 43 44 41 54 41 5b 3c 62 3e 5d 5d  ]><![CDATA[<b>]]
d1c0: 3e 61 72 67 63 20 26 67 74 3b 20 31 20 3c 21 5b  >argc &gt; 1 <![
d1d0: 43 44 41 54 41 5b 3c 62 72 3e 5d 5d 3e 20 61 72  CDATA[<br>]]> ar
d1e0: 67 76 5b 30 5d 20 3d 20 4e 55 4c 4c 3c 21 5b 43  gv[0] = NULL<![C
d1f0: 44 41 54 41 5b 3c 2f 62 3e 5d 5d 3e 0d 0a 20 20  DATA[</b>]]>..  
d200: 20 20 20 20 20 20 2f 2f 2f 20 3c 21 5b 43 44 41        /// <![CDA
d210: 54 41 5b 3c 2f 64 74 3e 5d 5d 3e 3c 21 5b 43 44  TA[</dt>]]><![CD
d220: 41 54 41 5b 3c 64 64 3e 5d 5d 3e 41 20 6e 65 77  ATA[<dd>]]>A new
d230: 20 72 6f 77 20 69 73 20 69 6e 73 65 72 74 65 64   row is inserted
d240: 20 77 69 74 68 20 61 20 72 6f 77 69 64 20 61 72   with a rowid ar
d250: 67 76 5b 31 5d 20 61 6e 64 20 63 6f 6c 75 6d 6e  gv[1] and column
d260: 20 76 61 6c 75 65 73 20 69 6e 0d 0a 20 20 20 20   values in..    
d270: 20 20 20 20 2f 2f 2f 20 20 20 20 20 20 20 20 61      ///        a
d280: 72 67 76 5b 32 5d 20 61 6e 64 20 66 6f 6c 6c 6f  rgv[2] and follo
d290: 77 69 6e 67 2e 20 20 49 66 20 61 72 67 76 5b 31  wing.  If argv[1
d2a0: 5d 20 69 73 20 61 6e 20 53 51 4c 20 4e 55 4c 4c  ] is an SQL NULL
d2b0: 2c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20  ,..        ///  
d2c0: 20 20 20 20 20 20 74 68 65 20 61 20 6e 65 77 20        the a new 
d2d0: 75 6e 69 71 75 65 20 72 6f 77 69 64 20 69 73 20  unique rowid is 
d2e0: 67 65 6e 65 72 61 74 65 64 20 61 75 74 6f 6d 61  generated automa
d2f0: 74 69 63 61 6c 6c 79 2e 0d 0a 20 20 20 20 20 20  tically...      
d300: 20 20 2f 2f 2f 20 3c 21 5b 43 44 41 54 41 5b 3c    /// <![CDATA[<
d310: 2f 64 64 3e 5d 5d 3e 3c 21 5b 43 44 41 54 41 5b  /dd>]]><![CDATA[
d320: 3c 64 74 3e 5d 5d 3e 3c 21 5b 43 44 41 54 41 5b  <dt>]]><![CDATA[
d330: 3c 62 3e 5d 5d 3e 61 72 67 63 20 26 67 74 3b 20  <b>]]>argc &gt; 
d340: 31 20 3c 21 5b 43 44 41 54 41 5b 3c 62 72 3e 5d  1 <![CDATA[<br>]
d350: 5d 3e 20 61 72 67 76 5b 30 5d 20 26 23 38 38 30  ]> argv[0] &#880
d360: 30 3b 20 4e 55 4c 4c 20 3c 21 5b 43 44 41 54 41  0; NULL <![CDATA
d370: 5b 3c 62 72 3e 5d 5d 3e 20 61 72 67 76 5b 30 5d  [<br>]]> argv[0]
d380: 20 3d 20 61 72 67 76 5b 31 5d 3c 21 5b 43 44 41   = argv[1]<![CDA
d390: 54 41 5b 3c 2f 62 3e 5d 5d 3e 0d 0a 20 20 20 20  TA[</b>]]>..    
d3a0: 20 20 20 20 2f 2f 2f 20 3c 21 5b 43 44 41 54 41      /// <![CDATA
d3b0: 5b 3c 2f 64 74 3e 5d 5d 3e 3c 21 5b 43 44 41 54  [</dt>]]><![CDAT
d3c0: 41 5b 3c 64 64 3e 5d 5d 3e 54 68 65 20 72 6f 77  A[<dd>]]>The row
d3d0: 20 77 69 74 68 20 72 6f 77 69 64 20 61 72 67 76   with rowid argv
d3e0: 5b 30 5d 20 69 73 20 75 70 64 61 74 65 64 20 77  [0] is updated w
d3f0: 69 74 68 20 6e 65 77 20 76 61 6c 75 65 73 20 0d  ith new values .
d400: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20  .        ///    
d410: 20 20 20 20 69 6e 20 61 72 67 76 5b 32 5d 20 61      in argv[2] a
d420: 6e 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 61 72  nd following par
d430: 61 6d 65 74 65 72 73 2e 0d 0a 20 20 20 20 20 20  ameters...      
d440: 20 20 2f 2f 2f 20 3c 21 5b 43 44 41 54 41 5b 3c    /// <![CDATA[<
d450: 2f 64 64 3e 5d 5d 3e 3c 21 5b 43 44 41 54 41 5b  /dd>]]><![CDATA[
d460: 3c 64 74 3e 5d 5d 3e 3c 21 5b 43 44 41 54 41 5b  <dt>]]><![CDATA[
d470: 3c 62 3e 5d 5d 3e 61 72 67 63 20 26 67 74 3b 20  <b>]]>argc &gt; 
d480: 31 20 3c 21 5b 43 44 41 54 41 5b 3c 62 72 3e 5d  1 <![CDATA[<br>]
d490: 5d 3e 20 61 72 67 76 5b 30 5d 20 26 23 38 38 30  ]> argv[0] &#880
d4a0: 30 3b 20 4e 55 4c 4c 20 3c 21 5b 43 44 41 54 41  0; NULL <![CDATA
d4b0: 5b 3c 62 72 3e 5d 5d 3e 20 61 72 67 76 5b 30 5d  [<br>]]> argv[0]
d4c0: 20 26 23 38 38 30 30 3b 20 61 72 67 76 5b 31 5d   &#8800; argv[1]
d4d0: 3c 21 5b 43 44 41 54 41 5b 3c 2f 62 3e 5d 5d 3e  <![CDATA[</b>]]>
d4e0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 21  ..        /// <!
d4f0: 5b 43 44 41 54 41 5b 3c 2f 64 74 3e 5d 5d 3e 3c  [CDATA[</dt>]]><
d500: 21 5b 43 44 41 54 41 5b 3c 64 64 3e 5d 5d 3e 20  ![CDATA[<dd>]]> 
d510: 54 68 65 20 72 6f 77 20 77 69 74 68 20 72 6f 77  The row with row
d520: 69 64 20 61 72 67 76 5b 30 5d 20 69 73 20 75 70  id argv[0] is up
d530: 64 61 74 65 64 20 77 69 74 68 20 72 6f 77 69 64  dated with rowid
d540: 20 61 72 67 76 5b 31 5d 20 0d 0a 20 20 20 20 20   argv[1] ..     
d550: 20 20 20 2f 2f 2f 20 61 6e 64 20 6e 65 77 20 76     /// and new v
d560: 61 6c 75 65 73 20 69 6e 20 61 72 67 76 5b 32 5d  alues in argv[2]
d570: 20 61 6e 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 70   and following p
d580: 61 72 61 6d 65 74 65 72 73 2e 20 54 68 69 73 20  arameters. This 
d590: 77 69 6c 6c 20 6f 63 63 75 72 20 0d 0a 20 20 20  will occur ..   
d5a0: 20 20 20 20 20 2f 2f 2f 20 77 68 65 6e 20 61 6e       /// when an
d5b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75   SQL statement u
d5c0: 70 64 61 74 65 73 20 61 20 72 6f 77 69 64 2c 20  pdates a rowid, 
d5d0: 61 73 20 69 6e 20 74 68 65 20 73 74 61 74 65 6d  as in the statem
d5e0: 65 6e 74 3a 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ent:..        //
d5f0: 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a  / <para><code>..
d600: 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 55          ///    U
d610: 50 44 41 54 45 20 74 61 62 6c 65 20 53 45 54 20  PDATE table SET 
d620: 72 6f 77 69 64 3d 72 6f 77 69 64 2b 31 20 57 48  rowid=rowid+1 WH
d630: 45 52 45 20 2e 2e 2e 3b 20 0d 0a 20 20 20 20 20  ERE ...; ..     
d640: 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f     /// </code></
d650: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
d660: 2f 2f 20 3c 21 5b 43 44 41 54 41 5b 3c 2f 64 64  // <![CDATA[</dd
d670: 3e 5d 5d 3e 3c 21 5b 43 44 41 54 41 5b 3c 2f 64  >]]><![CDATA[</d
d680: 6c 3e 5d 5d 3e 0d 0a 20 20 20 20 20 20 20 20 2f  l>]]>..        /
d690: 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61  // </code></para
d6a0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
d6b0: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
d6c0: 2f 2f 20 54 68 65 20 78 55 70 64 61 74 65 20 6d  // The xUpdate m
d6d0: 65 74 68 6f 64 20 6d 75 73 74 20 72 65 74 75 72  ethod must retur
d6e0: 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61  n SQLITE_OK if a
d6f0: 6e 64 20 6f 6e 6c 79 20 69 66 20 69 74 20 69 73  nd only if it is
d700: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 75  ..        /// su
d710: 63 63 65 73 73 66 75 6c 2e 20 20 49 66 20 61 20  ccessful.  If a 
d720: 66 61 69 6c 75 72 65 20 6f 63 63 75 72 73 2c 20  failure occurs, 
d730: 74 68 65 20 78 55 70 64 61 74 65 20 6d 75 73 74  the xUpdate must
d740: 20 72 65 74 75 72 6e 20 61 6e 20 61 70 70 72 6f   return an appro
d750: 70 72 69 61 74 65 0d 0a 20 20 20 20 20 20 20 20  priate..        
d760: 2f 2f 2f 20 65 72 72 6f 72 20 63 6f 64 65 2e 20  /// error code. 
d770: 20 4f 6e 20 61 20 66 61 69 6c 75 72 65 2c 20 74   On a failure, t
d780: 68 65 20 70 56 54 61 62 2d 3e 7a 45 72 72 4d 73  he pVTab->zErrMs
d790: 67 20 65 6c 65 6d 65 6e 74 20 6d 61 79 20 6f 70  g element may op
d7a0: 74 69 6f 6e 61 6c 6c 79 0d 0a 20 20 20 20 20 20  tionally..      
d7b0: 20 20 2f 2f 2f 20 62 65 20 72 65 70 6c 61 63 65    /// be replace
d7c0: 64 20 77 69 74 68 20 65 72 72 6f 72 20 6d 65 73  d with error mes
d7d0: 73 61 67 65 20 74 65 78 74 20 73 74 6f 72 65 64  sage text stored
d7e0: 20 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   in memory alloc
d7f0: 61 74 65 64 20 66 72 6f 6d 20 53 51 4c 69 74 65  ated from SQLite
d800: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 75   ..        /// u
d810: 73 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 73  sing functions s
d820: 75 63 68 20 61 73 20 73 71 6c 69 74 65 33 5f 6d  uch as sqlite3_m
d830: 70 72 69 6e 74 66 28 29 20 6f 72 20 73 71 6c 69  printf() or sqli
d840: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2e 0d 0a 20  te3_malloc()... 
d850: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
d860: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
d870: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
d880: 2f 2f 2f 20 49 66 20 74 68 65 20 78 55 70 64 61  /// If the xUpda
d890: 74 65 20 6d 65 74 68 6f 64 20 76 69 6f 6c 61 74  te method violat
d8a0: 65 73 20 73 6f 6d 65 20 63 6f 6e 73 74 72 61 69  es some constrai
d8b0: 6e 74 20 6f 66 20 74 68 65 20 76 69 72 74 75 61  nt of the virtua
d8c0: 6c 20 74 61 62 6c 65 0d 0a 20 20 20 20 20 20 20  l table..       
d8d0: 20 2f 2f 2f 20 28 69 6e 63 6c 75 64 69 6e 67 2c   /// (including,
d8e0: 20 62 75 74 20 6e 6f 74 20 6c 69 6d 69 74 65 64   but not limited
d8f0: 20 74 6f 2c 20 61 74 74 65 6d 70 74 69 6e 67 20   to, attempting 
d900: 74 6f 20 73 74 6f 72 65 20 61 20 76 61 6c 75 65  to store a value
d910: 20 6f 66 20 74 68 65 20 77 72 6f 6e 67 20 0d 0a   of the wrong ..
d920: 20 20 20 20 20 20 20 20 2f 2f 2f 20 64 61 74 61          /// data
d930: 74 79 70 65 2c 20 61 74 74 65 6d 70 74 69 6e 67  type, attempting
d940: 20 74 6f 20 73 74 6f 72 65 20 61 20 76 61 6c 75   to store a valu
d950: 65 20 74 68 61 74 20 69 73 20 74 6f 6f 0d 0a 20  e that is too.. 
d960: 20 20 20 20 20 20 20 2f 2f 2f 20 6c 61 72 67 65         /// large
d970: 20 6f 72 20 74 6f 6f 20 73 6d 61 6c 6c 2c 20 6f   or too small, o
d980: 72 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20  r attempting to 
d990: 63 68 61 6e 67 65 20 61 20 72 65 61 64 2d 6f 6e  change a read-on
d9a0: 6c 79 20 76 61 6c 75 65 29 20 74 68 65 6e 20 74  ly value) then t
d9b0: 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  he..        /// 
d9c0: 78 55 70 64 61 74 65 20 6d 75 73 74 20 66 61 69  xUpdate must fai
d9d0: 6c 20 77 69 74 68 20 61 6e 20 61 70 70 72 6f 70  l with an approp
d9e0: 72 69 61 74 65 20 65 72 72 6f 72 20 63 6f 64 65  riate error code
d9f0: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
da00: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
da10: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20  /// <para>..    
da20: 20 20 20 20 2f 2f 2f 20 54 68 65 72 65 20 6d 69      /// There mi
da30: 67 68 74 20 62 65 20 6f 6e 65 20 6f 72 20 6d 6f  ght be one or mo
da40: 72 65 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  re sqlite3_vtab_
da50: 63 75 72 73 6f 72 20 6f 62 6a 65 63 74 73 20 6f  cursor objects o
da60: 70 65 6e 20 61 6e 64 20 69 6e 20 75 73 65 20 0d  pen and in use .
da70: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6f 6e 20  .        /// on 
da80: 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
da90: 65 20 69 6e 73 74 61 6e 63 65 20 61 6e 64 20 70  e instance and p
daa0: 65 72 68 61 70 73 20 65 76 65 6e 20 6f 6e 20 74  erhaps even on t
dab0: 68 65 20 72 6f 77 20 6f 66 20 74 68 65 20 76 69  he row of the vi
dac0: 72 74 75 61 6c 0d 0a 20 20 20 20 20 20 20 20 2f  rtual..        /
dad0: 2f 2f 20 74 61 62 6c 65 20 77 68 65 6e 20 74 68  // table when th
dae0: 65 20 78 55 70 64 61 74 65 20 6d 65 74 68 6f 64  e xUpdate method
daf0: 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 54 68   is invoked.  Th
db00: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
db10: 20 6f 66 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f   of..        ///
db20: 20 78 55 70 64 61 74 65 20 6d 75 73 74 20 62 65   xUpdate must be
db30: 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 74   prepared for at
db40: 74 65 6d 70 74 73 20 74 6f 20 64 65 6c 65 74 65  tempts to delete
db50: 20 6f 72 20 6d 6f 64 69 66 79 20 72 6f 77 73 20   or modify rows 
db60: 6f 66 20 74 68 65 20 74 61 62 6c 65 0d 0a 20 20  of the table..  
db70: 20 20 20 20 20 20 2f 2f 2f 20 6f 75 74 20 66 72        /// out fr
db80: 6f 6d 20 6f 74 68 65 72 20 65 78 69 73 74 69 6e  om other existin
db90: 67 20 63 75 72 73 6f 72 73 2e 20 20 49 66 20 74  g cursors.  If t
dba0: 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
dbb0: 20 63 61 6e 6e 6f 74 20 61 63 63 6f 6d 6d 6f 64   cannot accommod
dbc0: 61 74 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ate..        ///
dbd0: 20 73 75 63 68 20 63 68 61 6e 67 65 73 2c 20 74   such changes, t
dbe0: 68 65 20 78 55 70 64 61 74 65 20 6d 65 74 68 6f  he xUpdate metho
dbf0: 64 20 6d 75 73 74 20 72 65 74 75 72 6e 20 61 6e  d must return an
dc00: 20 65 72 72 6f 72 20 63 6f 64 65 2e 0d 0a 20 20   error code...  
dc10: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61        /// </para
dc20: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
dc30: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
dc40: 2f 2f 20 54 68 65 20 78 55 70 64 61 74 65 20 6d  // The xUpdate m
dc50: 65 74 68 6f 64 20 69 73 20 6f 70 74 69 6f 6e 61  ethod is optiona
dc60: 6c 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  l...        /// 
dc70: 49 66 20 74 68 65 20 78 55 70 64 61 74 65 20 70  If the xUpdate p
dc80: 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 73 71  ointer in the sq
dc90: 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 66 6f 72  lite3_module for
dca0: 20 61 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65   a virtual table
dcb0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 73  ..        /// is
dcc0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
dcd0: 20 74 68 65 6e 20 74 68 65 20 76 69 72 74 75 61   then the virtua
dce0: 6c 20 74 61 62 6c 65 20 69 73 20 72 65 61 64 2d  l table is read-
dcf0: 6f 6e 6c 79 2e 0d 0a 20 20 20 20 20 20 20 20 2f  only...        /
dd00: 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  // </para>..    
dd10: 20 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72      /// </summar
dd20: 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  y>..        /// 
dd30: 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 56 74  <param name="pVt
dd40: 61 62 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ab">..        //
dd50: 2f 20 54 68 65 20 6e 61 74 69 76 65 20 70 6f 69  / The native poi
dd60: 6e 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  nter to the sqli
dd70: 74 65 33 5f 76 74 61 62 20 64 65 72 69 76 65 64  te3_vtab derived
dd80: 20 73 74 72 75 63 74 75 72 65 2e 0d 0a 20 20 20   structure...   
dd90: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d       /// </param
dda0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
ddb0: 70 61 72 61 6d 20 6e 61 6d 65 3d 22 61 72 67 63  param name="argc
ddc0: 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ">..        /// 
ddd0: 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e 65  The number of ne
dde0: 77 20 6f 72 20 6d 6f 64 69 66 69 65 64 20 63 6f  w or modified co
ddf0: 6c 75 6d 6e 20 76 61 6c 75 65 73 20 63 6f 6e 74  lumn values cont
de00: 61 69 6e 65 64 20 69 6e 0d 0a 20 20 20 20 20 20  ained in..      
de10: 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 72 65 66 20    /// <paramref 
de20: 6e 61 6d 65 3d 22 61 72 67 76 22 20 2f 3e 2e 0d  name="argv" />..
de30: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
de40: 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f  aram>..        /
de50: 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22  // <param name="
de60: 61 72 67 76 22 3e 0d 0a 20 20 20 20 20 20 20 20  argv">..        
de70: 2f 2f 2f 20 54 68 65 20 61 72 72 61 79 20 6f 66  /// The array of
de80: 20 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72 73   native pointers
de90: 20 74 6f 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   to sqlite3_valu
dea0: 65 20 73 74 72 75 63 74 75 72 65 73 20 63 6f 6e  e structures con
deb0: 74 61 69 6e 69 6e 67 0d 0a 20 20 20 20 20 20 20  taining..       
dec0: 20 2f 2f 2f 20 74 68 65 20 6e 65 77 20 6f 72 20   /// the new or 
ded0: 6d 6f 64 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20  modified column 
dee0: 76 61 6c 75 65 73 2c 20 69 66 20 61 6e 79 2e 0d  values, if any..
def0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
df00: 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f  aram>..        /
df10: 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22  // <param name="
df20: 72 6f 77 49 64 22 3e 0d 0a 20 20 20 20 20 20 20  rowId">..       
df30: 20 2f 2f 2f 20 55 70 6f 6e 20 73 75 63 63 65 73   /// Upon succes
df40: 73 2c 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  s, this paramete
df50: 72 20 6d 75 73 74 20 62 65 20 6d 6f 64 69 66 69  r must be modifi
df60: 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 74 68  ed to contain th
df70: 65 20 75 6e 69 71 75 65 0d 0a 20 20 20 20 20 20  e unique..      
df80: 20 20 2f 2f 2f 20 69 6e 74 65 67 65 72 20 72 6f    /// integer ro
df90: 77 20 69 64 65 6e 74 69 66 69 65 72 20 66 6f 72  w identifier for
dfa0: 20 74 68 65 20 72 6f 77 20 74 68 61 74 20 77 61   the row that wa
dfb0: 73 20 69 6e 73 65 72 74 65 64 2c 20 69 66 20 61  s inserted, if a
dfc0: 6e 79 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ny...        ///
dfd0: 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20   </param>..     
dfe0: 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72 6e 73 3e     /// <returns>
dff0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 20  ..        /// A 
e000: 73 74 61 6e 64 61 72 64 20 53 51 4c 69 74 65 20  standard SQLite 
e010: 72 65 74 75 72 6e 20 63 6f 64 65 2e 0d 0a 20 20  return code...  
e020: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72 65 74 75        /// </retu
e030: 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 53 51  rns>..        SQ
e040: 4c 69 74 65 45 72 72 6f 72 43 6f 64 65 20 78 55  LiteErrorCode xU
e050: 70 64 61 74 65 28 0d 0a 20 20 20 20 20 20 20 20  pdate(..        
e060: 20 20 20 20 49 6e 74 50 74 72 20 70 56 74 61 62      IntPtr pVtab
e070: 2c 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 69  ,..            i
e080: 6e 74 20 61 72 67 63 2c 0d 0a 20 20 20 20 20 20  nt argc,..      
e090: 20 20 20 20 20 20 49 6e 74 50 74 72 20 61 72 67        IntPtr arg
e0a0: 76 2c 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20  v,..            
e0b0: 72 65 66 20 6c 6f 6e 67 20 72 6f 77 49 64 0d 0a  ref long rowId..
e0c0: 20 20 20 20 20 20 20 20 20 20 20 20 29 3b 0d 0a              );..
e0d0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f  ..        //////
e0e0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
e0f0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
e100: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
e110: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
e120: 2f 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  /....        ///
e130: 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20   <summary>..    
e140: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63      /// <para><c
e150: 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ode>..        //
e160: 2f 20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29 28  / int (*xBegin)(
e170: 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
e180: 54 61 62 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f  Tab);..        /
e190: 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61  // </code></para
e1a0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
e1b0: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
e1c0: 2f 2f 20 54 68 69 73 20 6d 65 74 68 6f 64 20 62  // This method b
e1d0: 65 67 69 6e 73 20 61 20 74 72 61 6e 73 61 63 74  egins a transact
e1e0: 69 6f 6e 20 6f 6e 20 61 20 76 69 72 74 75 61 6c  ion on a virtual
e1f0: 20 74 61 62 6c 65 2e 0d 0a 20 20 20 20 20 20 20   table...       
e200: 20 2f 2f 2f 20 54 68 69 73 20 69 73 20 6d 65 74   /// This is met
e210: 68 6f 64 20 69 73 20 6f 70 74 69 6f 6e 61 6c 2e  hod is optional.
e220: 20 20 54 68 65 20 78 42 65 67 69 6e 20 70 6f 69    The xBegin poi
e230: 6e 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  nter of sqlite3_
e240: 6d 6f 64 75 6c 65 0d 0a 20 20 20 20 20 20 20 20  module..        
e250: 2f 2f 2f 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e  /// may be NULL.
e260: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
e270: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
e280: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20  // <para>..     
e290: 20 20 20 2f 2f 2f 20 54 68 69 73 20 6d 65 74 68     /// This meth
e2a0: 6f 64 20 69 73 20 61 6c 77 61 79 73 20 66 6f 6c  od is always fol
e2b0: 6c 6f 77 65 64 20 62 79 20 6f 6e 65 20 63 61 6c  lowed by one cal
e2c0: 6c 20 74 6f 20 65 69 74 68 65 72 20 74 68 65 0d  l to either the.
e2d0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 78 43 6f  .        /// xCo
e2e0: 6d 6d 69 74 20 6f 72 20 78 52 6f 6c 6c 62 61 63  mmit or xRollbac
e2f0: 6b 20 6d 65 74 68 6f 64 2e 20 20 56 69 72 74 75  k method.  Virtu
e300: 61 6c 20 74 61 62 6c 65 20 74 72 61 6e 73 61 63  al table transac
e310: 74 69 6f 6e 73 20 64 6f 0d 0a 20 20 20 20 20 20  tions do..      
e320: 20 20 2f 2f 2f 20 6e 6f 74 20 6e 65 73 74 2c 20    /// not nest, 
e330: 73 6f 20 74 68 65 20 78 42 65 67 69 6e 20 6d 65  so the xBegin me
e340: 74 68 6f 64 20 77 69 6c 6c 20 6e 6f 74 20 62 65  thod will not be
e350: 20 69 6e 76 6f 6b 65 64 20 6d 6f 72 65 20 74 68   invoked more th
e360: 61 6e 20 6f 6e 63 65 0d 0a 20 20 20 20 20 20 20  an once..       
e370: 20 2f 2f 2f 20 6f 6e 20 61 20 73 69 6e 67 6c 65   /// on a single
e380: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 0d 0a   virtual table..
e390: 20 20 20 20 20 20 20 20 2f 2f 2f 20 77 69 74 68          /// with
e3a0: 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69  out an interveni
e3b0: 6e 67 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65  ng call to eithe
e3c0: 72 20 78 43 6f 6d 6d 69 74 20 6f 72 20 78 52 6f  r xCommit or xRo
e3d0: 6c 6c 62 61 63 6b 2e 0d 0a 20 20 20 20 20 20 20  llback...       
e3e0: 20 2f 2f 2f 20 4d 75 6c 74 69 70 6c 65 20 63 61   /// Multiple ca
e3f0: 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 6d 65 74  lls to other met
e400: 68 6f 64 73 20 63 61 6e 20 61 6e 64 20 6c 69 6b  hods can and lik
e410: 65 6c 79 20 77 69 6c 6c 20 6f 63 63 75 72 20 69  ely will occur i
e420: 6e 20 62 65 74 77 65 65 6e 0d 0a 20 20 20 20 20  n between..     
e430: 20 20 20 2f 2f 2f 20 74 68 65 20 78 42 65 67 69     /// the xBegi
e440: 6e 20 61 6e 64 20 74 68 65 20 63 6f 72 72 65 73  n and the corres
e450: 70 6f 6e 64 69 6e 67 20 78 43 6f 6d 6d 69 74 20  ponding xCommit 
e460: 6f 72 20 78 52 6f 6c 6c 62 61 63 6b 2e 0d 0a 20  or xRollback... 
e470: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
e480: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
e490: 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20  </summary>..    
e4a0: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e      /// <param n
e4b0: 61 6d 65 3d 22 70 56 74 61 62 22 3e 0d 0a 20 20  ame="pVtab">..  
e4c0: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e 61        /// The na
e4d0: 74 69 76 65 20 70 6f 69 6e 74 65 72 20 74 6f 20  tive pointer to 
e4e0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 74 61 62  the sqlite3_vtab
e4f0: 20 64 65 72 69 76 65 64 20 73 74 72 75 63 74 75   derived structu
e500: 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  re...        ///
e510: 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20   </param>..     
e520: 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72 6e 73 3e     /// <returns>
e530: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 20  ..        /// A 
e540: 73 74 61 6e 64 61 72 64 20 53 51 4c 69 74 65 20  standard SQLite 
e550: 72 65 74 75 72 6e 20 63 6f 64 65 2e 0d 0a 20 20  return code...  
e560: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72 65 74 75        /// </retu
e570: 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 53 51  rns>..        SQ
e580: 4c 69 74 65 45 72 72 6f 72 43 6f 64 65 20 78 42  LiteErrorCode xB
e590: 65 67 69 6e 28 0d 0a 20 20 20 20 20 20 20 20 20  egin(..         
e5a0: 20 20 20 49 6e 74 50 74 72 20 70 56 74 61 62 0d     IntPtr pVtab.
e5b0: 0a 20 20 20 20 20 20 20 20 20 20 20 20 29 3b 0d  .            );.
e5c0: 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 2f 2f  ...        /////
e5d0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
e5e0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
e5f0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
e600: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
e610: 2f 2f 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f  //....        //
e620: 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20  / <summary>..   
e630: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c       /// <para><
e640: 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f  code>..        /
e650: 2f 2f 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28  // int (*xSync)(
e660: 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
e670: 54 61 62 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f  Tab);..        /
e680: 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61  // </code></para
e690: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
e6a0: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
e6b0: 2f 2f 20 54 68 69 73 20 6d 65 74 68 6f 64 20 73  // This method s
e6c0: 69 67 6e 61 6c 73 20 74 68 65 20 73 74 61 72 74  ignals the start
e6d0: 20 6f 66 20 61 20 74 77 6f 2d 70 68 61 73 65 20   of a two-phase 
e6e0: 63 6f 6d 6d 69 74 20 6f 6e 20 61 20 76 69 72 74  commit on a virt
e6f0: 75 61 6c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ual..        ///
e700: 20 74 61 62 6c 65 2e 0d 0a 20 20 20 20 20 20 20   table...       
e710: 20 2f 2f 2f 20 54 68 69 73 20 69 73 20 6d 65 74   /// This is met
e720: 68 6f 64 20 69 73 20 6f 70 74 69 6f 6e 61 6c 2e  hod is optional.
e730: 20 20 54 68 65 20 78 53 79 6e 63 20 70 6f 69 6e    The xSync poin
e740: 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d  ter of sqlite3_m
e750: 6f 64 75 6c 65 0d 0a 20 20 20 20 20 20 20 20 2f  odule..        /
e760: 2f 2f 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0d  // may be NULL..
e770: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
e780: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
e790: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
e7a0: 20 20 2f 2f 2f 20 54 68 69 73 20 6d 65 74 68 6f    /// This metho
e7b0: 64 20 69 73 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65  d is only invoke
e7c0: 64 20 61 66 74 65 72 20 63 61 6c 6c 20 74 6f 20  d after call to 
e7d0: 74 68 65 20 78 42 65 67 69 6e 20 6d 65 74 68 6f  the xBegin metho
e7e0: 64 20 61 6e 64 0d 0a 20 20 20 20 20 20 20 20 2f  d and..        /
e7f0: 2f 2f 20 70 72 69 6f 72 20 74 6f 20 61 6e 20 78  // prior to an x
e800: 43 6f 6d 6d 69 74 20 6f 72 20 78 52 6f 6c 6c 62  Commit or xRollb
e810: 61 63 6b 2e 20 20 49 6e 20 6f 72 64 65 72 20 74  ack.  In order t
e820: 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 77 6f 2d  o implement two-
e830: 70 68 61 73 65 0d 0a 20 20 20 20 20 20 20 20 2f  phase..        /
e840: 2f 2f 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20 78  // commit, the x
e850: 53 79 6e 63 20 6d 65 74 68 6f 64 20 6f 6e 20 61  Sync method on a
e860: 6c 6c 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ll virtual table
e870: 73 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 72 69  s is invoked pri
e880: 6f 72 20 74 6f 0d 0a 20 20 20 20 20 20 20 20 2f  or to..        /
e890: 2f 2f 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  // invoking the 
e8a0: 78 43 6f 6d 6d 69 74 20 6d 65 74 68 6f 64 20 6f  xCommit method o
e8b0: 6e 20 61 6e 79 20 76 69 72 74 75 61 6c 20 74 61  n any virtual ta
e8c0: 62 6c 65 2e 20 20 49 66 20 61 6e 79 20 6f 66 20  ble.  If any of 
e8d0: 74 68 65 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  the ..        //
e8e0: 2f 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 73 20  / xSync methods 
e8f0: 66 61 69 6c 2c 20 74 68 65 20 65 6e 74 69 72 65  fail, the entire
e900: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
e910: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0d 0a 20 20  rolled back...  
e920: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61        /// </para
e930: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
e940: 2f 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20  /summary>..     
e950: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61     /// <param na
e960: 6d 65 3d 22 70 56 74 61 62 22 3e 0d 0a 20 20 20  me="pVtab">..   
e970: 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e 61 74       /// The nat
e980: 69 76 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  ive pointer to t
e990: 68 65 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20  he sqlite3_vtab 
e9a0: 64 65 72 69 76 65 64 20 73 74 72 75 63 74 75 72  derived structur
e9b0: 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e...        /// 
e9c0: 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20  </param>..      
e9d0: 20 20 2f 2f 2f 20 3c 72 65 74 75 72 6e 73 3e 0d    /// <returns>.
e9e0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 20 73  .        /// A s
e9f0: 74 61 6e 64 61 72 64 20 53 51 4c 69 74 65 20 72  tandard SQLite r
ea00: 65 74 75 72 6e 20 63 6f 64 65 2e 0d 0a 20 20 20  eturn code...   
ea10: 20 20 20 20 20 2f 2f 2f 20 3c 2f 72 65 74 75 72       /// </retur
ea20: 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 53 51 4c  ns>..        SQL
ea30: 69 74 65 45 72 72 6f 72 43 6f 64 65 20 78 53 79  iteErrorCode xSy
ea40: 6e 63 28 0d 0a 20 20 20 20 20 20 20 20 20 20 20  nc(..           
ea50: 20 49 6e 74 50 74 72 20 70 56 74 61 62 0d 0a 20   IntPtr pVtab.. 
ea60: 20 20 20 20 20 20 20 20 20 20 20 29 3b 0d 0a 0d             );...
ea70: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f  .        ///////
ea80: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
ea90: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
eaa0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
eab0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
eac0: 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ....        /// 
ead0: 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20  <summary>..     
eae0: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f     /// <para><co
eaf0: 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  de>..        ///
eb00: 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28   int (*xCommit)(
eb10: 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
eb20: 54 61 62 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f  Tab);..        /
eb30: 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61  // </code></para
eb40: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
eb50: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
eb60: 2f 2f 20 54 68 69 73 20 6d 65 74 68 6f 64 20 63  // This method c
eb70: 61 75 73 65 73 20 61 20 76 69 72 74 75 61 6c 20  auses a virtual 
eb80: 74 61 62 6c 65 20 74 72 61 6e 73 61 63 74 69 6f  table transactio
eb90: 6e 20 74 6f 20 63 6f 6d 6d 69 74 2e 0d 0a 20 20  n to commit...  
eba0: 20 20 20 20 20 20 2f 2f 2f 20 54 68 69 73 20 69        /// This i
ebb0: 73 20 6d 65 74 68 6f 64 20 69 73 20 6f 70 74 69  s method is opti
ebc0: 6f 6e 61 6c 2e 20 20 54 68 65 20 78 43 6f 6d 6d  onal.  The xComm
ebd0: 69 74 20 70 6f 69 6e 74 65 72 20 6f 66 20 73 71  it pointer of sq
ebe0: 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 0d 0a 20 20  lite3_module..  
ebf0: 20 20 20 20 20 20 2f 2f 2f 20 6d 61 79 20 62 65        /// may be
ec00: 20 4e 55 4c 4c 2e 0d 0a 20 20 20 20 20 20 20 20   NULL...        
ec10: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
ec20: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
ec30: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 20 63  .        /// A c
ec40: 61 6c 6c 20 74 6f 20 74 68 69 73 20 6d 65 74 68  all to this meth
ec50: 6f 64 20 61 6c 77 61 79 73 20 66 6f 6c 6c 6f 77  od always follow
ec60: 73 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  s a prior call t
ec70: 6f 20 78 42 65 67 69 6e 20 61 6e 64 0d 0a 20 20  o xBegin and..  
ec80: 20 20 20 20 20 20 2f 2f 2f 20 78 53 79 6e 63 2e        /// xSync.
ec90: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
eca0: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
ecb0: 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a 20  // </summary>.. 
ecc0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
ecd0: 6d 20 6e 61 6d 65 3d 22 70 56 74 61 62 22 3e 0d  m name="pVtab">.
ece0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65  .        /// The
ecf0: 20 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72 20   native pointer 
ed00: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  to the sqlite3_v
ed10: 74 61 62 20 64 65 72 69 76 65 64 20 73 74 72 75  tab derived stru
ed20: 63 74 75 72 65 2e 0d 0a 20 20 20 20 20 20 20 20  cture...        
ed30: 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20  /// </param>..  
ed40: 20 20 20 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72        /// <retur
ed50: 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ns>..        ///
ed60: 20 41 20 73 74 61 6e 64 61 72 64 20 53 51 4c 69   A standard SQLi
ed70: 74 65 20 72 65 74 75 72 6e 20 63 6f 64 65 2e 0d  te return code..
ed80: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72  .        /// </r
ed90: 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20  eturns>..       
eda0: 20 53 51 4c 69 74 65 45 72 72 6f 72 43 6f 64 65   SQLiteErrorCode
edb0: 20 78 43 6f 6d 6d 69 74 28 0d 0a 20 20 20 20 20   xCommit(..     
edc0: 20 20 20 20 20 20 20 49 6e 74 50 74 72 20 70 56         IntPtr pV
edd0: 74 61 62 0d 0a 20 20 20 20 20 20 20 20 20 20 20  tab..           
ede0: 20 29 3b 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f   );....        /
edf0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
ee00: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
ee10: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
ee20: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
ee30: 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 20 20  //////....      
ee40: 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d    /// <summary>.
ee50: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
ee60: 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20  ra><code>..     
ee70: 20 20 20 2f 2f 2f 20 69 6e 74 20 28 2a 78 52 6f     /// int (*xRo
ee80: 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f  llback)(sqlite3_
ee90: 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0d 0a 20  vtab *pVTab);.. 
eea0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64         /// </cod
eeb0: 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  e></para>..     
eec0: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20     /// <para>.. 
eed0: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 69 73 20         /// This 
eee0: 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 61 20  method causes a 
eef0: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 74 72  virtual table tr
ef00: 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 72 6f 6c  ansaction to rol
ef10: 6c 62 61 63 6b 2e 0d 0a 20 20 20 20 20 20 20 20  lback...        
ef20: 2f 2f 2f 20 54 68 69 73 20 69 73 20 6d 65 74 68  /// This is meth
ef30: 6f 64 20 69 73 20 6f 70 74 69 6f 6e 61 6c 2e 20  od is optional. 
ef40: 20 54 68 65 20 78 52 6f 6c 6c 62 61 63 6b 20 70   The xRollback p
ef50: 6f 69 6e 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ointer of sqlite
ef60: 33 5f 6d 6f 64 75 6c 65 0d 0a 20 20 20 20 20 20  3_module..      
ef70: 20 20 2f 2f 2f 20 6d 61 79 20 62 65 20 4e 55 4c    /// may be NUL
ef80: 4c 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  L...        /// 
ef90: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
efa0: 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20   /// <para>..   
efb0: 20 20 20 20 20 2f 2f 2f 20 41 20 63 61 6c 6c 20       /// A call 
efc0: 74 6f 20 74 68 69 73 20 6d 65 74 68 6f 64 20 61  to this method a
efd0: 6c 77 61 79 73 20 66 6f 6c 6c 6f 77 73 20 61 20  lways follows a 
efe0: 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 42  prior call to xB
eff0: 65 67 69 6e 2e 0d 0a 20 20 20 20 20 20 20 20 2f  egin...        /
f000: 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  // </para>..    
f010: 20 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72      /// </summar
f020: 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  y>..        /// 
f030: 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 56 74  <param name="pVt
f040: 61 62 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ab">..        //
f050: 2f 20 54 68 65 20 6e 61 74 69 76 65 20 70 6f 69  / The native poi
f060: 6e 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  nter to the sqli
f070: 74 65 33 5f 76 74 61 62 20 64 65 72 69 76 65 64  te3_vtab derived
f080: 20 73 74 72 75 63 74 75 72 65 2e 0d 0a 20 20 20   structure...   
f090: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d       /// </param
f0a0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
f0b0: 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20  returns>..      
f0c0: 20 20 2f 2f 2f 20 41 20 73 74 61 6e 64 61 72 64    /// A standard
f0d0: 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 20 63   SQLite return c
f0e0: 6f 64 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ode...        //
f0f0: 2f 20 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a 20 20  / </returns>..  
f100: 20 20 20 20 20 20 53 51 4c 69 74 65 45 72 72 6f        SQLiteErro
f110: 72 43 6f 64 65 20 78 52 6f 6c 6c 62 61 63 6b 28  rCode xRollback(
f120: 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 49 6e  ..            In
f130: 74 50 74 72 20 70 56 74 61 62 0d 0a 20 20 20 20  tPtr pVtab..    
f140: 20 20 20 20 20 20 20 20 29 3b 0d 0a 0d 0a 20 20          );....  
f150: 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f        //////////
f160: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
f170: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
f180: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
f190: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d  /////////////...
f1a0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 73 75  .        /// <su
f1b0: 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20  mmary>..        
f1c0: 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e  /// <para><code>
f1d0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e  ..        /// in
f1e0: 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f  t (*xFindFunctio
f1f0: 6e 29 28 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  n)(..        ///
f200: 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20     sqlite3_vtab 
f210: 2a 70 56 74 61 62 2c 0d 0a 20 20 20 20 20 20 20  *pVtab,..       
f220: 20 2f 2f 2f 20 20 20 69 6e 74 20 6e 41 72 67 2c   ///   int nArg,
f230: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20  ..        ///   
f240: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
f250: 65 2c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e,..        /// 
f260: 20 20 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63    void (**pxFunc
f270: 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
f280: 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
f290: 61 6c 75 65 2a 2a 29 2c 0d 0a 20 20 20 20 20 20  alue**),..      
f2a0: 20 20 2f 2f 2f 20 20 20 76 6f 69 64 20 2a 2a 70    ///   void **p
f2b0: 70 41 72 67 0d 0a 20 20 20 20 20 20 20 20 2f 2f  pArg..        //
f2c0: 2f 20 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f  / );..        //
f2d0: 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e  / </code></para>
f2e0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
f2f0: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
f300: 2f 20 54 68 69 73 20 6d 65 74 68 6f 64 20 69 73  / This method is
f310: 20 63 61 6c 6c 65 64 20 64 75 72 69 6e 67 20 73   called during s
f320: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
f330: 20 74 6f 20 67 69 76 65 20 74 68 65 20 76 69 72   to give the vir
f340: 74 75 61 6c 0d 0a 20 20 20 20 20 20 20 20 2f 2f  tual..        //
f350: 2f 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  / table implemen
f360: 74 61 74 69 6f 6e 20 61 6e 20 6f 70 70 6f 72 74  tation an opport
f370: 75 6e 69 74 79 20 74 6f 20 6f 76 65 72 6c 6f 61  unity to overloa
f380: 64 20 66 75 6e 63 74 69 6f 6e 73 2e 20 0d 0a 20  d functions. .. 
f390: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 69 73 20         /// This 
f3a0: 6d 65 74 68 6f 64 20 6d 61 79 20 62 65 20 73 65  method may be se
f3b0: 74 20 74 6f 20 4e 55 4c 4c 20 69 6e 20 77 68 69  t to NULL in whi
f3c0: 63 68 20 63 61 73 65 20 6e 6f 20 6f 76 65 72 6c  ch case no overl
f3d0: 6f 61 64 69 6e 67 20 6f 63 63 75 72 73 2e 0d 0a  oading occurs...
f3e0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
f3f0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
f400: 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20   <para>..       
f410: 20 2f 2f 2f 20 57 68 65 6e 20 61 20 66 75 6e 63   /// When a func
f420: 74 69 6f 6e 20 75 73 65 73 20 61 20 63 6f 6c 75  tion uses a colu
f430: 6d 6e 20 66 72 6f 6d 20 61 20 76 69 72 74 75 61  mn from a virtua
f440: 6c 20 74 61 62 6c 65 20 61 73 20 69 74 73 20 66  l table as its f
f450: 69 72 73 74 20 0d 0a 20 20 20 20 20 20 20 20 2f  irst ..        /
f460: 2f 2f 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 69  // argument, thi
f470: 73 20 6d 65 74 68 6f 64 20 69 73 20 63 61 6c 6c  s method is call
f480: 65 64 20 74 6f 20 73 65 65 20 69 66 20 74 68 65  ed to see if the
f490: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 77   virtual table w
f4a0: 6f 75 6c 64 20 0d 0a 20 20 20 20 20 20 20 20 2f  ould ..        /
f4b0: 2f 2f 20 6c 69 6b 65 20 74 6f 20 6f 76 65 72 6c  // like to overl
f4c0: 6f 61 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  oad the function
f4d0: 2e 20 54 68 65 20 66 69 72 73 74 20 74 68 72 65  . The first thre
f4e0: 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  e parameters are
f4f0: 20 69 6e 70 75 74 73 3a 20 0d 0a 20 20 20 20 20   inputs: ..     
f500: 20 20 20 2f 2f 2f 20 74 68 65 20 76 69 72 74 75     /// the virtu
f510: 61 6c 20 74 61 62 6c 65 2c 20 74 68 65 20 6e 75  al table, the nu
f520: 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
f530: 73 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f  s to the functio
f540: 6e 2c 20 61 6e 64 20 74 68 65 20 0d 0a 20 20 20  n, and the ..   
f550: 20 20 20 20 20 2f 2f 2f 20 6e 61 6d 65 20 6f 66       /// name of
f560: 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2e 20 49   the function. I
f570: 66 20 6e 6f 20 6f 76 65 72 6c 6f 61 64 69 6e 67  f no overloading
f580: 20 69 73 20 64 65 73 69 72 65 64 2c 20 74 68 69   is desired, thi
f590: 73 20 6d 65 74 68 6f 64 0d 0a 20 20 20 20 20 20  s method..      
f5a0: 20 20 2f 2f 2f 20 72 65 74 75 72 6e 73 20 30 2e    /// returns 0.
f5b0: 20 54 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   To overload the
f5c0: 20 66 75 6e 63 74 69 6f 6e 2c 20 74 68 69 73 20   function, this 
f5d0: 6d 65 74 68 6f 64 20 77 72 69 74 65 73 20 74 68  method writes th
f5e0: 65 20 6e 65 77 20 0d 0a 20 20 20 20 20 20 20 20  e new ..        
f5f0: 2f 2f 2f 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  /// function imp
f600: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f  lementation into
f610: 20 2a 70 78 46 75 6e 63 20 61 6e 64 20 77 72 69   *pxFunc and wri
f620: 74 65 73 20 75 73 65 72 20 64 61 74 61 20 69 6e  tes user data in
f630: 74 6f 20 2a 70 70 41 72 67 20 0d 0a 20 20 20 20  to *ppArg ..    
f640: 20 20 20 20 2f 2f 2f 20 61 6e 64 20 72 65 74 75      /// and retu
f650: 72 6e 73 20 31 2e 0d 0a 20 20 20 20 20 20 20 20  rns 1...        
f660: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
f670: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
f680: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 4e 6f 74  .        /// Not
f690: 65 20 74 68 61 74 20 69 6e 66 69 78 20 66 75 6e  e that infix fun
f6a0: 63 74 69 6f 6e 73 20 28 4c 49 4b 45 2c 20 47 4c  ctions (LIKE, GL
f6b0: 4f 42 2c 20 52 45 47 45 58 50 2c 20 61 6e 64 20  OB, REGEXP, and 
f6c0: 4d 41 54 43 48 29 20 72 65 76 65 72 73 65 20 0d  MATCH) reverse .
f6d0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65  .        /// the
f6e0: 20 6f 72 64 65 72 20 6f 66 20 74 68 65 69 72 20   order of their 
f6f0: 61 72 67 75 6d 65 6e 74 73 2e 20 53 6f 20 22 6c  arguments. So "l
f700: 69 6b 65 28 41 2c 42 29 22 20 69 73 20 65 71 75  ike(A,B)" is equ
f710: 69 76 61 6c 65 6e 74 20 74 6f 20 22 42 20 6c 69  ivalent to "B li
f720: 6b 65 20 41 22 2e 20 0d 0a 20 20 20 20 20 20 20  ke A". ..       
f730: 20 2f 2f 2f 20 46 6f 72 20 74 68 65 20 66 6f 72   /// For the for
f740: 6d 20 22 42 20 6c 69 6b 65 20 41 22 20 74 68 65  m "B like A" the
f750: 20 42 20 74 65 72 6d 20 69 73 20 63 6f 6e 73 69   B term is consi
f760: 64 65 72 65 64 20 74 68 65 20 66 69 72 73 74 20  dered the first 
f770: 61 72 67 75 6d 65 6e 74 20 0d 0a 20 20 20 20 20  argument ..     
f780: 20 20 20 2f 2f 2f 20 74 6f 20 74 68 65 20 66 75     /// to the fu
f790: 6e 63 74 69 6f 6e 2e 20 42 75 74 20 66 6f 72 20  nction. But for 
f7a0: 22 6c 69 6b 65 28 41 2c 42 29 22 20 74 68 65 20  "like(A,B)" the 
f7b0: 41 20 74 65 72 6d 20 69 73 20 63 6f 6e 73 69 64  A term is consid
f7c0: 65 72 65 64 20 74 68 65 20 0d 0a 20 20 20 20 20  ered the ..     
f7d0: 20 20 20 2f 2f 2f 20 66 69 72 73 74 20 61 72 67     /// first arg
f7e0: 75 6d 65 6e 74 2e 0d 0a 20 20 20 20 20 20 20 20  ument...        
f7f0: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
f800: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
f810: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65  .        /// The
f820: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
f830: 72 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  r returned by th
f840: 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
f850: 62 65 20 76 61 6c 69 64 20 66 6f 72 0d 0a 20 20  be valid for..  
f860: 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 20 6c 69        /// the li
f870: 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20 73 71  fetime of the sq
f880: 6c 69 74 65 33 5f 76 74 61 62 20 6f 62 6a 65 63  lite3_vtab objec
f890: 74 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 66  t given in the f
f8a0: 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0d  irst parameter..
f8b0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
f8c0: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
f8d0: 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a 20 20  / </summary>..  
f8e0: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d        /// <param
f8f0: 20 6e 61 6d 65 3d 22 70 56 74 61 62 22 3e 0d 0a   name="pVtab">..
f900: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20          /// The 
f910: 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72 20 74  native pointer t
f920: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 74  o the sqlite3_vt
f930: 61 62 20 64 65 72 69 76 65 64 20 73 74 72 75 63  ab derived struc
f940: 74 75 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f  ture...        /
f950: 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20  // </param>..   
f960: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20       /// <param 
f970: 6e 61 6d 65 3d 22 6e 41 72 67 22 3e 0d 0a 20 20  name="nArg">..  
f980: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e 75        /// The nu
f990: 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
f9a0: 73 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f  s to the functio
f9b0: 6e 20 62 65 69 6e 67 20 73 6f 75 67 68 74 2e 0d  n being sought..
f9c0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
f9d0: 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f  aram>..        /
f9e0: 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22  // <param name="
f9f0: 7a 4e 61 6d 65 22 3e 0d 0a 20 20 20 20 20 20 20  zName">..       
fa00: 20 2f 2f 2f 20 54 68 65 20 6e 61 6d 65 20 6f 66   /// The name of
fa10: 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65   the function be
fa20: 69 6e 67 20 73 6f 75 67 68 74 2e 0d 0a 20 20 20  ing sought...   
fa30: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d       /// </param
fa40: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
fa50: 70 61 72 61 6d 20 6e 61 6d 65 3d 22 63 61 6c 6c  param name="call
fa60: 62 61 63 6b 22 3e 0d 0a 20 20 20 20 20 20 20 20  back">..        
fa70: 2f 2f 2f 20 55 70 6f 6e 20 73 75 63 63 65 73 73  /// Upon success
fa80: 2c 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  , this parameter
fa90: 20 6d 75 73 74 20 62 65 20 6d 6f 64 69 66 69 65   must be modifie
faa0: 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 74 68 65  d to contain the
fab0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 64 65  ..        /// de
fac0: 6c 65 67 61 74 65 20 72 65 73 70 6f 6e 73 69 62  legate responsib
fad0: 6c 65 20 66 6f 72 20 69 6d 70 6c 65 6d 65 6e 74  le for implement
fae0: 69 6e 67 20 74 68 65 20 73 70 65 63 69 66 69 65  ing the specifie
faf0: 64 20 66 75 6e 63 74 69 6f 6e 2e 0d 0a 20 20 20  d function...   
fb00: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d       /// </param
fb10: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
fb20: 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 43 6c 69  param name="pCli
fb30: 65 6e 74 44 61 74 61 22 3e 0d 0a 20 20 20 20 20  entData">..     
fb40: 20 20 20 2f 2f 2f 20 55 70 6f 6e 20 73 75 63 63     /// Upon succ
fb50: 65 73 73 2c 20 74 68 69 73 20 70 61 72 61 6d 65  ess, this parame
fb60: 74 65 72 20 6d 75 73 74 20 62 65 20 6d 6f 64 69  ter must be modi
fb70: 66 69 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  fied to contain 
fb80: 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  the..        ///
fb90: 20 6e 61 74 69 76 65 20 75 73 65 72 2d 64 61 74   native user-dat
fba0: 61 20 70 6f 69 6e 74 65 72 20 61 73 73 6f 63 69  a pointer associ
fbb0: 61 74 65 64 20 77 69 74 68 0d 0a 20 20 20 20 20  ated with..     
fbc0: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 72 65 66     /// <paramref
fbd0: 20 6e 61 6d 65 3d 22 63 61 6c 6c 62 61 63 6b 22   name="callback"
fbe0: 20 2f 3e 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f   />...        //
fbf0: 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20  / </param>..    
fc00: 20 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72 6e 73      /// <returns
fc10: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 4e  >..        /// N
fc20: 6f 6e 2d 7a 65 72 6f 20 69 66 20 74 68 65 20 73  on-zero if the s
fc30: 70 65 63 69 66 69 65 64 20 66 75 6e 63 74 69 6f  pecified functio
fc40: 6e 20 77 61 73 20 66 6f 75 6e 64 3b 20 7a 65 72  n was found; zer
fc50: 6f 20 6f 74 68 65 72 77 69 73 65 2e 0d 0a 20 20  o otherwise...  
fc60: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72 65 74 75        /// </retu
fc70: 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 69 6e  rns>..        in
fc80: 74 20 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 28  t xFindFunction(
fc90: 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 49 6e  ..            In
fca0: 74 50 74 72 20 70 56 74 61 62 2c 0d 0a 20 20 20  tPtr pVtab,..   
fcb0: 20 20 20 20 20 20 20 20 20 69 6e 74 20 6e 41 72           int nAr
fcc0: 67 2c 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20  g,..            
fcd0: 49 6e 74 50 74 72 20 7a 4e 61 6d 65 2c 0d 0a 20  IntPtr zName,.. 
fce0: 20 20 20 20 20 20 20 20 20 20 20 72 65 66 20 53             ref S
fcf0: 51 4c 69 74 65 43 61 6c 6c 62 61 63 6b 20 63 61  QLiteCallback ca
fd00: 6c 6c 62 61 63 6b 2c 0d 0a 20 20 20 20 20 20 20  llback,..       
fd10: 20 20 20 20 20 72 65 66 20 49 6e 74 50 74 72 20       ref IntPtr 
fd20: 70 43 6c 69 65 6e 74 44 61 74 61 0d 0a 20 20 20  pClientData..   
fd30: 20 20 20 20 20 20 20 20 20 29 3b 0d 0a 0d 0a 20           );.... 
fd40: 20 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f         /////////
fd50: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
fd60: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
fd70: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
fd80: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a  //////////////..
fd90: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 73  ..        /// <s
fda0: 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20  ummary>..       
fdb0: 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65   /// <para><code
fdc0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69  >..        /// i
fdd0: 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71  nt (*xRename)(sq
fde0: 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61  lite3_vtab *pVta
fdf0: 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  b, const char *z
fe00: 4e 65 77 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f  New);..        /
fe10: 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61  // </code></para
fe20: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
fe30: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
fe40: 2f 2f 20 54 68 69 73 20 6d 65 74 68 6f 64 20 70  // This method p
fe50: 72 6f 76 69 64 65 73 20 6e 6f 74 69 66 69 63 61  rovides notifica
fe60: 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20 76 69  tion that the vi
fe70: 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c  rtual table impl
fe80: 65 6d 65 6e 74 61 74 69 6f 6e 0d 0a 20 20 20 20  ementation..    
fe90: 20 20 20 20 2f 2f 2f 20 74 68 61 74 20 74 68 65      /// that the
fea0: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 77   virtual table w
feb0: 69 6c 6c 20 62 65 20 67 69 76 65 6e 20 61 20 6e  ill be given a n
fec0: 65 77 20 6e 61 6d 65 2e 20 0d 0a 20 20 20 20 20  ew name. ..     
fed0: 20 20 20 2f 2f 2f 20 49 66 20 74 68 69 73 20 6d     /// If this m
fee0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 53 51  ethod returns SQ
fef0: 4c 49 54 45 5f 4f 4b 20 74 68 65 6e 20 53 51 4c  LITE_OK then SQL
ff00: 69 74 65 20 72 65 6e 61 6d 65 73 20 74 68 65 20  ite renames the 
ff10: 74 61 62 6c 65 2e 0d 0a 20 20 20 20 20 20 20 20  table...        
ff20: 2f 2f 2f 20 49 66 20 74 68 69 73 20 6d 65 74 68  /// If this meth
ff30: 6f 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72  od returns an er
ff40: 72 6f 72 20 63 6f 64 65 20 74 68 65 6e 20 74 68  ror code then th
ff50: 65 20 72 65 6e 61 6d 69 6e 67 20 69 73 20 70 72  e renaming is pr
ff60: 65 76 65 6e 74 65 64 2e 0d 0a 20 20 20 20 20 20  evented...      
ff70: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
ff80: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
ff90: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54  >..        /// T
ffa0: 68 65 20 78 52 65 6e 61 6d 65 20 6d 65 74 68 6f  he xRename metho
ffb0: 64 20 69 73 20 72 65 71 75 69 72 65 64 20 66 6f  d is required fo
ffc0: 72 20 65 76 65 72 79 20 76 69 72 74 75 61 6c 20  r every virtual 
ffd0: 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
ffe0: 74 69 6f 6e 2e 0d 0a 20 20 20 20 20 20 20 20 2f  tion...        /
fff0: 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  // </para>..    
10000 20 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72      /// </summar
10010 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  y>..        /// 
10020 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 56 74  <param name="pVt
10030 61 62 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ab">..        //
10040 2f 20 54 68 65 20 6e 61 74 69 76 65 20 70 6f 69  / The native poi
10050 6e 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  nter to the sqli
10060 74 65 33 5f 76 74 61 62 20 64 65 72 69 76 65 64  te3_vtab derived
10070 20 73 74 72 75 63 74 75 72 65 2e 0d 0a 20 20 20   structure...   
10080 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d       /// </param
10090 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
100a0 70 61 72 61 6d 20 6e 61 6d 65 3d 22 7a 4e 65 77  param name="zNew
100b0 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ">..        /// 
100c0 54 68 65 20 6e 61 74 69 76 65 20 70 6f 69 6e 74  The native point
100d0 65 72 20 74 6f 20 74 68 65 20 55 54 46 2d 38 20  er to the UTF-8 
100e0 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 20 63  encoded string c
100f0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65  ontaining the ne
10100 77 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6e  w..        /// n
10110 61 6d 65 20 66 6f 72 20 74 68 65 20 76 69 72 74  ame for the virt
10120 75 61 6c 20 74 61 62 6c 65 2e 0d 0a 20 20 20 20  ual table...    
10130 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e      /// </param>
10140 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 72  ..        /// <r
10150 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20  eturns>..       
10160 20 2f 2f 2f 20 41 20 73 74 61 6e 64 61 72 64 20   /// A standard 
10170 53 51 4c 69 74 65 20 72 65 74 75 72 6e 20 63 6f  SQLite return co
10180 64 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  de...        ///
10190 20 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20   </returns>..   
101a0 20 20 20 20 20 53 51 4c 69 74 65 45 72 72 6f 72       SQLiteError
101b0 43 6f 64 65 20 78 52 65 6e 61 6d 65 28 0d 0a 20  Code xRename(.. 
101c0 20 20 20 20 20 20 20 20 20 20 20 49 6e 74 50 74             IntPt
101d0 72 20 70 56 74 61 62 2c 0d 0a 20 20 20 20 20 20  r pVtab,..      
101e0 20 20 20 20 20 20 49 6e 74 50 74 72 20 7a 4e 65        IntPtr zNe
101f0 77 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 29  w..            )
10200 3b 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ;....        ///
10210 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
10220 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
10230 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
10240 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
10250 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 20 20 20 20  ////....        
10260 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20  /// <summary>.. 
10270 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
10280 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20  ><code>..       
10290 20 2f 2f 2f 20 69 6e 74 20 28 2a 78 53 61 76 65   /// int (*xSave
102a0 70 6f 69 6e 74 29 28 73 71 6c 69 74 65 33 5f 76  point)(sqlite3_v
102b0 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 29  tab *pVtab, int)
102c0 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69  ;..        /// i
102d0 6e 74 20 28 2a 78 52 65 6c 65 61 73 65 29 28 73  nt (*xRelease)(s
102e0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74  qlite3_vtab *pVt
102f0 61 62 2c 20 69 6e 74 29 3b 0d 0a 20 20 20 20 20  ab, int);..     
10300 20 20 20 2f 2f 2f 20 69 6e 74 20 28 2a 78 52 6f     /// int (*xRo
10310 6c 6c 62 61 63 6b 54 6f 29 28 73 71 6c 69 74 65  llbackTo)(sqlite
10320 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69  3_vtab *pVtab, i
10330 6e 74 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f  nt);..        //
10340 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e  / </code></para>
10350 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
10360 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
10370 2f 20 54 68 65 73 65 20 6d 65 74 68 6f 64 73 20  / These methods 
10380 70 72 6f 76 69 64 65 20 74 68 65 20 76 69 72 74  provide the virt
10390 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
103a0 65 6e 74 61 74 69 6f 6e 20 61 6e 20 6f 70 70 6f  entation an oppo
103b0 72 74 75 6e 69 74 79 20 74 6f 0d 0a 20 20 20 20  rtunity to..    
103c0 20 20 20 20 2f 2f 2f 20 69 6d 70 6c 65 6d 65 6e      /// implemen
103d0 74 20 6e 65 73 74 65 64 20 74 72 61 6e 73 61 63  t nested transac
103e0 74 69 6f 6e 73 2e 20 20 54 68 65 79 20 61 72 65  tions.  They are
103f0 20 61 6c 77 61 79 73 20 6f 70 74 69 6f 6e 61 6c   always optional
10400 20 61 6e 64 20 77 69 6c 6c 20 6f 6e 6c 79 20 62   and will only b
10410 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 63  e..        /// c
10420 61 6c 6c 65 64 20 69 6e 20 53 51 4c 69 74 65 20  alled in SQLite 
10430 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 20 28 32  version 3.7.7 (2
10440 30 31 31 2d 30 36 2d 32 33 29 20 61 6e 64 20 6c  011-06-23) and l
10450 61 74 65 72 2e 0d 0a 20 20 20 20 20 20 20 20 2f  ater...        /
10460 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  // </para>..    
10470 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a      /// <para>..
10480 20 20 20 20 20 20 20 20 2f 2f 2f 20 57 68 65 6e          /// When
10490 20 78 53 61 76 65 70 6f 69 6e 74 28 58 2c 4e 29   xSavepoint(X,N)
104a0 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 61   is invoked, tha
104b0 74 20 69 73 20 61 20 73 69 67 6e 61 6c 20 74 6f  t is a signal to
104c0 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
104d0 6c 65 20 58 0d 0a 20 20 20 20 20 20 20 20 2f 2f  le X..        //
104e0 2f 20 74 68 61 74 20 69 74 20 73 68 6f 75 6c 64  / that it should
104f0 20 73 61 76 65 20 69 74 73 20 63 75 72 72 65 6e   save its curren
10500 74 20 73 74 61 74 65 20 61 73 20 73 61 76 65 70  t state as savep
10510 6f 69 6e 74 20 4e 2e 20 20 0d 0a 20 20 20 20 20  oint N.  ..     
10520 20 20 20 2f 2f 2f 20 41 20 73 75 62 73 65 71 75     /// A subsequ
10530 65 6e 74 20 63 61 6c 6c 0d 0a 20 20 20 20 20 20  ent call..      
10540 20 20 2f 2f 2f 20 74 6f 20 78 52 6f 6c 6c 62 61    /// to xRollba
10550 63 6b 54 6f 28 58 2c 52 29 20 6d 65 61 6e 73 20  ckTo(X,R) means 
10560 74 68 61 74 20 74 68 65 20 73 74 61 74 65 20 6f  that the state o
10570 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  f the virtual ta
10580 62 6c 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72  ble should retur
10590 6e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74  n..        /// t
105a0 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 77 68  o what it was wh
105b0 65 6e 20 78 53 61 76 65 70 6f 69 6e 74 28 58 2c  en xSavepoint(X,
105c0 52 29 20 77 61 73 20 6c 61 73 74 20 63 61 6c 6c  R) was last call
105d0 65 64 2e 20 20 0d 0a 20 20 20 20 20 20 20 20 2f  ed.  ..        /
105e0 2f 2f 20 54 68 65 20 63 61 6c 6c 0d 0a 20 20 20  // The call..   
105f0 20 20 20 20 20 2f 2f 2f 20 74 6f 20 78 52 6f 6c       /// to xRol
10600 6c 62 61 63 6b 54 6f 28 58 2c 52 29 20 77 69 6c  lbackTo(X,R) wil
10610 6c 20 69 6e 76 61 6c 69 64 61 74 65 20 61 6c 6c  l invalidate all
10620 20 73 61 76 65 70 6f 69 6e 74 73 20 77 69 74 68   savepoints with
10630 20 4e 3e 52 3b 20 6e 6f 6e 65 20 6f 66 20 74 68   N>R; none of th
10640 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69  e..        /// i
10650 6e 76 61 6c 69 64 65 64 20 73 61 76 65 70 6f 69  nvalided savepoi
10660 6e 74 73 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c  nts will be roll
10670 65 64 20 62 61 63 6b 20 6f 72 20 72 65 6c 65 61  ed back or relea
10680 73 65 64 20 77 69 74 68 6f 75 74 20 66 69 72 73  sed without firs
10690 74 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 62  t..        /// b
106a0 65 69 6e 67 20 72 65 69 6e 69 74 69 61 6c 69 7a  eing reinitializ
106b0 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20  ed by a call to 
106c0 78 53 61 76 65 70 6f 69 6e 74 28 29 2e 20 20 0d  xSavepoint().  .
106d0 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 20 63  .        /// A c
106e0 61 6c 6c 20 74 6f 20 78 52 65 6c 65 61 73 65 28  all to xRelease(
106f0 58 2c 4d 29 20 69 6e 76 61 6c 69 64 61 74 65 73  X,M) invalidates
10700 20 61 6c 6c 20 73 61 76 65 70 6f 69 6e 74 73 20   all savepoints 
10710 77 68 65 72 65 20 4e 3e 3d 4d 2e 0d 0a 20 20 20  where N>=M...   
10720 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e       /// </para>
10730 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
10740 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
10750 2f 20 4e 6f 6e 65 20 6f 66 20 74 68 65 20 78 53  / None of the xS
10760 61 76 65 70 6f 69 6e 74 28 29 2c 20 78 52 65 6c  avepoint(), xRel
10770 65 61 73 65 28 29 2c 20 6f 72 20 78 52 6f 6c 6c  ease(), or xRoll
10780 62 61 63 6b 54 6f 28 29 20 6d 65 74 68 6f 64 73  backTo() methods
10790 20 77 69 6c 6c 20 65 76 65 72 0d 0a 20 20 20 20   will ever..    
107a0 20 20 20 20 2f 2f 2f 20 62 65 20 63 61 6c 6c 65      /// be calle
107b0 64 20 65 78 63 65 70 74 20 69 6e 20 62 65 74 77  d except in betw
107c0 65 65 6e 20 63 61 6c 6c 73 20 74 6f 20 78 42 65  een calls to xBe
107d0 67 69 6e 28 29 20 61 6e 64 20 0d 0a 20 20 20 20  gin() and ..    
107e0 20 20 20 20 2f 2f 2f 20 65 69 74 68 65 72 20 78      /// either x
107f0 43 6f 6d 6d 69 74 28 29 20 6f 72 20 78 52 6f 6c  Commit() or xRol
10800 6c 62 61 63 6b 28 29 2e 0d 0a 20 20 20 20 20 20  lback()...      
10810 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
10820 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d         /// </sum
10830 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f  mary>..        /
10840 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22  // <param name="
10850 70 56 74 61 62 22 3e 0d 0a 20 20 20 20 20 20 20  pVtab">..       
10860 20 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76 65 20   /// The native 
10870 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73  pointer to the s
10880 71 6c 69 74 65 33 5f 76 74 61 62 20 64 65 72 69  qlite3_vtab deri
10890 76 65 64 20 73 74 72 75 63 74 75 72 65 2e 0d 0a  ved structure...
108a0 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
108b0 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ram>..        //
108c0 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 69  / <param name="i
108d0 53 61 76 65 70 6f 69 6e 74 22 3e 0d 0a 20 20 20  Savepoint">..   
108e0 20 20 20 20 20 2f 2f 2f 20 54 68 69 73 20 69 73       /// This is
108f0 20 61 6e 20 69 6e 74 65 67 65 72 20 69 64 65 6e   an integer iden
10900 74 69 66 69 65 72 20 75 6e 64 65 72 20 77 68 69  tifier under whi
10910 63 68 20 74 68 65 20 74 68 65 20 63 75 72 72 65  ch the the curre
10920 6e 74 20 73 74 61 74 65 20 6f 66 0d 0a 20 20 20  nt state of..   
10930 20 20 20 20 20 2f 2f 2f 20 74 68 65 20 76 69 72       /// the vir
10940 74 75 61 6c 20 74 61 62 6c 65 20 73 68 6f 75 6c  tual table shoul
10950 64 20 62 65 20 73 61 76 65 64 2e 0d 0a 20 20 20  d be saved...   
10960 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d       /// </param
10970 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
10980 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20  returns>..      
10990 20 20 2f 2f 2f 20 41 20 73 74 61 6e 64 61 72 64    /// A standard
109a0 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 20 63   SQLite return c
109b0 6f 64 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ode...        //
109c0 2f 20 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a 20 20  / </returns>..  
109d0 20 20 20 20 20 20 53 51 4c 69 74 65 45 72 72 6f        SQLiteErro
109e0 72 43 6f 64 65 20 78 53 61 76 65 70 6f 69 6e 74  rCode xSavepoint
109f0 28 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 49  (..            I
10a00 6e 74 50 74 72 20 70 56 74 61 62 2c 0d 0a 20 20  ntPtr pVtab,..  
10a10 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 69 53            int iS
10a20 61 76 65 70 6f 69 6e 74 0d 0a 20 20 20 20 20 20  avepoint..      
10a30 20 20 20 20 20 20 29 3b 0d 0a 0d 0a 20 20 20 20        );....    
10a40 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f      ////////////
10a50 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
10a60 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
10a70 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
10a80 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20  ///////////.... 
10a90 20 20 20 20 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d         /// <summ
10aa0 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ary>..        //
10ab0 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a  / <para><code>..
10ac0 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e 74 20          /// int 
10ad0 28 2a 78 53 61 76 65 70 6f 69 6e 74 29 28 73 71  (*xSavepoint)(sq
10ae0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61  lite3_vtab *pVta
10af0 62 2c 20 69 6e 74 29 3b 0d 0a 20 20 20 20 20 20  b, int);..      
10b00 20 20 2f 2f 2f 20 69 6e 74 20 28 2a 78 52 65 6c    /// int (*xRel
10b10 65 61 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74  ease)(sqlite3_vt
10b20 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 29 3b  ab *pVtab, int);
10b30 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e  ..        /// in
10b40 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 54 6f 29  t (*xRollbackTo)
10b50 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
10b60 56 74 61 62 2c 20 69 6e 74 29 3b 0d 0a 20 20 20  Vtab, int);..   
10b70 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e       /// </code>
10b80 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
10b90 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20   /// <para>..   
10ba0 20 20 20 20 20 2f 2f 2f 20 54 68 65 73 65 20 6d       /// These m
10bb0 65 74 68 6f 64 73 20 70 72 6f 76 69 64 65 20 74  ethods provide t
10bc0 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
10bd0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
10be0 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 20 74  an opportunity t
10bf0 6f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69  o..        /// i
10c00 6d 70 6c 65 6d 65 6e 74 20 6e 65 73 74 65 64 20  mplement nested 
10c10 74 72 61 6e 73 61 63 74 69 6f 6e 73 2e 20 20 54  transactions.  T
10c20 68 65 79 20 61 72 65 20 61 6c 77 61 79 73 20 6f  hey are always o
10c30 70 74 69 6f 6e 61 6c 20 61 6e 64 20 77 69 6c 6c  ptional and will
10c40 20 6f 6e 6c 79 20 62 65 0d 0a 20 20 20 20 20 20   only be..      
10c50 20 20 2f 2f 2f 20 63 61 6c 6c 65 64 20 69 6e 20    /// called in 
10c60 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
10c70 2e 37 2e 37 20 28 32 30 31 31 2d 30 36 2d 32 33  .7.7 (2011-06-23
10c80 29 20 61 6e 64 20 6c 61 74 65 72 2e 0d 0a 20 20  ) and later...  
10c90 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61        /// </para
10ca0 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
10cb0 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
10cc0 2f 2f 20 57 68 65 6e 20 78 53 61 76 65 70 6f 69  // When xSavepoi
10cd0 6e 74 28 58 2c 4e 29 20 69 73 20 69 6e 76 6f 6b  nt(X,N) is invok
10ce0 65 64 2c 20 74 68 61 74 20 69 73 20 61 20 73 69  ed, that is a si
10cf0 67 6e 61 6c 20 74 6f 20 74 68 65 20 76 69 72 74  gnal to the virt
10d00 75 61 6c 20 74 61 62 6c 65 20 58 0d 0a 20 20 20  ual table X..   
10d10 20 20 20 20 20 2f 2f 2f 20 74 68 61 74 20 69 74       /// that it
10d20 20 73 68 6f 75 6c 64 20 73 61 76 65 20 69 74 73   should save its
10d30 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 61   current state a
10d40 73 20 73 61 76 65 70 6f 69 6e 74 20 4e 2e 20 20  s savepoint N.  
10d50 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 20  ..        /// A 
10d60 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 0d  subsequent call.
10d70 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 6f 20  .        /// to 
10d80 78 52 6f 6c 6c 62 61 63 6b 54 6f 28 58 2c 52 29  xRollbackTo(X,R)
10d90 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
10da0 73 74 61 74 65 20 6f 66 20 74 68 65 20 76 69 72  state of the vir
10db0 74 75 61 6c 20 74 61 62 6c 65 20 73 68 6f 75 6c  tual table shoul
10dc0 64 20 72 65 74 75 72 6e 0d 0a 20 20 20 20 20 20  d return..      
10dd0 20 20 2f 2f 2f 20 74 6f 20 77 68 61 74 20 69 74    /// to what it
10de0 20 77 61 73 20 77 68 65 6e 20 78 53 61 76 65 70   was when xSavep
10df0 6f 69 6e 74 28 58 2c 52 29 20 77 61 73 20 6c 61  oint(X,R) was la
10e00 73 74 20 63 61 6c 6c 65 64 2e 20 20 0d 0a 20 20  st called.  ..  
10e10 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 63 61        /// The ca
10e20 6c 6c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ll..        /// 
10e30 74 6f 20 78 52 6f 6c 6c 62 61 63 6b 54 6f 28 58  to xRollbackTo(X
10e40 2c 52 29 20 77 69 6c 6c 20 69 6e 76 61 6c 69 64  ,R) will invalid
10e50 61 74 65 20 61 6c 6c 20 73 61 76 65 70 6f 69 6e  ate all savepoin
10e60 74 73 20 77 69 74 68 20 4e 3e 52 3b 20 6e 6f 6e  ts with N>R; non
10e70 65 20 6f 66 20 74 68 65 0d 0a 20 20 20 20 20 20  e of the..      
10e80 20 20 2f 2f 2f 20 69 6e 76 61 6c 69 64 65 64 20    /// invalided 
10e90 73 61 76 65 70 6f 69 6e 74 73 20 77 69 6c 6c 20  savepoints will 
10ea0 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 6f  be rolled back o
10eb0 72 20 72 65 6c 65 61 73 65 64 20 77 69 74 68 6f  r released witho
10ec0 75 74 20 66 69 72 73 74 0d 0a 20 20 20 20 20 20  ut first..      
10ed0 20 20 2f 2f 2f 20 62 65 69 6e 67 20 72 65 69 6e    /// being rein
10ee0 69 74 69 61 6c 69 7a 65 64 20 62 79 20 61 20 63  itialized by a c
10ef0 61 6c 6c 20 74 6f 20 78 53 61 76 65 70 6f 69 6e  all to xSavepoin
10f00 74 28 29 2e 20 20 0d 0a 20 20 20 20 20 20 20 20  t().  ..        
10f10 2f 2f 2f 20 41 20 63 61 6c 6c 20 74 6f 20 78 52  /// A call to xR
10f20 65 6c 65 61 73 65 28 58 2c 4d 29 20 69 6e 76 61  elease(X,M) inva
10f30 6c 69 64 61 74 65 73 20 61 6c 6c 20 73 61 76 65  lidates all save
10f40 70 6f 69 6e 74 73 20 77 68 65 72 65 20 4e 3e 3d  points where N>=
10f50 4d 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  M...        /// 
10f60 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
10f70 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20   /// <para>..   
10f80 20 20 20 20 20 2f 2f 2f 20 4e 6f 6e 65 20 6f 66       /// None of
10f90 20 74 68 65 20 78 53 61 76 65 70 6f 69 6e 74 28   the xSavepoint(
10fa0 29 2c 20 78 52 65 6c 65 61 73 65 28 29 2c 20 6f  ), xRelease(), o
10fb0 72 20 78 52 6f 6c 6c 62 61 63 6b 54 6f 28 29 20  r xRollbackTo() 
10fc0 6d 65 74 68 6f 64 73 20 77 69 6c 6c 20 65 76 65  methods will eve
10fd0 72 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 62  r..        /// b
10fe0 65 20 63 61 6c 6c 65 64 20 65 78 63 65 70 74 20  e called except 
10ff0 69 6e 20 62 65 74 77 65 65 6e 20 63 61 6c 6c 73  in between calls
11000 20 74 6f 20 78 42 65 67 69 6e 28 29 20 61 6e 64   to xBegin() and
11010 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 65   ..        /// e
11020 69 74 68 65 72 20 78 43 6f 6d 6d 69 74 28 29 20  ither xCommit() 
11030 6f 72 20 78 52 6f 6c 6c 62 61 63 6b 28 29 2e 0d  or xRollback()..
11040 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
11050 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
11060 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a 20 20  / </summary>..  
11070 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d        /// <param
11080 20 6e 61 6d 65 3d 22 70 56 74 61 62 22 3e 0d 0a   name="pVtab">..
11090 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20          /// The 
110a0 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72 20 74  native pointer t
110b0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 74  o the sqlite3_vt
110c0 61 62 20 64 65 72 69 76 65 64 20 73 74 72 75 63  ab derived struc
110d0 74 75 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f  ture...        /
110e0 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20  // </param>..   
110f0 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20       /// <param 
11100 6e 61 6d 65 3d 22 69 53 61 76 65 70 6f 69 6e 74  name="iSavepoint
11110 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ">..        /// 
11120 54 68 69 73 20 69 73 20 61 6e 20 69 6e 74 65 67  This is an integ
11130 65 72 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  er used to indic
11140 61 74 65 20 74 68 61 74 20 61 6e 79 20 73 61 76  ate that any sav
11150 65 64 20 73 74 61 74 65 73 20 77 69 74 68 20 61  ed states with a
11160 6e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69  n..        /// i
11170 64 65 6e 74 69 66 69 65 72 20 67 72 65 61 74 65  dentifier greate
11180 72 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  r than or equal 
11190 74 6f 20 74 68 69 73 20 73 68 6f 75 6c 64 20 62  to this should b
111a0 65 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65  e deleted by the
111b0 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 76 69  ..        /// vi
111c0 72 74 75 61 6c 20 74 61 62 6c 65 2e 0d 0a 20 20  rtual table...  
111d0 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61        /// </para
111e0 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  m>..        /// 
111f0 3c 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20  <returns>..     
11200 20 20 20 2f 2f 2f 20 41 20 73 74 61 6e 64 61 72     /// A standar
11210 64 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 20  d SQLite return 
11220 63 6f 64 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f  code...        /
11230 2f 2f 20 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a 20  // </returns>.. 
11240 20 20 20 20 20 20 20 53 51 4c 69 74 65 45 72 72         SQLiteErr
11250 6f 72 43 6f 64 65 20 78 52 65 6c 65 61 73 65 28  orCode xRelease(
11260 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 49 6e  ..            In
11270 74 50 74 72 20 70 56 74 61 62 2c 0d 0a 20 20 20  tPtr pVtab,..   
11280 20 20 20 20 20 20 20 20 20 69 6e 74 20 69 53 61           int iSa
11290 76 65 70 6f 69 6e 74 0d 0a 20 20 20 20 20 20 20  vepoint..       
112a0 20 20 20 20 20 29 3b 0d 0a 0d 0a 20 20 20 20 20       );....     
112b0 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f     /////////////
112c0 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
112d0 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
112e0 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
112f0 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20  //////////....  
11300 20 20 20 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61        /// <summa
11310 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ry>..        ///
11320 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20   <para><code>.. 
11330 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e 74 20 28         /// int (
11340 2a 78 53 61 76 65 70 6f 69 6e 74 29 28 73 71 6c  *xSavepoint)(sql
11350 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62  ite3_vtab *pVtab
11360 2c 20 69 6e 74 29 3b 0d 0a 20 20 20 20 20 20 20  , int);..       
11370 20 2f 2f 2f 20 69 6e 74 20 28 2a 78 52 65 6c 65   /// int (*xRele
11380 61 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ase)(sqlite3_vta
11390 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 29 3b 0d  b *pVtab, int);.
113a0 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e 74  .        /// int
113b0 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 54 6f 29 28   (*xRollbackTo)(
113c0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
113d0 74 61 62 2c 20 69 6e 74 29 3b 0d 0a 20 20 20 20  tab, int);..    
113e0 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c      /// </code><
113f0 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
11400 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20  /// <para>..    
11410 20 20 20 20 2f 2f 2f 20 54 68 65 73 65 20 6d 65      /// These me
11420 74 68 6f 64 73 20 70 72 6f 76 69 64 65 20 74 68  thods provide th
11430 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  e virtual table 
11440 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61  implementation a
11450 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 20 74 6f  n opportunity to
11460 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6d  ..        /// im
11470 70 6c 65 6d 65 6e 74 20 6e 65 73 74 65 64 20 74  plement nested t
11480 72 61 6e 73 61 63 74 69 6f 6e 73 2e 20 20 54 68  ransactions.  Th
11490 65 79 20 61 72 65 20 61 6c 77 61 79 73 20 6f 70  ey are always op
114a0 74 69 6f 6e 61 6c 20 61 6e 64 20 77 69 6c 6c 20  tional and will 
114b0 6f 6e 6c 79 20 62 65 0d 0a 20 20 20 20 20 20 20  only be..       
114c0 20 2f 2f 2f 20 63 61 6c 6c 65 64 20 69 6e 20 53   /// called in S
114d0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
114e0 37 2e 37 20 28 32 30 31 31 2d 30 36 2d 32 33 29  7.7 (2011-06-23)
114f0 20 61 6e 64 20 6c 61 74 65 72 2e 0d 0a 20 20 20   and later...   
11500 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e       /// </para>
11510 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
11520 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
11530 2f 20 57 68 65 6e 20 78 53 61 76 65 70 6f 69 6e  / When xSavepoin
11540 74 28 58 2c 4e 29 20 69 73 20 69 6e 76 6f 6b 65  t(X,N) is invoke
11550 64 2c 20 74 68 61 74 20 69 73 20 61 20 73 69 67  d, that is a sig
11560 6e 61 6c 20 74 6f 20 74 68 65 20 76 69 72 74 75  nal to the virtu
11570 61 6c 20 74 61 62 6c 65 20 58 0d 0a 20 20 20 20  al table X..    
11580 20 20 20 20 2f 2f 2f 20 74 68 61 74 20 69 74 20      /// that it 
11590 73 68 6f 75 6c 64 20 73 61 76 65 20 69 74 73 20  should save its 
115a0 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 61 73  current state as
115b0 20 73 61 76 65 70 6f 69 6e 74 20 4e 2e 20 20 0d   savepoint N.  .
115c0 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 20 73  .        /// A s
115d0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 0d 0a  ubsequent call..
115e0 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 6f 20 78          /// to x
115f0 52 6f 6c 6c 62 61 63 6b 54 6f 28 58 2c 52 29 20  RollbackTo(X,R) 
11600 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73  means that the s
11610 74 61 74 65 20 6f 66 20 74 68 65 20 76 69 72 74  tate of the virt
11620 75 61 6c 20 74 61 62 6c 65 20 73 68 6f 75 6c 64  ual table should
11630 20 72 65 74 75 72 6e 0d 0a 20 20 20 20 20 20 20   return..       
11640 20 2f 2f 2f 20 74 6f 20 77 68 61 74 20 69 74 20   /// to what it 
11650 77 61 73 20 77 68 65 6e 20 78 53 61 76 65 70 6f  was when xSavepo
11660 69 6e 74 28 58 2c 52 29 20 77 61 73 20 6c 61 73  int(X,R) was las
11670 74 20 63 61 6c 6c 65 64 2e 20 20 0d 0a 20 20 20  t called.  ..   
11680 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 63 61 6c       /// The cal
11690 6c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74  l..        /// t
116a0 6f 20 78 52 6f 6c 6c 62 61 63 6b 54 6f 28 58 2c  o xRollbackTo(X,
116b0 52 29 20 77 69 6c 6c 20 69 6e 76 61 6c 69 64 61  R) will invalida
116c0 74 65 20 61 6c 6c 20 73 61 76 65 70 6f 69 6e 74  te all savepoint
116d0 73 20 77 69 74 68 20 4e 3e 52 3b 20 6e 6f 6e 65  s with N>R; none
116e0 20 6f 66 20 74 68 65 0d 0a 20 20 20 20 20 20 20   of the..       
116f0 20 2f 2f 2f 20 69 6e 76 61 6c 69 64 65 64 20 73   /// invalided s
11700 61 76 65 70 6f 69 6e 74 73 20 77 69 6c 6c 20 62  avepoints will b
11710 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 6f 72  e rolled back or
11720 20 72 65 6c 65 61 73 65 64 20 77 69 74 68 6f 75   released withou
11730 74 20 66 69 72 73 74 0d 0a 20 20 20 20 20 20 20  t first..       
11740 20 2f 2f 2f 20 62 65 69 6e 67 20 72 65 69 6e 69   /// being reini
11750 74 69 61 6c 69 7a 65 64 20 62 79 20 61 20 63 61  tialized by a ca
11760 6c 6c 20 74 6f 20 78 53 61 76 65 70 6f 69 6e 74  ll to xSavepoint
11770 28 29 2e 20 20 0d 0a 20 20 20 20 20 20 20 20 2f  ().  ..        /
11780 2f 2f 20 41 20 63 61 6c 6c 20 74 6f 20 78 52 65  // A call to xRe
11790 6c 65 61 73 65 28 58 2c 4d 29 20 69 6e 76 61 6c  lease(X,M) inval
117a0 69 64 61 74 65 73 20 61 6c 6c 20 73 61 76 65 70  idates all savep
117b0 6f 69 6e 74 73 20 77 68 65 72 65 20 4e 3e 3d 4d  oints where N>=M
117c0 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
117d0 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
117e0 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20  /// <para>..    
117f0 20 20 20 20 2f 2f 2f 20 4e 6f 6e 65 20 6f 66 20      /// None of 
11800 74 68 65 20 78 53 61 76 65 70 6f 69 6e 74 28 29  the xSavepoint()
11810 2c 20 78 52 65 6c 65 61 73 65 28 29 2c 20 6f 72  , xRelease(), or
11820 20 78 52 6f 6c 6c 62 61 63 6b 54 6f 28 29 20 6d   xRollbackTo() m
11830 65 74 68 6f 64 73 20 77 69 6c 6c 20 65 76 65 72  ethods will ever
11840 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 62 65  ..        /// be
11850 20 63 61 6c 6c 65 64 20 65 78 63 65 70 74 20 69   called except i
11860 6e 20 62 65 74 77 65 65 6e 20 63 61 6c 6c 73 20  n between calls 
11870 74 6f 20 78 42 65 67 69 6e 28 29 20 61 6e 64 20  to xBegin() and 
11880 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 65 69  ..        /// ei
11890 74 68 65 72 20 78 43 6f 6d 6d 69 74 28 29 20 6f  ther xCommit() o
118a0 72 20 78 52 6f 6c 6c 62 61 63 6b 28 29 2e 0d 0a  r xRollback()...
118b0 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
118c0 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
118d0 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20   </summary>..   
118e0 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20       /// <param 
118f0 6e 61 6d 65 3d 22 70 56 74 61 62 22 3e 0d 0a 20  name="pVtab">.. 
11900 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e         /// The n
11910 61 74 69 76 65 20 70 6f 69 6e 74 65 72 20 74 6f  ative pointer to
11920 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 74 61   the sqlite3_vta
11930 62 20 64 65 72 69 76 65 64 20 73 74 72 75 63 74  b derived struct
11940 75 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ure...        //
11950 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20  / </param>..    
11960 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e      /// <param n
11970 61 6d 65 3d 22 69 53 61 76 65 70 6f 69 6e 74 22  ame="iSavepoint"
11980 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54  >..        /// T
11990 68 69 73 20 69 73 20 61 6e 20 69 6e 74 65 67 65  his is an intege
119a0 72 20 69 64 65 6e 74 69 66 69 65 72 20 75 73 65  r identifier use
119b0 64 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 73  d to specify a s
119c0 70 65 63 69 66 69 63 20 73 61 76 65 64 0d 0a 20  pecific saved.. 
119d0 20 20 20 20 20 20 20 2f 2f 2f 20 73 74 61 74 65         /// state
119e0 20 66 6f 72 20 74 68 65 20 76 69 72 74 75 61 6c   for the virtual
119f0 20 74 61 62 6c 65 20 66 6f 72 20 69 74 20 74 6f   table for it to
11a00 20 72 65 73 74 6f 72 65 20 69 74 73 65 6c 66 20   restore itself 
11a10 62 61 63 6b 20 74 6f 2c 20 77 68 69 63 68 0d 0a  back to, which..
11a20 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 68 6f 75          /// shou
11a30 6c 64 20 61 6c 73 6f 20 68 61 76 65 20 74 68 65  ld also have the
11a40 20 65 66 66 65 63 74 20 6f 66 20 64 65 6c 65 74   effect of delet
11a50 69 6e 67 20 61 6c 6c 20 73 61 76 65 64 20 73 74  ing all saved st
11a60 61 74 65 73 20 77 69 74 68 20 61 6e 0d 0a 20 20  ates with an..  
11a70 20 20 20 20 20 20 2f 2f 2f 20 69 6e 74 65 67 65        /// intege
11a80 72 20 69 64 65 6e 74 69 66 69 65 72 20 67 72 65  r identifier gre
11a90 61 74 65 72 20 74 68 61 6e 20 74 68 69 73 20 6f  ater than this o
11aa0 6e 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ne...        ///
11ab0 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20   </param>..     
11ac0 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72 6e 73 3e     /// <returns>
11ad0 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 20  ..        /// A 
11ae0 73 74 61 6e 64 61 72 64 20 53 51 4c 69 74 65 20  standard SQLite 
11af0 72 65 74 75 72 6e 20 63 6f 64 65 2e 0d 0a 20 20  return code...  
11b00 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72 65 74 75        /// </retu
11b10 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 53 51  rns>..        SQ
11b20 4c 69 74 65 45 72 72 6f 72 43 6f 64 65 20 78 52  LiteErrorCode xR
11b30 6f 6c 6c 62 61 63 6b 54 6f 28 0d 0a 20 20 20 20  ollbackTo(..    
11b40 20 20 20 20 20 20 20 20 49 6e 74 50 74 72 20 70          IntPtr p
11b50 56 74 61 62 2c 0d 0a 20 20 20 20 20 20 20 20 20  Vtab,..         
11b60 20 20 20 69 6e 74 20 69 53 61 76 65 70 6f 69 6e     int iSavepoin
11b70 74 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 29  t..            )
11b80 3b 0d 0a 20 20 20 20 7d 0d 0a 20 20 20 20 23 65  ;..    }..    #e
11b90 6e 64 72 65 67 69 6f 6e 0d 0a 7d 0d 0a           ndregion..}..