System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 1d8a878808da692c0c114661070084a80ac8c778:


0000: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
0010: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0020: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0030: 2a 2a 2a 2a 2a 2a 2a 2a 2a 0d 0a 20 2a 20 41 44  *********.. * AD
0040: 4f 2e 4e 45 54 20 32 2e 30 20 44 61 74 61 20 50  O.NET 2.0 Data P
0050: 72 6f 76 69 64 65 72 20 66 6f 72 20 53 51 4c 69  rovider for SQLi
0060: 74 65 20 56 65 72 73 69 6f 6e 20 33 2e 58 0d 0a  te Version 3.X..
0070: 20 2a 20 57 72 69 74 74 65 6e 20 62 79 20 4a 6f   * Written by Jo
0080: 65 20 4d 69 73 74 61 63 68 6b 69 6e 20 28 6a 6f  e Mistachkin (jo
0090: 65 40 6d 69 73 74 61 63 68 6b 69 6e 2e 63 6f 6d  e@mistachkin.com
00a0: 29 0d 0a 20 2a 0d 0a 20 2a 20 52 65 6c 65 61 73  ).. *.. * Releas
00b0: 65 64 20 74 6f 20 74 68 65 20 70 75 62 6c 69 63  ed to the public
00c0: 20 64 6f 6d 61 69 6e 2c 20 75 73 65 20 61 74 20   domain, use at 
00d0: 79 6f 75 72 20 6f 77 6e 20 72 69 73 6b 21 0d 0a  your own risk!..
00e0: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   ***************
00f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0100: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0110: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0d 0a 0d 0a 6e 61  *********/....na
0120: 6d 65 73 70 61 63 65 20 53 79 73 74 65 6d 2e 44  mespace System.D
0130: 61 74 61 2e 53 51 4c 69 74 65 0d 0a 7b 0d 0a 20  ata.SQLite..{.. 
0140: 20 20 20 23 72 65 67 69 6f 6e 20 49 53 51 4c 69     #region ISQLi
0150: 74 65 4e 61 74 69 76 65 4d 6f 64 75 6c 65 20 49  teNativeModule I
0160: 6e 74 65 72 66 61 63 65 0d 0a 20 20 20 20 2f 2f  nterface..    //
0170: 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20  / <summary>..   
0180: 20 2f 2f 2f 20 54 68 69 73 20 69 6e 74 65 72 66   /// This interf
0190: 61 63 65 20 72 65 70 72 65 73 65 6e 74 73 20 61  ace represents a
01a0: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
01b0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 72  mplementation wr
01c0: 69 74 74 65 6e 20 69 6e 0d 0a 20 20 20 20 2f 2f  itten in..    //
01d0: 2f 20 6e 61 74 69 76 65 20 63 6f 64 65 2e 0d 0a  / native code...
01e0: 20 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72      /// </summar
01f0: 79 3e 0d 0a 20 20 20 20 70 75 62 6c 69 63 20 69  y>..    public i
0200: 6e 74 65 72 66 61 63 65 20 49 53 51 4c 69 74 65  nterface ISQLite
0210: 4e 61 74 69 76 65 4d 6f 64 75 6c 65 0d 0a 20 20  NativeModule..  
0220: 20 20 7b 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f    {..        ///
0230: 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20   <summary>..    
0240: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63      /// <para><c
0250: 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ode>..        //
0260: 2f 20 20 20 69 6e 74 20 28 2a 78 43 72 65 61 74  /   int (*xCreat
0270: 65 29 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  e)(sqlite3 *db, 
0280: 76 6f 69 64 20 2a 70 41 75 78 2c 0d 0a 20 20 20  void *pAux,..   
0290: 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 20 20 20       ///        
02a0: 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63          int argc
02b0: 2c 20 63 68 61 72 20 2a 2a 61 72 67 76 2c 0d 0a  , char **argv,..
02c0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20          ///     
02d0: 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74             sqlit
02e0: 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62  e3_vtab **ppVTab
02f0: 2c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20  ,..        ///  
0300: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 63 68                ch
0310: 61 72 20 2a 2a 70 7a 45 72 72 29 3b 0d 0a 20 20  ar **pzErr);..  
0320: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65        /// </code
0330: 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  ></para>..      
0340: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
0350: 20 20 20 20 20 20 2f 2f 2f 20 54 68 69 73 20 6d        /// This m
0360: 65 74 68 6f 64 20 69 73 20 63 61 6c 6c 65 64 20  ethod is called 
0370: 74 6f 20 63 72 65 61 74 65 20 61 20 6e 65 77 20  to create a new 
0380: 69 6e 73 74 61 6e 63 65 20 6f 66 20 61 20 76 69  instance of a vi
0390: 72 74 75 61 6c 20 74 61 62 6c 65 20 0d 0a 20 20  rtual table ..  
03a0: 20 20 20 20 20 20 2f 2f 2f 20 69 6e 20 72 65 73        /// in res
03b0: 70 6f 6e 73 65 20 74 6f 20 61 20 43 52 45 41 54  ponse to a CREAT
03c0: 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20  E VIRTUAL TABLE 
03d0: 73 74 61 74 65 6d 65 6e 74 2e 20 0d 0a 20 20 20  statement. ..   
03e0: 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 64 62 20       /// The db 
03f0: 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
0400: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 53 51  ointer to the SQ
0410: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 63 6f  Lite database co
0420: 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 0d 0a  nnection that ..
0430: 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 73 20 65          /// is e
0440: 78 65 63 75 74 69 6e 67 20 74 68 65 20 43 52 45  xecuting the CRE
0450: 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c  ATE VIRTUAL TABL
0460: 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 0d 0a 20  E statement. .. 
0470: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 70         /// The p
0480: 41 75 78 20 61 72 67 75 6d 65 6e 74 20 69 73 20  Aux argument is 
0490: 74 68 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  the copy of the 
04a0: 63 6c 69 65 6e 74 20 64 61 74 61 20 70 6f 69 6e  client data poin
04b0: 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65  ter that was the
04c0: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 66   ..        /// f
04d0: 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
04e0: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72  o the sqlite3_cr
04f0: 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 20 6f 72  eate_module() or
0500: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 71  ..        /// sq
0510: 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
0520: 75 6c 65 5f 76 32 28 29 20 63 61 6c 6c 20 74 68  ule_v2() call th
0530: 61 74 20 72 65 67 69 73 74 65 72 65 64 20 74 68  at registered th
0540: 65 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e ..        /// 
0550: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
0560: 64 75 6c 65 2e 20 0d 0a 20 20 20 20 20 20 20 20  dule. ..        
0570: 2f 2f 2f 20 54 68 65 20 61 72 67 76 20 70 61 72  /// The argv par
0580: 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 72  ameter is an arr
0590: 61 79 20 6f 66 20 61 72 67 63 20 70 6f 69 6e 74  ay of argc point
05a0: 65 72 73 20 74 6f 20 6e 75 6c 6c 20 74 65 72 6d  ers to null term
05b0: 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 2e 20  inated strings. 
05c0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
05d0: 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 2c 20  e first string, 
05e0: 61 72 67 76 5b 30 5d 2c 20 69 73 20 74 68 65 20  argv[0], is the 
05f0: 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75  name of the modu
0600: 6c 65 20 62 65 69 6e 67 20 69 6e 76 6f 6b 65 64  le being invoked
0610: 2e 20 20 20 54 68 65 0d 0a 20 20 20 20 20 20 20  .   The..       
0620: 20 2f 2f 2f 20 6d 6f 64 75 6c 65 20 6e 61 6d 65   /// module name
0630: 20 69 73 20 74 68 65 20 6e 61 6d 65 20 70 72 6f   is the name pro
0640: 76 69 64 65 64 20 61 73 20 74 68 65 20 73 65 63  vided as the sec
0650: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
0660: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 71  ..        /// sq
0670: 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
0680: 75 6c 65 28 29 20 61 6e 64 20 61 73 20 74 68 65  ule() and as the
0690: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
06a0: 20 55 53 49 4e 47 20 63 6c 61 75 73 65 20 6f 66   USING clause of
06b0: 20 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f   the..        //
06c0: 2f 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c  / CREATE VIRTUAL
06d0: 20 54 41 42 4c 45 20 73 74 61 74 65 6d 65 6e 74   TABLE statement
06e0: 20 74 68 61 74 20 69 73 20 72 75 6e 6e 69 6e 67   that is running
06f0: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54  ...        /// T
0700: 68 65 20 73 65 63 6f 6e 64 2c 20 61 72 67 76 5b  he second, argv[
0710: 31 5d 2c 20 69 73 20 74 68 65 20 6e 61 6d 65 20  1], is the name 
0720: 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
0730: 69 6e 20 77 68 69 63 68 20 74 68 65 20 6e 65 77  in which the new
0740: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
0750: 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 2e  s being created.
0760: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   The database na
0770: 6d 65 20 69 73 20 22 6d 61 69 6e 22 20 66 6f 72  me is "main" for
0780: 20 74 68 65 20 70 72 69 6d 61 72 79 20 64 61 74   the primary dat
0790: 61 62 61 73 65 2c 20 6f 72 0d 0a 20 20 20 20 20  abase, or..     
07a0: 20 20 20 2f 2f 2f 20 22 74 65 6d 70 22 20 66 6f     /// "temp" fo
07b0: 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 2c  r TEMP database,
07c0: 20 6f 72 20 74 68 65 20 6e 61 6d 65 20 67 69 76   or the name giv
07d0: 65 6e 20 61 74 20 74 68 65 20 65 6e 64 20 6f 66  en at the end of
07e0: 20 74 68 65 20 41 54 54 41 43 48 0d 0a 20 20 20   the ATTACH..   
07f0: 20 20 20 20 20 2f 2f 2f 20 73 74 61 74 65 6d 65       /// stateme
0800: 6e 74 20 66 6f 72 20 61 74 74 61 63 68 65 64 20  nt for attached 
0810: 64 61 74 61 62 61 73 65 73 2e 20 20 54 68 65 20  databases.  The 
0820: 74 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 6f 66  third element of
0830: 20 74 68 65 20 61 72 72 61 79 2c 20 61 72 67 76   the array, argv
0840: 5b 32 5d 2c 20 0d 0a 20 20 20 20 20 20 20 20 2f  [2], ..        /
0850: 2f 2f 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  // is the name o
0860: 66 20 74 68 65 20 6e 65 77 20 76 69 72 74 75 61  f the new virtua
0870: 6c 20 74 61 62 6c 65 2c 20 61 73 20 73 70 65 63  l table, as spec
0880: 69 66 69 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20  ified following 
0890: 74 68 65 20 54 41 42 4c 45 0d 0a 20 20 20 20 20  the TABLE..     
08a0: 20 20 20 2f 2f 2f 20 6b 65 79 77 6f 72 64 20 69     /// keyword i
08b0: 6e 20 74 68 65 20 43 52 45 41 54 45 20 56 49 52  n the CREATE VIR
08c0: 54 55 41 4c 20 54 41 42 4c 45 20 73 74 61 74 65  TUAL TABLE state
08d0: 6d 65 6e 74 2e 0d 0a 20 20 20 20 20 20 20 20 2f  ment...        /
08e0: 2f 2f 20 49 66 20 70 72 65 73 65 6e 74 2c 20 74  // If present, t
08f0: 68 65 20 66 6f 75 72 74 68 20 61 6e 64 20 73 75  he fourth and su
0900: 62 73 65 71 75 65 6e 74 20 73 74 72 69 6e 67 73  bsequent strings
0910: 20 69 6e 20 74 68 65 20 61 72 67 76 5b 5d 20 61   in the argv[] a
0920: 72 72 61 79 20 72 65 70 6f 72 74 20 0d 0a 20 20  rray report ..  
0930: 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 20 61 72        /// the ar
0940: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 6d  guments to the m
0950: 6f 64 75 6c 65 20 6e 61 6d 65 20 69 6e 20 74 68  odule name in th
0960: 65 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c  e CREATE VIRTUAL
0970: 20 54 41 42 4c 45 20 73 74 61 74 65 6d 65 6e 74   TABLE statement
0980: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
0990: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
09a0: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20  /// <para>..    
09b0: 20 20 20 20 2f 2f 2f 20 54 68 65 20 6a 6f 62 20      /// The job 
09c0: 6f 66 20 74 68 69 73 20 6d 65 74 68 6f 64 20 69  of this method i
09d0: 73 20 74 6f 20 63 6f 6e 73 74 72 75 63 74 20 74  s to construct t
09e0: 68 65 20 6e 65 77 20 76 69 72 74 75 61 6c 20 74  he new virtual t
09f0: 61 62 6c 65 20 6f 62 6a 65 63 74 0d 0a 20 20 20  able object..   
0a00: 20 20 20 20 20 2f 2f 2f 20 28 61 6e 20 73 71 6c       /// (an sql
0a10: 69 74 65 33 5f 76 74 61 62 20 6f 62 6a 65 63 74  ite3_vtab object
0a20: 29 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70  ) and return a p
0a30: 6f 69 6e 74 65 72 20 74 6f 20 69 74 20 69 6e 20  ointer to it in 
0a40: 2a 70 70 56 54 61 62 2e 0d 0a 20 20 20 20 20 20  *ppVTab...      
0a50: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
0a60: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
0a70: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41  >..        /// A
0a80: 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 61  s part of the ta
0a90: 73 6b 20 6f 66 20 63 72 65 61 74 69 6e 67 20 61  sk of creating a
0aa0: 20 6e 65 77 20 73 71 6c 69 74 65 33 5f 76 74 61   new sqlite3_vta
0ab0: 62 20 73 74 72 75 63 74 75 72 65 2c 20 74 68 69  b structure, thi
0ac0: 73 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  s ..        /// 
0ad0: 6d 65 74 68 6f 64 20 3c 75 3e 6d 75 73 74 3c 2f  method <u>must</
0ae0: 75 3e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  u> invoke sqlite
0af0: 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 29  3_declare_vtab()
0b00: 20 74 6f 20 74 65 6c 6c 20 74 68 65 20 53 51 4c   to tell the SQL
0b10: 69 74 65 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ite ..        //
0b20: 2f 20 63 6f 72 65 20 61 62 6f 75 74 20 74 68 65  / core about the
0b30: 20 63 6f 6c 75 6d 6e 73 20 61 6e 64 20 64 61 74   columns and dat
0b40: 61 74 79 70 65 73 20 69 6e 20 74 68 65 20 76 69  atypes in the vi
0b50: 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 0d 0a 20  rtual table. .. 
0b60: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 73         /// The s
0b70: 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76  qlite3_declare_v
0b80: 74 61 62 28 29 20 41 50 49 20 68 61 73 20 74 68  tab() API has th
0b90: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 74  e following prot
0ba0: 6f 74 79 70 65 3a 0d 0a 20 20 20 20 20 20 20 20  otype:..        
0bb0: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
0bc0: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c       /// <para><
0bd0: 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f  code>..        /
0be0: 2f 2f 20 20 20 20 20 69 6e 74 20 73 71 6c 69 74  //     int sqlit
0bf0: 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28  e3_declare_vtab(
0c00: 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e  sqlite3 *db, con
0c10: 73 74 20 63 68 61 72 20 2a 7a 43 72 65 61 74 65  st char *zCreate
0c20: 54 61 62 6c 65 29 0d 0a 20 20 20 20 20 20 20 20  Table)..        
0c30: 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72  /// </code></par
0c40: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
0c50: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
0c60: 2f 2f 2f 20 54 68 65 20 66 69 72 73 74 20 61 72  /// The first ar
0c70: 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
0c80: 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 29  3_declare_vtab()
0c90: 20 6d 75 73 74 20 62 65 20 74 68 65 20 73 61 6d   must be the sam
0ca0: 65 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e ..        /// 
0cb0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
0cc0: 69 6f 6e 20 70 6f 69 6e 74 65 72 20 61 73 20 74  ion pointer as t
0cd0: 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
0ce0: 65 72 20 74 6f 20 74 68 69 73 20 6d 65 74 68 6f  er to this metho
0cf0: 64 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  d...        /// 
0d00: 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
0d10: 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  ent to sqlite3_d
0d20: 65 63 6c 61 72 65 5f 76 74 61 62 28 29 20 6d 75  eclare_vtab() mu
0d30: 73 74 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  st a zero-termin
0d40: 61 74 65 64 20 0d 0a 20 20 20 20 20 20 20 20 2f  ated ..        /
0d50: 2f 2f 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  // UTF-8 string 
0d60: 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 61 20  that contains a 
0d70: 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41  well-formed CREA
0d80: 54 45 20 54 41 42 4c 45 20 73 74 61 74 65 6d 65  TE TABLE stateme
0d90: 6e 74 20 74 68 61 74 20 0d 0a 20 20 20 20 20 20  nt that ..      
0da0: 20 20 2f 2f 2f 20 64 65 66 69 6e 65 73 20 74 68    /// defines th
0db0: 65 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  e columns in the
0dc0: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61   virtual table a
0dd0: 6e 64 20 74 68 65 69 72 20 64 61 74 61 20 74 79  nd their data ty
0de0: 70 65 73 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f  pes. ..        /
0df0: 2f 2f 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  // The name of t
0e00: 68 65 20 74 61 62 6c 65 20 69 6e 20 74 68 69 73  he table in this
0e10: 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 73 74   CREATE TABLE st
0e20: 61 74 65 6d 65 6e 74 20 69 73 20 69 67 6e 6f 72  atement is ignor
0e30: 65 64 2c 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ed, ..        //
0e40: 2f 20 61 73 20 61 72 65 20 61 6c 6c 20 63 6f 6e  / as are all con
0e50: 73 74 72 61 69 6e 74 73 2e 20 4f 6e 6c 79 20 74  straints. Only t
0e60: 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20  he column names 
0e70: 61 6e 64 20 64 61 74 61 74 79 70 65 73 20 6d 61  and datatypes ma
0e80: 74 74 65 72 2e 0d 0a 20 20 20 20 20 20 20 20 2f  tter...        /
0e90: 2f 2f 20 54 68 65 20 43 52 45 41 54 45 20 54 41  // The CREATE TA
0ea0: 42 4c 45 20 73 74 61 74 65 6d 65 6e 74 20 73 74  BLE statement st
0eb0: 72 69 6e 67 20 6e 65 65 64 20 6e 6f 74 20 74 6f  ring need not to
0ec0: 20 62 65 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f   be ..        //
0ed0: 2f 20 68 65 6c 64 20 69 6e 20 70 65 72 73 69 73  / held in persis
0ee0: 74 65 6e 74 20 6d 65 6d 6f 72 79 2e 20 20 54 68  tent memory.  Th
0ef0: 65 20 73 74 72 69 6e 67 20 63 61 6e 20 62 65 0d  e string can be.
0f00: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 64 65 61  .        /// dea
0f10: 6c 6c 6f 63 61 74 65 64 20 61 6e 64 2f 6f 72 20  llocated and/or 
0f20: 72 65 75 73 65 64 20 61 73 20 73 6f 6f 6e 20 61  reused as soon a
0f30: 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 64 65  s the sqlite3_de
0f40: 63 6c 61 72 65 5f 76 74 61 62 28 29 0d 0a 20 20  clare_vtab()..  
0f50: 20 20 20 20 20 20 2f 2f 2f 20 72 6f 75 74 69 6e        /// routin
0f60: 65 20 72 65 74 75 72 6e 73 2e 0d 0a 20 20 20 20  e returns...    
0f70: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
0f80: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
0f90: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
0fa0: 20 54 68 65 20 78 43 72 65 61 74 65 20 6d 65 74   The xCreate met
0fb0: 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 69 6e 69  hod need not ini
0fc0: 74 69 61 6c 69 7a 65 20 74 68 65 20 70 4d 6f 64  tialize the pMod
0fd0: 75 6c 65 2c 20 6e 52 65 66 2c 20 61 6e 64 20 7a  ule, nRef, and z
0fe0: 45 72 72 4d 73 67 0d 0a 20 20 20 20 20 20 20 20  ErrMsg..        
0ff0: 2f 2f 2f 20 66 69 65 6c 64 73 20 6f 66 20 74 68  /// fields of th
1000: 65 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 6f  e sqlite3_vtab o
1010: 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69  bject.  The SQLi
1020: 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 74 61 6b  te core will tak
1030: 65 20 63 61 72 65 20 6f 66 20 0d 0a 20 20 20 20  e care of ..    
1040: 20 20 20 20 2f 2f 2f 20 74 68 61 74 20 63 68 6f      /// that cho
1050: 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  re...        ///
1060: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
1070: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
1080: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 43        /// The xC
1090: 72 65 61 74 65 20 73 68 6f 75 6c 64 20 72 65 74  reate should ret
10a0: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
10b0: 20 69 74 20 69 73 20 73 75 63 63 65 73 73 66 75   it is successfu
10c0: 6c 20 69 6e 20 0d 0a 20 20 20 20 20 20 20 20 2f  l in ..        /
10d0: 2f 2f 20 63 72 65 61 74 69 6e 67 20 74 68 65 20  // creating the 
10e0: 6e 65 77 20 76 69 72 74 75 61 6c 20 74 61 62 6c  new virtual tabl
10f0: 65 2c 20 6f 72 20 53 51 4c 49 54 45 5f 45 52 52  e, or SQLITE_ERR
1100: 4f 52 20 69 66 20 69 74 20 69 73 20 6e 6f 74 20  OR if it is not 
1110: 73 75 63 63 65 73 73 66 75 6c 2e 0d 0a 20 20 20  successful...   
1120: 20 20 20 20 20 2f 2f 2f 20 49 66 20 6e 6f 74 20       /// If not 
1130: 73 75 63 63 65 73 73 66 75 6c 2c 20 74 68 65 20  successful, the 
1140: 73 71 6c 69 74 65 33 5f 76 74 61 62 20 73 74 72  sqlite3_vtab str
1150: 75 63 74 75 72 65 20 6d 75 73 74 20 6e 6f 74 20  ucture must not 
1160: 62 65 20 61 6c 6c 6f 63 61 74 65 64 2e 20 0d 0a  be allocated. ..
1170: 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 6e 20 65          /// An e
1180: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 6d 61 79  rror message may
1190: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 72   optionally be r
11a0: 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 7a 45 72  eturned in *pzEr
11b0: 72 20 69 66 20 75 6e 73 75 63 63 65 73 73 66 75  r if unsuccessfu
11c0: 6c 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  l...        /// 
11d0: 53 70 61 63 65 20 74 6f 20 68 6f 6c 64 20 74 68  Space to hold th
11e0: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
11f0: 73 74 72 69 6e 67 20 6d 75 73 74 20 62 65 20 61  string must be a
1200: 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 0d 0a  llocated using..
1210: 20 20 20 20 20 20 20 20 2f 2f 2f 20 61 6e 20 53          /// an S
1220: 51 4c 69 74 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  QLite memory all
1230: 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  ocation function
1240: 20 6c 69 6b 65 20 0d 0a 20 20 20 20 20 20 20 20   like ..        
1250: 2f 2f 2f 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  /// sqlite3_mall
1260: 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
1270: 6d 70 72 69 6e 74 66 28 29 20 61 73 20 74 68 65  mprintf() as the
1280: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c   SQLite core wil
1290: 6c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 61  l..        /// a
12a0: 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74  ttempt to free t
12b0: 68 65 20 73 70 61 63 65 20 75 73 69 6e 67 20 73  he space using s
12c0: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61 66  qlite3_free() af
12d0: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 68 61  ter the error ha
12e0: 73 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 62  s..        /// b
12f0: 65 65 6e 20 72 65 70 6f 72 74 65 64 20 75 70 20  een reported up 
1300: 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
1310: 6f 6e 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  on...        ///
1320: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
1330: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
1340: 20 20 20 20 20 20 2f 2f 2f 20 49 66 20 74 68 65        /// If the
1350: 20 78 43 72 65 61 74 65 20 6d 65 74 68 6f 64 20   xCreate method 
1360: 69 73 20 6f 6d 69 74 74 65 64 20 28 6c 65 66 74  is omitted (left
1370: 20 61 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   as a NULL point
1380: 65 72 29 20 74 68 65 6e 20 74 68 65 0d 0a 20 20  er) then the..  
1390: 20 20 20 20 20 20 2f 2f 2f 20 76 69 72 74 75 61        /// virtua
13a0: 6c 20 74 61 62 6c 65 20 69 73 20 61 6e 20 65 70  l table is an ep
13b0: 6f 6e 79 6d 6f 75 73 2d 6f 6e 6c 79 20 76 69 72  onymous-only vir
13c0: 74 75 61 6c 20 74 61 62 6c 65 2e 20 20 4e 65 77  tual table.  New
13d0: 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 0d 0a 20   instances of.. 
13e0: 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 20 76         /// the v
13f0: 69 72 74 75 61 6c 20 74 61 62 6c 65 20 63 61 6e  irtual table can
1400: 6e 6f 74 20 62 65 20 63 72 65 61 74 65 64 20 75  not be created u
1410: 73 69 6e 67 20 43 52 45 41 54 45 20 56 49 52 54  sing CREATE VIRT
1420: 55 41 4c 20 54 41 42 4c 45 20 61 6e 64 20 74 68  UAL TABLE and th
1430: 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 76  e..        /// v
1440: 69 72 74 75 61 6c 20 74 61 62 6c 65 20 63 61 6e  irtual table can
1450: 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 76 69   only be used vi
1460: 61 20 69 74 73 20 6d 6f 64 75 6c 65 20 6e 61 6d  a its module nam
1470: 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e...        /// 
1480: 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65  Note that SQLite
1490: 20 76 65 72 73 69 6f 6e 73 20 70 72 69 6f 72 20   versions prior 
14a0: 74 6f 20 33 2e 39 2e 30 20 64 6f 20 6e 6f 74 20  to 3.9.0 do not 
14b0: 75 6e 64 65 72 73 74 61 6e 64 0d 0a 20 20 20 20  understand..    
14c0: 20 20 20 20 2f 2f 2f 20 65 70 6f 6e 79 6d 6f 75      /// eponymou
14d0: 73 2d 6f 6e 6c 79 20 76 69 72 74 75 61 6c 20 74  s-only virtual t
14e0: 61 62 6c 65 73 20 61 6e 64 20 77 69 6c 6c 20 73  ables and will s
14f0: 65 67 66 61 75 6c 74 20 69 66 20 61 6e 20 61 74  egfault if an at
1500: 74 65 6d 70 74 20 69 73 20 6d 61 64 65 0d 0a 20  tempt is made.. 
1510: 20 20 20 20 20 20 20 2f 2f 2f 20 74 6f 20 43 52         /// to CR
1520: 45 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42  EATE VIRTUAL TAB
1530: 4c 45 20 6f 6e 20 61 6e 20 65 70 6f 6e 79 6d 6f  LE on an eponymo
1540: 75 73 2d 6f 6e 6c 79 20 76 69 72 74 75 61 6c 20  us-only virtual 
1550: 74 61 62 6c 65 20 62 65 63 61 75 73 65 0d 0a 20  table because.. 
1560: 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 20 78         /// the x
1570: 43 72 65 61 74 65 20 6d 65 74 68 6f 64 20 77 61  Create method wa
1580: 73 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 66 6f  s not checked fo
1590: 72 20 6e 75 6c 6c 2e 0d 0a 20 20 20 20 20 20 20  r null...       
15a0: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
15b0: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
15c0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 49 66  ..        /// If
15d0: 20 74 68 65 20 78 43 72 65 61 74 65 20 6d 65 74   the xCreate met
15e0: 68 6f 64 20 69 73 20 74 68 65 20 65 78 61 63 74  hod is the exact
15f0: 20 73 61 6d 65 20 70 6f 69 6e 74 65 72 20 61 73   same pointer as
1600: 20 74 68 65 20 78 43 6f 6e 6e 65 63 74 20 6d 65   the xConnect me
1610: 74 68 6f 64 2c 0d 0a 20 20 20 20 20 20 20 20 2f  thod,..        /
1620: 2f 2f 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  // that indicate
1630: 73 20 74 68 61 74 20 74 68 65 20 76 69 72 74 75  s that the virtu
1640: 61 6c 20 74 61 62 6c 65 20 64 6f 65 73 20 6e 6f  al table does no
1650: 74 20 6e 65 65 64 20 74 6f 20 69 6e 69 74 69 61  t need to initia
1660: 6c 69 7a 65 20 62 61 63 6b 69 6e 67 0d 0a 20 20  lize backing..  
1670: 20 20 20 20 20 20 2f 2f 2f 20 73 74 6f 72 65 2e        /// store.
1680: 20 20 53 75 63 68 20 61 20 76 69 72 74 75 61 6c    Such a virtual
1690: 20 74 61 62 6c 65 20 63 61 6e 20 62 65 20 75 73   table can be us
16a0: 65 64 20 61 73 20 61 6e 20 65 70 6f 6e 79 6d 6f  ed as an eponymo
16b0: 75 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  us virtual table
16c0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6f 72  ..        /// or
16d0: 20 61 73 20 61 20 6e 61 6d 65 64 20 76 69 72 74   as a named virt
16e0: 75 61 6c 20 74 61 62 6c 65 20 75 73 69 6e 67 20  ual table using 
16f0: 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20 54  CREATE VIRTUAL T
1700: 41 42 4c 45 20 6f 72 20 62 6f 74 68 2e 0d 0a 20  ABLE or both... 
1710: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
1720: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
1730: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
1740: 2f 2f 2f 20 49 66 20 61 20 63 6f 6c 75 6d 6e 20  /// If a column 
1750: 64 61 74 61 74 79 70 65 20 63 6f 6e 74 61 69 6e  datatype contain
1760: 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 6b 65  s the special ke
1770: 79 77 6f 72 64 20 22 48 49 44 44 45 4e 22 0d 0a  yword "HIDDEN"..
1780: 20 20 20 20 20 20 20 20 2f 2f 2f 20 28 69 6e 20          /// (in 
1790: 61 6e 79 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  any combination 
17a0: 6f 66 20 75 70 70 65 72 20 61 6e 64 20 6c 6f 77  of upper and low
17b0: 65 72 20 63 61 73 65 20 6c 65 74 74 65 72 73 29  er case letters)
17c0: 20 74 68 65 6e 20 74 68 61 74 20 6b 65 79 77 6f   then that keywo
17d0: 72 64 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  rd..        /// 
17e0: 69 74 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  it is omitted fr
17f0: 6f 6d 20 74 68 65 20 63 6f 6c 75 6d 6e 20 64 61  om the column da
1800: 74 61 74 79 70 65 20 6e 61 6d 65 20 61 6e 64 20  tatype name and 
1810: 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 6d 61  the column is ma
1820: 72 6b 65 64 20 0d 0a 20 20 20 20 20 20 20 20 2f  rked ..        /
1830: 2f 2f 20 61 73 20 61 20 68 69 64 64 65 6e 20 63  // as a hidden c
1840: 6f 6c 75 6d 6e 20 69 6e 74 65 72 6e 61 6c 6c 79  olumn internally
1850: 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  . ..        /// 
1860: 41 20 68 69 64 64 65 6e 20 63 6f 6c 75 6d 6e 20  A hidden column 
1870: 64 69 66 66 65 72 73 20 66 72 6f 6d 20 61 20 6e  differs from a n
1880: 6f 72 6d 61 6c 20 63 6f 6c 75 6d 6e 20 69 6e 20  ormal column in 
1890: 74 68 72 65 65 20 72 65 73 70 65 63 74 73 3a 0d  three respects:.
18a0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
18b0: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
18c0: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
18d0: 20 20 2f 2f 2f 20 3c 21 5b 43 44 41 54 41 5b 3c    /// <![CDATA[<
18e0: 75 6c 3e 5d 5d 3e 0d 0a 20 20 20 20 20 20 20 20  ul>]]>..        
18f0: 2f 2f 2f 20 3c 21 5b 43 44 41 54 41 5b 3c 6c 69  /// <![CDATA[<li
1900: 3e 5d 5d 3e 20 48 69 64 64 65 6e 20 63 6f 6c 75  >]]> Hidden colu
1910: 6d 6e 73 20 61 72 65 20 6e 6f 74 20 6c 69 73 74  mns are not list
1920: 65 64 20 69 6e 20 74 68 65 20 64 61 74 61 73 65  ed in the datase
1930: 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 0d 0a  t returned by ..
1940: 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20          ///     
1950: 20 22 50 52 41 47 4d 41 20 74 61 62 6c 65 5f 69   "PRAGMA table_i
1960: 6e 66 6f 22 2c 0d 0a 20 20 20 20 20 20 20 20 2f  nfo",..        /
1970: 2f 2f 20 3c 21 5b 43 44 41 54 41 5b 3c 6c 69 3e  // <![CDATA[<li>
1980: 5d 5d 3e 20 48 69 64 64 65 6e 20 63 6f 6c 75 6d  ]]> Hidden colum
1990: 6e 73 20 61 72 65 20 6e 6f 74 20 69 6e 63 6c 75  ns are not inclu
19a0: 64 65 64 20 69 6e 20 74 68 65 20 65 78 70 61 6e  ded in the expan
19b0: 73 69 6f 6e 20 6f 66 20 61 20 22 2a 22 0d 0a 20  sion of a "*".. 
19c0: 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 20         ///      
19d0: 65 78 70 72 65 73 73 69 6f 6e 20 69 6e 20 74 68  expression in th
19e0: 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
19f0: 61 20 53 45 4c 45 43 54 2c 20 61 6e 64 0d 0a 20  a SELECT, and.. 
1a00: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 21 5b 43 44         /// <![CD
1a10: 41 54 41 5b 3c 6c 69 3e 5d 5d 3e 20 48 69 64 64  ATA[<li>]]> Hidd
1a20: 65 6e 20 63 6f 6c 75 6d 6e 73 20 61 72 65 20 6e  en columns are n
1a30: 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  ot included in t
1a40: 68 65 20 69 6d 70 6c 69 63 69 74 20 63 6f 6c 75  he implicit colu
1a50: 6d 6e 2d 6c 69 73 74 20 0d 0a 20 20 20 20 20 20  mn-list ..      
1a60: 20 20 2f 2f 2f 20 20 20 20 20 20 75 73 65 64 20    ///      used 
1a70: 62 79 20 61 6e 20 49 4e 53 45 52 54 20 73 74 61  by an INSERT sta
1a80: 74 65 6d 65 6e 74 20 74 68 61 74 20 6c 61 63 6b  tement that lack
1a90: 73 20 61 6e 20 65 78 70 6c 69 63 69 74 20 63 6f  s an explicit co
1aa0: 6c 75 6d 6e 2d 6c 69 73 74 2e 20 0d 0a 20 20 20  lumn-list. ..   
1ab0: 20 20 20 20 20 2f 2f 2f 20 3c 21 5b 43 44 41 54       /// <![CDAT
1ac0: 41 5b 3c 2f 75 6c 3e 5d 5d 3e 0d 0a 20 20 20 20  A[</ul>]]>..    
1ad0: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
1ae0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
1af0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
1b00: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66   For example, if
1b10: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   the following S
1b20: 51 4c 20 69 73 20 70 61 73 73 65 64 20 74 6f 20  QL is passed to 
1b30: 73 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f  sqlite3_declare_
1b40: 76 74 61 62 28 29 3a 0d 0a 20 20 20 20 20 20 20  vtab():..       
1b50: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
1b60: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
1b70: 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20 20  <code>..        
1b80: 2f 2f 2f 20 20 20 20 43 52 45 41 54 45 20 54 41  ///    CREATE TA
1b90: 42 4c 45 20 78 28 61 20 48 49 44 44 45 4e 20 56  BLE x(a HIDDEN V
1ba0: 41 52 43 48 41 52 28 31 32 29 2c 20 62 20 49 4e  ARCHAR(12), b IN
1bb0: 54 45 47 45 52 2c 20 63 20 49 4e 54 45 47 45 52  TEGER, c INTEGER
1bc0: 20 48 69 64 64 65 6e 29 3b 0d 0a 20 20 20 20 20   Hidden);..     
1bd0: 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f     /// </code></
1be0: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
1bf0: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20  // <para>..     
1c00: 20 20 20 2f 2f 2f 20 54 68 65 6e 20 74 68 65 20     /// Then the 
1c10: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 77 6f  virtual table wo
1c20: 75 6c 64 20 62 65 20 63 72 65 61 74 65 64 20 77  uld be created w
1c30: 69 74 68 20 74 77 6f 20 68 69 64 64 65 6e 20 63  ith two hidden c
1c40: 6f 6c 75 6d 6e 73 2c 0d 0a 20 20 20 20 20 20 20  olumns,..       
1c50: 20 2f 2f 2f 20 61 6e 64 20 77 69 74 68 20 64 61   /// and with da
1c60: 74 61 74 79 70 65 73 20 6f 66 20 22 56 41 52 43  tatypes of "VARC
1c70: 48 41 52 28 31 32 29 22 20 61 6e 64 20 22 49 4e  HAR(12)" and "IN
1c80: 54 45 47 45 52 22 2e 0d 0a 20 20 20 20 20 20 20  TEGER"...       
1c90: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
1ca0: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
1cb0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 6e  ..        /// An
1cc0: 20 65 78 61 6d 70 6c 65 20 75 73 65 20 6f 66 20   example use of 
1cd0: 68 69 64 64 65 6e 20 63 6f 6c 75 6d 6e 73 20 63  hidden columns c
1ce0: 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68  an be seen in th
1cf0: 65 20 46 54 53 33 20 76 69 72 74 75 61 6c 20 0d  e FTS3 virtual .
1d00: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 61 62  .        /// tab
1d10: 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
1d20: 6e 2c 20 77 68 65 72 65 20 65 76 65 72 79 20 46  n, where every F
1d30: 54 53 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  TS virtual table
1d40: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 63 6f  ..        /// co
1d50: 6e 74 61 69 6e 73 20 61 6e 20 46 54 53 20 68 69  ntains an FTS hi
1d60: 64 64 65 6e 20 63 6f 6c 75 6d 6e 20 74 68 61 74  dden column that
1d70: 20 69 73 20 75 73 65 64 20 74 6f 20 70 61 73 73   is used to pass
1d80: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 66 72 6f   information fro
1d90: 6d 20 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f  m the..        /
1da0: 2f 2f 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  // virtual table
1db0: 20 69 6e 74 6f 20 46 54 53 20 61 75 78 69 6c 69   into FTS auxili
1dc0: 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  ary functions an
1dd0: 64 20 74 6f 20 74 68 65 20 46 54 53 20 4d 41 54  d to the FTS MAT
1de0: 43 48 20 6f 70 65 72 61 74 6f 72 2e 0d 0a 20 20  CH operator...  
1df0: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61        /// </para
1e00: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
1e10: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
1e20: 2f 2f 20 41 20 76 69 72 74 75 61 6c 20 74 61 62  // A virtual tab
1e30: 6c 65 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73  le that contains
1e40: 20 68 69 64 64 65 6e 20 63 6f 6c 75 6d 6e 73 20   hidden columns 
1e50: 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 6b 65  can be used like
1e60: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 61 20  ..        /// a 
1e70: 74 61 62 6c 65 2d 76 61 6c 75 65 64 20 66 75 6e  table-valued fun
1e80: 63 74 69 6f 6e 20 69 6e 20 74 68 65 20 46 52 4f  ction in the FRO
1e90: 4d 20 63 6c 61 75 73 65 20 6f 66 20 61 20 53 45  M clause of a SE
1ea0: 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 0d  LECT statement..
1eb0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65  .        /// The
1ec0: 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
1ed0: 65 20 74 61 62 6c 65 2d 76 61 6c 75 65 64 20 66  e table-valued f
1ee0: 75 6e 63 74 69 6f 6e 20 62 65 63 6f 6d 65 20 63  unction become c
1ef0: 6f 6e 73 74 72 61 69 6e 74 73 20 6f 6e 20 0d 0a  onstraints on ..
1f00: 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 20          /// the 
1f10: 48 49 44 44 45 4e 20 63 6f 6c 75 6d 6e 73 20 6f  HIDDEN columns o
1f20: 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  f the virtual ta
1f30: 62 6c 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ble...        //
1f40: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  / </para>..     
1f50: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20     /// <para>.. 
1f60: 20 20 20 20 20 20 20 2f 2f 2f 20 46 6f 72 20 65         /// For e
1f70: 78 61 6d 70 6c 65 2c 20 74 68 65 20 22 67 65 6e  xample, the "gen
1f80: 65 72 61 74 65 5f 73 65 72 69 65 73 22 20 65 78  erate_series" ex
1f90: 74 65 6e 73 69 6f 6e 20 28 6c 6f 63 61 74 65 64  tension (located
1fa0: 20 69 6e 20 74 68 65 0d 0a 20 20 20 20 20 20 20   in the..       
1fb0: 20 2f 2f 2f 20 65 78 74 2f 6d 69 73 63 2f 73 65   /// ext/misc/se
1fc0: 72 69 65 73 2e 63 0d 0a 20 20 20 20 20 20 20 20  ries.c..        
1fd0: 2f 2f 2f 20 66 69 6c 65 20 69 6e 20 74 68 65 20  /// file in the 
1fe0: 73 6f 75 72 63 65 20 74 72 65 65 29 0d 0a 20 20  source tree)..  
1ff0: 20 20 20 20 20 20 2f 2f 2f 20 69 6d 70 6c 65 6d        /// implem
2000: 65 6e 74 73 20 61 6e 20 65 70 6f 6e 79 6d 6f 75  ents an eponymou
2010: 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  s virtual table 
2020: 77 69 74 68 20 74 68 65 20 66 6f 6c 6c 6f 77 69  with the followi
2030: 6e 67 20 73 63 68 65 6d 61 3a 0d 0a 20 20 20 20  ng schema:..    
2040: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
2050: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
2060: 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20  ra><code>..     
2070: 20 20 20 2f 2f 2f 20 43 52 45 41 54 45 20 54 41     /// CREATE TA
2080: 42 4c 45 20 67 65 6e 65 72 61 74 65 5f 73 65 72  BLE generate_ser
2090: 69 65 73 28 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ies(..        //
20a0: 2f 20 20 20 76 61 6c 75 65 2c 0d 0a 20 20 20 20  /   value,..    
20b0: 20 20 20 20 2f 2f 2f 20 20 20 73 74 61 72 74 20      ///   start 
20c0: 48 49 44 44 45 4e 2c 0d 0a 20 20 20 20 20 20 20  HIDDEN,..       
20d0: 20 2f 2f 2f 20 20 20 73 74 6f 70 20 48 49 44 44   ///   stop HIDD
20e0: 45 4e 2c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  EN,..        ///
20f0: 20 20 20 73 74 65 70 20 48 49 44 44 45 4e 0d 0a     step HIDDEN..
2100: 20 20 20 20 20 20 20 20 2f 2f 2f 20 29 3b 0d 0a          /// );..
2110: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f          /// </co
2120: 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  de></para>..    
2130: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a      /// <para>..
2140: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20          /// The 
2150: 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78  sqlite3_module.x
2160: 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64  BestIndex method
2170: 20 69 6e 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e   in the implemen
2180: 74 61 74 69 6f 6e 20 6f 66 20 74 68 69 73 0d 0a  tation of this..
2190: 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 61 62 6c          /// tabl
21a0: 65 20 63 68 65 63 6b 73 20 66 6f 72 20 65 71 75  e checks for equ
21b0: 61 6c 69 74 79 20 63 6f 6e 73 74 72 61 69 6e 74  ality constraint
21c0: 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 48 49  s against the HI
21d0: 44 44 45 4e 20 63 6f 6c 75 6d 6e 73 2c 20 61 6e  DDEN columns, an
21e0: 64 20 75 73 65 73 0d 0a 20 20 20 20 20 20 20 20  d uses..        
21f0: 2f 2f 2f 20 74 68 6f 73 65 20 61 73 20 69 6e 70  /// those as inp
2200: 75 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  ut parameters to
2210: 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 72   determine the r
2220: 61 6e 67 65 20 6f 66 20 69 6e 74 65 67 65 72 20  ange of integer 
2230: 22 76 61 6c 75 65 22 20 6f 75 74 70 75 74 73 0d  "value" outputs.
2240: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 6f 20  .        /// to 
2250: 67 65 6e 65 72 61 74 65 2e 20 20 52 65 61 73 6f  generate.  Reaso
2260: 6e 61 62 6c 65 20 64 65 66 61 75 6c 74 73 20 61  nable defaults a
2270: 72 65 20 75 73 65 64 20 66 6f 72 20 61 6e 79 20  re used for any 
2280: 75 6e 63 6f 6e 73 74 72 61 69 6e 65 64 20 63 6f  unconstrained co
2290: 6c 75 6d 6e 73 2e 0d 0a 20 20 20 20 20 20 20 20  lumns...        
22a0: 2f 2f 2f 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  /// For example,
22b0: 20 74 6f 20 6c 69 73 74 20 61 6c 6c 20 69 6e 74   to list all int
22c0: 65 67 65 72 73 20 62 65 74 77 65 65 6e 20 35 20  egers between 5 
22d0: 61 6e 64 20 35 30 3a 0d 0a 20 20 20 20 20 20 20  and 50:..       
22e0: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
22f0: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
2300: 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20 20  <code>..        
2310: 2f 2f 2f 20 53 45 4c 45 43 54 20 76 61 6c 75 65  /// SELECT value
2320: 20 46 52 4f 4d 20 67 65 6e 65 72 61 74 65 5f 73   FROM generate_s
2330: 65 72 69 65 73 28 35 2c 35 30 29 3b 0d 0a 20 20  eries(5,50);..  
2340: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65        /// </code
2350: 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  ></para>..      
2360: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
2370: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 70 72        /// The pr
2380: 65 76 69 6f 75 73 20 71 75 65 72 79 20 69 73 20  evious query is 
2390: 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 74 68  equivalent to th
23a0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 3a 0d 0a 20 20  e following:..  
23b0: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61        /// </para
23c0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
23d0: 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20  para><code>..   
23e0: 20 20 20 20 20 2f 2f 2f 20 53 45 4c 45 43 54 20       /// SELECT 
23f0: 76 61 6c 75 65 20 46 52 4f 4d 20 67 65 6e 65 72  value FROM gener
2400: 61 74 65 5f 73 65 72 69 65 73 20 57 48 45 52 45  ate_series WHERE
2410: 20 73 74 61 72 74 3d 35 20 41 4e 44 20 73 74 6f   start=5 AND sto
2420: 70 3d 35 30 3b 0d 0a 20 20 20 20 20 20 20 20 2f  p=50;..        /
2430: 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61  // </code></para
2440: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
2450: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
2460: 2f 2f 20 41 72 67 75 6d 65 6e 74 73 20 6f 6e 20  // Arguments on 
2470: 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
2480: 65 20 6e 61 6d 65 20 61 72 65 20 6d 61 74 63 68  e name are match
2490: 65 64 20 74 6f 20 68 69 64 64 65 6e 20 63 6f 6c  ed to hidden col
24a0: 75 6d 6e 73 0d 0a 20 20 20 20 20 20 20 20 2f 2f  umns..        //
24b0: 2f 20 69 6e 20 6f 72 64 65 72 2e 20 20 54 68 65  / in order.  The
24c0: 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
24d0: 65 6e 74 73 20 63 61 6e 20 62 65 20 6c 65 73 73  ents can be less
24e0: 20 74 68 61 6e 20 74 68 65 0d 0a 20 20 20 20 20   than the..     
24f0: 20 20 20 2f 2f 2f 20 6e 75 6d 62 65 72 20 6f 66     /// number of
2500: 20 68 69 64 64 65 6e 20 63 6f 6c 75 6d 6e 73 2c   hidden columns,
2510: 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74   in which case t
2520: 68 65 20 6c 61 74 74 65 72 20 68 69 64 64 65 6e  he latter hidden
2530: 20 63 6f 6c 75 6d 6e 73 20 61 72 65 0d 0a 20 20   columns are..  
2540: 20 20 20 20 20 20 2f 2f 2f 20 75 6e 63 6f 6e 73        /// uncons
2550: 74 72 61 69 6e 65 64 2e 20 20 48 6f 77 65 76 65  trained.  Howeve
2560: 72 2c 20 61 6e 20 65 72 72 6f 72 20 72 65 73 75  r, an error resu
2570: 6c 74 73 20 69 66 20 74 68 65 72 65 20 61 72 65  lts if there are
2580: 20 6d 6f 72 65 20 61 72 67 75 6d 65 6e 74 73 0d   more arguments.
2590: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 61  .        /// tha
25a0: 6e 20 74 68 65 72 65 20 61 72 65 20 68 69 64 64  n there are hidd
25b0: 65 6e 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  en columns in th
25c0: 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e  e virtual table.
25d0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
25e0: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
25f0: 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a 20  // </summary>.. 
2600: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
2610: 6d 20 6e 61 6d 65 3d 22 70 44 62 22 3e 0d 0a 20  m name="pDb">.. 
2620: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e         /// The n
2630: 61 74 69 76 65 20 64 61 74 61 62 61 73 65 20 63  ative database c
2640: 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65  onnection handle
2650: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
2660: 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20  /param>..       
2670: 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65   /// <param name
2680: 3d 22 70 41 75 78 22 3e 0d 0a 20 20 20 20 20 20  ="pAux">..      
2690: 20 20 2f 2f 2f 20 54 68 65 20 6f 72 69 67 69 6e    /// The origin
26a0: 61 6c 20 6e 61 74 69 76 65 20 70 6f 69 6e 74 65  al native pointe
26b0: 72 20 76 61 6c 75 65 20 74 68 61 74 20 77 61 73  r value that was
26c0: 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74 68 65   provided to the
26d0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 71  ..        /// sq
26e0: 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
26f0: 75 6c 65 28 29 2c 20 73 71 6c 69 74 65 33 5f 63  ule(), sqlite3_c
2700: 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28  reate_module_v2(
2710: 29 20 6f 72 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ) or..        //
2720: 2f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  / sqlite3_create
2730: 5f 64 69 73 70 6f 73 61 62 6c 65 5f 6d 6f 64 75  _disposable_modu
2740: 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 2e 0d  le() functions..
2750: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
2760: 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f  aram>..        /
2770: 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22  // <param name="
2780: 61 72 67 63 22 3e 0d 0a 20 20 20 20 20 20 20 20  argc">..        
2790: 2f 2f 2f 20 54 68 65 20 6e 75 6d 62 65 72 20 6f  /// The number o
27a0: 66 20 61 72 67 75 6d 65 6e 74 73 20 66 72 6f 6d  f arguments from
27b0: 20 74 68 65 20 43 52 45 41 54 45 20 56 49 52 54   the CREATE VIRT
27c0: 55 41 4c 20 54 41 42 4c 45 20 73 74 61 74 65 6d  UAL TABLE statem
27d0: 65 6e 74 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ent...        //
27e0: 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20  / </param>..    
27f0: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e      /// <param n
2800: 61 6d 65 3d 22 61 72 67 76 22 3e 0d 0a 20 20 20  ame="argv">..   
2810: 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 61 72 72       /// The arr
2820: 61 79 20 6f 66 20 73 74 72 69 6e 67 20 61 72 67  ay of string arg
2830: 75 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20  uments from the 
2840: 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20 54  CREATE VIRTUAL T
2850: 41 42 4c 45 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ABLE..        //
2860: 2f 20 73 74 61 74 65 6d 65 6e 74 2e 0d 0a 20 20  / statement...  
2870: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61        /// </para
2880: 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  m>..        /// 
2890: 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 56 74  <param name="pVt
28a0: 61 62 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ab">..        //
28b0: 2f 20 55 70 6f 6e 20 73 75 63 63 65 73 73 2c 20  / Upon success, 
28c0: 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 6d  this parameter m
28d0: 75 73 74 20 62 65 20 6d 6f 64 69 66 69 65 64 20  ust be modified 
28e0: 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
28f0: 6e 65 77 6c 79 0d 0a 20 20 20 20 20 20 20 20 2f  newly..        /
2900: 2f 2f 20 63 72 65 61 74 65 64 20 6e 61 74 69 76  // created nativ
2910: 65 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 64  e sqlite3_vtab d
2920: 65 72 69 76 65 64 20 73 74 72 75 63 74 75 72 65  erived structure
2930: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
2940: 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20  /param>..       
2950: 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65   /// <param name
2960: 3d 22 70 45 72 72 6f 72 22 3e 0d 0a 20 20 20 20  ="pError">..    
2970: 20 20 20 20 2f 2f 2f 20 55 70 6f 6e 20 66 61 69      /// Upon fai
2980: 6c 75 72 65 2c 20 74 68 69 73 20 70 61 72 61 6d  lure, this param
2990: 65 74 65 72 20 6d 75 73 74 20 62 65 20 6d 6f 64  eter must be mod
29a0: 69 66 69 65 64 20 74 6f 20 70 6f 69 6e 74 20 74  ified to point t
29b0: 6f 20 74 68 65 20 65 72 72 6f 72 0d 0a 20 20 20  o the error..   
29c0: 20 20 20 20 20 2f 2f 2f 20 6d 65 73 73 61 67 65       /// message
29d0: 2c 20 77 69 74 68 20 74 68 65 20 75 6e 64 65 72  , with the under
29e0: 6c 79 69 6e 67 20 6d 65 6d 6f 72 79 20 68 61 76  lying memory hav
29f0: 69 6e 67 20 62 65 65 6e 20 6f 62 74 61 69 6e 65  ing been obtaine
2a00: 64 20 66 72 6f 6d 20 74 68 65 0d 0a 20 20 20 20  d from the..    
2a10: 20 20 20 20 2f 2f 2f 20 73 71 6c 69 74 65 33 5f      /// sqlite3_
2a20: 6d 61 6c 6c 6f 63 28 29 20 66 75 6e 63 74 69 6f  malloc() functio
2a30: 6e 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  n...        /// 
2a40: 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20  </param>..      
2a50: 20 20 2f 2f 2f 20 3c 72 65 74 75 72 6e 73 3e 0d    /// <returns>.
2a60: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 20 73  .        /// A s
2a70: 74 61 6e 64 61 72 64 20 53 51 4c 69 74 65 20 72  tandard SQLite r
2a80: 65 74 75 72 6e 20 63 6f 64 65 2e 0d 0a 20 20 20  eturn code...   
2a90: 20 20 20 20 20 2f 2f 2f 20 3c 2f 72 65 74 75 72       /// </retur
2aa0: 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 53 51 4c  ns>..        SQL
2ab0: 69 74 65 45 72 72 6f 72 43 6f 64 65 20 78 43 72  iteErrorCode xCr
2ac0: 65 61 74 65 28 0d 0a 20 20 20 20 20 20 20 20 20  eate(..         
2ad0: 20 20 20 49 6e 74 50 74 72 20 70 44 62 2c 0d 0a     IntPtr pDb,..
2ae0: 20 20 20 20 20 20 20 20 20 20 20 20 49 6e 74 50              IntP
2af0: 74 72 20 70 41 75 78 2c 0d 0a 20 20 20 20 20 20  tr pAux,..      
2b00: 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 0d        int argc,.
2b10: 0a 20 20 20 20 20 20 20 20 20 20 20 20 49 6e 74  .            Int
2b20: 50 74 72 20 61 72 67 76 2c 0d 0a 20 20 20 20 20  Ptr argv,..     
2b30: 20 20 20 20 20 20 20 72 65 66 20 49 6e 74 50 74         ref IntPt
2b40: 72 20 70 56 74 61 62 2c 0d 0a 20 20 20 20 20 20  r pVtab,..      
2b50: 20 20 20 20 20 20 72 65 66 20 49 6e 74 50 74 72        ref IntPtr
2b60: 20 70 45 72 72 6f 72 0d 0a 20 20 20 20 20 20 20   pError..       
2b70: 20 20 20 20 20 29 3b 0d 0a 0d 0a 20 20 20 20 20       );....     
2b80: 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f     /////////////
2b90: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
2ba0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
2bb0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
2bc0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20  //////////....  
2bd0: 20 20 20 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61        /// <summa
2be0: 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ry>..        ///
2bf0: 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20   <para><code>.. 
2c00: 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 69 6e 74         ///   int
2c10: 20 28 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c   (*xConnect)(sql
2c20: 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75  ite3*, void *pAu
2c30: 78 2c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  x,..        /// 
2c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
2c50: 6e 74 20 61 72 67 63 2c 20 63 68 61 72 20 2a 2a  nt argc, char **
2c60: 61 72 67 76 2c 0d 0a 20 20 20 20 20 20 20 20 2f  argv,..        /
2c70: 2f 2f 20 20 20 20 20 20 20 20 20 20 20 20 20 20  //              
2c80: 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a    sqlite3_vtab *
2c90: 2a 70 70 56 54 61 62 2c 0d 0a 20 20 20 20 20 20  *ppVTab,..      
2ca0: 20 20 2f 2f 2f 20 20 20 20 20 20 20 20 20 20 20    ///           
2cb0: 20 20 20 20 20 63 68 61 72 20 2a 2a 70 7a 45 72       char **pzEr
2cc0: 72 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  r);..        ///
2cd0: 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d   </code></para>.
2ce0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
2cf0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
2d00: 20 54 68 65 20 78 43 6f 6e 6e 65 63 74 20 6d 65   The xConnect me
2d10: 74 68 6f 64 20 69 73 20 76 65 72 79 20 73 69 6d  thod is very sim
2d20: 69 6c 61 72 20 74 6f 20 78 43 72 65 61 74 65 2e  ilar to xCreate.
2d30: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 49   ..        /// I
2d40: 74 20 68 61 73 20 74 68 65 20 73 61 6d 65 20 70  t has the same p
2d50: 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 63 6f  arameters and co
2d60: 6e 73 74 72 75 63 74 73 20 61 20 6e 65 77 20 73  nstructs a new s
2d70: 71 6c 69 74 65 33 5f 76 74 61 62 20 73 74 72 75  qlite3_vtab stru
2d80: 63 74 75 72 65 20 0d 0a 20 20 20 20 20 20 20 20  cture ..        
2d90: 2f 2f 2f 20 6a 75 73 74 20 6c 69 6b 65 20 78 43  /// just like xC
2da0: 72 65 61 74 65 2e 20 0d 0a 20 20 20 20 20 20 20  reate. ..       
2db0: 20 2f 2f 2f 20 41 6e 64 20 69 74 20 6d 75 73 74   /// And it must
2dc0: 20 61 6c 73 6f 20 63 61 6c 6c 20 73 71 6c 69 74   also call sqlit
2dd0: 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28  e3_declare_vtab(
2de0: 29 20 6c 69 6b 65 20 78 43 72 65 61 74 65 2e 0d  ) like xCreate..
2df0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
2e00: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
2e10: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
2e20: 20 20 2f 2f 2f 20 54 68 65 20 64 69 66 66 65 72    /// The differ
2e30: 65 6e 63 65 20 69 73 20 74 68 61 74 20 78 43 6f  ence is that xCo
2e40: 6e 6e 65 63 74 20 69 73 20 63 61 6c 6c 65 64 20  nnect is called 
2e50: 74 6f 20 65 73 74 61 62 6c 69 73 68 20 61 20 6e  to establish a n
2e60: 65 77 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ew ..        ///
2e70: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 61   connection to a
2e80: 6e 20 65 78 69 73 74 69 6e 67 20 76 69 72 74 75  n existing virtu
2e90: 61 6c 20 74 61 62 6c 65 20 77 68 65 72 65 61 73  al table whereas
2ea0: 20 78 43 72 65 61 74 65 20 69 73 20 63 61 6c 6c   xCreate is call
2eb0: 65 64 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ed ..        ///
2ec0: 20 74 6f 20 63 72 65 61 74 65 20 61 20 6e 65 77   to create a new
2ed0: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 66   virtual table f
2ee0: 72 6f 6d 20 73 63 72 61 74 63 68 2e 0d 0a 20 20  rom scratch...  
2ef0: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61        /// </para
2f00: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
2f10: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
2f20: 2f 2f 20 54 68 65 20 78 43 72 65 61 74 65 20 61  // The xCreate a
2f30: 6e 64 20 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68  nd xConnect meth
2f40: 6f 64 73 20 61 72 65 20 6f 6e 6c 79 20 64 69 66  ods are only dif
2f50: 66 65 72 65 6e 74 20 77 68 65 6e 20 74 68 65 0d  ferent when the.
2f60: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 76 69 72  .        /// vir
2f70: 74 75 61 6c 20 74 61 62 6c 65 20 68 61 73 20 73  tual table has s
2f80: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 62 61 63 6b  ome kind of back
2f90: 69 6e 67 20 73 74 6f 72 65 20 74 68 61 74 20 6d  ing store that m
2fa0: 75 73 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a  ust be initializ
2fb0: 65 64 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ed ..        ///
2fc0: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
2fd0: 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
2fe0: 65 20 69 73 20 63 72 65 61 74 65 64 2e 20 54 68  e is created. Th
2ff0: 65 20 78 43 72 65 61 74 65 20 6d 65 74 68 6f 64  e xCreate method
3000: 20 63 72 65 61 74 65 73 20 0d 0a 20 20 20 20 20   creates ..     
3010: 20 20 20 2f 2f 2f 20 61 6e 64 20 69 6e 69 74 69     /// and initi
3020: 61 6c 69 7a 65 73 20 74 68 65 20 62 61 63 6b 69  alizes the backi
3030: 6e 67 20 73 74 6f 72 65 2e 20 54 68 65 20 78 43  ng store. The xC
3040: 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64 20 6a 75  onnect method ju
3050: 73 74 20 63 6f 6e 6e 65 63 74 73 20 0d 0a 20 20  st connects ..  
3060: 20 20 20 20 20 20 2f 2f 2f 20 74 6f 20 61 6e 20        /// to an 
3070: 65 78 69 73 74 69 6e 67 20 62 61 63 6b 69 6e 67  existing backing
3080: 20 73 74 6f 72 65 2e 20 20 57 68 65 6e 20 78 43   store.  When xC
3090: 72 65 61 74 65 20 61 6e 64 20 78 43 6f 6e 6e 65  reate and xConne
30a0: 63 74 20 61 72 65 20 74 68 65 20 73 61 6d 65 2c  ct are the same,
30b0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68  ..        /// th
30c0: 65 20 74 61 62 6c 65 20 69 73 20 61 6e 20 65 70  e table is an ep
30d0: 6f 6e 79 6d 6f 75 73 20 76 69 72 74 75 61 6c 20  onymous virtual 
30e0: 74 61 62 6c 65 2e 0d 0a 20 20 20 20 20 20 20 20  table...        
30f0: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
3100: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
3110: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 73 20  .        /// As 
3120: 61 6e 20 65 78 61 6d 70 6c 65 2c 20 63 6f 6e 73  an example, cons
3130: 69 64 65 72 20 61 20 76 69 72 74 75 61 6c 20 74  ider a virtual t
3140: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
3150: 69 6f 6e 20 74 68 61 74 20 0d 0a 20 20 20 20 20  ion that ..     
3160: 20 20 20 2f 2f 2f 20 70 72 6f 76 69 64 65 73 20     /// provides 
3170: 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73  read-only access
3180: 20 74 6f 20 65 78 69 73 74 69 6e 67 20 63 6f 6d   to existing com
3190: 6d 61 2d 73 65 70 61 72 61 74 65 64 2d 76 61 6c  ma-separated-val
31a0: 75 65 20 28 43 53 56 29 0d 0a 20 20 20 20 20 20  ue (CSV)..      
31b0: 20 20 2f 2f 2f 20 66 69 6c 65 73 20 6f 6e 20 64    /// files on d
31c0: 69 73 6b 2e 20 54 68 65 72 65 20 69 73 20 6e 6f  isk. There is no
31d0: 20 62 61 63 6b 69 6e 67 20 73 74 6f 72 65 20 74   backing store t
31e0: 68 61 74 20 6e 65 65 64 73 20 74 6f 20 62 65 20  hat needs to be 
31f0: 63 72 65 61 74 65 64 20 0d 0a 20 20 20 20 20 20  created ..      
3200: 20 20 2f 2f 2f 20 6f 72 20 69 6e 69 74 69 61 6c    /// or initial
3210: 69 7a 65 64 20 66 6f 72 20 73 75 63 68 20 61 20  ized for such a 
3220: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 28 73  virtual table (s
3230: 69 6e 63 65 20 74 68 65 20 43 53 56 20 66 69 6c  ince the CSV fil
3240: 65 73 20 61 6c 72 65 61 64 79 20 0d 0a 20 20 20  es already ..   
3250: 20 20 20 20 20 2f 2f 2f 20 65 78 69 73 74 20 6f       /// exist o
3260: 6e 20 64 69 73 6b 29 20 73 6f 20 74 68 65 20 78  n disk) so the x
3270: 43 72 65 61 74 65 20 61 6e 64 20 78 43 6f 6e 6e  Create and xConn
3280: 65 63 74 20 6d 65 74 68 6f 64 73 20 77 69 6c 6c  ect methods will
3290: 20 62 65 20 69 64 65 6e 74 69 63 61 6c 20 0d 0a   be identical ..
32a0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 66 6f 72 20          /// for 
32b0: 74 68 61 74 20 6d 6f 64 75 6c 65 2e 0d 0a 20 20  that module...  
32c0: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61        /// </para
32d0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
32e0: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
32f0: 2f 2f 20 41 6e 6f 74 68 65 72 20 65 78 61 6d 70  // Another examp
3300: 6c 65 20 69 73 20 61 20 76 69 72 74 75 61 6c 20  le is a virtual 
3310: 74 61 62 6c 65 20 74 68 61 74 20 69 6d 70 6c 65  table that imple
3320: 6d 65 6e 74 73 20 61 20 66 75 6c 6c 2d 74 65 78  ments a full-tex
3330: 74 20 69 6e 64 65 78 2e 20 0d 0a 20 20 20 20 20  t index. ..     
3340: 20 20 20 2f 2f 2f 20 54 68 65 20 78 43 72 65 61     /// The xCrea
3350: 74 65 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 63  te method must c
3360: 72 65 61 74 65 20 61 6e 64 20 69 6e 69 74 69 61  reate and initia
3370: 6c 69 7a 65 20 64 61 74 61 20 73 74 72 75 63 74  lize data struct
3380: 75 72 65 73 20 74 6f 20 68 6f 6c 64 20 0d 0a 20  ures to hold .. 
3390: 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 20 64         /// the d
33a0: 69 63 74 69 6f 6e 61 72 79 20 61 6e 64 20 70 6f  ictionary and po
33b0: 73 74 69 6e 67 20 6c 69 73 74 73 20 66 6f 72 20  sting lists for 
33c0: 74 68 61 74 20 69 6e 64 65 78 2e 20 54 68 65 20  that index. The 
33d0: 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64 2c  xConnect method,
33e0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6f 6e  ..        /// on
33f0: 20 74 68 65 20 6f 74 68 65 72 20 68 61 6e 64 2c   the other hand,
3400: 20 6f 6e 6c 79 20 68 61 73 20 74 6f 20 6c 6f 63   only has to loc
3410: 61 74 65 20 61 6e 64 20 75 73 65 20 61 6e 20 65  ate and use an e
3420: 78 69 73 74 69 6e 67 20 64 69 63 74 69 6f 6e 61  xisting dictiona
3430: 72 79 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ry ..        ///
3440: 20 61 6e 64 20 70 6f 73 74 69 6e 67 20 6c 69 73   and posting lis
3450: 74 73 20 74 68 61 74 20 77 65 72 65 20 63 72 65  ts that were cre
3460: 61 74 65 64 20 62 79 20 61 20 70 72 69 6f 72 20  ated by a prior 
3470: 78 43 72 65 61 74 65 20 63 61 6c 6c 2e 0d 0a 20  xCreate call... 
3480: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
3490: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
34a0: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
34b0: 2f 2f 2f 20 54 68 65 20 78 43 6f 6e 6e 65 63 74  /// The xConnect
34c0: 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 72 65 74   method must ret
34d0: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
34e0: 20 69 74 20 69 73 20 73 75 63 63 65 73 73 66 75   it is successfu
34f0: 6c 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  l ..        /// 
3500: 69 6e 20 63 72 65 61 74 69 6e 67 20 74 68 65 20  in creating the 
3510: 6e 65 77 20 76 69 72 74 75 61 6c 20 74 61 62 6c  new virtual tabl
3520: 65 2c 20 6f 72 20 53 51 4c 49 54 45 5f 45 52 52  e, or SQLITE_ERR
3530: 4f 52 20 69 66 20 69 74 20 69 73 20 6e 6f 74 20  OR if it is not 
3540: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 75  ..        /// su
3550: 63 63 65 73 73 66 75 6c 2e 20 49 66 20 6e 6f 74  ccessful. If not
3560: 20 73 75 63 63 65 73 73 66 75 6c 2c 20 74 68 65   successful, the
3570: 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 73 74   sqlite3_vtab st
3580: 72 75 63 74 75 72 65 20 6d 75 73 74 20 6e 6f 74  ructure must not
3590: 20 62 65 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f   be ..        //
35a0: 2f 20 61 6c 6c 6f 63 61 74 65 64 2e 20 41 6e 20  / allocated. An 
35b0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 6d 61  error message ma
35c0: 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20  y optionally be 
35d0: 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 7a 45  returned in *pzE
35e0: 72 72 20 69 66 20 0d 0a 20 20 20 20 20 20 20 20  rr if ..        
35f0: 2f 2f 2f 20 75 6e 73 75 63 63 65 73 73 66 75 6c  /// unsuccessful
3600: 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  . ..        /// 
3610: 53 70 61 63 65 20 74 6f 20 68 6f 6c 64 20 74 68  Space to hold th
3620: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
3630: 73 74 72 69 6e 67 20 6d 75 73 74 20 62 65 20 61  string must be a
3640: 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 0d 0a  llocated using..
3650: 20 20 20 20 20 20 20 20 2f 2f 2f 20 61 6e 20 53          /// an S
3660: 51 4c 69 74 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  QLite memory all
3670: 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  ocation function
3680: 20 6c 69 6b 65 20 0d 0a 20 20 20 20 20 20 20 20   like ..        
3690: 2f 2f 2f 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  /// sqlite3_mall
36a0: 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
36b0: 6d 70 72 69 6e 74 66 28 29 20 61 73 20 74 68 65  mprintf() as the
36c0: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c   SQLite core wil
36d0: 6c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 61  l..        /// a
36e0: 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74  ttempt to free t
36f0: 68 65 20 73 70 61 63 65 20 75 73 69 6e 67 20 73  he space using s
3700: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61 66  qlite3_free() af
3710: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 68 61  ter the error ha
3720: 73 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 62  s..        /// b
3730: 65 65 6e 20 72 65 70 6f 72 74 65 64 20 75 70 20  een reported up 
3740: 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
3750: 6f 6e 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  on...        ///
3760: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
3770: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
3780: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 43        /// The xC
3790: 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64 20 69 73  onnect method is
37a0: 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 65 76   required for ev
37b0: 65 72 79 20 76 69 72 74 75 61 6c 20 74 61 62 6c  ery virtual tabl
37c0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
37d0: 2c 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  , ..        /// 
37e0: 74 68 6f 75 67 68 20 74 68 65 20 78 43 72 65 61  though the xCrea
37f0: 74 65 20 61 6e 64 20 78 43 6f 6e 6e 65 63 74 20  te and xConnect 
3800: 70 6f 69 6e 74 65 72 73 20 6f 66 20 74 68 65 20  pointers of the 
3810: 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 6f  sqlite3_module o
3820: 62 6a 65 63 74 0d 0a 20 20 20 20 20 20 20 20 2f  bject..        /
3830: 2f 2f 20 6d 61 79 20 70 6f 69 6e 74 20 74 6f 20  // may point to 
3840: 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
3850: 6e 20 69 66 20 74 68 65 20 76 69 72 74 75 61 6c  n if the virtual
3860: 20 74 61 62 6c 65 20 64 6f 65 73 20 6e 6f 74 20   table does not 
3870: 6e 65 65 64 20 74 6f 0d 0a 20 20 20 20 20 20 20  need to..       
3880: 20 2f 2f 2f 20 69 6e 69 74 69 61 6c 69 7a 65 20   /// initialize 
3890: 62 61 63 6b 69 6e 67 20 73 74 6f 72 65 2e 0d 0a  backing store...
38a0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
38b0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
38c0: 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20   </summary>..   
38d0: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20       /// <param 
38e0: 6e 61 6d 65 3d 22 70 44 62 22 3e 0d 0a 20 20 20  name="pDb">..   
38f0: 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e 61 74       /// The nat
3900: 69 76 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ive database con
3910: 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 2e 0d  nection handle..
3920: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
3930: 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f  aram>..        /
3940: 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22  // <param name="
3950: 70 41 75 78 22 3e 0d 0a 20 20 20 20 20 20 20 20  pAux">..        
3960: 2f 2f 2f 20 54 68 65 20 6f 72 69 67 69 6e 61 6c  /// The original
3970: 20 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72 20   native pointer 
3980: 76 61 6c 75 65 20 74 68 61 74 20 77 61 73 20 70  value that was p
3990: 72 6f 76 69 64 65 64 20 74 6f 20 74 68 65 0d 0a  rovided to the..
39a0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 71 6c 69          /// sqli
39b0: 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
39c0: 65 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 72 65  e(), sqlite3_cre
39d0: 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 20  ate_module_v2() 
39e0: 6f 72 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  or..        /// 
39f0: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 64  sqlite3_create_d
3a00: 69 73 70 6f 73 61 62 6c 65 5f 6d 6f 64 75 6c 65  isposable_module
3a10: 28 29 20 66 75 6e 63 74 69 6f 6e 73 2e 0d 0a 20  () functions... 
3a20: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
3a30: 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  am>..        ///
3a40: 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 61 72   <param name="ar
3a50: 67 63 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  gc">..        //
3a60: 2f 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  / The number of 
3a70: 61 72 67 75 6d 65 6e 74 73 20 66 72 6f 6d 20 74  arguments from t
3a80: 68 65 20 43 52 45 41 54 45 20 56 49 52 54 55 41  he CREATE VIRTUA
3a90: 4c 20 54 41 42 4c 45 20 73 74 61 74 65 6d 65 6e  L TABLE statemen
3aa0: 74 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  t...        /// 
3ab0: 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20  </param>..      
3ac0: 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d    /// <param nam
3ad0: 65 3d 22 61 72 67 76 22 3e 0d 0a 20 20 20 20 20  e="argv">..     
3ae0: 20 20 20 2f 2f 2f 20 54 68 65 20 61 72 72 61 79     /// The array
3af0: 20 6f 66 20 73 74 72 69 6e 67 20 61 72 67 75 6d   of string argum
3b00: 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 43 52  ents from the CR
3b10: 45 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42  EATE VIRTUAL TAB
3b20: 4c 45 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  LE..        /// 
3b30: 73 74 61 74 65 6d 65 6e 74 2e 0d 0a 20 20 20 20  statement...    
3b40: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e      /// </param>
3b50: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
3b60: 61 72 61 6d 20 6e 61 6d 65 3d 22 70 56 74 61 62  aram name="pVtab
3b70: 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ">..        /// 
3b80: 55 70 6f 6e 20 73 75 63 63 65 73 73 2c 20 74 68  Upon success, th
3b90: 69 73 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73  is parameter mus
3ba0: 74 20 62 65 20 6d 6f 64 69 66 69 65 64 20 74 6f  t be modified to
3bb0: 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 6e 65   point to the ne
3bc0: 77 6c 79 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  wly..        ///
3bd0: 20 63 72 65 61 74 65 64 20 6e 61 74 69 76 65 20   created native 
3be0: 73 71 6c 69 74 65 33 5f 76 74 61 62 20 64 65 72  sqlite3_vtab der
3bf0: 69 76 65 64 20 73 74 72 75 63 74 75 72 65 2e 0d  ived structure..
3c00: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
3c10: 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f  aram>..        /
3c20: 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22  // <param name="
3c30: 70 45 72 72 6f 72 22 3e 0d 0a 20 20 20 20 20 20  pError">..      
3c40: 20 20 2f 2f 2f 20 55 70 6f 6e 20 66 61 69 6c 75    /// Upon failu
3c50: 72 65 2c 20 74 68 69 73 20 70 61 72 61 6d 65 74  re, this paramet
3c60: 65 72 20 6d 75 73 74 20 62 65 20 6d 6f 64 69 66  er must be modif
3c70: 69 65 64 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ied to point to 
3c80: 74 68 65 20 65 72 72 6f 72 0d 0a 20 20 20 20 20  the error..     
3c90: 20 20 20 2f 2f 2f 20 6d 65 73 73 61 67 65 2c 20     /// message, 
3ca0: 77 69 74 68 20 74 68 65 20 75 6e 64 65 72 6c 79  with the underly
3cb0: 69 6e 67 20 6d 65 6d 6f 72 79 20 68 61 76 69 6e  ing memory havin
3cc0: 67 20 62 65 65 6e 20 6f 62 74 61 69 6e 65 64 20  g been obtained 
3cd0: 66 72 6f 6d 20 74 68 65 0d 0a 20 20 20 20 20 20  from the..      
3ce0: 20 20 2f 2f 2f 20 73 71 6c 69 74 65 33 5f 6d 61    /// sqlite3_ma
3cf0: 6c 6c 6f 63 28 29 20 66 75 6e 63 74 69 6f 6e 2e  lloc() function.
3d00: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
3d10: 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20  param>..        
3d20: 2f 2f 2f 20 3c 72 65 74 75 72 6e 73 3e 0d 0a 20  /// <returns>.. 
3d30: 20 20 20 20 20 20 20 2f 2f 2f 20 41 20 73 74 61         /// A sta
3d40: 6e 64 61 72 64 20 53 51 4c 69 74 65 20 72 65 74  ndard SQLite ret
3d50: 75 72 6e 20 63 6f 64 65 2e 0d 0a 20 20 20 20 20  urn code...     
3d60: 20 20 20 2f 2f 2f 20 3c 2f 72 65 74 75 72 6e 73     /// </returns
3d70: 3e 0d 0a 20 20 20 20 20 20 20 20 53 51 4c 69 74  >..        SQLit
3d80: 65 45 72 72 6f 72 43 6f 64 65 20 78 43 6f 6e 6e  eErrorCode xConn
3d90: 65 63 74 28 0d 0a 20 20 20 20 20 20 20 20 20 20  ect(..          
3da0: 20 20 49 6e 74 50 74 72 20 70 44 62 2c 0d 0a 20    IntPtr pDb,.. 
3db0: 20 20 20 20 20 20 20 20 20 20 20 49 6e 74 50 74             IntPt
3dc0: 72 20 70 41 75 78 2c 0d 0a 20 20 20 20 20 20 20  r pAux,..       
3dd0: 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 0d 0a       int argc,..
3de0: 20 20 20 20 20 20 20 20 20 20 20 20 49 6e 74 50              IntP
3df0: 74 72 20 61 72 67 76 2c 0d 0a 20 20 20 20 20 20  tr argv,..      
3e00: 20 20 20 20 20 20 72 65 66 20 49 6e 74 50 74 72        ref IntPtr
3e10: 20 70 56 74 61 62 2c 0d 0a 20 20 20 20 20 20 20   pVtab,..       
3e20: 20 20 20 20 20 72 65 66 20 49 6e 74 50 74 72 20       ref IntPtr 
3e30: 70 45 72 72 6f 72 0d 0a 20 20 20 20 20 20 20 20  pError..        
3e40: 20 20 20 20 29 3b 0d 0a 0d 0a 20 20 20 20 20 20      );....      
3e50: 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f    //////////////
3e60: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
3e70: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
3e80: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
3e90: 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20  /////////....   
3ea0: 20 20 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72       /// <summar
3eb0: 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  y>..        /// 
3ec0: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
3ed0: 2f 2f 2f 20 53 51 4c 69 74 65 20 75 73 65 73 20  /// SQLite uses 
3ee0: 74 68 65 20 78 42 65 73 74 49 6e 64 65 78 20 6d  the xBestIndex m
3ef0: 65 74 68 6f 64 20 6f 66 20 61 20 76 69 72 74 75  ethod of a virtu
3f00: 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20  al table module 
3f10: 74 6f 20 64 65 74 65 72 6d 69 6e 65 0d 0a 20 20  to determine..  
3f20: 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 20 62 65        /// the be
3f30: 73 74 20 77 61 79 20 74 6f 20 61 63 63 65 73 73  st way to access
3f40: 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
3f50: 6c 65 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  le. ..        //
3f60: 2f 20 54 68 65 20 78 42 65 73 74 49 6e 64 65 78  / The xBestIndex
3f70: 20 6d 65 74 68 6f 64 20 68 61 73 20 61 20 70 72   method has a pr
3f80: 6f 74 6f 74 79 70 65 20 6c 69 6b 65 20 74 68 69  ototype like thi
3f90: 73 3a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  s:..        /// 
3fa0: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
3fb0: 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65   /// <para><code
3fc0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20  >..        ///  
3fd0: 20 69 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 65   int (*xBestInde
3fe0: 78 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  x)(sqlite3_vtab 
3ff0: 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f  *pVTab, sqlite3_
4000: 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0d 0a 20  index_info*);.. 
4010: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64         /// </cod
4020: 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  e></para>..     
4030: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20     /// <para>.. 
4040: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 53         /// The S
4050: 51 4c 69 74 65 20 63 6f 72 65 20 63 6f 6d 6d 75  QLite core commu
4060: 6e 69 63 61 74 65 73 20 77 69 74 68 20 74 68 65  nicates with the
4070: 20 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68   xBestIndex meth
4080: 6f 64 20 62 79 20 66 69 6c 6c 69 6e 67 20 0d 0a  od by filling ..
4090: 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e 20 63          /// in c
40a0: 65 72 74 61 69 6e 20 66 69 65 6c 64 73 20 6f 66  ertain fields of
40b0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64   the sqlite3_ind
40c0: 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72  ex_info structur
40d0: 65 20 61 6e 64 20 70 61 73 73 69 6e 67 20 61 20  e and passing a 
40e0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 70 6f  ..        /// po
40f0: 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74  inter to that st
4100: 72 75 63 74 75 72 65 20 69 6e 74 6f 20 78 42 65  ructure into xBe
4110: 73 74 49 6e 64 65 78 20 61 73 20 74 68 65 20 73  stIndex as the s
4120: 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
4130: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54   ..        /// T
4140: 68 65 20 78 42 65 73 74 49 6e 64 65 78 20 6d 65  he xBestIndex me
4150: 74 68 6f 64 20 66 69 6c 6c 73 20 6f 75 74 20 6f  thod fills out o
4160: 74 68 65 72 20 66 69 65 6c 64 73 20 6f 66 20 74  ther fields of t
4170: 68 69 73 20 73 74 72 75 63 74 75 72 65 20 77 68  his structure wh
4180: 69 63 68 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ich..        ///
4190: 20 66 6f 72 6d 73 20 74 68 65 20 72 65 70 6c 79   forms the reply
41a0: 2e 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  . The sqlite3_in
41b0: 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75  dex_info structu
41c0: 72 65 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 74 68  re looks like th
41d0: 69 73 3a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  is:..        ///
41e0: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
41f0: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64    /// <para><cod
4200: 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e>..        /// 
4210: 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33    struct sqlite3
4220: 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0d 0a 20  _index_info {.. 
4230: 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 2f         ///     /
4240: 2a 20 49 6e 70 75 74 73 20 2a 2f 0d 0a 20 20 20  * Inputs */..   
4250: 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 63 6f 6e       ///     con
4260: 73 74 20 69 6e 74 20 6e 43 6f 6e 73 74 72 61 69  st int nConstrai
4270: 6e 74 3b 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65  nt;     /* Numbe
4280: 72 20 6f 66 20 65 6e 74 72 69 65 73 20 69 6e 20  r of entries in 
4290: 61 43 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0d 0a  aConstraint */..
42a0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20          ///     
42b0: 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c  const struct sql
42c0: 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74  ite3_index_const
42d0: 72 61 69 6e 74 20 7b 0d 0a 20 20 20 20 20 20 20  raint {..       
42e0: 20 2f 2f 2f 20 20 20 20 20 20 20 20 69 6e 74 20   ///        int 
42f0: 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20  iColumn;        
4300: 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20        /* Column 
4310: 63 6f 6e 73 74 72 61 69 6e 65 64 2e 20 20 2d 31  constrained.  -1
4320: 20 66 6f 72 20 52 4f 57 49 44 20 2a 2f 0d 0a 20   for ROWID */.. 
4330: 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 20         ///      
4340: 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20    unsigned char 
4350: 6f 70 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43  op;         /* C
4360: 6f 6e 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74  onstraint operat
4370: 6f 72 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20 2f  or */..        /
4380: 2f 2f 20 20 20 20 20 20 20 20 75 6e 73 69 67 6e  //        unsign
4390: 65 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20  ed char usable; 
43a0: 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74      /* True if t
43b0: 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69  his constraint i
43c0: 73 20 75 73 61 62 6c 65 20 2a 2f 0d 0a 20 20 20  s usable */..   
43d0: 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 20 20 20       ///        
43e0: 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b  int iTermOffset;
43f0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65            /* Use
4400: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78  d internally - x
4410: 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64  BestIndex should
4420: 20 69 67 6e 6f 72 65 20 2a 2f 0d 0a 20 20 20 20   ignore */..    
4430: 20 20 20 20 2f 2f 2f 20 20 20 20 20 7d 20 2a 63      ///     } *c
4440: 6f 6e 73 74 20 61 43 6f 6e 73 74 72 61 69 6e 74  onst aConstraint
4450: 3b 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20  ;      /* Table 
4460: 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  of WHERE clause 
4470: 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0d 0a  constraints */..
4480: 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20          ///     
4490: 63 6f 6e 73 74 20 69 6e 74 20 6e 4f 72 64 65 72  const int nOrder
44a0: 42 79 3b 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  By;        /* Nu
44b0: 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
44c0: 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
44d0: 61 75 73 65 20 2a 2f 0d 0a 20 20 20 20 20 20 20  ause */..       
44e0: 20 2f 2f 2f 20 20 20 20 20 63 6f 6e 73 74 20 73   ///     const s
44f0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e  truct sqlite3_in
4500: 64 65 78 5f 6f 72 64 65 72 62 79 20 7b 0d 0a 20  dex_orderby {.. 
4510: 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 20         ///      
4520: 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20    int iColumn;  
4530: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
4540: 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0d  olumn number */.
4550: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20  .        ///    
4560: 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61      unsigned cha
4570: 72 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a  r desc;       /*
4580: 20 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20   True for DESC. 
4590: 20 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20   False for ASC. 
45a0: 2a 2f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  */..        /// 
45b0: 20 20 20 20 7d 20 2a 63 6f 6e 73 74 20 61 4f 72      } *const aOr
45c0: 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 2f  derBy;         /
45d0: 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59 20 63  * The ORDER BY c
45e0: 6c 61 75 73 65 20 2a 2f 0d 0a 20 20 20 20 20 20  lause */..      
45f0: 20 20 2f 2f 2f 20 20 20 20 20 2f 2a 20 4f 75 74    ///     /* Out
4600: 70 75 74 73 20 2a 2f 0d 0a 20 20 20 20 20 20 20  puts */..       
4610: 20 2f 2f 2f 20 20 20 20 20 73 74 72 75 63 74 20   ///     struct 
4620: 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f  sqlite3_index_co
4630: 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20 7b  nstraint_usage {
4640: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20  ..        ///   
4650: 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64 65      int argvInde
4660: 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  x;           /* 
4670: 69 66 20 26 67 74 3b 30 2c 20 63 6f 6e 73 74 72  if &gt;0, constr
4680: 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20  aint is part of 
4690: 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20  argv to xFilter 
46a0: 2a 2f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  */..        /// 
46b0: 20 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63        unsigned c
46c0: 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f  har omit;      /
46d0: 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20  * Do not code a 
46e0: 74 65 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f  test for this co
46f0: 6e 73 74 72 61 69 6e 74 20 2a 2f 0d 0a 20 20 20  nstraint */..   
4700: 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 7d 20 2a       ///     } *
4710: 63 6f 6e 73 74 20 61 43 6f 6e 73 74 72 61 69 6e  const aConstrain
4720: 74 55 73 61 67 65 3b 0d 0a 20 20 20 20 20 20 20  tUsage;..       
4730: 20 2f 2f 2f 20 20 20 20 20 69 6e 74 20 69 64 78   ///     int idx
4740: 4e 75 6d 3b 20 20 20 20 20 20 20 20 20 20 20 20  Num;            
4750: 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73      /* Number us
4760: 65 64 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74  ed to identify t
4770: 68 65 20 69 6e 64 65 78 20 2a 2f 0d 0a 20 20 20  he index */..   
4780: 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 63 68 61       ///     cha
4790: 72 20 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20  r *idxStr;      
47a0: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e          /* Strin
47b0: 67 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61  g, possibly obta
47c0: 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
47d0: 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0d 0a 20 20 20  3_malloc */..   
47e0: 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 69 6e 74       ///     int
47f0: 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53 74   needToFreeIdxSt
4800: 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20  r;      /* Free 
4810: 69 64 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c  idxStr using sql
4820: 69 74 65 33 5f 66 72 65 65 28 29 20 69 66 20 74  ite3_free() if t
4830: 72 75 65 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20  rue */..        
4840: 2f 2f 2f 20 20 20 20 20 69 6e 74 20 6f 72 64 65  ///     int orde
4850: 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20  rByConsumed;    
4860: 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75     /* True if ou
4870: 74 70 75 74 20 69 73 20 61 6c 72 65 61 64 79 20  tput is already 
4880: 6f 72 64 65 72 65 64 20 2a 2f 0d 0a 20 20 20 20  ordered */..    
4890: 20 20 20 20 2f 2f 2f 20 20 20 20 20 64 6f 75 62      ///     doub
48a0: 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74  le estimatedCost
48b0: 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61  ;      /* Estima
48c0: 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e  ted cost of usin
48d0: 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0d  g this index */.
48e0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20  .        ///    
48f0: 20 3c 21 5b 43 44 41 54 41 5b 3c 62 3e 5d 5d 3e   <![CDATA[<b>]]>
4900: 2f 2a 20 46 69 65 6c 64 73 20 62 65 6c 6f 77 20  /* Fields below 
4910: 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62  are only availab
4920: 6c 65 20 69 6e 20 53 51 4c 69 74 65 20 33 2e 38  le in SQLite 3.8
4930: 2e 32 20 61 6e 64 20 6c 61 74 65 72 20 2a 2f 3c  .2 and later */<
4940: 21 5b 43 44 41 54 41 5b 3c 2f 62 3e 5d 5d 3e 0d  ![CDATA[</b>]]>.
4950: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20  .        ///    
4960: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 65   sqlite3_int64 e
4970: 73 74 69 6d 61 74 65 64 52 6f 77 73 3b 20 20 20  stimatedRows;   
4980: 20 2f 2a 20 45 73 74 69 6d 61 74 65 64 20 6e 75   /* Estimated nu
4990: 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 72 65 74  mber of rows ret
49a0: 75 72 6e 65 64 20 2a 2f 0d 0a 20 20 20 20 20 20  urned */..      
49b0: 20 20 2f 2f 2f 20 20 20 20 20 3c 21 5b 43 44 41    ///     <![CDA
49c0: 54 41 5b 3c 62 3e 5d 5d 3e 2f 2a 20 46 69 65 6c  TA[<b>]]>/* Fiel
49d0: 64 73 20 62 65 6c 6f 77 20 61 72 65 20 6f 6e 6c  ds below are onl
49e0: 79 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 53  y available in S
49f0: 51 4c 69 74 65 20 33 2e 39 2e 30 20 61 6e 64 20  QLite 3.9.0 and 
4a00: 6c 61 74 65 72 20 2a 2f 3c 21 5b 43 44 41 54 41  later */<![CDATA
4a10: 5b 3c 2f 62 3e 5d 5d 3e 0d 0a 20 20 20 20 20 20  [</b>]]>..      
4a20: 20 20 2f 2f 2f 20 20 20 20 20 69 6e 74 20 69 64    ///     int id
4a30: 78 46 6c 61 67 73 3b 20 20 20 20 20 20 20 20 20  xFlags;         
4a40: 20 20 20 20 20 2f 2a 20 4d 61 73 6b 20 6f 66 20       /* Mask of 
4a50: 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 53 43 41  SQLITE_INDEX_SCA
4a60: 4e 5f 2a 20 66 6c 61 67 73 20 2a 2f 0d 0a 20 20  N_* flags */..  
4a70: 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 3c 21        ///     <!
4a80: 5b 43 44 41 54 41 5b 3c 62 3e 5d 5d 3e 2f 2a 20  [CDATA[<b>]]>/* 
4a90: 46 69 65 6c 64 73 20 62 65 6c 6f 77 20 61 72 65  Fields below are
4aa0: 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
4ab0: 69 6e 20 53 51 4c 69 74 65 20 33 2e 31 30 2e 30  in SQLite 3.10.0
4ac0: 20 61 6e 64 20 6c 61 74 65 72 20 2a 2f 3c 21 5b   and later */<![
4ad0: 43 44 41 54 41 5b 3c 2f 62 3e 5d 5d 3e 0d 0a 20  CDATA[</b>]]>.. 
4ae0: 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 73         ///     s
4af0: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 63 6f  qlite3_uint64 co
4b00: 6c 55 73 65 64 3b 20 20 20 20 2f 2a 20 49 6e 70  lUsed;    /* Inp
4b10: 75 74 3a 20 4d 61 73 6b 20 6f 66 20 63 6f 6c 75  ut: Mask of colu
4b20: 6d 6e 73 20 75 73 65 64 20 62 79 20 73 74 61 74  mns used by stat
4b30: 65 6d 65 6e 74 20 2a 2f 0d 0a 20 20 20 20 20 20  ement */..      
4b40: 20 20 2f 2f 2f 20 20 20 7d 3b 0d 0a 20 20 20 20    ///   };..    
4b50: 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c      /// </code><
4b60: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
4b70: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20  /// <para>..    
4b80: 20 20 20 20 2f 2f 2f 20 4e 6f 74 65 20 74 68 65      /// Note the
4b90: 20 77 61 72 6e 69 6e 67 73 20 6f 6e 20 74 68 65   warnings on the
4ba0: 20 22 65 73 74 69 6d 61 74 65 64 52 6f 77 73 22   "estimatedRows"
4bb0: 2c 20 22 69 64 78 46 6c 61 67 73 22 2c 20 61 6e  , "idxFlags", an
4bc0: 64 20 63 6f 6c 55 73 65 64 20 66 69 65 6c 64 73  d colUsed fields
4bd0: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54  ...        /// T
4be0: 68 65 73 65 20 66 69 65 6c 64 73 20 77 65 72 65  hese fields were
4bf0: 20 61 64 64 65 64 20 77 69 74 68 20 53 51 4c 69   added with SQLi
4c00: 74 65 20 76 65 72 73 69 6f 6e 73 20 33 2e 38 2e  te versions 3.8.
4c10: 32 2c 20 33 2e 39 2e 30 2c 20 61 6e 64 20 33 2e  2, 3.9.0, and 3.
4c20: 31 30 2e 30 2c 20 72 65 73 70 65 63 74 69 76 65  10.0, respective
4c30: 6c 79 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ly. ..        //
4c40: 2f 20 41 6e 79 20 65 78 74 65 6e 73 69 6f 6e 20  / Any extension 
4c50: 74 68 61 74 20 72 65 61 64 73 20 6f 72 20 77 72  that reads or wr
4c60: 69 74 65 73 20 74 68 65 73 65 20 66 69 65 6c 64  ites these field
4c70: 73 20 6d 75 73 74 20 66 69 72 73 74 20 63 68 65  s must first che
4c80: 63 6b 20 74 68 61 74 20 74 68 65 20 0d 0a 20 20  ck that the ..  
4c90: 20 20 20 20 20 20 2f 2f 2f 20 76 65 72 73 69 6f        /// versio
4ca0: 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20  n of the SQLite 
4cb0: 6c 69 62 72 61 72 79 20 69 6e 20 75 73 65 20 69  library in use i
4cc0: 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 6f  s greater than o
4cd0: 72 20 65 71 75 61 6c 20 74 6f 20 61 70 70 72 6f  r equal to appro
4ce0: 70 72 69 61 74 65 0d 0a 20 20 20 20 20 20 20 20  priate..        
4cf0: 2f 2f 2f 20 76 65 72 73 69 6f 6e 20 2d 20 70 65  /// version - pe
4d00: 72 68 61 70 73 20 63 6f 6d 70 61 72 69 6e 67 20  rhaps comparing 
4d10: 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
4d20: 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
4d30: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
4d40: 72 28 29 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  r()..        ///
4d50: 20 61 67 61 69 6e 73 74 20 63 6f 6e 73 74 61 6e   against constan
4d60: 74 73 20 33 30 30 38 30 30 32 2c 20 33 30 30 39  ts 3008002, 3009
4d70: 30 30 30 2c 20 61 6e 64 2f 6f 72 20 33 30 31 30  000, and/or 3010
4d80: 30 30 30 2e 20 54 68 65 20 72 65 73 75 6c 74 20  000. The result 
4d90: 6f 66 20 61 74 74 65 6d 70 74 69 6e 67 20 0d 0a  of attempting ..
4da0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 6f 20 61          /// to a
4db0: 63 63 65 73 73 20 74 68 65 73 65 20 66 69 65 6c  ccess these fiel
4dc0: 64 73 20 69 6e 20 61 6e 20 73 71 6c 69 74 65 33  ds in an sqlite3
4dd0: 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75  _index_info stru
4de0: 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79  cture created by
4df0: 20 61 6e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f   an ..        //
4e00: 2f 20 6f 6c 64 65 72 20 76 65 72 73 69 6f 6e 20  / older version 
4e10: 6f 66 20 53 51 4c 69 74 65 20 61 72 65 20 75 6e  of SQLite are un
4e20: 64 65 66 69 6e 65 64 2e 0d 0a 20 20 20 20 20 20  defined...      
4e30: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
4e40: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
4e50: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 49  >..        /// I
4e60: 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72  n addition, ther
4e70: 65 20 61 72 65 20 73 6f 6d 65 20 64 65 66 69 6e  e are some defin
4e80: 65 64 20 63 6f 6e 73 74 61 6e 74 73 3a 0d 0a 20  ed constants:.. 
4e90: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
4ea0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
4eb0: 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20  <para><code>..  
4ec0: 20 20 20 20 20 20 2f 2f 2f 20 20 20 23 64 65 66        ///   #def
4ed0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
4ee0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 20  _CONSTRAINT_EQ  
4ef0: 20 20 20 20 32 0d 0a 20 20 20 20 20 20 20 20 2f      2..        /
4f00: 2f 2f 20 20 20 23 64 65 66 69 6e 65 20 53 51 4c  //   #define SQL
4f10: 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
4f20: 41 49 4e 54 5f 47 54 20 20 20 20 20 20 34 0d 0a  AINT_GT      4..
4f30: 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 23 64          ///   #d
4f40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
4f50: 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45  EX_CONSTRAINT_LE
4f60: 20 20 20 20 20 20 38 0d 0a 20 20 20 20 20 20 20        8..       
4f70: 20 2f 2f 2f 20 20 20 23 64 65 66 69 6e 65 20 53   ///   #define S
4f80: 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
4f90: 54 52 41 49 4e 54 5f 4c 54 20 20 20 20 20 31 36  TRAINT_LT     16
4fa0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20  ..        ///   
4fb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4fc0: 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
4fd0: 47 45 20 20 20 20 20 33 32 0d 0a 20 20 20 20 20  GE     32..     
4fe0: 20 20 20 2f 2f 2f 20 20 20 23 64 65 66 69 6e 65     ///   #define
4ff0: 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f   SQLITE_INDEX_CO
5000: 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43 48 20 20  NSTRAINT_MATCH  
5010: 36 34 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  64..        /// 
5020: 20 20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45    #define SQLITE
5030: 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
5040: 54 5f 4c 49 4b 45 20 20 20 36 35 20 20 20 20 20  T_LIKE   65     
5050: 2f 2a 20 33 2e 31 30 2e 30 20 61 6e 64 20 6c 61  /* 3.10.0 and la
5060: 74 65 72 20 6f 6e 6c 79 20 2a 2f 0d 0a 20 20 20  ter only */..   
5070: 20 20 20 20 20 2f 2f 2f 20 20 20 23 64 65 66 69       ///   #defi
5080: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
5090: 43 4f 4e 53 54 52 41 49 4e 54 5f 47 4c 4f 42 20  CONSTRAINT_GLOB 
50a0: 20 20 36 36 20 20 20 20 20 2f 2a 20 33 2e 31 30    66     /* 3.10
50b0: 2e 30 20 61 6e 64 20 6c 61 74 65 72 20 6f 6e 6c  .0 and later onl
50c0: 79 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20 2f 2f  y */..        //
50d0: 2f 20 20 20 23 64 65 66 69 6e 65 20 53 51 4c 49  /   #define SQLI
50e0: 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
50f0: 49 4e 54 5f 52 45 47 45 58 50 20 36 37 20 20 20  INT_REGEXP 67   
5100: 20 20 2f 2a 20 33 2e 31 30 2e 30 20 61 6e 64 20    /* 3.10.0 and 
5110: 6c 61 74 65 72 20 6f 6e 6c 79 20 2a 2f 0d 0a 20  later only */.. 
5120: 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 23 64 65         ///   #de
5130: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
5140: 58 5f 53 43 41 4e 5f 55 4e 49 51 55 45 20 20 20  X_SCAN_UNIQUE   
5150: 20 20 20 20 20 31 20 20 20 20 20 2f 2a 20 53 63       1     /* Sc
5160: 61 6e 20 76 69 73 69 74 73 20 61 74 20 6d 6f 73  an visits at mos
5170: 74 20 31 20 72 6f 77 20 2a 2f 0d 0a 20 20 20 20  t 1 row */..    
5180: 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c      /// </code><
5190: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
51a0: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20  /// <para>..    
51b0: 20 20 20 20 2f 2f 2f 20 54 68 65 20 53 51 4c 69      /// The SQLi
51c0: 74 65 20 63 6f 72 65 20 63 61 6c 6c 73 20 74 68  te core calls th
51d0: 65 20 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74  e xBestIndex met
51e0: 68 6f 64 20 77 68 65 6e 20 69 74 20 69 73 20 63  hod when it is c
51f0: 6f 6d 70 69 6c 69 6e 67 20 61 20 71 75 65 72 79  ompiling a query
5200: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68  ..        /// th
5210: 61 74 20 69 6e 76 6f 6c 76 65 73 20 61 20 76 69  at involves a vi
5220: 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 49 6e 20  rtual table. In 
5230: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 53 51 4c  other words, SQL
5240: 69 74 65 20 63 61 6c 6c 73 20 74 68 69 73 20 6d  ite calls this m
5250: 65 74 68 6f 64 20 0d 0a 20 20 20 20 20 20 20 20  ethod ..        
5260: 2f 2f 2f 20 77 68 65 6e 20 69 74 20 69 73 20 72  /// when it is r
5270: 75 6e 6e 69 6e 67 20 73 71 6c 69 74 65 33 5f 70  unning sqlite3_p
5280: 72 65 70 61 72 65 28 29 20 6f 72 20 74 68 65 20  repare() or the 
5290: 65 71 75 69 76 61 6c 65 6e 74 2e 20 0d 0a 20 20  equivalent. ..  
52a0: 20 20 20 20 20 20 2f 2f 2f 20 42 79 20 63 61 6c        /// By cal
52b0: 6c 69 6e 67 20 74 68 69 73 20 6d 65 74 68 6f 64  ling this method
52c0: 2c 20 74 68 65 20 0d 0a 20 20 20 20 20 20 20 20  , the ..        
52d0: 2f 2f 2f 20 53 51 4c 69 74 65 20 63 6f 72 65 20  /// SQLite core 
52e0: 69 73 20 73 61 79 69 6e 67 20 74 6f 20 74 68 65  is saying to the
52f0: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 74   virtual table t
5300: 68 61 74 20 69 74 20 6e 65 65 64 73 20 74 6f 20  hat it needs to 
5310: 61 63 63 65 73 73 20 0d 0a 20 20 20 20 20 20 20  access ..       
5320: 20 2f 2f 2f 20 73 6f 6d 65 20 73 75 62 73 65 74   /// some subset
5330: 20 6f 66 20 74 68 65 20 72 6f 77 73 20 69 6e 20   of the rows in 
5340: 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
5350: 65 20 61 6e 64 20 69 74 20 77 61 6e 74 73 20 74  e and it wants t
5360: 6f 20 6b 6e 6f 77 20 74 68 65 0d 0a 20 20 20 20  o know the..    
5370: 20 20 20 20 2f 2f 2f 20 6d 6f 73 74 20 65 66 66      /// most eff
5380: 69 63 69 65 6e 74 20 77 61 79 20 74 6f 20 64 6f  icient way to do
5390: 20 74 68 61 74 20 61 63 63 65 73 73 2e 20 54 68   that access. Th
53a0: 65 20 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74  e xBestIndex met
53b0: 68 6f 64 20 72 65 70 6c 69 65 73 20 0d 0a 20 20  hod replies ..  
53c0: 20 20 20 20 20 20 2f 2f 2f 20 77 69 74 68 20 69        /// with i
53d0: 6e 66 6f 72 6d 61 74 69 6f 6e 20 74 68 61 74 20  nformation that 
53e0: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  the SQLite core 
53f0: 63 61 6e 20 74 68 65 6e 20 75 73 65 20 74 6f 20  can then use to 
5400: 63 6f 6e 64 75 63 74 20 61 6e 20 0d 0a 20 20 20  conduct an ..   
5410: 20 20 20 20 20 2f 2f 2f 20 65 66 66 69 63 69 65       /// efficie
5420: 6e 74 20 73 65 61 72 63 68 20 6f 66 20 74 68 65  nt search of the
5430: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 0d   virtual table..
5440: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
5450: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
5460: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
5470: 20 20 2f 2f 2f 20 57 68 69 6c 65 20 63 6f 6d 70    /// While comp
5480: 69 6c 69 6e 67 20 61 20 73 69 6e 67 6c 65 20 53  iling a single S
5490: 51 4c 20 71 75 65 72 79 2c 20 74 68 65 20 53 51  QL query, the SQ
54a0: 4c 69 74 65 20 63 6f 72 65 20 6d 69 67 68 74 20  Lite core might 
54b0: 63 61 6c 6c 20 0d 0a 20 20 20 20 20 20 20 20 2f  call ..        /
54c0: 2f 2f 20 78 42 65 73 74 49 6e 64 65 78 20 6d 75  // xBestIndex mu
54d0: 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74  ltiple times wit
54e0: 68 20 64 69 66 66 65 72 65 6e 74 20 73 65 74 74  h different sett
54f0: 69 6e 67 73 20 69 6e 20 73 71 6c 69 74 65 33 5f  ings in sqlite3_
5500: 69 6e 64 65 78 5f 69 6e 66 6f 2e 0d 0a 20 20 20  index_info...   
5510: 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 53 51 4c       /// The SQL
5520: 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 74 68  ite core will th
5530: 65 6e 20 73 65 6c 65 63 74 20 74 68 65 20 63 6f  en select the co
5540: 6d 62 69 6e 61 74 69 6f 6e 20 74 68 61 74 20 61  mbination that a
5550: 70 70 65 61 72 73 20 74 6f 20 0d 0a 20 20 20 20  ppears to ..    
5560: 20 20 20 20 2f 2f 2f 20 67 69 76 65 20 74 68 65      /// give the
5570: 20 62 65 73 74 20 70 65 72 66 6f 72 6d 61 6e 63   best performanc
5580: 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e...        /// 
5590: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
55a0: 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20   /// <para>..   
55b0: 20 20 20 20 20 2f 2f 2f 20 42 65 66 6f 72 65 20       /// Before 
55c0: 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 6d 65 74  calling this met
55d0: 68 6f 64 2c 20 74 68 65 20 53 51 4c 69 74 65 20  hod, the SQLite 
55e0: 63 6f 72 65 20 69 6e 69 74 69 61 6c 69 7a 65 73  core initializes
55f0: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 0d 0a 20   an instance .. 
5600: 20 20 20 20 20 20 20 2f 2f 2f 20 6f 66 20 74 68         /// of th
5610: 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  e sqlite3_index_
5620: 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20 77  info structure w
5630: 69 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ith information 
5640: 61 62 6f 75 74 20 74 68 65 0d 0a 20 20 20 20 20  about the..     
5650: 20 20 20 2f 2f 2f 20 71 75 65 72 79 20 74 68 61     /// query tha
5660: 74 20 69 74 20 69 73 20 63 75 72 72 65 6e 74 6c  t it is currentl
5670: 79 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 63  y trying to proc
5680: 65 73 73 2e 20 54 68 69 73 20 69 6e 66 6f 72 6d  ess. This inform
5690: 61 74 69 6f 6e 20 0d 0a 20 20 20 20 20 20 20 20  ation ..        
56a0: 2f 2f 2f 20 64 65 72 69 76 65 73 20 6d 61 69 6e  /// derives main
56b0: 6c 79 20 66 72 6f 6d 20 74 68 65 20 57 48 45 52  ly from the WHER
56c0: 45 20 63 6c 61 75 73 65 20 61 6e 64 20 4f 52 44  E clause and ORD
56d0: 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42  ER BY or GROUP B
56e0: 59 20 63 6c 61 75 73 65 73 20 0d 0a 20 20 20 20  Y clauses ..    
56f0: 20 20 20 20 2f 2f 2f 20 6f 66 20 74 68 65 20 71      /// of the q
5700: 75 65 72 79 2c 20 62 75 74 20 61 6c 73 6f 20 66  uery, but also f
5710: 72 6f 6d 20 61 6e 79 20 4f 4e 20 6f 72 20 55 53  rom any ON or US
5720: 49 4e 47 20 63 6c 61 75 73 65 73 20 69 66 20 74  ING clauses if t
5730: 68 65 20 71 75 65 72 79 20 69 73 20 61 20 0d 0a  he query is a ..
5740: 20 20 20 20 20 20 20 20 2f 2f 2f 20 6a 6f 69 6e          /// join
5750: 2e 20 54 68 65 20 69 6e 66 6f 72 6d 61 74 69 6f  . The informatio
5760: 6e 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74  n that the SQLit
5770: 65 20 63 6f 72 65 20 70 72 6f 76 69 64 65 73 20  e core provides 
5780: 74 6f 20 74 68 65 20 78 42 65 73 74 49 6e 64 65  to the xBestInde
5790: 78 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  x ..        /// 
57a0: 6d 65 74 68 6f 64 20 69 73 20 68 65 6c 64 20 69  method is held i
57b0: 6e 20 74 68 65 20 70 61 72 74 20 6f 66 20 74 68  n the part of th
57c0: 65 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74  e structure that
57d0: 20 69 73 20 6d 61 72 6b 65 64 20 61 73 20 22 49   is marked as "I
57e0: 6e 70 75 74 73 22 2e 20 0d 0a 20 20 20 20 20 20  nputs". ..      
57f0: 20 20 2f 2f 2f 20 54 68 65 20 22 4f 75 74 70 75    /// The "Outpu
5800: 74 73 22 20 73 65 63 74 69 6f 6e 20 69 73 20 69  ts" section is i
5810: 6e 69 74 69 61 6c 69 7a 65 64 20 74 6f 20 7a 65  nitialized to ze
5820: 72 6f 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ro...        ///
5830: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
5840: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
5850: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 69 6e        /// The in
5860: 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 20 74 68 65  formation in the
5870: 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
5880: 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20 69 73  nfo structure is
5890: 20 65 70 68 65 6d 65 72 61 6c 0d 0a 20 20 20 20   ephemeral..    
58a0: 20 20 20 20 2f 2f 2f 20 61 6e 64 20 6d 61 79 20      /// and may 
58b0: 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f  be overwritten o
58c0: 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 73  r deallocated as
58d0: 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 78 42 65   soon as the xBe
58e0: 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64 0d 0a  stIndex method..
58f0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 72 65 74 75          /// retu
5900: 72 6e 73 2e 20 20 49 66 20 74 68 65 20 78 42 65  rns.  If the xBe
5910: 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64 20 6e  stIndex method n
5920: 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72  eeds to remember
5930: 20 61 6e 79 20 70 61 72 74 20 6f 66 20 74 68 65   any part of the
5940: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 71  ..        /// sq
5950: 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
5960: 20 73 74 72 75 63 74 75 72 65 2c 20 69 74 20 73   structure, it s
5970: 68 6f 75 6c 64 20 6d 61 6b 65 20 61 20 63 6f 70  hould make a cop
5980: 79 2e 20 20 43 61 72 65 20 6d 75 73 74 20 62 65  y.  Care must be
5990: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 61  ..        /// ta
59a0: 6b 65 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20  ke to store the 
59b0: 63 6f 70 79 20 69 6e 20 61 20 70 6c 61 63 65 20  copy in a place 
59c0: 77 68 65 72 65 20 69 74 20 77 69 6c 6c 20 62 65  where it will be
59d0: 20 64 65 61 6c 6c 6f 63 61 74 65 64 2c 20 73 75   deallocated, su
59e0: 63 68 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ch..        /// 
59f0: 61 73 20 69 6e 20 74 68 65 20 69 64 78 53 74 72  as in the idxStr
5a00: 20 66 69 65 6c 64 20 77 69 74 68 20 6e 65 65 64   field with need
5a10: 54 6f 46 72 65 65 49 64 78 53 74 72 20 73 65 74  ToFreeIdxStr set
5a20: 20 74 6f 20 31 2e 0d 0a 20 20 20 20 20 20 20 20   to 1...        
5a30: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
5a40: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
5a50: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 4e 6f 74  .        /// Not
5a60: 65 20 74 68 61 74 20 78 42 65 73 74 49 6e 64 65  e that xBestInde
5a70: 78 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 62 65  x will always be
5a80: 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 78   called before x
5a90: 46 69 6c 74 65 72 2c 20 73 69 6e 63 65 0d 0a 20  Filter, since.. 
5aa0: 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 20 69         /// the i
5ab0: 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 53 74 72  dxNum and idxStr
5ac0: 20 6f 75 74 70 75 74 73 20 66 72 6f 6d 20 78 42   outputs from xB
5ad0: 65 73 74 49 6e 64 65 78 20 61 72 65 20 72 65 71  estIndex are req
5ae0: 75 69 72 65 64 20 69 6e 70 75 74 73 20 74 6f 0d  uired inputs to.
5af0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 78 46 69  .        /// xFi
5b00: 6c 74 65 72 2e 20 20 48 6f 77 65 76 65 72 2c 20  lter.  However, 
5b10: 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72  there is no guar
5b20: 61 6e 74 65 65 20 74 68 61 74 20 78 46 69 6c 74  antee that xFilt
5b30: 65 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65  er will be calle
5b40: 64 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 66  d..        /// f
5b50: 6f 6c 6c 6f 77 69 6e 67 20 61 20 73 75 63 63 65  ollowing a succe
5b60: 73 73 66 75 6c 20 78 42 65 73 74 49 6e 64 65 78  ssful xBestIndex
5b70: 2e 20 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  .  ..        ///
5b80: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
5b90: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
5ba0: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 42        /// The xB
5bb0: 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64 20  estIndex method 
5bc0: 69 73 20 72 65 71 75 69 72 65 64 20 66 6f 72 20  is required for 
5bd0: 65 76 65 72 79 20 76 69 72 74 75 61 6c 20 74 61  every virtual ta
5be0: 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
5bf0: 6f 6e 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  on...        ///
5c00: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
5c10: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
5c20: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 6d 61        /// The ma
5c30: 69 6e 20 74 68 69 6e 67 20 74 68 61 74 20 74 68  in thing that th
5c40: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 69 73  e SQLite core is
5c50: 20 74 72 79 69 6e 67 20 74 6f 20 63 6f 6d 6d 75   trying to commu
5c60: 6e 69 63 61 74 65 20 74 6f 20 0d 0a 20 20 20 20  nicate to ..    
5c70: 20 20 20 20 2f 2f 2f 20 74 68 65 20 76 69 72 74      /// the virt
5c80: 75 61 6c 20 74 61 62 6c 65 20 69 73 20 74 68 65  ual table is the
5c90: 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 74 68 61   constraints tha
5ca0: 74 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20  t are available 
5cb0: 74 6f 20 6c 69 6d 69 74 20 0d 0a 20 20 20 20 20  to limit ..     
5cc0: 20 20 20 2f 2f 2f 20 74 68 65 20 6e 75 6d 62 65     /// the numbe
5cd0: 72 20 6f 66 20 72 6f 77 73 20 74 68 61 74 20 6e  r of rows that n
5ce0: 65 65 64 20 74 6f 20 62 65 20 73 65 61 72 63 68  eed to be search
5cf0: 65 64 2e 20 54 68 65 20 61 43 6f 6e 73 74 72 61  ed. The aConstra
5d00: 69 6e 74 5b 5d 20 61 72 72 61 79 20 0d 0a 20 20  int[] array ..  
5d10: 20 20 20 20 20 20 2f 2f 2f 20 63 6f 6e 74 61 69        /// contai
5d20: 6e 73 20 6f 6e 65 20 65 6e 74 72 79 20 66 6f 72  ns one entry for
5d30: 20 65 61 63 68 20 63 6f 6e 73 74 72 61 69 6e 74   each constraint
5d40: 2e 20 54 68 65 72 65 20 77 69 6c 6c 20 62 65 20  . There will be 
5d50: 65 78 61 63 74 6c 79 20 0d 0a 20 20 20 20 20 20  exactly ..      
5d60: 20 20 2f 2f 2f 20 6e 43 6f 6e 73 74 72 61 69 6e    /// nConstrain
5d70: 74 20 65 6e 74 72 69 65 73 20 69 6e 20 74 68 61  t entries in tha
5d80: 74 20 61 72 72 61 79 2e 0d 0a 20 20 20 20 20 20  t array...      
5d90: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
5da0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
5db0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 45  >..        /// E
5dc0: 61 63 68 20 63 6f 6e 73 74 72 61 69 6e 74 20 77  ach constraint w
5dd0: 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74  ill correspond t
5de0: 6f 20 61 20 74 65 72 6d 20 69 6e 20 74 68 65 20  o a term in the 
5df0: 57 48 45 52 45 20 63 6c 61 75 73 65 0d 0a 20 20  WHERE clause..  
5e00: 20 20 20 20 20 20 2f 2f 2f 20 6f 72 20 69 6e 20        /// or in 
5e10: 61 20 55 53 49 4e 47 20 6f 72 20 4f 4e 20 63 6c  a USING or ON cl
5e20: 61 75 73 65 20 74 68 61 74 20 69 73 20 6f 66 20  ause that is of 
5e30: 74 68 65 20 66 6f 72 6d 0d 0a 20 20 20 20 20 20  the form..      
5e40: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
5e50: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
5e60: 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20  ><code>..       
5e70: 20 2f 2f 2f 20 20 20 20 20 20 63 6f 6c 75 6d 6e   ///      column
5e80: 20 20 4f 50 20 20 45 58 50 52 0d 0a 20 20 20 20    OP  EXPR..    
5e90: 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c      /// </code><
5ea0: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
5eb0: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20  /// <para>..    
5ec0: 20 20 20 20 2f 2f 2f 20 57 68 65 72 65 20 22 63      /// Where "c
5ed0: 6f 6c 75 6d 6e 22 20 69 73 20 61 20 63 6f 6c 75  olumn" is a colu
5ee0: 6d 6e 20 69 6e 20 74 68 65 20 76 69 72 74 75 61  mn in the virtua
5ef0: 6c 20 74 61 62 6c 65 2c 20 4f 50 20 69 73 20 61  l table, OP is a
5f00: 6e 20 6f 70 65 72 61 74 6f 72 20 0d 0a 20 20 20  n operator ..   
5f10: 20 20 20 20 20 2f 2f 2f 20 6c 69 6b 65 20 22 3d       /// like "=
5f20: 22 20 6f 72 20 22 26 6c 74 3b 22 2c 20 61 6e 64  " or "&lt;", and
5f30: 20 45 58 50 52 20 69 73 20 61 6e 20 61 72 62 69   EXPR is an arbi
5f40: 74 72 61 72 79 20 65 78 70 72 65 73 73 69 6f 6e  trary expression
5f50: 2e 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c  . So, for exampl
5f60: 65 2c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e,..        /// 
5f70: 69 66 20 74 68 65 20 57 48 45 52 45 20 63 6c 61  if the WHERE cla
5f80: 75 73 65 20 63 6f 6e 74 61 69 6e 65 64 20 61 20  use contained a 
5f90: 74 65 72 6d 20 6c 69 6b 65 20 74 68 69 73 3a 0d  term like this:.
5fa0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
5fb0: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
5fc0: 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a  / <para><code>..
5fd0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20          ///     
5fe0: 20 61 20 3d 20 35 0d 0a 20 20 20 20 20 20 20 20   a = 5..        
5ff0: 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72  /// </code></par
6000: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
6010: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
6020: 2f 2f 2f 20 54 68 65 6e 20 6f 6e 65 20 6f 66 20  /// Then one of 
6030: 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  the constraints 
6040: 77 6f 75 6c 64 20 62 65 20 6f 6e 20 74 68 65 20  would be on the 
6050: 22 61 22 20 63 6f 6c 75 6d 6e 20 77 69 74 68 20  "a" column with 
6060: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6f 70  ..        /// op
6070: 65 72 61 74 6f 72 20 22 3d 22 20 61 6e 64 20 61  erator "=" and a
6080: 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 66 20  n expression of 
6090: 22 35 22 2e 20 43 6f 6e 73 74 72 61 69 6e 74 73  "5". Constraints
60a0: 20 6e 65 65 64 20 6e 6f 74 20 68 61 76 65 20 61   need not have a
60b0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6c 69  ..        /// li
60c0: 74 65 72 61 6c 20 72 65 70 72 65 73 65 6e 74 61  teral representa
60d0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 57 48 45 52  tion of the WHER
60e0: 45 20 63 6c 61 75 73 65 2e 20 54 68 65 20 71 75  E clause. The qu
60f0: 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 20 6d 69  ery optimizer mi
6100: 67 68 74 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ght..        ///
6110: 20 6d 61 6b 65 20 74 72 61 6e 73 66 6f 72 6d 61   make transforma
6120: 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 0d 0a 20  tions to the .. 
6130: 20 20 20 20 20 20 20 2f 2f 2f 20 57 48 45 52 45         /// WHERE
6140: 20 63 6c 61 75 73 65 20 69 6e 20 6f 72 64 65 72   clause in order
6150: 20 74 6f 20 65 78 74 72 61 63 74 20 61 73 20 6d   to extract as m
6160: 61 6e 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  any constraints 
6170: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 61 73  ..        /// as
6180: 20 69 74 20 63 61 6e 2e 20 53 6f 2c 20 66 6f 72   it can. So, for
6190: 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65   example, if the
61a0: 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f   WHERE clause co
61b0: 6e 74 61 69 6e 65 64 20 73 6f 6d 65 74 68 69 6e  ntained somethin
61c0: 67 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  g ..        /// 
61d0: 6c 69 6b 65 20 74 68 69 73 3a 0d 0a 20 20 20 20  like this:..    
61e0: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
61f0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
6200: 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20  ra><code>..     
6210: 20 20 20 2f 2f 2f 20 20 20 20 20 20 78 20 42 45     ///      x BE
6220: 54 57 45 45 4e 20 31 30 20 41 4e 44 20 31 30 30  TWEEN 10 AND 100
6230: 20 41 4e 44 20 39 39 39 26 67 74 3b 79 0d 0a 20   AND 999&gt;y.. 
6240: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64         /// </cod
6250: 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  e></para>..     
6260: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20     /// <para>.. 
6270: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 71         /// The q
6280: 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 20 6d  uery optimizer m
6290: 69 67 68 74 20 74 72 61 6e 73 6c 61 74 65 20 74  ight translate t
62a0: 68 69 73 20 69 6e 74 6f 20 74 68 72 65 65 20 73  his into three s
62b0: 65 70 61 72 61 74 65 20 63 6f 6e 73 74 72 61 69  eparate constrai
62c0: 6e 74 73 3a 0d 0a 20 20 20 20 20 20 20 20 2f 2f  nts:..        //
62d0: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  / </para>..     
62e0: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f     /// <para><co
62f0: 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  de>..        ///
6300: 20 20 20 20 20 20 78 20 26 67 74 3b 3d 20 31 30        x &gt;= 10
6310: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20  ..        ///   
6320: 20 20 20 78 20 26 6c 74 3b 3d 20 31 30 30 0d 0a     x &lt;= 100..
6330: 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20          ///     
6340: 20 79 20 26 6c 74 3b 20 39 39 39 0d 0a 20 20 20   y &lt; 999..   
6350: 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e       /// </code>
6360: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
6370: 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20   /// <para>..   
6380: 20 20 20 20 20 2f 2f 2f 20 46 6f 72 20 65 61 63       /// For eac
6390: 68 20 63 6f 6e 73 74 72 61 69 6e 74 2c 20 74 68  h constraint, th
63a0: 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e  e aConstraint[].
63b0: 69 43 6f 6c 75 6d 6e 20 66 69 65 6c 64 20 69 6e  iColumn field in
63c0: 64 69 63 61 74 65 73 20 77 68 69 63 68 20 0d 0a  dicates which ..
63d0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 63 6f 6c 75          /// colu
63e0: 6d 6e 20 61 70 70 65 61 72 73 20 6f 6e 20 74 68  mn appears on th
63f0: 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65  e left-hand side
6400: 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 72 61 69   of the constrai
6410: 6e 74 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  nt...        ///
6420: 20 54 68 65 20 66 69 72 73 74 20 63 6f 6c 75 6d   The first colum
6430: 6e 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c  n of the virtual
6440: 20 74 61 62 6c 65 20 69 73 20 63 6f 6c 75 6d 6e   table is column
6450: 20 30 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f   0. ..        //
6460: 2f 20 54 68 65 20 72 6f 77 69 64 20 6f 66 20 74  / The rowid of t
6470: 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
6480: 20 69 73 20 63 6f 6c 75 6d 6e 20 2d 31 2e 20 0d   is column -1. .
6490: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65  .        /// The
64a0: 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f   aConstraint[].o
64b0: 70 20 66 69 65 6c 64 20 69 6e 64 69 63 61 74 65  p field indicate
64c0: 73 20 77 68 69 63 68 20 6f 70 65 72 61 74 6f 72  s which operator
64d0: 20 69 73 20 75 73 65 64 2e 20 0d 0a 20 20 20 20   is used. ..    
64e0: 20 20 20 20 2f 2f 2f 20 54 68 65 20 53 51 4c 49      /// The SQLI
64f0: 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
6500: 49 4e 54 5f 2a 20 63 6f 6e 73 74 61 6e 74 73 20  INT_* constants 
6510: 6d 61 70 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  map integer cons
6520: 74 61 6e 74 73 20 0d 0a 20 20 20 20 20 20 20 20  tants ..        
6530: 2f 2f 2f 20 69 6e 74 6f 20 6f 70 65 72 61 74 6f  /// into operato
6540: 72 20 76 61 6c 75 65 73 2e 0d 0a 20 20 20 20 20  r values...     
6550: 20 20 20 2f 2f 2f 20 43 6f 6c 75 6d 6e 73 20 6f     /// Columns o
6560: 63 63 75 72 20 69 6e 20 74 68 65 20 6f 72 64 65  ccur in the orde
6570: 72 20 74 68 65 79 20 77 65 72 65 20 64 65 66 69  r they were defi
6580: 6e 65 64 20 62 79 20 74 68 65 20 63 61 6c 6c 20  ned by the call 
6590: 74 6f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  to..        /// 
65a0: 73 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f  sqlite3_declare_
65b0: 76 74 61 62 28 29 20 69 6e 20 74 68 65 20 78 43  vtab() in the xC
65c0: 72 65 61 74 65 20 6f 72 20 78 43 6f 6e 6e 65 63  reate or xConnec
65d0: 74 20 6d 65 74 68 6f 64 2e 0d 0a 20 20 20 20 20  t method...     
65e0: 20 20 20 2f 2f 2f 20 48 69 64 64 65 6e 20 63 6f     /// Hidden co
65f0: 6c 75 6d 6e 73 20 61 72 65 20 63 6f 75 6e 74 65  lumns are counte
6600: 64 20 77 68 65 6e 20 64 65 74 65 72 6d 69 6e 69  d when determini
6610: 6e 67 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 6e  ng the column in
6620: 64 65 78 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  dex...        //
6630: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  / </para>..     
6640: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20     /// <para>.. 
6650: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 61         /// The a
6660: 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72  Constraint[] arr
6670: 61 79 20 63 6f 6e 74 61 69 6e 73 20 69 6e 66 6f  ay contains info
6680: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 6c  rmation about al
6690: 6c 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 0d 0a  l constraints ..
66a0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 61 74          /// that
66b0: 20 61 70 70 6c 79 20 74 6f 20 74 68 65 20 76 69   apply to the vi
66c0: 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 42 75 74  rtual table. But
66d0: 20 73 6f 6d 65 20 6f 66 20 74 68 65 20 63 6f 6e   some of the con
66e0: 73 74 72 61 69 6e 74 73 20 6d 69 67 68 74 0d 0a  straints might..
66f0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 6e 6f 74 20          /// not 
6700: 62 65 20 75 73 61 62 6c 65 20 62 65 63 61 75 73  be usable becaus
6710: 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 61 62  e of the way tab
6720: 6c 65 73 20 61 72 65 20 6f 72 64 65 72 65 64 20  les are ordered 
6730: 69 6e 20 61 20 6a 6f 69 6e 2e 20 0d 0a 20 20 20  in a join. ..   
6740: 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 42 65       /// The xBe
6750: 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64 20 6d  stIndex method m
6760: 75 73 74 20 74 68 65 72 65 66 6f 72 65 20 6f 6e  ust therefore on
6770: 6c 79 20 63 6f 6e 73 69 64 65 72 20 63 6f 6e 73  ly consider cons
6780: 74 72 61 69 6e 74 73 20 0d 0a 20 20 20 20 20 20  traints ..      
6790: 20 20 2f 2f 2f 20 74 68 61 74 20 68 61 76 65 20    /// that have 
67a0: 61 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  an aConstraint[]
67b0: 2e 75 73 61 62 6c 65 20 66 6c 61 67 20 77 68 69  .usable flag whi
67c0: 63 68 20 69 73 20 74 72 75 65 2e 0d 0a 20 20 20  ch is true...   
67d0: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e       /// </para>
67e0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
67f0: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
6800: 2f 20 49 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f  / In addition to
6810: 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f   WHERE clause co
6820: 6e 73 74 72 61 69 6e 74 73 2c 20 74 68 65 20 53  nstraints, the S
6830: 51 4c 69 74 65 20 63 6f 72 65 20 61 6c 73 6f 20  QLite core also 
6840: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 65  ..        /// te
6850: 6c 6c 73 20 74 68 65 20 78 42 65 73 74 49 6e 64  lls the xBestInd
6860: 65 78 20 6d 65 74 68 6f 64 20 61 62 6f 75 74 20  ex method about 
6870: 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  the ORDER BY cla
6880: 75 73 65 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f  use. ..        /
6890: 2f 2f 20 28 49 6e 20 61 6e 20 61 67 67 72 65 67  // (In an aggreg
68a0: 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 53  ate query, the S
68b0: 51 4c 69 74 65 20 63 6f 72 65 20 6d 69 67 68 74  QLite core might
68c0: 20 70 75 74 20 69 6e 20 47 52 4f 55 50 20 42 59   put in GROUP BY
68d0: 20 63 6c 61 75 73 65 20 0d 0a 20 20 20 20 20 20   clause ..      
68e0: 20 20 2f 2f 2f 20 69 6e 66 6f 72 6d 61 74 69 6f    /// informatio
68f0: 6e 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68  n in place of th
6900: 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
6910: 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c 20 62  e information, b
6920: 75 74 20 74 68 69 73 20 66 61 63 74 0d 0a 20 20  ut this fact..  
6930: 20 20 20 20 20 20 2f 2f 2f 20 73 68 6f 75 6c 64        /// should
6940: 20 6e 6f 74 20 6d 61 6b 65 20 61 6e 79 20 64 69   not make any di
6950: 66 66 65 72 65 6e 63 65 20 74 6f 20 74 68 65 20  fference to the 
6960: 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f  xBestIndex metho
6970: 64 2e 29 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  d.) ..        //
6980: 2f 20 49 66 20 61 6c 6c 20 74 65 72 6d 73 20 6f  / If all terms o
6990: 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  f the ORDER BY c
69a0: 6c 61 75 73 65 20 61 72 65 20 63 6f 6c 75 6d 6e  lause are column
69b0: 73 20 69 6e 20 74 68 65 20 76 69 72 74 75 61 6c  s in the virtual
69c0: 20 74 61 62 6c 65 2c 20 0d 0a 20 20 20 20 20 20   table, ..      
69d0: 20 20 2f 2f 2f 20 74 68 65 6e 20 6e 4f 72 64 65    /// then nOrde
69e0: 72 42 79 20 77 69 6c 6c 20 62 65 20 74 68 65 20  rBy will be the 
69f0: 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
6a00: 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  in the ORDER BY 
6a10: 63 6c 61 75 73 65 20 0d 0a 20 20 20 20 20 20 20  clause ..       
6a20: 20 2f 2f 2f 20 61 6e 64 20 74 68 65 20 61 4f 72   /// and the aOr
6a30: 64 65 72 42 79 5b 5d 20 61 72 72 61 79 20 77 69  derBy[] array wi
6a40: 6c 6c 20 69 64 65 6e 74 69 66 79 20 74 68 65 20  ll identify the 
6a50: 63 6f 6c 75 6d 6e 20 66 6f 72 20 65 61 63 68 20  column for each 
6a60: 74 65 72 6d 20 0d 0a 20 20 20 20 20 20 20 20 2f  term ..        /
6a70: 2f 2f 20 69 6e 20 74 68 65 20 6f 72 64 65 72 20  // in the order 
6a80: 62 79 20 63 6c 61 75 73 65 20 61 6e 64 20 77 68  by clause and wh
6a90: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 61  ether or not tha
6aa0: 74 20 63 6f 6c 75 6d 6e 20 69 73 20 41 53 43 20  t column is ASC 
6ab0: 6f 72 20 44 45 53 43 2e 0d 0a 20 20 20 20 20 20  or DESC...      
6ac0: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
6ad0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
6ae0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 49  >..        /// I
6af0: 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
6b00: 20 33 2e 31 30 2e 30 20 61 6e 64 20 6c 61 74 65   3.10.0 and late
6b10: 72 2c 20 74 68 65 20 63 6f 6c 55 73 65 64 20 66  r, the colUsed f
6b20: 69 65 6c 64 20 69 73 20 61 76 61 69 6c 61 62 6c  ield is availabl
6b30: 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74  e..        /// t
6b40: 6f 20 69 6e 64 69 63 61 74 65 20 77 68 69 63 68  o indicate which
6b50: 20 66 69 65 6c 64 73 20 6f 66 20 74 68 65 20 76   fields of the v
6b60: 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61 72 65  irtual table are
6b70: 20 61 63 74 75 61 6c 6c 79 20 75 73 65 64 20 62   actually used b
6b80: 79 20 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f  y the..        /
6b90: 2f 2f 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69  // statement bei
6ba0: 6e 67 20 70 72 65 70 61 72 65 64 2e 20 20 49 66  ng prepared.  If
6bb0: 20 74 68 65 20 6c 6f 77 65 73 74 20 62 69 74 20   the lowest bit 
6bc0: 6f 66 20 63 6f 6c 55 73 65 64 20 69 73 20 73 65  of colUsed is se
6bd0: 74 2c 20 74 68 61 74 0d 0a 20 20 20 20 20 20 20  t, that..       
6be0: 20 2f 2f 2f 20 6d 65 61 6e 73 20 74 68 61 74 20   /// means that 
6bf0: 74 68 65 20 66 69 72 73 74 20 63 6f 6c 75 6d 6e  the first column
6c00: 20 69 73 20 75 73 65 64 2e 20 20 54 68 65 20 73   is used.  The s
6c10: 65 63 6f 6e 64 20 6c 6f 77 65 73 74 20 62 69 74  econd lowest bit
6c20: 20 63 6f 72 72 65 73 70 6f 6e 64 73 0d 0a 20 20   corresponds..  
6c30: 20 20 20 20 20 20 2f 2f 2f 20 74 6f 20 74 68 65        /// to the
6c40: 20 73 65 63 6f 6e 64 20 63 6f 6c 75 6d 6e 2e 20   second column. 
6c50: 20 41 6e 64 20 73 6f 20 66 6f 72 74 68 2e 20 20   And so forth.  
6c60: 49 66 20 74 68 65 20 6d 6f 73 74 20 73 69 67 6e  If the most sign
6c70: 69 66 69 63 61 6e 74 20 62 69 74 20 6f 66 0d 0a  ificant bit of..
6c80: 20 20 20 20 20 20 20 20 2f 2f 2f 20 63 6f 6c 55          /// colU
6c90: 73 65 64 20 69 73 20 73 65 74 2c 20 74 68 61 74  sed is set, that
6ca0: 20 6d 65 61 6e 73 20 74 68 61 74 20 6f 6e 65 20   means that one 
6cb0: 6f 72 20 6d 6f 72 65 20 63 6f 6c 75 6d 6e 73 20  or more columns 
6cc0: 6f 74 68 65 72 20 74 68 61 6e 20 74 68 65 20 0d  other than the .
6cd0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 66 69 72  .        /// fir
6ce0: 73 74 20 36 33 20 63 6f 6c 75 6d 6e 73 20 61 72  st 63 columns ar
6cf0: 65 20 75 73 65 64 2e 20 20 49 66 20 63 6f 6c 75  e used.  If colu
6d00: 6d 6e 20 75 73 61 67 65 20 69 6e 66 6f 72 6d 61  mn usage informa
6d10: 74 69 6f 6e 20 69 73 20 6e 65 65 64 65 64 20 62  tion is needed b
6d20: 79 20 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f  y the..        /
6d30: 2f 2f 20 78 46 69 6c 74 65 72 20 6d 65 74 68 6f  // xFilter metho
6d40: 64 2c 20 74 68 65 6e 20 74 68 65 20 72 65 71 75  d, then the requ
6d50: 69 72 65 64 20 62 69 74 73 20 6d 75 73 74 20 62  ired bits must b
6d60: 65 20 65 6e 63 6f 64 65 64 20 69 6e 74 6f 20 65  e encoded into e
6d70: 69 74 68 65 72 0d 0a 20 20 20 20 20 20 20 20 2f  ither..        /
6d80: 2f 2f 20 74 68 65 20 69 64 78 4e 75 6d 20 6f 72  // the idxNum or
6d90: 20 69 64 78 53 74 72 20 6f 75 74 70 75 74 20 66   idxStr output f
6da0: 69 65 6c 64 73 2e 0d 0a 20 20 20 20 20 20 20 20  ields...        
6db0: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
6dc0: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
6dd0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 47 69 76  .        /// Giv
6de0: 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 20 69 6e  en all of the in
6df0: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 76 65 2c  formation above,
6e00: 20 74 68 65 20 6a 6f 62 20 6f 66 20 74 68 65 20   the job of the 
6e10: 78 42 65 73 74 49 6e 64 65 78 20 0d 0a 20 20 20  xBestIndex ..   
6e20: 20 20 20 20 20 2f 2f 2f 20 6d 65 74 68 6f 64 20       /// method 
6e30: 69 74 20 74 6f 20 66 69 67 75 72 65 20 6f 75 74  it to figure out
6e40: 20 74 68 65 20 62 65 73 74 20 77 61 79 20 74 6f   the best way to
6e50: 20 73 65 61 72 63 68 20 74 68 65 20 76 69 72 74   search the virt
6e60: 75 61 6c 20 74 61 62 6c 65 2e 0d 0a 20 20 20 20  ual table...    
6e70: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
6e80: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
6e90: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
6ea0: 20 54 68 65 20 78 42 65 73 74 49 6e 64 65 78 20   The xBestIndex 
6eb0: 6d 65 74 68 6f 64 20 66 69 6c 6c 73 20 74 68 65  method fills the
6ec0: 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 53   idxNum and idxS
6ed0: 74 72 20 66 69 65 6c 64 73 20 77 69 74 68 20 0d  tr fields with .
6ee0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e 66  .        /// inf
6ef0: 6f 72 6d 61 74 69 6f 6e 20 74 68 61 74 20 63 6f  ormation that co
6f00: 6d 6d 75 6e 69 63 61 74 65 73 20 61 6e 20 69 6e  mmunicates an in
6f10: 64 65 78 69 6e 67 20 73 74 72 61 74 65 67 79 20  dexing strategy 
6f20: 74 6f 20 74 68 65 20 78 46 69 6c 74 65 72 20 0d  to the xFilter .
6f30: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6d 65 74  .        /// met
6f40: 68 6f 64 2e 20 54 68 65 20 69 6e 66 6f 72 6d 61  hod. The informa
6f50: 74 69 6f 6e 20 69 6e 20 69 64 78 4e 75 6d 20 61  tion in idxNum a
6f60: 6e 64 20 69 64 78 53 74 72 20 69 73 20 61 72 62  nd idxStr is arb
6f70: 69 74 72 61 72 79 20 61 73 20 66 61 72 20 0d 0a  itrary as far ..
6f80: 20 20 20 20 20 20 20 20 2f 2f 2f 20 61 73 20 74          /// as t
6f90: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 69  he SQLite core i
6fa0: 73 20 63 6f 6e 63 65 72 6e 65 64 2e 20 54 68 65  s concerned. The
6fb0: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6a 75 73   SQLite core jus
6fc0: 74 20 63 6f 70 69 65 73 20 74 68 65 20 0d 0a 20  t copies the .. 
6fd0: 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e 66 6f 72         /// infor
6fe0: 6d 61 74 69 6f 6e 20 74 68 72 6f 75 67 68 20 74  mation through t
6ff0: 6f 20 74 68 65 20 78 46 69 6c 74 65 72 20 6d 65  o the xFilter me
7000: 74 68 6f 64 2e 20 41 6e 79 20 64 65 73 69 72 65  thod. Any desire
7010: 64 20 6d 65 61 6e 69 6e 67 20 63 61 6e 20 0d 0a  d meaning can ..
7020: 20 20 20 20 20 20 20 20 2f 2f 2f 20 62 65 20 61          /// be a
7030: 73 73 69 67 6e 65 64 20 74 6f 20 69 64 78 4e 75  ssigned to idxNu
7040: 6d 20 61 6e 64 20 69 64 78 53 74 72 20 61 73 20  m and idxStr as 
7050: 6c 6f 6e 67 20 61 73 20 78 42 65 73 74 49 6e 64  long as xBestInd
7060: 65 78 20 61 6e 64 20 78 46 69 6c 74 65 72 20 0d  ex and xFilter .
7070: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 61 67 72  .        /// agr
7080: 65 65 20 6f 6e 20 77 68 61 74 20 74 68 61 74 20  ee on what that 
7090: 6d 65 61 6e 69 6e 67 20 69 73 2e 0d 0a 20 20 20  meaning is...   
70a0: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e       /// </para>
70b0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
70c0: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
70d0: 2f 20 54 68 65 20 69 64 78 53 74 72 20 76 61 6c  / The idxStr val
70e0: 75 65 20 6d 61 79 20 62 65 20 61 20 73 74 72 69  ue may be a stri
70f0: 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ng obtained from
7100: 20 61 6e 20 53 51 4c 69 74 65 0d 0a 20 20 20 20   an SQLite..    
7110: 20 20 20 20 2f 2f 2f 20 6d 65 6d 6f 72 79 20 61      /// memory a
7120: 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69  llocation functi
7130: 6f 6e 20 73 75 63 68 20 61 73 20 73 71 6c 69 74  on such as sqlit
7140: 65 33 5f 6d 70 72 69 6e 74 66 28 29 2e 20 0d 0a  e3_mprintf(). ..
7150: 20 20 20 20 20 20 20 20 2f 2f 2f 20 49 66 20 74          /// If t
7160: 68 69 73 20 69 73 20 74 68 65 20 63 61 73 65 2c  his is the case,
7170: 20 74 68 65 6e 20 74 68 65 20 6e 65 65 64 54 6f   then the needTo
7180: 46 72 65 65 49 64 78 53 74 72 20 66 6c 61 67 20  FreeIdxStr flag 
7190: 6d 75 73 74 20 62 65 20 73 65 74 20 74 6f 20 0d  must be set to .
71a0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 72 75  .        /// tru
71b0: 65 20 73 6f 20 74 68 61 74 20 74 68 65 20 53 51  e so that the SQ
71c0: 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6b  Lite core will k
71d0: 6e 6f 77 20 74 6f 20 63 61 6c 6c 20 73 71 6c 69  now to call sqli
71e0: 74 65 33 5f 66 72 65 65 28 29 20 6f 6e 20 0d 0a  te3_free() on ..
71f0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 61 74          /// that
7200: 20 73 74 72 69 6e 67 20 77 68 65 6e 20 69 74 20   string when it 
7210: 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
7220: 68 20 69 74 2c 20 61 6e 64 20 74 68 75 73 20 61  h it, and thus a
7230: 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65  void a memory le
7240: 61 6b 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ak...        ///
7250: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
7260: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
7270: 20 20 20 20 20 20 2f 2f 2f 20 49 66 20 74 68 65        /// If the
7280: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 77   virtual table w
7290: 69 6c 6c 20 6f 75 74 70 75 74 20 72 6f 77 73 20  ill output rows 
72a0: 69 6e 20 74 68 65 20 6f 72 64 65 72 20 73 70 65  in the order spe
72b0: 63 69 66 69 65 64 20 62 79 20 0d 0a 20 20 20 20  cified by ..    
72c0: 20 20 20 20 2f 2f 2f 20 74 68 65 20 4f 52 44 45      /// the ORDE
72d0: 52 20 42 59 20 63 6c 61 75 73 65 2c 20 74 68 65  R BY clause, the
72e0: 6e 20 74 68 65 20 6f 72 64 65 72 42 79 43 6f 6e  n the orderByCon
72f0: 73 75 6d 65 64 20 66 6c 61 67 20 6d 61 79 20 62  sumed flag may b
7300: 65 20 73 65 74 20 74 6f 20 0d 0a 20 20 20 20 20  e set to ..     
7310: 20 20 20 2f 2f 2f 20 74 72 75 65 2e 20 49 66 20     /// true. If 
7320: 74 68 65 20 6f 75 74 70 75 74 20 69 73 20 6e 6f  the output is no
7330: 74 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  t automatically 
7340: 69 6e 20 74 68 65 20 63 6f 72 72 65 63 74 20 6f  in the correct o
7350: 72 64 65 72 20 0d 0a 20 20 20 20 20 20 20 20 2f  rder ..        /
7360: 2f 2f 20 74 68 65 6e 20 6f 72 64 65 72 42 79 43  // then orderByC
7370: 6f 6e 73 75 6d 65 64 20 6d 75 73 74 20 62 65 20  onsumed must be 
7380: 6c 65 66 74 20 69 6e 20 69 74 73 20 64 65 66 61  left in its defa
7390: 75 6c 74 20 66 61 6c 73 65 20 73 65 74 74 69 6e  ult false settin
73a0: 67 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  g. ..        ///
73b0: 20 54 68 69 73 20 77 69 6c 6c 20 69 6e 64 69 63   This will indic
73c0: 61 74 65 20 74 6f 20 74 68 65 20 53 51 4c 69 74  ate to the SQLit
73d0: 65 20 63 6f 72 65 20 74 68 61 74 20 69 74 20 77  e core that it w
73e0: 69 6c 6c 20 6e 65 65 64 20 74 6f 20 64 6f 20 61  ill need to do a
73f0: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73   ..        /// s
7400: 65 70 61 72 61 74 65 20 73 6f 72 74 69 6e 67 20  eparate sorting 
7410: 70 61 73 73 20 6f 76 65 72 20 74 68 65 20 64 61  pass over the da
7420: 74 61 20 61 66 74 65 72 20 69 74 20 63 6f 6d 65  ta after it come
7430: 73 20 6f 75 74 20 6f 66 20 74 68 65 20 76 69 72  s out of the vir
7440: 74 75 61 6c 20 74 61 62 6c 65 2e 0d 0a 20 20 20  tual table...   
7450: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e       /// </para>
7460: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
7470: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
7480: 2f 20 54 68 65 20 65 73 74 69 6d 61 74 65 64 43  / The estimatedC
7490: 6f 73 74 20 66 69 65 6c 64 20 73 68 6f 75 6c 64  ost field should
74a0: 20 62 65 20 73 65 74 20 74 6f 20 74 68 65 20 65   be set to the e
74b0: 73 74 69 6d 61 74 65 64 20 6e 75 6d 62 65 72 0d  stimated number.
74c0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6f 66 20  .        /// of 
74d0: 64 69 73 6b 20 61 63 63 65 73 73 20 6f 70 65 72  disk access oper
74e0: 61 74 69 6f 6e 73 20 72 65 71 75 69 72 65 64 20  ations required 
74f0: 74 6f 20 65 78 65 63 75 74 65 20 74 68 69 73 20  to execute this 
7500: 71 75 65 72 79 20 61 67 61 69 6e 73 74 20 0d 0a  query against ..
7510: 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 20          /// the 
7520: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 54  virtual table. T
7530: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77  he SQLite core w
7540: 69 6c 6c 20 6f 66 74 65 6e 20 63 61 6c 6c 20 78  ill often call x
7550: 42 65 73 74 49 6e 64 65 78 20 0d 0a 20 20 20 20  BestIndex ..    
7560: 20 20 20 20 2f 2f 2f 20 6d 75 6c 74 69 70 6c 65      /// multiple
7570: 20 74 69 6d 65 73 20 77 69 74 68 20 64 69 66 66   times with diff
7580: 65 72 65 6e 74 20 63 6f 6e 73 74 72 61 69 6e 74  erent constraint
7590: 73 2c 20 6f 62 74 61 69 6e 20 6d 75 6c 74 69 70  s, obtain multip
75a0: 6c 65 20 63 6f 73 74 0d 0a 20 20 20 20 20 20 20  le cost..       
75b0: 20 2f 2f 2f 20 65 73 74 69 6d 61 74 65 73 2c 20   /// estimates, 
75c0: 74 68 65 6e 20 63 68 6f 6f 73 65 20 74 68 65 20  then choose the 
75d0: 71 75 65 72 79 20 70 6c 61 6e 20 74 68 61 74 20  query plan that 
75e0: 67 69 76 65 73 20 74 68 65 20 6c 6f 77 65 73 74  gives the lowest
75f0: 20 65 73 74 69 6d 61 74 65 2e 0d 0a 20 20 20 20   estimate...    
7600: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
7610: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
7620: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
7630: 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   If the current 
7640: 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74  version of SQLit
7650: 65 20 69 73 20 33 2e 38 2e 32 20 6f 72 20 67 72  e is 3.8.2 or gr
7660: 65 61 74 65 72 2c 20 74 68 65 20 65 73 74 69 6d  eater, the estim
7670: 61 74 65 64 52 6f 77 73 0d 0a 20 20 20 20 20 20  atedRows..      
7680: 20 20 2f 2f 2f 20 66 69 65 6c 64 20 6d 61 79 20    /// field may 
7690: 62 65 20 73 65 74 20 74 6f 20 61 6e 20 65 73 74  be set to an est
76a0: 69 6d 61 74 65 20 6f 66 20 74 68 65 20 6e 75 6d  imate of the num
76b0: 62 65 72 20 6f 66 20 72 6f 77 73 20 72 65 74 75  ber of rows retu
76c0: 72 6e 65 64 20 62 79 20 74 68 65 0d 0a 20 20 20  rned by the..   
76d0: 20 20 20 20 20 2f 2f 2f 20 70 72 6f 70 6f 73 65       /// propose
76e0: 64 20 71 75 65 72 79 20 70 6c 61 6e 2e 20 49 66  d query plan. If
76f0: 20 74 68 69 73 20 76 61 6c 75 65 20 69 73 20 6e   this value is n
7700: 6f 74 20 65 78 70 6c 69 63 69 74 6c 79 20 73 65  ot explicitly se
7710: 74 2c 20 74 68 65 20 64 65 66 61 75 6c 74 20 0d  t, the default .
7720: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 65 73 74  .        /// est
7730: 69 6d 61 74 65 20 6f 66 20 32 35 20 72 6f 77 73  imate of 25 rows
7740: 20 69 73 20 75 73 65 64 2e 0d 0a 20 20 20 20 20   is used...     
7750: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a     /// </para>..
7760: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
7770: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
7780: 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  If the current v
7790: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
77a0: 20 69 73 20 33 2e 39 2e 30 20 6f 72 20 67 72 65   is 3.9.0 or gre
77b0: 61 74 65 72 2c 20 74 68 65 20 69 64 78 46 6c 61  ater, the idxFla
77c0: 67 73 20 66 69 65 6c 64 0d 0a 20 20 20 20 20 20  gs field..      
77d0: 20 20 2f 2f 2f 20 6d 61 79 20 62 65 20 73 65 74    /// may be set
77e0: 20 74 6f 20 53 51 4c 49 54 45 5f 49 4e 44 45 58   to SQLITE_INDEX
77f0: 5f 53 43 41 4e 5f 55 4e 49 51 55 45 20 74 6f 20  _SCAN_UNIQUE to 
7800: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 74 68  indicate that th
7810: 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 0d  e virtual table.
7820: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 77 69 6c  .        /// wil
7830: 6c 20 72 65 74 75 72 6e 20 6f 6e 6c 79 20 7a 65  l return only ze
7840: 72 6f 20 6f 72 20 6f 6e 65 20 72 6f 77 73 20 67  ro or one rows g
7850: 69 76 65 6e 20 74 68 65 20 69 6e 70 75 74 20 63  iven the input c
7860: 6f 6e 73 74 72 61 69 6e 74 73 2e 20 20 41 64 64  onstraints.  Add
7870: 69 74 69 6f 6e 61 6c 0d 0a 20 20 20 20 20 20 20  itional..       
7880: 20 2f 2f 2f 20 62 69 74 73 20 6f 66 20 74 68 65   /// bits of the
7890: 20 69 64 78 46 6c 61 67 73 20 66 69 65 6c 64 20   idxFlags field 
78a0: 6d 69 67 68 74 20 62 65 20 75 6e 64 65 72 73 74  might be underst
78b0: 6f 6f 64 20 69 6e 20 6c 61 74 65 72 20 76 65 72  ood in later ver
78c0: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
78d0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
78e0: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
78f0: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20  // <para>..     
7900: 20 20 20 2f 2f 2f 20 54 68 65 20 61 43 6f 6e 73     /// The aCons
7910: 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 61 72  traintUsage[] ar
7920: 72 61 79 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 65  ray contains one
7930: 20 65 6c 65 6d 65 6e 74 20 66 6f 72 20 65 61 63   element for eac
7940: 68 20 6f 66 20 0d 0a 20 20 20 20 20 20 20 20 2f  h of ..        /
7950: 2f 2f 20 74 68 65 20 6e 43 6f 6e 73 74 72 61 69  // the nConstrai
7960: 6e 74 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 69  nt constraints i
7970: 6e 20 74 68 65 20 69 6e 70 75 74 73 20 73 65 63  n the inputs sec
7980: 74 69 6f 6e 20 6f 66 20 74 68 65 20 0d 0a 20 20  tion of the ..  
7990: 20 20 20 20 20 20 2f 2f 2f 20 73 71 6c 69 74 65        /// sqlite
79a0: 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72  3_index_info str
79b0: 75 63 74 75 72 65 2e 20 0d 0a 20 20 20 20 20 20  ucture. ..      
79c0: 20 20 2f 2f 2f 20 54 68 65 20 61 43 6f 6e 73 74    /// The aConst
79d0: 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 61 72 72  raintUsage[] arr
79e0: 61 79 20 69 73 20 75 73 65 64 20 62 79 20 78 42  ay is used by xB
79f0: 65 73 74 49 6e 64 65 78 20 74 6f 20 74 65 6c 6c  estIndex to tell
7a00: 20 74 68 65 20 0d 0a 20 20 20 20 20 20 20 20 2f   the ..        /
7a10: 2f 2f 20 63 6f 72 65 20 68 6f 77 20 69 74 20 69  // core how it i
7a20: 73 20 75 73 69 6e 67 20 74 68 65 20 63 6f 6e 73  s using the cons
7a30: 74 72 61 69 6e 74 73 2e 0d 0a 20 20 20 20 20 20  traints...      
7a40: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
7a50: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
7a60: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54  >..        /// T
7a70: 68 65 20 78 42 65 73 74 49 6e 64 65 78 20 6d 65  he xBestIndex me
7a80: 74 68 6f 64 20 6d 61 79 20 73 65 74 20 61 43 6f  thod may set aCo
7a90: 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e  nstraintUsage[].
7aa0: 61 72 67 76 49 6e 64 65 78 20 0d 0a 20 20 20 20  argvIndex ..    
7ab0: 20 20 20 20 2f 2f 2f 20 65 6e 74 72 69 65 73 20      /// entries 
7ac0: 74 6f 20 76 61 6c 75 65 73 20 67 72 65 61 74 65  to values greate
7ad0: 72 20 74 68 61 6e 20 7a 65 72 6f 2e 20 0d 0a 20  r than zero. .. 
7ae0: 20 20 20 20 20 20 20 2f 2f 2f 20 45 78 61 63 74         /// Exact
7af0: 6c 79 20 6f 6e 65 20 65 6e 74 72 79 20 73 68 6f  ly one entry sho
7b00: 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 31 2c  uld be set to 1,
7b10: 20 61 6e 6f 74 68 65 72 20 74 6f 20 32 2c 20 61   another to 2, a
7b20: 6e 6f 74 68 65 72 20 74 6f 20 33 2c 20 0d 0a 20  nother to 3, .. 
7b30: 20 20 20 20 20 20 20 2f 2f 2f 20 61 6e 64 20 73         /// and s
7b40: 6f 20 66 6f 72 74 68 20 75 70 20 74 6f 20 61 73  o forth up to as
7b50: 20 6d 61 6e 79 20 6f 72 20 61 73 20 66 65 77 20   many or as few 
7b60: 61 73 20 74 68 65 20 78 42 65 73 74 49 6e 64 65  as the xBestInde
7b70: 78 20 6d 65 74 68 6f 64 20 77 61 6e 74 73 2e 20  x method wants. 
7b80: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
7b90: 65 20 45 58 50 52 20 6f 66 20 74 68 65 20 63 6f  e EXPR of the co
7ba0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 63 6f 6e 73  rresponding cons
7bb0: 74 72 61 69 6e 74 73 20 77 69 6c 6c 20 74 68 65  traints will the
7bc0: 6e 20 62 65 20 70 61 73 73 65 64 20 0d 0a 20 20  n be passed ..  
7bd0: 20 20 20 20 20 20 2f 2f 2f 20 69 6e 20 61 73 20        /// in as 
7be0: 74 68 65 20 61 72 67 76 5b 5d 20 70 61 72 61 6d  the argv[] param
7bf0: 65 74 65 72 73 20 74 6f 20 78 46 69 6c 74 65 72  eters to xFilter
7c00: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
7c10: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
7c20: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20  /// <para>..    
7c30: 20 20 20 20 2f 2f 2f 20 46 6f 72 20 65 78 61 6d      /// For exam
7c40: 70 6c 65 2c 20 69 66 20 74 68 65 20 61 43 6f 6e  ple, if the aCon
7c50: 73 74 72 61 69 6e 74 5b 33 5d 2e 61 72 67 76 49  straint[3].argvI
7c60: 6e 64 65 78 20 69 73 20 73 65 74 20 74 6f 20 31  ndex is set to 1
7c70: 2c 20 74 68 65 6e 20 0d 0a 20 20 20 20 20 20 20  , then ..       
7c80: 20 2f 2f 2f 20 77 68 65 6e 20 78 46 69 6c 74 65   /// when xFilte
7c90: 72 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65  r is called, the
7ca0: 20 61 72 67 76 5b 30 5d 20 70 61 73 73 65 64 20   argv[0] passed 
7cb0: 74 6f 20 78 46 69 6c 74 65 72 20 77 69 6c 6c 20  to xFilter will 
7cc0: 68 61 76 65 20 0d 0a 20 20 20 20 20 20 20 20 2f  have ..        /
7cd0: 2f 2f 20 74 68 65 20 45 58 50 52 20 76 61 6c 75  // the EXPR valu
7ce0: 65 20 6f 66 20 74 68 65 20 61 43 6f 6e 73 74 72  e of the aConstr
7cf0: 61 69 6e 74 5b 33 5d 20 63 6f 6e 73 74 72 61 69  aint[3] constrai
7d00: 6e 74 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  nt...        ///
7d10: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
7d20: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
7d30: 20 20 20 20 20 20 2f 2f 2f 20 42 79 20 64 65 66        /// By def
7d40: 61 75 6c 74 2c 20 74 68 65 20 53 51 4c 69 74 65  ault, the SQLite
7d50: 20 63 6f 72 65 20 64 6f 75 62 6c 65 20 63 68 65   core double che
7d60: 63 6b 73 20 61 6c 6c 20 63 6f 6e 73 74 72 61 69  cks all constrai
7d70: 6e 74 73 20 6f 6e 20 0d 0a 20 20 20 20 20 20 20  nts on ..       
7d80: 20 2f 2f 2f 20 65 61 63 68 20 72 6f 77 20 6f 66   /// each row of
7d90: 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
7da0: 6c 65 20 74 68 61 74 20 69 74 20 72 65 63 65 69  le that it recei
7db0: 76 65 73 2e 20 49 66 20 73 75 63 68 20 61 20 63  ves. If such a c
7dc0: 68 65 63 6b 20 0d 0a 20 20 20 20 20 20 20 20 2f  heck ..        /
7dd0: 2f 2f 20 69 73 20 72 65 64 75 6e 64 61 6e 74 2c  // is redundant,
7de0: 20 74 68 65 20 78 42 65 73 74 46 69 6c 74 65 72   the xBestFilter
7df0: 20 6d 65 74 68 6f 64 20 63 61 6e 20 73 75 70 70   method can supp
7e00: 72 65 73 73 20 74 68 61 74 20 64 6f 75 62 6c 65  ress that double
7e10: 2d 63 68 65 63 6b 20 62 79 20 0d 0a 20 20 20 20  -check by ..    
7e20: 20 20 20 20 2f 2f 2f 20 73 65 74 74 69 6e 67 20      /// setting 
7e30: 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65  aConstraintUsage
7e40: 5b 5d 2e 6f 6d 69 74 2e 0d 0a 20 20 20 20 20 20  [].omit...      
7e50: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
7e60: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d         /// </sum
7e70: 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f  mary>..        /
7e80: 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22  // <param name="
7e90: 70 56 74 61 62 22 3e 0d 0a 20 20 20 20 20 20 20  pVtab">..       
7ea0: 20 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76 65 20   /// The native 
7eb0: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73  pointer to the s
7ec0: 71 6c 69 74 65 33 5f 76 74 61 62 20 64 65 72 69  qlite3_vtab deri
7ed0: 76 65 64 20 73 74 72 75 63 74 75 72 65 2e 0d 0a  ved structure...
7ee0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
7ef0: 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ram>..        //
7f00: 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70  / <param name="p
7f10: 49 6e 64 65 78 22 3e 0d 0a 20 20 20 20 20 20 20  Index">..       
7f20: 20 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76 65 20   /// The native 
7f30: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73  pointer to the s
7f40: 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
7f50: 6f 20 73 74 72 75 63 74 75 72 65 2e 0d 0a 20 20  o structure...  
7f60: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61        /// </para
7f70: 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  m>..        /// 
7f80: 3c 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20  <returns>..     
7f90: 20 20 20 2f 2f 2f 20 41 20 73 74 61 6e 64 61 72     /// A standar
7fa0: 64 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 20  d SQLite return 
7fb0: 63 6f 64 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f  code...        /
7fc0: 2f 2f 20 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a 20  // </returns>.. 
7fd0: 20 20 20 20 20 20 20 53 51 4c 69 74 65 45 72 72         SQLiteErr
7fe0: 6f 72 43 6f 64 65 20 78 42 65 73 74 49 6e 64 65  orCode xBestInde
7ff0: 78 28 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20  x(..            
8000: 49 6e 74 50 74 72 20 70 56 74 61 62 2c 0d 0a 20  IntPtr pVtab,.. 
8010: 20 20 20 20 20 20 20 20 20 20 20 49 6e 74 50 74             IntPt
8020: 72 20 70 49 6e 64 65 78 0d 0a 20 20 20 20 20 20  r pIndex..      
8030: 20 20 20 20 20 20 29 3b 0d 0a 0d 0a 20 20 20 20        );....    
8040: 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f      ////////////
8050: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8060: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8070: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8080: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20  ///////////.... 
8090: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d         /// <summ
80a0: 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ary>..        //
80b0: 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a  / <para><code>..
80c0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 69 6e          ///   in
80d0: 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29  t (*xDisconnect)
80e0: 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
80f0: 56 54 61 62 29 3b 0d 0a 20 20 20 20 20 20 20 20  VTab);..        
8100: 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72  /// </code></par
8110: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
8120: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
8130: 2f 2f 2f 20 54 68 69 73 20 6d 65 74 68 6f 64 20  /// This method 
8140: 72 65 6c 65 61 73 65 73 20 61 20 63 6f 6e 6e 65  releases a conne
8150: 63 74 69 6f 6e 20 74 6f 20 61 20 76 69 72 74 75  ction to a virtu
8160: 61 6c 20 74 61 62 6c 65 2e 20 0d 0a 20 20 20 20  al table. ..    
8170: 20 20 20 20 2f 2f 2f 20 4f 6e 6c 79 20 74 68 65      /// Only the
8180: 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 6f 62   sqlite3_vtab ob
8190: 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f 79 65  ject is destroye
81a0: 64 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  d...        /// 
81b0: 54 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  The virtual tabl
81c0: 65 20 69 73 20 6e 6f 74 20 64 65 73 74 72 6f 79  e is not destroy
81d0: 65 64 20 61 6e 64 20 61 6e 79 20 62 61 63 6b 69  ed and any backi
81e0: 6e 67 20 73 74 6f 72 65 20 0d 0a 20 20 20 20 20  ng store ..     
81f0: 20 20 20 2f 2f 2f 20 61 73 73 6f 63 69 61 74 65     /// associate
8200: 64 20 77 69 74 68 20 74 68 65 20 76 69 72 74 75  d with the virtu
8210: 61 6c 20 74 61 62 6c 65 20 70 65 72 73 69 73 74  al table persist
8220: 73 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  s. ..        ///
8230: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
8240: 20 20 2f 2f 2f 20 54 68 69 73 20 6d 65 74 68 6f    /// This metho
8250: 64 20 75 6e 64 6f 65 73 20 74 68 65 20 77 6f 72  d undoes the wor
8260: 6b 20 6f 66 20 78 43 6f 6e 6e 65 63 74 2e 0d 0a  k of xConnect...
8270: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
8280: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
8290: 54 68 69 73 20 6d 65 74 68 6f 64 20 69 73 20 61  This method is a
82a0: 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20   destructor for 
82b0: 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  a connection to 
82c0: 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
82d0: 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e...        /// 
82e0: 43 6f 6e 74 72 61 73 74 20 74 68 69 73 20 6d 65  Contrast this me
82f0: 74 68 6f 64 20 77 69 74 68 20 78 44 65 73 74 72  thod with xDestr
8300: 6f 79 2e 20 20 54 68 65 20 78 44 65 73 74 72 6f  oy.  The xDestro
8310: 79 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  y is a destructo
8320: 72 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 66  r..        /// f
8330: 6f 72 20 74 68 65 20 65 6e 74 69 72 65 20 76 69  or the entire vi
8340: 72 74 75 61 6c 20 74 61 62 6c 65 2e 0d 0a 20 20  rtual table...  
8350: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61        /// </para
8360: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
8370: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
8380: 2f 2f 20 54 68 65 20 78 44 69 73 63 6f 6e 6e 65  // The xDisconne
8390: 63 74 20 6d 65 74 68 6f 64 20 69 73 20 72 65 71  ct method is req
83a0: 75 69 72 65 64 20 66 6f 72 20 65 76 65 72 79 20  uired for every 
83b0: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d  virtual table im
83c0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 0d 0a 20  plementation,.. 
83d0: 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 6f 75 67         /// thoug
83e0: 68 20 69 74 20 69 73 20 61 63 63 65 70 74 61 62  h it is acceptab
83f0: 6c 65 20 66 6f 72 20 74 68 65 20 78 44 69 73 63  le for the xDisc
8400: 6f 6e 6e 65 63 74 20 61 6e 64 20 78 44 65 73 74  onnect and xDest
8410: 72 6f 79 20 6d 65 74 68 6f 64 73 20 74 6f 20 62  roy methods to b
8420: 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74  e..        /// t
8430: 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
8440: 20 69 66 20 74 68 61 74 20 6d 61 6b 65 73 20 73   if that makes s
8450: 65 6e 73 65 20 66 6f 72 20 74 68 65 20 70 61 72  ense for the par
8460: 74 69 63 75 6c 61 72 20 76 69 72 74 75 61 6c 20  ticular virtual 
8470: 74 61 62 6c 65 2e 0d 0a 20 20 20 20 20 20 20 20  table...        
8480: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
8490: 20 20 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61       /// </summa
84a0: 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ry>..        ///
84b0: 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 56   <param name="pV
84c0: 74 61 62 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f  tab">..        /
84d0: 2f 2f 20 54 68 65 20 6e 61 74 69 76 65 20 70 6f  // The native po
84e0: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  inter to the sql
84f0: 69 74 65 33 5f 76 74 61 62 20 64 65 72 69 76 65  ite3_vtab derive
8500: 64 20 73 74 72 75 63 74 75 72 65 2e 0d 0a 20 20  d structure...  
8510: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61        /// </para
8520: 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  m>..        /// 
8530: 3c 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20  <returns>..     
8540: 20 20 20 2f 2f 2f 20 41 20 73 74 61 6e 64 61 72     /// A standar
8550: 64 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 20  d SQLite return 
8560: 63 6f 64 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f  code...        /
8570: 2f 2f 20 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a 20  // </returns>.. 
8580: 20 20 20 20 20 20 20 53 51 4c 69 74 65 45 72 72         SQLiteErr
8590: 6f 72 43 6f 64 65 20 78 44 69 73 63 6f 6e 6e 65  orCode xDisconne
85a0: 63 74 28 0d 0a 20 20 20 20 20 20 20 20 20 20 20  ct(..           
85b0: 20 49 6e 74 50 74 72 20 70 56 74 61 62 0d 0a 20   IntPtr pVtab.. 
85c0: 20 20 20 20 20 20 20 20 20 20 20 29 3b 0d 0a 0d             );...
85d0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f  .        ///////
85e0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
85f0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8600: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8610: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8620: 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ....        /// 
8630: 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20  <summary>..     
8640: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f     /// <para><co
8650: 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  de>..        ///
8660: 20 20 20 69 6e 74 20 28 2a 78 44 65 73 74 72 6f     int (*xDestro
8670: 79 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  y)(sqlite3_vtab 
8680: 2a 70 56 54 61 62 29 3b 0d 0a 20 20 20 20 20 20  *pVTab);..      
8690: 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70    /// </code></p
86a0: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
86b0: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
86c0: 20 20 2f 2f 2f 20 54 68 69 73 20 6d 65 74 68 6f    /// This metho
86d0: 64 20 72 65 6c 65 61 73 65 73 20 61 20 63 6f 6e  d releases a con
86e0: 6e 65 63 74 69 6f 6e 20 74 6f 20 61 20 76 69 72  nection to a vir
86f0: 74 75 61 6c 20 74 61 62 6c 65 2c 20 6a 75 73 74  tual table, just
8700: 20 6c 69 6b 65 20 0d 0a 20 20 20 20 20 20 20 20   like ..        
8710: 2f 2f 2f 20 74 68 65 20 78 44 69 73 63 6f 6e 6e  /// the xDisconn
8720: 65 63 74 20 6d 65 74 68 6f 64 2c 20 61 6e 64 20  ect method, and 
8730: 69 74 20 61 6c 73 6f 20 64 65 73 74 72 6f 79 73  it also destroys
8740: 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
8750: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 61  ..        /// ta
8760: 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
8770: 6f 6e 2e 20 54 68 69 73 20 6d 65 74 68 6f 64 20  on. This method 
8780: 75 6e 64 6f 65 73 20 74 68 65 20 77 6f 72 6b 20  undoes the work 
8790: 6f 66 20 78 43 72 65 61 74 65 2e 0d 0a 20 20 20  of xCreate...   
87a0: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e       /// </para>
87b0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
87c0: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
87d0: 2f 20 54 68 65 20 78 44 69 73 63 6f 6e 6e 65 63  / The xDisconnec
87e0: 74 20 6d 65 74 68 6f 64 20 69 73 20 63 61 6c 6c  t method is call
87f0: 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 64 61  ed whenever a da
8800: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
8810: 6e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74  n..        /// t
8820: 68 61 74 20 75 73 65 73 20 61 20 76 69 72 74 75  hat uses a virtu
8830: 61 6c 20 74 61 62 6c 65 20 69 73 20 63 6c 6f 73  al table is clos
8840: 65 64 2e 20 54 68 65 20 78 44 65 73 74 72 6f 79  ed. The xDestroy
8850: 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20   method is only 
8860: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 63 61  ..        /// ca
8870: 6c 6c 65 64 20 77 68 65 6e 20 61 20 44 52 4f 50  lled when a DROP
8880: 20 54 41 42 4c 45 20 73 74 61 74 65 6d 65 6e 74   TABLE statement
8890: 20 69 73 20 65 78 65 63 75 74 65 64 20 61 67 61   is executed aga
88a0: 69 6e 73 74 20 74 68 65 20 76 69 72 74 75 61 6c  inst the virtual
88b0: 20 74 61 62 6c 65 2e 0d 0a 20 20 20 20 20 20 20   table...       
88c0: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
88d0: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
88e0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
88f0: 65 20 78 44 65 73 74 72 6f 79 20 6d 65 74 68 6f  e xDestroy metho
8900: 64 20 69 73 20 72 65 71 75 69 72 65 64 20 66 6f  d is required fo
8910: 72 20 65 76 65 72 79 20 76 69 72 74 75 61 6c 20  r every virtual 
8920: 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
8930: 74 69 6f 6e 2c 0d 0a 20 20 20 20 20 20 20 20 2f  tion,..        /
8940: 2f 2f 20 74 68 6f 75 67 68 20 69 74 20 69 73 20  // though it is 
8950: 61 63 63 65 70 74 61 62 6c 65 20 66 6f 72 20 74  acceptable for t
8960: 68 65 20 78 44 69 73 63 6f 6e 6e 65 63 74 20 61  he xDisconnect a
8970: 6e 64 20 78 44 65 73 74 72 6f 79 20 6d 65 74 68  nd xDestroy meth
8980: 6f 64 73 20 74 6f 20 62 65 0d 0a 20 20 20 20 20  ods to be..     
8990: 20 20 20 2f 2f 2f 20 74 68 65 20 73 61 6d 65 20     /// the same 
89a0: 66 75 6e 63 74 69 6f 6e 20 69 66 20 74 68 61 74  function if that
89b0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 66 6f 72   makes sense for
89c0: 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
89d0: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 0d 0a  virtual table...
89e0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
89f0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
8a00: 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20   </summary>..   
8a10: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20       /// <param 
8a20: 6e 61 6d 65 3d 22 70 56 74 61 62 22 3e 0d 0a 20  name="pVtab">.. 
8a30: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e         /// The n
8a40: 61 74 69 76 65 20 70 6f 69 6e 74 65 72 20 74 6f  ative pointer to
8a50: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 74 61   the sqlite3_vta
8a60: 62 20 64 65 72 69 76 65 64 20 73 74 72 75 63 74  b derived struct
8a70: 75 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ure...        //
8a80: 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20  / </param>..    
8a90: 20 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72 6e 73      /// <returns
8aa0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41  >..        /// A
8ab0: 20 73 74 61 6e 64 61 72 64 20 53 51 4c 69 74 65   standard SQLite
8ac0: 20 72 65 74 75 72 6e 20 63 6f 64 65 2e 0d 0a 20   return code... 
8ad0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72 65 74         /// </ret
8ae0: 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 53  urns>..        S
8af0: 51 4c 69 74 65 45 72 72 6f 72 43 6f 64 65 20 78  QLiteErrorCode x
8b00: 44 65 73 74 72 6f 79 28 0d 0a 20 20 20 20 20 20  Destroy(..      
8b10: 20 20 20 20 20 20 49 6e 74 50 74 72 20 70 56 74        IntPtr pVt
8b20: 61 62 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20  ab..            
8b30: 29 3b 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f  );....        //
8b40: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8b50: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8b60: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8b70: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
8b80: 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 20 20 20  /////....       
8b90: 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a   /// <summary>..
8ba0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
8bb0: 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20  a><code>..      
8bc0: 20 20 2f 2f 2f 20 20 20 69 6e 74 20 28 2a 78 4f    ///   int (*xO
8bd0: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61  pen)(sqlite3_vta
8be0: 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65  b *pVTab, sqlite
8bf0: 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a  3_vtab_cursor **
8c00: 70 70 43 75 72 73 6f 72 29 3b 0d 0a 20 20 20 20  ppCursor);..    
8c10: 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c      /// </code><
8c20: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
8c30: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20  /// <para>..    
8c40: 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 4f 70 65      /// The xOpe
8c50: 6e 20 6d 65 74 68 6f 64 20 63 72 65 61 74 65 73  n method creates
8c60: 20 61 20 6e 65 77 20 63 75 72 73 6f 72 20 75 73   a new cursor us
8c70: 65 64 20 66 6f 72 20 61 63 63 65 73 73 69 6e 67  ed for accessing
8c80: 20 28 72 65 61 64 20 61 6e 64 2f 6f 72 0d 0a 20   (read and/or.. 
8c90: 20 20 20 20 20 20 20 2f 2f 2f 20 77 72 69 74 69         /// writi
8ca0: 6e 67 29 20 61 20 76 69 72 74 75 61 6c 20 74 61  ng) a virtual ta
8cb0: 62 6c 65 2e 20 20 41 20 73 75 63 63 65 73 73 66  ble.  A successf
8cc0: 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ul invocation of
8cd0: 20 74 68 69 73 20 6d 65 74 68 6f 64 20 0d 0a 20   this method .. 
8ce0: 20 20 20 20 20 20 20 2f 2f 2f 20 77 69 6c 6c 20         /// will 
8cf0: 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 6d 65 6d  allocate the mem
8d00: 6f 72 79 20 66 6f 72 20 74 68 65 20 73 71 6c 69  ory for the sqli
8d10: 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20  te3_vtab_cursor 
8d20: 28 6f 72 20 61 20 73 75 62 63 6c 61 73 73 29 2c  (or a subclass),
8d30: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e  ..        /// in
8d40: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6e 65 77  itialize the new
8d50: 20 6f 62 6a 65 63 74 2c 20 61 6e 64 20 6d 61 6b   object, and mak
8d60: 65 20 2a 70 70 43 75 72 73 6f 72 20 70 6f 69 6e  e *ppCursor poin
8d70: 74 20 74 6f 20 74 68 65 20 6e 65 77 20 6f 62 6a  t to the new obj
8d80: 65 63 74 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ect...        //
8d90: 2f 20 54 68 65 20 73 75 63 63 65 73 73 66 75 6c  / The successful
8da0: 20 63 61 6c 6c 20 74 68 65 6e 20 72 65 74 75 72   call then retur
8db0: 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0d 0a 20  ns SQLITE_OK... 
8dc0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
8dd0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
8de0: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
8df0: 2f 2f 2f 20 46 6f 72 20 65 76 65 72 79 20 73 75  /// For every su
8e00: 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
8e10: 20 74 68 69 73 20 6d 65 74 68 6f 64 2c 20 74 68   this method, th
8e20: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69  e SQLite core wi
8e30: 6c 6c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ll..        /// 
8e40: 6c 61 74 65 72 20 69 6e 76 6f 6b 65 20 74 68 65  later invoke the
8e50: 20 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 20 74   xClose method t
8e60: 6f 20 64 65 73 74 72 6f 79 20 0d 0a 20 20 20 20  o destroy ..    
8e70: 20 20 20 20 2f 2f 2f 20 74 68 65 20 61 6c 6c 6f      /// the allo
8e80: 63 61 74 65 64 20 63 75 72 73 6f 72 2e 0d 0a 20  cated cursor... 
8e90: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
8ea0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
8eb0: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
8ec0: 2f 2f 2f 20 54 68 65 20 78 4f 70 65 6e 20 6d 65  /// The xOpen me
8ed0: 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 69 6e  thod need not in
8ee0: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 70 56 74  itialize the pVt
8ef0: 61 62 20 66 69 65 6c 64 20 6f 66 20 74 68 65 0d  ab field of the.
8f00: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 71 6c  .        /// sql
8f10: 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
8f20: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
8f30: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c   SQLite core wil
8f40: 6c 20 74 61 6b 65 20 63 61 72 65 0d 0a 20 20 20  l take care..   
8f50: 20 20 20 20 20 2f 2f 2f 20 6f 66 20 74 68 61 74       /// of that
8f60: 20 63 68 6f 72 65 20 61 75 74 6f 6d 61 74 69 63   chore automatic
8f70: 61 6c 6c 79 2e 0d 0a 20 20 20 20 20 20 20 20 2f  ally...        /
8f80: 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  // </para>..    
8f90: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a      /// <para>..
8fa0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 20 76 69          /// A vi
8fb0: 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c  rtual table impl
8fc0: 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20  ementation must 
8fd0: 62 65 20 61 62 6c 65 20 74 6f 20 73 75 70 70 6f  be able to suppo
8fe0: 72 74 20 61 6e 20 61 72 62 69 74 72 61 72 79 0d  rt an arbitrary.
8ff0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6e 75 6d  .        /// num
9000: 62 65 72 20 6f 66 20 73 69 6d 75 6c 74 61 6e 65  ber of simultane
9010: 6f 75 73 6c 79 20 6f 70 65 6e 20 63 75 72 73 6f  ously open curso
9020: 72 73 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  rs...        ///
9030: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
9040: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
9050: 20 20 20 20 20 20 2f 2f 2f 20 57 68 65 6e 20 69        /// When i
9060: 6e 69 74 69 61 6c 6c 79 20 6f 70 65 6e 65 64 2c  nitially opened,
9070: 20 74 68 65 20 63 75 72 73 6f 72 20 69 73 20 69   the cursor is i
9080: 6e 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 73  n an undefined s
9090: 74 61 74 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f  tate...        /
90a0: 2f 2f 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  // The SQLite co
90b0: 72 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  re will invoke t
90c0: 68 65 20 78 46 69 6c 74 65 72 20 6d 65 74 68 6f  he xFilter metho
90d0: 64 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6f  d..        /// o
90e0: 6e 20 74 68 65 20 63 75 72 73 6f 72 20 70 72 69  n the cursor pri
90f0: 6f 72 20 74 6f 20 61 6e 79 20 61 74 74 65 6d 70  or to any attemp
9100: 74 20 74 6f 20 70 6f 73 69 74 69 6f 6e 20 6f 72  t to position or
9110: 20 72 65 61 64 20 66 72 6f 6d 20 74 68 65 20 63   read from the c
9120: 75 72 73 6f 72 2e 0d 0a 20 20 20 20 20 20 20 20  ursor...        
9130: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
9140: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
9150: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65  .        /// The
9160: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 69 73   xOpen method is
9170: 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 65 76   required for ev
9180: 65 72 79 20 76 69 72 74 75 61 6c 20 74 61 62 6c  ery virtual tabl
9190: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
91a0: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
91b0: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
91c0: 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a  /// </summary>..
91d0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
91e0: 61 6d 20 6e 61 6d 65 3d 22 70 56 74 61 62 22 3e  am name="pVtab">
91f0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
9200: 65 20 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72  e native pointer
9210: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
9220: 76 74 61 62 20 64 65 72 69 76 65 64 20 73 74 72  vtab derived str
9230: 75 63 74 75 72 65 2e 0d 0a 20 20 20 20 20 20 20  ucture...       
9240: 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20   /// </param>.. 
9250: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
9260: 6d 20 6e 61 6d 65 3d 22 70 43 75 72 73 6f 72 22  m name="pCursor"
9270: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 55  >..        /// U
9280: 70 6f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 69  pon success, thi
9290: 73 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  s parameter must
92a0: 20 62 65 20 6d 6f 64 69 66 69 65 64 20 74 6f 20   be modified to 
92b0: 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 6e 65 77  point to the new
92c0: 6c 79 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ly..        /// 
92d0: 63 72 65 61 74 65 64 20 6e 61 74 69 76 65 20 73  created native s
92e0: 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
92f0: 6f 72 20 64 65 72 69 76 65 64 20 73 74 72 75 63  or derived struc
9300: 74 75 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f  ture...        /
9310: 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20  // </param>..   
9320: 20 20 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72 6e       /// <return
9330: 73 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  s>..        /// 
9340: 41 20 73 74 61 6e 64 61 72 64 20 53 51 4c 69 74  A standard SQLit
9350: 65 20 72 65 74 75 72 6e 20 63 6f 64 65 2e 0d 0a  e return code...
9360: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72 65          /// </re
9370: 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20  turns>..        
9380: 53 51 4c 69 74 65 45 72 72 6f 72 43 6f 64 65 20  SQLiteErrorCode 
9390: 78 4f 70 65 6e 28 0d 0a 20 20 20 20 20 20 20 20  xOpen(..        
93a0: 20 20 20 20 49 6e 74 50 74 72 20 70 56 74 61 62      IntPtr pVtab
93b0: 2c 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 72  ,..            r
93c0: 65 66 20 49 6e 74 50 74 72 20 70 43 75 72 73 6f  ef IntPtr pCurso
93d0: 72 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 29  r..            )
93e0: 3b 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ;....        ///
93f0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
9400: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
9410: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
9420: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
9430: 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 20 20 20 20  ////....        
9440: 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20  /// <summary>.. 
9450: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
9460: 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20  ><code>..       
9470: 20 2f 2f 2f 20 20 20 69 6e 74 20 28 2a 78 43 6c   ///   int (*xCl
9480: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ose)(sqlite3_vta
9490: 62 5f 63 75 72 73 6f 72 2a 29 3b 0d 0a 20 20 20  b_cursor*);..   
94a0: 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e       /// </code>
94b0: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
94c0: 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20   /// <para>..   
94d0: 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 43 6c       /// The xCl
94e0: 6f 73 65 20 6d 65 74 68 6f 64 20 63 6c 6f 73 65  ose method close
94f0: 73 20 61 20 63 75 72 73 6f 72 20 70 72 65 76 69  s a cursor previ
9500: 6f 75 73 6c 79 20 6f 70 65 6e 65 64 20 62 79 20  ously opened by 
9510: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 78 4f  ..        /// xO
9520: 70 65 6e 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f  pen. ..        /
9530: 2f 2f 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  // The SQLite co
9540: 72 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  re will always c
9550: 61 6c 6c 20 78 43 6c 6f 73 65 20 6f 6e 63 65 20  all xClose once 
9560: 66 6f 72 20 65 61 63 68 20 63 75 72 73 6f 72 20  for each cursor 
9570: 6f 70 65 6e 65 64 20 0d 0a 20 20 20 20 20 20 20  opened ..       
9580: 20 2f 2f 2f 20 75 73 69 6e 67 20 78 4f 70 65 6e   /// using xOpen
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 69 73 20 6d 65 74      /// This met
95d0: 68 6f 64 20 6d 75 73 74 20 72 65 6c 65 61 73 65  hod must release
95e0: 20 61 6c 6c 20 72 65 73 6f 75 72 63 65 73 20 61   all resources a
95f0: 6c 6c 6f 63 61 74 65 64 20 62 79 20 74 68 65 0d  llocated by the.
9600: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 63 6f 72  .        /// cor
9610: 72 65 73 70 6f 6e 64 69 6e 67 20 78 4f 70 65 6e  responding xOpen
9620: 20 63 61 6c 6c 2e 20 54 68 65 20 72 6f 75 74 69   call. The routi
9630: 6e 65 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 63  ne will not be c
9640: 61 6c 6c 65 64 20 61 67 61 69 6e 20 65 76 65 6e  alled again even
9650: 20 69 66 20 69 74 0d 0a 20 20 20 20 20 20 20 20   if it..        
9660: 2f 2f 2f 20 72 65 74 75 72 6e 73 20 61 6e 20 65  /// returns an e
9670: 72 72 6f 72 2e 20 20 54 68 65 20 53 51 4c 69 74  rror.  The SQLit
9680: 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 6f 74 20  e core will not 
9690: 75 73 65 20 74 68 65 0d 0a 20 20 20 20 20 20 20  use the..       
96a0: 20 2f 2f 2f 20 73 71 6c 69 74 65 33 5f 76 74 61   /// sqlite3_vta
96b0: 62 5f 63 75 72 73 6f 72 20 61 67 61 69 6e 20 61  b_cursor again a
96c0: 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
96d0: 20 63 6c 6f 73 65 64 2e 0d 0a 20 20 20 20 20 20   closed...      
96e0: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
96f0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
9700: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54  >..        /// T
9710: 68 65 20 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  he xClose method
9720: 20 69 73 20 72 65 71 75 69 72 65 64 20 66 6f 72   is required for
9730: 20 65 76 65 72 79 20 76 69 72 74 75 61 6c 20 74   every virtual t
9740: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
9750: 69 6f 6e 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ion...        //
9760: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  / </para>..     
9770: 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79     /// </summary
9780: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
9790: 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 43 75 72  param name="pCur
97a0: 73 6f 72 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f  sor">..        /
97b0: 2f 2f 20 54 68 65 20 6e 61 74 69 76 65 20 70 6f  // The native po
97c0: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  inter to the sql
97d0: 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
97e0: 20 64 65 72 69 76 65 64 20 73 74 72 75 63 74 75   derived structu
97f0: 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  re...        ///
9800: 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20   </param>..     
9810: 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72 6e 73 3e     /// <returns>
9820: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 20  ..        /// A 
9830: 73 74 61 6e 64 61 72 64 20 53 51 4c 69 74 65 20  standard SQLite 
9840: 72 65 74 75 72 6e 20 63 6f 64 65 2e 0d 0a 20 20  return code...  
9850: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72 65 74 75        /// </retu
9860: 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 53 51  rns>..        SQ
9870: 4c 69 74 65 45 72 72 6f 72 43 6f 64 65 20 78 43  LiteErrorCode xC
9880: 6c 6f 73 65 28 0d 0a 20 20 20 20 20 20 20 20 20  lose(..         
9890: 20 20 20 49 6e 74 50 74 72 20 70 43 75 72 73 6f     IntPtr pCurso
98a0: 72 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 29  r..            )
98b0: 3b 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ;....        ///
98c0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
98d0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
98e0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
98f0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
9900: 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 20 20 20 20  ////....        
9910: 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20  /// <summary>.. 
9920: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
9930: 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20  ><code>..       
9940: 20 2f 2f 2f 20 20 20 69 6e 74 20 28 2a 78 46 69   ///   int (*xFi
9950: 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f 76 74  lter)(sqlite3_vt
9960: 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20  ab_cursor*, int 
9970: 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68  idxNum, const ch
9980: 61 72 20 2a 69 64 78 53 74 72 2c 0d 0a 20 20 20  ar *idxStr,..   
9990: 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 20 20 20       ///        
99a0: 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
99b0: 63 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  c, sqlite3_value
99c0: 20 2a 2a 61 72 67 76 29 3b 0d 0a 20 20 20 20 20   **argv);..     
99d0: 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f     /// </code></
99e0: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
99f0: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20  // <para>..     
9a00: 20 20 20 2f 2f 2f 20 54 68 69 73 20 6d 65 74 68     /// This meth
9a10: 6f 64 20 62 65 67 69 6e 73 20 61 20 73 65 61 72  od begins a sear
9a20: 63 68 20 6f 66 20 61 20 76 69 72 74 75 61 6c 20  ch of a virtual 
9a30: 74 61 62 6c 65 2e 20 0d 0a 20 20 20 20 20 20 20  table. ..       
9a40: 20 2f 2f 2f 20 54 68 65 20 66 69 72 73 74 20 61   /// The first a
9a50: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63 75 72  rgument is a cur
9a60: 73 6f 72 20 6f 70 65 6e 65 64 20 62 79 20 78 4f  sor opened by xO
9a70: 70 65 6e 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f  pen. ..        /
9a80: 2f 2f 20 54 68 65 20 6e 65 78 74 20 74 77 6f 20  // The next two 
9a90: 61 72 67 75 6d 65 6e 74 73 20 64 65 66 69 6e 65  arguments define
9aa0: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 65   a particular se
9ab0: 61 72 63 68 20 69 6e 64 65 78 20 70 72 65 76 69  arch index previ
9ac0: 6f 75 73 6c 79 20 0d 0a 20 20 20 20 20 20 20 20  ously ..        
9ad0: 2f 2f 2f 20 63 68 6f 73 65 6e 20 62 79 20 78 42  /// chosen by xB
9ae0: 65 73 74 49 6e 64 65 78 2e 20 54 68 65 20 73 70  estIndex. The sp
9af0: 65 63 69 66 69 63 20 6d 65 61 6e 69 6e 67 73 20  ecific meanings 
9b00: 6f 66 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64  of idxNum and id
9b10: 78 53 74 72 20 0d 0a 20 20 20 20 20 20 20 20 2f  xStr ..        /
9b20: 2f 2f 20 61 72 65 20 75 6e 69 6d 70 6f 72 74 61  // are unimporta
9b30: 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 78 46  nt as long as xF
9b40: 69 6c 74 65 72 20 61 6e 64 20 78 42 65 73 74 49  ilter and xBestI
9b50: 6e 64 65 78 20 61 67 72 65 65 20 6f 6e 20 77 68  ndex agree on wh
9b60: 61 74 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  at ..        ///
9b70: 20 74 68 61 74 20 6d 65 61 6e 69 6e 67 20 69 73   that meaning is
9b80: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
9b90: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
9ba0: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20  /// <para>..    
9bb0: 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 42 65 73      /// The xBes
9bc0: 74 49 6e 64 65 78 20 66 75 6e 63 74 69 6f 6e 20  tIndex function 
9bd0: 6d 61 79 20 68 61 76 65 20 72 65 71 75 65 73 74  may have request
9be0: 65 64 20 74 68 65 20 76 61 6c 75 65 73 20 6f 66  ed the values of
9bf0: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 63   ..        /// c
9c00: 65 72 74 61 69 6e 20 65 78 70 72 65 73 73 69 6f  ertain expressio
9c10: 6e 73 20 75 73 69 6e 67 20 74 68 65 20 61 43 6f  ns using the aCo
9c20: 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e  nstraintUsage[].
9c30: 61 72 67 76 49 6e 64 65 78 20 76 61 6c 75 65 73  argvIndex values
9c40: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6f   ..        /// o
9c50: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  f the sqlite3_in
9c60: 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75  dex_info structu
9c70: 72 65 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  re. ..        //
9c80: 2f 20 54 68 6f 73 65 20 76 61 6c 75 65 73 20 61  / Those values a
9c90: 72 65 20 70 61 73 73 65 64 20 74 6f 20 78 46 69  re passed to xFi
9ca0: 6c 74 65 72 20 75 73 69 6e 67 20 74 68 65 20 61  lter using the a
9cb0: 72 67 63 20 61 6e 64 20 61 72 67 76 20 70 61 72  rgc and argv par
9cc0: 61 6d 65 74 65 72 73 2e 0d 0a 20 20 20 20 20 20  ameters...      
9cd0: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
9ce0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
9cf0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 49  >..        /// I
9d00: 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  f the virtual ta
9d10: 62 6c 65 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 65  ble contains one
9d20: 20 6f 72 20 6d 6f 72 65 20 72 6f 77 73 20 74 68   or more rows th
9d30: 61 74 20 6d 61 74 63 68 20 74 68 65 0d 0a 20 20  at match the..  
9d40: 20 20 20 20 20 20 2f 2f 2f 20 73 65 61 72 63 68        /// search
9d50: 20 63 72 69 74 65 72 69 61 2c 20 74 68 65 6e 20   criteria, then 
9d60: 74 68 65 20 63 75 72 73 6f 72 20 6d 75 73 74 20  the cursor must 
9d70: 62 65 20 6c 65 66 74 20 70 6f 69 6e 74 20 61 74  be left point at
9d80: 20 74 68 65 20 66 69 72 73 74 20 72 6f 77 2e 0d   the first row..
9d90: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 53 75 62  .        /// Sub
9da0: 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
9db0: 20 78 45 6f 66 20 6d 75 73 74 20 72 65 74 75 72   xEof must retur
9dc0: 6e 20 66 61 6c 73 65 20 28 7a 65 72 6f 29 2e 0d  n false (zero)..
9dd0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 49 66 20  .        /// If 
9de0: 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 6f 77  there are no row
9df0: 73 20 6d 61 74 63 68 2c 20 74 68 65 6e 20 74 68  s match, then th
9e00: 65 20 63 75 72 73 6f 72 20 6d 75 73 74 20 62 65  e cursor must be
9e10: 20 6c 65 66 74 20 69 6e 20 61 20 73 74 61 74 65   left in a state
9e20: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74   ..        /// t
9e30: 68 61 74 20 77 69 6c 6c 20 63 61 75 73 65 20 74  hat will cause t
9e40: 68 65 20 78 45 6f 66 20 74 6f 20 72 65 74 75 72  he xEof to retur
9e50: 6e 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  n true (non-zero
9e60: 29 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  )...        /// 
9e70: 54 68 65 20 53 51 4c 69 74 65 20 65 6e 67 69 6e  The SQLite engin
9e80: 65 20 77 69 6c 6c 20 75 73 65 0d 0a 20 20 20 20  e will use..    
9e90: 20 20 20 20 2f 2f 2f 20 74 68 65 20 78 43 6f 6c      /// the xCol
9ea0: 75 6d 6e 20 61 6e 64 20 78 52 6f 77 69 64 20 6d  umn and xRowid m
9eb0: 65 74 68 6f 64 73 20 74 6f 20 61 63 63 65 73 73  ethods to access
9ec0: 20 74 68 61 74 20 72 6f 77 20 63 6f 6e 74 65 6e   that row conten
9ed0: 74 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  t...        /// 
9ee0: 54 68 65 20 78 4e 65 78 74 20 6d 65 74 68 6f 64  The xNext method
9ef0: 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f   will be used to
9f00: 20 61 64 76 61 6e 63 65 20 74 6f 20 74 68 65 20   advance to the 
9f10: 6e 65 78 74 20 72 6f 77 2e 0d 0a 20 20 20 20 20  next row...     
9f20: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a     /// </para>..
9f30: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
9f40: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
9f50: 54 68 69 73 20 6d 65 74 68 6f 64 20 6d 75 73 74  This method must
9f60: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
9f70: 4b 20 69 66 20 73 75 63 63 65 73 73 66 75 6c 2c  K if successful,
9f80: 20 6f 72 20 61 6e 20 73 71 6c 69 74 65 20 0d 0a   or an sqlite ..
9f90: 20 20 20 20 20 20 20 20 2f 2f 2f 20 65 72 72 6f          /// erro
9fa0: 72 20 63 6f 64 65 20 69 66 20 61 6e 20 65 72 72  r code if an err
9fb0: 6f 72 20 6f 63 63 75 72 73 2e 0d 0a 20 20 20 20  or occurs...    
9fc0: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
9fd0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
9fe0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
9ff0: 20 54 68 65 20 78 46 69 6c 74 65 72 20 6d 65 74   The xFilter met
a000: 68 6f 64 20 69 73 20 72 65 71 75 69 72 65 64 20  hod is required 
a010: 66 6f 72 20 65 76 65 72 79 20 76 69 72 74 75 61  for every virtua
a020: 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  l table implemen
a030: 74 61 74 69 6f 6e 2e 0d 0a 20 20 20 20 20 20 20  tation...       
a040: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
a050: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d        /// </summ
a060: 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ary>..        //
a070: 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70  / <param name="p
a080: 43 75 72 73 6f 72 22 3e 0d 0a 20 20 20 20 20 20  Cursor">..      
a090: 20 20 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76 65    /// The native
a0a0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
a0b0: 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
a0c0: 73 6f 72 20 64 65 72 69 76 65 64 20 73 74 72 75  sor derived stru
a0d0: 63 74 75 72 65 2e 0d 0a 20 20 20 20 20 20 20 20  cture...        
a0e0: 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20  /// </param>..  
a0f0: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d        /// <param
a100: 20 6e 61 6d 65 3d 22 69 64 78 4e 75 6d 22 3e 0d   name="idxNum">.
a110: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 4e 75 6d  .        /// Num
a120: 62 65 72 20 75 73 65 64 20 74 6f 20 68 65 6c 70  ber used to help
a130: 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 73 65   identify the se
a140: 6c 65 63 74 65 64 20 69 6e 64 65 78 2e 0d 0a 20  lected index... 
a150: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
a160: 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  am>..        ///
a170: 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 69 64   <param name="id
a180: 78 53 74 72 22 3e 0d 0a 20 20 20 20 20 20 20 20  xStr">..        
a190: 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76 65 20 70  /// The native p
a1a0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 55 54  ointer to the UT
a1b0: 46 2d 38 20 65 6e 63 6f 64 65 64 20 73 74 72 69  F-8 encoded stri
a1c0: 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ng containing th
a1d0: 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73  e..        /// s
a1e0: 74 72 69 6e 67 20 75 73 65 64 20 74 6f 20 68 65  tring used to he
a1f0: 6c 70 20 69 64 65 6e 74 69 66 79 20 74 68 65 20  lp identify the 
a200: 73 65 6c 65 63 74 65 64 20 69 6e 64 65 78 2e 0d  selected index..
a210: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
a220: 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f  aram>..        /
a230: 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22  // <param name="
a240: 61 72 67 63 22 3e 0d 0a 20 20 20 20 20 20 20 20  argc">..        
a250: 2f 2f 2f 20 54 68 65 20 6e 75 6d 62 65 72 20 6f  /// The number o
a260: 66 20 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72  f native pointer
a270: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 76 61 6c  s to sqlite3_val
a280: 75 65 20 73 74 72 75 63 74 75 72 65 73 20 73 70  ue structures sp
a290: 65 63 69 66 69 65 64 0d 0a 20 20 20 20 20 20 20  ecified..       
a2a0: 20 2f 2f 2f 20 69 6e 20 3c 70 61 72 61 6d 72 65   /// in <paramre
a2b0: 66 20 6e 61 6d 65 3d 22 61 72 67 76 22 20 2f 3e  f name="argv" />
a2c0: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
a2d0: 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20  /param>..       
a2e0: 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65   /// <param name
a2f0: 3d 22 61 72 67 76 22 3e 0d 0a 20 20 20 20 20 20  ="argv">..      
a300: 20 20 2f 2f 2f 20 41 6e 20 61 72 72 61 79 20 6f    /// An array o
a310: 66 20 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72  f native pointer
a320: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 76 61 6c  s to sqlite3_val
a330: 75 65 20 73 74 72 75 63 74 75 72 65 73 20 63 6f  ue structures co
a340: 6e 74 61 69 6e 69 6e 67 0d 0a 20 20 20 20 20 20  ntaining..      
a350: 20 20 2f 2f 2f 20 66 69 6c 74 65 72 69 6e 67 20    /// filtering 
a360: 63 72 69 74 65 72 69 61 20 66 6f 72 20 74 68 65  criteria for the
a370: 20 73 65 6c 65 63 74 65 64 20 69 6e 64 65 78 2e   selected index.
a380: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
a390: 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20  param>..        
a3a0: 2f 2f 2f 20 3c 72 65 74 75 72 6e 73 3e 0d 0a 20  /// <returns>.. 
a3b0: 20 20 20 20 20 20 20 2f 2f 2f 20 41 20 73 74 61         /// A sta
a3c0: 6e 64 61 72 64 20 53 51 4c 69 74 65 20 72 65 74  ndard SQLite ret
a3d0: 75 72 6e 20 63 6f 64 65 2e 0d 0a 20 20 20 20 20  urn code...     
a3e0: 20 20 20 2f 2f 2f 20 3c 2f 72 65 74 75 72 6e 73     /// </returns
a3f0: 3e 0d 0a 20 20 20 20 20 20 20 20 53 51 4c 69 74  >..        SQLit
a400: 65 45 72 72 6f 72 43 6f 64 65 20 78 46 69 6c 74  eErrorCode xFilt
a410: 65 72 28 0d 0a 20 20 20 20 20 20 20 20 20 20 20  er(..           
a420: 20 49 6e 74 50 74 72 20 70 43 75 72 73 6f 72 2c   IntPtr pCursor,
a430: 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 69 6e  ..            in
a440: 74 20 69 64 78 4e 75 6d 2c 0d 0a 20 20 20 20 20  t idxNum,..     
a450: 20 20 20 20 20 20 20 49 6e 74 50 74 72 20 69 64         IntPtr id
a460: 78 53 74 72 2c 0d 0a 20 20 20 20 20 20 20 20 20  xStr,..         
a470: 20 20 20 69 6e 74 20 61 72 67 63 2c 0d 0a 20 20     int argc,..  
a480: 20 20 20 20 20 20 20 20 20 20 49 6e 74 50 74 72            IntPtr
a490: 20 61 72 67 76 0d 0a 20 20 20 20 20 20 20 20 20   argv..         
a4a0: 20 20 20 29 3b 0d 0a 0d 0a 20 20 20 20 20 20 20     );....       
a4b0: 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f   ///////////////
a4c0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
a4d0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
a4e0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
a4f0: 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20  ////////....    
a500: 20 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79      /// <summary
a510: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
a520: 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20  para><code>..   
a530: 20 20 20 20 20 2f 2f 2f 20 20 20 69 6e 74 20 28       ///   int (
a540: 2a 78 4e 65 78 74 29 28 73 71 6c 69 74 65 33 5f  *xNext)(sqlite3_
a550: 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0d 0a  vtab_cursor*);..
a560: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f          /// </co
a570: 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  de></para>..    
a580: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a      /// <para>..
a590: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20          /// The 
a5a0: 78 4e 65 78 74 20 6d 65 74 68 6f 64 20 61 64 76  xNext method adv
a5b0: 61 6e 63 65 73 20 61 20 76 69 72 74 75 61 6c 20  ances a virtual 
a5c0: 74 61 62 6c 65 20 63 75 72 73 6f 72 0d 0a 20 20  table cursor..  
a5d0: 20 20 20 20 20 20 2f 2f 2f 20 74 6f 20 74 68 65        /// to the
a5e0: 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 61 20 72   next row of a r
a5f0: 65 73 75 6c 74 20 73 65 74 20 69 6e 69 74 69 61  esult set initia
a600: 74 65 64 20 62 79 20 78 46 69 6c 74 65 72 2e 20  ted by xFilter. 
a610: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 49 66  ..        /// If
a620: 20 74 68 65 20 63 75 72 73 6f 72 20 69 73 20 61   the cursor is a
a630: 6c 72 65 61 64 79 20 70 6f 69 6e 74 69 6e 67 20  lready pointing 
a640: 61 74 20 74 68 65 20 6c 61 73 74 20 72 6f 77 20  at the last row 
a650: 77 68 65 6e 20 74 68 69 73 20 0d 0a 20 20 20 20  when this ..    
a660: 20 20 20 20 2f 2f 2f 20 72 6f 75 74 69 6e 65 20      /// routine 
a670: 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20  is called, then 
a680: 74 68 65 20 63 75 72 73 6f 72 20 6e 6f 20 6c 6f  the cursor no lo
a690: 6e 67 65 72 20 70 6f 69 6e 74 73 20 74 6f 20 76  nger points to v
a6a0: 61 6c 69 64 20 0d 0a 20 20 20 20 20 20 20 20 2f  alid ..        /
a6b0: 2f 2f 20 64 61 74 61 20 61 6e 64 20 61 20 73 75  // data and a su
a6c0: 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
a6d0: 20 74 68 65 20 78 45 6f 66 20 6d 65 74 68 6f 64   the xEof method
a6e0: 20 6d 75 73 74 20 72 65 74 75 72 6e 20 74 72 75   must return tru
a6f0: 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 2e 20 0d 0a  e (non-zero). ..
a700: 20 20 20 20 20 20 20 20 2f 2f 2f 20 49 66 20 74          /// If t
a710: 68 65 20 63 75 72 73 6f 72 20 69 73 20 73 75 63  he cursor is suc
a720: 63 65 73 73 66 75 6c 6c 79 20 61 64 76 61 6e 63  cessfully advanc
a730: 65 64 20 74 6f 20 61 6e 6f 74 68 65 72 20 72 6f  ed to another ro
a740: 77 20 6f 66 20 63 6f 6e 74 65 6e 74 2c 20 74 68  w of content, th
a750: 65 6e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  en..        /// 
a760: 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
a770: 20 74 6f 20 78 45 6f 66 20 6d 75 73 74 20 72 65   to xEof must re
a780: 74 75 72 6e 20 66 61 6c 73 65 20 28 7a 65 72 6f  turn false (zero
a790: 29 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  )...        /// 
a7a0: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
a7b0: 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20   /// <para>..   
a7c0: 20 20 20 20 20 2f 2f 2f 20 54 68 69 73 20 6d 65       /// This me
a7d0: 74 68 6f 64 20 6d 75 73 74 20 72 65 74 75 72 6e  thod must return
a7e0: 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 73 75   SQLITE_OK if su
a7f0: 63 63 65 73 73 66 75 6c 2c 20 6f 72 20 61 6e 20  ccessful, or an 
a800: 73 71 6c 69 74 65 20 0d 0a 20 20 20 20 20 20 20  sqlite ..       
a810: 20 2f 2f 2f 20 65 72 72 6f 72 20 63 6f 64 65 20   /// error code 
a820: 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  if an error occu
a830: 72 73 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  rs...        ///
a840: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
a850: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20    /// <para>..  
a860: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 4e        /// The xN
a870: 65 78 74 20 6d 65 74 68 6f 64 20 69 73 20 72 65  ext method is re
a880: 71 75 69 72 65 64 20 66 6f 72 20 65 76 65 72 79  quired for every
a890: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
a8a0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0d 0a  mplementation...
a8b0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
a8c0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
a8d0: 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20   </summary>..   
a8e0: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20       /// <param 
a8f0: 6e 61 6d 65 3d 22 70 43 75 72 73 6f 72 22 3e 0d  name="pCursor">.
a900: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65  .        /// The
a910: 20 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72 20   native pointer 
a920: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  to the sqlite3_v
a930: 74 61 62 5f 63 75 72 73 6f 72 20 64 65 72 69 76  tab_cursor deriv
a940: 65 64 20 73 74 72 75 63 74 75 72 65 2e 0d 0a 20  ed structure... 
a950: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
a960: 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  am>..        ///
a970: 20 3c 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20   <returns>..    
a980: 20 20 20 20 2f 2f 2f 20 41 20 73 74 61 6e 64 61      /// A standa
a990: 72 64 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  rd SQLite return
a9a0: 20 63 6f 64 65 2e 0d 0a 20 20 20 20 20 20 20 20   code...        
a9b0: 2f 2f 2f 20 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a  /// </returns>..
a9c0: 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 45 72          SQLiteEr
a9d0: 72 6f 72 43 6f 64 65 20 78 4e 65 78 74 28 0d 0a  rorCode xNext(..
a9e0: 20 20 20 20 20 20 20 20 20 20 20 20 49 6e 74 50              IntP
a9f0: 74 72 20 70 43 75 72 73 6f 72 0d 0a 20 20 20 20  tr pCursor..    
aa00: 20 20 20 20 20 20 20 20 29 3b 0d 0a 0d 0a 20 20          );....  
aa10: 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f        //////////
aa20: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
aa30: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
aa40: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
aa50: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d  /////////////...
aa60: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 73 75  .        /// <su
aa70: 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20  mmary>..        
aa80: 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e  /// <para><code>
aa90: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20  ..        ///   
aaa0: 69 6e 74 20 28 2a 78 45 6f 66 29 28 73 71 6c 69  int (*xEof)(sqli
aab0: 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
aac0: 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  );..        /// 
aad0: 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a  </code></para>..
aae0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
aaf0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
ab00: 54 68 65 20 78 45 6f 66 20 6d 65 74 68 6f 64 20  The xEof method 
ab10: 6d 75 73 74 20 72 65 74 75 72 6e 20 66 61 6c 73  must return fals
ab20: 65 20 28 7a 65 72 6f 29 20 69 66 20 74 68 65 20  e (zero) if the 
ab30: 73 70 65 63 69 66 69 65 64 20 63 75 72 73 6f 72  specified cursor
ab40: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 63   ..        /// c
ab50: 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 73 20  urrently points 
ab60: 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 20 6f  to a valid row o
ab70: 66 20 64 61 74 61 2c 20 6f 72 20 74 72 75 65 20  f data, or true 
ab80: 28 6e 6f 6e 2d 7a 65 72 6f 29 20 6f 74 68 65 72  (non-zero) other
ab90: 77 69 73 65 2e 20 0d 0a 20 20 20 20 20 20 20 20  wise. ..        
aba0: 2f 2f 2f 20 54 68 69 73 20 6d 65 74 68 6f 64 20  /// This method 
abb0: 69 73 20 63 61 6c 6c 65 64 20 62 79 20 74 68 65  is called by the
abc0: 20 53 51 4c 20 65 6e 67 69 6e 65 20 69 6d 6d 65   SQL engine imme
abd0: 64 69 61 74 65 6c 79 20 61 66 74 65 72 20 65 61  diately after ea
abe0: 63 68 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ch ..        ///
abf0: 20 78 46 69 6c 74 65 72 20 61 6e 64 20 78 4e 65   xFilter and xNe
ac00: 78 74 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0d 0a  xt invocation...
ac10: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
ac20: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
ac30: 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20   <para>..       
ac40: 20 2f 2f 2f 20 54 68 65 20 78 45 6f 66 20 6d 65   /// The xEof me
ac50: 74 68 6f 64 20 69 73 20 72 65 71 75 69 72 65 64  thod is required
ac60: 20 66 6f 72 20 65 76 65 72 79 20 76 69 72 74 75   for every virtu
ac70: 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  al table impleme
ac80: 6e 74 61 74 69 6f 6e 2e 0d 0a 20 20 20 20 20 20  ntation...      
ac90: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
aca0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d         /// </sum
acb0: 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f  mary>..        /
acc0: 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22  // <param name="
acd0: 70 43 75 72 73 6f 72 22 3e 0d 0a 20 20 20 20 20  pCursor">..     
ace0: 20 20 20 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76     /// The nativ
acf0: 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
ad00: 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
ad10: 72 73 6f 72 20 64 65 72 69 76 65 64 20 73 74 72  rsor derived str
ad20: 75 63 74 75 72 65 2e 0d 0a 20 20 20 20 20 20 20  ucture...       
ad30: 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20   /// </param>.. 
ad40: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 72 65 74 75         /// <retu
ad50: 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  rns>..        //
ad60: 2f 20 4e 6f 6e 2d 7a 65 72 6f 20 69 66 20 6e 6f  / Non-zero if no
ad70: 20 6d 6f 72 65 20 72 6f 77 73 20 61 72 65 20 61   more rows are a
ad80: 76 61 69 6c 61 62 6c 65 3b 20 7a 65 72 6f 20 6f  vailable; zero o
ad90: 74 68 65 72 77 69 73 65 2e 0d 0a 20 20 20 20 20  therwise...     
ada0: 20 20 20 2f 2f 2f 20 3c 2f 72 65 74 75 72 6e 73     /// </returns
adb0: 3e 0d 0a 20 20 20 20 20 20 20 20 69 6e 74 20 78  >..        int x
adc0: 45 6f 66 28 0d 0a 20 20 20 20 20 20 20 20 20 20  Eof(..          
add0: 20 20 49 6e 74 50 74 72 20 70 43 75 72 73 6f 72    IntPtr pCursor
ade0: 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 29 3b  ..            );
adf0: 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 2f  ....        ////
ae00: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
ae10: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
ae20: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
ae30: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
ae40: 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f  ///....        /
ae50: 2f 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20 20  // <summary>..  
ae60: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
ae70: 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20 20  <code>..        
ae80: 2f 2f 2f 20 20 20 69 6e 74 20 28 2a 78 43 6f 6c  ///   int (*xCol
ae90: 75 6d 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61  umn)(sqlite3_vta
aea0: 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74  b_cursor*, sqlit
aeb0: 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
aec0: 20 4e 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f   N);..        //
aed0: 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e  / </code></para>
aee0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
aef0: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
af00: 2f 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  / The SQLite cor
af10: 65 20 69 6e 76 6f 6b 65 73 20 74 68 69 73 20 6d  e invokes this m
af20: 65 74 68 6f 64 20 69 6e 20 6f 72 64 65 72 20 74  ethod in order t
af30: 6f 20 66 69 6e 64 20 74 68 65 20 76 61 6c 75 65  o find the value
af40: 20 66 6f 72 20 0d 0a 20 20 20 20 20 20 20 20 2f   for ..        /
af50: 2f 2f 20 74 68 65 20 4e 2d 74 68 20 63 6f 6c 75  // the N-th colu
af60: 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  mn of the curren
af70: 74 20 72 6f 77 2e 20 4e 20 69 73 20 7a 65 72 6f  t row. N is zero
af80: 2d 62 61 73 65 64 20 73 6f 20 74 68 65 20 66 69  -based so the fi
af90: 72 73 74 20 63 6f 6c 75 6d 6e 20 0d 0a 20 20 20  rst column ..   
afa0: 20 20 20 20 20 2f 2f 2f 20 69 73 20 6e 75 6d 62       /// is numb
afb0: 65 72 65 64 20 30 2e 20 0d 0a 20 20 20 20 20 20  ered 0. ..      
afc0: 20 20 2f 2f 2f 20 54 68 65 20 78 43 6f 6c 75 6d    /// The xColum
afd0: 6e 20 6d 65 74 68 6f 64 20 6d 61 79 20 72 65 74  n method may ret
afe0: 75 72 6e 20 69 74 73 20 72 65 73 75 6c 74 20 62  urn its result b
aff0: 61 63 6b 20 74 6f 20 53 51 4c 69 74 65 20 75 73  ack to SQLite us
b000: 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 0d 0a  ing one of the..
b010: 20 20 20 20 20 20 20 20 2f 2f 2f 20 66 6f 6c 6c          /// foll
b020: 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65 3a  owing interface:
b030: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
b040: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
b050: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20  // <para>..     
b060: 20 20 20 2f 2f 2f 20 3c 21 5b 43 44 41 54 41 5b     /// <![CDATA[
b070: 3c 75 6c 3e 5d 5d 3e 0d 0a 20 20 20 20 20 20 20  <ul>]]>..       
b080: 20 2f 2f 2f 20 3c 21 5b 43 44 41 54 41 5b 3c 6c   /// <![CDATA[<l
b090: 69 3e 5d 5d 3e 20 73 71 6c 69 74 65 33 5f 72 65  i>]]> sqlite3_re
b0a0: 73 75 6c 74 5f 62 6c 6f 62 28 29 0d 0a 20 20 20  sult_blob()..   
b0b0: 20 20 20 20 20 2f 2f 2f 20 3c 21 5b 43 44 41 54       /// <![CDAT
b0c0: 41 5b 3c 6c 69 3e 5d 5d 3e 20 73 71 6c 69 74 65  A[<li>]]> sqlite
b0d0: 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
b0e0: 29 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  )..        /// <
b0f0: 21 5b 43 44 41 54 41 5b 3c 6c 69 3e 5d 5d 3e 20  ![CDATA[<li>]]> 
b100: 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
b110: 6e 74 28 29 0d 0a 20 20 20 20 20 20 20 20 2f 2f  nt()..        //
b120: 2f 20 3c 21 5b 43 44 41 54 41 5b 3c 6c 69 3e 5d  / <![CDATA[<li>]
b130: 5d 3e 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ]> sqlite3_resul
b140: 74 5f 69 6e 74 36 34 28 29 0d 0a 20 20 20 20 20  t_int64()..     
b150: 20 20 20 2f 2f 2f 20 3c 21 5b 43 44 41 54 41 5b     /// <![CDATA[
b160: 3c 6c 69 3e 5d 5d 3e 20 73 71 6c 69 74 65 33 5f  <li>]]> sqlite3_
b170: 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 0d 0a 20  result_null().. 
b180: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 21 5b 43 44         /// <![CD
b190: 41 54 41 5b 3c 6c 69 3e 5d 5d 3e 20 73 71 6c 69  ATA[<li>]]> sqli
b1a0: 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
b1b0: 29 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  )..        /// <
b1c0: 21 5b 43 44 41 54 41 5b 3c 6c 69 3e 5d 5d 3e 20  ![CDATA[<li>]]> 
b1d0: 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
b1e0: 65 78 74 31 36 28 29 0d 0a 20 20 20 20 20 20 20  ext16()..       
b1f0: 20 2f 2f 2f 20 3c 21 5b 43 44 41 54 41 5b 3c 6c   /// <![CDATA[<l
b200: 69 3e 5d 5d 3e 20 73 71 6c 69 74 65 33 5f 72 65  i>]]> sqlite3_re
b210: 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 0d  sult_text16le().
b220: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 21 5b  .        /// <![
b230: 43 44 41 54 41 5b 3c 6c 69 3e 5d 5d 3e 20 73 71  CDATA[<li>]]> sq
b240: 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
b250: 74 31 36 62 65 28 29 0d 0a 20 20 20 20 20 20 20  t16be()..       
b260: 20 2f 2f 2f 20 3c 21 5b 43 44 41 54 41 5b 3c 6c   /// <![CDATA[<l
b270: 69 3e 5d 5d 3e 20 73 71 6c 69 74 65 33 5f 72 65  i>]]> sqlite3_re
b280: 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 0d  sult_zeroblob().
b290: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 21 5b  .        /// <![
b2a0: 43 44 41 54 41 5b 3c 2f 75 6c 3e 5d 5d 3e 0d 0a  CDATA[</ul>]]>..
b2b0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
b2c0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
b2d0: 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20   <para>..       
b2e0: 20 2f 2f 2f 20 49 66 20 74 68 65 20 78 43 6f 6c   /// If the xCol
b2f0: 75 6d 6e 20 6d 65 74 68 6f 64 20 69 6d 70 6c 65  umn method imple
b300: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6c 6c 73 20  mentation calls 
b310: 6e 6f 6e 65 20 6f 66 20 74 68 65 20 66 75 6e 63  none of the func
b320: 74 69 6f 6e 73 20 61 62 6f 76 65 2c 0d 0a 20 20  tions above,..  
b330: 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 6e 20 74        /// then t
b340: 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
b350: 63 6f 6c 75 6d 6e 20 64 65 66 61 75 6c 74 73 20  column defaults 
b360: 74 6f 20 61 6e 20 53 51 4c 20 4e 55 4c 4c 2e 0d  to an SQL NULL..
b370: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
b380: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
b390: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20  / <para>..      
b3a0: 20 20 2f 2f 2f 20 54 6f 20 72 61 69 73 65 20 61    /// To raise a
b3b0: 6e 20 65 72 72 6f 72 2c 20 74 68 65 20 78 43 6f  n error, the xCo
b3c0: 6c 75 6d 6e 20 6d 65 74 68 6f 64 20 73 68 6f 75  lumn method shou
b3d0: 6c 64 20 75 73 65 20 6f 6e 65 20 6f 66 20 74 68  ld use one of th
b3e0: 65 20 72 65 73 75 6c 74 5f 74 65 78 74 28 29 20  e result_text() 
b3f0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6d 65  ..        /// me
b400: 74 68 6f 64 73 20 74 6f 20 73 65 74 20 74 68 65  thods to set the
b410: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
b420: 65 78 74 2c 20 74 68 65 6e 20 72 65 74 75 72 6e  ext, then return
b430: 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0d   an appropriate.
b440: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 65 72 72  .        /// err
b450: 6f 72 20 63 6f 64 65 2e 20 20 54 68 65 20 78 43  or code.  The xC
b460: 6f 6c 75 6d 6e 20 6d 65 74 68 6f 64 20 6d 75 73  olumn method mus
b470: 74 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  t return SQLITE_
b480: 4f 4b 20 6f 6e 20 73 75 63 63 65 73 73 2e 0d 0a  OK on success...
b490: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
b4a0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
b4b0: 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20   <para>..       
b4c0: 20 2f 2f 2f 20 54 68 65 20 78 43 6f 6c 75 6d 6e   /// The xColumn
b4d0: 20 6d 65 74 68 6f 64 20 69 73 20 72 65 71 75 69   method is requi
b4e0: 72 65 64 20 66 6f 72 20 65 76 65 72 79 20 76 69  red for every vi
b4f0: 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c  rtual table impl
b500: 65 6d 65 6e 74 61 74 69 6f 6e 2e 0d 0a 20 20 20  ementation...   
b510: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e       /// </para>
b520: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
b530: 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20  summary>..      
b540: 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d    /// <param nam
b550: 65 3d 22 70 43 75 72 73 6f 72 22 3e 0d 0a 20 20  e="pCursor">..  
b560: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e 61        /// The na
b570: 74 69 76 65 20 70 6f 69 6e 74 65 72 20 74 6f 20  tive pointer to 
b580: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 74 61 62  the sqlite3_vtab
b590: 5f 63 75 72 73 6f 72 20 64 65 72 69 76 65 64 20  _cursor derived 
b5a0: 73 74 72 75 63 74 75 72 65 2e 0d 0a 20 20 20 20  structure...    
b5b0: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e      /// </param>
b5c0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
b5d0: 61 72 61 6d 20 6e 61 6d 65 3d 22 70 43 6f 6e 74  aram name="pCont
b5e0: 65 78 74 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f  ext">..        /
b5f0: 2f 2f 20 54 68 65 20 6e 61 74 69 76 65 20 70 6f  // The native po
b600: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  inter to the sql
b610: 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 74 72  ite3_context str
b620: 75 63 74 75 72 65 20 74 6f 20 62 65 20 75 73 65  ucture to be use
b630: 64 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 66  d..        /// f
b640: 6f 72 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65  or returning the
b650: 20 73 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d   specified colum
b660: 6e 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 53  n value to the S
b670: 51 4c 69 74 65 20 63 6f 72 65 0d 0a 20 20 20 20  QLite core..    
b680: 20 20 20 20 2f 2f 2f 20 6c 69 62 72 61 72 79 2e      /// library.
b690: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
b6a0: 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20  param>..        
b6b0: 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d  /// <param name=
b6c0: 22 69 6e 64 65 78 22 3e 0d 0a 20 20 20 20 20 20  "index">..      
b6d0: 20 20 2f 2f 2f 20 54 68 65 20 7a 65 72 6f 2d 62    /// The zero-b
b6e0: 61 73 65 64 20 69 6e 64 65 78 20 63 6f 72 72 65  ased index corre
b6f0: 73 70 6f 6e 64 69 6e 67 20 74 6f 20 74 68 65 20  sponding to the 
b700: 63 6f 6c 75 6d 6e 20 63 6f 6e 74 61 69 6e 69 6e  column containin
b710: 67 20 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f  g the..        /
b720: 2f 2f 20 76 61 6c 75 65 20 74 6f 20 62 65 20 72  // value to be r
b730: 65 74 75 72 6e 65 64 2e 0d 0a 20 20 20 20 20 20  eturned...      
b740: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a    /// </param>..
b750: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 72 65 74          /// <ret
b760: 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 2f  urns>..        /
b770: 2f 2f 20 41 20 73 74 61 6e 64 61 72 64 20 53 51  // A standard SQ
b780: 4c 69 74 65 20 72 65 74 75 72 6e 20 63 6f 64 65  Lite return code
b790: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
b7a0: 2f 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20  /returns>..     
b7b0: 20 20 20 53 51 4c 69 74 65 45 72 72 6f 72 43 6f     SQLiteErrorCo
b7c0: 64 65 20 78 43 6f 6c 75 6d 6e 28 0d 0a 20 20 20  de xColumn(..   
b7d0: 20 20 20 20 20 20 20 20 20 49 6e 74 50 74 72 20           IntPtr 
b7e0: 70 43 75 72 73 6f 72 2c 0d 0a 20 20 20 20 20 20  pCursor,..      
b7f0: 20 20 20 20 20 20 49 6e 74 50 74 72 20 70 43 6f        IntPtr pCo
b800: 6e 74 65 78 74 2c 0d 0a 20 20 20 20 20 20 20 20  ntext,..        
b810: 20 20 20 20 69 6e 74 20 69 6e 64 65 78 0d 0a 20      int index.. 
b820: 20 20 20 20 20 20 20 20 20 20 20 29 3b 0d 0a 0d             );...
b830: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f  .        ///////
b840: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
b850: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
b860: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
b870: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
b880: 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ....        /// 
b890: 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20  <summary>..     
b8a0: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f     /// <para><co
b8b0: 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  de>..        ///
b8c0: 20 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 64 29     int (*xRowid)
b8d0: 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
b8e0: 72 73 6f 72 20 2a 70 43 75 72 2c 20 73 71 6c 69  rsor *pCur, sqli
b8f0: 74 65 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69 64  te_int64 *pRowid
b900: 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  );..        /// 
b910: 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a  </code></para>..
b920: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
b930: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
b940: 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76  A successful inv
b950: 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 69 73 20  ocation of this 
b960: 6d 65 74 68 6f 64 20 77 69 6c 6c 20 63 61 75 73  method will caus
b970: 65 20 2a 70 52 6f 77 69 64 20 74 6f 20 62 65 0d  e *pRowid to be.
b980: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 66 69 6c  .        /// fil
b990: 6c 65 64 20 77 69 74 68 20 74 68 65 20 72 6f 77  led with the row
b9a0: 69 64 20 6f 66 20 72 6f 77 20 74 68 61 74 20 74  id of row that t
b9b0: 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  he..        /// 
b9c0: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 63 75  virtual table cu
b9d0: 72 73 6f 72 20 70 43 75 72 20 69 73 20 63 75 72  rsor pCur is cur
b9e0: 72 65 6e 74 6c 79 20 70 6f 69 6e 74 69 6e 67 20  rently pointing 
b9f0: 61 74 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  at...        ///
ba00: 20 54 68 69 73 20 6d 65 74 68 6f 64 20 72 65 74   This method ret
ba10: 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 20 6f  urns SQLITE_OK o
ba20: 6e 20 73 75 63 63 65 73 73 2e 0d 0a 20 20 20 20  n success...    
ba30: 20 20 20 20 2f 2f 2f 20 49 74 20 72 65 74 75 72      /// It retur
ba40: 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  ns an appropriat
ba50: 65 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 6e 20  e error code on 
ba60: 66 61 69 6c 75 72 65 2e 0d 0a 20 20 20 20 20 20  failure...      
ba70: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
ba80: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
ba90: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54  >..        /// T
baa0: 68 65 20 78 52 6f 77 69 64 20 6d 65 74 68 6f 64  he xRowid method
bab0: 20 69 73 20 72 65 71 75 69 72 65 64 20 66 6f 72   is required for
bac0: 20 65 76 65 72 79 20 76 69 72 74 75 61 6c 20 74   every virtual t
bad0: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
bae0: 69 6f 6e 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ion...        //
baf0: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  / </para>..     
bb00: 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79     /// </summary
bb10: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
bb20: 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 43 75 72  param name="pCur
bb30: 73 6f 72 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f  sor">..        /
bb40: 2f 2f 20 54 68 65 20 6e 61 74 69 76 65 20 70 6f  // The native po
bb50: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  inter to the sql
bb60: 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
bb70: 20 64 65 72 69 76 65 64 20 73 74 72 75 63 74 75   derived structu
bb80: 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  re...        ///
bb90: 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20   </param>..     
bba0: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61     /// <param na
bbb0: 6d 65 3d 22 72 6f 77 49 64 22 3e 0d 0a 20 20 20  me="rowId">..   
bbc0: 20 20 20 20 20 2f 2f 2f 20 55 70 6f 6e 20 73 75       /// Upon su
bbd0: 63 63 65 73 73 2c 20 74 68 69 73 20 70 61 72 61  ccess, this para
bbe0: 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 6d 6f  meter must be mo
bbf0: 64 69 66 69 65 64 20 74 6f 20 63 6f 6e 74 61 69  dified to contai
bc00: 6e 20 74 68 65 20 75 6e 69 71 75 65 0d 0a 20 20  n the unique..  
bc10: 20 20 20 20 20 20 2f 2f 2f 20 69 6e 74 65 67 65        /// intege
bc20: 72 20 72 6f 77 20 69 64 65 6e 74 69 66 69 65 72  r row identifier
bc30: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
bc40: 20 72 6f 77 20 66 6f 72 20 74 68 65 20 73 70 65   row for the spe
bc50: 63 69 66 69 65 64 20 63 75 72 73 6f 72 2e 0d 0a  cified cursor...
bc60: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
bc70: 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ram>..        //
bc80: 2f 20 3c 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20  / <returns>..   
bc90: 20 20 20 20 20 2f 2f 2f 20 41 20 73 74 61 6e 64       /// A stand
bca0: 61 72 64 20 53 51 4c 69 74 65 20 72 65 74 75 72  ard SQLite retur
bcb0: 6e 20 63 6f 64 65 2e 0d 0a 20 20 20 20 20 20 20  n code...       
bcc0: 20 2f 2f 2f 20 3c 2f 72 65 74 75 72 6e 73 3e 0d   /// </returns>.
bcd0: 0a 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 45  .        SQLiteE
bce0: 72 72 6f 72 43 6f 64 65 20 78 52 6f 77 49 64 28  rrorCode xRowId(
bcf0: 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 49 6e  ..            In
bd00: 74 50 74 72 20 70 43 75 72 73 6f 72 2c 0d 0a 20  tPtr pCursor,.. 
bd10: 20 20 20 20 20 20 20 20 20 20 20 72 65 66 20 6c             ref l
bd20: 6f 6e 67 20 72 6f 77 49 64 0d 0a 20 20 20 20 20  ong rowId..     
bd30: 20 20 20 20 20 20 20 29 3b 0d 0a 0d 0a 20 20 20         );....   
bd40: 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f       ///////////
bd50: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
bd60: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
bd70: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
bd80: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a  ////////////....
bd90: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 73 75 6d          /// <sum
bda0: 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f  mary>..        /
bdb0: 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d  // <para><code>.
bdc0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 69  .        ///   i
bdd0: 6e 74 20 28 2a 78 55 70 64 61 74 65 29 28 0d 0a  nt (*xUpdate)(..
bde0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20          ///     
bdf0: 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
be00: 54 61 62 2c 0d 0a 20 20 20 20 20 20 20 20 2f 2f  Tab,..        //
be10: 2f 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 0d  /     int argc,.
be20: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20  .        ///    
be30: 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a   sqlite3_value *
be40: 2a 61 72 67 76 2c 0d 0a 20 20 20 20 20 20 20 20  *argv,..        
be50: 2f 2f 2f 20 20 20 20 20 73 71 6c 69 74 65 5f 69  ///     sqlite_i
be60: 6e 74 36 34 20 2a 70 52 6f 77 69 64 0d 0a 20 20  nt64 *pRowid..  
be70: 20 20 20 20 20 20 2f 2f 2f 20 20 20 29 3b 0d 0a        ///   );..
be80: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f          /// </co
be90: 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  de></para>..    
bea0: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a      /// <para>..
beb0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 6c 6c 20          /// All 
bec0: 63 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 72  changes to a vir
bed0: 74 75 61 6c 20 74 61 62 6c 65 20 61 72 65 20 6d  tual table are m
bee0: 61 64 65 20 75 73 69 6e 67 20 74 68 65 20 78 55  ade using the xU
bef0: 70 64 61 74 65 20 6d 65 74 68 6f 64 2e 0d 0a 20  pdate method... 
bf00: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 69 73 20         /// This 
bf10: 6f 6e 65 20 6d 65 74 68 6f 64 20 63 61 6e 20 62  one method can b
bf20: 65 20 75 73 65 64 20 74 6f 20 69 6e 73 65 72 74  e used to insert
bf30: 2c 20 64 65 6c 65 74 65 2c 20 6f 72 20 75 70 64  , delete, or upd
bf40: 61 74 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ate...        //
bf50: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  / </para>..     
bf60: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20     /// <para>.. 
bf70: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 61         /// The a
bf80: 72 67 63 20 70 61 72 61 6d 65 74 65 72 20 73 70  rgc parameter sp
bf90: 65 63 69 66 69 65 73 20 74 68 65 20 6e 75 6d 62  ecifies the numb
bfa0: 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20 69 6e  er of entries in
bfb0: 20 74 68 65 20 61 72 67 76 20 61 72 72 61 79 2e   the argv array.
bfc0: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54   ..        /// T
bfd0: 68 65 20 76 61 6c 75 65 20 6f 66 20 61 72 67 63  he value of argc
bfe0: 20 77 69 6c 6c 20 62 65 20 31 20 66 6f 72 20 61   will be 1 for a
bff0: 20 70 75 72 65 20 64 65 6c 65 74 65 20 6f 70 65   pure delete ope
c000: 72 61 74 69 6f 6e 20 6f 72 20 4e 2b 32 20 66 6f  ration or N+2 fo
c010: 72 20 61 6e 20 69 6e 73 65 72 74 0d 0a 20 20 20  r an insert..   
c020: 20 20 20 20 20 2f 2f 2f 20 6f 72 20 72 65 70 6c       /// or repl
c030: 61 63 65 20 6f 72 20 75 70 64 61 74 65 20 77 68  ace or update wh
c040: 65 72 65 20 4e 20 69 73 20 74 68 65 20 6e 75 6d  ere N is the num
c050: 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
c060: 6e 20 74 68 65 20 74 61 62 6c 65 2e 20 20 0d 0a  n the table.  ..
c070: 20 20 20 20 20 20 20 20 2f 2f 2f 20 49 6e 20 74          /// In t
c080: 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
c090: 65 6e 63 65 2c 20 4e 20 69 6e 63 6c 75 64 65 73  ence, N includes
c0a0: 20 61 6e 79 20 68 69 64 64 65 6e 20 63 6f 6c 75   any hidden colu
c0b0: 6d 6e 73 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  mns...        //
c0c0: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  / </para>..     
c0d0: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20     /// <para>.. 
c0e0: 20 20 20 20 20 20 20 2f 2f 2f 20 45 76 65 72 79         /// Every
c0f0: 20 61 72 67 76 20 65 6e 74 72 79 20 77 69 6c 6c   argv entry will
c100: 20 68 61 76 65 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   have a non-NULL
c110: 20 76 61 6c 75 65 20 69 6e 20 43 20 62 75 74 20   value in C but 
c120: 6d 61 79 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  may contain the 
c130: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 53 51  ..        /// SQ
c140: 4c 20 76 61 6c 75 65 20 4e 55 4c 4c 2e 20 20 49  L value NULL.  I
c150: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
c160: 74 20 69 73 20 61 6c 77 61 79 73 20 74 72 75 65  t is always true
c170: 20 74 68 61 74 0d 0a 20 20 20 20 20 20 20 20 2f   that..        /
c180: 2f 2f 20 3c 21 5b 43 44 41 54 41 5b 3c 74 74 3e  // <![CDATA[<tt>
c190: 5d 5d 3e 61 72 67 76 5b 69 5d 21 3d 30 3c 21 5b  ]]>argv[i]!=0<![
c1a0: 43 44 41 54 41 5b 3c 2f 74 74 3e 5d 5d 3e 20 66  CDATA[</tt>]]> f
c1b0: 6f 72 20 3c 21 5b 43 44 41 54 41 5b 3c 62 3e 5d  or <![CDATA[<b>]
c1c0: 5d 3e 69 3c 21 5b 43 44 41 54 41 5b 3c 2f 62 3e  ]>i<![CDATA[</b>
c1d0: 5d 5d 3e 20 62 65 74 77 65 65 6e 20 30 20 61 6e  ]]> between 0 an
c1e0: 64 20 3c 21 5b 43 44 41 54 41 5b 3c 74 74 3e 5d  d <![CDATA[<tt>]
c1f0: 5d 3e 61 72 67 63 2d 31 3c 21 5b 43 44 41 54 41  ]>argc-1<![CDATA
c200: 5b 3c 2f 74 74 3e 5d 5d 3e 2e 0d 0a 20 20 20 20  [</tt>]]>...    
c210: 20 20 20 20 2f 2f 2f 20 48 6f 77 65 76 65 72 2c      /// However,
c220: 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65   it might be the
c230: 20 63 61 73 65 20 74 68 61 74 0d 0a 20 20 20 20   case that..    
c240: 20 20 20 20 2f 2f 2f 20 3c 21 5b 43 44 41 54 41      /// <![CDATA
c250: 5b 3c 74 74 3e 5d 5d 3e 73 71 6c 69 74 65 33 5f  [<tt>]]>sqlite3_
c260: 76 61 6c 75 65 5f 74 79 70 65 28 61 72 67 76 5b  value_type(argv[
c270: 69 5d 29 3d 3d 53 51 4c 49 54 45 5f 4e 55 4c 4c  i])==SQLITE_NULL
c280: 3c 21 5b 43 44 41 54 41 5b 3c 2f 74 74 3e 5d 5d  <![CDATA[</tt>]]
c290: 3e 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  >...        /// 
c2a0: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
c2b0: 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20   /// <para>..   
c2c0: 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 61 72 67       /// The arg
c2d0: 76 5b 30 5d 20 70 61 72 61 6d 65 74 65 72 20 69  v[0] parameter i
c2e0: 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 61  s the rowid of a
c2f0: 20 72 6f 77 20 69 6e 20 74 68 65 20 76 69 72 74   row in the virt
c300: 75 61 6c 20 74 61 62 6c 65 20 0d 0a 20 20 20 20  ual table ..    
c310: 20 20 20 20 2f 2f 2f 20 74 6f 20 62 65 20 64 65      /// to be de
c320: 6c 65 74 65 64 2e 20 49 66 20 61 72 67 76 5b 30  leted. If argv[0
c330: 5d 20 69 73 20 61 6e 20 53 51 4c 20 4e 55 4c 4c  ] is an SQL NULL
c340: 2c 20 74 68 65 6e 20 6e 6f 20 64 65 6c 65 74 69  , then no deleti
c350: 6f 6e 20 6f 63 63 75 72 73 2e 0d 0a 20 20 20 20  on occurs...    
c360: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
c370: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
c380: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
c390: 20 54 68 65 20 61 72 67 76 5b 31 5d 20 70 61 72   The argv[1] par
c3a0: 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 72 6f  ameter is the ro
c3b0: 77 69 64 20 6f 66 20 61 20 6e 65 77 20 72 6f 77  wid of a new row
c3c0: 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
c3d0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e  ..        /// in
c3e0: 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  to the virtual t
c3f0: 61 62 6c 65 2e 20 49 66 20 61 72 67 76 5b 31 5d  able. If argv[1]
c400: 20 69 73 20 61 6e 20 53 51 4c 20 4e 55 4c 4c 2c   is an SQL NULL,
c410: 20 74 68 65 6e 20 74 68 65 20 69 6d 70 6c 65 6d   then the implem
c420: 65 6e 74 61 74 69 6f 6e 20 0d 0a 20 20 20 20 20  entation ..     
c430: 20 20 20 2f 2f 2f 20 6d 75 73 74 20 63 68 6f 6f     /// must choo
c440: 73 65 20 61 20 72 6f 77 69 64 20 66 6f 72 20 74  se a rowid for t
c450: 68 65 20 6e 65 77 6c 79 20 69 6e 73 65 72 74 65  he newly inserte
c460: 64 20 72 6f 77 2e 20 53 75 62 73 65 71 75 65 6e  d row. Subsequen
c470: 74 20 61 72 67 76 5b 5d 20 0d 0a 20 20 20 20 20  t argv[] ..     
c480: 20 20 20 2f 2f 2f 20 65 6e 74 72 69 65 73 20 63     /// entries c
c490: 6f 6e 74 61 69 6e 20 76 61 6c 75 65 73 20 6f 66  ontain values of
c4a0: 20 74 68 65 20 63 6f 6c 75 6d 6e 73 20 6f 66 20   the columns of 
c4b0: 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
c4c0: 65 2c 20 69 6e 20 74 68 65 20 0d 0a 20 20 20 20  e, in the ..    
c4d0: 20 20 20 20 2f 2f 2f 20 6f 72 64 65 72 20 74 68      /// order th
c4e0: 61 74 20 74 68 65 20 63 6f 6c 75 6d 6e 73 20 77  at the columns w
c4f0: 65 72 65 20 64 65 63 6c 61 72 65 64 2e 20 54 68  ere declared. Th
c500: 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
c510: 6d 6e 73 20 77 69 6c 6c 0d 0a 20 20 20 20 20 20  mns will..      
c520: 20 20 2f 2f 2f 20 6d 61 74 63 68 20 74 68 65 20    /// match the 
c530: 74 61 62 6c 65 20 64 65 63 6c 61 72 61 74 69 6f  table declaratio
c540: 6e 20 74 68 61 74 20 74 68 65 20 78 43 6f 6e 6e  n that the xConn
c550: 65 63 74 20 6f 72 20 78 43 72 65 61 74 65 20 6d  ect or xCreate m
c560: 65 74 68 6f 64 20 6d 61 64 65 20 0d 0a 20 20 20  ethod made ..   
c570: 20 20 20 20 20 2f 2f 2f 20 75 73 69 6e 67 20 74       /// using t
c580: 68 65 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61  he sqlite3_decla
c590: 72 65 5f 76 74 61 62 28 29 20 63 61 6c 6c 2e 20  re_vtab() call. 
c5a0: 20 41 6c 6c 20 68 69 64 64 65 6e 20 63 6f 6c 75   All hidden colu
c5b0: 6d 6e 73 20 61 72 65 20 69 6e 63 6c 75 64 65 64  mns are included
c5c0: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
c5d0: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
c5e0: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20  /// <para>..    
c5f0: 20 20 20 20 2f 2f 2f 20 57 68 65 6e 20 64 6f 69      /// When doi
c600: 6e 67 20 61 6e 20 69 6e 73 65 72 74 20 77 69 74  ng an insert wit
c610: 68 6f 75 74 20 61 20 72 6f 77 69 64 20 28 61 72  hout a rowid (ar
c620: 67 63 3e 31 2c 20 61 72 67 76 5b 31 5d 20 69 73  gc>1, argv[1] is
c630: 20 61 6e 20 53 51 4c 20 4e 55 4c 4c 29 2c 20 74   an SQL NULL), t
c640: 68 65 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  he ..        ///
c650: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
c660: 6d 75 73 74 20 73 65 74 20 2a 70 52 6f 77 69 64  must set *pRowid
c670: 20 74 6f 20 74 68 65 20 72 6f 77 69 64 20 6f 66   to the rowid of
c680: 20 74 68 65 20 6e 65 77 6c 79 20 69 6e 73 65 72   the newly inser
c690: 74 65 64 20 72 6f 77 3b 20 0d 0a 20 20 20 20 20  ted row; ..     
c6a0: 20 20 20 2f 2f 2f 20 74 68 69 73 20 77 69 6c 6c     /// this will
c6b0: 20 62 65 63 6f 6d 65 20 74 68 65 20 76 61 6c 75   become the valu
c6c0: 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
c6d0: 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  e sqlite3_last_i
c6e0: 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 0d 0a 20  nsert_rowid().. 
c6f0: 20 20 20 20 20 20 20 2f 2f 2f 20 66 75 6e 63 74         /// funct
c700: 69 6f 6e 2e 20 53 65 74 74 69 6e 67 20 74 68 69  ion. Setting thi
c710: 73 20 76 61 6c 75 65 20 69 6e 20 61 6c 6c 20 74  s value in all t
c720: 68 65 20 6f 74 68 65 72 20 63 61 73 65 73 20 69  he other cases i
c730: 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
c740: 6f 70 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  op;..        ///
c750: 20 74 68 65 20 53 51 4c 69 74 65 20 65 6e 67 69   the SQLite engi
c760: 6e 65 20 69 67 6e 6f 72 65 73 20 74 68 65 20 2a  ne ignores the *
c770: 70 52 6f 77 69 64 20 72 65 74 75 72 6e 20 76 61  pRowid return va
c780: 6c 75 65 20 69 66 20 61 72 67 63 3d 3d 31 20 6f  lue if argc==1 o
c790: 72 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  r ..        /// 
c7a0: 61 72 67 76 5b 31 5d 20 69 73 20 6e 6f 74 20 61  argv[1] is not a
c7b0: 6e 20 53 51 4c 20 4e 55 4c 4c 2e 0d 0a 20 20 20  n SQL NULL...   
c7c0: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e       /// </para>
c7d0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
c7e0: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ara>..        //
c7f0: 2f 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 78  / Each call to x
c800: 55 70 64 61 74 65 20 77 69 6c 6c 20 66 61 6c 6c  Update will fall
c810: 20 69 6e 74 6f 20 6f 6e 65 20 6f 66 20 63 61 73   into one of cas
c820: 65 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0d  es shown below..
c830: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 4e 6f 74  .        /// Not
c840: 20 74 68 61 74 20 72 65 66 65 72 65 6e 63 65 73   that references
c850: 20 74 6f 20 3c 21 5b 43 44 41 54 41 5b 3c 62 3e   to <![CDATA[<b>
c860: 5d 5d 3e 61 72 67 76 5b 69 5d 3c 21 5b 43 44 41  ]]>argv[i]<![CDA
c870: 54 41 5b 3c 2f 62 3e 5d 5d 3e 20 6d 65 61 6e 20  TA[</b>]]> mean 
c880: 74 68 65 20 53 51 4c 20 76 61 6c 75 65 0d 0a 20  the SQL value.. 
c890: 20 20 20 20 20 20 20 2f 2f 2f 20 68 65 6c 64 20         /// held 
c8a0: 77 69 74 68 69 6e 20 74 68 65 20 61 72 67 76 5b  within the argv[
c8b0: 69 5d 20 6f 62 6a 65 63 74 2c 20 6e 6f 74 20 74  i] object, not t
c8c0: 68 65 20 61 72 67 76 5b 69 5d 0d 0a 20 20 20 20  he argv[i]..    
c8d0: 20 20 20 20 2f 2f 2f 20 6f 62 6a 65 63 74 20 69      /// object i
c8e0: 74 73 65 6c 66 2e 0d 0a 20 20 20 20 20 20 20 20  tself...        
c8f0: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
c900: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c       /// <para><
c910: 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f  code>..        /
c920: 2f 2f 20 3c 21 5b 43 44 41 54 41 5b 3c 64 6c 3e  // <![CDATA[<dl>
c930: 5d 5d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ]]>..        ///
c940: 20 3c 21 5b 43 44 41 54 41 5b 3c 64 74 3e 5d 5d   <![CDATA[<dt>]]
c950: 3e 3c 21 5b 43 44 41 54 41 5b 3c 62 3e 5d 5d 3e  ><![CDATA[<b>]]>
c960: 61 72 67 63 20 3d 20 31 3c 21 5b 43 44 41 54 41  argc = 1<![CDATA
c970: 5b 3c 2f 62 3e 5d 5d 3e 0d 0a 20 20 20 20 20 20  [</b>]]>..      
c980: 20 20 2f 2f 2f 20 3c 21 5b 43 44 41 54 41 5b 3c    /// <![CDATA[<
c990: 64 64 3e 5d 5d 3e 54 68 65 20 73 69 6e 67 6c 65  dd>]]>The single
c9a0: 20 72 6f 77 20 77 69 74 68 20 72 6f 77 69 64 20   row with rowid 
c9b0: 65 71 75 61 6c 20 74 6f 20 61 72 67 76 5b 30 5d  equal to argv[0]
c9c0: 20 69 73 20 64 65 6c 65 74 65 64 2e 20 4e 6f 20   is deleted. No 
c9d0: 69 6e 73 65 72 74 20 6f 63 63 75 72 73 2e 0d 0a  insert occurs...
c9e0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 21 5b 43          /// <![C
c9f0: 44 41 54 41 5b 3c 64 74 3e 5d 5d 3e 3c 21 5b 43  DATA[<dt>]]><![C
ca00: 44 41 54 41 5b 3c 62 3e 5d 5d 3e 61 72 67 63 20  DATA[<b>]]>argc 
ca10: 26 67 74 3b 20 31 20 3c 21 5b 43 44 41 54 41 5b  &gt; 1 <![CDATA[
ca20: 3c 62 72 3e 5d 5d 3e 20 61 72 67 76 5b 30 5d 20  <br>]]> argv[0] 
ca30: 3d 20 4e 55 4c 4c 3c 21 5b 43 44 41 54 41 5b 3c  = NULL<![CDATA[<
ca40: 2f 62 3e 5d 5d 3e 0d 0a 20 20 20 20 20 20 20 20  /b>]]>..        
ca50: 2f 2f 2f 20 3c 21 5b 43 44 41 54 41 5b 3c 64 64  /// <![CDATA[<dd
ca60: 3e 5d 5d 3e 41 20 6e 65 77 20 72 6f 77 20 69 73  >]]>A new row is
ca70: 20 69 6e 73 65 72 74 65 64 20 77 69 74 68 20 61   inserted with a
ca80: 20 72 6f 77 69 64 20 61 72 67 76 5b 31 5d 20 61   rowid argv[1] a
ca90: 6e 64 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 73  nd column values
caa0: 20 69 6e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f   in..        ///
cab0: 20 20 20 20 20 20 20 20 61 72 67 76 5b 32 5d 20          argv[2] 
cac0: 61 6e 64 20 66 6f 6c 6c 6f 77 69 6e 67 2e 20 20  and following.  
cad0: 49 66 20 61 72 67 76 5b 31 5d 20 69 73 20 61 6e  If argv[1] is an
cae0: 20 53 51 4c 20 4e 55 4c 4c 2c 0d 0a 20 20 20 20   SQL NULL,..    
caf0: 20 20 20 20 2f 2f 2f 20 20 20 20 20 20 20 20 74      ///        t
cb00: 68 65 20 61 20 6e 65 77 20 75 6e 69 71 75 65 20  he a new unique 
cb10: 72 6f 77 69 64 20 69 73 20 67 65 6e 65 72 61 74  rowid is generat
cb20: 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
cb30: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
cb40: 21 5b 43 44 41 54 41 5b 3c 64 74 3e 5d 5d 3e 3c  ![CDATA[<dt>]]><
cb50: 21 5b 43 44 41 54 41 5b 3c 62 3e 5d 5d 3e 61 72  ![CDATA[<b>]]>ar
cb60: 67 63 20 26 67 74 3b 20 31 20 3c 21 5b 43 44 41  gc &gt; 1 <![CDA
cb70: 54 41 5b 3c 62 72 3e 5d 5d 3e 20 61 72 67 76 5b  TA[<br>]]> argv[
cb80: 30 5d 20 26 23 38 38 30 30 3b 20 4e 55 4c 4c 20  0] &#8800; NULL 
cb90: 3c 21 5b 43 44 41 54 41 5b 3c 62 72 3e 5d 5d 3e  <![CDATA[<br>]]>
cba0: 20 61 72 67 76 5b 30 5d 20 3d 20 61 72 67 76 5b   argv[0] = argv[
cbb0: 31 5d 3c 21 5b 43 44 41 54 41 5b 3c 2f 62 3e 5d  1]<![CDATA[</b>]
cbc0: 5d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ]>..        /// 
cbd0: 3c 21 5b 43 44 41 54 41 5b 3c 64 64 3e 5d 5d 3e  <![CDATA[<dd>]]>
cbe0: 54 68 65 20 72 6f 77 20 77 69 74 68 20 72 6f 77  The row with row
cbf0: 69 64 20 61 72 67 76 5b 30 5d 20 69 73 20 75 70  id argv[0] is up
cc00: 64 61 74 65 64 20 77 69 74 68 20 6e 65 77 20 76  dated with new v
cc10: 61 6c 75 65 73 20 0d 0a 20 20 20 20 20 20 20 20  alues ..        
cc20: 2f 2f 2f 20 20 20 20 20 20 20 20 69 6e 20 61 72  ///        in ar
cc30: 67 76 5b 32 5d 20 61 6e 64 20 66 6f 6c 6c 6f 77  gv[2] and follow
cc40: 69 6e 67 20 70 61 72 61 6d 65 74 65 72 73 2e 0d  ing parameters..
cc50: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 21 5b  .        /// <![
cc60: 43 44 41 54 41 5b 3c 64 74 3e 5d 5d 3e 3c 21 5b  CDATA[<dt>]]><![
cc70: 43 44 41 54 41 5b 3c 62 3e 5d 5d 3e 61 72 67 63  CDATA[<b>]]>argc
cc80: 20 26 67 74 3b 20 31 20 3c 21 5b 43 44 41 54 41   &gt; 1 <![CDATA
cc90: 5b 3c 62 72 3e 5d 5d 3e 20 61 72 67 76 5b 30 5d  [<br>]]> argv[0]
cca0: 20 26 23 38 38 30 30 3b 20 4e 55 4c 4c 20 3c 21   &#8800; NULL <!
ccb0: 5b 43 44 41 54 41 5b 3c 62 72 3e 5d 5d 3e 20 61  [CDATA[<br>]]> a
ccc0: 72 67 76 5b 30 5d 20 26 23 38 38 30 30 3b 20 61  rgv[0] &#8800; a
ccd0: 72 67 76 5b 31 5d 3c 21 5b 43 44 41 54 41 5b 3c  rgv[1]<![CDATA[<
cce0: 2f 62 3e 5d 5d 3e 0d 0a 20 20 20 20 20 20 20 20  /b>]]>..        
ccf0: 2f 2f 2f 20 3c 21 5b 43 44 41 54 41 5b 3c 64 64  /// <![CDATA[<dd
cd00: 3e 5d 5d 3e 20 54 68 65 20 72 6f 77 20 77 69 74  >]]> The row wit
cd10: 68 20 72 6f 77 69 64 20 61 72 67 76 5b 30 5d 20  h rowid argv[0] 
cd20: 69 73 20 75 70 64 61 74 65 64 20 77 69 74 68 20  is updated with 
cd30: 72 6f 77 69 64 20 61 72 67 76 5b 31 5d 20 0d 0a  rowid argv[1] ..
cd40: 20 20 20 20 20 20 20 20 2f 2f 2f 20 61 6e 64 20          /// and 
cd50: 6e 65 77 20 76 61 6c 75 65 73 20 69 6e 20 61 72  new values in ar
cd60: 67 76 5b 32 5d 20 61 6e 64 20 66 6f 6c 6c 6f 77  gv[2] and follow
cd70: 69 6e 67 20 70 61 72 61 6d 65 74 65 72 73 2e 20  ing parameters. 
cd80: 54 68 69 73 20 77 69 6c 6c 20 6f 63 63 75 72 20  This will occur 
cd90: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 77 68  ..        /// wh
cda0: 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  en an SQL statem
cdb0: 65 6e 74 20 75 70 64 61 74 65 73 20 61 20 72 6f  ent updates a ro
cdc0: 77 69 64 2c 20 61 73 20 69 6e 20 74 68 65 20 73  wid, as in the s
cdd0: 74 61 74 65 6d 65 6e 74 3a 0d 0a 20 20 20 20 20  tatement:..     
cde0: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f     /// <para><co
cdf0: 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  de>..        ///
ce00: 20 20 20 20 55 50 44 41 54 45 20 74 61 62 6c 65      UPDATE table
ce10: 20 53 45 54 20 72 6f 77 69 64 3d 72 6f 77 69 64   SET rowid=rowid
ce20: 2b 31 20 57 48 45 52 45 20 2e 2e 2e 3b 20 0d 0a  +1 WHERE ...; ..
ce30: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f          /// </co
ce40: 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  de></para>..    
ce50: 20 20 20 20 2f 2f 2f 20 3c 21 5b 43 44 41 54 41      /// <![CDATA
ce60: 5b 3c 2f 64 6c 3e 5d 5d 3e 0d 0a 20 20 20 20 20  [</dl>]]>..     
ce70: 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f     /// </code></
ce80: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
ce90: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20  // <para>..     
cea0: 20 20 20 2f 2f 2f 20 54 68 65 20 78 55 70 64 61     /// The xUpda
ceb0: 74 65 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 72  te method must r
cec0: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
ced0: 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 69  if and only if i
cee0: 74 20 69 73 0d 0a 20 20 20 20 20 20 20 20 2f 2f  t is..        //
cef0: 2f 20 73 75 63 63 65 73 73 66 75 6c 2e 20 20 49  / successful.  I
cf00: 66 20 61 20 66 61 69 6c 75 72 65 20 6f 63 63 75  f a failure occu
cf10: 72 73 2c 20 74 68 65 20 78 55 70 64 61 74 65 20  rs, the xUpdate 
cf20: 6d 75 73 74 20 72 65 74 75 72 6e 20 61 6e 20 61  must return an a
cf30: 70 70 72 6f 70 72 69 61 74 65 0d 0a 20 20 20 20  ppropriate..    
cf40: 20 20 20 20 2f 2f 2f 20 65 72 72 6f 72 20 63 6f      /// error co
cf50: 64 65 2e 20 20 4f 6e 20 61 20 66 61 69 6c 75 72  de.  On a failur
cf60: 65 2c 20 74 68 65 20 70 56 54 61 62 2d 3e 7a 45  e, the pVTab->zE
cf70: 72 72 4d 73 67 20 65 6c 65 6d 65 6e 74 20 6d 61  rrMsg element ma
cf80: 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 0d 0a 20 20  y optionally..  
cf90: 20 20 20 20 20 20 2f 2f 2f 20 62 65 20 72 65 70        /// be rep
cfa0: 6c 61 63 65 64 20 77 69 74 68 20 65 72 72 6f 72  laced with error
cfb0: 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 73 74   message text st
cfc0: 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 20 61  ored in memory a
cfd0: 6c 6c 6f 63 61 74 65 64 20 66 72 6f 6d 20 53 51  llocated from SQ
cfe0: 4c 69 74 65 20 0d 0a 20 20 20 20 20 20 20 20 2f  Lite ..        /
cff0: 2f 2f 20 75 73 69 6e 67 20 66 75 6e 63 74 69 6f  // using functio
d000: 6e 73 20 73 75 63 68 20 61 73 20 73 71 6c 69 74  ns such as sqlit
d010: 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 6f 72 20  e3_mprintf() or 
d020: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
d030: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
d040: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
d050: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20  /// <para>..    
d060: 20 20 20 20 2f 2f 2f 20 49 66 20 74 68 65 20 78      /// If the x
d070: 55 70 64 61 74 65 20 6d 65 74 68 6f 64 20 76 69  Update method vi
d080: 6f 6c 61 74 65 73 20 73 6f 6d 65 20 63 6f 6e 73  olates some cons
d090: 74 72 61 69 6e 74 20 6f 66 20 74 68 65 20 76 69  traint of the vi
d0a0: 72 74 75 61 6c 20 74 61 62 6c 65 0d 0a 20 20 20  rtual table..   
d0b0: 20 20 20 20 20 2f 2f 2f 20 28 69 6e 63 6c 75 64       /// (includ
d0c0: 69 6e 67 2c 20 62 75 74 20 6e 6f 74 20 6c 69 6d  ing, but not lim
d0d0: 69 74 65 64 20 74 6f 2c 20 61 74 74 65 6d 70 74  ited to, attempt
d0e0: 69 6e 67 20 74 6f 20 73 74 6f 72 65 20 61 20 76  ing to store a v
d0f0: 61 6c 75 65 20 6f 66 20 74 68 65 20 77 72 6f 6e  alue of the wron
d100: 67 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  g ..        /// 
d110: 64 61 74 61 74 79 70 65 2c 20 61 74 74 65 6d 70  datatype, attemp
d120: 74 69 6e 67 20 74 6f 20 73 74 6f 72 65 20 61 20  ting to store a 
d130: 76 61 6c 75 65 20 74 68 61 74 20 69 73 20 74 6f  value that is to
d140: 6f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6c  o..        /// l
d150: 61 72 67 65 20 6f 72 20 74 6f 6f 20 73 6d 61 6c  arge or too smal
d160: 6c 2c 20 6f 72 20 61 74 74 65 6d 70 74 69 6e 67  l, or attempting
d170: 20 74 6f 20 63 68 61 6e 67 65 20 61 20 72 65 61   to change a rea
d180: 64 2d 6f 6e 6c 79 20 76 61 6c 75 65 29 20 74 68  d-only value) th
d190: 65 6e 20 74 68 65 0d 0a 20 20 20 20 20 20 20 20  en the..        
d1a0: 2f 2f 2f 20 78 55 70 64 61 74 65 20 6d 75 73 74  /// xUpdate must
d1b0: 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 61 70   fail with an ap
d1c0: 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20  propriate error 
d1d0: 63 6f 64 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f  code...        /
d1e0: 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  // </para>..    
d1f0: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a      /// <para>..
d200: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 72          /// Ther
d210: 65 20 6d 69 67 68 74 20 62 65 20 6f 6e 65 20 6f  e might be one o
d220: 72 20 6d 6f 72 65 20 73 71 6c 69 74 65 33 5f 76  r more sqlite3_v
d230: 74 61 62 5f 63 75 72 73 6f 72 20 6f 62 6a 65 63  tab_cursor objec
d240: 74 73 20 6f 70 65 6e 20 61 6e 64 20 69 6e 20 75  ts open and in u
d250: 73 65 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  se ..        ///
d260: 20 6f 6e 20 74 68 65 20 76 69 72 74 75 61 6c 20   on the virtual 
d270: 74 61 62 6c 65 20 69 6e 73 74 61 6e 63 65 20 61  table instance a
d280: 6e 64 20 70 65 72 68 61 70 73 20 65 76 65 6e 20  nd perhaps even 
d290: 6f 6e 20 74 68 65 20 72 6f 77 20 6f 66 20 74 68  on the row of th
d2a0: 65 20 76 69 72 74 75 61 6c 0d 0a 20 20 20 20 20  e virtual..     
d2b0: 20 20 20 2f 2f 2f 20 74 61 62 6c 65 20 77 68 65     /// table whe
d2c0: 6e 20 74 68 65 20 78 55 70 64 61 74 65 20 6d 65  n the xUpdate me
d2d0: 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 2e  thod is invoked.
d2e0: 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61    The implementa
d2f0: 74 69 6f 6e 20 6f 66 0d 0a 20 20 20 20 20 20 20  tion of..       
d300: 20 2f 2f 2f 20 78 55 70 64 61 74 65 20 6d 75 73   /// xUpdate mus
d310: 74 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f  t be prepared fo
d320: 72 20 61 74 74 65 6d 70 74 73 20 74 6f 20 64 65  r attempts to de
d330: 6c 65 74 65 20 6f 72 20 6d 6f 64 69 66 79 20 72  lete or modify r
d340: 6f 77 73 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ows of the table
d350: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6f 75  ..        /// ou
d360: 74 20 66 72 6f 6d 20 6f 74 68 65 72 20 65 78 69  t from other exi
d370: 73 74 69 6e 67 20 63 75 72 73 6f 72 73 2e 20 20  sting cursors.  
d380: 49 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  If the virtual t
d390: 61 62 6c 65 20 63 61 6e 6e 6f 74 20 61 63 63 6f  able cannot acco
d3a0: 6d 6d 6f 64 61 74 65 0d 0a 20 20 20 20 20 20 20  mmodate..       
d3b0: 20 2f 2f 2f 20 73 75 63 68 20 63 68 61 6e 67 65   /// such change
d3c0: 73 2c 20 74 68 65 20 78 55 70 64 61 74 65 20 6d  s, the xUpdate m
d3d0: 65 74 68 6f 64 20 6d 75 73 74 20 72 65 74 75 72  ethod must retur
d3e0: 6e 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 2e  n an error code.
d3f0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
d400: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
d410: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20  // <para>..     
d420: 20 20 20 2f 2f 2f 20 54 68 65 20 78 55 70 64 61     /// The xUpda
d430: 74 65 20 6d 65 74 68 6f 64 20 69 73 20 6f 70 74  te method is opt
d440: 69 6f 6e 61 6c 2e 0d 0a 20 20 20 20 20 20 20 20  ional...        
d450: 2f 2f 2f 20 49 66 20 74 68 65 20 78 55 70 64 61  /// If the xUpda
d460: 74 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68  te pointer in th
d470: 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  e sqlite3_module
d480: 20 66 6f 72 20 61 20 76 69 72 74 75 61 6c 20 74   for a virtual t
d490: 61 62 6c 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f  able..        //
d4a0: 2f 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  / is a NULL poin
d4b0: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 76 69  ter, then the vi
d4c0: 72 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20 72  rtual table is r
d4d0: 65 61 64 2d 6f 6e 6c 79 2e 0d 0a 20 20 20 20 20  ead-only...     
d4e0: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a     /// </para>..
d4f0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 73 75          /// </su
d500: 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20  mmary>..        
d510: 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d  /// <param name=
d520: 22 70 56 74 61 62 22 3e 0d 0a 20 20 20 20 20 20  "pVtab">..      
d530: 20 20 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76 65    /// The native
d540: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
d550: 73 71 6c 69 74 65 33 5f 76 74 61 62 20 64 65 72  sqlite3_vtab der
d560: 69 76 65 64 20 73 74 72 75 63 74 75 72 65 2e 0d  ived structure..
d570: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
d580: 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f  aram>..        /
d590: 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22  // <param name="
d5a0: 61 72 67 63 22 3e 0d 0a 20 20 20 20 20 20 20 20  argc">..        
d5b0: 2f 2f 2f 20 54 68 65 20 6e 75 6d 62 65 72 20 6f  /// The number o
d5c0: 66 20 6e 65 77 20 6f 72 20 6d 6f 64 69 66 69 65  f new or modifie
d5d0: 64 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 20  d column values 
d5e0: 63 6f 6e 74 61 69 6e 65 64 20 69 6e 0d 0a 20 20  contained in..  
d5f0: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d        /// <param
d600: 72 65 66 20 6e 61 6d 65 3d 22 61 72 67 76 22 20  ref name="argv" 
d610: 2f 3e 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  />...        ///
d620: 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20   </param>..     
d630: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61     /// <param na
d640: 6d 65 3d 22 61 72 67 76 22 3e 0d 0a 20 20 20 20  me="argv">..    
d650: 20 20 20 20 2f 2f 2f 20 54 68 65 20 61 72 72 61      /// The arra
d660: 79 20 6f 66 20 6e 61 74 69 76 65 20 70 6f 69 6e  y of native poin
d670: 74 65 72 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  ters to sqlite3_
d680: 76 61 6c 75 65 20 73 74 72 75 63 74 75 72 65 73  value structures
d690: 20 63 6f 6e 74 61 69 6e 69 6e 67 0d 0a 20 20 20   containing..   
d6a0: 20 20 20 20 20 2f 2f 2f 20 74 68 65 20 6e 65 77       /// the new
d6b0: 20 6f 72 20 6d 6f 64 69 66 69 65 64 20 63 6f 6c   or modified col
d6c0: 75 6d 6e 20 76 61 6c 75 65 73 2c 20 69 66 20 61  umn values, if a
d6d0: 6e 79 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ny...        ///
d6e0: 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20   </param>..     
d6f0: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61     /// <param na
d700: 6d 65 3d 22 72 6f 77 49 64 22 3e 0d 0a 20 20 20  me="rowId">..   
d710: 20 20 20 20 20 2f 2f 2f 20 55 70 6f 6e 20 73 75       /// Upon su
d720: 63 63 65 73 73 2c 20 74 68 69 73 20 70 61 72 61  ccess, this para
d730: 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 6d 6f  meter must be mo
d740: 64 69 66 69 65 64 20 74 6f 20 63 6f 6e 74 61 69  dified to contai
d750: 6e 20 74 68 65 20 75 6e 69 71 75 65 0d 0a 20 20  n the unique..  
d760: 20 20 20 20 20 20 2f 2f 2f 20 69 6e 74 65 67 65        /// intege
d770: 72 20 72 6f 77 20 69 64 65 6e 74 69 66 69 65 72  r row identifier
d780: 20 66 6f 72 20 74 68 65 20 72 6f 77 20 74 68 61   for the row tha
d790: 74 20 77 61 73 20 69 6e 73 65 72 74 65 64 2c 20  t was inserted, 
d7a0: 69 66 20 61 6e 79 2e 0d 0a 20 20 20 20 20 20 20  if any...       
d7b0: 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20   /// </param>.. 
d7c0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 72 65 74 75         /// <retu
d7d0: 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  rns>..        //
d7e0: 2f 20 41 20 73 74 61 6e 64 61 72 64 20 53 51 4c  / A standard SQL
d7f0: 69 74 65 20 72 65 74 75 72 6e 20 63 6f 64 65 2e  ite return code.
d800: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
d810: 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20  returns>..      
d820: 20 20 53 51 4c 69 74 65 45 72 72 6f 72 43 6f 64    SQLiteErrorCod
d830: 65 20 78 55 70 64 61 74 65 28 0d 0a 20 20 20 20  e xUpdate(..    
d840: 20 20 20 20 20 20 20 20 49 6e 74 50 74 72 20 70          IntPtr p
d850: 56 74 61 62 2c 0d 0a 20 20 20 20 20 20 20 20 20  Vtab,..         
d860: 20 20 20 69 6e 74 20 61 72 67 63 2c 0d 0a 20 20     int argc,..  
d870: 20 20 20 20 20 20 20 20 20 20 49 6e 74 50 74 72            IntPtr
d880: 20 61 72 67 76 2c 0d 0a 20 20 20 20 20 20 20 20   argv,..        
d890: 20 20 20 20 72 65 66 20 6c 6f 6e 67 20 72 6f 77      ref long row
d8a0: 49 64 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20  Id..            
d8b0: 29 3b 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f  );....        //
d8c0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
d8d0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
d8e0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
d8f0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
d900: 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 20 20 20  /////....       
d910: 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a   /// <summary>..
d920: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
d930: 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20  a><code>..      
d940: 20 20 2f 2f 2f 20 20 20 69 6e 74 20 28 2a 78 42    ///   int (*xB
d950: 65 67 69 6e 29 28 73 71 6c 69 74 65 33 5f 76 74  egin)(sqlite3_vt
d960: 61 62 20 2a 70 56 54 61 62 29 3b 0d 0a 20 20 20  ab *pVTab);..   
d970: 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e       /// </code>
d980: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
d990: 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20   /// <para>..   
d9a0: 20 20 20 20 20 2f 2f 2f 20 54 68 69 73 20 6d 65       /// This me
d9b0: 74 68 6f 64 20 62 65 67 69 6e 73 20 61 20 74 72  thod begins a tr
d9c0: 61 6e 73 61 63 74 69 6f 6e 20 6f 6e 20 61 20 76  ansaction on a v
d9d0: 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 0d 0a 20  irtual table... 
d9e0: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 69 73 20         /// This 
d9f0: 69 73 20 6d 65 74 68 6f 64 20 69 73 20 6f 70 74  is method is opt
da00: 69 6f 6e 61 6c 2e 20 20 54 68 65 20 78 42 65 67  ional.  The xBeg
da10: 69 6e 20 70 6f 69 6e 74 65 72 20 6f 66 20 73 71  in pointer of sq
da20: 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 0d 0a 20 20  lite3_module..  
da30: 20 20 20 20 20 20 2f 2f 2f 20 6d 61 79 20 62 65        /// may be
da40: 20 4e 55 4c 4c 2e 0d 0a 20 20 20 20 20 20 20 20   NULL...        
da50: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  /// </para>..   
da60: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
da70: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 69  .        /// Thi
da80: 73 20 6d 65 74 68 6f 64 20 69 73 20 61 6c 77 61  s method is alwa
da90: 79 73 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6f  ys followed by o
daa0: 6e 65 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65  ne call to eithe
dab0: 72 20 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f  r the..        /
dac0: 2f 2f 20 78 43 6f 6d 6d 69 74 20 6f 72 20 78 52  // xCommit or xR
dad0: 6f 6c 6c 62 61 63 6b 20 6d 65 74 68 6f 64 2e 20  ollback method. 
dae0: 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 74   Virtual table t
daf0: 72 61 6e 73 61 63 74 69 6f 6e 73 20 64 6f 0d 0a  ransactions do..
db00: 20 20 20 20 20 20 20 20 2f 2f 2f 20 6e 6f 74 20          /// not 
db10: 6e 65 73 74 2c 20 73 6f 20 74 68 65 20 78 42 65  nest, so the xBe
db20: 67 69 6e 20 6d 65 74 68 6f 64 20 77 69 6c 6c 20  gin method will 
db30: 6e 6f 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 6d  not be invoked m
db40: 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 0d 0a 20  ore than once.. 
db50: 20 20 20 20 20 20 20 2f 2f 2f 20 6f 6e 20 61 20         /// on a 
db60: 73 69 6e 67 6c 65 20 76 69 72 74 75 61 6c 20 74  single virtual t
db70: 61 62 6c 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f  able..        //
db80: 2f 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74  / without an int
db90: 65 72 76 65 6e 69 6e 67 20 63 61 6c 6c 20 74 6f  ervening call to
dba0: 20 65 69 74 68 65 72 20 78 43 6f 6d 6d 69 74 20   either xCommit 
dbb0: 6f 72 20 78 52 6f 6c 6c 62 61 63 6b 2e 0d 0a 20  or xRollback... 
dbc0: 20 20 20 20 20 20 20 2f 2f 2f 20 4d 75 6c 74 69         /// Multi
dbd0: 70 6c 65 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68  ple calls to oth
dbe0: 65 72 20 6d 65 74 68 6f 64 73 20 63 61 6e 20 61  er methods can a
dbf0: 6e 64 20 6c 69 6b 65 6c 79 20 77 69 6c 6c 20 6f  nd likely will o
dc00: 63 63 75 72 20 69 6e 20 62 65 74 77 65 65 6e 0d  ccur in between.
dc10: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65  .        /// the
dc20: 20 78 42 65 67 69 6e 20 61 6e 64 20 74 68 65 20   xBegin and the 
dc30: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 78 43  corresponding xC
dc40: 6f 6d 6d 69 74 20 6f 72 20 78 52 6f 6c 6c 62 61  ommit or xRollba
dc50: 63 6b 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ck...        ///
dc60: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20   </para>..      
dc70: 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e    /// </summary>
dc80: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70  ..        /// <p
dc90: 61 72 61 6d 20 6e 61 6d 65 3d 22 70 56 74 61 62  aram name="pVtab
dca0: 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ">..        /// 
dcb0: 54 68 65 20 6e 61 74 69 76 65 20 70 6f 69 6e 74  The native point
dcc0: 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
dcd0: 33 5f 76 74 61 62 20 64 65 72 69 76 65 64 20 73  3_vtab derived s
dce0: 74 72 75 63 74 75 72 65 2e 0d 0a 20 20 20 20 20  tructure...     
dcf0: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d     /// </param>.
dd00: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 72 65  .        /// <re
dd10: 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20  turns>..        
dd20: 2f 2f 2f 20 41 20 73 74 61 6e 64 61 72 64 20 53  /// A standard S
dd30: 51 4c 69 74 65 20 72 65 74 75 72 6e 20 63 6f 64  QLite return cod
dd40: 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e...        /// 
dd50: 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20  </returns>..    
dd60: 20 20 20 20 53 51 4c 69 74 65 45 72 72 6f 72 43      SQLiteErrorC
dd70: 6f 64 65 20 78 42 65 67 69 6e 28 0d 0a 20 20 20  ode xBegin(..   
dd80: 20 20 20 20 20 20 20 20 20 49 6e 74 50 74 72 20           IntPtr 
dd90: 70 56 74 61 62 0d 0a 20 20 20 20 20 20 20 20 20  pVtab..         
dda0: 20 20 20 29 3b 0d 0a 0d 0a 20 20 20 20 20 20 20     );....       
ddb0: 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f   ///////////////
ddc0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
ddd0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
dde0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
ddf0: 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20  ////////....    
de00: 20 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79      /// <summary
de10: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
de20: 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20  para><code>..   
de30: 20 20 20 20 20 2f 2f 2f 20 20 20 69 6e 74 20 28       ///   int (
de40: 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xSync)(sqlite3_
de50: 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0d 0a 20  vtab *pVTab);.. 
de60: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64         /// </cod
de70: 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  e></para>..     
de80: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20     /// <para>.. 
de90: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 69 73 20         /// This 
dea0: 6d 65 74 68 6f 64 20 73 69 67 6e 61 6c 73 20 74  method signals t
deb0: 68 65 20 73 74 61 72 74 20 6f 66 20 61 20 74 77  he start of a tw
dec0: 6f 2d 70 68 61 73 65 20 63 6f 6d 6d 69 74 20 6f  o-phase commit o
ded0: 6e 20 61 20 76 69 72 74 75 61 6c 0d 0a 20 20 20  n a virtual..   
dee0: 20 20 20 20 20 2f 2f 2f 20 74 61 62 6c 65 2e 0d       /// table..
def0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 69  .        /// Thi
df00: 73 20 69 73 20 6d 65 74 68 6f 64 20 69 73 20 6f  s is method is o
df10: 70 74 69 6f 6e 61 6c 2e 20 20 54 68 65 20 78 53  ptional.  The xS
df20: 79 6e 63 20 70 6f 69 6e 74 65 72 20 6f 66 20 73  ync pointer of s
df30: 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 0d 0a 20  qlite3_module.. 
df40: 20 20 20 20 20 20 20 2f 2f 2f 20 6d 61 79 20 62         /// may b
df50: 65 20 4e 55 4c 4c 2e 0d 0a 20 20 20 20 20 20 20  e NULL...       
df60: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20   /// </para>..  
df70: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e        /// <para>
df80: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
df90: 69 73 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c  is method is onl
dfa0: 79 20 69 6e 76 6f 6b 65 64 20 61 66 74 65 72 20  y invoked after 
dfb0: 63 61 6c 6c 20 74 6f 20 74 68 65 20 78 42 65 67  call to the xBeg
dfc0: 69 6e 20 6d 65 74 68 6f 64 20 61 6e 64 0d 0a 20  in method and.. 
dfd0: 20 20 20 20 20 20 20 2f 2f 2f 20 70 72 69 6f 72         /// prior
dfe0: 20 74 6f 20 61 6e 20 78 43 6f 6d 6d 69 74 20 6f   to an xCommit o
dff0: 72 20 78 52 6f 6c 6c 62 61 63 6b 2e 20 20 49 6e  r xRollback.  In
e000: 20 6f 72 64 65 72 20 74 6f 20 69 6d 70 6c 65 6d   order to implem
e010: 65 6e 74 20 74 77 6f 2d 70 68 61 73 65 0d 0a 20  ent two-phase.. 
e020: 20 20 20 20 20 20 20 2f 2f 2f 20 63 6f 6d 6d 69         /// commi
e030: 74 2c 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  t, the xSync met
e040: 68 6f 64 20 6f 6e 20 61 6c 6c 20 76 69 72 74 75  hod on all virtu
e050: 61 6c 20 74 61 62 6c 65 73 20 69 73 20 69 6e 76  al tables is inv
e060: 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 0d 0a 20  oked prior to.. 
e070: 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e 76 6f 6b         /// invok
e080: 69 6e 67 20 74 68 65 20 78 43 6f 6d 6d 69 74 20  ing the xCommit 
e090: 6d 65 74 68 6f 64 20 6f 6e 20 61 6e 79 20 76 69  method on any vi
e0a0: 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 20 49 66  rtual table.  If
e0b0: 20 61 6e 79 20 6f 66 20 74 68 65 20 0d 0a 20 20   any of the ..  
e0c0: 20 20 20 20 20 20 2f 2f 2f 20 78 53 79 6e 63 20        /// xSync 
e0d0: 6d 65 74 68 6f 64 73 20 66 61 69 6c 2c 20 74 68  methods fail, th
e0e0: 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63  e entire transac
e0f0: 74 69 6f 6e 20 69 73 20 72 6f 6c 6c 65 64 20 62  tion is rolled b
e100: 61 63 6b 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ack...        //
e110: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  / </para>..     
e120: 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79     /// </summary
e130: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
e140: 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 56 74 61  param name="pVta
e150: 62 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  b">..        ///
e160: 20 54 68 65 20 6e 61 74 69 76 65 20 70 6f 69 6e   The native poin
e170: 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
e180: 65 33 5f 76 74 61 62 20 64 65 72 69 76 65 64 20  e3_vtab derived 
e190: 73 74 72 75 63 74 75 72 65 2e 0d 0a 20 20 20 20  structure...    
e1a0: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e      /// </param>
e1b0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 72  ..        /// <r
e1c0: 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20  eturns>..       
e1d0: 20 2f 2f 2f 20 41 20 73 74 61 6e 64 61 72 64 20   /// A standard 
e1e0: 53 51 4c 69 74 65 20 72 65 74 75 72 6e 20 63 6f  SQLite return co
e1f0: 64 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  de...        ///
e200: 20 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20   </returns>..   
e210: 20 20 20 20 20 53 51 4c 69 74 65 45 72 72 6f 72       SQLiteError
e220: 43 6f 64 65 20 78 53 79 6e 63 28 0d 0a 20 20 20  Code xSync(..   
e230: 20 20 20 20 20 20 20 20 20 49 6e 74 50 74 72 20           IntPtr 
e240: 70 56 74 61 62 0d 0a 20 20 20 20 20 20 20 20 20  pVtab..         
e250: 20 20 20 29 3b 0d 0a 0d 0a 20 20 20 20 20 20 20     );....       
e260: 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f   ///////////////
e270: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
e280: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
e290: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
e2a0: 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20  ////////....    
e2b0: 20 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79      /// <summary
e2c0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
e2d0: 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20  para><code>..   
e2e0: 20 20 20 20 20 2f 2f 2f 20 20 20 69 6e 74 20 28       ///   int (
e2f0: 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69 74 65  *xCommit)(sqlite
e300: 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0d  3_vtab *pVTab);.
e310: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63  .        /// </c
e320: 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20  ode></para>..   
e330: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d       /// <para>.
e340: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 69  .        /// Thi
e350: 73 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20  s method causes 
e360: 61 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  a virtual table 
e370: 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 63  transaction to c
e380: 6f 6d 6d 69 74 2e 0d 0a 20 20 20 20 20 20 20 20  ommit...        
e390: 2f 2f 2f 20 54 68 69 73 20 69 73 20 6d 65 74 68  /// This is meth
e3a0: 6f 64 20 69 73 20 6f 70 74 69 6f 6e 61 6c 2e 20  od is optional. 
e3b0: 20 54 68 65 20 78 43 6f 6d 6d 69 74 20 70 6f 69   The xCommit poi
e3c0: 6e 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  nter of sqlite3_
e3d0: 6d 6f 64 75 6c 65 0d 0a 20 20 20 20 20 20 20 20  module..        
e3e0: 2f 2f 2f 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e  /// may be NULL.
e3f0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
e400: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
e410: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20  // <para>..     
e420: 20 20 20 2f 2f 2f 20 41 20 63 61 6c 6c 20 74 6f     /// A call to
e430: 20 74 68 69 73 20 6d 65 74 68 6f 64 20 61 6c 77   this method alw
e440: 61 79 73 20 66 6f 6c 6c 6f 77 73 20 61 20 70 72  ays follows a pr
e450: 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 42 65 67  ior call to xBeg
e460: 69 6e 20 61 6e 64 0d 0a 20 20 20 20 20 20 20 20  in and..        
e470: 2f 2f 2f 20 78 53 79 6e 63 2e 0d 0a 20 20 20 20  /// xSync...    
e480: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
e490: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 73  .        /// </s
e4a0: 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20  ummary>..       
e4b0: 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65   /// <param name
e4c0: 3d 22 70 56 74 61 62 22 3e 0d 0a 20 20 20 20 20  ="pVtab">..     
e4d0: 20 20 20 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76     /// The nativ
e4e0: 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
e4f0: 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 64 65   sqlite3_vtab de
e500: 72 69 76 65 64 20 73 74 72 75 63 74 75 72 65 2e  rived structure.
e510: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
e520: 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20  param>..        
e530: 2f 2f 2f 20 3c 72 65 74 75 72 6e 73 3e 0d 0a 20  /// <returns>.. 
e540: 20 20 20 20 20 20 20 2f 2f 2f 20 41 20 73 74 61         /// A sta
e550: 6e 64 61 72 64 20 53 51 4c 69 74 65 20 72 65 74  ndard SQLite ret
e560: 75 72 6e 20 63 6f 64 65 2e 0d 0a 20 20 20 20 20  urn code...     
e570: 20 20 20 2f 2f 2f 20 3c 2f 72 65 74 75 72 6e 73     /// </returns
e580: 3e 0d 0a 20 20 20 20 20 20 20 20 53 51 4c 69 74  >..        SQLit
e590: 65 45 72 72 6f 72 43 6f 64 65 20 78 43 6f 6d 6d  eErrorCode xComm
e5a0: 69 74 28 0d 0a 20 20 20 20 20 20 20 20 20 20 20  it(..           
e5b0: 20 49 6e 74 50 74 72 20 70 56 74 61 62 0d 0a 20   IntPtr pVtab.. 
e5c0: 20 20 20 20 20 20 20 20 20 20 20 29 3b 0d 0a 0d             );...
e5d0: 0a 20 20 20 20 20 20 20 20 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 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
e620: 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ....        /// 
e630: 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20  <summary>..     
e640: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f     /// <para><co
e650: 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  de>..        ///
e660: 20 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61     int (*xRollba
e670: 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  ck)(sqlite3_vtab
e680: 20 2a 70 56 54 61 62 29 3b 0d 0a 20 20 20 20 20   *pVTab);..     
e690: 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f     /// </code></
e6a0: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
e6b0: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20  // <para>..     
e6c0: 20 20 20 2f 2f 2f 20 54 68 69 73 20 6d 65 74 68     /// This meth
e6d0: 6f 64 20 63 61 75 73 65 73 20 61 20 76 69 72 74  od causes a virt
e6e0: 75 61 6c 20 74 61 62 6c 65 20 74 72 61 6e 73 61  ual table transa
e6f0: 63 74 69 6f 6e 20 74 6f 20 72 6f 6c 6c 62 61 63  ction to rollbac
e700: 6b 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  k...        /// 
e710: 54 68 69 73 20 69 73 20 6d 65 74 68 6f 64 20 69  This is method i
e720: 73 20 6f 70 74 69 6f 6e 61 6c 2e 20 20 54 68 65  s optional.  The
e730: 20 78 52 6f 6c 6c 62 61 63 6b 20 70 6f 69 6e 74   xRollback point
e740: 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d 6f  er of sqlite3_mo
e750: 64 75 6c 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f  dule..        //
e760: 2f 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0d 0a  / may be NULL...
e770: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
e780: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
e790: 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20   <para>..       
e7a0: 20 2f 2f 2f 20 41 20 63 61 6c 6c 20 74 6f 20 74   /// A call to t
e7b0: 68 69 73 20 6d 65 74 68 6f 64 20 61 6c 77 61 79  his method alway
e7c0: 73 20 66 6f 6c 6c 6f 77 73 20 61 20 70 72 69 6f  s follows a prio
e7d0: 72 20 63 61 6c 6c 20 74 6f 20 78 42 65 67 69 6e  r call to xBegin
e7e0: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
e7f0: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
e800: 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a  /// </summary>..
e810: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
e820: 61 6d 20 6e 61 6d 65 3d 22 70 56 74 61 62 22 3e  am name="pVtab">
e830: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
e840: 65 20 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72  e native pointer
e850: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
e860: 76 74 61 62 20 64 65 72 69 76 65 64 20 73 74 72  vtab derived str
e870: 75 63 74 75 72 65 2e 0d 0a 20 20 20 20 20 20 20  ucture...       
e880: 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20   /// </param>.. 
e890: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 72 65 74 75         /// <retu
e8a0: 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  rns>..        //
e8b0: 2f 20 41 20 73 74 61 6e 64 61 72 64 20 53 51 4c  / A standard SQL
e8c0: 69 74 65 20 72 65 74 75 72 6e 20 63 6f 64 65 2e  ite return code.
e8d0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
e8e0: 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20  returns>..      
e8f0: 20 20 53 51 4c 69 74 65 45 72 72 6f 72 43 6f 64    SQLiteErrorCod
e900: 65 20 78 52 6f 6c 6c 62 61 63 6b 28 0d 0a 20 20  e xRollback(..  
e910: 20 20 20 20 20 20 20 20 20 20 49 6e 74 50 74 72            IntPtr
e920: 20 70 56 74 61 62 0d 0a 20 20 20 20 20 20 20 20   pVtab..        
e930: 20 20 20 20 29 3b 0d 0a 0d 0a 20 20 20 20 20 20      );....      
e940: 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f    //////////////
e950: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
e960: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
e970: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
e980: 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20  /////////....   
e990: 20 20 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72       /// <summar
e9a0: 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  y>..        /// 
e9b0: 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20  <para><code>..  
e9c0: 20 20 20 20 20 20 2f 2f 2f 20 20 20 69 6e 74 20        ///   int 
e9d0: 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29  (*xFindFunction)
e9e0: 28 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20  (..        ///  
e9f0: 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20     sqlite3_vtab 
ea00: 2a 70 56 74 61 62 2c 0d 0a 20 20 20 20 20 20 20  *pVtab,..       
ea10: 20 2f 2f 2f 20 20 20 20 20 69 6e 74 20 6e 41 72   ///     int nAr
ea20: 67 2c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  g,..        /// 
ea30: 20 20 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a      const char *
ea40: 7a 4e 61 6d 65 2c 0d 0a 20 20 20 20 20 20 20 20  zName,..        
ea50: 2f 2f 2f 20 20 20 20 20 76 6f 69 64 20 28 2a 2a  ///     void (**
ea60: 70 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  pxFunc)(sqlite3_
ea70: 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
ea80: 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0d 0a  ite3_value**),..
ea90: 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20          ///     
eaa0: 76 6f 69 64 20 2a 2a 70 70 41 72 67 0d 0a 20 20  void **ppArg..  
eab0: 20 20 20 20 20 20 2f 2f 2f 20 20 20 29 3b 0d 0a        ///   );..
eac0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f          /// </co
ead0: 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  de></para>..    
eae0: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a      /// <para>..
eaf0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 69 73          /// This
eb00: 20 6d 65 74 68 6f 64 20 69 73 20 63 61 6c 6c 65   method is calle
eb10: 64 20 64 75 72 69 6e 67 20 73 71 6c 69 74 65 33  d during sqlite3
eb20: 5f 70 72 65 70 61 72 65 28 29 20 74 6f 20 67 69  _prepare() to gi
eb30: 76 65 20 74 68 65 20 76 69 72 74 75 61 6c 0d 0a  ve the virtual..
eb40: 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 61 62 6c          /// tabl
eb50: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
eb60: 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 20   an opportunity 
eb70: 74 6f 20 6f 76 65 72 6c 6f 61 64 20 66 75 6e 63  to overload func
eb80: 74 69 6f 6e 73 2e 20 0d 0a 20 20 20 20 20 20 20  tions. ..       
eb90: 20 2f 2f 2f 20 54 68 69 73 20 6d 65 74 68 6f 64   /// This method
eba0: 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 4e   may be set to N
ebb0: 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73  ULL in which cas
ebc0: 65 20 6e 6f 20 6f 76 65 72 6c 6f 61 64 69 6e 67  e no overloading
ebd0: 20 6f 63 63 75 72 73 2e 0d 0a 20 20 20 20 20 20   occurs...      
ebe0: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
ebf0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
ec00: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 57  >..        /// W
ec10: 68 65 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 75  hen a function u
ec20: 73 65 73 20 61 20 63 6f 6c 75 6d 6e 20 66 72 6f  ses a column fro
ec30: 6d 20 61 20 76 69 72 74 75 61 6c 20 74 61 62 6c  m a virtual tabl
ec40: 65 20 61 73 20 69 74 73 20 66 69 72 73 74 20 0d  e as its first .
ec50: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 61 72 67  .        /// arg
ec60: 75 6d 65 6e 74 2c 20 74 68 69 73 20 6d 65 74 68  ument, this meth
ec70: 6f 64 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  od is called to 
ec80: 73 65 65 20 69 66 20 74 68 65 20 76 69 72 74 75  see if the virtu
ec90: 61 6c 20 74 61 62 6c 65 20 77 6f 75 6c 64 20 0d  al table would .
eca0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6c 69 6b  .        /// lik
ecb0: 65 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  e to overload th
ecc0: 65 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20  e function. The 
ecd0: 66 69 72 73 74 20 74 68 72 65 65 20 70 61 72 61  first three para
ece0: 6d 65 74 65 72 73 20 61 72 65 20 69 6e 70 75 74  meters are input
ecf0: 73 3a 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  s: ..        ///
ed00: 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
ed10: 6c 65 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  le, the number o
ed20: 66 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  f arguments to t
ed30: 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 61 6e 64  he function, and
ed40: 20 74 68 65 20 0d 0a 20 20 20 20 20 20 20 20 2f   the ..        /
ed50: 2f 2f 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66  // name of the f
ed60: 75 6e 63 74 69 6f 6e 2e 20 49 66 20 6e 6f 20 6f  unction. If no o
ed70: 76 65 72 6c 6f 61 64 69 6e 67 20 69 73 20 64 65  verloading is de
ed80: 73 69 72 65 64 2c 20 74 68 69 73 20 6d 65 74 68  sired, this meth
ed90: 6f 64 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  od..        /// 
eda0: 72 65 74 75 72 6e 73 20 30 2e 20 54 6f 20 6f 76  returns 0. To ov
edb0: 65 72 6c 6f 61 64 20 74 68 65 20 66 75 6e 63 74  erload the funct
edc0: 69 6f 6e 2c 20 74 68 69 73 20 6d 65 74 68 6f 64  ion, this method
edd0: 20 77 72 69 74 65 73 20 74 68 65 20 6e 65 77 20   writes the new 
ede0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 66 75  ..        /// fu
edf0: 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
ee00: 61 74 69 6f 6e 20 69 6e 74 6f 20 2a 70 78 46 75  ation into *pxFu
ee10: 6e 63 20 61 6e 64 20 77 72 69 74 65 73 20 75 73  nc and writes us
ee20: 65 72 20 64 61 74 61 20 69 6e 74 6f 20 2a 70 70  er data into *pp
ee30: 41 72 67 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  Arg ..        //
ee40: 2f 20 61 6e 64 20 72 65 74 75 72 6e 73 20 31 2e  / and returns 1.
ee50: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
ee60: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
ee70: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20  // <para>..     
ee80: 20 20 20 2f 2f 2f 20 4e 6f 74 65 20 74 68 61 74     /// Note that
ee90: 20 69 6e 66 69 78 20 66 75 6e 63 74 69 6f 6e 73   infix functions
eea0: 20 28 4c 49 4b 45 2c 20 47 4c 4f 42 2c 20 52 45   (LIKE, GLOB, RE
eeb0: 47 45 58 50 2c 20 61 6e 64 20 4d 41 54 43 48 29  GEXP, and MATCH)
eec0: 20 72 65 76 65 72 73 65 20 0d 0a 20 20 20 20 20   reverse ..     
eed0: 20 20 20 2f 2f 2f 20 74 68 65 20 6f 72 64 65 72     /// the order
eee0: 20 6f 66 20 74 68 65 69 72 20 61 72 67 75 6d 65   of their argume
eef0: 6e 74 73 2e 20 53 6f 20 22 6c 69 6b 65 28 41 2c  nts. So "like(A,
ef00: 42 29 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e  B)" is equivalen
ef10: 74 20 74 6f 20 22 42 20 6c 69 6b 65 20 41 22 2e  t to "B like A".
ef20: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 46   ..        /// F
ef30: 6f 72 20 74 68 65 20 66 6f 72 6d 20 22 42 20 6c  or the form "B l
ef40: 69 6b 65 20 41 22 20 74 68 65 20 42 20 74 65 72  ike A" the B ter
ef50: 6d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  m is considered 
ef60: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
ef70: 6e 74 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  nt ..        ///
ef80: 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   to the function
ef90: 2e 20 42 75 74 20 66 6f 72 20 22 6c 69 6b 65 28  . But for "like(
efa0: 41 2c 42 29 22 20 74 68 65 20 41 20 74 65 72 6d  A,B)" the A term
efb0: 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74   is considered t
efc0: 68 65 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  he ..        ///
efd0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
efe0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
eff0: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
f000: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20  // <para>..     
f010: 20 20 20 2f 2f 2f 20 54 68 65 20 66 75 6e 63 74     /// The funct
f020: 69 6f 6e 20 70 6f 69 6e 74 65 72 20 72 65 74 75  ion pointer retu
f030: 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75  rned by this rou
f040: 74 69 6e 65 20 6d 75 73 74 20 62 65 20 76 61 6c  tine must be val
f050: 69 64 20 66 6f 72 0d 0a 20 20 20 20 20 20 20 20  id for..        
f060: 2f 2f 2f 20 74 68 65 20 6c 69 66 65 74 69 6d 65  /// the lifetime
f070: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
f080: 76 74 61 62 20 6f 62 6a 65 63 74 20 67 69 76 65  vtab object give
f090: 6e 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70  n in the first p
f0a0: 61 72 61 6d 65 74 65 72 2e 0d 0a 20 20 20 20 20  arameter...     
f0b0: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a     /// </para>..
f0c0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 73 75          /// </su
f0d0: 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20  mmary>..        
f0e0: 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d  /// <param name=
f0f0: 22 70 56 74 61 62 22 3e 0d 0a 20 20 20 20 20 20  "pVtab">..      
f100: 20 20 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76 65    /// The native
f110: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
f120: 73 71 6c 69 74 65 33 5f 76 74 61 62 20 64 65 72  sqlite3_vtab der
f130: 69 76 65 64 20 73 74 72 75 63 74 75 72 65 2e 0d  ived structure..
f140: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70  .        /// </p
f150: 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f  aram>..        /
f160: 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22  // <param name="
f170: 6e 41 72 67 22 3e 0d 0a 20 20 20 20 20 20 20 20  nArg">..        
f180: 2f 2f 2f 20 54 68 65 20 6e 75 6d 62 65 72 20 6f  /// The number o
f190: 66 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  f arguments to t
f1a0: 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e  he function bein
f1b0: 67 20 73 6f 75 67 68 74 2e 0d 0a 20 20 20 20 20  g sought...     
f1c0: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d     /// </param>.
f1d0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
f1e0: 72 61 6d 20 6e 61 6d 65 3d 22 7a 4e 61 6d 65 22  ram name="zName"
f1f0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54  >..        /// T
f200: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66  he name of the f
f210: 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 73 6f  unction being so
f220: 75 67 68 74 2e 0d 0a 20 20 20 20 20 20 20 20 2f  ught...        /
f230: 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20  // </param>..   
f240: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20       /// <param 
f250: 6e 61 6d 65 3d 22 63 61 6c 6c 62 61 63 6b 22 3e  name="callback">
f260: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 55 70  ..        /// Up
f270: 6f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 69 73  on success, this
f280: 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
f290: 62 65 20 6d 6f 64 69 66 69 65 64 20 74 6f 20 63  be modified to c
f2a0: 6f 6e 74 61 69 6e 20 74 68 65 0d 0a 20 20 20 20  ontain the..    
f2b0: 20 20 20 20 2f 2f 2f 20 64 65 6c 65 67 61 74 65      /// delegate
f2c0: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
f2d0: 20 69 6d 70 6c 65 6d 65 6e 74 69 6e 67 20 74 68   implementing th
f2e0: 65 20 73 70 65 63 69 66 69 65 64 20 66 75 6e 63  e specified func
f2f0: 74 69 6f 6e 2e 0d 0a 20 20 20 20 20 20 20 20 2f  tion...        /
f300: 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20  // </param>..   
f310: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20       /// <param 
f320: 6e 61 6d 65 3d 22 70 43 6c 69 65 6e 74 44 61 74  name="pClientDat
f330: 61 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  a">..        ///
f340: 20 55 70 6f 6e 20 73 75 63 63 65 73 73 2c 20 74   Upon success, t
f350: 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 6d 75  his parameter mu
f360: 73 74 20 62 65 20 6d 6f 64 69 66 69 65 64 20 74  st be modified t
f370: 6f 20 63 6f 6e 74 61 69 6e 20 74 68 65 0d 0a 20  o contain the.. 
f380: 20 20 20 20 20 20 20 2f 2f 2f 20 6e 61 74 69 76         /// nativ
f390: 65 20 75 73 65 72 2d 64 61 74 61 20 70 6f 69 6e  e user-data poin
f3a0: 74 65 72 20 61 73 73 6f 63 69 61 74 65 64 20 77  ter associated w
f3b0: 69 74 68 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ith..        ///
f3c0: 20 3c 70 61 72 61 6d 72 65 66 20 6e 61 6d 65 3d   <paramref name=
f3d0: 22 63 61 6c 6c 62 61 63 6b 22 20 2f 3e 2e 0d 0a  "callback" />...
f3e0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61          /// </pa
f3f0: 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ram>..        //
f400: 2f 20 3c 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20  / <returns>..   
f410: 20 20 20 20 20 2f 2f 2f 20 4e 6f 6e 2d 7a 65 72       /// Non-zer
f420: 6f 20 69 66 20 74 68 65 20 73 70 65 63 69 66 69  o if the specifi
f430: 65 64 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20  ed function was 
f440: 66 6f 75 6e 64 3b 20 7a 65 72 6f 20 6f 74 68 65  found; zero othe
f450: 72 77 69 73 65 2e 0d 0a 20 20 20 20 20 20 20 20  rwise...        
f460: 2f 2f 2f 20 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a  /// </returns>..
f470: 20 20 20 20 20 20 20 20 69 6e 74 20 78 46 69 6e          int xFin
f480: 64 46 75 6e 63 74 69 6f 6e 28 0d 0a 20 20 20 20  dFunction(..    
f490: 20 20 20 20 20 20 20 20 49 6e 74 50 74 72 20 70          IntPtr p
f4a0: 56 74 61 62 2c 0d 0a 20 20 20 20 20 20 20 20 20  Vtab,..         
f4b0: 20 20 20 69 6e 74 20 6e 41 72 67 2c 0d 0a 20 20     int nArg,..  
f4c0: 20 20 20 20 20 20 20 20 20 20 49 6e 74 50 74 72            IntPtr
f4d0: 20 7a 4e 61 6d 65 2c 0d 0a 20 20 20 20 20 20 20   zName,..       
f4e0: 20 20 20 20 20 72 65 66 20 53 51 4c 69 74 65 43       ref SQLiteC
f4f0: 61 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b  allback callback
f500: 2c 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 72  ,..            r
f510: 65 66 20 49 6e 74 50 74 72 20 70 43 6c 69 65 6e  ef IntPtr pClien
f520: 74 44 61 74 61 0d 0a 20 20 20 20 20 20 20 20 20  tData..         
f530: 20 20 20 29 3b 0d 0a 0d 0a 20 20 20 20 20 20 20     );....       
f540: 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f   ///////////////
f550: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
f560: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
f570: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
f580: 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20  ////////....    
f590: 20 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79      /// <summary
f5a0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
f5b0: 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20  para><code>..   
f5c0: 20 20 20 20 20 2f 2f 2f 20 20 20 69 6e 74 20 28       ///   int (
f5d0: 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65  *xRename)(sqlite
f5e0: 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 63  3_vtab *pVtab, c
f5f0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 29  onst char *zNew)
f600: 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ;..        /// <
f610: 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20  /code></para>.. 
f620: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
f630: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54  >..        /// T
f640: 68 69 73 20 6d 65 74 68 6f 64 20 70 72 6f 76 69  his method provi
f650: 64 65 73 20 6e 6f 74 69 66 69 63 61 74 69 6f 6e  des notification
f660: 20 74 68 61 74 20 74 68 65 20 76 69 72 74 75 61   that the virtua
f670: 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  l table implemen
f680: 74 61 74 69 6f 6e 0d 0a 20 20 20 20 20 20 20 20  tation..        
f690: 2f 2f 2f 20 74 68 61 74 20 74 68 65 20 76 69 72  /// that the vir
f6a0: 74 75 61 6c 20 74 61 62 6c 65 20 77 69 6c 6c 20  tual table will 
f6b0: 62 65 20 67 69 76 65 6e 20 61 20 6e 65 77 20 6e  be given a new n
f6c0: 61 6d 65 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f  ame. ..        /
f6d0: 2f 2f 20 49 66 20 74 68 69 73 20 6d 65 74 68 6f  // If this metho
f6e0: 64 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  d returns SQLITE
f6f0: 5f 4f 4b 20 74 68 65 6e 20 53 51 4c 69 74 65 20  _OK then SQLite 
f700: 72 65 6e 61 6d 65 73 20 74 68 65 20 74 61 62 6c  renames the tabl
f710: 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  e...        /// 
f720: 49 66 20 74 68 69 73 20 6d 65 74 68 6f 64 20 72  If this method r
f730: 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 20  eturns an error 
f740: 63 6f 64 65 20 74 68 65 6e 20 74 68 65 20 72 65  code then the re
f750: 6e 61 6d 69 6e 67 20 69 73 20 70 72 65 76 65 6e  naming is preven
f760: 74 65 64 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ted...        //
f770: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20  / </para>..     
f780: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20     /// <para>.. 
f790: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 78         /// The x
f7a0: 52 65 6e 61 6d 65 20 6d 65 74 68 6f 64 20 69 73  Rename method is
f7b0: 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 65 76   required for ev
f7c0: 65 72 79 20 76 69 72 74 75 61 6c 20 74 61 62 6c  ery virtual tabl
f7d0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
f7e0: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  ...        /// <
f7f0: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  /para>..        
f800: 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a  /// </summary>..
f810: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72          /// <par
f820: 61 6d 20 6e 61 6d 65 3d 22 70 56 74 61 62 22 3e  am name="pVtab">
f830: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
f840: 65 20 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72  e native pointer
f850: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
f860: 76 74 61 62 20 64 65 72 69 76 65 64 20 73 74 72  vtab derived str
f870: 75 63 74 75 72 65 2e 0d 0a 20 20 20 20 20 20 20  ucture...       
f880: 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20   /// </param>.. 
f890: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
f8a0: 6d 20 6e 61 6d 65 3d 22 7a 4e 65 77 22 3e 0d 0a  m name="zNew">..
f8b0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20          /// The 
f8c0: 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72 20 74  native pointer t
f8d0: 6f 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  o the UTF-8 enco
f8e0: 64 65 64 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  ded string conta
f8f0: 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 0d 0a 20  ining the new.. 
f900: 20 20 20 20 20 20 20 2f 2f 2f 20 6e 61 6d 65 20         /// name 
f910: 66 6f 72 20 74 68 65 20 76 69 72 74 75 61 6c 20  for the virtual 
f920: 74 61 62 6c 65 2e 0d 0a 20 20 20 20 20 20 20 20  table...        
f930: 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20  /// </param>..  
f940: 20 20 20 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72        /// <retur
f950: 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ns>..        ///
f960: 20 41 20 73 74 61 6e 64 61 72 64 20 53 51 4c 69   A standard SQLi
f970: 74 65 20 72 65 74 75 72 6e 20 63 6f 64 65 2e 0d  te return code..
f980: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72  .        /// </r
f990: 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20  eturns>..       
f9a0: 20 53 51 4c 69 74 65 45 72 72 6f 72 43 6f 64 65   SQLiteErrorCode
f9b0: 20 78 52 65 6e 61 6d 65 28 0d 0a 20 20 20 20 20   xRename(..     
f9c0: 20 20 20 20 20 20 20 49 6e 74 50 74 72 20 70 56         IntPtr pV
f9d0: 74 61 62 2c 0d 0a 20 20 20 20 20 20 20 20 20 20  tab,..          
f9e0: 20 20 49 6e 74 50 74 72 20 7a 4e 65 77 0d 0a 20    IntPtr zNew.. 
f9f0: 20 20 20 20 20 20 20 20 20 20 20 29 3b 0d 0a 0d             );...
fa00: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f  .        ///////
fa10: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
fa20: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
fa30: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
fa40: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
fa50: 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ....        /// 
fa60: 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20  <summary>..     
fa70: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f     /// <para><co
fa80: 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  de>..        ///
fa90: 20 20 20 69 6e 74 20 28 2a 78 53 61 76 65 70 6f     int (*xSavepo
faa0: 69 6e 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61  int)(sqlite3_vta
fab0: 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 29 3b 0d  b *pVtab, int);.
fac0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 69  .        ///   i
fad0: 6e 74 20 28 2a 78 52 65 6c 65 61 73 65 29 28 73  nt (*xRelease)(s
fae0: 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74  qlite3_vtab *pVt
faf0: 61 62 2c 20 69 6e 74 29 3b 0d 0a 20 20 20 20 20  ab, int);..     
fb00: 20 20 20 2f 2f 2f 20 20 20 69 6e 74 20 28 2a 78     ///   int (*x
fb10: 52 6f 6c 6c 62 61 63 6b 54 6f 29 28 73 71 6c 69  RollbackTo)(sqli
fb20: 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c  te3_vtab *pVtab,
fb30: 20 69 6e 74 29 3b 0d 0a 20 20 20 20 20 20 20 20   int);..        
fb40: 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72  /// </code></par
fb50: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
fb60: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
fb70: 2f 2f 2f 20 54 68 65 73 65 20 6d 65 74 68 6f 64  /// These method
fb80: 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 76 69  s provide the vi
fb90: 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c  rtual table impl
fba0: 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 20 6f 70  ementation an op
fbb0: 70 6f 72 74 75 6e 69 74 79 20 74 6f 0d 0a 20 20  portunity to..  
fbc0: 20 20 20 20 20 20 2f 2f 2f 20 69 6d 70 6c 65 6d        /// implem
fbd0: 65 6e 74 20 6e 65 73 74 65 64 20 74 72 61 6e 73  ent nested trans
fbe0: 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 79 20 61  actions.  They a
fbf0: 72 65 20 61 6c 77 61 79 73 20 6f 70 74 69 6f 6e  re always option
fc00: 61 6c 20 61 6e 64 20 77 69 6c 6c 20 6f 6e 6c 79  al and will only
fc10: 20 62 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f   be..        ///
fc20: 20 63 61 6c 6c 65 64 20 69 6e 20 53 51 4c 69 74   called in SQLit
fc30: 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 20  e version 3.7.7 
fc40: 61 6e 64 20 6c 61 74 65 72 2e 0d 0a 20 20 20 20  and later...    
fc50: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
fc60: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
fc70: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
fc80: 20 57 68 65 6e 20 78 53 61 76 65 70 6f 69 6e 74   When xSavepoint
fc90: 28 58 2c 4e 29 20 69 73 20 69 6e 76 6f 6b 65 64  (X,N) is invoked
fca0: 2c 20 74 68 61 74 20 69 73 20 61 20 73 69 67 6e  , that is a sign
fcb0: 61 6c 20 74 6f 20 74 68 65 20 76 69 72 74 75 61  al to the virtua
fcc0: 6c 20 74 61 62 6c 65 20 58 0d 0a 20 20 20 20 20  l table X..     
fcd0: 20 20 20 2f 2f 2f 20 74 68 61 74 20 69 74 20 73     /// that it s
fce0: 68 6f 75 6c 64 20 73 61 76 65 20 69 74 73 20 63  hould save its c
fcf0: 75 72 72 65 6e 74 20 73 74 61 74 65 20 61 73 20  urrent state as 
fd00: 73 61 76 65 70 6f 69 6e 74 20 4e 2e 20 20 0d 0a  savepoint N.  ..
fd10: 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 20 73 75          /// A su
fd20: 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 0d 0a 20  bsequent call.. 
fd30: 20 20 20 20 20 20 20 2f 2f 2f 20 74 6f 20 78 52         /// to xR
fd40: 6f 6c 6c 62 61 63 6b 54 6f 28 58 2c 52 29 20 6d  ollbackTo(X,R) m
fd50: 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74  eans that the st
fd60: 61 74 65 20 6f 66 20 74 68 65 20 76 69 72 74 75  ate of the virtu
fd70: 61 6c 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20  al table should 
fd80: 72 65 74 75 72 6e 0d 0a 20 20 20 20 20 20 20 20  return..        
fd90: 2f 2f 2f 20 74 6f 20 77 68 61 74 20 69 74 20 77  /// to what it w
fda0: 61 73 20 77 68 65 6e 20 78 53 61 76 65 70 6f 69  as when xSavepoi
fdb0: 6e 74 28 58 2c 52 29 20 77 61 73 20 6c 61 73 74  nt(X,R) was last
fdc0: 20 63 61 6c 6c 65 64 2e 20 20 0d 0a 20 20 20 20   called.  ..    
fdd0: 20 20 20 20 2f 2f 2f 20 54 68 65 20 63 61 6c 6c      /// The call
fde0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 6f  ..        /// to
fdf0: 20 78 52 6f 6c 6c 62 61 63 6b 54 6f 28 58 2c 52   xRollbackTo(X,R
fe00: 29 20 77 69 6c 6c 20 69 6e 76 61 6c 69 64 61 74  ) will invalidat
fe10: 65 20 61 6c 6c 20 73 61 76 65 70 6f 69 6e 74 73  e all savepoints
fe20: 20 77 69 74 68 20 4e 3e 52 3b 20 6e 6f 6e 65 20   with N>R; none 
fe30: 6f 66 20 74 68 65 0d 0a 20 20 20 20 20 20 20 20  of the..        
fe40: 2f 2f 2f 20 69 6e 76 61 6c 69 64 65 64 20 73 61  /// invalided sa
fe50: 76 65 70 6f 69 6e 74 73 20 77 69 6c 6c 20 62 65  vepoints will be
fe60: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 6f 72 20   rolled back or 
fe70: 72 65 6c 65 61 73 65 64 20 77 69 74 68 6f 75 74  released without
fe80: 20 66 69 72 73 74 0d 0a 20 20 20 20 20 20 20 20   first..        
fe90: 2f 2f 2f 20 62 65 69 6e 67 20 72 65 69 6e 69 74  /// being reinit
fea0: 69 61 6c 69 7a 65 64 20 62 79 20 61 20 63 61 6c  ialized by a cal
feb0: 6c 20 74 6f 20 78 53 61 76 65 70 6f 69 6e 74 28  l to xSavepoint(
fec0: 29 2e 20 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ).  ..        //
fed0: 2f 20 41 20 63 61 6c 6c 20 74 6f 20 78 52 65 6c  / A call to xRel
fee0: 65 61 73 65 28 58 2c 4d 29 20 69 6e 76 61 6c 69  ease(X,M) invali
fef0: 64 61 74 65 73 20 61 6c 6c 20 73 61 76 65 70 6f  dates all savepo
ff00: 69 6e 74 73 20 77 68 65 72 65 20 4e 3e 3d 4d 2e  ints where N>=M.
ff10: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
ff20: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
ff30: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20  // <para>..     
ff40: 20 20 20 2f 2f 2f 20 4e 6f 6e 65 20 6f 66 20 74     /// None of t
ff50: 68 65 20 78 53 61 76 65 70 6f 69 6e 74 28 29 2c  he xSavepoint(),
ff60: 20 78 52 65 6c 65 61 73 65 28 29 2c 20 6f 72 20   xRelease(), or 
ff70: 78 52 6f 6c 6c 62 61 63 6b 54 6f 28 29 20 6d 65  xRollbackTo() me
ff80: 74 68 6f 64 73 20 77 69 6c 6c 20 65 76 65 72 0d  thods will ever.
ff90: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 62 65 20  .        /// be 
ffa0: 63 61 6c 6c 65 64 20 65 78 63 65 70 74 20 69 6e  called except in
ffb0: 20 62 65 74 77 65 65 6e 20 63 61 6c 6c 73 20 74   between calls t
ffc0: 6f 20 78 42 65 67 69 6e 28 29 20 61 6e 64 20 0d  o xBegin() and .
ffd0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 65 69 74  .        /// eit
ffe0: 68 65 72 20 78 43 6f 6d 6d 69 74 28 29 20 6f 72  her xCommit() or
fff0: 20 78 52 6f 6c 6c 62 61 63 6b 28 29 2e 0d 0a 20   xRollback()... 
10000 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
10010 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
10020 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20  </summary>..    
10030 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e      /// <param n
10040 61 6d 65 3d 22 70 56 74 61 62 22 3e 0d 0a 20 20  ame="pVtab">..  
10050 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e 61        /// The na
10060 74 69 76 65 20 70 6f 69 6e 74 65 72 20 74 6f 20  tive pointer to 
10070 74 68 65 20 73 71 6c 69 74 65 33 5f 76 74 61 62  the sqlite3_vtab
10080 20 64 65 72 69 76 65 64 20 73 74 72 75 63 74 75   derived structu
10090 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  re...        ///
100a0 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20   </param>..     
100b0 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61     /// <param na
100c0 6d 65 3d 22 69 53 61 76 65 70 6f 69 6e 74 22 3e  me="iSavepoint">
100d0 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
100e0 69 73 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  is is an integer
100f0 20 69 64 65 6e 74 69 66 69 65 72 20 75 6e 64 65   identifier unde
10100 72 20 77 68 69 63 68 20 74 68 65 20 74 68 65 20  r which the the 
10110 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66  current state of
10120 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68  ..        /// th
10130 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  e virtual table 
10140 73 68 6f 75 6c 64 20 62 65 20 73 61 76 65 64 2e  should be saved.
10150 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
10160 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20  param>..        
10170 2f 2f 2f 20 3c 72 65 74 75 72 6e 73 3e 0d 0a 20  /// <returns>.. 
10180 20 20 20 20 20 20 20 2f 2f 2f 20 41 20 73 74 61         /// A sta
10190 6e 64 61 72 64 20 53 51 4c 69 74 65 20 72 65 74  ndard SQLite ret
101a0 75 72 6e 20 63 6f 64 65 2e 0d 0a 20 20 20 20 20  urn code...     
101b0 20 20 20 2f 2f 2f 20 3c 2f 72 65 74 75 72 6e 73     /// </returns
101c0 3e 0d 0a 20 20 20 20 20 20 20 20 53 51 4c 69 74  >..        SQLit
101d0 65 45 72 72 6f 72 43 6f 64 65 20 78 53 61 76 65  eErrorCode xSave
101e0 70 6f 69 6e 74 28 0d 0a 20 20 20 20 20 20 20 20  point(..        
101f0 20 20 20 20 49 6e 74 50 74 72 20 70 56 74 61 62      IntPtr pVtab
10200 2c 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 69  ,..            i
10210 6e 74 20 69 53 61 76 65 70 6f 69 6e 74 0d 0a 20  nt iSavepoint.. 
10220 20 20 20 20 20 20 20 20 20 20 20 29 3b 0d 0a 0d             );...
10230 0a 20 20 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f  .        ///////
10240 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
10250 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
10260 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
10270 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
10280 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  ....        /// 
10290 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20  <summary>..     
102a0 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f     /// <para><co
102b0 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  de>..        ///
102c0 20 20 20 69 6e 74 20 28 2a 78 53 61 76 65 70 6f     int (*xSavepo
102d0 69 6e 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61  int)(sqlite3_vta
102e0 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 29 3b 0d  b *pVtab, int);.
102f0 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 69  .        ///   i
10300 6e 74 20 28 2a 78 52 65 6c 65 61 73 65 29 28 73  nt (*xRelease)(s
10310 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74  qlite3_vtab *pVt
10320 61 62 2c 20 69 6e 74 29 3b 0d 0a 20 20 20 20 20  ab, int);..     
10330 20 20 20 2f 2f 2f 20 20 20 69 6e 74 20 28 2a 78     ///   int (*x
10340 52 6f 6c 6c 62 61 63 6b 54 6f 29 28 73 71 6c 69  RollbackTo)(sqli
10350 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c  te3_vtab *pVtab,
10360 20 69 6e 74 29 3b 0d 0a 20 20 20 20 20 20 20 20   int);..        
10370 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72  /// </code></par
10380 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
10390 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20  <para>..        
103a0 2f 2f 2f 20 54 68 65 73 65 20 6d 65 74 68 6f 64  /// These method
103b0 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 76 69  s provide the vi
103c0 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c  rtual table impl
103d0 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 20 6f 70  ementation an op
103e0 70 6f 72 74 75 6e 69 74 79 20 74 6f 0d 0a 20 20  portunity to..  
103f0 20 20 20 20 20 20 2f 2f 2f 20 69 6d 70 6c 65 6d        /// implem
10400 65 6e 74 20 6e 65 73 74 65 64 20 74 72 61 6e 73  ent nested trans
10410 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 79 20 61  actions.  They a
10420 72 65 20 61 6c 77 61 79 73 20 6f 70 74 69 6f 6e  re always option
10430 61 6c 20 61 6e 64 20 77 69 6c 6c 20 6f 6e 6c 79  al and will only
10440 20 62 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f   be..        ///
10450 20 63 61 6c 6c 65 64 20 69 6e 20 53 51 4c 69 74   called in SQLit
10460 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 20  e version 3.7.7 
10470 61 6e 64 20 6c 61 74 65 72 2e 0d 0a 20 20 20 20  and later...    
10480 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d      /// </para>.
10490 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61  .        /// <pa
104a0 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  ra>..        ///
104b0 20 57 68 65 6e 20 78 53 61 76 65 70 6f 69 6e 74   When xSavepoint
104c0 28 58 2c 4e 29 20 69 73 20 69 6e 76 6f 6b 65 64  (X,N) is invoked
104d0 2c 20 74 68 61 74 20 69 73 20 61 20 73 69 67 6e  , that is a sign
104e0 61 6c 20 74 6f 20 74 68 65 20 76 69 72 74 75 61  al to the virtua
104f0 6c 20 74 61 62 6c 65 20 58 0d 0a 20 20 20 20 20  l table X..     
10500 20 20 20 2f 2f 2f 20 74 68 61 74 20 69 74 20 73     /// that it s
10510 68 6f 75 6c 64 20 73 61 76 65 20 69 74 73 20 63  hould save its c
10520 75 72 72 65 6e 74 20 73 74 61 74 65 20 61 73 20  urrent state as 
10530 73 61 76 65 70 6f 69 6e 74 20 4e 2e 20 20 0d 0a  savepoint N.  ..
10540 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 20 73 75          /// A su
10550 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 0d 0a 20  bsequent call.. 
10560 20 20 20 20 20 20 20 2f 2f 2f 20 74 6f 20 78 52         /// to xR
10570 6f 6c 6c 62 61 63 6b 54 6f 28 58 2c 52 29 20 6d  ollbackTo(X,R) m
10580 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74  eans that the st
10590 61 74 65 20 6f 66 20 74 68 65 20 76 69 72 74 75  ate of the virtu
105a0 61 6c 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20  al table should 
105b0 72 65 74 75 72 6e 0d 0a 20 20 20 20 20 20 20 20  return..        
105c0 2f 2f 2f 20 74 6f 20 77 68 61 74 20 69 74 20 77  /// to what it w
105d0 61 73 20 77 68 65 6e 20 78 53 61 76 65 70 6f 69  as when xSavepoi
105e0 6e 74 28 58 2c 52 29 20 77 61 73 20 6c 61 73 74  nt(X,R) was last
105f0 20 63 61 6c 6c 65 64 2e 20 20 0d 0a 20 20 20 20   called.  ..    
10600 20 20 20 20 2f 2f 2f 20 54 68 65 20 63 61 6c 6c      /// The call
10610 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 6f  ..        /// to
10620 20 78 52 6f 6c 6c 62 61 63 6b 54 6f 28 58 2c 52   xRollbackTo(X,R
10630 29 20 77 69 6c 6c 20 69 6e 76 61 6c 69 64 61 74  ) will invalidat
10640 65 20 61 6c 6c 20 73 61 76 65 70 6f 69 6e 74 73  e all savepoints
10650 20 77 69 74 68 20 4e 3e 52 3b 20 6e 6f 6e 65 20   with N>R; none 
10660 6f 66 20 74 68 65 0d 0a 20 20 20 20 20 20 20 20  of the..        
10670 2f 2f 2f 20 69 6e 76 61 6c 69 64 65 64 20 73 61  /// invalided sa
10680 76 65 70 6f 69 6e 74 73 20 77 69 6c 6c 20 62 65  vepoints will be
10690 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 6f 72 20   rolled back or 
106a0 72 65 6c 65 61 73 65 64 20 77 69 74 68 6f 75 74  released without
106b0 20 66 69 72 73 74 0d 0a 20 20 20 20 20 20 20 20   first..        
106c0 2f 2f 2f 20 62 65 69 6e 67 20 72 65 69 6e 69 74  /// being reinit
106d0 69 61 6c 69 7a 65 64 20 62 79 20 61 20 63 61 6c  ialized by a cal
106e0 6c 20 74 6f 20 78 53 61 76 65 70 6f 69 6e 74 28  l to xSavepoint(
106f0 29 2e 20 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ).  ..        //
10700 2f 20 41 20 63 61 6c 6c 20 74 6f 20 78 52 65 6c  / A call to xRel
10710 65 61 73 65 28 58 2c 4d 29 20 69 6e 76 61 6c 69  ease(X,M) invali
10720 64 61 74 65 73 20 61 6c 6c 20 73 61 76 65 70 6f  dates all savepo
10730 69 6e 74 73 20 77 68 65 72 65 20 4e 3e 3d 4d 2e  ints where N>=M.
10740 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f  ..        /// </
10750 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f  para>..        /
10760 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20  // <para>..     
10770 20 20 20 2f 2f 2f 20 4e 6f 6e 65 20 6f 66 20 74     /// None of t
10780 68 65 20 78 53 61 76 65 70 6f 69 6e 74 28 29 2c  he xSavepoint(),
10790 20 78 52 65 6c 65 61 73 65 28 29 2c 20 6f 72 20   xRelease(), or 
107a0 78 52 6f 6c 6c 62 61 63 6b 54 6f 28 29 20 6d 65  xRollbackTo() me
107b0 74 68 6f 64 73 20 77 69 6c 6c 20 65 76 65 72 0d  thods will ever.
107c0 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 62 65 20  .        /// be 
107d0 63 61 6c 6c 65 64 20 65 78 63 65 70 74 20 69 6e  called except in
107e0 20 62 65 74 77 65 65 6e 20 63 61 6c 6c 73 20 74   between calls t
107f0 6f 20 78 42 65 67 69 6e 28 29 20 61 6e 64 20 0d  o xBegin() and .
10800 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 65 69 74  .        /// eit
10810 68 65 72 20 78 43 6f 6d 6d 69 74 28 29 20 6f 72  her xCommit() or
10820 20 78 52 6f 6c 6c 62 61 63 6b 28 29 2e 0d 0a 20   xRollback()... 
10830 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72         /// </par
10840 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  a>..        /// 
10850 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20  </summary>..    
10860 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e      /// <param n
10870 61 6d 65 3d 22 70 56 74 61 62 22 3e 0d 0a 20 20  ame="pVtab">..  
10880 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e 61        /// The na
10890 74 69 76 65 20 70 6f 69 6e 74 65 72 20 74 6f 20  tive pointer to 
108a0 74 68 65 20 73 71 6c 69 74 65 33 5f 76 74 61 62  the sqlite3_vtab
108b0 20 64 65 72 69 76 65 64 20 73 74 72 75 63 74 75   derived structu
108c0 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  re...        ///
108d0 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20   </param>..     
108e0 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61     /// <param na
108f0 6d 65 3d 22 69 53 61 76 65 70 6f 69 6e 74 22 3e  me="iSavepoint">
10900 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68  ..        /// Th
10910 69 73 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  is is an integer
10920 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74   used to indicat
10930 65 20 74 68 61 74 20 61 6e 79 20 73 61 76 65 64  e that any saved
10940 20 73 74 61 74 65 73 20 77 69 74 68 20 61 6e 0d   states with an.
10950 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 64 65  .        /// ide
10960 6e 74 69 66 69 65 72 20 67 72 65 61 74 65 72 20  ntifier greater 
10970 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
10980 20 74 68 69 73 20 73 68 6f 75 6c 64 20 62 65 20   this should be 
10990 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 0d 0a  deleted by the..
109a0 20 20 20 20 20 20 20 20 2f 2f 2f 20 76 69 72 74          /// virt
109b0 75 61 6c 20 74 61 62 6c 65 2e 0d 0a 20 20 20 20  ual table...    
109c0 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e      /// </param>
109d0 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 72  ..        /// <r
109e0 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20  eturns>..       
109f0 20 2f 2f 2f 20 41 20 73 74 61 6e 64 61 72 64 20   /// A standard 
10a00 53 51 4c 69 74 65 20 72 65 74 75 72 6e 20 63 6f  SQLite return co
10a10 64 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  de...        ///
10a20 20 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20   </returns>..   
10a30 20 20 20 20 20 53 51 4c 69 74 65 45 72 72 6f 72       SQLiteError
10a40 43 6f 64 65 20 78 52 65 6c 65 61 73 65 28 0d 0a  Code xRelease(..
10a50 20 20 20 20 20 20 20 20 20 20 20 20 49 6e 74 50              IntP
10a60 74 72 20 70 56 74 61 62 2c 0d 0a 20 20 20 20 20  tr pVtab,..     
10a70 20 20 20 20 20 20 20 69 6e 74 20 69 53 61 76 65         int iSave
10a80 70 6f 69 6e 74 0d 0a 20 20 20 20 20 20 20 20 20  point..         
10a90 20 20 20 29 3b 0d 0a 0d 0a 20 20 20 20 20 20 20     );....       
10aa0 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f   ///////////////
10ab0 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
10ac0 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
10ad0 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f  ////////////////
10ae0 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20  ////////....    
10af0 20 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79      /// <summary
10b00 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
10b10 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20  para><code>..   
10b20 20 20 20 20 20 2f 2f 2f 20 20 20 69 6e 74 20 28       ///   int (
10b30 2a 78 53 61 76 65 70 6f 69 6e 74 29 28 73 71 6c  *xSavepoint)(sql
10b40 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62  ite3_vtab *pVtab
10b50 2c 20 69 6e 74 29 3b 0d 0a 20 20 20 20 20 20 20  , int);..       
10b60 20 2f 2f 2f 20 20 20 69 6e 74 20 28 2a 78 52 65   ///   int (*xRe
10b70 6c 65 61 73 65 29 28 73 71 6c 69 74 65 33 5f 76  lease)(sqlite3_v
10b80 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 29  tab *pVtab, int)
10b90 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20  ;..        ///  
10ba0 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b   int (*xRollback
10bb0 54 6f 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  To)(sqlite3_vtab
10bc0 20 2a 70 56 74 61 62 2c 20 69 6e 74 29 3b 0d 0a   *pVtab, int);..
10bd0 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f          /// </co
10be0 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  de></para>..    
10bf0 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a      /// <para>..
10c00 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 73          /// Thes
10c10 65 20 6d 65 74 68 6f 64 73 20 70 72 6f 76 69 64  e methods provid
10c20 65 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  e the virtual ta
10c30 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
10c40 6f 6e 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74  on an opportunit
10c50 79 20 74 6f 0d 0a 20 20 20 20 20 20 20 20 2f 2f  y to..        //
10c60 2f 20 69 6d 70 6c 65 6d 65 6e 74 20 6e 65 73 74  / implement nest
10c70 65 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 2e  ed transactions.
10c80 20 20 54 68 65 79 20 61 72 65 20 61 6c 77 61 79    They are alway
10c90 73 20 6f 70 74 69 6f 6e 61 6c 20 61 6e 64 20 77  s optional and w
10ca0 69 6c 6c 20 6f 6e 6c 79 20 62 65 0d 0a 20 20 20  ill only be..   
10cb0 20 20 20 20 20 2f 2f 2f 20 63 61 6c 6c 65 64 20       /// called 
10cc0 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  in SQLite versio
10cd0 6e 20 33 2e 37 2e 37 20 61 6e 64 20 6c 61 74 65  n 3.7.7 and late
10ce0 72 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  r...        /// 
10cf0 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20  </para>..       
10d00 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20   /// <para>..   
10d10 20 20 20 20 20 2f 2f 2f 20 57 68 65 6e 20 78 53       /// When xS
10d20 61 76 65 70 6f 69 6e 74 28 58 2c 4e 29 20 69 73  avepoint(X,N) is
10d30 20 69 6e 76 6f 6b 65 64 2c 20 74 68 61 74 20 69   invoked, that i
10d40 73 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68  s a signal to th
10d50 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  e virtual table 
10d60 58 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74  X..        /// t
10d70 68 61 74 20 69 74 20 73 68 6f 75 6c 64 20 73 61  hat it should sa
10d80 76 65 20 69 74 73 20 63 75 72 72 65 6e 74 20 73  ve its current s
10d90 74 61 74 65 20 61 73 20 73 61 76 65 70 6f 69 6e  tate as savepoin
10da0 74 20 4e 2e 20 20 0d 0a 20 20 20 20 20 20 20 20  t N.  ..        
10db0 2f 2f 2f 20 41 20 73 75 62 73 65 71 75 65 6e 74  /// A subsequent
10dc0 20 63 61 6c 6c 0d 0a 20 20 20 20 20 20 20 20 2f   call..        /
10dd0 2f 2f 20 74 6f 20 78 52 6f 6c 6c 62 61 63 6b 54  // to xRollbackT
10de0 6f 28 58 2c 52 29 20 6d 65 61 6e 73 20 74 68 61  o(X,R) means tha
10df0 74 20 74 68 65 20 73 74 61 74 65 20 6f 66 20 74  t the state of t
10e00 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
10e10 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 0d 0a   should return..
10e20 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 6f 20 77          /// to w
10e30 68 61 74 20 69 74 20 77 61 73 20 77 68 65 6e 20  hat it was when 
10e40 78 53 61 76 65 70 6f 69 6e 74 28 58 2c 52 29 20  xSavepoint(X,R) 
10e50 77 61 73 20 6c 61 73 74 20 63 61 6c 6c 65 64 2e  was last called.
10e60 20 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20    ..        /// 
10e70 54 68 65 20 63 61 6c 6c 0d 0a 20 20 20 20 20 20  The call..      
10e80 20 20 2f 2f 2f 20 74 6f 20 78 52 6f 6c 6c 62 61    /// to xRollba
10e90 63 6b 54 6f 28 58 2c 52 29 20 77 69 6c 6c 20 69  ckTo(X,R) will i
10ea0 6e 76 61 6c 69 64 61 74 65 20 61 6c 6c 20 73 61  nvalidate all sa
10eb0 76 65 70 6f 69 6e 74 73 20 77 69 74 68 20 4e 3e  vepoints with N>
10ec0 52 3b 20 6e 6f 6e 65 20 6f 66 20 74 68 65 0d 0a  R; none of the..
10ed0 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e 76 61          /// inva
10ee0 6c 69 64 65 64 20 73 61 76 65 70 6f 69 6e 74 73  lided savepoints
10ef0 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20   will be rolled 
10f00 62 61 63 6b 20 6f 72 20 72 65 6c 65 61 73 65 64  back or released
10f10 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 0d 0a   without first..
10f20 20 20 20 20 20 20 20 20 2f 2f 2f 20 62 65 69 6e          /// bein
10f30 67 20 72 65 69 6e 69 74 69 61 6c 69 7a 65 64 20  g reinitialized 
10f40 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 78 53 61  by a call to xSa
10f50 76 65 70 6f 69 6e 74 28 29 2e 20 20 0d 0a 20 20  vepoint().  ..  
10f60 20 20 20 20 20 20 2f 2f 2f 20 41 20 63 61 6c 6c        /// A call
10f70 20 74 6f 20 78 52 65 6c 65 61 73 65 28 58 2c 4d   to xRelease(X,M
10f80 29 20 69 6e 76 61 6c 69 64 61 74 65 73 20 61 6c  ) invalidates al
10f90 6c 20 73 61 76 65 70 6f 69 6e 74 73 20 77 68 65  l savepoints whe
10fa0 72 65 20 4e 3e 3d 4d 2e 0d 0a 20 20 20 20 20 20  re N>=M...      
10fb0 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20    /// </para>.. 
10fc0 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61         /// <para
10fd0 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 4e  >..        /// N
10fe0 6f 6e 65 20 6f 66 20 74 68 65 20 78 53 61 76 65  one of the xSave
10ff0 70 6f 69 6e 74 28 29 2c 20 78 52 65 6c 65 61 73  point(), xReleas
11000 65 28 29 2c 20 6f 72 20 78 52 6f 6c 6c 62 61 63  e(), or xRollbac
11010 6b 54 6f 28 29 20 6d 65 74 68 6f 64 73 20 77 69  kTo() methods wi
11020 6c 6c 20 65 76 65 72 0d 0a 20 20 20 20 20 20 20  ll ever..       
11030 20 2f 2f 2f 20 62 65 20 63 61 6c 6c 65 64 20 65   /// be called e
11040 78 63 65 70 74 20 69 6e 20 62 65 74 77 65 65 6e  xcept in between
11050 20 63 61 6c 6c 73 20 74 6f 20 78 42 65 67 69 6e   calls to xBegin
11060 28 29 20 61 6e 64 20 0d 0a 20 20 20 20 20 20 20  () and ..       
11070 20 2f 2f 2f 20 65 69 74 68 65 72 20 78 43 6f 6d   /// either xCom
11080 6d 69 74 28 29 20 6f 72 20 78 52 6f 6c 6c 62 61  mit() or xRollba
11090 63 6b 28 29 2e 0d 0a 20 20 20 20 20 20 20 20 2f  ck()...        /
110a0 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20  // </para>..    
110b0 20 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72      /// </summar
110c0 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20  y>..        /// 
110d0 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 56 74  <param name="pVt
110e0 61 62 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f  ab">..        //
110f0 2f 20 54 68 65 20 6e 61 74 69 76 65 20 70 6f 69  / The native poi
11100 6e 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  nter to the sqli
11110 74 65 33 5f 76 74 61 62 20 64 65 72 69 76 65 64  te3_vtab derived
11120 20 73 74 72 75 63 74 75 72 65 2e 0d 0a 20 20 20   structure...   
11130 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d       /// </param
11140 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c  >..        /// <
11150 70 61 72 61 6d 20 6e 61 6d 65 3d 22 69 53 61 76  param name="iSav
11160 65 70 6f 69 6e 74 22 3e 0d 0a 20 20 20 20 20 20  epoint">..      
11170 20 20 2f 2f 2f 20 54 68 69 73 20 69 73 20 61 6e    /// This is an
11180 20 69 6e 74 65 67 65 72 20 69 64 65 6e 74 69 66   integer identif
11190 69 65 72 20 75 73 65 64 20 74 6f 20 73 70 65 63  ier used to spec
111a0 69 66 79 20 61 20 73 70 65 63 69 66 69 63 20 73  ify a specific s
111b0 61 76 65 64 0d 0a 20 20 20 20 20 20 20 20 2f 2f  aved..        //
111c0 2f 20 73 74 61 74 65 20 66 6f 72 20 74 68 65 20  / state for the 
111d0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 66 6f  virtual table fo
111e0 72 20 69 74 20 74 6f 20 72 65 73 74 6f 72 65 20  r it to restore 
111f0 69 74 73 65 6c 66 20 62 61 63 6b 20 74 6f 2c 20  itself back to, 
11200 77 68 69 63 68 0d 0a 20 20 20 20 20 20 20 20 2f  which..        /
11210 2f 2f 20 73 68 6f 75 6c 64 20 61 6c 73 6f 20 68  // should also h
11220 61 76 65 20 74 68 65 20 65 66 66 65 63 74 20 6f  ave the effect o
11230 66 20 64 65 6c 65 74 69 6e 67 20 61 6c 6c 20 73  f deleting all s
11240 61 76 65 64 20 73 74 61 74 65 73 20 77 69 74 68  aved states with
11250 20 61 6e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f   an..        ///
11260 20 69 6e 74 65 67 65 72 20 69 64 65 6e 74 69 66   integer identif
11270 69 65 72 20 67 72 65 61 74 65 72 20 74 68 61 6e  ier greater than
11280 20 74 68 69 73 20 6f 6e 65 2e 0d 0a 20 20 20 20   this one...    
11290 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e      /// </param>
112a0 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 72  ..        /// <r
112b0 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20  eturns>..       
112c0 20 2f 2f 2f 20 41 20 73 74 61 6e 64 61 72 64 20   /// A standard 
112d0 53 51 4c 69 74 65 20 72 65 74 75 72 6e 20 63 6f  SQLite return co
112e0 64 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f  de...        ///
112f0 20 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20   </returns>..   
11300 20 20 20 20 20 53 51 4c 69 74 65 45 72 72 6f 72       SQLiteError
11310 43 6f 64 65 20 78 52 6f 6c 6c 62 61 63 6b 54 6f  Code xRollbackTo
11320 28 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 49  (..            I
11330 6e 74 50 74 72 20 70 56 74 61 62 2c 0d 0a 20 20  ntPtr pVtab,..  
11340 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 69 53            int iS
11350 61 76 65 70 6f 69 6e 74 0d 0a 20 20 20 20 20 20  avepoint..      
11360 20 20 20 20 20 20 29 3b 0d 0a 20 20 20 20 7d 0d        );..    }.
11370 0a 20 20 20 20 23 65 6e 64 72 65 67 69 6f 6e 0d  .    #endregion.
11380 0a 7d 0d 0a                                      .}..