0000: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a /***************
0010: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0020: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0030: 2a 2a 2a 2a 2a 2a 2a 2a 2a 0d 0a 20 2a 20 41 44 *********.. * AD
0040: 4f 2e 4e 45 54 20 32 2e 30 20 44 61 74 61 20 50 O.NET 2.0 Data P
0050: 72 6f 76 69 64 65 72 20 66 6f 72 20 53 51 4c 69 rovider for SQLi
0060: 74 65 20 56 65 72 73 69 6f 6e 20 33 2e 58 0d 0a te Version 3.X..
0070: 20 2a 20 57 72 69 74 74 65 6e 20 62 79 20 4a 6f * Written by Jo
0080: 65 20 4d 69 73 74 61 63 68 6b 69 6e 20 28 6a 6f e Mistachkin (jo
0090: 65 40 6d 69 73 74 61 63 68 6b 69 6e 2e 63 6f 6d e@mistachkin.com
00a0: 29 0d 0a 20 2a 0d 0a 20 2a 20 52 65 6c 65 61 73 ).. *.. * Releas
00b0: 65 64 20 74 6f 20 74 68 65 20 70 75 62 6c 69 63 ed to the public
00c0: 20 64 6f 6d 61 69 6e 2c 20 75 73 65 20 61 74 20 domain, use at
00d0: 79 6f 75 72 20 6f 77 6e 20 72 69 73 6b 21 0d 0a your own risk!..
00e0: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ***************
00f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0100: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0110: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0d 0a 0d 0a 6e 61 *********/....na
0120: 6d 65 73 70 61 63 65 20 53 79 73 74 65 6d 2e 44 mespace System.D
0130: 61 74 61 2e 53 51 4c 69 74 65 0d 0a 7b 0d 0a 20 ata.SQLite..{..
0140: 20 20 20 23 72 65 67 69 6f 6e 20 49 53 51 4c 69 #region ISQLi
0150: 74 65 4e 61 74 69 76 65 4d 6f 64 75 6c 65 20 49 teNativeModule I
0160: 6e 74 65 72 66 61 63 65 0d 0a 20 20 20 20 2f 2f nterface.. //
0170: 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 / <summary>..
0180: 20 2f 2f 2f 20 54 68 69 73 20 69 6e 74 65 72 66 /// This interf
0190: 61 63 65 20 72 65 70 72 65 73 65 6e 74 73 20 61 ace represents a
01a0: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 virtual table i
01b0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 72 mplementation wr
01c0: 69 74 74 65 6e 20 69 6e 0d 0a 20 20 20 20 2f 2f itten in.. //
01d0: 2f 20 6e 61 74 69 76 65 20 63 6f 64 65 2e 0d 0a / native code...
01e0: 20 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 /// </summar
01f0: 79 3e 0d 0a 20 20 20 20 70 75 62 6c 69 63 20 69 y>.. public i
0200: 6e 74 65 72 66 61 63 65 20 49 53 51 4c 69 74 65 nterface ISQLite
0210: 4e 61 74 69 76 65 4d 6f 64 75 6c 65 0d 0a 20 20 NativeModule..
0220: 20 20 7b 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f {.. ///
0230: 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 <summary>..
0240: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 /// <para><c
0250: 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ode>.. //
0260: 2f 20 69 6e 74 20 28 2a 78 43 72 65 61 74 65 29 / int (*xCreate)
0270: 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 76 6f (sqlite3 *db, vo
0280: 69 64 20 2a 70 41 75 78 2c 0d 0a 20 20 20 20 20 id *pAux,..
0290: 20 20 20 2f 2f 2f 20 20 20 20 20 20 20 20 20 20 ///
02a0: 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 68 int argc, ch
02b0: 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0d ar *const*argv,.
02c0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 . ///
02d0: 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 sqlite
02e0: 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 3_vtab **ppVTab,
02f0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 .. ///
0300: 20 20 20 20 20 20 20 20 20 20 20 63 68 61 72 20 char
0310: 2a 2a 70 7a 45 72 72 29 3b 0d 0a 20 20 20 20 20 **pzErr);..
0320: 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f /// </code></
0330: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f para>.. /
0340: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 // <para>..
0350: 20 20 20 2f 2f 2f 20 54 68 65 20 78 43 72 65 61 /// The xCrea
0360: 74 65 20 6d 65 74 68 6f 64 20 69 73 20 63 61 6c te method is cal
0370: 6c 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 led to create a
0380: 6e 65 77 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 new instance of
0390: 61 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 a virtual table
03a0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e .. /// in
03b0: 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 43 response to a C
03c0: 52 45 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 REATE VIRTUAL TA
03d0: 42 4c 45 20 73 74 61 74 65 6d 65 6e 74 2e 0d 0a BLE statement...
03e0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 49 66 20 74 /// If t
03f0: 68 65 20 78 43 72 65 61 74 65 20 6d 65 74 68 6f he xCreate metho
0400: 64 20 69 73 20 74 68 65 20 73 61 6d 65 20 70 6f d is the same po
0410: 69 6e 74 65 72 20 61 73 20 74 68 65 20 78 43 6f inter as the xCo
0420: 6e 6e 65 63 74 20 6d 65 74 68 6f 64 2c 20 74 68 nnect method, th
0430: 65 6e 20 74 68 65 0d 0a 20 20 20 20 20 20 20 20 en the..
0440: 2f 2f 2f 20 76 69 72 74 75 61 6c 20 74 61 62 6c /// virtual tabl
0450: 65 20 69 73 20 61 6e 20 65 70 6f 6e 79 6d 6f 75 e is an eponymou
0460: 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e s virtual table.
0470: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 49 66 .. /// If
0480: 20 74 68 65 20 78 43 72 65 61 74 65 20 6d 65 74 the xCreate met
0490: 68 6f 64 20 69 73 20 6f 6d 69 74 74 65 64 20 28 hod is omitted (
04a0: 69 66 20 69 74 20 69 73 20 61 20 4e 55 4c 4c 20 if it is a NULL
04b0: 70 6f 69 6e 74 65 72 29 20 74 68 65 6e 20 74 68 pointer) then th
04c0: 65 20 76 69 72 74 75 61 6c 20 0d 0a 20 20 20 20 e virtual ..
04d0: 20 20 20 20 2f 2f 2f 20 74 61 62 6c 65 20 69 73 /// table is
04e0: 20 61 6e 20 65 70 6f 6e 79 6d 6f 75 73 2d 6f 6e an eponymous-on
04f0: 6c 79 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 ly virtual table
0500: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c ... /// <
0510: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 /para>..
0520: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 /// <para>..
0530: 20 20 20 20 2f 2f 2f 20 54 68 65 20 64 62 20 70 /// The db p
0540: 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f arameter is a po
0550: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c inter to the SQL
0560: 69 74 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e ite database con
0570: 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 0d 0a 20 nection that ..
0580: 20 20 20 20 20 20 20 2f 2f 2f 20 69 73 20 65 78 /// is ex
0590: 65 63 75 74 69 6e 67 20 74 68 65 20 43 52 45 41 ecuting the CREA
05a0: 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 TE VIRTUAL TABLE
05b0: 20 73 74 61 74 65 6d 65 6e 74 2e 20 0d 0a 20 20 statement. ..
05c0: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 70 41 /// The pA
05d0: 75 78 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 ux argument is t
05e0: 68 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 he copy of the c
05f0: 6c 69 65 6e 74 20 64 61 74 61 20 70 6f 69 6e 74 lient data point
0600: 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20 er that was the
0610: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 66 6f .. /// fo
0620: 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f urth argument to
0630: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 the sqlite3_cre
0640: 61 74 65 5f 6d 6f 64 75 6c 65 28 29 20 6f 72 0d ate_module() or.
0650: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 71 6c . /// sql
0660: 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 ite3_create_modu
0670: 6c 65 5f 76 32 28 29 20 63 61 6c 6c 20 74 68 61 le_v2() call tha
0680: 74 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 t registered the
0690: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 76 .. /// v
06a0: 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 irtual table mod
06b0: 75 6c 65 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f ule. .. /
06c0: 2f 2f 20 54 68 65 20 61 72 67 76 20 70 61 72 61 // The argv para
06d0: 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 72 61 meter is an arra
06e0: 79 20 6f 66 20 61 72 67 63 20 70 6f 69 6e 74 65 y of argc pointe
06f0: 72 73 20 74 6f 20 6e 75 6c 6c 20 74 65 72 6d 69 rs to null termi
0700: 6e 61 74 65 64 20 73 74 72 69 6e 67 73 2e 20 0d nated strings. .
0710: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 . /// The
0720: 20 66 69 72 73 74 20 73 74 72 69 6e 67 2c 20 61 first string, a
0730: 72 67 76 5b 30 5d 2c 20 69 73 20 74 68 65 20 6e rgv[0], is the n
0740: 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c ame of the modul
0750: 65 20 62 65 69 6e 67 20 69 6e 76 6f 6b 65 64 2e e being invoked.
0760: 20 20 20 54 68 65 0d 0a 20 20 20 20 20 20 20 20 The..
0770: 2f 2f 2f 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 /// module name
0780: 69 73 20 74 68 65 20 6e 61 6d 65 20 70 72 6f 76 is the name prov
0790: 69 64 65 64 20 61 73 20 74 68 65 20 73 65 63 6f ided as the seco
07a0: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 0d nd argument to .
07b0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 71 6c . /// sql
07c0: 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 ite3_create_modu
07d0: 6c 65 28 29 20 61 6e 64 20 61 73 20 74 68 65 20 le() and as the
07e0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
07f0: 55 53 49 4e 47 20 63 6c 61 75 73 65 20 6f 66 20 USING clause of
0800: 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f the.. ///
0810: 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20 CREATE VIRTUAL
0820: 54 41 42 4c 45 20 73 74 61 74 65 6d 65 6e 74 20 TABLE statement
0830: 74 68 61 74 20 69 73 20 72 75 6e 6e 69 6e 67 2e that is running.
0840: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 .. /// Th
0850: 65 20 73 65 63 6f 6e 64 2c 20 61 72 67 76 5b 31 e second, argv[1
0860: 5d 2c 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f ], is the name o
0870: 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 f the database i
0880: 6e 20 77 68 69 63 68 20 74 68 65 20 6e 65 77 20 n which the new
0890: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 73 virtual table is
08a0: 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 2e 20 being created.
08b0: 54 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d The database nam
08c0: 65 20 69 73 20 22 6d 61 69 6e 22 20 66 6f 72 20 e is "main" for
08d0: 74 68 65 20 70 72 69 6d 61 72 79 20 64 61 74 61 the primary data
08e0: 62 61 73 65 2c 20 6f 72 0d 0a 20 20 20 20 20 20 base, or..
08f0: 20 20 2f 2f 2f 20 22 74 65 6d 70 22 20 66 6f 72 /// "temp" for
0900: 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 2c 20 TEMP database,
0910: 6f 72 20 74 68 65 20 6e 61 6d 65 20 67 69 76 65 or the name give
0920: 6e 20 61 74 20 74 68 65 20 65 6e 64 20 6f 66 20 n at the end of
0930: 74 68 65 20 41 54 54 41 43 48 0d 0a 20 20 20 20 the ATTACH..
0940: 20 20 20 20 2f 2f 2f 20 73 74 61 74 65 6d 65 6e /// statemen
0950: 74 20 66 6f 72 20 61 74 74 61 63 68 65 64 20 64 t for attached d
0960: 61 74 61 62 61 73 65 73 2e 20 20 54 68 65 20 74 atabases. The t
0970: 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 hird element of
0980: 74 68 65 20 61 72 72 61 79 2c 20 61 72 67 76 5b the array, argv[
0990: 32 5d 2c 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2], .. //
09a0: 2f 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 / is the name of
09b0: 20 74 68 65 20 6e 65 77 20 76 69 72 74 75 61 6c the new virtual
09c0: 20 74 61 62 6c 65 2c 20 61 73 20 73 70 65 63 69 table, as speci
09d0: 66 69 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 fied following t
09e0: 68 65 20 54 41 42 4c 45 0d 0a 20 20 20 20 20 20 he TABLE..
09f0: 20 20 2f 2f 2f 20 6b 65 79 77 6f 72 64 20 69 6e /// keyword in
0a00: 20 74 68 65 20 43 52 45 41 54 45 20 56 49 52 54 the CREATE VIRT
0a10: 55 41 4c 20 54 41 42 4c 45 20 73 74 61 74 65 6d UAL TABLE statem
0a20: 65 6e 74 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ent... //
0a30: 2f 20 49 66 20 70 72 65 73 65 6e 74 2c 20 74 68 / If present, th
0a40: 65 20 66 6f 75 72 74 68 20 61 6e 64 20 73 75 62 e fourth and sub
0a50: 73 65 71 75 65 6e 74 20 73 74 72 69 6e 67 73 20 sequent strings
0a60: 69 6e 20 74 68 65 20 61 72 67 76 5b 5d 20 61 72 in the argv[] ar
0a70: 72 61 79 20 72 65 70 6f 72 74 20 0d 0a 20 20 20 ray report ..
0a80: 20 20 20 20 20 2f 2f 2f 20 74 68 65 20 61 72 67 /// the arg
0a90: 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 6d 6f uments to the mo
0aa0: 64 75 6c 65 20 6e 61 6d 65 20 69 6e 20 74 68 65 dule name in the
0ab0: 20 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20 CREATE VIRTUAL
0ac0: 54 41 42 4c 45 20 73 74 61 74 65 6d 65 6e 74 2e TABLE statement.
0ad0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f .. /// </
0ae0: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f para>.. /
0af0: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 // <para>..
0b00: 20 20 20 2f 2f 2f 20 54 68 65 20 6a 6f 62 20 6f /// The job o
0b10: 66 20 74 68 69 73 20 6d 65 74 68 6f 64 20 69 73 f this method is
0b20: 20 74 6f 20 63 6f 6e 73 74 72 75 63 74 20 74 68 to construct th
0b30: 65 20 6e 65 77 20 76 69 72 74 75 61 6c 20 74 61 e new virtual ta
0b40: 62 6c 65 20 6f 62 6a 65 63 74 0d 0a 20 20 20 20 ble object..
0b50: 20 20 20 20 2f 2f 2f 20 28 61 6e 20 73 71 6c 69 /// (an sqli
0b60: 74 65 33 5f 76 74 61 62 20 6f 62 6a 65 63 74 29 te3_vtab object)
0b70: 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f and return a po
0b80: 69 6e 74 65 72 20 74 6f 20 69 74 20 69 6e 20 2a inter to it in *
0b90: 70 70 56 54 61 62 2e 0d 0a 20 20 20 20 20 20 20 ppVTab...
0ba0: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 /// </para>..
0bb0: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e /// <para>
0bc0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 73 .. /// As
0bd0: 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 61 73 part of the tas
0be0: 6b 20 6f 66 20 63 72 65 61 74 69 6e 67 20 61 20 k of creating a
0bf0: 6e 65 77 20 73 71 6c 69 74 65 33 5f 76 74 61 62 new sqlite3_vtab
0c00: 20 73 74 72 75 63 74 75 72 65 2c 20 74 68 69 73 structure, this
0c10: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6d .. /// m
0c20: 65 74 68 6f 64 20 3c 75 3e 6d 75 73 74 3c 2f 75 ethod <u>must</u
0c30: 3e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 > invoke sqlite3
0c40: 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 29 20 _declare_vtab()
0c50: 74 6f 20 74 65 6c 6c 20 74 68 65 20 53 51 4c 69 to tell the SQLi
0c60: 74 65 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f te .. ///
0c70: 20 63 6f 72 65 20 61 62 6f 75 74 20 74 68 65 20 core about the
0c80: 63 6f 6c 75 6d 6e 73 20 61 6e 64 20 64 61 74 61 columns and data
0c90: 74 79 70 65 73 20 69 6e 20 74 68 65 20 76 69 72 types in the vir
0ca0: 74 75 61 6c 20 74 61 62 6c 65 2e 20 0d 0a 20 20 tual table. ..
0cb0: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 73 71 /// The sq
0cc0: 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 lite3_declare_vt
0cd0: 61 62 28 29 20 41 50 49 20 68 61 73 20 74 68 65 ab() API has the
0ce0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 74 6f following proto
0cf0: 74 79 70 65 3a 0d 0a 20 20 20 20 20 20 20 20 2f type:.. /
0d00: 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 // </para>..
0d10: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 /// <para><c
0d20: 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ode>.. //
0d30: 2f 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 65 / int sqlite3_de
0d40: 63 6c 61 72 65 5f 76 74 61 62 28 73 71 6c 69 74 clare_vtab(sqlit
0d50: 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68 e3 *db, const ch
0d60: 61 72 20 2a 7a 43 72 65 61 74 65 54 61 62 6c 65 ar *zCreateTable
0d70: 29 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c ).. /// <
0d80: 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 /code></para>..
0d90: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 /// <para
0da0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 >.. /// T
0db0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
0dc0: 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 65 63 t to sqlite3_dec
0dd0: 6c 61 72 65 5f 76 74 61 62 28 29 20 6d 75 73 74 lare_vtab() must
0de0: 20 62 65 20 74 68 65 20 73 61 6d 65 20 0d 0a 20 be the same ..
0df0: 20 20 20 20 20 20 20 2f 2f 2f 20 64 61 74 61 62 /// datab
0e00: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 ase connection p
0e10: 6f 69 6e 74 65 72 20 61 73 20 74 68 65 20 66 69 ointer as the fi
0e20: 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f rst parameter to
0e30: 20 74 68 69 73 20 6d 65 74 68 6f 64 2e 0d 0a 20 this method...
0e40: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 73 /// The s
0e50: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 econd argument t
0e60: 6f 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 o sqlite3_declar
0e70: 65 5f 76 74 61 62 28 29 20 6d 75 73 74 20 61 20 e_vtab() must a
0e80: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
0e90: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 55 54 .. /// UT
0ea0: 46 2d 38 20 73 74 72 69 6e 67 20 74 68 61 74 20 F-8 string that
0eb0: 63 6f 6e 74 61 69 6e 73 20 61 20 77 65 6c 6c 2d contains a well-
0ec0: 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 41 formed CREATE TA
0ed0: 42 4c 45 20 73 74 61 74 65 6d 65 6e 74 20 74 68 BLE statement th
0ee0: 61 74 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f at .. ///
0ef0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 63 6f 6c defines the col
0f00: 75 6d 6e 73 20 69 6e 20 74 68 65 20 76 69 72 74 umns in the virt
0f10: 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 74 68 ual table and th
0f20: 65 69 72 20 64 61 74 61 20 74 79 70 65 73 2e 20 eir data types.
0f30: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 .. /// Th
0f40: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 e name of the ta
0f50: 62 6c 65 20 69 6e 20 74 68 69 73 20 43 52 45 41 ble in this CREA
0f60: 54 45 20 54 41 42 4c 45 20 73 74 61 74 65 6d 65 TE TABLE stateme
0f70: 6e 74 20 69 73 20 69 67 6e 6f 72 65 64 2c 20 0d nt is ignored, .
0f80: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 61 73 20 . /// as
0f90: 61 72 65 20 61 6c 6c 20 63 6f 6e 73 74 72 61 69 are all constrai
0fa0: 6e 74 73 2e 20 4f 6e 6c 79 20 74 68 65 20 63 6f nts. Only the co
0fb0: 6c 75 6d 6e 20 6e 61 6d 65 73 20 61 6e 64 20 64 lumn names and d
0fc0: 61 74 61 74 79 70 65 73 20 6d 61 74 74 65 72 2e atatypes matter.
0fd0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 .. /// Th
0fe0: 65 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 73 e CREATE TABLE s
0ff0: 74 61 74 65 6d 65 6e 74 20 73 74 72 69 6e 67 20 tatement string
1000: 6e 65 65 64 20 6e 6f 74 20 74 6f 20 62 65 20 0d need not to be .
1010: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 68 65 6c . /// hel
1020: 64 20 69 6e 20 70 65 72 73 69 73 74 65 6e 74 20 d in persistent
1030: 6d 65 6d 6f 72 79 2e 20 20 54 68 65 20 73 74 72 memory. The str
1040: 69 6e 67 20 63 61 6e 20 62 65 0d 0a 20 20 20 20 ing can be..
1050: 20 20 20 20 2f 2f 2f 20 64 65 61 6c 6c 6f 63 61 /// dealloca
1060: 74 65 64 20 61 6e 64 2f 6f 72 20 72 65 75 73 65 ted and/or reuse
1070: 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 d as soon as the
1080: 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 sqlite3_declare
1090: 5f 76 74 61 62 28 29 0d 0a 20 20 20 20 20 20 20 _vtab()..
10a0: 20 2f 2f 2f 20 72 6f 75 74 69 6e 65 20 72 65 74 /// routine ret
10b0: 75 72 6e 73 2e 0d 0a 20 20 20 20 20 20 20 20 2f urns... /
10c0: 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 // </para>..
10d0: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a /// <para>..
10e0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 /// The
10f0: 78 43 72 65 61 74 65 20 6d 65 74 68 6f 64 20 6e xCreate method n
1100: 65 65 64 20 6e 6f 74 20 69 6e 69 74 69 61 6c 69 eed not initiali
1110: 7a 65 20 74 68 65 20 70 4d 6f 64 75 6c 65 2c 20 ze the pModule,
1120: 6e 52 65 66 2c 20 61 6e 64 20 7a 45 72 72 4d 73 nRef, and zErrMs
1130: 67 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 66 g.. /// f
1140: 69 65 6c 64 73 20 6f 66 20 74 68 65 20 73 71 6c ields of the sql
1150: 69 74 65 33 5f 76 74 61 62 20 6f 62 6a 65 63 74 ite3_vtab object
1160: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f . The SQLite co
1170: 72 65 20 77 69 6c 6c 20 74 61 6b 65 20 63 61 72 re will take car
1180: 65 20 6f 66 20 0d 0a 20 20 20 20 20 20 20 20 2f e of .. /
1190: 2f 2f 20 74 68 61 74 20 63 68 6f 72 65 2e 0d 0a // that chore...
11a0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 /// </pa
11b0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ra>.. ///
11c0: 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 <para>..
11d0: 20 2f 2f 2f 20 54 68 65 20 78 43 72 65 61 74 65 /// The xCreate
11e0: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 should return S
11f0: 51 4c 49 54 45 5f 4f 4b 20 69 66 20 69 74 20 69 QLITE_OK if it i
1200: 73 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 20 s successful in
1210: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 63 72 .. /// cr
1220: 65 61 74 69 6e 67 20 74 68 65 20 6e 65 77 20 76 eating the new v
1230: 69 72 74 75 61 6c 20 74 61 62 6c 65 2c 20 6f 72 irtual table, or
1240: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 69 66 SQLITE_ERROR if
1250: 20 69 74 20 69 73 20 6e 6f 74 20 73 75 63 63 65 it is not succe
1260: 73 73 66 75 6c 2e 0d 0a 20 20 20 20 20 20 20 20 ssful...
1270: 2f 2f 2f 20 49 66 20 6e 6f 74 20 73 75 63 63 65 /// If not succe
1280: 73 73 66 75 6c 2c 20 74 68 65 20 73 71 6c 69 74 ssful, the sqlit
1290: 65 33 5f 76 74 61 62 20 73 74 72 75 63 74 75 72 e3_vtab structur
12a0: 65 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 6c e must not be al
12b0: 6c 6f 63 61 74 65 64 2e 20 0d 0a 20 20 20 20 20 located. ..
12c0: 20 20 20 2f 2f 2f 20 41 6e 20 65 72 72 6f 72 20 /// An error
12d0: 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 70 74 69 message may opti
12e0: 6f 6e 61 6c 6c 79 20 62 65 20 72 65 74 75 72 6e onally be return
12f0: 65 64 20 69 6e 20 2a 70 7a 45 72 72 20 69 66 20 ed in *pzErr if
1300: 75 6e 73 75 63 63 65 73 73 66 75 6c 2e 0d 0a 20 unsuccessful...
1310: 20 20 20 20 20 20 20 2f 2f 2f 20 53 70 61 63 65 /// Space
1320: 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 to hold the err
1330: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e or message strin
1340: 67 20 6d 75 73 74 20 62 65 20 61 6c 6c 6f 63 61 g must be alloca
1350: 74 65 64 20 75 73 69 6e 67 0d 0a 20 20 20 20 20 ted using..
1360: 20 20 20 2f 2f 2f 20 61 6e 20 53 51 4c 69 74 65 /// an SQLite
1370: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
1380: 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 6c 69 6b 65 on function like
1390: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 .. /// s
13a0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
13b0: 6f 72 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e or sqlite3_mprin
13c0: 74 66 28 29 20 61 73 20 74 68 65 20 53 51 4c 69 tf() as the SQLi
13d0: 74 65 20 63 6f 72 65 20 77 69 6c 6c 0d 0a 20 20 te core will..
13e0: 20 20 20 20 20 20 2f 2f 2f 20 61 74 74 65 6d 70 /// attemp
13f0: 74 20 74 6f 20 66 72 65 65 20 74 68 65 20 73 70 t to free the sp
1400: 61 63 65 20 75 73 69 6e 67 20 73 71 6c 69 74 65 ace using sqlite
1410: 33 5f 66 72 65 65 28 29 20 61 66 74 65 72 20 74 3_free() after t
1420: 68 65 20 65 72 72 6f 72 20 68 61 73 0d 0a 20 20 he error has..
1430: 20 20 20 20 20 20 2f 2f 2f 20 62 65 65 6e 20 72 /// been r
1440: 65 70 6f 72 74 65 64 20 75 70 20 74 6f 20 74 68 eported up to th
1450: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0d 0a e application...
1460: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 /// </pa
1470: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ra>.. ///
1480: 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 <para>..
1490: 20 2f 2f 2f 20 49 66 20 74 68 65 20 78 43 72 65 /// If the xCre
14a0: 61 74 65 20 6d 65 74 68 6f 64 20 69 73 20 6f 6d ate method is om
14b0: 69 74 74 65 64 20 28 6c 65 66 74 20 61 73 20 61 itted (left as a
14c0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 29 20 74 NULL pointer) t
14d0: 68 65 6e 20 74 68 65 0d 0a 20 20 20 20 20 20 20 hen the..
14e0: 20 2f 2f 2f 20 76 69 72 74 75 61 6c 20 74 61 62 /// virtual tab
14f0: 6c 65 20 69 73 20 61 6e 20 65 70 6f 6e 79 6d 6f le is an eponymo
1500: 75 73 2d 6f 6e 6c 79 20 76 69 72 74 75 61 6c 20 us-only virtual
1510: 74 61 62 6c 65 2e 20 20 4e 65 77 20 69 6e 73 74 table. New inst
1520: 61 6e 63 65 73 20 6f 66 0d 0a 20 20 20 20 20 20 ances of..
1530: 20 20 2f 2f 2f 20 74 68 65 20 76 69 72 74 75 61 /// the virtua
1540: 6c 20 74 61 62 6c 65 20 63 61 6e 6e 6f 74 20 62 l table cannot b
1550: 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 e created using
1560: 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20 54 CREATE VIRTUAL T
1570: 41 42 4c 45 20 61 6e 64 20 74 68 65 0d 0a 20 20 ABLE and the..
1580: 20 20 20 20 20 20 2f 2f 2f 20 76 69 72 74 75 61 /// virtua
1590: 6c 20 74 61 62 6c 65 20 63 61 6e 20 6f 6e 6c 79 l table can only
15a0: 20 62 65 20 75 73 65 64 20 76 69 61 20 69 74 73 be used via its
15b0: 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 2e 0d 0a 20 module name...
15c0: 20 20 20 20 20 20 20 2f 2f 2f 20 4e 6f 74 65 20 /// Note
15d0: 74 68 61 74 20 53 51 4c 69 74 65 20 76 65 72 73 that SQLite vers
15e0: 69 6f 6e 73 20 70 72 69 6f 72 20 74 6f 20 33 2e ions prior to 3.
15f0: 39 2e 30 20 28 32 30 31 35 2d 31 30 2d 31 34 29 9.0 (2015-10-14)
1600: 20 64 6f 20 6e 6f 74 20 75 6e 64 65 72 73 74 61 do not understa
1610: 6e 64 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 nd.. ///
1620: 65 70 6f 6e 79 6d 6f 75 73 2d 6f 6e 6c 79 20 76 eponymous-only v
1630: 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 61 6e irtual tables an
1640: 64 20 77 69 6c 6c 20 73 65 67 66 61 75 6c 74 20 d will segfault
1650: 69 66 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 if an attempt is
1660: 20 6d 61 64 65 0d 0a 20 20 20 20 20 20 20 20 2f made.. /
1670: 2f 2f 20 74 6f 20 43 52 45 41 54 45 20 56 49 52 // to CREATE VIR
1680: 54 55 41 4c 20 54 41 42 4c 45 20 6f 6e 20 61 6e TUAL TABLE on an
1690: 20 65 70 6f 6e 79 6d 6f 75 73 2d 6f 6e 6c 79 20 eponymous-only
16a0: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 62 65 virtual table be
16b0: 63 61 75 73 65 0d 0a 20 20 20 20 20 20 20 20 2f cause.. /
16c0: 2f 2f 20 74 68 65 20 78 43 72 65 61 74 65 20 6d // the xCreate m
16d0: 65 74 68 6f 64 20 77 61 73 20 6e 6f 74 20 63 68 ethod was not ch
16e0: 65 63 6b 65 64 20 66 6f 72 20 6e 75 6c 6c 2e 0d ecked for null..
16f0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 . /// </p
1700: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ara>.. //
1710: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 / <para>..
1720: 20 20 2f 2f 2f 20 49 66 20 74 68 65 20 78 43 72 /// If the xCr
1730: 65 61 74 65 20 6d 65 74 68 6f 64 20 69 73 20 74 eate method is t
1740: 68 65 20 65 78 61 63 74 20 73 61 6d 65 20 70 6f he exact same po
1750: 69 6e 74 65 72 20 61 73 20 74 68 65 20 78 43 6f inter as the xCo
1760: 6e 6e 65 63 74 20 6d 65 74 68 6f 64 2c 0d 0a 20 nnect method,..
1770: 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 61 74 20 /// that
1780: 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 indicates that t
1790: 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 he virtual table
17a0: 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 does not need t
17b0: 6f 20 69 6e 69 74 69 61 6c 69 7a 65 20 62 61 63 o initialize bac
17c0: 6b 69 6e 67 0d 0a 20 20 20 20 20 20 20 20 2f 2f king.. //
17d0: 2f 20 73 74 6f 72 65 2e 20 20 53 75 63 68 20 61 / store. Such a
17e0: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 63 virtual table c
17f0: 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 61 6e an be used as an
1800: 20 65 70 6f 6e 79 6d 6f 75 73 20 76 69 72 74 75 eponymous virtu
1810: 61 6c 20 74 61 62 6c 65 0d 0a 20 20 20 20 20 20 al table..
1820: 20 20 2f 2f 2f 20 6f 72 20 61 73 20 61 20 6e 61 /// or as a na
1830: 6d 65 64 20 76 69 72 74 75 61 6c 20 74 61 62 6c med virtual tabl
1840: 65 20 75 73 69 6e 67 20 43 52 45 41 54 45 20 56 e using CREATE V
1850: 49 52 54 55 41 4c 20 54 41 42 4c 45 20 6f 72 20 IRTUAL TABLE or
1860: 62 6f 74 68 2e 0d 0a 20 20 20 20 20 20 20 20 2f both... /
1870: 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 // </para>..
1880: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a /// <para>..
1890: 20 20 20 20 20 20 20 20 2f 2f 2f 20 49 66 20 61 /// If a
18a0: 20 63 6f 6c 75 6d 6e 20 64 61 74 61 74 79 70 65 column datatype
18b0: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 73 70 contains the sp
18c0: 65 63 69 61 6c 20 6b 65 79 77 6f 72 64 20 22 48 ecial keyword "H
18d0: 49 44 44 45 4e 22 0d 0a 20 20 20 20 20 20 20 20 IDDEN"..
18e0: 2f 2f 2f 20 28 69 6e 20 61 6e 79 20 63 6f 6d 62 /// (in any comb
18f0: 69 6e 61 74 69 6f 6e 20 6f 66 20 75 70 70 65 72 ination of upper
1900: 20 61 6e 64 20 6c 6f 77 65 72 20 63 61 73 65 20 and lower case
1910: 6c 65 74 74 65 72 73 29 20 74 68 65 6e 20 74 68 letters) then th
1920: 61 74 20 6b 65 79 77 6f 72 64 0d 0a 20 20 20 20 at keyword..
1930: 20 20 20 20 2f 2f 2f 20 69 74 20 69 73 20 6f 6d /// it is om
1940: 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 63 itted from the c
1950: 6f 6c 75 6d 6e 20 64 61 74 61 74 79 70 65 20 6e olumn datatype n
1960: 61 6d 65 20 61 6e 64 20 74 68 65 20 63 6f 6c 75 ame and the colu
1970: 6d 6e 20 69 73 20 6d 61 72 6b 65 64 20 0d 0a 20 mn is marked ..
1980: 20 20 20 20 20 20 20 2f 2f 2f 20 61 73 20 61 20 /// as a
1990: 68 69 64 64 65 6e 20 63 6f 6c 75 6d 6e 20 69 6e hidden column in
19a0: 74 65 72 6e 61 6c 6c 79 2e 20 0d 0a 20 20 20 20 ternally. ..
19b0: 20 20 20 20 2f 2f 2f 20 41 20 68 69 64 64 65 6e /// A hidden
19c0: 20 63 6f 6c 75 6d 6e 20 64 69 66 66 65 72 73 20 column differs
19d0: 66 72 6f 6d 20 61 20 6e 6f 72 6d 61 6c 20 63 6f from a normal co
19e0: 6c 75 6d 6e 20 69 6e 20 74 68 72 65 65 20 72 65 lumn in three re
19f0: 73 70 65 63 74 73 3a 0d 0a 20 20 20 20 20 20 20 spects:..
1a00: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 /// </para>..
1a10: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e /// <para>
1a20: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 21 .. /// <!
1a30: 5b 43 44 41 54 41 5b 3c 75 6c 3e 5d 5d 3e 0d 0a [CDATA[<ul>]]>..
1a40: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 21 5b 43 /// <![C
1a50: 44 41 54 41 5b 3c 6c 69 3e 5d 5d 3e 20 48 69 64 DATA[<li>]]> Hid
1a60: 64 65 6e 20 63 6f 6c 75 6d 6e 73 20 61 72 65 20 den columns are
1a70: 6e 6f 74 20 6c 69 73 74 65 64 20 69 6e 20 74 68 not listed in th
1a80: 65 20 64 61 74 61 73 65 74 20 72 65 74 75 72 6e e dataset return
1a90: 65 64 20 62 79 20 0d 0a 20 20 20 20 20 20 20 20 ed by ..
1aa0: 2f 2f 2f 20 20 20 20 20 20 22 50 52 41 47 4d 41 /// "PRAGMA
1ab0: 20 74 61 62 6c 65 5f 69 6e 66 6f 22 2c 0d 0a 20 table_info",..
1ac0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 21 5b 43 44 /// <![CD
1ad0: 41 54 41 5b 3c 2f 6c 69 3e 5d 5d 3e 3c 21 5b 43 ATA[</li>]]><![C
1ae0: 44 41 54 41 5b 3c 6c 69 3e 5d 5d 3e 20 48 69 64 DATA[<li>]]> Hid
1af0: 64 65 6e 20 63 6f 6c 75 6d 6e 73 20 61 72 65 20 den columns are
1b00: 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 not included in
1b10: 74 68 65 20 65 78 70 61 6e 73 69 6f 6e 20 6f 66 the expansion of
1b20: 20 61 20 22 2a 22 0d 0a 20 20 20 20 20 20 20 20 a "*"..
1b30: 2f 2f 2f 20 20 20 20 20 20 65 78 70 72 65 73 73 /// express
1b40: 69 6f 6e 20 69 6e 20 74 68 65 20 72 65 73 75 6c ion in the resul
1b50: 74 20 73 65 74 20 6f 66 20 61 20 53 45 4c 45 43 t set of a SELEC
1b60: 54 2c 20 61 6e 64 0d 0a 20 20 20 20 20 20 20 20 T, and..
1b70: 2f 2f 2f 20 3c 21 5b 43 44 41 54 41 5b 3c 2f 6c /// <![CDATA[</l
1b80: 69 3e 5d 5d 3e 3c 21 5b 43 44 41 54 41 5b 3c 6c i>]]><![CDATA[<l
1b90: 69 3e 5d 5d 3e 20 48 69 64 64 65 6e 20 63 6f 6c i>]]> Hidden col
1ba0: 75 6d 6e 73 20 61 72 65 20 6e 6f 74 20 69 6e 63 umns are not inc
1bb0: 6c 75 64 65 64 20 69 6e 20 74 68 65 20 69 6d 70 luded in the imp
1bc0: 6c 69 63 69 74 20 63 6f 6c 75 6d 6e 2d 6c 69 73 licit column-lis
1bd0: 74 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 t .. ///
1be0: 20 20 20 20 20 75 73 65 64 20 62 79 20 61 6e 20 used by an
1bf0: 49 4e 53 45 52 54 20 73 74 61 74 65 6d 65 6e 74 INSERT statement
1c00: 20 74 68 61 74 20 6c 61 63 6b 73 20 61 6e 20 65 that lacks an e
1c10: 78 70 6c 69 63 69 74 20 63 6f 6c 75 6d 6e 2d 6c xplicit column-l
1c20: 69 73 74 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f ist. .. /
1c30: 2f 2f 20 3c 21 5b 43 44 41 54 41 5b 3c 2f 6c 69 // <![CDATA[</li
1c40: 3e 5d 5d 3e 3c 21 5b 43 44 41 54 41 5b 3c 2f 75 >]]><![CDATA[</u
1c50: 6c 3e 5d 5d 3e 0d 0a 20 20 20 20 20 20 20 20 2f l>]]>.. /
1c60: 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 // </para>..
1c70: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a /// <para>..
1c80: 20 20 20 20 20 20 20 20 2f 2f 2f 20 46 6f 72 20 /// For
1c90: 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 example, if the
1ca0: 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 69 73 following SQL is
1cb0: 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 passed to sqlit
1cc0: 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 e3_declare_vtab(
1cd0: 29 3a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 ):.. ///
1ce0: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 </para>..
1cf0: 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 /// <para><code
1d00: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 43 >.. /// C
1d10: 52 45 41 54 45 20 54 41 42 4c 45 20 78 28 61 20 REATE TABLE x(a
1d20: 48 49 44 44 45 4e 20 56 41 52 43 48 41 52 28 31 HIDDEN VARCHAR(1
1d30: 32 29 2c 20 62 20 49 4e 54 45 47 45 52 2c 20 63 2), b INTEGER, c
1d40: 20 49 4e 54 45 47 45 52 20 48 69 64 64 65 6e 29 INTEGER Hidden)
1d50: 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c ;.. /// <
1d60: 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 /code></para>..
1d70: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 /// <para
1d80: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 >.. /// T
1d90: 68 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 20 hen the virtual
1da0: 74 61 62 6c 65 20 77 6f 75 6c 64 20 62 65 20 63 table would be c
1db0: 72 65 61 74 65 64 20 77 69 74 68 20 74 77 6f 20 reated with two
1dc0: 68 69 64 64 65 6e 20 63 6f 6c 75 6d 6e 73 2c 0d hidden columns,.
1dd0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 61 6e 64 . /// and
1de0: 20 77 69 74 68 20 64 61 74 61 74 79 70 65 73 20 with datatypes
1df0: 6f 66 20 22 56 41 52 43 48 41 52 28 31 32 29 22 of "VARCHAR(12)"
1e00: 20 61 6e 64 20 22 49 4e 54 45 47 45 52 22 2e 0d and "INTEGER"..
1e10: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 . /// </p
1e20: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ara>.. //
1e30: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 / <para>..
1e40: 20 20 2f 2f 2f 20 41 6e 20 65 78 61 6d 70 6c 65 /// An example
1e50: 20 75 73 65 20 6f 66 20 68 69 64 64 65 6e 20 63 use of hidden c
1e60: 6f 6c 75 6d 6e 73 20 63 61 6e 20 62 65 20 73 65 olumns can be se
1e70: 65 6e 20 69 6e 20 74 68 65 20 46 54 53 33 20 76 en in the FTS3 v
1e80: 69 72 74 75 61 6c 20 0d 0a 20 20 20 20 20 20 20 irtual ..
1e90: 20 2f 2f 2f 20 74 61 62 6c 65 20 69 6d 70 6c 65 /// table imple
1ea0: 6d 65 6e 74 61 74 69 6f 6e 2c 20 77 68 65 72 65 mentation, where
1eb0: 20 65 76 65 72 79 20 46 54 53 20 76 69 72 74 75 every FTS virtu
1ec0: 61 6c 20 74 61 62 6c 65 0d 0a 20 20 20 20 20 20 al table..
1ed0: 20 20 2f 2f 2f 20 63 6f 6e 74 61 69 6e 73 20 61 /// contains a
1ee0: 6e 20 46 54 53 20 68 69 64 64 65 6e 20 63 6f 6c n FTS hidden col
1ef0: 75 6d 6e 20 74 68 61 74 20 69 73 20 75 73 65 64 umn that is used
1f00: 20 74 6f 20 70 61 73 73 20 69 6e 66 6f 72 6d 61 to pass informa
1f10: 74 69 6f 6e 20 66 72 6f 6d 20 74 68 65 0d 0a 20 tion from the..
1f20: 20 20 20 20 20 20 20 2f 2f 2f 20 76 69 72 74 75 /// virtu
1f30: 61 6c 20 74 61 62 6c 65 20 69 6e 74 6f 20 46 54 al table into FT
1f40: 53 20 61 75 78 69 6c 69 61 72 79 20 66 75 6e 63 S auxiliary func
1f50: 74 69 6f 6e 73 20 61 6e 64 20 74 6f 20 74 68 65 tions and to the
1f60: 20 46 54 53 20 4d 41 54 43 48 20 6f 70 65 72 61 FTS MATCH opera
1f70: 74 6f 72 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f tor... //
1f80: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 / </para>..
1f90: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 /// <para>..
1fa0: 20 20 20 20 20 20 20 2f 2f 2f 20 41 20 76 69 72 /// A vir
1fb0: 74 75 61 6c 20 74 61 62 6c 65 20 74 68 61 74 20 tual table that
1fc0: 63 6f 6e 74 61 69 6e 73 20 68 69 64 64 65 6e 20 contains hidden
1fd0: 63 6f 6c 75 6d 6e 73 20 63 61 6e 20 62 65 20 75 columns can be u
1fe0: 73 65 64 20 6c 69 6b 65 0d 0a 20 20 20 20 20 20 sed like..
1ff0: 20 20 2f 2f 2f 20 61 20 74 61 62 6c 65 2d 76 61 /// a table-va
2000: 6c 75 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 6e lued function in
2010: 20 74 68 65 20 46 52 4f 4d 20 63 6c 61 75 73 65 the FROM clause
2020: 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74 61 of a SELECT sta
2030: 74 65 6d 65 6e 74 2e 0d 0a 20 20 20 20 20 20 20 tement...
2040: 20 2f 2f 2f 20 54 68 65 20 61 72 67 75 6d 65 6e /// The argumen
2050: 74 73 20 74 6f 20 74 68 65 20 74 61 62 6c 65 2d ts to the table-
2060: 76 61 6c 75 65 64 20 66 75 6e 63 74 69 6f 6e 20 valued function
2070: 62 65 63 6f 6d 65 20 63 6f 6e 73 74 72 61 69 6e become constrain
2080: 74 73 20 6f 6e 20 0d 0a 20 20 20 20 20 20 20 20 ts on ..
2090: 2f 2f 2f 20 74 68 65 20 48 49 44 44 45 4e 20 63 /// the HIDDEN c
20a0: 6f 6c 75 6d 6e 73 20 6f 66 20 74 68 65 20 76 69 olumns of the vi
20b0: 72 74 75 61 6c 20 74 61 62 6c 65 2e 0d 0a 20 20 rtual table...
20c0: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 /// </para
20d0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c >.. /// <
20e0: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f para>.. /
20f0: 2f 2f 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 // For example,
2100: 74 68 65 20 22 67 65 6e 65 72 61 74 65 5f 73 65 the "generate_se
2110: 72 69 65 73 22 20 65 78 74 65 6e 73 69 6f 6e 20 ries" extension
2120: 28 6c 6f 63 61 74 65 64 20 69 6e 20 74 68 65 0d (located in the.
2130: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 65 78 74 . /// ext
2140: 2f 6d 69 73 63 2f 73 65 72 69 65 73 2e 63 0d 0a /misc/series.c..
2150: 20 20 20 20 20 20 20 20 2f 2f 2f 20 66 69 6c 65 /// file
2160: 20 69 6e 20 74 68 65 20 73 6f 75 72 63 65 20 74 in the source t
2170: 72 65 65 29 0d 0a 20 20 20 20 20 20 20 20 2f 2f ree).. //
2180: 2f 20 69 6d 70 6c 65 6d 65 6e 74 73 20 61 6e 20 / implements an
2190: 65 70 6f 6e 79 6d 6f 75 73 20 76 69 72 74 75 61 eponymous virtua
21a0: 6c 20 74 61 62 6c 65 20 77 69 74 68 20 74 68 65 l table with the
21b0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 63 68 65 6d following schem
21c0: 61 3a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 a:.. ///
21d0: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 </para>..
21e0: 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 /// <para><code
21f0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 43 >.. /// C
2200: 52 45 41 54 45 20 54 41 42 4c 45 20 67 65 6e 65 REATE TABLE gene
2210: 72 61 74 65 5f 73 65 72 69 65 73 28 0d 0a 20 20 rate_series(..
2220: 20 20 20 20 20 20 2f 2f 2f 20 20 20 76 61 6c 75 /// valu
2230: 65 2c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 e,.. ///
2240: 20 20 73 74 61 72 74 20 48 49 44 44 45 4e 2c 0d start HIDDEN,.
2250: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 73 . /// s
2260: 74 6f 70 20 48 49 44 44 45 4e 2c 0d 0a 20 20 20 top HIDDEN,..
2270: 20 20 20 20 20 2f 2f 2f 20 20 20 73 74 65 70 20 /// step
2280: 48 49 44 44 45 4e 0d 0a 20 20 20 20 20 20 20 20 HIDDEN..
2290: 2f 2f 2f 20 29 3b 0d 0a 20 20 20 20 20 20 20 20 /// );..
22a0: 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 /// </code></par
22b0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 a>.. ///
22c0: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 <para>..
22d0: 2f 2f 2f 20 54 68 65 20 73 71 6c 69 74 65 33 5f /// The sqlite3_
22e0: 6d 6f 64 75 6c 65 2e 78 42 65 73 74 49 6e 64 65 module.xBestInde
22f0: 78 20 6d 65 74 68 6f 64 20 69 6e 20 74 68 65 20 x method in the
2300: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
2310: 66 20 74 68 69 73 0d 0a 20 20 20 20 20 20 20 20 f this..
2320: 2f 2f 2f 20 74 61 62 6c 65 20 63 68 65 63 6b 73 /// table checks
2330: 20 66 6f 72 20 65 71 75 61 6c 69 74 79 20 63 6f for equality co
2340: 6e 73 74 72 61 69 6e 74 73 20 61 67 61 69 6e 73 nstraints agains
2350: 74 20 74 68 65 20 48 49 44 44 45 4e 20 63 6f 6c t the HIDDEN col
2360: 75 6d 6e 73 2c 20 61 6e 64 20 75 73 65 73 0d 0a umns, and uses..
2370: 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 6f 73 /// thos
2380: 65 20 61 73 20 69 6e 70 75 74 20 70 61 72 61 6d e as input param
2390: 65 74 65 72 73 20 74 6f 20 64 65 74 65 72 6d 69 eters to determi
23a0: 6e 65 20 74 68 65 20 72 61 6e 67 65 20 6f 66 20 ne the range of
23b0: 69 6e 74 65 67 65 72 20 22 76 61 6c 75 65 22 20 integer "value"
23c0: 6f 75 74 70 75 74 73 0d 0a 20 20 20 20 20 20 20 outputs..
23d0: 20 2f 2f 2f 20 74 6f 20 67 65 6e 65 72 61 74 65 /// to generate
23e0: 2e 20 20 52 65 61 73 6f 6e 61 62 6c 65 20 64 65 . Reasonable de
23f0: 66 61 75 6c 74 73 20 61 72 65 20 75 73 65 64 20 faults are used
2400: 66 6f 72 20 61 6e 79 20 75 6e 63 6f 6e 73 74 72 for any unconstr
2410: 61 69 6e 65 64 20 63 6f 6c 75 6d 6e 73 2e 0d 0a ained columns...
2420: 20 20 20 20 20 20 20 20 2f 2f 2f 20 46 6f 72 20 /// For
2430: 65 78 61 6d 70 6c 65 2c 20 74 6f 20 6c 69 73 74 example, to list
2440: 20 61 6c 6c 20 69 6e 74 65 67 65 72 73 20 62 65 all integers be
2450: 74 77 65 65 6e 20 35 20 61 6e 64 20 35 30 3a 0d tween 5 and 50:.
2460: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 . /// </p
2470: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ara>.. //
2480: 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a / <para><code>..
2490: 20 20 20 20 20 20 20 20 2f 2f 2f 20 53 45 4c 45 /// SELE
24a0: 43 54 20 76 61 6c 75 65 20 46 52 4f 4d 20 67 65 CT value FROM ge
24b0: 6e 65 72 61 74 65 5f 73 65 72 69 65 73 28 35 2c nerate_series(5,
24c0: 35 30 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f 50);.. //
24d0: 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e / </code></para>
24e0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 .. /// <p
24f0: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ara>.. //
2500: 2f 20 54 68 65 20 70 72 65 76 69 6f 75 73 20 71 / The previous q
2510: 75 65 72 79 20 69 73 20 65 71 75 69 76 61 6c 65 uery is equivale
2520: 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 nt to the follow
2530: 69 6e 67 3a 0d 0a 20 20 20 20 20 20 20 20 2f 2f ing:.. //
2540: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 / </para>..
2550: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f /// <para><co
2560: 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f de>.. ///
2570: 20 53 45 4c 45 43 54 20 76 61 6c 75 65 20 46 52 SELECT value FR
2580: 4f 4d 20 67 65 6e 65 72 61 74 65 5f 73 65 72 69 OM generate_seri
2590: 65 73 20 57 48 45 52 45 20 73 74 61 72 74 3d 35 es WHERE start=5
25a0: 20 41 4e 44 20 73 74 6f 70 3d 35 30 3b 0d 0a 20 AND stop=50;..
25b0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 /// </cod
25c0: 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 e></para>..
25d0: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 /// <para>..
25e0: 20 20 20 20 20 20 20 2f 2f 2f 20 41 72 67 75 6d /// Argum
25f0: 65 6e 74 73 20 6f 6e 20 74 68 65 20 76 69 72 74 ents on the virt
2600: 75 61 6c 20 74 61 62 6c 65 20 6e 61 6d 65 20 61 ual table name a
2610: 72 65 20 6d 61 74 63 68 65 64 20 74 6f 20 68 69 re matched to hi
2620: 64 64 65 6e 20 63 6f 6c 75 6d 6e 73 0d 0a 20 20 dden columns..
2630: 20 20 20 20 20 20 2f 2f 2f 20 69 6e 20 6f 72 64 /// in ord
2640: 65 72 2e 20 20 54 68 65 20 6e 75 6d 62 65 72 20 er. The number
2650: 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 63 61 6e of arguments can
2660: 20 62 65 20 6c 65 73 73 20 74 68 61 6e 20 74 68 be less than th
2670: 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6e e.. /// n
2680: 75 6d 62 65 72 20 6f 66 20 68 69 64 64 65 6e 20 umber of hidden
2690: 63 6f 6c 75 6d 6e 73 2c 20 69 6e 20 77 68 69 63 columns, in whic
26a0: 68 20 63 61 73 65 20 74 68 65 20 6c 61 74 74 65 h case the latte
26b0: 72 20 68 69 64 64 65 6e 20 63 6f 6c 75 6d 6e 73 r hidden columns
26c0: 20 61 72 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f are.. //
26d0: 2f 20 75 6e 63 6f 6e 73 74 72 61 69 6e 65 64 2e / unconstrained.
26e0: 20 20 48 6f 77 65 76 65 72 2c 20 61 6e 20 65 72 However, an er
26f0: 72 6f 72 20 72 65 73 75 6c 74 73 20 69 66 20 74 ror results if t
2700: 68 65 72 65 20 61 72 65 20 6d 6f 72 65 20 61 72 here are more ar
2710: 67 75 6d 65 6e 74 73 0d 0a 20 20 20 20 20 20 20 guments..
2720: 20 2f 2f 2f 20 74 68 61 6e 20 74 68 65 72 65 20 /// than there
2730: 61 72 65 20 68 69 64 64 65 6e 20 63 6f 6c 75 6d are hidden colum
2740: 6e 73 20 69 6e 20 74 68 65 20 76 69 72 74 75 61 ns in the virtua
2750: 6c 20 74 61 62 6c 65 2e 0d 0a 20 20 20 20 20 20 l table...
2760: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 /// </para>..
2770: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 /// <para
2780: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 42 >.. /// B
2790: 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 eginning with SQ
27a0: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 31 Lite version 3.1
27b0: 34 2e 30 20 28 32 30 31 36 2d 30 38 2d 30 38 29 4.0 (2016-08-08)
27c0: 2c 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 , .. ///
27d0: 74 68 65 20 43 52 45 41 54 45 20 54 41 42 4c 45 the CREATE TABLE
27e0: 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0d statement that.
27f0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 73 20 . /// is
2800: 70 61 73 73 65 64 20 69 6e 74 6f 20 73 71 6c 69 passed into sqli
2810: 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 te3_declare_vtab
2820: 28 29 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 () may contain a
2830: 20 57 49 54 48 4f 55 54 20 52 4f 57 49 44 20 63 WITHOUT ROWID c
2840: 6c 61 75 73 65 2e 0d 0a 20 20 20 20 20 20 20 20 lause...
2850: 2f 2f 2f 20 54 68 69 73 20 69 73 20 75 73 65 66 /// This is usef
2860: 75 6c 20 66 6f 72 20 63 61 73 65 73 20 77 68 65 ul for cases whe
2870: 72 65 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 re the virtual t
2880: 61 62 6c 65 20 72 6f 77 73 20 0d 0a 20 20 20 20 able rows ..
2890: 20 20 20 20 2f 2f 2f 20 63 61 6e 6e 6f 74 20 65 /// cannot e
28a0: 61 73 69 6c 79 20 62 65 20 6d 61 70 70 65 64 20 asily be mapped
28b0: 69 6e 74 6f 20 75 6e 69 71 75 65 20 69 6e 74 65 into unique inte
28c0: 67 65 72 73 2e 20 20 41 20 43 52 45 41 54 45 20 gers. A CREATE
28d0: 54 41 42 4c 45 0d 0a 20 20 20 20 20 20 20 20 2f TABLE.. /
28e0: 2f 2f 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 // statement tha
28f0: 74 20 69 6e 63 6c 75 64 65 73 20 57 49 54 48 4f t includes WITHO
2900: 55 54 20 52 4f 57 49 44 20 6d 75 73 74 20 64 65 UT ROWID must de
2910: 66 69 6e 65 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 fine one or more
2920: 20 63 6f 6c 75 6d 6e 73 20 61 73 0d 0a 20 20 20 columns as..
2930: 20 20 20 20 20 2f 2f 2f 20 74 68 65 20 50 52 49 /// the PRI
2940: 4d 41 52 59 20 4b 45 59 2e 20 20 45 76 65 72 79 MARY KEY. Every
2950: 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 50 column of the P
2960: 52 49 4d 41 52 59 20 4b 45 59 20 6d 75 73 74 20 RIMARY KEY must
2970: 69 6e 64 69 76 69 64 75 61 6c 6c 79 20 62 65 0d individually be.
2980: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 4e 4f 54 . /// NOT
2990: 20 4e 55 4c 4c 20 61 6e 64 20 61 6c 6c 20 63 6f NULL and all co
29a0: 6c 75 6d 6e 73 20 66 6f 72 20 65 61 63 68 20 72 lumns for each r
29b0: 6f 77 20 6d 75 73 74 20 62 65 20 63 6f 6c 6c 65 ow must be colle
29c0: 63 74 69 76 65 6c 79 20 75 6e 69 71 75 65 2e 0d ctively unique..
29d0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 . /// </p
29e0: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ara>.. //
29f0: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 / <para>..
2a00: 20 20 2f 2f 2f 20 4e 6f 74 65 20 74 68 61 74 20 /// Note that
2a10: 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 SQLite does not
2a20: 65 6e 66 6f 72 63 65 20 74 68 65 20 50 52 49 4d enforce the PRIM
2a30: 41 52 59 20 4b 45 59 20 66 6f 72 20 61 20 57 49 ARY KEY for a WI
2a40: 54 48 4f 55 54 20 52 4f 57 49 44 0d 0a 20 20 20 THOUT ROWID..
2a50: 20 20 20 20 20 2f 2f 2f 20 76 69 72 74 75 61 6c /// virtual
2a60: 20 74 61 62 6c 65 2e 20 20 45 6e 66 6f 72 63 65 table. Enforce
2a70: 6d 65 6e 74 20 69 73 20 74 68 65 20 72 65 73 70 ment is the resp
2a80: 6f 6e 73 69 62 69 6c 69 74 79 20 6f 66 20 74 68 onsibility of th
2a90: 65 20 75 6e 64 65 72 6c 79 69 6e 67 0d 0a 20 20 e underlying..
2aa0: 20 20 20 20 20 20 2f 2f 2f 20 76 69 72 74 75 61 /// virtua
2ab0: 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e l table implemen
2ac0: 74 61 74 69 6f 6e 2e 20 20 42 75 74 20 53 51 4c tation. But SQL
2ad0: 69 74 65 20 64 6f 65 73 20 61 73 73 75 6d 65 20 ite does assume
2ae0: 74 68 61 74 20 74 68 65 20 50 52 49 4d 41 52 59 that the PRIMARY
2af0: 20 4b 45 59 0d 0a 20 20 20 20 20 20 20 20 2f 2f KEY.. //
2b00: 2f 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 / constraint is
2b10: 76 61 6c 69 64 20 2d 20 74 68 61 74 20 74 68 65 valid - that the
2b20: 20 69 64 65 6e 74 69 66 69 65 64 20 63 6f 6c 75 identified colu
2b30: 6d 6e 73 20 72 65 61 6c 6c 79 20 61 72 65 20 55 mns really are U
2b40: 4e 49 51 55 45 20 61 6e 64 0d 0a 20 20 20 20 20 NIQUE and..
2b50: 20 20 20 2f 2f 2f 20 4e 4f 54 20 4e 55 4c 4c 20 /// NOT NULL
2b60: 2d 20 61 6e 64 20 69 74 20 75 73 65 73 20 74 68 - and it uses th
2b70: 61 74 20 61 73 73 75 6d 70 74 69 6f 6e 20 74 6f at assumption to
2b80: 20 6f 70 74 69 6d 69 7a 65 20 71 75 65 72 69 65 optimize querie
2b90: 73 20 61 67 61 69 6e 73 74 20 74 68 65 0d 0a 20 s against the..
2ba0: 20 20 20 20 20 20 20 2f 2f 2f 20 76 69 72 74 75 /// virtu
2bb0: 61 6c 20 74 61 62 6c 65 2e 0d 0a 20 20 20 20 20 al table...
2bc0: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a /// </para>..
2bd0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 /// <par
2be0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 a>.. ///
2bf0: 54 68 65 20 72 6f 77 69 64 20 63 6f 6c 75 6d 6e The rowid column
2c00: 20 69 73 20 6e 6f 74 20 61 63 63 65 73 73 69 62 is not accessib
2c10: 6c 65 20 6f 6e 20 61 0d 0a 20 20 20 20 20 20 20 le on a..
2c20: 20 2f 2f 2f 20 57 49 54 48 4f 55 54 20 52 4f 57 /// WITHOUT ROW
2c30: 49 44 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 ID virtual table
2c40: 20 28 6f 66 20 63 6f 75 72 73 65 29 2e 0d 0a 20 (of course)...
2c50: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 /// </par
2c60: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 a>.. ///
2c70: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 <para>..
2c80: 2f 2f 2f 20 54 68 65 20 78 55 70 64 61 74 65 20 /// The xUpdate
2c90: 6d 65 74 68 6f 64 20 77 61 73 20 6f 72 69 67 69 method was origi
2ca0: 6e 61 6c 6c 79 20 64 65 73 69 67 6e 65 64 20 61 nally designed a
2cb0: 72 6f 75 6e 64 20 68 61 76 69 6e 67 20 61 0d 0a round having a..
2cc0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 52 4f 57 49 /// ROWI
2cd0: 44 20 61 73 20 61 20 73 69 6e 67 6c 65 20 76 61 D as a single va
2ce0: 6c 75 65 2e 20 20 54 68 65 20 78 55 70 64 61 74 lue. The xUpdat
2cf0: 65 20 6d 65 74 68 6f 64 20 68 61 73 20 62 65 65 e method has bee
2d00: 6e 20 65 78 70 61 6e 64 65 64 20 74 6f 0d 0a 20 n expanded to..
2d10: 20 20 20 20 20 20 20 2f 2f 2f 20 61 63 63 6f 6d /// accom
2d20: 6d 6f 64 61 74 65 20 61 6e 20 61 72 62 69 74 72 modate an arbitr
2d30: 61 72 79 20 50 52 49 4d 41 52 59 20 4b 45 59 20 ary PRIMARY KEY
2d40: 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 in place of the
2d50: 52 4f 57 49 44 2c 20 62 75 74 20 74 68 65 0d 0a ROWID, but the..
2d60: 20 20 20 20 20 20 20 20 2f 2f 2f 20 50 52 49 4d /// PRIM
2d70: 41 52 59 20 4b 45 59 20 6d 75 73 74 20 73 74 69 ARY KEY must sti
2d80: 6c 6c 20 62 65 20 6f 6e 6c 79 20 6f 6e 65 20 63 ll be only one c
2d90: 6f 6c 75 6d 6e 2e 20 20 46 6f 72 20 74 68 69 73 olumn. For this
2da0: 20 72 65 61 73 6f 6e 2c 20 53 51 4c 69 74 65 0d reason, SQLite.
2db0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 77 69 6c . /// wil
2dc0: 6c 20 72 65 6a 65 63 74 20 61 6e 79 20 57 49 54 l reject any WIT
2dd0: 48 4f 55 54 20 52 4f 57 49 44 20 76 69 72 74 75 HOUT ROWID virtu
2de0: 61 6c 20 74 61 62 6c 65 20 74 68 61 74 20 68 61 al table that ha
2df0: 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0d s more than one.
2e00: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 50 52 49 . /// PRI
2e10: 4d 41 52 59 20 4b 45 59 20 63 6f 6c 75 6d 6e 20 MARY KEY column
2e20: 61 6e 64 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 and a non-NULL x
2e30: 55 70 64 61 74 65 20 6d 65 74 68 6f 64 2e 0d 0a Update method...
2e40: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 /// </pa
2e50: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ra>.. ///
2e60: 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 </summary>..
2e70: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 /// <param
2e80: 6e 61 6d 65 3d 22 70 44 62 22 3e 0d 0a 20 20 20 name="pDb">..
2e90: 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e 61 74 /// The nat
2ea0: 69 76 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e ive database con
2eb0: 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 2e 0d nection handle..
2ec0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 . /// </p
2ed0: 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f aram>.. /
2ee0: 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 // <param name="
2ef0: 70 41 75 78 22 3e 0d 0a 20 20 20 20 20 20 20 20 pAux">..
2f00: 2f 2f 2f 20 54 68 65 20 6f 72 69 67 69 6e 61 6c /// The original
2f10: 20 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72 20 native pointer
2f20: 76 61 6c 75 65 20 74 68 61 74 20 77 61 73 20 70 value that was p
2f30: 72 6f 76 69 64 65 64 20 74 6f 20 74 68 65 0d 0a rovided to the..
2f40: 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 71 6c 69 /// sqli
2f50: 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c te3_create_modul
2f60: 65 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 72 65 e(), sqlite3_cre
2f70: 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 20 ate_module_v2()
2f80: 6f 72 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 or.. ///
2f90: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 64 sqlite3_create_d
2fa0: 69 73 70 6f 73 61 62 6c 65 5f 6d 6f 64 75 6c 65 isposable_module
2fb0: 28 29 20 66 75 6e 63 74 69 6f 6e 73 2e 0d 0a 20 () functions...
2fc0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 /// </par
2fd0: 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f am>.. ///
2fe0: 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 61 72 <param name="ar
2ff0: 67 63 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f gc">.. //
3000: 2f 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 / The number of
3010: 61 72 67 75 6d 65 6e 74 73 20 66 72 6f 6d 20 74 arguments from t
3020: 68 65 20 43 52 45 41 54 45 20 56 49 52 54 55 41 he CREATE VIRTUA
3030: 4c 20 54 41 42 4c 45 20 73 74 61 74 65 6d 65 6e L TABLE statemen
3040: 74 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 t... ///
3050: 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 </param>..
3060: 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d /// <param nam
3070: 65 3d 22 61 72 67 76 22 3e 0d 0a 20 20 20 20 20 e="argv">..
3080: 20 20 20 2f 2f 2f 20 54 68 65 20 61 72 72 61 79 /// The array
3090: 20 6f 66 20 73 74 72 69 6e 67 20 61 72 67 75 6d of string argum
30a0: 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 43 52 ents from the CR
30b0: 45 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 EATE VIRTUAL TAB
30c0: 4c 45 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 LE.. ///
30d0: 73 74 61 74 65 6d 65 6e 74 2e 0d 0a 20 20 20 20 statement...
30e0: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e /// </param>
30f0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 .. /// <p
3100: 61 72 61 6d 20 6e 61 6d 65 3d 22 70 56 74 61 62 aram name="pVtab
3110: 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 ">.. ///
3120: 55 70 6f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 Upon success, th
3130: 69 73 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 is parameter mus
3140: 74 20 62 65 20 6d 6f 64 69 66 69 65 64 20 74 6f t be modified to
3150: 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 6e 65 point to the ne
3160: 77 6c 79 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f wly.. ///
3170: 20 63 72 65 61 74 65 64 20 6e 61 74 69 76 65 20 created native
3180: 73 71 6c 69 74 65 33 5f 76 74 61 62 20 64 65 72 sqlite3_vtab der
3190: 69 76 65 64 20 73 74 72 75 63 74 75 72 65 2e 0d ived structure..
31a0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 . /// </p
31b0: 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f aram>.. /
31c0: 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 // <param name="
31d0: 70 45 72 72 6f 72 22 3e 0d 0a 20 20 20 20 20 20 pError">..
31e0: 20 20 2f 2f 2f 20 55 70 6f 6e 20 66 61 69 6c 75 /// Upon failu
31f0: 72 65 2c 20 74 68 69 73 20 70 61 72 61 6d 65 74 re, this paramet
3200: 65 72 20 6d 75 73 74 20 62 65 20 6d 6f 64 69 66 er must be modif
3210: 69 65 64 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 ied to point to
3220: 74 68 65 20 65 72 72 6f 72 0d 0a 20 20 20 20 20 the error..
3230: 20 20 20 2f 2f 2f 20 6d 65 73 73 61 67 65 2c 20 /// message,
3240: 77 69 74 68 20 74 68 65 20 75 6e 64 65 72 6c 79 with the underly
3250: 69 6e 67 20 6d 65 6d 6f 72 79 20 68 61 76 69 6e ing memory havin
3260: 67 20 62 65 65 6e 20 6f 62 74 61 69 6e 65 64 20 g been obtained
3270: 66 72 6f 6d 20 74 68 65 0d 0a 20 20 20 20 20 20 from the..
3280: 20 20 2f 2f 2f 20 73 71 6c 69 74 65 33 5f 6d 61 /// sqlite3_ma
3290: 6c 6c 6f 63 28 29 20 66 75 6e 63 74 69 6f 6e 2e lloc() function.
32a0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f .. /// </
32b0: 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 param>..
32c0: 2f 2f 2f 20 3c 72 65 74 75 72 6e 73 3e 0d 0a 20 /// <returns>..
32d0: 20 20 20 20 20 20 20 2f 2f 2f 20 41 20 73 74 61 /// A sta
32e0: 6e 64 61 72 64 20 53 51 4c 69 74 65 20 72 65 74 ndard SQLite ret
32f0: 75 72 6e 20 63 6f 64 65 2e 0d 0a 20 20 20 20 20 urn code...
3300: 20 20 20 2f 2f 2f 20 3c 2f 72 65 74 75 72 6e 73 /// </returns
3310: 3e 0d 0a 20 20 20 20 20 20 20 20 53 51 4c 69 74 >.. SQLit
3320: 65 45 72 72 6f 72 43 6f 64 65 20 78 43 72 65 61 eErrorCode xCrea
3330: 74 65 28 0d 0a 20 20 20 20 20 20 20 20 20 20 20 te(..
3340: 20 49 6e 74 50 74 72 20 70 44 62 2c 0d 0a 20 20 IntPtr pDb,..
3350: 20 20 20 20 20 20 20 20 20 20 49 6e 74 50 74 72 IntPtr
3360: 20 70 41 75 78 2c 0d 0a 20 20 20 20 20 20 20 20 pAux,..
3370: 20 20 20 20 69 6e 74 20 61 72 67 63 2c 0d 0a 20 int argc,..
3380: 20 20 20 20 20 20 20 20 20 20 20 49 6e 74 50 74 IntPt
3390: 72 20 61 72 67 76 2c 0d 0a 20 20 20 20 20 20 20 r argv,..
33a0: 20 20 20 20 20 72 65 66 20 49 6e 74 50 74 72 20 ref IntPtr
33b0: 70 56 74 61 62 2c 0d 0a 20 20 20 20 20 20 20 20 pVtab,..
33c0: 20 20 20 20 72 65 66 20 49 6e 74 50 74 72 20 70 ref IntPtr p
33d0: 45 72 72 6f 72 0d 0a 20 20 20 20 20 20 20 20 20 Error..
33e0: 20 20 20 29 3b 0d 0a 0d 0a 20 20 20 20 20 20 20 );....
33f0: 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ///////////////
3400: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
3410: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
3420: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
3430: 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 ////////....
3440: 20 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79 /// <summary
3450: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c >.. /// <
3460: 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 para><code>..
3470: 20 20 20 20 20 2f 2f 2f 20 69 6e 74 20 28 2a 78 /// int (*x
3480: 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 Connect)(sqlite3
3490: 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0d 0a *, void *pAux,..
34a0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 ///
34b0: 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 int arg
34c0: 63 2c 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 c, char *const*a
34d0: 72 67 76 2c 0d 0a 20 20 20 20 20 20 20 20 2f 2f rgv,.. //
34e0: 2f 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73 / s
34f0: 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 qlite3_vtab **pp
3500: 56 54 61 62 2c 0d 0a 20 20 20 20 20 20 20 20 2f VTab,.. /
3510: 2f 2f 20 20 20 20 20 20 20 20 20 20 20 20 20 20 //
3520: 63 68 61 72 20 2a 2a 70 7a 45 72 72 29 3b 0d 0a char **pzErr);..
3530: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f /// </co
3540: 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 de></para>..
3550: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a /// <para>..
3560: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 /// The
3570: 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64 20 xConnect method
3580: 69 73 20 76 65 72 79 20 73 69 6d 69 6c 61 72 20 is very similar
3590: 74 6f 20 78 43 72 65 61 74 65 2e 20 0d 0a 20 20 to xCreate. ..
35a0: 20 20 20 20 20 20 2f 2f 2f 20 49 74 20 68 61 73 /// It has
35b0: 20 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65 the same parame
35c0: 74 65 72 73 20 61 6e 64 20 63 6f 6e 73 74 72 75 ters and constru
35d0: 63 74 73 20 61 20 6e 65 77 20 73 71 6c 69 74 65 cts a new sqlite
35e0: 33 5f 76 74 61 62 20 73 74 72 75 63 74 75 72 65 3_vtab structure
35f0: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6a .. /// j
3600: 75 73 74 20 6c 69 6b 65 20 78 43 72 65 61 74 65 ust like xCreate
3610: 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 . .. ///
3620: 41 6e 64 20 69 74 20 6d 75 73 74 20 61 6c 73 6f And it must also
3630: 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 64 65 call sqlite3_de
3640: 63 6c 61 72 65 5f 76 74 61 62 28 29 20 6c 69 6b clare_vtab() lik
3650: 65 20 78 43 72 65 61 74 65 2e 0d 0a 20 20 20 20 e xCreate...
3660: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d /// </para>.
3670: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 . /// <pa
3680: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ra>.. ///
3690: 20 54 68 65 20 64 69 66 66 65 72 65 6e 63 65 20 The difference
36a0: 69 73 20 74 68 61 74 20 78 43 6f 6e 6e 65 63 74 is that xConnect
36b0: 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 65 73 is called to es
36c0: 74 61 62 6c 69 73 68 20 61 20 6e 65 77 20 0d 0a tablish a new ..
36d0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 63 6f 6e 6e /// conn
36e0: 65 63 74 69 6f 6e 20 74 6f 20 61 6e 20 65 78 69 ection to an exi
36f0: 73 74 69 6e 67 20 76 69 72 74 75 61 6c 20 74 61 sting virtual ta
3700: 62 6c 65 20 77 68 65 72 65 61 73 20 78 43 72 65 ble whereas xCre
3710: 61 74 65 20 69 73 20 63 61 6c 6c 65 64 20 0d 0a ate is called ..
3720: 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 6f 20 63 /// to c
3730: 72 65 61 74 65 20 61 20 6e 65 77 20 76 69 72 74 reate a new virt
3740: 75 61 6c 20 74 61 62 6c 65 20 66 72 6f 6d 20 73 ual table from s
3750: 63 72 61 74 63 68 2e 0d 0a 20 20 20 20 20 20 20 cratch...
3760: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 /// </para>..
3770: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e /// <para>
3780: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 .. /// Th
3790: 65 20 78 43 72 65 61 74 65 20 61 6e 64 20 78 43 e xCreate and xC
37a0: 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64 73 20 61 onnect methods a
37b0: 72 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e re only differen
37c0: 74 20 77 68 65 6e 20 74 68 65 0d 0a 20 20 20 20 t when the..
37d0: 20 20 20 20 2f 2f 2f 20 76 69 72 74 75 61 6c 20 /// virtual
37e0: 74 61 62 6c 65 20 68 61 73 20 73 6f 6d 65 20 6b table has some k
37f0: 69 6e 64 20 6f 66 20 62 61 63 6b 69 6e 67 20 73 ind of backing s
3800: 74 6f 72 65 20 74 68 61 74 20 6d 75 73 74 20 62 tore that must b
3810: 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 0d 0a e initialized ..
3820: 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 20 /// the
3830: 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 76 first time the v
3840: 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20 irtual table is
3850: 63 72 65 61 74 65 64 2e 20 54 68 65 20 78 43 72 created. The xCr
3860: 65 61 74 65 20 6d 65 74 68 6f 64 20 63 72 65 61 eate method crea
3870: 74 65 73 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f tes .. //
3880: 2f 20 61 6e 64 20 69 6e 69 74 69 61 6c 69 7a 65 / and initialize
3890: 73 20 74 68 65 20 62 61 63 6b 69 6e 67 20 73 74 s the backing st
38a0: 6f 72 65 2e 20 54 68 65 20 78 43 6f 6e 6e 65 63 ore. The xConnec
38b0: 74 20 6d 65 74 68 6f 64 20 6a 75 73 74 20 63 6f t method just co
38c0: 6e 6e 65 63 74 73 20 0d 0a 20 20 20 20 20 20 20 nnects ..
38d0: 20 2f 2f 2f 20 74 6f 20 61 6e 20 65 78 69 73 74 /// to an exist
38e0: 69 6e 67 20 62 61 63 6b 69 6e 67 20 73 74 6f 72 ing backing stor
38f0: 65 2e 20 20 57 68 65 6e 20 78 43 72 65 61 74 65 e. When xCreate
3900: 20 61 6e 64 20 78 43 6f 6e 6e 65 63 74 20 61 72 and xConnect ar
3910: 65 20 74 68 65 20 73 61 6d 65 2c 0d 0a 20 20 20 e the same,..
3920: 20 20 20 20 20 2f 2f 2f 20 74 68 65 20 74 61 62 /// the tab
3930: 6c 65 20 69 73 20 61 6e 20 65 70 6f 6e 79 6d 6f le is an eponymo
3940: 75 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 us virtual table
3950: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c ... /// <
3960: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 /para>..
3970: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 /// <para>..
3980: 20 20 20 20 2f 2f 2f 20 41 73 20 61 6e 20 65 78 /// As an ex
3990: 61 6d 70 6c 65 2c 20 63 6f 6e 73 69 64 65 72 20 ample, consider
39a0: 61 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 a virtual table
39b0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 implementation t
39c0: 68 61 74 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f hat .. //
39d0: 2f 20 70 72 6f 76 69 64 65 73 20 72 65 61 64 2d / provides read-
39e0: 6f 6e 6c 79 20 61 63 63 65 73 73 20 74 6f 20 65 only access to e
39f0: 78 69 73 74 69 6e 67 20 63 6f 6d 6d 61 2d 73 65 xisting comma-se
3a00: 70 61 72 61 74 65 64 2d 76 61 6c 75 65 20 28 43 parated-value (C
3a10: 53 56 29 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f SV).. ///
3a20: 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 20 files on disk.
3a30: 54 68 65 72 65 20 69 73 20 6e 6f 20 62 61 63 6b There is no back
3a40: 69 6e 67 20 73 74 6f 72 65 20 74 68 61 74 20 6e ing store that n
3a50: 65 65 64 73 20 74 6f 20 62 65 20 63 72 65 61 74 eeds to be creat
3a60: 65 64 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ed .. ///
3a70: 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 or initialized
3a80: 66 6f 72 20 73 75 63 68 20 61 20 76 69 72 74 75 for such a virtu
3a90: 61 6c 20 74 61 62 6c 65 20 28 73 69 6e 63 65 20 al table (since
3aa0: 74 68 65 20 43 53 56 20 66 69 6c 65 73 20 61 6c the CSV files al
3ab0: 72 65 61 64 79 20 0d 0a 20 20 20 20 20 20 20 20 ready ..
3ac0: 2f 2f 2f 20 65 78 69 73 74 20 6f 6e 20 64 69 73 /// exist on dis
3ad0: 6b 29 20 73 6f 20 74 68 65 20 78 43 72 65 61 74 k) so the xCreat
3ae0: 65 20 61 6e 64 20 78 43 6f 6e 6e 65 63 74 20 6d e and xConnect m
3af0: 65 74 68 6f 64 73 20 77 69 6c 6c 20 62 65 20 69 ethods will be i
3b00: 64 65 6e 74 69 63 61 6c 20 0d 0a 20 20 20 20 20 dentical ..
3b10: 20 20 20 2f 2f 2f 20 66 6f 72 20 74 68 61 74 20 /// for that
3b20: 6d 6f 64 75 6c 65 2e 0d 0a 20 20 20 20 20 20 20 module...
3b30: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 /// </para>..
3b40: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e /// <para>
3b50: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 6e .. /// An
3b60: 6f 74 68 65 72 20 65 78 61 6d 70 6c 65 20 69 73 other example is
3b70: 20 61 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 a virtual table
3b80: 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 that implements
3b90: 20 61 20 66 75 6c 6c 2d 74 65 78 74 20 69 6e 64 a full-text ind
3ba0: 65 78 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f ex. .. //
3bb0: 2f 20 54 68 65 20 78 43 72 65 61 74 65 20 6d 65 / The xCreate me
3bc0: 74 68 6f 64 20 6d 75 73 74 20 63 72 65 61 74 65 thod must create
3bd0: 20 61 6e 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 and initialize
3be0: 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 data structures
3bf0: 74 6f 20 68 6f 6c 64 20 0d 0a 20 20 20 20 20 20 to hold ..
3c00: 20 20 2f 2f 2f 20 74 68 65 20 64 69 63 74 69 6f /// the dictio
3c10: 6e 61 72 79 20 61 6e 64 20 70 6f 73 74 69 6e 67 nary and posting
3c20: 20 6c 69 73 74 73 20 66 6f 72 20 74 68 61 74 20 lists for that
3c30: 69 6e 64 65 78 2e 20 54 68 65 20 78 43 6f 6e 6e index. The xConn
3c40: 65 63 74 20 6d 65 74 68 6f 64 2c 0d 0a 20 20 20 ect method,..
3c50: 20 20 20 20 20 2f 2f 2f 20 6f 6e 20 74 68 65 20 /// on the
3c60: 6f 74 68 65 72 20 68 61 6e 64 2c 20 6f 6e 6c 79 other hand, only
3c70: 20 68 61 73 20 74 6f 20 6c 6f 63 61 74 65 20 61 has to locate a
3c80: 6e 64 20 75 73 65 20 61 6e 20 65 78 69 73 74 69 nd use an existi
3c90: 6e 67 20 64 69 63 74 69 6f 6e 61 72 79 20 0d 0a ng dictionary ..
3ca0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 61 6e 64 20 /// and
3cb0: 70 6f 73 74 69 6e 67 20 6c 69 73 74 73 20 74 68 posting lists th
3cc0: 61 74 20 77 65 72 65 20 63 72 65 61 74 65 64 20 at were created
3cd0: 62 79 20 61 20 70 72 69 6f 72 20 78 43 72 65 61 by a prior xCrea
3ce0: 74 65 20 63 61 6c 6c 2e 0d 0a 20 20 20 20 20 20 te call...
3cf0: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 /// </para>..
3d00: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 /// <para
3d10: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 >.. /// T
3d20: 68 65 20 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68 he xConnect meth
3d30: 6f 64 20 6d 75 73 74 20 72 65 74 75 72 6e 20 53 od must return S
3d40: 51 4c 49 54 45 5f 4f 4b 20 69 66 20 69 74 20 69 QLITE_OK if it i
3d50: 73 20 73 75 63 63 65 73 73 66 75 6c 20 0d 0a 20 s successful ..
3d60: 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e 20 63 72 /// in cr
3d70: 65 61 74 69 6e 67 20 74 68 65 20 6e 65 77 20 76 eating the new v
3d80: 69 72 74 75 61 6c 20 74 61 62 6c 65 2c 20 6f 72 irtual table, or
3d90: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 69 66 SQLITE_ERROR if
3da0: 20 69 74 20 69 73 20 6e 6f 74 20 0d 0a 20 20 20 it is not ..
3db0: 20 20 20 20 20 2f 2f 2f 20 73 75 63 63 65 73 73 /// success
3dc0: 66 75 6c 2e 20 49 66 20 6e 6f 74 20 73 75 63 63 ful. If not succ
3dd0: 65 73 73 66 75 6c 2c 20 74 68 65 20 73 71 6c 69 essful, the sqli
3de0: 74 65 33 5f 76 74 61 62 20 73 74 72 75 63 74 75 te3_vtab structu
3df0: 72 65 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 0d re must not be .
3e00: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 61 6c 6c . /// all
3e10: 6f 63 61 74 65 64 2e 20 41 6e 20 65 72 72 6f 72 ocated. An error
3e20: 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 70 74 message may opt
3e30: 69 6f 6e 61 6c 6c 79 20 62 65 20 72 65 74 75 72 ionally be retur
3e40: 6e 65 64 20 69 6e 20 2a 70 7a 45 72 72 20 69 66 ned in *pzErr if
3e50: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 75 .. /// u
3e60: 6e 73 75 63 63 65 73 73 66 75 6c 2e 20 0d 0a 20 nsuccessful. ..
3e70: 20 20 20 20 20 20 20 2f 2f 2f 20 53 70 61 63 65 /// Space
3e80: 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 to hold the err
3e90: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e or message strin
3ea0: 67 20 6d 75 73 74 20 62 65 20 61 6c 6c 6f 63 61 g must be alloca
3eb0: 74 65 64 20 75 73 69 6e 67 0d 0a 20 20 20 20 20 ted using..
3ec0: 20 20 20 2f 2f 2f 20 61 6e 20 53 51 4c 69 74 65 /// an SQLite
3ed0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
3ee0: 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 6c 69 6b 65 on function like
3ef0: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 .. /// s
3f00: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
3f10: 6f 72 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e or sqlite3_mprin
3f20: 74 66 28 29 20 61 73 20 74 68 65 20 53 51 4c 69 tf() as the SQLi
3f30: 74 65 20 63 6f 72 65 20 77 69 6c 6c 0d 0a 20 20 te core will..
3f40: 20 20 20 20 20 20 2f 2f 2f 20 61 74 74 65 6d 70 /// attemp
3f50: 74 20 74 6f 20 66 72 65 65 20 74 68 65 20 73 70 t to free the sp
3f60: 61 63 65 20 75 73 69 6e 67 20 73 71 6c 69 74 65 ace using sqlite
3f70: 33 5f 66 72 65 65 28 29 20 61 66 74 65 72 20 74 3_free() after t
3f80: 68 65 20 65 72 72 6f 72 20 68 61 73 0d 0a 20 20 he error has..
3f90: 20 20 20 20 20 20 2f 2f 2f 20 62 65 65 6e 20 72 /// been r
3fa0: 65 70 6f 72 74 65 64 20 75 70 20 74 6f 20 74 68 eported up to th
3fb0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0d 0a e application...
3fc0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 /// </pa
3fd0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ra>.. ///
3fe0: 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 <para>..
3ff0: 20 2f 2f 2f 20 54 68 65 20 78 43 6f 6e 6e 65 63 /// The xConnec
4000: 74 20 6d 65 74 68 6f 64 20 69 73 20 72 65 71 75 t method is requ
4010: 69 72 65 64 20 66 6f 72 20 65 76 65 72 79 20 76 ired for every v
4020: 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 irtual table imp
4030: 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 0d 0a 20 lementation, ..
4040: 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 6f 75 67 /// thoug
4050: 68 20 74 68 65 20 78 43 72 65 61 74 65 20 61 6e h the xCreate an
4060: 64 20 78 43 6f 6e 6e 65 63 74 20 70 6f 69 6e 74 d xConnect point
4070: 65 72 73 20 6f 66 20 74 68 65 20 73 71 6c 69 74 ers of the sqlit
4080: 65 33 5f 6d 6f 64 75 6c 65 20 6f 62 6a 65 63 74 e3_module object
4090: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6d 61 .. /// ma
40a0: 79 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 73 y point to the s
40b0: 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 69 66 20 ame function if
40c0: 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c the virtual tabl
40d0: 65 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 e does not need
40e0: 74 6f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 to.. ///
40f0: 69 6e 69 74 69 61 6c 69 7a 65 20 62 61 63 6b 69 initialize backi
4100: 6e 67 20 73 74 6f 72 65 2e 0d 0a 20 20 20 20 20 ng store...
4110: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a /// </para>..
4120: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 73 75 /// </su
4130: 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 mmary>..
4140: 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d /// <param name=
4150: 22 70 44 62 22 3e 0d 0a 20 20 20 20 20 20 20 20 "pDb">..
4160: 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76 65 20 64 /// The native d
4170: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
4180: 6f 6e 20 68 61 6e 64 6c 65 2e 0d 0a 20 20 20 20 on handle...
4190: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e /// </param>
41a0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 .. /// <p
41b0: 61 72 61 6d 20 6e 61 6d 65 3d 22 70 41 75 78 22 aram name="pAux"
41c0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 >.. /// T
41d0: 68 65 20 6f 72 69 67 69 6e 61 6c 20 6e 61 74 69 he original nati
41e0: 76 65 20 70 6f 69 6e 74 65 72 20 76 61 6c 75 65 ve pointer value
41f0: 20 74 68 61 74 20 77 61 73 20 70 72 6f 76 69 64 that was provid
4200: 65 64 20 74 6f 20 74 68 65 0d 0a 20 20 20 20 20 ed to the..
4210: 20 20 20 2f 2f 2f 20 73 71 6c 69 74 65 33 5f 63 /// sqlite3_c
4220: 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 2c 20 reate_module(),
4230: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d sqlite3_create_m
4240: 6f 64 75 6c 65 5f 76 32 28 29 20 6f 72 0d 0a 20 odule_v2() or..
4250: 20 20 20 20 20 20 20 2f 2f 2f 20 73 71 6c 69 74 /// sqlit
4260: 65 33 5f 63 72 65 61 74 65 5f 64 69 73 70 6f 73 e3_create_dispos
4270: 61 62 6c 65 5f 6d 6f 64 75 6c 65 28 29 20 66 75 able_module() fu
4280: 6e 63 74 69 6f 6e 73 2e 0d 0a 20 20 20 20 20 20 nctions...
4290: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a /// </param>..
42a0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 /// <par
42b0: 61 6d 20 6e 61 6d 65 3d 22 61 72 67 63 22 3e 0d am name="argc">.
42c0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 . /// The
42d0: 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d number of argum
42e0: 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 43 52 ents from the CR
42f0: 45 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 EATE VIRTUAL TAB
4300: 4c 45 20 73 74 61 74 65 6d 65 6e 74 2e 0d 0a 20 LE statement...
4310: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 /// </par
4320: 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f am>.. ///
4330: 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 61 72 <param name="ar
4340: 67 76 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f gv">.. //
4350: 2f 20 54 68 65 20 61 72 72 61 79 20 6f 66 20 73 / The array of s
4360: 74 72 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 tring arguments
4370: 66 72 6f 6d 20 74 68 65 20 43 52 45 41 54 45 20 from the CREATE
4380: 56 49 52 54 55 41 4c 20 54 41 42 4c 45 0d 0a 20 VIRTUAL TABLE..
4390: 20 20 20 20 20 20 20 2f 2f 2f 20 73 74 61 74 65 /// state
43a0: 6d 65 6e 74 2e 0d 0a 20 20 20 20 20 20 20 20 2f ment... /
43b0: 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 // </param>..
43c0: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 /// <param
43d0: 6e 61 6d 65 3d 22 70 56 74 61 62 22 3e 0d 0a 20 name="pVtab">..
43e0: 20 20 20 20 20 20 20 2f 2f 2f 20 55 70 6f 6e 20 /// Upon
43f0: 73 75 63 63 65 73 73 2c 20 74 68 69 73 20 70 61 success, this pa
4400: 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 rameter must be
4410: 6d 6f 64 69 66 69 65 64 20 74 6f 20 70 6f 69 6e modified to poin
4420: 74 20 74 6f 20 74 68 65 20 6e 65 77 6c 79 0d 0a t to the newly..
4430: 20 20 20 20 20 20 20 20 2f 2f 2f 20 63 72 65 61 /// crea
4440: 74 65 64 20 6e 61 74 69 76 65 20 73 71 6c 69 74 ted native sqlit
4450: 65 33 5f 76 74 61 62 20 64 65 72 69 76 65 64 20 e3_vtab derived
4460: 73 74 72 75 63 74 75 72 65 2e 0d 0a 20 20 20 20 structure...
4470: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e /// </param>
4480: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 .. /// <p
4490: 61 72 61 6d 20 6e 61 6d 65 3d 22 70 45 72 72 6f aram name="pErro
44a0: 72 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f r">.. ///
44b0: 20 55 70 6f 6e 20 66 61 69 6c 75 72 65 2c 20 74 Upon failure, t
44c0: 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 6d 75 his parameter mu
44d0: 73 74 20 62 65 20 6d 6f 64 69 66 69 65 64 20 74 st be modified t
44e0: 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 65 o point to the e
44f0: 72 72 6f 72 0d 0a 20 20 20 20 20 20 20 20 2f 2f rror.. //
4500: 2f 20 6d 65 73 73 61 67 65 2c 20 77 69 74 68 20 / message, with
4510: 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6d the underlying m
4520: 65 6d 6f 72 79 20 68 61 76 69 6e 67 20 62 65 65 emory having bee
4530: 6e 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 n obtained from
4540: 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f the.. ///
4550: 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
4560: 29 20 66 75 6e 63 74 69 6f 6e 2e 0d 0a 20 20 20 ) function...
4570: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d /// </param
4580: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c >.. /// <
4590: 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 returns>..
45a0: 20 20 2f 2f 2f 20 41 20 73 74 61 6e 64 61 72 64 /// A standard
45b0: 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 20 63 SQLite return c
45c0: 6f 64 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ode... //
45d0: 2f 20 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a 20 20 / </returns>..
45e0: 20 20 20 20 20 20 53 51 4c 69 74 65 45 72 72 6f SQLiteErro
45f0: 72 43 6f 64 65 20 78 43 6f 6e 6e 65 63 74 28 0d rCode xConnect(.
4600: 0a 20 20 20 20 20 20 20 20 20 20 20 20 49 6e 74 . Int
4610: 50 74 72 20 70 44 62 2c 0d 0a 20 20 20 20 20 20 Ptr pDb,..
4620: 20 20 20 20 20 20 49 6e 74 50 74 72 20 70 41 75 IntPtr pAu
4630: 78 2c 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 x,..
4640: 69 6e 74 20 61 72 67 63 2c 0d 0a 20 20 20 20 20 int argc,..
4650: 20 20 20 20 20 20 20 49 6e 74 50 74 72 20 61 72 IntPtr ar
4660: 67 76 2c 0d 0a 20 20 20 20 20 20 20 20 20 20 20 gv,..
4670: 20 72 65 66 20 49 6e 74 50 74 72 20 70 56 74 61 ref IntPtr pVta
4680: 62 2c 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 b,..
4690: 72 65 66 20 49 6e 74 50 74 72 20 70 45 72 72 6f ref IntPtr pErro
46a0: 72 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 29 r.. )
46b0: 3b 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ;.... ///
46c0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
46d0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
46e0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
46f0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
4700: 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 20 20 20 20 ////....
4710: 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20 /// <summary>..
4720: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 /// <para
4730: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 53 >.. /// S
4740: 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 78 QLite uses the x
4750: 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64 BestIndex method
4760: 20 6f 66 20 61 20 76 69 72 74 75 61 6c 20 74 61 of a virtual ta
4770: 62 6c 65 20 6d 6f 64 75 6c 65 20 74 6f 20 64 65 ble module to de
4780: 74 65 72 6d 69 6e 65 0d 0a 20 20 20 20 20 20 20 termine..
4790: 20 2f 2f 2f 20 74 68 65 20 62 65 73 74 20 77 61 /// the best wa
47a0: 79 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 y to access the
47b0: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 0d virtual table. .
47c0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 . /// The
47d0: 20 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68 xBestIndex meth
47e0: 6f 64 20 68 61 73 20 61 20 70 72 6f 74 6f 74 79 od has a prototy
47f0: 70 65 20 6c 69 6b 65 20 74 68 69 73 3a 0d 0a 20 pe like this:..
4800: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 /// </par
4810: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 a>.. ///
4820: 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 <para><code>..
4830: 20 20 20 20 20 20 2f 2f 2f 20 69 6e 74 20 28 2a /// int (*
4840: 78 42 65 73 74 49 6e 64 65 78 29 28 73 71 6c 69 xBestIndex)(sqli
4850: 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c te3_vtab *pVTab,
4860: 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 sqlite3_index_i
4870: 6e 66 6f 2a 29 3b 0d 0a 20 20 20 20 20 20 20 20 nfo*);..
4880: 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 /// </code></par
4890: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 a>.. ///
48a0: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 <para>..
48b0: 2f 2f 2f 20 54 68 65 20 53 51 4c 69 74 65 20 63 /// The SQLite c
48c0: 6f 72 65 20 63 6f 6d 6d 75 6e 69 63 61 74 65 73 ore communicates
48d0: 20 77 69 74 68 20 74 68 65 20 78 42 65 73 74 49 with the xBestI
48e0: 6e 64 65 78 20 6d 65 74 68 6f 64 20 62 79 20 66 ndex method by f
48f0: 69 6c 6c 69 6e 67 20 0d 0a 20 20 20 20 20 20 20 illing ..
4900: 20 2f 2f 2f 20 69 6e 20 63 65 72 74 61 69 6e 20 /// in certain
4910: 66 69 65 6c 64 73 20 6f 66 20 74 68 65 20 73 71 fields of the sq
4920: 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f lite3_index_info
4930: 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 20 70 structure and p
4940: 61 73 73 69 6e 67 20 61 20 0d 0a 20 20 20 20 20 assing a ..
4950: 20 20 20 2f 2f 2f 20 70 6f 69 6e 74 65 72 20 74 /// pointer t
4960: 6f 20 74 68 61 74 20 73 74 72 75 63 74 75 72 65 o that structure
4970: 20 69 6e 74 6f 20 78 42 65 73 74 49 6e 64 65 78 into xBestIndex
4980: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 as the second p
4990: 61 72 61 6d 65 74 65 72 2e 20 0d 0a 20 20 20 20 arameter. ..
49a0: 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 42 65 73 /// The xBes
49b0: 74 49 6e 64 65 78 20 6d 65 74 68 6f 64 20 66 69 tIndex method fi
49c0: 6c 6c 73 20 6f 75 74 20 6f 74 68 65 72 20 66 69 lls out other fi
49d0: 65 6c 64 73 20 6f 66 20 74 68 69 73 20 73 74 72 elds of this str
49e0: 75 63 74 75 72 65 20 77 68 69 63 68 0d 0a 20 20 ucture which..
49f0: 20 20 20 20 20 20 2f 2f 2f 20 66 6f 72 6d 73 20 /// forms
4a00: 74 68 65 20 72 65 70 6c 79 2e 20 54 68 65 20 73 the reply. The s
4a10: 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 qlite3_index_inf
4a20: 6f 20 73 74 72 75 63 74 75 72 65 20 6c 6f 6f 6b o structure look
4a30: 73 20 6c 69 6b 65 20 74 68 69 73 3a 0d 0a 20 20 s like this:..
4a40: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 /// </para
4a50: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c >.. /// <
4a60: 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 para><code>..
4a70: 20 20 20 20 20 2f 2f 2f 20 73 74 72 75 63 74 20 /// struct
4a80: 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e sqlite3_index_in
4a90: 66 6f 20 7b 0d 0a 20 20 20 20 20 20 20 20 2f 2f fo {.. //
4aa0: 2f 20 20 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f / /* Inputs */
4ab0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 .. ///
4ac0: 63 6f 6e 73 74 20 69 6e 74 20 6e 43 6f 6e 73 74 const int nConst
4ad0: 72 61 69 6e 74 3b 20 20 20 20 20 2f 2a 20 4e 75 raint; /* Nu
4ae0: 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20 mber of entries
4af0: 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 20 2a in aConstraint *
4b00: 2f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 /.. ///
4b10: 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 const struct sq
4b20: 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 lite3_index_cons
4b30: 74 72 61 69 6e 74 20 7b 0d 0a 20 20 20 20 20 20 traint {..
4b40: 20 20 2f 2f 2f 20 20 20 20 20 20 69 6e 74 20 69 /// int i
4b50: 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 Column;
4b60: 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 63 /* Column c
4b70: 6f 6e 73 74 72 61 69 6e 65 64 2e 20 20 2d 31 20 onstrained. -1
4b80: 66 6f 72 20 52 4f 57 49 44 20 2a 2f 0d 0a 20 20 for ROWID */..
4b90: 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 20 75 /// u
4ba0: 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b nsigned char op;
4bb0: 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 /* Cons
4bc0: 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 traint operator
4bd0: 2a 2f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 */.. ///
4be0: 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 unsigned ch
4bf0: 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20 20 2f ar usable; /
4c00: 2a 20 54 72 75 65 20 69 66 20 74 68 69 73 20 63 * True if this c
4c10: 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75 73 61 onstraint is usa
4c20: 62 6c 65 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20 ble */..
4c30: 2f 2f 2f 20 20 20 20 20 20 69 6e 74 20 69 54 65 /// int iTe
4c40: 72 6d 4f 66 66 73 65 74 3b 20 20 20 20 20 20 20 rmOffset;
4c50: 20 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 /* Used inter
4c60: 6e 61 6c 6c 79 20 2d 20 78 42 65 73 74 49 6e 64 nally - xBestInd
4c70: 65 78 20 73 68 6f 75 6c 64 20 69 67 6e 6f 72 65 ex should ignore
4c80: 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f */.. ///
4c90: 20 20 20 7d 20 2a 63 6f 6e 73 74 20 61 43 6f 6e } *const aCon
4ca0: 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 2f 2a straint; /*
4cb0: 20 54 61 62 6c 65 20 6f 66 20 57 48 45 52 45 20 Table of WHERE
4cc0: 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e clause constrain
4cd0: 74 73 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20 2f ts */.. /
4ce0: 2f 2f 20 20 20 63 6f 6e 73 74 20 69 6e 74 20 6e // const int n
4cf0: 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 OrderBy;
4d00: 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 /* Number of ter
4d10: 6d 73 20 69 6e 20 74 68 65 20 4f 52 44 45 52 20 ms in the ORDER
4d20: 42 59 20 63 6c 61 75 73 65 20 2a 2f 0d 0a 20 20 BY clause */..
4d30: 20 20 20 20 20 20 2f 2f 2f 20 20 20 63 6f 6e 73 /// cons
4d40: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 t struct sqlite3
4d50: 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62 79 20 7b _index_orderby {
4d60: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 .. ///
4d70: 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 int iColumn;
4d80: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
4d90: 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f Column number */
4da0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 .. ///
4db0: 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 unsigned char
4dc0: 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 desc; /*
4dd0: 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20 True for DESC.
4de0: 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a False for ASC. *
4df0: 2f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 /.. ///
4e00: 20 7d 20 2a 63 6f 6e 73 74 20 61 4f 72 64 65 72 } *const aOrder
4e10: 42 79 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 54 By; /* T
4e20: 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 he ORDER BY clau
4e30: 73 65 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20 2f se */.. /
4e40: 2f 2f 20 20 20 2f 2a 20 4f 75 74 70 75 74 73 20 // /* Outputs
4e50: 2a 2f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 */.. ///
4e60: 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 struct sqlite3
4e70: 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e _index_constrain
4e80: 74 5f 75 73 61 67 65 20 7b 0d 0a 20 20 20 20 20 t_usage {..
4e90: 20 20 20 2f 2f 2f 20 20 20 20 20 69 6e 74 20 61 /// int a
4ea0: 72 67 76 49 6e 64 65 78 3b 20 20 20 20 20 20 20 rgvIndex;
4eb0: 20 20 20 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f /* if >0, co
4ec0: 6e 73 74 72 61 69 6e 74 20 69 73 20 70 61 72 74 nstraint is part
4ed0: 20 6f 66 20 61 72 67 76 20 74 6f 20 78 46 69 6c of argv to xFil
4ee0: 74 65 72 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20 ter */..
4ef0: 2f 2f 2f 20 20 20 20 20 75 6e 73 69 67 6e 65 64 /// unsigned
4f00: 20 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 char omit;
4f10: 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 /* Do not code
4f20: 61 20 74 65 73 74 20 66 6f 72 20 74 68 69 73 20 a test for this
4f30: 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0d 0a 20 constraint */..
4f40: 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 7d 20 2a /// } *
4f50: 63 6f 6e 73 74 20 61 43 6f 6e 73 74 72 61 69 6e const aConstrain
4f60: 74 55 73 61 67 65 3b 0d 0a 20 20 20 20 20 20 20 tUsage;..
4f70: 20 2f 2f 2f 20 20 20 69 6e 74 20 69 64 78 4e 75 /// int idxNu
4f80: 6d 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 m;
4f90: 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 /* Number used
4fa0: 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65 to identify the
4fb0: 20 69 6e 64 65 78 20 2a 2f 0d 0a 20 20 20 20 20 index */..
4fc0: 20 20 20 2f 2f 2f 20 20 20 63 68 61 72 20 2a 69 /// char *i
4fd0: 64 78 53 74 72 3b 20 20 20 20 20 20 20 20 20 20 dxStr;
4fe0: 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 /* String, p
4ff0: 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 ossibly obtained
5000: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 from sqlite3_ma
5010: 6c 6c 6f 63 20 2a 2f 0d 0a 20 20 20 20 20 20 20 lloc */..
5020: 20 2f 2f 2f 20 20 20 69 6e 74 20 6e 65 65 64 54 /// int needT
5030: 6f 46 72 65 65 49 64 78 53 74 72 3b 20 20 20 20 oFreeIdxStr;
5040: 20 20 2f 2a 20 46 72 65 65 20 69 64 78 53 74 72 /* Free idxStr
5050: 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 using sqlite3_f
5060: 72 65 65 28 29 20 69 66 20 74 72 75 65 20 2a 2f ree() if true */
5070: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 .. ///
5080: 69 6e 74 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 int orderByConsu
5090: 6d 65 64 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 med; /* Tr
50a0: 75 65 20 69 66 20 6f 75 74 70 75 74 20 69 73 20 ue if output is
50b0: 61 6c 72 65 61 64 79 20 6f 72 64 65 72 65 64 20 already ordered
50c0: 2a 2f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 */.. ///
50d0: 20 20 64 6f 75 62 6c 65 20 65 73 74 69 6d 61 74 double estimat
50e0: 65 64 43 6f 73 74 3b 20 20 20 20 20 20 2f 2a 20 edCost; /*
50f0: 45 73 74 69 6d 61 74 65 64 20 63 6f 73 74 20 6f Estimated cost o
5100: 66 20 75 73 69 6e 67 20 74 68 69 73 20 69 6e 64 f using this ind
5110: 65 78 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20 2f ex */.. /
5120: 2f 2f 20 20 20 3c 21 5b 43 44 41 54 41 5b 3c 62 // <![CDATA[<b
5130: 3e 5d 5d 3e 2f 2a 20 46 69 65 6c 64 73 20 62 65 >]]>/* Fields be
5140: 6c 6f 77 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 low are only ava
5150: 69 6c 61 62 6c 65 20 69 6e 20 53 51 4c 69 74 65 ilable in SQLite
5160: 20 33 2e 38 2e 32 20 61 6e 64 20 6c 61 74 65 72 3.8.2 and later
5170: 20 2a 2f 3c 21 5b 43 44 41 54 41 5b 3c 2f 62 3e */<![CDATA[</b>
5180: 5d 5d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ]]>.. ///
5190: 20 20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 sqlite3_int64
51a0: 20 65 73 74 69 6d 61 74 65 64 52 6f 77 73 3b 20 estimatedRows;
51b0: 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 65 64 20 /* Estimated
51c0: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 72 number of rows r
51d0: 65 74 75 72 6e 65 64 20 2a 2f 0d 0a 20 20 20 20 eturned */..
51e0: 20 20 20 20 2f 2f 2f 20 20 20 3c 21 5b 43 44 41 /// <![CDA
51f0: 54 41 5b 3c 62 3e 5d 5d 3e 2f 2a 20 46 69 65 6c TA[<b>]]>/* Fiel
5200: 64 73 20 62 65 6c 6f 77 20 61 72 65 20 6f 6e 6c ds below are onl
5210: 79 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 53 y available in S
5220: 51 4c 69 74 65 20 33 2e 39 2e 30 20 61 6e 64 20 QLite 3.9.0 and
5230: 6c 61 74 65 72 20 2a 2f 3c 21 5b 43 44 41 54 41 later */<![CDATA
5240: 5b 3c 2f 62 3e 5d 5d 3e 0d 0a 20 20 20 20 20 20 [</b>]]>..
5250: 20 20 2f 2f 2f 20 20 20 69 6e 74 20 69 64 78 46 /// int idxF
5260: 6c 61 67 73 3b 20 20 20 20 20 20 20 20 20 20 20 lags;
5270: 20 20 20 2f 2a 20 4d 61 73 6b 20 6f 66 20 53 51 /* Mask of SQ
5280: 4c 49 54 45 5f 49 4e 44 45 58 5f 53 43 41 4e 5f LITE_INDEX_SCAN_
5290: 2a 20 66 6c 61 67 73 20 2a 2f 0d 0a 20 20 20 20 * flags */..
52a0: 20 20 20 20 2f 2f 2f 20 20 20 3c 21 5b 43 44 41 /// <![CDA
52b0: 54 41 5b 3c 62 3e 5d 5d 3e 2f 2a 20 46 69 65 6c TA[<b>]]>/* Fiel
52c0: 64 73 20 62 65 6c 6f 77 20 61 72 65 20 6f 6e 6c ds below are onl
52d0: 79 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 53 y available in S
52e0: 51 4c 69 74 65 20 33 2e 31 30 2e 30 20 61 6e 64 QLite 3.10.0 and
52f0: 20 6c 61 74 65 72 20 2a 2f 3c 21 5b 43 44 41 54 later */<![CDAT
5300: 41 5b 3c 2f 62 3e 5d 5d 3e 0d 0a 20 20 20 20 20 A[</b>]]>..
5310: 20 20 20 2f 2f 2f 20 20 20 73 71 6c 69 74 65 33 /// sqlite3
5320: 5f 75 69 6e 74 36 34 20 63 6f 6c 55 73 65 64 3b _uint64 colUsed;
5330: 20 20 20 20 2f 2a 20 49 6e 70 75 74 3a 20 4d 61 /* Input: Ma
5340: 73 6b 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 75 73 sk of columns us
5350: 65 64 20 62 79 20 73 74 61 74 65 6d 65 6e 74 20 ed by statement
5360: 2a 2f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 */.. ///
5370: 7d 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 };.. ///
5380: 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a </code></para>..
5390: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 /// <par
53a0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 a>.. ///
53b0: 4e 6f 74 65 20 74 68 65 20 77 61 72 6e 69 6e 67 Note the warning
53c0: 73 20 6f 6e 20 74 68 65 20 22 65 73 74 69 6d 61 s on the "estima
53d0: 74 65 64 52 6f 77 73 22 2c 20 22 69 64 78 46 6c tedRows", "idxFl
53e0: 61 67 73 22 2c 20 61 6e 64 20 63 6f 6c 55 73 65 ags", and colUse
53f0: 64 20 66 69 65 6c 64 73 2e 0d 0a 20 20 20 20 20 d fields...
5400: 20 20 20 2f 2f 2f 20 54 68 65 73 65 20 66 69 65 /// These fie
5410: 6c 64 73 20 77 65 72 65 20 61 64 64 65 64 20 77 lds were added w
5420: 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73 69 ith SQLite versi
5430: 6f 6e 73 20 33 2e 38 2e 32 2c 20 33 2e 39 2e 30 ons 3.8.2, 3.9.0
5440: 2c 20 61 6e 64 20 33 2e 31 30 2e 30 2c 20 72 65 , and 3.10.0, re
5450: 73 70 65 63 74 69 76 65 6c 79 2e 20 0d 0a 20 20 spectively. ..
5460: 20 20 20 20 20 20 2f 2f 2f 20 41 6e 79 20 65 78 /// Any ex
5470: 74 65 6e 73 69 6f 6e 20 74 68 61 74 20 72 65 61 tension that rea
5480: 64 73 20 6f 72 20 77 72 69 74 65 73 20 74 68 65 ds or writes the
5490: 73 65 20 66 69 65 6c 64 73 20 6d 75 73 74 20 66 se fields must f
54a0: 69 72 73 74 20 63 68 65 63 6b 20 74 68 61 74 20 irst check that
54b0: 74 68 65 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f the .. //
54c0: 2f 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 / version of the
54d0: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 SQLite library
54e0: 69 6e 20 75 73 65 20 69 73 20 67 72 65 61 74 65 in use is greate
54f0: 72 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 r than or equal
5500: 74 6f 20 61 70 70 72 6f 70 72 69 61 74 65 0d 0a to appropriate..
5510: 20 20 20 20 20 20 20 20 2f 2f 2f 20 76 65 72 73 /// vers
5520: 69 6f 6e 20 2d 20 70 65 72 68 61 70 73 20 63 6f ion - perhaps co
5530: 6d 70 61 72 69 6e 67 20 74 68 65 20 76 61 6c 75 mparing the valu
5540: 65 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 e returned from
5550: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 sqlite3_libversi
5560: 6f 6e 5f 6e 75 6d 62 65 72 28 29 0d 0a 20 20 20 on_number()..
5570: 20 20 20 20 20 2f 2f 2f 20 61 67 61 69 6e 73 74 /// against
5580: 20 63 6f 6e 73 74 61 6e 74 73 20 33 30 30 38 30 constants 30080
5590: 30 32 2c 20 33 30 30 39 30 30 30 2c 20 61 6e 64 02, 3009000, and
55a0: 2f 6f 72 20 33 30 31 30 30 30 30 2e 20 54 68 65 /or 3010000. The
55b0: 20 72 65 73 75 6c 74 20 6f 66 20 61 74 74 65 6d result of attem
55c0: 70 74 69 6e 67 20 0d 0a 20 20 20 20 20 20 20 20 pting ..
55d0: 2f 2f 2f 20 74 6f 20 61 63 63 65 73 73 20 74 68 /// to access th
55e0: 65 73 65 20 66 69 65 6c 64 73 20 69 6e 20 61 6e ese fields in an
55f0: 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 sqlite3_index_i
5600: 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20 63 72 nfo structure cr
5610: 65 61 74 65 64 20 62 79 20 61 6e 20 0d 0a 20 20 eated by an ..
5620: 20 20 20 20 20 20 2f 2f 2f 20 6f 6c 64 65 72 20 /// older
5630: 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 version of SQLit
5640: 65 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e e are undefined.
5650: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f .. /// </
5660: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f para>.. /
5670: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 // <para>..
5680: 20 20 20 2f 2f 2f 20 49 6e 20 61 64 64 69 74 69 /// In additi
5690: 6f 6e 2c 20 74 68 65 72 65 20 61 72 65 20 73 6f on, there are so
56a0: 6d 65 20 64 65 66 69 6e 65 64 20 63 6f 6e 73 74 me defined const
56b0: 61 6e 74 73 3a 0d 0a 20 20 20 20 20 20 20 20 2f ants:.. /
56c0: 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 // </para>..
56d0: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 /// <para><c
56e0: 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ode>.. //
56f0: 2f 20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 / #define SQLITE
5700: 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e _INDEX_CONSTRAIN
5710: 54 5f 45 51 20 20 20 20 20 20 20 20 20 32 0d 0a T_EQ 2..
5720: 20 20 20 20 20 20 20 20 2f 2f 2f 20 23 64 65 66 /// #def
5730: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 ine SQLITE_INDEX
5740: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 _CONSTRAINT_GT
5750: 20 20 20 20 20 20 20 34 0d 0a 20 20 20 20 20 20 4..
5760: 20 20 2f 2f 2f 20 23 64 65 66 69 6e 65 20 53 51 /// #define SQ
5770: 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 LITE_INDEX_CONST
5780: 52 41 49 4e 54 5f 4c 45 20 20 20 20 20 20 20 20 RAINT_LE
5790: 20 38 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 8.. ///
57a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
57b0: 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f NDEX_CONSTRAINT_
57c0: 4c 54 20 20 20 20 20 20 20 20 31 36 0d 0a 20 20 LT 16..
57d0: 20 20 20 20 20 20 2f 2f 2f 20 23 64 65 66 69 6e /// #defin
57e0: 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 e SQLITE_INDEX_C
57f0: 4f 4e 53 54 52 41 49 4e 54 5f 47 45 20 20 20 20 ONSTRAINT_GE
5800: 20 20 20 20 33 32 0d 0a 20 20 20 20 20 20 20 20 32..
5810: 2f 2f 2f 20 23 64 65 66 69 6e 65 20 53 51 4c 49 /// #define SQLI
5820: 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 TE_INDEX_CONSTRA
5830: 49 4e 54 5f 4d 41 54 43 48 20 20 20 20 20 36 34 INT_MATCH 64
5840: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 23 64 .. /// #d
5850: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 efine SQLITE_IND
5860: 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 49 EX_CONSTRAINT_LI
5870: 4b 45 20 20 20 20 20 20 36 35 20 20 2f 2a 20 33 KE 65 /* 3
5880: 2e 31 30 2e 30 20 61 6e 64 20 6c 61 74 65 72 20 .10.0 and later
5890: 2a 2f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 */.. ///
58a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
58b0: 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f NDEX_CONSTRAINT_
58c0: 47 4c 4f 42 20 20 20 20 20 20 36 36 20 20 2f 2a GLOB 66 /*
58d0: 20 33 2e 31 30 2e 30 20 61 6e 64 20 6c 61 74 65 3.10.0 and late
58e0: 72 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20 2f 2f r */.. //
58f0: 2f 20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 / #define SQLITE
5900: 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e _INDEX_CONSTRAIN
5910: 54 5f 52 45 47 45 58 50 20 20 20 20 36 37 20 20 T_REGEXP 67
5920: 2f 2a 20 33 2e 31 30 2e 30 20 61 6e 64 20 6c 61 /* 3.10.0 and la
5930: 74 65 72 20 2a 2f 0d 0a 20 20 20 20 20 20 20 20 ter */..
5940: 2f 2f 2f 20 23 64 65 66 69 6e 65 20 53 51 4c 49 /// #define SQLI
5950: 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 TE_INDEX_CONSTRA
5960: 49 4e 54 5f 4e 45 20 20 20 20 20 20 20 20 36 38 INT_NE 68
5970: 20 20 2f 2a 20 33 2e 32 31 2e 30 20 61 6e 64 20 /* 3.21.0 and
5980: 6c 61 74 65 72 20 2a 2f 0d 0a 20 20 20 20 20 20 later */..
5990: 20 20 2f 2f 2f 20 23 64 65 66 69 6e 65 20 53 51 /// #define SQ
59a0: 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 LITE_INDEX_CONST
59b0: 52 41 49 4e 54 5f 49 53 4e 4f 54 20 20 20 20 20 RAINT_ISNOT
59c0: 36 39 20 20 2f 2a 20 33 2e 32 31 2e 30 20 61 6e 69 /* 3.21.0 an
59d0: 64 20 6c 61 74 65 72 20 2a 2f 0d 0a 20 20 20 20 d later */..
59e0: 20 20 20 20 2f 2f 2f 20 23 64 65 66 69 6e 65 20 /// #define
59f0: 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e SQLITE_INDEX_CON
5a00: 53 54 52 41 49 4e 54 5f 49 53 4e 4f 54 4e 55 4c STRAINT_ISNOTNUL
5a10: 4c 20 37 30 20 20 2f 2a 20 33 2e 32 31 2e 30 20 L 70 /* 3.21.0
5a20: 61 6e 64 20 6c 61 74 65 72 20 2a 2f 0d 0a 20 20 and later */..
5a30: 20 20 20 20 20 20 2f 2f 2f 20 23 64 65 66 69 6e /// #defin
5a40: 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 e SQLITE_INDEX_C
5a50: 4f 4e 53 54 52 41 49 4e 54 5f 49 53 4e 55 4c 4c ONSTRAINT_ISNULL
5a60: 20 20 20 20 37 31 20 20 2f 2a 20 33 2e 32 31 2e 71 /* 3.21.
5a70: 30 20 61 6e 64 20 6c 61 74 65 72 20 2a 2f 0d 0a 0 and later */..
5a80: 20 20 20 20 20 20 20 20 2f 2f 2f 20 23 64 65 66 /// #def
5a90: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 ine SQLITE_INDEX
5aa0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 49 53 20 20 _CONSTRAINT_IS
5ab0: 20 20 20 20 20 20 37 32 20 20 2f 2a 20 33 2e 32 72 /* 3.2
5ac0: 31 2e 30 20 61 6e 64 20 6c 61 74 65 72 20 2a 2f 1.0 and later */
5ad0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 23 64 .. /// #d
5ae0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 efine SQLITE_IND
5af0: 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 EX_CONSTRAINT_FU
5b00: 4e 43 54 49 4f 4e 20 31 35 30 20 20 2f 2a 20 33 NCTION 150 /* 3
5b10: 2e 32 35 2e 30 20 61 6e 64 20 6c 61 74 65 72 20 .25.0 and later
5b20: 2a 2f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 */.. ///
5b30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5b40: 4e 44 45 58 5f 53 43 41 4e 5f 55 4e 49 51 55 45 NDEX_SCAN_UNIQUE
5b50: 20 20 20 20 20 20 20 20 20 20 20 31 20 20 2f 2a 1 /*
5b60: 20 53 63 61 6e 20 76 69 73 69 74 73 20 61 74 20 Scan visits at
5b70: 6d 6f 73 74 20 31 20 72 6f 77 20 2a 2f 0d 0a 20 most 1 row */..
5b80: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 /// </cod
5b90: 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 e></para>..
5ba0: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 /// <para>..
5bb0: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 53 /// The S
5bc0: 51 4c 69 74 65 20 63 6f 72 65 20 63 61 6c 6c 73 QLite core calls
5bd0: 20 74 68 65 20 78 42 65 73 74 49 6e 64 65 78 20 the xBestIndex
5be0: 6d 65 74 68 6f 64 20 77 68 65 6e 20 69 74 20 69 method when it i
5bf0: 73 20 63 6f 6d 70 69 6c 69 6e 67 20 61 20 71 75 s compiling a qu
5c00: 65 72 79 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ery.. ///
5c10: 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 61 that involves a
5c20: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 virtual table.
5c30: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 In other words,
5c40: 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 69 SQLite calls thi
5c50: 73 20 6d 65 74 68 6f 64 20 0d 0a 20 20 20 20 20 s method ..
5c60: 20 20 20 2f 2f 2f 20 77 68 65 6e 20 69 74 20 69 /// when it i
5c70: 73 20 72 75 6e 6e 69 6e 67 20 73 71 6c 69 74 65 s running sqlite
5c80: 33 5f 70 72 65 70 61 72 65 28 29 20 6f 72 20 74 3_prepare() or t
5c90: 68 65 20 65 71 75 69 76 61 6c 65 6e 74 2e 20 0d he equivalent. .
5ca0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 42 79 20 . /// By
5cb0: 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 6d 65 74 calling this met
5cc0: 68 6f 64 2c 20 74 68 65 20 0d 0a 20 20 20 20 20 hod, the ..
5cd0: 20 20 20 2f 2f 2f 20 53 51 4c 69 74 65 20 63 6f /// SQLite co
5ce0: 72 65 20 69 73 20 73 61 79 69 6e 67 20 74 6f 20 re is saying to
5cf0: 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c the virtual tabl
5d00: 65 20 74 68 61 74 20 69 74 20 6e 65 65 64 73 20 e that it needs
5d10: 74 6f 20 61 63 63 65 73 73 20 0d 0a 20 20 20 20 to access ..
5d20: 20 20 20 20 2f 2f 2f 20 73 6f 6d 65 20 73 75 62 /// some sub
5d30: 73 65 74 20 6f 66 20 74 68 65 20 72 6f 77 73 20 set of the rows
5d40: 69 6e 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 in the virtual t
5d50: 61 62 6c 65 20 61 6e 64 20 69 74 20 77 61 6e 74 able and it want
5d60: 73 20 74 6f 20 6b 6e 6f 77 20 74 68 65 0d 0a 20 s to know the..
5d70: 20 20 20 20 20 20 20 2f 2f 2f 20 6d 6f 73 74 20 /// most
5d80: 65 66 66 69 63 69 65 6e 74 20 77 61 79 20 74 6f efficient way to
5d90: 20 64 6f 20 74 68 61 74 20 61 63 63 65 73 73 2e do that access.
5da0: 20 54 68 65 20 78 42 65 73 74 49 6e 64 65 78 20 The xBestIndex
5db0: 6d 65 74 68 6f 64 20 72 65 70 6c 69 65 73 20 0d method replies .
5dc0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 77 69 74 . /// wit
5dd0: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 74 68 h information th
5de0: 61 74 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f at the SQLite co
5df0: 72 65 20 63 61 6e 20 74 68 65 6e 20 75 73 65 20 re can then use
5e00: 74 6f 20 63 6f 6e 64 75 63 74 20 61 6e 20 0d 0a to conduct an ..
5e10: 20 20 20 20 20 20 20 20 2f 2f 2f 20 65 66 66 69 /// effi
5e20: 63 69 65 6e 74 20 73 65 61 72 63 68 20 6f 66 20 cient search of
5e30: 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c the virtual tabl
5e40: 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 e... ///
5e50: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 </para>..
5e60: 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 /// <para>..
5e70: 20 20 20 20 20 2f 2f 2f 20 57 68 69 6c 65 20 63 /// While c
5e80: 6f 6d 70 69 6c 69 6e 67 20 61 20 73 69 6e 67 6c ompiling a singl
5e90: 65 20 53 51 4c 20 71 75 65 72 79 2c 20 74 68 65 e SQL query, the
5ea0: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6d 69 67 SQLite core mig
5eb0: 68 74 20 63 61 6c 6c 20 0d 0a 20 20 20 20 20 20 ht call ..
5ec0: 20 20 2f 2f 2f 20 78 42 65 73 74 49 6e 64 65 78 /// xBestIndex
5ed0: 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 multiple times
5ee0: 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 73 with different s
5ef0: 65 74 74 69 6e 67 73 20 69 6e 20 73 71 6c 69 74 ettings in sqlit
5f00: 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2e 0d 0a e3_index_info...
5f10: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 /// The
5f20: 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c SQLite core will
5f30: 20 74 68 65 6e 20 73 65 6c 65 63 74 20 74 68 65 then select the
5f40: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 74 68 61 combination tha
5f50: 74 20 61 70 70 65 61 72 73 20 74 6f 20 0d 0a 20 t appears to ..
5f60: 20 20 20 20 20 20 20 2f 2f 2f 20 67 69 76 65 20 /// give
5f70: 74 68 65 20 62 65 73 74 20 70 65 72 66 6f 72 6d the best perform
5f80: 61 6e 63 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f ance... /
5f90: 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 // </para>..
5fa0: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a /// <para>..
5fb0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 42 65 66 6f /// Befo
5fc0: 72 65 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 re calling this
5fd0: 6d 65 74 68 6f 64 2c 20 74 68 65 20 53 51 4c 69 method, the SQLi
5fe0: 74 65 20 63 6f 72 65 20 69 6e 69 74 69 61 6c 69 te core initiali
5ff0: 7a 65 73 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 zes an instance
6000: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6f 66 .. /// of
6010: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 the sqlite3_ind
6020: 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72 ex_info structur
6030: 65 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69 e with informati
6040: 6f 6e 20 61 62 6f 75 74 20 74 68 65 0d 0a 20 20 on about the..
6050: 20 20 20 20 20 20 2f 2f 2f 20 71 75 65 72 79 20 /// query
6060: 74 68 61 74 20 69 74 20 69 73 20 63 75 72 72 65 that it is curre
6070: 6e 74 6c 79 20 74 72 79 69 6e 67 20 74 6f 20 70 ntly trying to p
6080: 72 6f 63 65 73 73 2e 20 54 68 69 73 20 69 6e 66 rocess. This inf
6090: 6f 72 6d 61 74 69 6f 6e 20 0d 0a 20 20 20 20 20 ormation ..
60a0: 20 20 20 2f 2f 2f 20 64 65 72 69 76 65 73 20 6d /// derives m
60b0: 61 69 6e 6c 79 20 66 72 6f 6d 20 74 68 65 20 57 ainly from the W
60c0: 48 45 52 45 20 63 6c 61 75 73 65 20 61 6e 64 20 HERE clause and
60d0: 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 ORDER BY or GROU
60e0: 50 20 42 59 20 63 6c 61 75 73 65 73 20 0d 0a 20 P BY clauses ..
60f0: 20 20 20 20 20 20 20 2f 2f 2f 20 6f 66 20 74 68 /// of th
6100: 65 20 71 75 65 72 79 2c 20 62 75 74 20 61 6c 73 e query, but als
6110: 6f 20 66 72 6f 6d 20 61 6e 79 20 4f 4e 20 6f 72 o from any ON or
6120: 20 55 53 49 4e 47 20 63 6c 61 75 73 65 73 20 69 USING clauses i
6130: 66 20 74 68 65 20 71 75 65 72 79 20 69 73 20 61 f the query is a
6140: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6a .. /// j
6150: 6f 69 6e 2e 20 54 68 65 20 69 6e 66 6f 72 6d 61 oin. The informa
6160: 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20 53 51 tion that the SQ
6170: 4c 69 74 65 20 63 6f 72 65 20 70 72 6f 76 69 64 Lite core provid
6180: 65 73 20 74 6f 20 74 68 65 20 78 42 65 73 74 49 es to the xBestI
6190: 6e 64 65 78 20 0d 0a 20 20 20 20 20 20 20 20 2f ndex .. /
61a0: 2f 2f 20 6d 65 74 68 6f 64 20 69 73 20 68 65 6c // method is hel
61b0: 64 20 69 6e 20 74 68 65 20 70 61 72 74 20 6f 66 d in the part of
61c0: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 20 74 the structure t
61d0: 68 61 74 20 69 73 20 6d 61 72 6b 65 64 20 61 73 hat is marked as
61e0: 20 22 49 6e 70 75 74 73 22 2e 20 0d 0a 20 20 20 "Inputs". ..
61f0: 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 22 4f 75 /// The "Ou
6200: 74 70 75 74 73 22 20 73 65 63 74 69 6f 6e 20 69 tputs" section i
6210: 73 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 74 6f s initialized to
6220: 20 7a 65 72 6f 2e 0d 0a 20 20 20 20 20 20 20 20 zero...
6230: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 /// </para>..
6240: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d /// <para>.
6250: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 . /// The
6260: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 20 information in
6270: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 the sqlite3_inde
6280: 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65 x_info structure
6290: 20 69 73 20 65 70 68 65 6d 65 72 61 6c 0d 0a 20 is ephemeral..
62a0: 20 20 20 20 20 20 20 2f 2f 2f 20 61 6e 64 20 6d /// and m
62b0: 61 79 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 ay be overwritte
62c0: 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 n or deallocated
62d0: 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 as soon as the
62e0: 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f xBestIndex metho
62f0: 64 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 72 d.. /// r
6300: 65 74 75 72 6e 73 2e 20 20 49 66 20 74 68 65 20 eturns. If the
6310: 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f xBestIndex metho
6320: 64 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d d needs to remem
6330: 62 65 72 20 61 6e 79 20 70 61 72 74 20 6f 66 20 ber any part of
6340: 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f the.. ///
6350: 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 sqlite3_index_i
6360: 6e 66 6f 20 73 74 72 75 63 74 75 72 65 2c 20 69 nfo structure, i
6370: 74 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 61 20 t should make a
6380: 63 6f 70 79 2e 20 20 43 61 72 65 20 6d 75 73 74 copy. Care must
6390: 20 62 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f be.. ///
63a0: 20 74 61 6b 65 20 74 6f 20 73 74 6f 72 65 20 74 take to store t
63b0: 68 65 20 63 6f 70 79 20 69 6e 20 61 20 70 6c 61 he copy in a pla
63c0: 63 65 20 77 68 65 72 65 20 69 74 20 77 69 6c 6c ce where it will
63d0: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2c be deallocated,
63e0: 20 73 75 63 68 0d 0a 20 20 20 20 20 20 20 20 2f such.. /
63f0: 2f 2f 20 61 73 20 69 6e 20 74 68 65 20 69 64 78 // as in the idx
6400: 53 74 72 20 66 69 65 6c 64 20 77 69 74 68 20 6e Str field with n
6410: 65 65 64 54 6f 46 72 65 65 49 64 78 53 74 72 20 eedToFreeIdxStr
6420: 73 65 74 20 74 6f 20 31 2e 0d 0a 20 20 20 20 20 set to 1...
6430: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a /// </para>..
6440: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 /// <par
6450: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 a>.. ///
6460: 4e 6f 74 65 20 74 68 61 74 20 78 42 65 73 74 49 Note that xBestI
6470: 6e 64 65 78 20 77 69 6c 6c 20 61 6c 77 61 79 73 ndex will always
6480: 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 be called befor
6490: 65 20 78 46 69 6c 74 65 72 2c 20 73 69 6e 63 65 e xFilter, since
64a0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 .. /// th
64b0: 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 e idxNum and idx
64c0: 53 74 72 20 6f 75 74 70 75 74 73 20 66 72 6f 6d Str outputs from
64d0: 20 78 42 65 73 74 49 6e 64 65 78 20 61 72 65 20 xBestIndex are
64e0: 72 65 71 75 69 72 65 64 20 69 6e 70 75 74 73 20 required inputs
64f0: 74 6f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 to.. ///
6500: 78 46 69 6c 74 65 72 2e 20 20 48 6f 77 65 76 65 xFilter. Howeve
6510: 72 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67 r, there is no g
6520: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 78 46 uarantee that xF
6530: 69 6c 74 65 72 20 77 69 6c 6c 20 62 65 20 63 61 ilter will be ca
6540: 6c 6c 65 64 0d 0a 20 20 20 20 20 20 20 20 2f 2f lled.. //
6550: 2f 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 73 75 / following a su
6560: 63 63 65 73 73 66 75 6c 20 78 42 65 73 74 49 6e ccessful xBestIn
6570: 64 65 78 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f dex... //
6580: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 / </para>..
6590: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 /// <para>..
65a0: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 /// The x
65b0: 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64 BestIndex method
65c0: 20 69 73 20 72 65 71 75 69 72 65 64 20 66 6f 72 is required for
65d0: 20 65 76 65 72 79 20 76 69 72 74 75 61 6c 20 74 every virtual t
65e0: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 able implementat
65f0: 69 6f 6e 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ion... //
6600: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 / </para>..
6610: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 /// <para>..
6620: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 6d /// The m
6630: 61 69 6e 20 74 68 69 6e 67 20 74 68 61 74 20 74 ain thing that t
6640: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 69 he SQLite core i
6650: 73 20 74 72 79 69 6e 67 20 74 6f 20 63 6f 6d 6d s trying to comm
6660: 75 6e 69 63 61 74 65 20 74 6f 20 0d 0a 20 20 20 unicate to ..
6670: 20 20 20 20 20 2f 2f 2f 20 74 68 65 20 76 69 72 /// the vir
6680: 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20 74 68 tual table is th
6690: 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 74 68 e constraints th
66a0: 61 74 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 at are available
66b0: 20 74 6f 20 6c 69 6d 69 74 20 0d 0a 20 20 20 20 to limit ..
66c0: 20 20 20 20 2f 2f 2f 20 74 68 65 20 6e 75 6d 62 /// the numb
66d0: 65 72 20 6f 66 20 72 6f 77 73 20 74 68 61 74 20 er of rows that
66e0: 6e 65 65 64 20 74 6f 20 62 65 20 73 65 61 72 63 need to be searc
66f0: 68 65 64 2e 20 54 68 65 20 61 43 6f 6e 73 74 72 hed. The aConstr
6700: 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 0d 0a 20 aint[] array ..
6710: 20 20 20 20 20 20 20 2f 2f 2f 20 63 6f 6e 74 61 /// conta
6720: 69 6e 73 20 6f 6e 65 20 65 6e 74 72 79 20 66 6f ins one entry fo
6730: 72 20 65 61 63 68 20 63 6f 6e 73 74 72 61 69 6e r each constrain
6740: 74 2e 20 54 68 65 72 65 20 77 69 6c 6c 20 62 65 t. There will be
6750: 20 65 78 61 63 74 6c 79 20 0d 0a 20 20 20 20 20 exactly ..
6760: 20 20 20 2f 2f 2f 20 6e 43 6f 6e 73 74 72 61 69 /// nConstrai
6770: 6e 74 20 65 6e 74 72 69 65 73 20 69 6e 20 74 68 nt entries in th
6780: 61 74 20 61 72 72 61 79 2e 0d 0a 20 20 20 20 20 at array...
6790: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a /// </para>..
67a0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 /// <par
67b0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 a>.. ///
67c0: 45 61 63 68 20 63 6f 6e 73 74 72 61 69 6e 74 20 Each constraint
67d0: 77 69 6c 6c 20 75 73 75 61 6c 6c 79 20 63 6f 72 will usually cor
67e0: 72 65 73 70 6f 6e 64 20 74 6f 20 61 20 74 65 72 respond to a ter
67f0: 6d 20 69 6e 20 74 68 65 20 57 48 45 52 45 20 63 m in the WHERE c
6800: 6c 61 75 73 65 0d 0a 20 20 20 20 20 20 20 20 2f lause.. /
6810: 2f 2f 20 6f 72 20 69 6e 20 61 20 55 53 49 4e 47 // or in a USING
6820: 20 6f 72 20 4f 4e 20 63 6c 61 75 73 65 20 74 68 or ON clause th
6830: 61 74 20 69 73 20 6f 66 20 74 68 65 20 66 6f 72 at is of the for
6840: 6d 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c m.. /// <
6850: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 /para>..
6860: 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e /// <para><code>
6870: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 .. ///
6880: 20 20 20 63 6f 6c 75 6d 6e 20 20 4f 50 20 20 45 column OP E
6890: 58 50 52 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f XPR.. ///
68a0: 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d </code></para>.
68b0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 . /// <pa
68c0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ra>.. ///
68d0: 20 57 68 65 72 65 20 22 63 6f 6c 75 6d 6e 22 20 Where "column"
68e0: 69 73 20 61 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 is a column in t
68f0: 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 he virtual table
6900: 2c 20 4f 50 20 69 73 20 61 6e 20 6f 70 65 72 61 , OP is an opera
6910: 74 6f 72 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f tor .. //
6920: 2f 20 6c 69 6b 65 20 22 3d 22 20 6f 72 20 22 26 / like "=" or "&
6930: 6c 74 3b 22 2c 20 61 6e 64 20 45 58 50 52 20 69 lt;", and EXPR i
6940: 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 65 s an arbitrary e
6950: 78 70 72 65 73 73 69 6f 6e 2e 20 53 6f 2c 20 66 xpression. So, f
6960: 6f 72 20 65 78 61 6d 70 6c 65 2c 0d 0a 20 20 20 or example,..
6970: 20 20 20 20 20 2f 2f 2f 20 69 66 20 74 68 65 20 /// if the
6980: 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e WHERE clause con
6990: 74 61 69 6e 65 64 20 61 20 74 65 72 6d 20 6c 69 tained a term li
69a0: 6b 65 20 74 68 69 73 3a 0d 0a 20 20 20 20 20 20 ke this:..
69b0: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 /// </para>..
69c0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 /// <para
69d0: 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20 ><code>..
69e0: 20 2f 2f 2f 20 61 20 3d 20 35 0d 0a 20 20 20 20 /// a = 5..
69f0: 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c /// </code><
6a00: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 /para>..
6a10: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 /// <para>..
6a20: 20 20 20 20 2f 2f 2f 20 54 68 65 6e 20 6f 6e 65 /// Then one
6a30: 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 72 61 69 of the constrai
6a40: 6e 74 73 20 77 6f 75 6c 64 20 62 65 20 6f 6e 20 nts would be on
6a50: 74 68 65 20 22 61 22 20 63 6f 6c 75 6d 6e 20 77 the "a" column w
6a60: 69 74 68 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f ith .. //
6a70: 2f 20 6f 70 65 72 61 74 6f 72 20 22 3d 22 20 61 / operator "=" a
6a80: 6e 64 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e nd an expression
6a90: 20 6f 66 20 22 35 22 2e 20 43 6f 6e 73 74 72 61 of "5". Constra
6aa0: 69 6e 74 73 20 6e 65 65 64 20 6e 6f 74 20 68 61 ints need not ha
6ab0: 76 65 20 61 0d 0a 20 20 20 20 20 20 20 20 2f 2f ve a.. //
6ac0: 2f 20 6c 69 74 65 72 61 6c 20 72 65 70 72 65 73 / literal repres
6ad0: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 entation of the
6ae0: 57 48 45 52 45 20 63 6c 61 75 73 65 2e 20 54 68 WHERE clause. Th
6af0: 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 e query optimize
6b00: 72 20 6d 69 67 68 74 0d 0a 20 20 20 20 20 20 20 r might..
6b10: 20 2f 2f 2f 20 6d 61 6b 65 20 74 72 61 6e 73 66 /// make transf
6b20: 6f 72 6d 61 74 69 6f 6e 73 20 74 6f 20 74 68 65 ormations to the
6b30: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 57 .. /// W
6b40: 48 45 52 45 20 63 6c 61 75 73 65 20 69 6e 20 6f HERE clause in o
6b50: 72 64 65 72 20 74 6f 20 65 78 74 72 61 63 74 20 rder to extract
6b60: 61 73 20 6d 61 6e 79 20 63 6f 6e 73 74 72 61 69 as many constrai
6b70: 6e 74 73 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f nts .. //
6b80: 2f 20 61 73 20 69 74 20 63 61 6e 2e 20 53 6f 2c / as it can. So,
6b90: 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 for example, if
6ba0: 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 the WHERE claus
6bb0: 65 20 63 6f 6e 74 61 69 6e 65 64 20 73 6f 6d 65 e contained some
6bc0: 74 68 69 6e 67 20 0d 0a 20 20 20 20 20 20 20 20 thing ..
6bd0: 2f 2f 2f 20 6c 69 6b 65 20 74 68 69 73 3a 0d 0a /// like this:..
6be0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 /// </pa
6bf0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ra>.. ///
6c00: 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 <para><code>..
6c10: 20 20 20 20 20 20 20 2f 2f 2f 20 78 20 42 45 54 /// x BET
6c20: 57 45 45 4e 20 31 30 20 41 4e 44 20 31 30 30 20 WEEN 10 AND 100
6c30: 41 4e 44 20 39 39 39 26 67 74 3b 79 0d 0a 20 20 AND 999>y..
6c40: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 /// </code
6c50: 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 ></para>..
6c60: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 /// <para>..
6c70: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 71 75 /// The qu
6c80: 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 20 6d 69 ery optimizer mi
6c90: 67 68 74 20 74 72 61 6e 73 6c 61 74 65 20 74 68 ght translate th
6ca0: 69 73 20 69 6e 74 6f 20 74 68 72 65 65 20 73 65 is into three se
6cb0: 70 61 72 61 74 65 20 63 6f 6e 73 74 72 61 69 6e parate constrain
6cc0: 74 73 3a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ts:.. ///
6cd0: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 </para>..
6ce0: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 /// <para><cod
6cf0: 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 e>.. ///
6d00: 78 20 26 67 74 3b 3d 20 31 30 0d 0a 20 20 20 20 x >= 10..
6d10: 20 20 20 20 2f 2f 2f 20 78 20 26 6c 74 3b 3d 20 /// x <=
6d20: 31 30 30 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 100.. ///
6d30: 20 79 20 26 6c 74 3b 20 39 39 39 0d 0a 20 20 20 y < 999..
6d40: 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e /// </code>
6d50: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 </para>..
6d60: 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 /// <para>..
6d70: 20 20 20 20 20 2f 2f 2f 20 46 6f 72 20 65 61 63 /// For eac
6d80: 68 20 73 75 63 68 20 63 6f 6e 73 74 72 61 69 6e h such constrain
6d90: 74 2c 20 74 68 65 20 61 43 6f 6e 73 74 72 61 69 t, the aConstrai
6da0: 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 20 66 69 65 nt[].iColumn fie
6db0: 6c 64 20 69 6e 64 69 63 61 74 65 73 20 77 68 69 ld indicates whi
6dc0: 63 68 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ch .. ///
6dd0: 20 63 6f 6c 75 6d 6e 20 61 70 70 65 61 72 73 20 column appears
6de0: 6f 6e 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 on the left-hand
6df0: 20 73 69 64 65 20 6f 66 20 74 68 65 20 63 6f 6e side of the con
6e00: 73 74 72 61 69 6e 74 2e 0d 0a 20 20 20 20 20 20 straint...
6e10: 20 20 2f 2f 2f 20 54 68 65 20 66 69 72 73 74 20 /// The first
6e20: 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 76 69 column of the vi
6e30: 72 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20 63 rtual table is c
6e40: 6f 6c 75 6d 6e 20 30 2e 20 0d 0a 20 20 20 20 20 olumn 0. ..
6e50: 20 20 20 2f 2f 2f 20 54 68 65 20 72 6f 77 69 64 /// The rowid
6e60: 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 of the virtual
6e70: 74 61 62 6c 65 20 69 73 20 63 6f 6c 75 6d 6e 20 table is column
6e80: 2d 31 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f -1. .. //
6e90: 2f 20 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e / The aConstrain
6ea0: 74 5b 5d 2e 6f 70 20 66 69 65 6c 64 20 69 6e 64 t[].op field ind
6eb0: 69 63 61 74 65 73 20 77 68 69 63 68 20 6f 70 65 icates which ope
6ec0: 72 61 74 6f 72 20 69 73 20 75 73 65 64 2e 20 0d rator is used. .
6ed0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 . /// The
6ee0: 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f SQLITE_INDEX_CO
6ef0: 4e 53 54 52 41 49 4e 54 5f 2a 20 63 6f 6e 73 74 NSTRAINT_* const
6f00: 61 6e 74 73 20 6d 61 70 20 69 6e 74 65 67 65 72 ants map integer
6f10: 20 63 6f 6e 73 74 61 6e 74 73 20 0d 0a 20 20 20 constants ..
6f20: 20 20 20 20 20 2f 2f 2f 20 69 6e 74 6f 20 6f 70 /// into op
6f30: 65 72 61 74 6f 72 20 76 61 6c 75 65 73 2e 0d 0a erator values...
6f40: 20 20 20 20 20 20 20 20 2f 2f 2f 20 43 6f 6c 75 /// Colu
6f50: 6d 6e 73 20 6f 63 63 75 72 20 69 6e 20 74 68 65 mns occur in the
6f60: 20 6f 72 64 65 72 20 74 68 65 79 20 77 65 72 65 order they were
6f70: 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 65 20 defined by the
6f80: 63 61 6c 6c 20 74 6f 0d 0a 20 20 20 20 20 20 20 call to..
6f90: 20 2f 2f 2f 20 73 71 6c 69 74 65 33 5f 64 65 63 /// sqlite3_dec
6fa0: 6c 61 72 65 5f 76 74 61 62 28 29 20 69 6e 20 74 lare_vtab() in t
6fb0: 68 65 20 78 43 72 65 61 74 65 20 6f 72 20 78 43 he xCreate or xC
6fc0: 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64 2e 0d 0a onnect method...
6fd0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 48 69 64 64 /// Hidd
6fe0: 65 6e 20 63 6f 6c 75 6d 6e 73 20 61 72 65 20 63 en columns are c
6ff0: 6f 75 6e 74 65 64 20 77 68 65 6e 20 64 65 74 65 ounted when dete
7000: 72 6d 69 6e 69 6e 67 20 74 68 65 20 63 6f 6c 75 rmining the colu
7010: 6d 6e 20 69 6e 64 65 78 2e 0d 0a 20 20 20 20 20 mn index...
7020: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a /// </para>..
7030: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 /// <par
7040: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 a>.. ///
7050: 49 66 20 74 68 65 20 78 46 69 6e 64 46 75 6e 63 If the xFindFunc
7060: 74 69 6f 6e 28 29 20 6d 65 74 68 6f 64 20 66 6f tion() method fo
7070: 72 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 r the virtual ta
7080: 62 6c 65 20 69 73 20 64 65 66 69 6e 65 64 2c 20 ble is defined,
7090: 61 6e 64 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f and .. //
70a0: 2f 20 69 66 20 78 46 69 6e 64 46 75 6e 63 74 69 / if xFindFuncti
70b0: 6f 6e 28 29 20 73 6f 6d 65 74 69 6d 65 73 20 72 on() sometimes r
70c0: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4e eturns SQLITE_IN
70d0: 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 DEX_CONSTRAINT_F
70e0: 55 4e 43 54 49 4f 4e 20 6f 72 0d 0a 20 20 20 20 UNCTION or..
70f0: 20 20 20 20 2f 2f 2f 20 6c 61 72 67 65 72 2c 20 /// larger,
7100: 74 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 72 61 then the constra
7110: 69 6e 74 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 ints might also
7120: 62 65 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0d be of the form:.
7130: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 . /// </p
7140: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ara>.. //
7150: 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a / <para><code>..
7160: 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 ///
7170: 20 46 55 4e 43 54 49 4f 4e 28 20 63 6f 6c 75 6d FUNCTION( colum
7180: 6e 2c 20 45 58 50 52 29 0d 0a 20 20 20 20 20 20 n, EXPR)..
7190: 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 /// </code></p
71a0: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ara>.. //
71b0: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 / <para>..
71c0: 20 20 2f 2f 2f 20 49 6e 20 74 68 69 73 20 63 61 /// In this ca
71d0: 73 65 20 74 68 65 20 61 43 6f 6e 73 74 72 61 69 se the aConstrai
71e0: 6e 74 5b 5d 2e 6f 70 20 76 61 6c 75 65 20 69 73 nt[].op value is
71f0: 20 74 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 the same as the
7200: 20 76 61 6c 75 65 0d 0a 20 20 20 20 20 20 20 20 value..
7210: 2f 2f 2f 20 72 65 74 75 72 6e 65 64 20 62 79 20 /// returned by
7220: 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 28 29 20 xFindFunction()
7230: 66 6f 72 20 46 55 4e 43 54 49 4f 4e 2e 0d 0a 20 for FUNCTION...
7240: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 /// </par
7250: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 a>.. ///
7260: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 <para>..
7270: 2f 2f 2f 20 54 68 65 20 61 43 6f 6e 73 74 72 61 /// The aConstra
7280: 69 6e 74 5b 5d 20 61 72 72 61 79 20 63 6f 6e 74 int[] array cont
7290: 61 69 6e 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e ains information
72a0: 20 61 62 6f 75 74 20 61 6c 6c 20 63 6f 6e 73 74 about all const
72b0: 72 61 69 6e 74 73 20 0d 0a 20 20 20 20 20 20 20 raints ..
72c0: 20 2f 2f 2f 20 74 68 61 74 20 61 70 70 6c 79 20 /// that apply
72d0: 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 to the virtual t
72e0: 61 62 6c 65 2e 20 42 75 74 20 73 6f 6d 65 20 6f able. But some o
72f0: 66 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 f the constraint
7300: 73 20 6d 69 67 68 74 0d 0a 20 20 20 20 20 20 20 s might..
7310: 20 2f 2f 2f 20 6e 6f 74 20 62 65 20 75 73 61 62 /// not be usab
7320: 6c 65 20 62 65 63 61 75 73 65 20 6f 66 20 74 68 le because of th
7330: 65 20 77 61 79 20 74 61 62 6c 65 73 20 61 72 65 e way tables are
7340: 20 6f 72 64 65 72 65 64 20 69 6e 20 61 20 6a 6f ordered in a jo
7350: 69 6e 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f in. .. //
7360: 2f 20 54 68 65 20 78 42 65 73 74 49 6e 64 65 78 / The xBestIndex
7370: 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 74 68 65 method must the
7380: 72 65 66 6f 72 65 20 6f 6e 6c 79 20 63 6f 6e 73 refore only cons
7390: 69 64 65 72 20 63 6f 6e 73 74 72 61 69 6e 74 73 ider constraints
73a0: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 .. /// t
73b0: 68 61 74 20 68 61 76 65 20 61 6e 20 61 43 6f 6e hat have an aCon
73c0: 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 straint[].usable
73d0: 20 66 6c 61 67 20 77 68 69 63 68 20 69 73 20 74 flag which is t
73e0: 72 75 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f rue... //
73f0: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 / </para>..
7400: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 /// <para>..
7410: 20 20 20 20 20 20 20 2f 2f 2f 20 49 6e 20 61 64 /// In ad
7420: 64 69 74 69 6f 6e 20 74 6f 20 57 48 45 52 45 20 dition to WHERE
7430: 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e clause constrain
7440: 74 73 2c 20 74 68 65 20 53 51 4c 69 74 65 20 63 ts, the SQLite c
7450: 6f 72 65 20 61 6c 73 6f 20 0d 0a 20 20 20 20 20 ore also ..
7460: 20 20 20 2f 2f 2f 20 74 65 6c 6c 73 20 74 68 65 /// tells the
7470: 20 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68 xBestIndex meth
7480: 6f 64 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 od about the ORD
7490: 45 52 20 42 59 20 63 6c 61 75 73 65 2e 20 0d 0a ER BY clause. ..
74a0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 28 49 6e 20 /// (In
74b0: 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65 an aggregate que
74c0: 72 79 2c 20 74 68 65 20 53 51 4c 69 74 65 20 63 ry, the SQLite c
74d0: 6f 72 65 20 6d 69 67 68 74 20 70 75 74 20 69 6e ore might put in
74e0: 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 GROUP BY clause
74f0: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 .. /// i
7500: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 20 70 6c nformation in pl
7510: 61 63 65 20 6f 66 20 74 68 65 20 4f 52 44 45 52 ace of the ORDER
7520: 20 42 59 20 63 6c 61 75 73 65 20 69 6e 66 6f 72 BY clause infor
7530: 6d 61 74 69 6f 6e 2c 20 62 75 74 20 74 68 69 73 mation, but this
7540: 20 66 61 63 74 0d 0a 20 20 20 20 20 20 20 20 2f fact.. /
7550: 2f 2f 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61 // should not ma
7560: 6b 65 20 61 6e 79 20 64 69 66 66 65 72 65 6e 63 ke any differenc
7570: 65 20 74 6f 20 74 68 65 20 78 42 65 73 74 49 6e e to the xBestIn
7580: 64 65 78 20 6d 65 74 68 6f 64 2e 29 20 0d 0a 20 dex method.) ..
7590: 20 20 20 20 20 20 20 2f 2f 2f 20 49 66 20 61 6c /// If al
75a0: 6c 20 74 65 72 6d 73 20 6f 66 20 74 68 65 20 4f l terms of the O
75b0: 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 61 RDER BY clause a
75c0: 72 65 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 re columns in th
75d0: 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2c e virtual table,
75e0: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 .. /// t
75f0: 68 65 6e 20 6e 4f 72 64 65 72 42 79 20 77 69 6c hen nOrderBy wil
7600: 6c 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 l be the number
7610: 6f 66 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20 of terms in the
7620: 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 ORDER BY clause
7630: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 61 6e .. /// an
7640: 64 20 74 68 65 20 61 4f 72 64 65 72 42 79 5b 5d d the aOrderBy[]
7650: 20 61 72 72 61 79 20 77 69 6c 6c 20 69 64 65 6e array will iden
7660: 74 69 66 79 20 74 68 65 20 63 6f 6c 75 6d 6e 20 tify the column
7670: 66 6f 72 20 65 61 63 68 20 74 65 72 6d 20 0d 0a for each term ..
7680: 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e 20 74 /// in t
7690: 68 65 20 6f 72 64 65 72 20 62 79 20 63 6c 61 75 he order by clau
76a0: 73 65 20 61 6e 64 20 77 68 65 74 68 65 72 20 6f se and whether o
76b0: 72 20 6e 6f 74 20 74 68 61 74 20 63 6f 6c 75 6d r not that colum
76c0: 6e 20 69 73 20 41 53 43 20 6f 72 20 44 45 53 43 n is ASC or DESC
76d0: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c ... /// <
76e0: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 /para>..
76f0: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 /// <para>..
7700: 20 20 20 20 2f 2f 2f 20 49 6e 20 53 51 4c 69 74 /// In SQLit
7710: 65 20 76 65 72 73 69 6f 6e 20 33 2e 31 30 2e 30 e version 3.10.0
7720: 20 28 32 30 31 36 2d 30 31 2d 30 36 29 20 61 6e (2016-01-06) an
7730: 64 20 6c 61 74 65 72 2c 20 0d 0a 20 20 20 20 20 d later, ..
7740: 20 20 20 2f 2f 2f 20 74 68 65 20 63 6f 6c 55 73 /// the colUs
7750: 65 64 20 66 69 65 6c 64 20 69 73 20 61 76 61 69 ed field is avai
7760: 6c 61 62 6c 65 0d 0a 20 20 20 20 20 20 20 20 2f lable.. /
7770: 2f 2f 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 // to indicate w
7780: 68 69 63 68 20 66 69 65 6c 64 73 20 6f 66 20 74 hich fields of t
7790: 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 he virtual table
77a0: 20 61 72 65 20 61 63 74 75 61 6c 6c 79 20 75 73 are actually us
77b0: 65 64 20 62 79 20 74 68 65 0d 0a 20 20 20 20 20 ed by the..
77c0: 20 20 20 2f 2f 2f 20 73 74 61 74 65 6d 65 6e 74 /// statement
77d0: 20 62 65 69 6e 67 20 70 72 65 70 61 72 65 64 2e being prepared.
77e0: 20 20 49 66 20 74 68 65 20 6c 6f 77 65 73 74 20 If the lowest
77f0: 62 69 74 20 6f 66 20 63 6f 6c 55 73 65 64 20 69 bit of colUsed i
7800: 73 20 73 65 74 2c 20 74 68 61 74 0d 0a 20 20 20 s set, that..
7810: 20 20 20 20 20 2f 2f 2f 20 6d 65 61 6e 73 20 74 /// means t
7820: 68 61 74 20 74 68 65 20 66 69 72 73 74 20 63 6f hat the first co
7830: 6c 75 6d 6e 20 69 73 20 75 73 65 64 2e 20 20 54 lumn is used. T
7840: 68 65 20 73 65 63 6f 6e 64 20 6c 6f 77 65 73 74 he second lowest
7850: 20 62 69 74 20 63 6f 72 72 65 73 70 6f 6e 64 73 bit corresponds
7860: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 6f .. /// to
7870: 20 74 68 65 20 73 65 63 6f 6e 64 20 63 6f 6c 75 the second colu
7880: 6d 6e 2e 20 20 41 6e 64 20 73 6f 20 66 6f 72 74 mn. And so fort
7890: 68 2e 20 20 49 66 20 74 68 65 20 6d 6f 73 74 20 h. If the most
78a0: 73 69 67 6e 69 66 69 63 61 6e 74 20 62 69 74 20 significant bit
78b0: 6f 66 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 of.. ///
78c0: 63 6f 6c 55 73 65 64 20 69 73 20 73 65 74 2c 20 colUsed is set,
78d0: 74 68 61 74 20 6d 65 61 6e 73 20 74 68 61 74 20 that means that
78e0: 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 75 one or more colu
78f0: 6d 6e 73 20 6f 74 68 65 72 20 74 68 61 6e 20 74 mns other than t
7900: 68 65 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f he .. ///
7910: 20 66 69 72 73 74 20 36 33 20 63 6f 6c 75 6d 6e first 63 column
7920: 73 20 61 72 65 20 75 73 65 64 2e 20 20 49 66 20 s are used. If
7930: 63 6f 6c 75 6d 6e 20 75 73 61 67 65 20 69 6e 66 column usage inf
7940: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 6e 65 65 64 ormation is need
7950: 65 64 20 62 79 20 74 68 65 0d 0a 20 20 20 20 20 ed by the..
7960: 20 20 20 2f 2f 2f 20 78 46 69 6c 74 65 72 20 6d /// xFilter m
7970: 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 ethod, then the
7980: 72 65 71 75 69 72 65 64 20 62 69 74 73 20 6d 75 required bits mu
7990: 73 74 20 62 65 20 65 6e 63 6f 64 65 64 20 69 6e st be encoded in
79a0: 74 6f 20 65 69 74 68 65 72 0d 0a 20 20 20 20 20 to either..
79b0: 20 20 20 2f 2f 2f 20 74 68 65 20 69 64 78 4e 75 /// the idxNu
79c0: 6d 20 6f 72 20 69 64 78 53 74 72 20 6f 75 74 70 m or idxStr outp
79d0: 75 74 20 66 69 65 6c 64 73 2e 0d 0a 20 20 20 20 ut fields...
79e0: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d /// </para>.
79f0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 . /// <pa
7a00: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ra>.. ///
7a10: 20 47 69 76 65 6e 20 61 6c 6c 20 6f 66 20 74 68 Given all of th
7a20: 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 e information ab
7a30: 6f 76 65 2c 20 74 68 65 20 6a 6f 62 20 6f 66 20 ove, the job of
7a40: 74 68 65 20 78 42 65 73 74 49 6e 64 65 78 20 0d the xBestIndex .
7a50: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6d 65 74 . /// met
7a60: 68 6f 64 20 69 74 20 74 6f 20 66 69 67 75 72 65 hod it to figure
7a70: 20 6f 75 74 20 74 68 65 20 62 65 73 74 20 77 61 out the best wa
7a80: 79 20 74 6f 20 73 65 61 72 63 68 20 74 68 65 20 y to search the
7a90: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 0d 0a virtual table...
7aa0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 /// </pa
7ab0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ra>.. ///
7ac0: 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 <para>..
7ad0: 20 2f 2f 2f 20 54 68 65 20 78 42 65 73 74 49 6e /// The xBestIn
7ae0: 64 65 78 20 6d 65 74 68 6f 64 20 66 69 6c 6c 73 dex method fills
7af0: 20 74 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 the idxNum and
7b00: 69 64 78 53 74 72 20 66 69 65 6c 64 73 20 77 69 idxStr fields wi
7b10: 74 68 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f th .. ///
7b20: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 74 68 61 information tha
7b30: 74 20 63 6f 6d 6d 75 6e 69 63 61 74 65 73 20 61 t communicates a
7b40: 6e 20 69 6e 64 65 78 69 6e 67 20 73 74 72 61 74 n indexing strat
7b50: 65 67 79 20 74 6f 20 74 68 65 20 78 46 69 6c 74 egy to the xFilt
7b60: 65 72 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f er .. ///
7b70: 20 6d 65 74 68 6f 64 2e 20 54 68 65 20 69 6e 66 method. The inf
7b80: 6f 72 6d 61 74 69 6f 6e 20 69 6e 20 69 64 78 4e ormation in idxN
7b90: 75 6d 20 61 6e 64 20 69 64 78 53 74 72 20 69 73 um and idxStr is
7ba0: 20 61 72 62 69 74 72 61 72 79 20 61 73 20 66 61 arbitrary as fa
7bb0: 72 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 r .. ///
7bc0: 61 73 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f as the SQLite co
7bd0: 72 65 20 69 73 20 63 6f 6e 63 65 72 6e 65 64 2e re is concerned.
7be0: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 The SQLite core
7bf0: 20 6a 75 73 74 20 63 6f 70 69 65 73 20 74 68 65 just copies the
7c00: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 .. /// i
7c10: 6e 66 6f 72 6d 61 74 69 6f 6e 20 74 68 72 6f 75 nformation throu
7c20: 67 68 20 74 6f 20 74 68 65 20 78 46 69 6c 74 65 gh to the xFilte
7c30: 72 20 6d 65 74 68 6f 64 2e 20 41 6e 79 20 64 65 r method. Any de
7c40: 73 69 72 65 64 20 6d 65 61 6e 69 6e 67 20 63 61 sired meaning ca
7c50: 6e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 n .. ///
7c60: 62 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 69 be assigned to i
7c70: 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 53 74 72 dxNum and idxStr
7c80: 20 61 73 20 6c 6f 6e 67 20 61 73 20 78 42 65 73 as long as xBes
7c90: 74 49 6e 64 65 78 20 61 6e 64 20 78 46 69 6c 74 tIndex and xFilt
7ca0: 65 72 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f er .. ///
7cb0: 20 61 67 72 65 65 20 6f 6e 20 77 68 61 74 20 74 agree on what t
7cc0: 68 61 74 20 6d 65 61 6e 69 6e 67 20 69 73 2e 0d hat meaning is..
7cd0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 . /// </p
7ce0: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ara>.. //
7cf0: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 / <para>..
7d00: 20 20 2f 2f 2f 20 54 68 65 20 69 64 78 53 74 72 /// The idxStr
7d10: 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 61 20 value may be a
7d20: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 string obtained
7d30: 66 72 6f 6d 20 61 6e 20 53 51 4c 69 74 65 0d 0a from an SQLite..
7d40: 20 20 20 20 20 20 20 20 2f 2f 2f 20 6d 65 6d 6f /// memo
7d50: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 ry allocation fu
7d60: 6e 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 73 nction such as s
7d70: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 qlite3_mprintf()
7d80: 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 . .. ///
7d90: 49 66 20 74 68 69 73 20 69 73 20 74 68 65 20 63 If this is the c
7da0: 61 73 65 2c 20 74 68 65 6e 20 74 68 65 20 6e 65 ase, then the ne
7db0: 65 64 54 6f 46 72 65 65 49 64 78 53 74 72 20 66 edToFreeIdxStr f
7dc0: 6c 61 67 20 6d 75 73 74 20 62 65 20 73 65 74 20 lag must be set
7dd0: 74 6f 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f to .. ///
7de0: 20 74 72 75 65 20 73 6f 20 74 68 61 74 20 74 68 true so that th
7df0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 e SQLite core wi
7e00: 6c 6c 20 6b 6e 6f 77 20 74 6f 20 63 61 6c 6c 20 ll know to call
7e10: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 6f sqlite3_free() o
7e20: 6e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 n .. ///
7e30: 74 68 61 74 20 73 74 72 69 6e 67 20 77 68 65 6e that string when
7e40: 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 it has finished
7e50: 20 77 69 74 68 20 69 74 2c 20 61 6e 64 20 74 68 with it, and th
7e60: 75 73 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 us avoid a memor
7e70: 79 20 6c 65 61 6b 2e 0d 0a 20 20 20 20 20 20 20 y leak...
7e80: 20 2f 2f 2f 20 54 68 65 20 69 64 78 53 74 72 20 /// The idxStr
7e90: 76 61 6c 75 65 20 6d 61 79 20 61 6c 73 6f 20 62 value may also b
7ea0: 65 20 61 20 73 74 61 74 69 63 20 63 6f 6e 73 74 e a static const
7eb0: 61 6e 74 20 73 74 72 69 6e 67 2c 20 69 6e 20 77 ant string, in w
7ec0: 68 69 63 68 20 63 61 73 65 0d 0a 20 20 20 20 20 hich case..
7ed0: 20 20 20 2f 2f 2f 20 74 68 65 20 6e 65 65 64 54 /// the needT
7ee0: 6f 46 72 65 65 49 64 78 53 74 72 20 62 6f 6f 6c oFreeIdxStr bool
7ef0: 65 61 6e 20 73 68 6f 75 6c 64 20 72 65 6d 61 69 ean should remai
7f00: 6e 20 66 61 6c 73 65 2e 0d 0a 20 20 20 20 20 20 n false...
7f10: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 /// </para>..
7f20: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 /// <para
7f30: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 49 >.. /// I
7f40: 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 f the virtual ta
7f50: 62 6c 65 20 77 69 6c 6c 20 6f 75 74 70 75 74 20 ble will output
7f60: 72 6f 77 73 20 69 6e 20 74 68 65 20 6f 72 64 65 rows in the orde
7f70: 72 20 73 70 65 63 69 66 69 65 64 20 62 79 20 0d r specified by .
7f80: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 . /// the
7f90: 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 ORDER BY clause
7fa0: 2c 20 74 68 65 6e 20 74 68 65 20 6f 72 64 65 72 , then the order
7fb0: 42 79 43 6f 6e 73 75 6d 65 64 20 66 6c 61 67 20 ByConsumed flag
7fc0: 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 0d 0a may be set to ..
7fd0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 72 75 65 /// true
7fe0: 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 . If the output
7ff0: 69 73 20 6e 6f 74 20 61 75 74 6f 6d 61 74 69 63 is not automatic
8000: 61 6c 6c 79 20 69 6e 20 74 68 65 20 63 6f 72 72 ally in the corr
8010: 65 63 74 20 6f 72 64 65 72 20 0d 0a 20 20 20 20 ect order ..
8020: 20 20 20 20 2f 2f 2f 20 74 68 65 6e 20 6f 72 64 /// then ord
8030: 65 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d 75 73 erByConsumed mus
8040: 74 20 62 65 20 6c 65 66 74 20 69 6e 20 69 74 73 t be left in its
8050: 20 64 65 66 61 75 6c 74 20 66 61 6c 73 65 20 73 default false s
8060: 65 74 74 69 6e 67 2e 20 0d 0a 20 20 20 20 20 20 etting. ..
8070: 20 20 2f 2f 2f 20 54 68 69 73 20 77 69 6c 6c 20 /// This will
8080: 69 6e 64 69 63 61 74 65 20 74 6f 20 74 68 65 20 indicate to the
8090: 53 51 4c 69 74 65 20 63 6f 72 65 20 74 68 61 74 SQLite core that
80a0: 20 69 74 20 77 69 6c 6c 20 6e 65 65 64 20 74 6f it will need to
80b0: 20 64 6f 20 61 20 0d 0a 20 20 20 20 20 20 20 20 do a ..
80c0: 2f 2f 2f 20 73 65 70 61 72 61 74 65 20 73 6f 72 /// separate sor
80d0: 74 69 6e 67 20 70 61 73 73 20 6f 76 65 72 20 74 ting pass over t
80e0: 68 65 20 64 61 74 61 20 61 66 74 65 72 20 69 74 he data after it
80f0: 20 63 6f 6d 65 73 20 6f 75 74 20 6f 66 20 74 68 comes out of th
8100: 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e e virtual table.
8110: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f .. /// </
8120: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f para>.. /
8130: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 // <para>..
8140: 20 20 20 2f 2f 2f 20 54 68 65 20 65 73 74 69 6d /// The estim
8150: 61 74 65 64 43 6f 73 74 20 66 69 65 6c 64 20 73 atedCost field s
8160: 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 hould be set to
8170: 74 68 65 20 65 73 74 69 6d 61 74 65 64 20 6e 75 the estimated nu
8180: 6d 62 65 72 0d 0a 20 20 20 20 20 20 20 20 2f 2f mber.. //
8190: 2f 20 6f 66 20 64 69 73 6b 20 61 63 63 65 73 73 / of disk access
81a0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 72 65 71 75 operations requ
81b0: 69 72 65 64 20 74 6f 20 65 78 65 63 75 74 65 20 ired to execute
81c0: 74 68 69 73 20 71 75 65 72 79 20 61 67 61 69 6e this query again
81d0: 73 74 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f st .. ///
81e0: 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 the virtual tab
81f0: 6c 65 2e 20 54 68 65 20 53 51 4c 69 74 65 20 63 le. The SQLite c
8200: 6f 72 65 20 77 69 6c 6c 20 6f 66 74 65 6e 20 63 ore will often c
8210: 61 6c 6c 20 78 42 65 73 74 49 6e 64 65 78 20 0d all xBestIndex .
8220: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6d 75 6c . /// mul
8230: 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68 tiple times with
8240: 20 64 69 66 66 65 72 65 6e 74 20 63 6f 6e 73 74 different const
8250: 72 61 69 6e 74 73 2c 20 6f 62 74 61 69 6e 20 6d raints, obtain m
8260: 75 6c 74 69 70 6c 65 20 63 6f 73 74 0d 0a 20 20 ultiple cost..
8270: 20 20 20 20 20 20 2f 2f 2f 20 65 73 74 69 6d 61 /// estima
8280: 74 65 73 2c 20 74 68 65 6e 20 63 68 6f 6f 73 65 tes, then choose
8290: 20 74 68 65 20 71 75 65 72 79 20 70 6c 61 6e 20 the query plan
82a0: 74 68 61 74 20 67 69 76 65 73 20 74 68 65 20 6c that gives the l
82b0: 6f 77 65 73 74 20 65 73 74 69 6d 61 74 65 2e 0d owest estimate..
82c0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 . /// The
82d0: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 69 6e 69 SQLite core ini
82e0: 74 69 61 6c 69 7a 65 73 20 65 73 74 69 6d 61 74 tializes estimat
82f0: 65 64 43 6f 73 74 20 74 6f 20 61 20 76 65 72 79 edCost to a very
8300: 20 6c 61 72 67 65 20 76 61 6c 75 65 0d 0a 20 20 large value..
8310: 20 20 20 20 20 20 2f 2f 2f 20 70 72 69 6f 72 20 /// prior
8320: 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 78 42 65 73 to invoking xBes
8330: 74 49 6e 64 65 78 2c 20 73 6f 20 69 66 20 78 42 tIndex, so if xB
8340: 65 73 74 49 6e 64 65 78 20 64 65 74 65 72 6d 69 estIndex determi
8350: 6e 65 73 20 74 68 61 74 20 74 68 65 0d 0a 20 20 nes that the..
8360: 20 20 20 20 20 20 2f 2f 2f 20 63 75 72 72 65 6e /// curren
8370: 74 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 t combination of
8380: 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 75 parameters is u
8390: 6e 64 65 73 69 72 61 62 6c 65 2c 20 69 74 20 63 ndesirable, it c
83a0: 61 6e 20 6c 65 61 76 65 20 74 68 65 0d 0a 20 20 an leave the..
83b0: 20 20 20 20 20 20 2f 2f 2f 20 65 73 74 69 6d 61 /// estima
83c0: 74 65 64 43 6f 73 74 20 66 69 65 6c 64 20 75 6e tedCost field un
83d0: 63 68 61 6e 67 65 64 20 74 6f 20 64 69 73 63 6f changed to disco
83e0: 75 72 61 67 65 20 69 74 73 20 75 73 65 2e 0d 0a urage its use...
83f0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 /// </pa
8400: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ra>.. ///
8410: 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 <para>..
8420: 20 2f 2f 2f 20 49 66 20 74 68 65 20 63 75 72 72 /// If the curr
8430: 65 6e 74 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 ent version of S
8440: 51 4c 69 74 65 20 69 73 20 33 2e 38 2e 32 20 6f QLite is 3.8.2 o
8450: 72 20 67 72 65 61 74 65 72 2c 20 74 68 65 20 65 r greater, the e
8460: 73 74 69 6d 61 74 65 64 52 6f 77 73 0d 0a 20 20 stimatedRows..
8470: 20 20 20 20 20 20 2f 2f 2f 20 66 69 65 6c 64 20 /// field
8480: 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 61 6e may be set to an
8490: 20 65 73 74 69 6d 61 74 65 20 6f 66 20 74 68 65 estimate of the
84a0: 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 number of rows
84b0: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0d returned by the.
84c0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 70 72 6f . /// pro
84d0: 70 6f 73 65 64 20 71 75 65 72 79 20 70 6c 61 6e posed query plan
84e0: 2e 20 49 66 20 74 68 69 73 20 76 61 6c 75 65 20 . If this value
84f0: 69 73 20 6e 6f 74 20 65 78 70 6c 69 63 69 74 6c is not explicitl
8500: 79 20 73 65 74 2c 20 74 68 65 20 64 65 66 61 75 y set, the defau
8510: 6c 74 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f lt .. ///
8520: 20 65 73 74 69 6d 61 74 65 20 6f 66 20 32 35 20 estimate of 25
8530: 72 6f 77 73 20 69 73 20 75 73 65 64 2e 0d 0a 20 rows is used...
8540: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 /// </par
8550: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 a>.. ///
8560: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 <para>..
8570: 2f 2f 2f 20 49 66 20 74 68 65 20 63 75 72 72 65 /// If the curre
8580: 6e 74 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 nt version of SQ
8590: 4c 69 74 65 20 69 73 20 33 2e 39 2e 30 20 6f 72 Lite is 3.9.0 or
85a0: 20 67 72 65 61 74 65 72 2c 20 74 68 65 20 69 64 greater, the id
85b0: 78 46 6c 61 67 73 20 66 69 65 6c 64 0d 0a 20 20 xFlags field..
85c0: 20 20 20 20 20 20 2f 2f 2f 20 6d 61 79 20 62 65 /// may be
85d0: 20 73 65 74 20 74 6f 20 53 51 4c 49 54 45 5f 49 set to SQLITE_I
85e0: 4e 44 45 58 5f 53 43 41 4e 5f 55 4e 49 51 55 45 NDEX_SCAN_UNIQUE
85f0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 to indicate tha
8600: 74 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 t the virtual ta
8610: 62 6c 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ble.. ///
8620: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 6c will return onl
8630: 79 20 7a 65 72 6f 20 6f 72 20 6f 6e 65 20 72 6f y zero or one ro
8640: 77 73 20 67 69 76 65 6e 20 74 68 65 20 69 6e 70 ws given the inp
8650: 75 74 20 63 6f 6e 73 74 72 61 69 6e 74 73 2e 20 ut constraints.
8660: 20 41 64 64 69 74 69 6f 6e 61 6c 0d 0a 20 20 20 Additional..
8670: 20 20 20 20 20 2f 2f 2f 20 62 69 74 73 20 6f 66 /// bits of
8680: 20 74 68 65 20 69 64 78 46 6c 61 67 73 20 66 69 the idxFlags fi
8690: 65 6c 64 20 6d 69 67 68 74 20 62 65 20 75 6e 64 eld might be und
86a0: 65 72 73 74 6f 6f 64 20 69 6e 20 6c 61 74 65 72 erstood in later
86b0: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
86c0: 69 74 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ite... //
86d0: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 / </para>..
86e0: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 /// <para>..
86f0: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 61 /// The a
8700: 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b ConstraintUsage[
8710: 5d 20 61 72 72 61 79 20 63 6f 6e 74 61 69 6e 73 ] array contains
8720: 20 6f 6e 65 20 65 6c 65 6d 65 6e 74 20 66 6f 72 one element for
8730: 20 65 61 63 68 20 6f 66 20 0d 0a 20 20 20 20 20 each of ..
8740: 20 20 20 2f 2f 2f 20 74 68 65 20 6e 43 6f 6e 73 /// the nCons
8750: 74 72 61 69 6e 74 20 63 6f 6e 73 74 72 61 69 6e traint constrain
8760: 74 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 73 ts in the inputs
8770: 20 73 65 63 74 69 6f 6e 20 6f 66 20 74 68 65 20 section of the
8780: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 71 .. /// sq
8790: 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f lite3_index_info
87a0: 20 73 74 72 75 63 74 75 72 65 2e 20 0d 0a 20 20 structure. ..
87b0: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 61 43 /// The aC
87c0: 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d onstraintUsage[]
87d0: 20 61 72 72 61 79 20 69 73 20 75 73 65 64 20 62 array is used b
87e0: 79 20 78 42 65 73 74 49 6e 64 65 78 20 74 6f 20 y xBestIndex to
87f0: 74 65 6c 6c 20 74 68 65 20 0d 0a 20 20 20 20 20 tell the ..
8800: 20 20 20 2f 2f 2f 20 63 6f 72 65 20 68 6f 77 20 /// core how
8810: 69 74 20 69 73 20 75 73 69 6e 67 20 74 68 65 20 it is using the
8820: 63 6f 6e 73 74 72 61 69 6e 74 73 2e 0d 0a 20 20 constraints...
8830: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 /// </para
8840: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c >.. /// <
8850: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f para>.. /
8860: 2f 2f 20 54 68 65 20 78 42 65 73 74 49 6e 64 65 // The xBestInde
8870: 78 20 6d 65 74 68 6f 64 20 6d 61 79 20 73 65 74 x method may set
8880: 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 aConstraintUsag
8890: 65 5b 5d 2e 61 72 67 76 49 6e 64 65 78 20 0d 0a e[].argvIndex ..
88a0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 65 6e 74 72 /// entr
88b0: 69 65 73 20 74 6f 20 76 61 6c 75 65 73 20 67 72 ies to values gr
88c0: 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2e eater than zero.
88d0: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 45 .. /// E
88e0: 78 61 63 74 6c 79 20 6f 6e 65 20 65 6e 74 72 79 xactly one entry
88f0: 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 should be set t
8900: 6f 20 31 2c 20 61 6e 6f 74 68 65 72 20 74 6f 20 o 1, another to
8910: 32 2c 20 61 6e 6f 74 68 65 72 20 74 6f 20 33 2c 2, another to 3,
8920: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 61 .. /// a
8930: 6e 64 20 73 6f 20 66 6f 72 74 68 20 75 70 20 74 nd so forth up t
8940: 6f 20 61 73 20 6d 61 6e 79 20 6f 72 20 61 73 20 o as many or as
8950: 66 65 77 20 61 73 20 74 68 65 20 78 42 65 73 74 few as the xBest
8960: 49 6e 64 65 78 20 6d 65 74 68 6f 64 20 77 61 6e Index method wan
8970: 74 73 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f ts. .. //
8980: 2f 20 54 68 65 20 45 58 50 52 20 6f 66 20 74 68 / The EXPR of th
8990: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 e corresponding
89a0: 63 6f 6e 73 74 72 61 69 6e 74 73 20 77 69 6c 6c constraints will
89b0: 20 74 68 65 6e 20 62 65 20 70 61 73 73 65 64 20 then be passed
89c0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e .. /// in
89d0: 20 61 73 20 74 68 65 20 61 72 67 76 5b 5d 20 70 as the argv[] p
89e0: 61 72 61 6d 65 74 65 72 73 20 74 6f 20 78 46 69 arameters to xFi
89f0: 6c 74 65 72 2e 0d 0a 20 20 20 20 20 20 20 20 2f lter... /
8a00: 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 // </para>..
8a10: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a /// <para>..
8a20: 20 20 20 20 20 20 20 20 2f 2f 2f 20 46 6f 72 20 /// For
8a30: 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 example, if the
8a40: 61 43 6f 6e 73 74 72 61 69 6e 74 5b 33 5d 2e 61 aConstraint[3].a
8a50: 72 67 76 49 6e 64 65 78 20 69 73 20 73 65 74 20 rgvIndex is set
8a60: 74 6f 20 31 2c 20 74 68 65 6e 20 0d 0a 20 20 20 to 1, then ..
8a70: 20 20 20 20 20 2f 2f 2f 20 77 68 65 6e 20 78 46 /// when xF
8a80: 69 6c 74 65 72 20 69 73 20 63 61 6c 6c 65 64 2c ilter is called,
8a90: 20 74 68 65 20 61 72 67 76 5b 30 5d 20 70 61 73 the argv[0] pas
8aa0: 73 65 64 20 74 6f 20 78 46 69 6c 74 65 72 20 77 sed to xFilter w
8ab0: 69 6c 6c 20 68 61 76 65 20 0d 0a 20 20 20 20 20 ill have ..
8ac0: 20 20 20 2f 2f 2f 20 74 68 65 20 45 58 50 52 20 /// the EXPR
8ad0: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 43 6f value of the aCo
8ae0: 6e 73 74 72 61 69 6e 74 5b 33 5d 20 63 6f 6e 73 nstraint[3] cons
8af0: 74 72 61 69 6e 74 2e 0d 0a 20 20 20 20 20 20 20 traint...
8b00: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 /// </para>..
8b10: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e /// <para>
8b20: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 42 79 .. /// By
8b30: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 53 51 default, the SQ
8b40: 4c 69 74 65 20 63 6f 72 65 20 64 6f 75 62 6c 65 Lite core double
8b50: 20 63 68 65 63 6b 73 20 61 6c 6c 20 63 6f 6e 73 checks all cons
8b60: 74 72 61 69 6e 74 73 20 6f 6e 20 0d 0a 20 20 20 traints on ..
8b70: 20 20 20 20 20 2f 2f 2f 20 65 61 63 68 20 72 6f /// each ro
8b80: 77 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c w of the virtual
8b90: 20 74 61 62 6c 65 20 74 68 61 74 20 69 74 20 72 table that it r
8ba0: 65 63 65 69 76 65 73 2e 20 49 66 20 73 75 63 68 eceives. If such
8bb0: 20 61 20 63 68 65 63 6b 20 0d 0a 20 20 20 20 20 a check ..
8bc0: 20 20 20 2f 2f 2f 20 69 73 20 72 65 64 75 6e 64 /// is redund
8bd0: 61 6e 74 2c 20 74 68 65 20 78 42 65 73 74 46 69 ant, the xBestFi
8be0: 6c 74 65 72 20 6d 65 74 68 6f 64 20 63 61 6e 20 lter method can
8bf0: 73 75 70 70 72 65 73 73 20 74 68 61 74 20 64 6f suppress that do
8c00: 75 62 6c 65 2d 63 68 65 63 6b 20 62 79 20 0d 0a uble-check by ..
8c10: 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 65 74 74 /// sett
8c20: 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 ing aConstraintU
8c30: 73 61 67 65 5b 5d 2e 6f 6d 69 74 2e 0d 0a 20 20 sage[].omit...
8c40: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 /// </para
8c50: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c >.. /// <
8c60: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f para>.. /
8c70: 2f 2f 20 54 68 65 20 78 42 65 73 74 49 6e 64 65 // The xBestInde
8c80: 78 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 x method should
8c90: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b return SQLITE_OK
8ca0: 20 6f 6e 20 73 75 63 63 65 73 73 2e 20 20 49 66 on success. If
8cb0: 20 61 6e 79 0d 0a 20 20 20 20 20 20 20 20 2f 2f any.. //
8cc0: 2f 20 6b 69 6e 64 20 6f 66 20 66 61 74 61 6c 20 / kind of fatal
8cd0: 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 61 6e error occurs, an
8ce0: 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 appropriate err
8cf0: 6f 72 20 63 6f 64 65 20 28 65 78 3a 20 53 51 4c or code (ex: SQL
8d00: 49 54 45 5f 4e 4f 4d 45 4d 29 0d 0a 20 20 20 20 ITE_NOMEM)..
8d10: 20 20 20 20 2f 2f 2f 20 73 68 6f 75 6c 64 20 62 /// should b
8d20: 65 20 72 65 74 75 72 6e 65 64 20 69 6e 73 74 65 e returned inste
8d30: 61 64 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ad... ///
8d40: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 </para>..
8d50: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 /// <para>..
8d60: 20 20 20 20 20 20 2f 2f 2f 20 49 66 20 78 42 65 /// If xBe
8d70: 73 74 49 6e 64 65 78 20 72 65 74 75 72 6e 73 20 stIndex returns
8d80: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
8d90: 54 2c 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 T, that does not
8da0: 20 69 6e 64 69 63 61 74 65 20 61 6e 0d 0a 20 20 indicate an..
8db0: 20 20 20 20 20 20 2f 2f 2f 20 65 72 72 6f 72 2e /// error.
8dc0: 20 20 52 61 74 68 65 72 2c 20 53 51 4c 49 54 45 Rather, SQLITE
8dd0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 69 6e 64 69 _CONSTRAINT indi
8de0: 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20 70 cates that the p
8df0: 61 72 74 69 63 75 6c 61 72 20 63 6f 6d 62 69 6e articular combin
8e00: 61 74 69 6f 6e 0d 0a 20 20 20 20 20 20 20 20 2f ation.. /
8e10: 2f 2f 20 6f 66 20 69 6e 70 75 74 20 70 61 72 61 // of input para
8e20: 6d 65 74 65 72 73 20 73 70 65 63 69 66 69 65 64 meters specified
8e30: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 should not be u
8e40: 73 65 64 20 69 6e 20 74 68 65 20 71 75 65 72 79 sed in the query
8e50: 20 70 6c 61 6e 2e 0d 0a 20 20 20 20 20 20 20 20 plan...
8e60: 2f 2f 2f 20 54 68 65 20 53 51 4c 49 54 45 5f 43 /// The SQLITE_C
8e70: 4f 4e 53 54 52 41 49 4e 54 20 72 65 74 75 72 6e ONSTRAINT return
8e80: 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20 74 is useful for t
8e90: 61 62 6c 65 2d 76 61 6c 75 65 64 20 66 75 6e 63 able-valued func
8ea0: 74 69 6f 6e 73 20 74 68 61 74 0d 0a 20 20 20 20 tions that..
8eb0: 20 20 20 20 2f 2f 2f 20 68 61 76 65 20 72 65 71 /// have req
8ec0: 75 69 72 65 64 20 70 61 72 61 6d 65 74 65 72 73 uired parameters
8ed0: 2e 20 20 49 66 20 74 68 65 20 61 43 6f 6e 73 74 . If the aConst
8ee0: 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 66 raint[].usable f
8ef0: 69 65 6c 64 20 69 73 20 66 61 6c 73 65 0d 0a 20 ield is false..
8f00: 20 20 20 20 20 20 20 2f 2f 2f 20 66 6f 72 20 6f /// for o
8f10: 6e 65 20 6f 66 20 74 68 65 20 72 65 71 75 69 72 ne of the requir
8f20: 65 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 ed parameter, th
8f30: 65 6e 20 74 68 65 20 78 42 65 73 74 49 6e 64 65 en the xBestInde
8f40: 78 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 0d x method should.
8f50: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 72 65 74 . /// ret
8f60: 75 72 6e 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 urn SQLITE_CONST
8f70: 52 41 49 4e 54 2e 0d 0a 20 20 20 20 20 20 20 20 RAINT...
8f80: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 /// </para>..
8f90: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d /// <para>.
8fa0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 . /// The
8fb0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 65 78 61 6d 70 following examp
8fc0: 6c 65 20 77 69 6c 6c 20 62 65 74 74 65 72 20 69 le will better i
8fd0: 6c 6c 75 73 74 72 61 74 65 20 74 68 65 20 75 73 llustrate the us
8fe0: 65 20 6f 66 20 53 51 4c 49 54 45 5f 43 4f 4e 53 e of SQLITE_CONS
8ff0: 54 52 41 49 4e 54 0d 0a 20 20 20 20 20 20 20 20 TRAINT..
9000: 2f 2f 2f 20 61 73 20 61 20 72 65 74 75 72 6e 20 /// as a return
9010: 76 61 6c 75 65 20 66 72 6f 6d 20 78 42 65 73 74 value from xBest
9020: 49 6e 64 65 78 3a 0d 0a 20 20 20 20 20 20 20 20 Index:..
9030: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 /// </para>..
9040: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c /// <para><
9050: 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f code>.. /
9060: 2f 2f 20 53 45 4c 45 43 54 20 2a 20 46 52 4f 4d // SELECT * FROM
9070: 20 72 65 61 6c 74 61 62 2c 20 74 61 62 6c 65 76 realtab, tablev
9080: 61 6c 75 65 64 66 75 6e 63 28 72 65 61 6c 74 61 aluedfunc(realta
9090: 62 2e 78 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f b.x);.. /
90a0: 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 // </code></para
90b0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c >.. /// <
90c0: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f para>.. /
90d0: 2f 2f 20 41 73 73 75 6d 69 6e 67 20 74 68 61 74 // Assuming that
90e0: 20 74 68 65 20 66 69 72 73 74 20 68 69 64 64 65 the first hidde
90f0: 6e 20 63 6f 6c 75 6d 6e 20 6f 66 20 22 74 61 62 n column of "tab
9100: 6c 65 76 61 6c 75 65 64 66 75 6e 63 22 20 69 73 levaluedfunc" is
9110: 20 22 70 61 72 61 6d 31 22 2c 0d 0a 20 20 20 20 "param1",..
9120: 20 20 20 20 2f 2f 2f 20 74 68 65 20 71 75 65 72 /// the quer
9130: 79 20 61 62 6f 76 65 20 69 73 20 73 65 6d 61 6e y above is seman
9140: 74 69 63 61 6c 6c 79 20 65 71 75 69 76 61 6c 65 tically equivale
9150: 6e 74 20 74 6f 20 74 68 69 73 3a 0d 0a 20 20 20 nt to this:..
9160: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e /// </para>
9170: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 .. /// <p
9180: 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 ara><code>..
9190: 20 20 20 20 2f 2f 2f 20 53 45 4c 45 43 54 20 2a /// SELECT *
91a0: 20 46 52 4f 4d 20 72 65 61 6c 74 61 62 2c 20 74 FROM realtab, t
91b0: 61 62 6c 65 76 61 6c 75 65 64 66 75 6e 63 0d 0a ablevaluedfunc..
91c0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 57 48 45 /// WHE
91d0: 52 45 20 74 61 62 6c 65 76 61 6c 75 65 64 66 75 RE tablevaluedfu
91e0: 6e 63 2e 70 61 72 61 6d 31 20 3d 20 72 65 61 6c nc.param1 = real
91f0: 74 61 62 2e 78 3b 0d 0a 20 20 20 20 20 20 20 20 tab.x;..
9200: 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 /// </code></par
9210: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 a>.. ///
9220: 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 <para>..
9230: 2f 2f 2f 20 54 68 65 20 71 75 65 72 79 20 70 6c /// The query pl
9240: 61 6e 6e 65 72 20 6d 75 73 74 20 64 65 63 69 64 anner must decid
9250: 65 20 62 65 74 77 65 65 6e 20 6d 61 6e 79 20 70 e between many p
9260: 6f 73 73 69 62 6c 65 20 69 6d 70 6c 65 6d 65 6e ossible implemen
9270: 74 61 74 69 6f 6e 73 0d 0a 20 20 20 20 20 20 20 tations..
9280: 20 2f 2f 2f 20 6f 66 20 74 68 69 73 20 71 75 65 /// of this que
9290: 72 79 2c 20 62 75 74 20 74 77 6f 20 70 6c 61 6e ry, but two plan
92a0: 73 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20 s in particular
92b0: 61 72 65 20 6f 66 20 6e 6f 74 65 3a 0d 0a 20 20 are of note:..
92c0: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 /// </para
92d0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c >.. /// <
92e0: 21 5b 43 44 41 54 41 5b 3c 6f 6c 3e 5d 5d 3e 0d ![CDATA[<ol>]]>.
92f0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 21 5b . /// <![
9300: 43 44 41 54 41 5b 3c 6c 69 3e 5d 5d 3e 53 63 61 CDATA[<li>]]>Sca
9310: 6e 20 61 6c 6c 0d 0a 20 20 20 20 20 20 20 20 2f n all.. /
9320: 2f 2f 20 72 6f 77 73 20 6f 66 20 72 65 61 6c 74 // rows of realt
9330: 61 62 20 61 6e 64 20 66 6f 72 20 65 61 63 68 20 ab and for each
9340: 72 6f 77 2c 20 66 69 6e 64 20 72 6f 77 73 20 69 row, find rows i
9350: 6e 20 74 61 62 6c 65 76 61 6c 75 65 64 66 75 6e n tablevaluedfun
9360: 63 20 77 68 65 72 65 0d 0a 20 20 20 20 20 20 20 c where..
9370: 20 2f 2f 2f 20 70 61 72 61 6d 31 20 69 73 20 65 /// param1 is e
9380: 71 75 61 6c 20 74 6f 20 72 65 61 6c 74 61 62 2e qual to realtab.
9390: 78 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c x.. /// <
93a0: 21 5b 43 44 41 54 41 5b 3c 2f 6c 69 3e 5d 5d 3e ![CDATA[</li>]]>
93b0: 3c 21 5b 43 44 41 54 41 5b 3c 6c 69 3e 5d 5d 3e <![CDATA[<li>]]>
93c0: 53 63 61 6e 20 61 6c 6c 20 72 6f 77 73 20 6f 66 Scan all rows of
93d0: 20 74 61 62 6c 65 76 61 6c 75 65 64 20 66 75 6e tablevalued fun
93e0: 63 20 61 6e 64 20 66 6f 72 20 65 61 63 68 20 72 c and for each r
93f0: 6f 77 20 66 69 6e 64 20 72 6f 77 73 0d 0a 20 20 ow find rows..
9400: 20 20 20 20 20 20 2f 2f 2f 20 69 6e 20 72 65 61 /// in rea
9410: 6c 74 61 62 20 77 68 65 72 65 20 78 20 69 73 20 ltab where x is
9420: 65 71 75 61 6c 20 74 6f 20 74 61 62 6c 65 76 61 equal to tableva
9430: 6c 75 65 64 66 75 6e 63 2e 70 61 72 61 6d 31 2e luedfunc.param1.
9440: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 21 .. /// <!
9450: 5b 43 44 41 54 41 5b 3c 2f 6c 69 3e 5d 5d 3e 3c [CDATA[</li>]]><
9460: 21 5b 43 44 41 54 41 5b 3c 2f 6f 6c 3e 5d 5d 3e ![CDATA[</ol>]]>
9470: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 .. /// <p
9480: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ara>.. //
9490: 2f 20 54 68 65 20 78 42 65 73 74 49 6e 64 65 78 / The xBestIndex
94a0: 20 6d 65 74 68 6f 64 20 77 69 6c 6c 20 62 65 20 method will be
94b0: 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 invoked once for
94c0: 20 65 61 63 68 20 6f 66 20 74 68 65 20 70 6f 74 each of the pot
94d0: 65 6e 74 69 61 6c 0d 0a 20 20 20 20 20 20 20 20 ential..
94e0: 2f 2f 2f 20 70 6c 61 6e 73 20 61 62 6f 76 65 2e /// plans above.
94f0: 20 20 46 6f 72 20 70 6c 61 6e 20 31 2c 20 74 68 For plan 1, th
9500: 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e e aConstraint[].
9510: 75 73 61 62 6c 65 20 66 6c 61 67 20 66 6f 72 20 usable flag for
9520: 66 6f 72 20 74 68 65 0d 0a 20 20 20 20 20 20 20 for the..
9530: 20 2f 2f 2f 20 53 51 4c 49 54 45 5f 43 4f 4e 53 /// SQLITE_CONS
9540: 54 52 41 49 4e 54 5f 45 51 20 63 6f 6e 73 74 72 TRAINT_EQ constr
9550: 61 69 6e 74 20 6f 6e 20 74 68 65 20 70 61 72 61 aint on the para
9560: 6d 31 20 63 6f 6c 75 6d 6e 20 77 69 6c 6c 20 62 m1 column will b
9570: 65 20 74 72 75 65 20 62 65 63 61 75 73 65 0d 0a e true because..
9580: 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 20 /// the
9590: 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 right-hand side
95a0: 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 22 70 value for the "p
95b0: 61 72 61 6d 31 20 3d 20 3f 22 20 63 6f 6e 73 74 aram1 = ?" const
95c0: 72 61 69 6e 74 20 77 69 6c 6c 20 62 65 20 6b 6e raint will be kn
95d0: 6f 77 6e 2c 0d 0a 20 20 20 20 20 20 20 20 2f 2f own,.. //
95e0: 2f 20 73 69 6e 63 65 20 69 74 20 69 73 20 64 65 / since it is de
95f0: 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 termined by the
9600: 6f 75 74 65 72 20 72 65 61 6c 74 61 62 20 6c 6f outer realtab lo
9610: 6f 70 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f op... ///
9620: 20 42 75 74 20 66 6f 72 20 70 6c 61 6e 20 32 2c But for plan 2,
9630: 20 74 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 the aConstraint
9640: 5b 5d 2e 75 73 61 62 6c 65 20 66 6c 61 67 20 66 [].usable flag f
9650: 6f 72 20 22 70 61 72 61 6d 31 20 3d 20 3f 22 20 or "param1 = ?"
9660: 77 69 6c 6c 20 62 65 20 66 61 6c 73 65 0d 0a 20 will be false..
9670: 20 20 20 20 20 20 20 2f 2f 2f 20 62 65 63 61 75 /// becau
9680: 73 65 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e se the right-han
9690: 64 20 73 69 64 65 20 76 61 6c 75 65 20 69 73 20 d side value is
96a0: 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 61 6e determined by an
96b0: 20 69 6e 6e 65 72 20 6c 6f 6f 70 20 61 6e 64 20 inner loop and
96c0: 69 73 20 74 68 75 73 0d 0a 20 20 20 20 20 20 20 is thus..
96d0: 20 2f 2f 2f 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 /// an unknown
96e0: 71 75 61 6e 74 69 74 79 2e 20 20 42 65 63 61 75 quantity. Becau
96f0: 73 65 20 70 61 72 61 6d 31 20 69 73 20 61 20 72 se param1 is a r
9700: 65 71 75 69 72 65 64 20 69 6e 70 75 74 20 74 6f equired input to
9710: 20 74 68 65 20 74 61 62 6c 65 2d 76 61 6c 75 65 the table-value
9720: 64 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 66 d.. /// f
9730: 75 6e 63 74 69 6f 6e 73 2c 20 74 68 65 20 78 42 unctions, the xB
9740: 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64 20 estIndex method
9750: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51 should return SQ
9760: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 LITE_CONSTRAINT
9770: 77 68 65 6e 20 70 72 65 73 65 6e 74 65 64 20 0d when presented .
9780: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 77 69 74 . /// wit
9790: 68 20 70 6c 61 6e 20 32 2c 20 69 6e 64 69 63 61 h plan 2, indica
97a0: 74 69 6e 67 20 74 68 61 74 20 61 20 72 65 71 75 ting that a requ
97b0: 69 72 65 64 20 69 6e 70 75 74 20 69 73 20 6d 69 ired input is mi
97c0: 73 73 69 6e 67 2e 20 20 54 68 69 73 20 66 6f 72 ssing. This for
97d0: 63 65 73 20 74 68 65 0d 0a 20 20 20 20 20 20 20 ces the..
97e0: 20 2f 2f 2f 20 71 75 65 72 79 20 70 6c 61 6e 6e /// query plann
97f0: 65 72 20 74 6f 20 73 65 6c 65 63 74 20 70 6c 61 er to select pla
9800: 6e 20 31 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f n 1... //
9810: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 / </para>..
9820: 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79 /// </summary
9830: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c >.. /// <
9840: 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 56 74 61 param name="pVta
9850: 62 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f b">.. ///
9860: 20 54 68 65 20 6e 61 74 69 76 65 20 70 6f 69 6e The native poin
9870: 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ter to the sqlit
9880: 65 33 5f 76 74 61 62 20 64 65 72 69 76 65 64 20 e3_vtab derived
9890: 73 74 72 75 63 74 75 72 65 2e 0d 0a 20 20 20 20 structure...
98a0: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e /// </param>
98b0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 .. /// <p
98c0: 61 72 61 6d 20 6e 61 6d 65 3d 22 70 49 6e 64 65 aram name="pInde
98d0: 78 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f x">.. ///
98e0: 20 54 68 65 20 6e 61 74 69 76 65 20 70 6f 69 6e The native poin
98f0: 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ter to the sqlit
9900: 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 e3_index_info st
9910: 72 75 63 74 75 72 65 2e 0d 0a 20 20 20 20 20 20 ructure...
9920: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a /// </param>..
9930: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 72 65 74 /// <ret
9940: 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 2f urns>.. /
9950: 2f 2f 20 41 20 73 74 61 6e 64 61 72 64 20 53 51 // A standard SQ
9960: 4c 69 74 65 20 72 65 74 75 72 6e 20 63 6f 64 65 Lite return code
9970: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c ... /// <
9980: 2f 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 /returns>..
9990: 20 20 20 53 51 4c 69 74 65 45 72 72 6f 72 43 6f SQLiteErrorCo
99a0: 64 65 20 78 42 65 73 74 49 6e 64 65 78 28 0d 0a de xBestIndex(..
99b0: 20 20 20 20 20 20 20 20 20 20 20 20 49 6e 74 50 IntP
99c0: 74 72 20 70 56 74 61 62 2c 0d 0a 20 20 20 20 20 tr pVtab,..
99d0: 20 20 20 20 20 20 20 49 6e 74 50 74 72 20 70 49 IntPtr pI
99e0: 6e 64 65 78 0d 0a 20 20 20 20 20 20 20 20 20 20 ndex..
99f0: 20 20 29 3b 0d 0a 0d 0a 20 20 20 20 20 20 20 20 );....
9a00: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
9a10: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
9a20: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
9a30: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
9a40: 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 20 ///////....
9a50: 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79 3e /// <summary>
9a60: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 .. /// <p
9a70: 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 ara><code>..
9a80: 20 20 20 20 2f 2f 2f 20 69 6e 74 20 28 2a 78 44 /// int (*xD
9a90: 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 isconnect)(sqlit
9aa0: 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b e3_vtab *pVTab);
9ab0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f .. /// </
9ac0: 63 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 code></para>..
9ad0: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e /// <para>
9ae0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 .. /// Th
9af0: 69 73 20 6d 65 74 68 6f 64 20 72 65 6c 65 61 73 is method releas
9b00: 65 73 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 es a connection
9b10: 74 6f 20 61 20 76 69 72 74 75 61 6c 20 74 61 62 to a virtual tab
9b20: 6c 65 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f le. .. //
9b30: 2f 20 4f 6e 6c 79 20 74 68 65 20 73 71 6c 69 74 / Only the sqlit
9b40: 65 33 5f 76 74 61 62 20 6f 62 6a 65 63 74 20 69 e3_vtab object i
9b50: 73 20 64 65 73 74 72 6f 79 65 64 2e 0d 0a 20 20 s destroyed...
9b60: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 76 69 /// The vi
9b70: 72 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20 6e rtual table is n
9b80: 6f 74 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 ot destroyed and
9b90: 20 61 6e 79 20 62 61 63 6b 69 6e 67 20 73 74 6f any backing sto
9ba0: 72 65 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f re .. ///
9bb0: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
9bc0: 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 the virtual tab
9bd0: 6c 65 20 70 65 72 73 69 73 74 73 2e 20 0d 0a 20 le persists. ..
9be0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 /// </par
9bf0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 a>.. ///
9c00: 54 68 69 73 20 6d 65 74 68 6f 64 20 75 6e 64 6f This method undo
9c10: 65 73 20 74 68 65 20 77 6f 72 6b 20 6f 66 20 78 es the work of x
9c20: 43 6f 6e 6e 65 63 74 2e 0d 0a 20 20 20 20 20 20 Connect...
9c30: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 /// <para>..
9c40: 20 20 20 20 20 20 2f 2f 2f 20 54 68 69 73 20 6d /// This m
9c50: 65 74 68 6f 64 20 69 73 20 61 20 64 65 73 74 72 ethod is a destr
9c60: 75 63 74 6f 72 20 66 6f 72 20 61 20 63 6f 6e 6e uctor for a conn
9c70: 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 76 69 ection to the vi
9c80: 72 74 75 61 6c 20 74 61 62 6c 65 2e 0d 0a 20 20 rtual table...
9c90: 20 20 20 20 20 20 2f 2f 2f 20 43 6f 6e 74 72 61 /// Contra
9ca0: 73 74 20 74 68 69 73 20 6d 65 74 68 6f 64 20 77 st this method w
9cb0: 69 74 68 20 78 44 65 73 74 72 6f 79 2e 20 20 54 ith xDestroy. T
9cc0: 68 65 20 78 44 65 73 74 72 6f 79 20 69 73 20 61 he xDestroy is a
9cd0: 20 64 65 73 74 72 75 63 74 6f 72 0d 0a 20 20 20 destructor..
9ce0: 20 20 20 20 20 2f 2f 2f 20 66 6f 72 20 74 68 65 /// for the
9cf0: 20 65 6e 74 69 72 65 20 76 69 72 74 75 61 6c 20 entire virtual
9d00: 74 61 62 6c 65 2e 0d 0a 20 20 20 20 20 20 20 20 table...
9d10: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 /// </para>..
9d20: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d /// <para>.
9d30: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 . /// The
9d40: 20 78 44 69 73 63 6f 6e 6e 65 63 74 20 6d 65 74 xDisconnect met
9d50: 68 6f 64 20 69 73 20 72 65 71 75 69 72 65 64 20 hod is required
9d60: 66 6f 72 20 65 76 65 72 79 20 76 69 72 74 75 61 for every virtua
9d70: 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e l table implemen
9d80: 74 61 74 69 6f 6e 2c 0d 0a 20 20 20 20 20 20 20 tation,..
9d90: 20 2f 2f 2f 20 74 68 6f 75 67 68 20 69 74 20 69 /// though it i
9da0: 73 20 61 63 63 65 70 74 61 62 6c 65 20 66 6f 72 s acceptable for
9db0: 20 74 68 65 20 78 44 69 73 63 6f 6e 6e 65 63 74 the xDisconnect
9dc0: 20 61 6e 64 20 78 44 65 73 74 72 6f 79 20 6d 65 and xDestroy me
9dd0: 74 68 6f 64 73 20 74 6f 20 62 65 0d 0a 20 20 20 thods to be..
9de0: 20 20 20 20 20 2f 2f 2f 20 74 68 65 20 73 61 6d /// the sam
9df0: 65 20 66 75 6e 63 74 69 6f 6e 20 69 66 20 74 68 e function if th
9e00: 61 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 66 at makes sense f
9e10: 6f 72 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 or the particula
9e20: 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e r virtual table.
9e30: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f .. /// </
9e40: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f para>.. /
9e50: 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a 20 // </summary>..
9e60: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 /// <para
9e70: 6d 20 6e 61 6d 65 3d 22 70 56 74 61 62 22 3e 0d m name="pVtab">.
9e80: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 . /// The
9e90: 20 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72 20 native pointer
9ea0: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 to the sqlite3_v
9eb0: 74 61 62 20 64 65 72 69 76 65 64 20 73 74 72 75 tab derived stru
9ec0: 63 74 75 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 cture...
9ed0: 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 /// </param>..
9ee0: 20 20 20 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72 /// <retur
9ef0: 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ns>.. ///
9f00: 20 41 20 73 74 61 6e 64 61 72 64 20 53 51 4c 69 A standard SQLi
9f10: 74 65 20 72 65 74 75 72 6e 20 63 6f 64 65 2e 0d te return code..
9f20: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72 . /// </r
9f30: 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 eturns>..
9f40: 20 53 51 4c 69 74 65 45 72 72 6f 72 43 6f 64 65 SQLiteErrorCode
9f50: 20 78 44 69 73 63 6f 6e 6e 65 63 74 28 0d 0a 20 xDisconnect(..
9f60: 20 20 20 20 20 20 20 20 20 20 20 49 6e 74 50 74 IntPt
9f70: 72 20 70 56 74 61 62 0d 0a 20 20 20 20 20 20 20 r pVtab..
9f80: 20 20 20 20 20 29 3b 0d 0a 0d 0a 20 20 20 20 20 );....
9f90: 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f /////////////
9fa0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
9fb0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
9fc0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
9fd0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 //////////....
9fe0: 20 20 20 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61 /// <summa
9ff0: 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ry>.. ///
a000: 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 <para><code>..
a010: 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e 74 20 28 /// int (
a020: 2a 78 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74 *xDestroy)(sqlit
a030: 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b e3_vtab *pVTab);
a040: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f .. /// </
a050: 63 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 code></para>..
a060: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e /// <para>
a070: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 .. /// Th
a080: 69 73 20 6d 65 74 68 6f 64 20 72 65 6c 65 61 73 is method releas
a090: 65 73 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 es a connection
a0a0: 74 6f 20 61 20 76 69 72 74 75 61 6c 20 74 61 62 to a virtual tab
a0b0: 6c 65 2c 20 6a 75 73 74 20 6c 69 6b 65 20 0d 0a le, just like ..
a0c0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 20 /// the
a0d0: 78 44 69 73 63 6f 6e 6e 65 63 74 20 6d 65 74 68 xDisconnect meth
a0e0: 6f 64 2c 20 61 6e 64 20 69 74 20 61 6c 73 6f 20 od, and it also
a0f0: 64 65 73 74 72 6f 79 73 20 74 68 65 20 75 6e 64 destroys the und
a100: 65 72 6c 79 69 6e 67 20 0d 0a 20 20 20 20 20 20 erlying ..
a110: 20 20 2f 2f 2f 20 74 61 62 6c 65 20 69 6d 70 6c /// table impl
a120: 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 54 68 69 73 ementation. This
a130: 20 6d 65 74 68 6f 64 20 75 6e 64 6f 65 73 20 74 method undoes t
a140: 68 65 20 77 6f 72 6b 20 6f 66 20 78 43 72 65 61 he work of xCrea
a150: 74 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f te... ///
a160: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 </para>..
a170: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 /// <para>..
a180: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 44 /// The xD
a190: 69 73 63 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64 isconnect method
a1a0: 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 is called whene
a1b0: 76 65 72 20 61 20 64 61 74 61 62 61 73 65 20 63 ver a database c
a1c0: 6f 6e 6e 65 63 74 69 6f 6e 0d 0a 20 20 20 20 20 onnection..
a1d0: 20 20 20 2f 2f 2f 20 74 68 61 74 20 75 73 65 73 /// that uses
a1e0: 20 61 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 a virtual table
a1f0: 20 69 73 20 63 6c 6f 73 65 64 2e 20 54 68 65 20 is closed. The
a200: 78 44 65 73 74 72 6f 79 20 6d 65 74 68 6f 64 20 xDestroy method
a210: 69 73 20 6f 6e 6c 79 20 0d 0a 20 20 20 20 20 20 is only ..
a220: 20 20 2f 2f 2f 20 63 61 6c 6c 65 64 20 77 68 65 /// called whe
a230: 6e 20 61 20 44 52 4f 50 20 54 41 42 4c 45 20 73 n a DROP TABLE s
a240: 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 tatement is exec
a250: 75 74 65 64 20 61 67 61 69 6e 73 74 20 74 68 65 uted against the
a260: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 0d virtual table..
a270: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 . /// </p
a280: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ara>.. //
a290: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 / <para>..
a2a0: 20 20 2f 2f 2f 20 54 68 65 20 78 44 65 73 74 72 /// The xDestr
a2b0: 6f 79 20 6d 65 74 68 6f 64 20 69 73 20 72 65 71 oy method is req
a2c0: 75 69 72 65 64 20 66 6f 72 20 65 76 65 72 79 20 uired for every
a2d0: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d virtual table im
a2e0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 0d 0a 20 plementation,..
a2f0: 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 6f 75 67 /// thoug
a300: 68 20 69 74 20 69 73 20 61 63 63 65 70 74 61 62 h it is acceptab
a310: 6c 65 20 66 6f 72 20 74 68 65 20 78 44 69 73 63 le for the xDisc
a320: 6f 6e 6e 65 63 74 20 61 6e 64 20 78 44 65 73 74 onnect and xDest
a330: 72 6f 79 20 6d 65 74 68 6f 64 73 20 74 6f 20 62 roy methods to b
a340: 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 e.. /// t
a350: 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e he same function
a360: 20 69 66 20 74 68 61 74 20 6d 61 6b 65 73 20 73 if that makes s
a370: 65 6e 73 65 20 66 6f 72 20 74 68 65 20 70 61 72 ense for the par
a380: 74 69 63 75 6c 61 72 20 76 69 72 74 75 61 6c 20 ticular virtual
a390: 74 61 62 6c 65 2e 0d 0a 20 20 20 20 20 20 20 20 table...
a3a0: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 /// </para>..
a3b0: 20 20 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 /// </summa
a3c0: 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ry>.. ///
a3d0: 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 56 <param name="pV
a3e0: 74 61 62 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f tab">.. /
a3f0: 2f 2f 20 54 68 65 20 6e 61 74 69 76 65 20 70 6f // The native po
a400: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c inter to the sql
a410: 69 74 65 33 5f 76 74 61 62 20 64 65 72 69 76 65 ite3_vtab derive
a420: 64 20 73 74 72 75 63 74 75 72 65 2e 0d 0a 20 20 d structure...
a430: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 /// </para
a440: 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 m>.. ///
a450: 3c 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 <returns>..
a460: 20 20 20 2f 2f 2f 20 41 20 73 74 61 6e 64 61 72 /// A standar
a470: 64 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 20 d SQLite return
a480: 63 6f 64 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f code... /
a490: 2f 2f 20 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a 20 // </returns>..
a4a0: 20 20 20 20 20 20 20 53 51 4c 69 74 65 45 72 72 SQLiteErr
a4b0: 6f 72 43 6f 64 65 20 78 44 65 73 74 72 6f 79 28 orCode xDestroy(
a4c0: 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 49 6e .. In
a4d0: 74 50 74 72 20 70 56 74 61 62 0d 0a 20 20 20 20 tPtr pVtab..
a4e0: 20 20 20 20 20 20 20 20 29 3b 0d 0a 0d 0a 20 20 );....
a4f0: 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f //////////
a500: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
a510: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
a520: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
a530: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d /////////////...
a540: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 73 75 . /// <su
a550: 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 mmary>..
a560: 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e /// <para><code>
a570: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e .. /// in
a580: 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 t (*xOpen)(sqlit
a590: 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 e3_vtab *pVTab,
a5a0: 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 sqlite3_vtab_cur
a5b0: 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b sor **ppCursor);
a5c0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f .. /// </
a5d0: 63 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 code></para>..
a5e0: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e /// <para>
a5f0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 .. /// Th
a600: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 63 e xOpen method c
a610: 72 65 61 74 65 73 20 61 20 6e 65 77 20 63 75 72 reates a new cur
a620: 73 6f 72 20 75 73 65 64 20 66 6f 72 20 61 63 63 sor used for acc
a630: 65 73 73 69 6e 67 20 28 72 65 61 64 20 61 6e 64 essing (read and
a640: 2f 6f 72 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f /or.. ///
a650: 20 77 72 69 74 69 6e 67 29 20 61 20 76 69 72 74 writing) a virt
a660: 75 61 6c 20 74 61 62 6c 65 2e 20 20 41 20 73 75 ual table. A su
a670: 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 ccessful invocat
a680: 69 6f 6e 20 6f 66 20 74 68 69 73 20 6d 65 74 68 ion of this meth
a690: 6f 64 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f od .. ///
a6a0: 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 will allocate t
a6b0: 68 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 74 68 he memory for th
a6c0: 65 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 e sqlite3_vtab_c
a6d0: 75 72 73 6f 72 20 28 6f 72 20 61 20 73 75 62 63 ursor (or a subc
a6e0: 6c 61 73 73 29 2c 0d 0a 20 20 20 20 20 20 20 20 lass),..
a6f0: 2f 2f 2f 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 /// initialize t
a700: 68 65 20 6e 65 77 20 6f 62 6a 65 63 74 2c 20 61 he new object, a
a710: 6e 64 20 6d 61 6b 65 20 2a 70 70 43 75 72 73 6f nd make *ppCurso
a720: 72 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 6e r point to the n
a730: 65 77 20 6f 62 6a 65 63 74 2e 0d 0a 20 20 20 20 ew object...
a740: 20 20 20 20 2f 2f 2f 20 54 68 65 20 73 75 63 63 /// The succ
a750: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 68 65 6e essful call then
a760: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f returns SQLITE_
a770: 4f 4b 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f OK... ///
a780: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 </para>..
a790: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 /// <para>..
a7a0: 20 20 20 20 20 20 2f 2f 2f 20 46 6f 72 20 65 76 /// For ev
a7b0: 65 72 79 20 73 75 63 63 65 73 73 66 75 6c 20 63 ery successful c
a7c0: 61 6c 6c 20 74 6f 20 74 68 69 73 20 6d 65 74 68 all to this meth
a7d0: 6f 64 2c 20 74 68 65 20 53 51 4c 69 74 65 20 63 od, the SQLite c
a7e0: 6f 72 65 20 77 69 6c 6c 0d 0a 20 20 20 20 20 20 ore will..
a7f0: 20 20 2f 2f 2f 20 6c 61 74 65 72 20 69 6e 76 6f /// later invo
a800: 6b 65 20 74 68 65 20 78 43 6c 6f 73 65 20 6d 65 ke the xClose me
a810: 74 68 6f 64 20 74 6f 20 64 65 73 74 72 6f 79 20 thod to destroy
a820: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 .. /// th
a830: 65 20 61 6c 6c 6f 63 61 74 65 64 20 63 75 72 73 e allocated curs
a840: 6f 72 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f or... ///
a850: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 </para>..
a860: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 /// <para>..
a870: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 4f /// The xO
a880: 70 65 6e 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 pen method need
a890: 6e 6f 74 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 not initialize t
a8a0: 68 65 20 70 56 74 61 62 20 66 69 65 6c 64 20 6f he pVtab field o
a8b0: 66 20 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f f the.. /
a8c0: 2f 2f 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f // sqlite3_vtab_
a8d0: 63 75 72 73 6f 72 20 73 74 72 75 63 74 75 72 65 cursor structure
a8e0: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f . The SQLite co
a8f0: 72 65 20 77 69 6c 6c 20 74 61 6b 65 20 63 61 72 re will take car
a900: 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6f e.. /// o
a910: 66 20 74 68 61 74 20 63 68 6f 72 65 20 61 75 74 f that chore aut
a920: 6f 6d 61 74 69 63 61 6c 6c 79 2e 0d 0a 20 20 20 omatically...
a930: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e /// </para>
a940: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 .. /// <p
a950: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ara>.. //
a960: 2f 20 41 20 76 69 72 74 75 61 6c 20 74 61 62 6c / A virtual tabl
a970: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
a980: 20 6d 75 73 74 20 62 65 20 61 62 6c 65 20 74 6f must be able to
a990: 20 73 75 70 70 6f 72 74 20 61 6e 20 61 72 62 69 support an arbi
a9a0: 74 72 61 72 79 0d 0a 20 20 20 20 20 20 20 20 2f trary.. /
a9b0: 2f 2f 20 6e 75 6d 62 65 72 20 6f 66 20 73 69 6d // number of sim
a9c0: 75 6c 74 61 6e 65 6f 75 73 6c 79 20 6f 70 65 6e ultaneously open
a9d0: 20 63 75 72 73 6f 72 73 2e 0d 0a 20 20 20 20 20 cursors...
a9e0: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a /// </para>..
a9f0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 /// <par
aa00: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 a>.. ///
aa10: 57 68 65 6e 20 69 6e 69 74 69 61 6c 6c 79 20 6f When initially o
aa20: 70 65 6e 65 64 2c 20 74 68 65 20 63 75 72 73 6f pened, the curso
aa30: 72 20 69 73 20 69 6e 20 61 6e 20 75 6e 64 65 66 r is in an undef
aa40: 69 6e 65 64 20 73 74 61 74 65 2e 0d 0a 20 20 20 ined state...
aa50: 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 53 51 4c /// The SQL
aa60: 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 69 6e ite core will in
aa70: 76 6f 6b 65 20 74 68 65 20 78 46 69 6c 74 65 72 voke the xFilter
aa80: 20 6d 65 74 68 6f 64 0d 0a 20 20 20 20 20 20 20 method..
aa90: 20 2f 2f 2f 20 6f 6e 20 74 68 65 20 63 75 72 73 /// on the curs
aaa0: 6f 72 20 70 72 69 6f 72 20 74 6f 20 61 6e 79 20 or prior to any
aab0: 61 74 74 65 6d 70 74 20 74 6f 20 70 6f 73 69 74 attempt to posit
aac0: 69 6f 6e 20 6f 72 20 72 65 61 64 20 66 72 6f 6d ion or read from
aad0: 20 74 68 65 20 63 75 72 73 6f 72 2e 0d 0a 20 20 the cursor...
aae0: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 /// </para
aaf0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c >.. /// <
ab00: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f para>.. /
ab10: 2f 2f 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 // The xOpen met
ab20: 68 6f 64 20 69 73 20 72 65 71 75 69 72 65 64 20 hod is required
ab30: 66 6f 72 20 65 76 65 72 79 20 76 69 72 74 75 61 for every virtua
ab40: 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e l table implemen
ab50: 74 61 74 69 6f 6e 2e 0d 0a 20 20 20 20 20 20 20 tation...
ab60: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 /// </para>..
ab70: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d /// </summ
ab80: 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ary>.. //
ab90: 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 / <param name="p
aba0: 56 74 61 62 22 3e 0d 0a 20 20 20 20 20 20 20 20 Vtab">..
abb0: 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76 65 20 70 /// The native p
abc0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 71 ointer to the sq
abd0: 6c 69 74 65 33 5f 76 74 61 62 20 64 65 72 69 76 lite3_vtab deriv
abe0: 65 64 20 73 74 72 75 63 74 75 72 65 2e 0d 0a 20 ed structure...
abf0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 /// </par
ac00: 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f am>.. ///
ac10: 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 43 <param name="pC
ac20: 75 72 73 6f 72 22 3e 0d 0a 20 20 20 20 20 20 20 ursor">..
ac30: 20 2f 2f 2f 20 55 70 6f 6e 20 73 75 63 63 65 73 /// Upon succes
ac40: 73 2c 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 s, this paramete
ac50: 72 20 6d 75 73 74 20 62 65 20 6d 6f 64 69 66 69 r must be modifi
ac60: 65 64 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 ed to point to t
ac70: 68 65 20 6e 65 77 6c 79 0d 0a 20 20 20 20 20 20 he newly..
ac80: 20 20 2f 2f 2f 20 63 72 65 61 74 65 64 20 6e 61 /// created na
ac90: 74 69 76 65 20 73 71 6c 69 74 65 33 5f 76 74 61 tive sqlite3_vta
aca0: 62 5f 63 75 72 73 6f 72 20 64 65 72 69 76 65 64 b_cursor derived
acb0: 20 73 74 72 75 63 74 75 72 65 2e 0d 0a 20 20 20 structure...
acc0: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d /// </param
acd0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c >.. /// <
ace0: 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 returns>..
acf0: 20 20 2f 2f 2f 20 41 20 73 74 61 6e 64 61 72 64 /// A standard
ad00: 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 20 63 SQLite return c
ad10: 6f 64 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ode... //
ad20: 2f 20 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a 20 20 / </returns>..
ad30: 20 20 20 20 20 20 53 51 4c 69 74 65 45 72 72 6f SQLiteErro
ad40: 72 43 6f 64 65 20 78 4f 70 65 6e 28 0d 0a 20 20 rCode xOpen(..
ad50: 20 20 20 20 20 20 20 20 20 20 49 6e 74 50 74 72 IntPtr
ad60: 20 70 56 74 61 62 2c 0d 0a 20 20 20 20 20 20 20 pVtab,..
ad70: 20 20 20 20 20 72 65 66 20 49 6e 74 50 74 72 20 ref IntPtr
ad80: 70 43 75 72 73 6f 72 0d 0a 20 20 20 20 20 20 20 pCursor..
ad90: 20 20 20 20 20 29 3b 0d 0a 0d 0a 20 20 20 20 20 );....
ada0: 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f /////////////
adb0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
adc0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
add0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
ade0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 //////////....
adf0: 20 20 20 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61 /// <summa
ae00: 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ry>.. ///
ae10: 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 <para><code>..
ae20: 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e 74 20 28 /// int (
ae30: 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 *xClose)(sqlite3
ae40: 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0d _vtab_cursor*);.
ae50: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 . /// </c
ae60: 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 ode></para>..
ae70: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d /// <para>.
ae80: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 . /// The
ae90: 20 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 20 63 xClose method c
aea0: 6c 6f 73 65 73 20 61 20 63 75 72 73 6f 72 20 70 loses a cursor p
aeb0: 72 65 76 69 6f 75 73 6c 79 20 6f 70 65 6e 65 64 reviously opened
aec0: 20 62 79 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f by .. //
aed0: 2f 20 78 4f 70 65 6e 2e 20 0d 0a 20 20 20 20 20 / xOpen. ..
aee0: 20 20 20 2f 2f 2f 20 54 68 65 20 53 51 4c 69 74 /// The SQLit
aef0: 65 20 63 6f 72 65 20 77 69 6c 6c 20 61 6c 77 61 e core will alwa
af00: 79 73 20 63 61 6c 6c 20 78 43 6c 6f 73 65 20 6f ys call xClose o
af10: 6e 63 65 20 66 6f 72 20 65 61 63 68 20 63 75 72 nce for each cur
af20: 73 6f 72 20 6f 70 65 6e 65 64 20 0d 0a 20 20 20 sor opened ..
af30: 20 20 20 20 20 2f 2f 2f 20 75 73 69 6e 67 20 78 /// using x
af40: 4f 70 65 6e 2e 0d 0a 20 20 20 20 20 20 20 20 2f Open... /
af50: 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 // </para>..
af60: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a /// <para>..
af70: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 69 73 /// This
af80: 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 72 65 6c method must rel
af90: 65 61 73 65 20 61 6c 6c 20 72 65 73 6f 75 72 63 ease all resourc
afa0: 65 73 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 es allocated by
afb0: 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f the.. ///
afc0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 78 corresponding x
afd0: 4f 70 65 6e 20 63 61 6c 6c 2e 20 54 68 65 20 72 Open call. The r
afe0: 6f 75 74 69 6e 65 20 77 69 6c 6c 20 6e 6f 74 20 outine will not
aff0: 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 be called again
b000: 65 76 65 6e 20 69 66 20 69 74 0d 0a 20 20 20 20 even if it..
b010: 20 20 20 20 2f 2f 2f 20 72 65 74 75 72 6e 73 20 /// returns
b020: 61 6e 20 65 72 72 6f 72 2e 20 20 54 68 65 20 53 an error. The S
b030: 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 QLite core will
b040: 6e 6f 74 20 75 73 65 20 74 68 65 0d 0a 20 20 20 not use the..
b050: 20 20 20 20 20 2f 2f 2f 20 73 71 6c 69 74 65 33 /// sqlite3
b060: 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 61 67 61 _vtab_cursor aga
b070: 69 6e 20 61 66 74 65 72 20 69 74 20 68 61 73 20 in after it has
b080: 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0d 0a 20 20 been closed...
b090: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 /// </para
b0a0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c >.. /// <
b0b0: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f para>.. /
b0c0: 2f 2f 20 54 68 65 20 78 43 6c 6f 73 65 20 6d 65 // The xClose me
b0d0: 74 68 6f 64 20 69 73 20 72 65 71 75 69 72 65 64 thod is required
b0e0: 20 66 6f 72 20 65 76 65 72 79 20 76 69 72 74 75 for every virtu
b0f0: 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 al table impleme
b100: 6e 74 61 74 69 6f 6e 2e 0d 0a 20 20 20 20 20 20 ntation...
b110: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 /// </para>..
b120: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d /// </sum
b130: 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f mary>.. /
b140: 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 // <param name="
b150: 70 43 75 72 73 6f 72 22 3e 0d 0a 20 20 20 20 20 pCursor">..
b160: 20 20 20 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76 /// The nativ
b170: 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 e pointer to the
b180: 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 sqlite3_vtab_cu
b190: 72 73 6f 72 20 64 65 72 69 76 65 64 20 73 74 72 rsor derived str
b1a0: 75 63 74 75 72 65 2e 0d 0a 20 20 20 20 20 20 20 ucture...
b1b0: 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 /// </param>..
b1c0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 72 65 74 75 /// <retu
b1d0: 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f rns>.. //
b1e0: 2f 20 41 20 73 74 61 6e 64 61 72 64 20 53 51 4c / A standard SQL
b1f0: 69 74 65 20 72 65 74 75 72 6e 20 63 6f 64 65 2e ite return code.
b200: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f .. /// </
b210: 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 returns>..
b220: 20 20 53 51 4c 69 74 65 45 72 72 6f 72 43 6f 64 SQLiteErrorCod
b230: 65 20 78 43 6c 6f 73 65 28 0d 0a 20 20 20 20 20 e xClose(..
b240: 20 20 20 20 20 20 20 49 6e 74 50 74 72 20 70 43 IntPtr pC
b250: 75 72 73 6f 72 0d 0a 20 20 20 20 20 20 20 20 20 ursor..
b260: 20 20 20 29 3b 0d 0a 0d 0a 20 20 20 20 20 20 20 );....
b270: 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ///////////////
b280: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
b290: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
b2a0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
b2b0: 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 ////////....
b2c0: 20 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79 /// <summary
b2d0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c >.. /// <
b2e0: 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 para><code>..
b2f0: 20 20 20 20 20 2f 2f 2f 20 69 6e 74 20 28 2a 78 /// int (*x
b300: 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f Filter)(sqlite3_
b310: 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e vtab_cursor*, in
b320: 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 t idxNum, const
b330: 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0d 0a 20 char *idxStr,..
b340: 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 20 20 ///
b350: 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 int arg
b360: 63 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 c, sqlite3_value
b370: 20 2a 2a 61 72 67 76 29 3b 0d 0a 20 20 20 20 20 **argv);..
b380: 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f /// </code></
b390: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f para>.. /
b3a0: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 // <para>..
b3b0: 20 20 20 2f 2f 2f 20 54 68 69 73 20 6d 65 74 68 /// This meth
b3c0: 6f 64 20 62 65 67 69 6e 73 20 61 20 73 65 61 72 od begins a sear
b3d0: 63 68 20 6f 66 20 61 20 76 69 72 74 75 61 6c 20 ch of a virtual
b3e0: 74 61 62 6c 65 2e 20 0d 0a 20 20 20 20 20 20 20 table. ..
b3f0: 20 2f 2f 2f 20 54 68 65 20 66 69 72 73 74 20 61 /// The first a
b400: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63 75 72 rgument is a cur
b410: 73 6f 72 20 6f 70 65 6e 65 64 20 62 79 20 78 4f sor opened by xO
b420: 70 65 6e 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f pen. .. /
b430: 2f 2f 20 54 68 65 20 6e 65 78 74 20 74 77 6f 20 // The next two
b440: 61 72 67 75 6d 65 6e 74 73 20 64 65 66 69 6e 65 arguments define
b450: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 65 a particular se
b460: 61 72 63 68 20 69 6e 64 65 78 20 70 72 65 76 69 arch index previ
b470: 6f 75 73 6c 79 20 0d 0a 20 20 20 20 20 20 20 20 ously ..
b480: 2f 2f 2f 20 63 68 6f 73 65 6e 20 62 79 20 78 42 /// chosen by xB
b490: 65 73 74 49 6e 64 65 78 2e 20 54 68 65 20 73 70 estIndex. The sp
b4a0: 65 63 69 66 69 63 20 6d 65 61 6e 69 6e 67 73 20 ecific meanings
b4b0: 6f 66 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 of idxNum and id
b4c0: 78 53 74 72 20 0d 0a 20 20 20 20 20 20 20 20 2f xStr .. /
b4d0: 2f 2f 20 61 72 65 20 75 6e 69 6d 70 6f 72 74 61 // are unimporta
b4e0: 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 78 46 nt as long as xF
b4f0: 69 6c 74 65 72 20 61 6e 64 20 78 42 65 73 74 49 ilter and xBestI
b500: 6e 64 65 78 20 61 67 72 65 65 20 6f 6e 20 77 68 ndex agree on wh
b510: 61 74 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f at .. ///
b520: 20 74 68 61 74 20 6d 65 61 6e 69 6e 67 20 69 73 that meaning is
b530: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c ... /// <
b540: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 /para>..
b550: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 /// <para>..
b560: 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 42 65 73 /// The xBes
b570: 74 49 6e 64 65 78 20 66 75 6e 63 74 69 6f 6e 20 tIndex function
b580: 6d 61 79 20 68 61 76 65 20 72 65 71 75 65 73 74 may have request
b590: 65 64 20 74 68 65 20 76 61 6c 75 65 73 20 6f 66 ed the values of
b5a0: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 63 .. /// c
b5b0: 65 72 74 61 69 6e 20 65 78 70 72 65 73 73 69 6f ertain expressio
b5c0: 6e 73 20 75 73 69 6e 67 20 74 68 65 20 61 43 6f ns using the aCo
b5d0: 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e nstraintUsage[].
b5e0: 61 72 67 76 49 6e 64 65 78 20 76 61 6c 75 65 73 argvIndex values
b5f0: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6f .. /// o
b600: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e f the sqlite3_in
b610: 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 dex_info structu
b620: 72 65 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f re. .. //
b630: 2f 20 54 68 6f 73 65 20 76 61 6c 75 65 73 20 61 / Those values a
b640: 72 65 20 70 61 73 73 65 64 20 74 6f 20 78 46 69 re passed to xFi
b650: 6c 74 65 72 20 75 73 69 6e 67 20 74 68 65 20 61 lter using the a
b660: 72 67 63 20 61 6e 64 20 61 72 67 76 20 70 61 72 rgc and argv par
b670: 61 6d 65 74 65 72 73 2e 0d 0a 20 20 20 20 20 20 ameters...
b680: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 /// </para>..
b690: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 /// <para
b6a0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 49 >.. /// I
b6b0: 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 f the virtual ta
b6c0: 62 6c 65 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 65 ble contains one
b6d0: 20 6f 72 20 6d 6f 72 65 20 72 6f 77 73 20 74 68 or more rows th
b6e0: 61 74 20 6d 61 74 63 68 20 74 68 65 0d 0a 20 20 at match the..
b6f0: 20 20 20 20 20 20 2f 2f 2f 20 73 65 61 72 63 68 /// search
b700: 20 63 72 69 74 65 72 69 61 2c 20 74 68 65 6e 20 criteria, then
b710: 74 68 65 20 63 75 72 73 6f 72 20 6d 75 73 74 20 the cursor must
b720: 62 65 20 6c 65 66 74 20 70 6f 69 6e 74 20 61 74 be left point at
b730: 20 74 68 65 20 66 69 72 73 74 20 72 6f 77 2e 0d the first row..
b740: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 53 75 62 . /// Sub
b750: 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f sequent calls to
b760: 20 78 45 6f 66 20 6d 75 73 74 20 72 65 74 75 72 xEof must retur
b770: 6e 20 66 61 6c 73 65 20 28 7a 65 72 6f 29 2e 0d n false (zero)..
b780: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 49 66 20 . /// If
b790: 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 6f 77 there are no row
b7a0: 73 20 6d 61 74 63 68 2c 20 74 68 65 6e 20 74 68 s match, then th
b7b0: 65 20 63 75 72 73 6f 72 20 6d 75 73 74 20 62 65 e cursor must be
b7c0: 20 6c 65 66 74 20 69 6e 20 61 20 73 74 61 74 65 left in a state
b7d0: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 .. /// t
b7e0: 68 61 74 20 77 69 6c 6c 20 63 61 75 73 65 20 74 hat will cause t
b7f0: 68 65 20 78 45 6f 66 20 74 6f 20 72 65 74 75 72 he xEof to retur
b800: 6e 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f n true (non-zero
b810: 29 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 )... ///
b820: 54 68 65 20 53 51 4c 69 74 65 20 65 6e 67 69 6e The SQLite engin
b830: 65 20 77 69 6c 6c 20 75 73 65 0d 0a 20 20 20 20 e will use..
b840: 20 20 20 20 2f 2f 2f 20 74 68 65 20 78 43 6f 6c /// the xCol
b850: 75 6d 6e 20 61 6e 64 20 78 52 6f 77 69 64 20 6d umn and xRowid m
b860: 65 74 68 6f 64 73 20 74 6f 20 61 63 63 65 73 73 ethods to access
b870: 20 74 68 61 74 20 72 6f 77 20 63 6f 6e 74 65 6e that row conten
b880: 74 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 t... ///
b890: 54 68 65 20 78 4e 65 78 74 20 6d 65 74 68 6f 64 The xNext method
b8a0: 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f will be used to
b8b0: 20 61 64 76 61 6e 63 65 20 74 6f 20 74 68 65 20 advance to the
b8c0: 6e 65 78 74 20 72 6f 77 2e 0d 0a 20 20 20 20 20 next row...
b8d0: 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a /// </para>..
b8e0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 /// <par
b8f0: 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 a>.. ///
b900: 54 68 69 73 20 6d 65 74 68 6f 64 20 6d 75 73 74 This method must
b910: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f return SQLITE_O
b920: 4b 20 69 66 20 73 75 63 63 65 73 73 66 75 6c 2c K if successful,
b930: 20 6f 72 20 61 6e 20 73 71 6c 69 74 65 20 0d 0a or an sqlite ..
b940: 20 20 20 20 20 20 20 20 2f 2f 2f 20 65 72 72 6f /// erro
b950: 72 20 63 6f 64 65 20 69 66 20 61 6e 20 65 72 72 r code if an err
b960: 6f 72 20 6f 63 63 75 72 73 2e 0d 0a 20 20 20 20 or occurs...
b970: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d /// </para>.
b980: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 . /// <pa
b990: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ra>.. ///
b9a0: 20 54 68 65 20 78 46 69 6c 74 65 72 20 6d 65 74 The xFilter met
b9b0: 68 6f 64 20 69 73 20 72 65 71 75 69 72 65 64 20 hod is required
b9c0: 66 6f 72 20 65 76 65 72 79 20 76 69 72 74 75 61 for every virtua
b9d0: 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e l table implemen
b9e0: 74 61 74 69 6f 6e 2e 0d 0a 20 20 20 20 20 20 20 tation...
b9f0: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 /// </para>..
ba00: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d /// </summ
ba10: 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ary>.. //
ba20: 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 / <param name="p
ba30: 43 75 72 73 6f 72 22 3e 0d 0a 20 20 20 20 20 20 Cursor">..
ba40: 20 20 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76 65 /// The native
ba50: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
ba60: 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 sqlite3_vtab_cur
ba70: 73 6f 72 20 64 65 72 69 76 65 64 20 73 74 72 75 sor derived stru
ba80: 63 74 75 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 cture...
ba90: 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 /// </param>..
baa0: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d /// <param
bab0: 20 6e 61 6d 65 3d 22 69 64 78 4e 75 6d 22 3e 0d name="idxNum">.
bac0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 4e 75 6d . /// Num
bad0: 62 65 72 20 75 73 65 64 20 74 6f 20 68 65 6c 70 ber used to help
bae0: 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 73 65 identify the se
baf0: 6c 65 63 74 65 64 20 69 6e 64 65 78 2e 0d 0a 20 lected index...
bb00: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 /// </par
bb10: 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f am>.. ///
bb20: 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 69 64 <param name="id
bb30: 78 53 74 72 22 3e 0d 0a 20 20 20 20 20 20 20 20 xStr">..
bb40: 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76 65 20 70 /// The native p
bb50: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 55 54 ointer to the UT
bb60: 46 2d 38 20 65 6e 63 6f 64 65 64 20 73 74 72 69 F-8 encoded stri
bb70: 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 ng containing th
bb80: 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 e.. /// s
bb90: 74 72 69 6e 67 20 75 73 65 64 20 74 6f 20 68 65 tring used to he
bba0: 6c 70 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 lp identify the
bbb0: 73 65 6c 65 63 74 65 64 20 69 6e 64 65 78 2e 0d selected index..
bbc0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 . /// </p
bbd0: 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f aram>.. /
bbe0: 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 // <param name="
bbf0: 61 72 67 63 22 3e 0d 0a 20 20 20 20 20 20 20 20 argc">..
bc00: 2f 2f 2f 20 54 68 65 20 6e 75 6d 62 65 72 20 6f /// The number o
bc10: 66 20 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72 f native pointer
bc20: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 76 61 6c s to sqlite3_val
bc30: 75 65 20 73 74 72 75 63 74 75 72 65 73 20 73 70 ue structures sp
bc40: 65 63 69 66 69 65 64 0d 0a 20 20 20 20 20 20 20 ecified..
bc50: 20 2f 2f 2f 20 69 6e 20 3c 70 61 72 61 6d 72 65 /// in <paramre
bc60: 66 20 6e 61 6d 65 3d 22 61 72 67 76 22 20 2f 3e f name="argv" />
bc70: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c ... /// <
bc80: 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 /param>..
bc90: 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 /// <param name
bca0: 3d 22 61 72 67 76 22 3e 0d 0a 20 20 20 20 20 20 ="argv">..
bcb0: 20 20 2f 2f 2f 20 41 6e 20 61 72 72 61 79 20 6f /// An array o
bcc0: 66 20 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72 f native pointer
bcd0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 76 61 6c s to sqlite3_val
bce0: 75 65 20 73 74 72 75 63 74 75 72 65 73 20 63 6f ue structures co
bcf0: 6e 74 61 69 6e 69 6e 67 0d 0a 20 20 20 20 20 20 ntaining..
bd00: 20 20 2f 2f 2f 20 66 69 6c 74 65 72 69 6e 67 20 /// filtering
bd10: 63 72 69 74 65 72 69 61 20 66 6f 72 20 74 68 65 criteria for the
bd20: 20 73 65 6c 65 63 74 65 64 20 69 6e 64 65 78 2e selected index.
bd30: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f .. /// </
bd40: 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 param>..
bd50: 2f 2f 2f 20 3c 72 65 74 75 72 6e 73 3e 0d 0a 20 /// <returns>..
bd60: 20 20 20 20 20 20 20 2f 2f 2f 20 41 20 73 74 61 /// A sta
bd70: 6e 64 61 72 64 20 53 51 4c 69 74 65 20 72 65 74 ndard SQLite ret
bd80: 75 72 6e 20 63 6f 64 65 2e 0d 0a 20 20 20 20 20 urn code...
bd90: 20 20 20 2f 2f 2f 20 3c 2f 72 65 74 75 72 6e 73 /// </returns
bda0: 3e 0d 0a 20 20 20 20 20 20 20 20 53 51 4c 69 74 >.. SQLit
bdb0: 65 45 72 72 6f 72 43 6f 64 65 20 78 46 69 6c 74 eErrorCode xFilt
bdc0: 65 72 28 0d 0a 20 20 20 20 20 20 20 20 20 20 20 er(..
bdd0: 20 49 6e 74 50 74 72 20 70 43 75 72 73 6f 72 2c IntPtr pCursor,
bde0: 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 69 6e .. in
bdf0: 74 20 69 64 78 4e 75 6d 2c 0d 0a 20 20 20 20 20 t idxNum,..
be00: 20 20 20 20 20 20 20 49 6e 74 50 74 72 20 69 64 IntPtr id
be10: 78 53 74 72 2c 0d 0a 20 20 20 20 20 20 20 20 20 xStr,..
be20: 20 20 20 69 6e 74 20 61 72 67 63 2c 0d 0a 20 20 int argc,..
be30: 20 20 20 20 20 20 20 20 20 20 49 6e 74 50 74 72 IntPtr
be40: 20 61 72 67 76 0d 0a 20 20 20 20 20 20 20 20 20 argv..
be50: 20 20 20 29 3b 0d 0a 0d 0a 20 20 20 20 20 20 20 );....
be60: 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ///////////////
be70: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
be80: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
be90: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
bea0: 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 ////////....
beb0: 20 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79 /// <summary
bec0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c >.. /// <
bed0: 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 para><code>..
bee0: 20 20 20 20 20 2f 2f 2f 20 69 6e 74 20 28 2a 78 /// int (*x
bef0: 4e 65 78 74 29 28 73 71 6c 69 74 65 33 5f 76 74 Next)(sqlite3_vt
bf00: 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0d 0a 20 20 ab_cursor*);..
bf10: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 /// </code
bf20: 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 ></para>..
bf30: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 /// <para>..
bf40: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 4e /// The xN
bf50: 65 78 74 20 6d 65 74 68 6f 64 20 61 64 76 61 6e ext method advan
bf60: 63 65 73 20 61 20 76 69 72 74 75 61 6c 20 74 61 ces a virtual ta
bf70: 62 6c 65 20 63 75 72 73 6f 72 0d 0a 20 20 20 20 ble cursor..
bf80: 20 20 20 20 2f 2f 2f 20 74 6f 20 74 68 65 20 6e /// to the n
bf90: 65 78 74 20 72 6f 77 20 6f 66 20 61 20 72 65 73 ext row of a res
bfa0: 75 6c 74 20 73 65 74 20 69 6e 69 74 69 61 74 65 ult set initiate
bfb0: 64 20 62 79 20 78 46 69 6c 74 65 72 2e 20 0d 0a d by xFilter. ..
bfc0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 49 66 20 74 /// If t
bfd0: 68 65 20 63 75 72 73 6f 72 20 69 73 20 61 6c 72 he cursor is alr
bfe0: 65 61 64 79 20 70 6f 69 6e 74 69 6e 67 20 61 74 eady pointing at
bff0: 20 74 68 65 20 6c 61 73 74 20 72 6f 77 20 77 68 the last row wh
c000: 65 6e 20 74 68 69 73 20 0d 0a 20 20 20 20 20 20 en this ..
c010: 20 20 2f 2f 2f 20 72 6f 75 74 69 6e 65 20 69 73 /// routine is
c020: 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 74 68 called, then th
c030: 65 20 63 75 72 73 6f 72 20 6e 6f 20 6c 6f 6e 67 e cursor no long
c040: 65 72 20 70 6f 69 6e 74 73 20 74 6f 20 76 61 6c er points to val
c050: 69 64 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f id .. ///
c060: 20 64 61 74 61 20 61 6e 64 20 61 20 73 75 62 73 data and a subs
c070: 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 74 equent call to t
c080: 68 65 20 78 45 6f 66 20 6d 65 74 68 6f 64 20 6d he xEof method m
c090: 75 73 74 20 72 65 74 75 72 6e 20 74 72 75 65 20 ust return true
c0a0: 28 6e 6f 6e 2d 7a 65 72 6f 29 2e 20 0d 0a 20 20 (non-zero). ..
c0b0: 20 20 20 20 20 20 2f 2f 2f 20 49 66 20 74 68 65 /// If the
c0c0: 20 63 75 72 73 6f 72 20 69 73 20 73 75 63 63 65 cursor is succe
c0d0: 73 73 66 75 6c 6c 79 20 61 64 76 61 6e 63 65 64 ssfully advanced
c0e0: 20 74 6f 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 to another row
c0f0: 6f 66 20 63 6f 6e 74 65 6e 74 2c 20 74 68 65 6e of content, then
c100: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 75 .. /// su
c110: 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 bsequent calls t
c120: 6f 20 78 45 6f 66 20 6d 75 73 74 20 72 65 74 75 o xEof must retu
c130: 72 6e 20 66 61 6c 73 65 20 28 7a 65 72 6f 29 2e rn false (zero).
c140: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f .. /// </
c150: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f para>.. /
c160: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 // <para>..
c170: 20 20 20 2f 2f 2f 20 54 68 69 73 20 6d 65 74 68 /// This meth
c180: 6f 64 20 6d 75 73 74 20 72 65 74 75 72 6e 20 53 od must return S
c190: 51 4c 49 54 45 5f 4f 4b 20 69 66 20 73 75 63 63 QLITE_OK if succ
c1a0: 65 73 73 66 75 6c 2c 20 6f 72 20 61 6e 20 73 71 essful, or an sq
c1b0: 6c 69 74 65 20 0d 0a 20 20 20 20 20 20 20 20 2f lite .. /
c1c0: 2f 2f 20 65 72 72 6f 72 20 63 6f 64 65 20 69 66 // error code if
c1d0: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 an error occurs
c1e0: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c ... /// <
c1f0: 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 /para>..
c200: 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 /// <para>..
c210: 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 4e 65 78 /// The xNex
c220: 74 20 6d 65 74 68 6f 64 20 69 73 20 72 65 71 75 t method is requ
c230: 69 72 65 64 20 66 6f 72 20 65 76 65 72 79 20 76 ired for every v
c240: 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 irtual table imp
c250: 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0d 0a 20 20 lementation...
c260: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 /// </para
c270: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c >.. /// <
c280: 2f 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 /summary>..
c290: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 /// <param na
c2a0: 6d 65 3d 22 70 43 75 72 73 6f 72 22 3e 0d 0a 20 me="pCursor">..
c2b0: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e /// The n
c2c0: 61 74 69 76 65 20 70 6f 69 6e 74 65 72 20 74 6f ative pointer to
c2d0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 74 61 the sqlite3_vta
c2e0: 62 5f 63 75 72 73 6f 72 20 64 65 72 69 76 65 64 b_cursor derived
c2f0: 20 73 74 72 75 63 74 75 72 65 2e 0d 0a 20 20 20 structure...
c300: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d /// </param
c310: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c >.. /// <
c320: 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 returns>..
c330: 20 20 2f 2f 2f 20 41 20 73 74 61 6e 64 61 72 64 /// A standard
c340: 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 20 63 SQLite return c
c350: 6f 64 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ode... //
c360: 2f 20 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a 20 20 / </returns>..
c370: 20 20 20 20 20 20 53 51 4c 69 74 65 45 72 72 6f SQLiteErro
c380: 72 43 6f 64 65 20 78 4e 65 78 74 28 0d 0a 20 20 rCode xNext(..
c390: 20 20 20 20 20 20 20 20 20 20 49 6e 74 50 74 72 IntPtr
c3a0: 20 70 43 75 72 73 6f 72 0d 0a 20 20 20 20 20 20 pCursor..
c3b0: 20 20 20 20 20 20 29 3b 0d 0a 0d 0a 20 20 20 20 );....
c3c0: 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////
c3d0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
c3e0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
c3f0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
c400: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 ///////////....
c410: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d /// <summ
c420: 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ary>.. //
c430: 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a / <para><code>..
c440: 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e 74 20 /// int
c450: 28 2a 78 45 6f 66 29 28 73 71 6c 69 74 65 33 5f (*xEof)(sqlite3_
c460: 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0d 0a vtab_cursor*);..
c470: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f /// </co
c480: 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 de></para>..
c490: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a /// <para>..
c4a0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 /// The
c4b0: 78 45 6f 66 20 6d 65 74 68 6f 64 20 6d 75 73 74 xEof method must
c4c0: 20 72 65 74 75 72 6e 20 66 61 6c 73 65 20 28 7a return false (z
c4d0: 65 72 6f 29 20 69 66 20 74 68 65 20 73 70 65 63 ero) if the spec
c4e0: 69 66 69 65 64 20 63 75 72 73 6f 72 20 0d 0a 20 ified cursor ..
c4f0: 20 20 20 20 20 20 20 2f 2f 2f 20 63 75 72 72 65 /// curre
c500: 6e 74 6c 79 20 70 6f 69 6e 74 73 20 74 6f 20 61 ntly points to a
c510: 20 76 61 6c 69 64 20 72 6f 77 20 6f 66 20 64 61 valid row of da
c520: 74 61 2c 20 6f 72 20 74 72 75 65 20 28 6e 6f 6e ta, or true (non
c530: 2d 7a 65 72 6f 29 20 6f 74 68 65 72 77 69 73 65 -zero) otherwise
c540: 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 . .. ///
c550: 54 68 69 73 20 6d 65 74 68 6f 64 20 69 73 20 63 This method is c
c560: 61 6c 6c 65 64 20 62 79 20 74 68 65 20 53 51 4c alled by the SQL
c570: 20 65 6e 67 69 6e 65 20 69 6d 6d 65 64 69 61 74 engine immediat
c580: 65 6c 79 20 61 66 74 65 72 20 65 61 63 68 20 0d ely after each .
c590: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 78 46 69 . /// xFi
c5a0: 6c 74 65 72 20 61 6e 64 20 78 4e 65 78 74 20 69 lter and xNext i
c5b0: 6e 76 6f 63 61 74 69 6f 6e 2e 0d 0a 20 20 20 20 nvocation...
c5c0: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d /// </para>.
c5d0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 . /// <pa
c5e0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ra>.. ///
c5f0: 20 54 68 65 20 78 45 6f 66 20 6d 65 74 68 6f 64 The xEof method
c600: 20 69 73 20 72 65 71 75 69 72 65 64 20 66 6f 72 is required for
c610: 20 65 76 65 72 79 20 76 69 72 74 75 61 6c 20 74 every virtual t
c620: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 able implementat
c630: 69 6f 6e 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ion... //
c640: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 / </para>..
c650: 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79 /// </summary
c660: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c >.. /// <
c670: 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 43 75 72 param name="pCur
c680: 73 6f 72 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f sor">.. /
c690: 2f 2f 20 54 68 65 20 6e 61 74 69 76 65 20 70 6f // The native po
c6a0: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c inter to the sql
c6b0: 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 ite3_vtab_cursor
c6c0: 20 64 65 72 69 76 65 64 20 73 74 72 75 63 74 75 derived structu
c6d0: 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f re... ///
c6e0: 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 </param>..
c6f0: 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72 6e 73 3e /// <returns>
c700: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 4e 6f .. /// No
c710: 6e 2d 7a 65 72 6f 20 69 66 20 6e 6f 20 6d 6f 72 n-zero if no mor
c720: 65 20 72 6f 77 73 20 61 72 65 20 61 76 61 69 6c e rows are avail
c730: 61 62 6c 65 3b 20 7a 65 72 6f 20 6f 74 68 65 72 able; zero other
c740: 77 69 73 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f wise... /
c750: 2f 2f 20 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a 20 // </returns>..
c760: 20 20 20 20 20 20 20 69 6e 74 20 78 45 6f 66 28 int xEof(
c770: 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 49 6e .. In
c780: 74 50 74 72 20 70 43 75 72 73 6f 72 0d 0a 20 20 tPtr pCursor..
c790: 20 20 20 20 20 20 20 20 20 20 29 3b 0d 0a 0d 0a );....
c7a0: 20 20 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f ////////
c7b0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
c7c0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
c7d0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
c7e0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d ///////////////.
c7f0: 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c ... /// <
c800: 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 summary>..
c810: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 /// <para><cod
c820: 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 e>.. ///
c830: 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 int (*xColumn)(s
c840: 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 qlite3_vtab_curs
c850: 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e or*, sqlite3_con
c860: 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0d 0a text*, int N);..
c870: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f /// </co
c880: 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 de></para>..
c890: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a /// <para>..
c8a0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 /// The
c8b0: 53 51 4c 69 74 65 20 63 6f 72 65 20 69 6e 76 6f SQLite core invo
c8c0: 6b 65 73 20 74 68 69 73 20 6d 65 74 68 6f 64 20 kes this method
c8d0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 in order to find
c8e0: 20 74 68 65 20 76 61 6c 75 65 20 66 6f 72 20 0d the value for .
c8f0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 65 . /// the
c900: 20 4e 2d 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 N-th column of
c910: 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 2e the current row.
c920: 20 4e 20 69 73 20 7a 65 72 6f 2d 62 61 73 65 64 N is zero-based
c930: 20 73 6f 20 74 68 65 20 66 69 72 73 74 20 63 6f so the first co
c940: 6c 75 6d 6e 20 0d 0a 20 20 20 20 20 20 20 20 2f lumn .. /
c950: 2f 2f 20 69 73 20 6e 75 6d 62 65 72 65 64 20 30 // is numbered 0
c960: 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 . .. ///
c970: 54 68 65 20 78 43 6f 6c 75 6d 6e 20 6d 65 74 68 The xColumn meth
c980: 6f 64 20 6d 61 79 20 72 65 74 75 72 6e 20 69 74 od may return it
c990: 73 20 72 65 73 75 6c 74 20 62 61 63 6b 20 74 6f s result back to
c9a0: 20 53 51 4c 69 74 65 20 75 73 69 6e 67 20 6f 6e SQLite using on
c9b0: 65 20 6f 66 20 74 68 65 0d 0a 20 20 20 20 20 20 e of the..
c9c0: 20 20 2f 2f 2f 20 66 6f 6c 6c 6f 77 69 6e 67 20 /// following
c9d0: 69 6e 74 65 72 66 61 63 65 3a 0d 0a 20 20 20 20 interface:..
c9e0: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d /// </para>.
c9f0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 . /// <pa
ca00: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ra>.. ///
ca10: 20 3c 21 5b 43 44 41 54 41 5b 3c 75 6c 3e 5d 5d <![CDATA[<ul>]]
ca20: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c >.. /// <
ca30: 21 5b 43 44 41 54 41 5b 3c 6c 69 3e 5d 5d 3e 20 ![CDATA[<li>]]>
ca40: 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 sqlite3_result_b
ca50: 6c 6f 62 28 29 0d 0a 20 20 20 20 20 20 20 20 2f lob().. /
ca60: 2f 2f 20 3c 21 5b 43 44 41 54 41 5b 3c 2f 6c 69 // <![CDATA[</li
ca70: 3e 5d 5d 3e 3c 21 5b 43 44 41 54 41 5b 3c 6c 69 >]]><![CDATA[<li
ca80: 3e 5d 5d 3e 20 73 71 6c 69 74 65 33 5f 72 65 73 >]]> sqlite3_res
ca90: 75 6c 74 5f 64 6f 75 62 6c 65 28 29 0d 0a 20 20 ult_double()..
caa0: 20 20 20 20 20 20 2f 2f 2f 20 3c 21 5b 43 44 41 /// <![CDA
cab0: 54 41 5b 3c 2f 6c 69 3e 5d 5d 3e 3c 21 5b 43 44 TA[</li>]]><![CD
cac0: 41 54 41 5b 3c 6c 69 3e 5d 5d 3e 20 73 71 6c 69 ATA[<li>]]> sqli
cad0: 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 te3_result_int()
cae0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 21 .. /// <!
caf0: 5b 43 44 41 54 41 5b 3c 2f 6c 69 3e 5d 5d 3e 3c [CDATA[</li>]]><
cb00: 21 5b 43 44 41 54 41 5b 3c 6c 69 3e 5d 5d 3e 20 ![CDATA[<li>]]>
cb10: 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 sqlite3_result_i
cb20: 6e 74 36 34 28 29 0d 0a 20 20 20 20 20 20 20 20 nt64()..
cb30: 2f 2f 2f 20 3c 21 5b 43 44 41 54 41 5b 3c 2f 6c /// <![CDATA[</l
cb40: 69 3e 5d 5d 3e 3c 21 5b 43 44 41 54 41 5b 3c 6c i>]]><![CDATA[<l
cb50: 69 3e 5d 5d 3e 20 73 71 6c 69 74 65 33 5f 72 65 i>]]> sqlite3_re
cb60: 73 75 6c 74 5f 6e 75 6c 6c 28 29 0d 0a 20 20 20 sult_null()..
cb70: 20 20 20 20 20 2f 2f 2f 20 3c 21 5b 43 44 41 54 /// <![CDAT
cb80: 41 5b 3c 2f 6c 69 3e 5d 5d 3e 3c 21 5b 43 44 41 A[</li>]]><![CDA
cb90: 54 41 5b 3c 6c 69 3e 5d 5d 3e 20 73 71 6c 69 74 TA[<li>]]> sqlit
cba0: 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 e3_result_text()
cbb0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 21 .. /// <!
cbc0: 5b 43 44 41 54 41 5b 3c 2f 6c 69 3e 5d 5d 3e 3c [CDATA[</li>]]><
cbd0: 21 5b 43 44 41 54 41 5b 3c 6c 69 3e 5d 5d 3e 20 ![CDATA[<li>]]>
cbe0: 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
cbf0: 65 78 74 31 36 28 29 0d 0a 20 20 20 20 20 20 20 ext16()..
cc00: 20 2f 2f 2f 20 3c 21 5b 43 44 41 54 41 5b 3c 2f /// <![CDATA[</
cc10: 6c 69 3e 5d 5d 3e 3c 21 5b 43 44 41 54 41 5b 3c li>]]><![CDATA[<
cc20: 6c 69 3e 5d 5d 3e 20 73 71 6c 69 74 65 33 5f 72 li>]]> sqlite3_r
cc30: 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 esult_text16le()
cc40: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 21 .. /// <!
cc50: 5b 43 44 41 54 41 5b 3c 2f 6c 69 3e 5d 5d 3e 3c [CDATA[</li>]]><
cc60: 21 5b 43 44 41 54 41 5b 3c 6c 69 3e 5d 5d 3e 20 ![CDATA[<li>]]>
cc70: 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
cc80: 65 78 74 31 36 62 65 28 29 0d 0a 20 20 20 20 20 ext16be()..
cc90: 20 20 20 2f 2f 2f 20 3c 21 5b 43 44 41 54 41 5b /// <![CDATA[
cca0: 3c 2f 6c 69 3e 5d 5d 3e 3c 21 5b 43 44 41 54 41 </li>]]><![CDATA
ccb0: 5b 3c 6c 69 3e 5d 5d 3e 20 73 71 6c 69 74 65 33 [<li>]]> sqlite3
ccc0: 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 _result_zeroblob
ccd0: 28 29 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 ().. ///
cce0: 3c 21 5b 43 44 41 54 41 5b 3c 2f 6c 69 3e 5d 5d <![CDATA[</li>]]
ccf0: 3e 3c 21 5b 43 44 41 54 41 5b 3c 2f 75 6c 3e 5d ><![CDATA[</ul>]
cd00: 5d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 ]>.. ///
cd10: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 </para>..
cd20: 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 /// <para>..
cd30: 20 20 20 20 20 2f 2f 2f 20 49 66 20 74 68 65 20 /// If the
cd40: 78 43 6f 6c 75 6d 6e 20 6d 65 74 68 6f 64 20 69 xColumn method i
cd50: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 mplementation ca
cd60: 6c 6c 73 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 lls none of the
cd70: 66 75 6e 63 74 69 6f 6e 73 20 61 62 6f 76 65 2c functions above,
cd80: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 .. /// th
cd90: 65 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 en the value of
cda0: 74 68 65 20 63 6f 6c 75 6d 6e 20 64 65 66 61 75 the column defau
cdb0: 6c 74 73 20 74 6f 20 61 6e 20 53 51 4c 20 4e 55 lts to an SQL NU
cdc0: 4c 4c 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f LL... ///
cdd0: 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 </para>..
cde0: 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 /// <para>..
cdf0: 20 20 20 20 20 20 2f 2f 2f 20 54 6f 20 72 61 69 /// To rai
ce00: 73 65 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 se an error, the
ce10: 20 78 43 6f 6c 75 6d 6e 20 6d 65 74 68 6f 64 20 xColumn method
ce20: 73 68 6f 75 6c 64 20 75 73 65 20 6f 6e 65 20 6f should use one o
ce30: 66 20 74 68 65 20 72 65 73 75 6c 74 5f 74 65 78 f the result_tex
ce40: 74 28 29 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f t() .. //
ce50: 2f 20 6d 65 74 68 6f 64 73 20 74 6f 20 73 65 74 / methods to set
ce60: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 the error messa
ce70: 67 65 20 74 65 78 74 2c 20 74 68 65 6e 20 72 65 ge text, then re
ce80: 74 75 72 6e 20 61 6e 20 61 70 70 72 6f 70 72 69 turn an appropri
ce90: 61 74 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ate.. ///
cea0: 20 65 72 72 6f 72 20 63 6f 64 65 2e 20 20 54 68 error code. Th
ceb0: 65 20 78 43 6f 6c 75 6d 6e 20 6d 65 74 68 6f 64 e xColumn method
cec0: 20 6d 75 73 74 20 72 65 74 75 72 6e 20 53 51 4c must return SQL
ced0: 49 54 45 5f 4f 4b 20 6f 6e 20 73 75 63 63 65 73 ITE_OK on succes
cee0: 73 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 s... ///
cef0: 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 </para>..
cf00: 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 /// <para>..
cf10: 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 43 6f /// The xCo
cf20: 6c 75 6d 6e 20 6d 65 74 68 6f 64 20 69 73 20 72 lumn method is r
cf30: 65 71 75 69 72 65 64 20 66 6f 72 20 65 76 65 72 equired for ever
cf40: 79 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 y virtual table
cf50: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0d implementation..
cf60: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 . /// </p
cf70: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ara>.. //
cf80: 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 / </summary>..
cf90: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d /// <param
cfa0: 20 6e 61 6d 65 3d 22 70 43 75 72 73 6f 72 22 3e name="pCursor">
cfb0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 .. /// Th
cfc0: 65 20 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72 e native pointer
cfd0: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
cfe0: 76 74 61 62 5f 63 75 72 73 6f 72 20 64 65 72 69 vtab_cursor deri
cff0: 76 65 64 20 73 74 72 75 63 74 75 72 65 2e 0d 0a ved structure...
d000: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 /// </pa
d010: 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ram>.. //
d020: 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 / <param name="p
d030: 43 6f 6e 74 65 78 74 22 3e 0d 0a 20 20 20 20 20 Context">..
d040: 20 20 20 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76 /// The nativ
d050: 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 e pointer to the
d060: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
d070: 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 62 65 structure to be
d080: 20 75 73 65 64 0d 0a 20 20 20 20 20 20 20 20 2f used.. /
d090: 2f 2f 20 66 6f 72 20 72 65 74 75 72 6e 69 6e 67 // for returning
d0a0: 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63 the specified c
d0b0: 6f 6c 75 6d 6e 20 76 61 6c 75 65 20 74 6f 20 74 olumn value to t
d0c0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 0d 0a he SQLite core..
d0d0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 6c 69 62 72 /// libr
d0e0: 61 72 79 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ary... //
d0f0: 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 / </param>..
d100: 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e /// <param n
d110: 61 6d 65 3d 22 69 6e 64 65 78 22 3e 0d 0a 20 20 ame="index">..
d120: 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 7a 65 /// The ze
d130: 72 6f 2d 62 61 73 65 64 20 69 6e 64 65 78 20 63 ro-based index c
d140: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 74 6f 20 orresponding to
d150: 74 68 65 20 63 6f 6c 75 6d 6e 20 63 6f 6e 74 61 the column conta
d160: 69 6e 69 6e 67 20 74 68 65 0d 0a 20 20 20 20 20 ining the..
d170: 20 20 20 2f 2f 2f 20 76 61 6c 75 65 20 74 6f 20 /// value to
d180: 62 65 20 72 65 74 75 72 6e 65 64 2e 0d 0a 20 20 be returned...
d190: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 /// </para
d1a0: 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 m>.. ///
d1b0: 3c 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 <returns>..
d1c0: 20 20 20 2f 2f 2f 20 41 20 73 74 61 6e 64 61 72 /// A standar
d1d0: 64 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 20 d SQLite return
d1e0: 63 6f 64 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f code... /
d1f0: 2f 2f 20 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a 20 // </returns>..
d200: 20 20 20 20 20 20 20 53 51 4c 69 74 65 45 72 72 SQLiteErr
d210: 6f 72 43 6f 64 65 20 78 43 6f 6c 75 6d 6e 28 0d orCode xColumn(.
d220: 0a 20 20 20 20 20 20 20 20 20 20 20 20 49 6e 74 . Int
d230: 50 74 72 20 70 43 75 72 73 6f 72 2c 0d 0a 20 20 Ptr pCursor,..
d240: 20 20 20 20 20 20 20 20 20 20 49 6e 74 50 74 72 IntPtr
d250: 20 70 43 6f 6e 74 65 78 74 2c 0d 0a 20 20 20 20 pContext,..
d260: 20 20 20 20 20 20 20 20 69 6e 74 20 69 6e 64 65 int inde
d270: 78 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 29 x.. )
d280: 3b 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ;.... ///
d290: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
d2a0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
d2b0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
d2c0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
d2d0: 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 20 20 20 20 ////....
d2e0: 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20 /// <summary>..
d2f0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 /// <para
d300: 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20 ><code>..
d310: 20 2f 2f 2f 20 69 6e 74 20 28 2a 78 52 6f 77 69 /// int (*xRowi
d320: 64 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f d)(sqlite3_vtab_
d330: 63 75 72 73 6f 72 20 2a 70 43 75 72 2c 20 73 71 cursor *pCur, sq
d340: 6c 69 74 65 5f 69 6e 74 36 34 20 2a 70 52 6f 77 lite_int64 *pRow
d350: 69 64 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f id);.. //
d360: 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e / </code></para>
d370: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 .. /// <p
d380: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ara>.. //
d390: 2f 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 / A successful i
d3a0: 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 69 nvocation of thi
d3b0: 73 20 6d 65 74 68 6f 64 20 77 69 6c 6c 20 63 61 s method will ca
d3c0: 75 73 65 20 2a 70 52 6f 77 69 64 20 74 6f 20 62 use *pRowid to b
d3d0: 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 66 e.. /// f
d3e0: 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 72 illed with the r
d3f0: 6f 77 69 64 20 6f 66 20 72 6f 77 20 74 68 61 74 owid of row that
d400: 20 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f the.. //
d410: 2f 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 / virtual table
d420: 63 75 72 73 6f 72 20 70 43 75 72 20 69 73 20 63 cursor pCur is c
d430: 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 69 6e urrently pointin
d440: 67 20 61 74 2e 0d 0a 20 20 20 20 20 20 20 20 2f g at... /
d450: 2f 2f 20 54 68 69 73 20 6d 65 74 68 6f 64 20 72 // This method r
d460: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b eturns SQLITE_OK
d470: 20 6f 6e 20 73 75 63 63 65 73 73 2e 0d 0a 20 20 on success...
d480: 20 20 20 20 20 20 2f 2f 2f 20 49 74 20 72 65 74 /// It ret
d490: 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 urns an appropri
d4a0: 61 74 65 20 65 72 72 6f 72 20 63 6f 64 65 20 6f ate error code o
d4b0: 6e 20 66 61 69 6c 75 72 65 2e 0d 0a 20 20 20 20 n failure...
d4c0: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d /// </para>.
d4d0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 . /// <pa
d4e0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ra>.. ///
d4f0: 20 54 68 65 20 78 52 6f 77 69 64 20 6d 65 74 68 The xRowid meth
d500: 6f 64 20 69 73 20 72 65 71 75 69 72 65 64 20 66 od is required f
d510: 6f 72 20 65 76 65 72 79 20 76 69 72 74 75 61 6c or every virtual
d520: 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 table implement
d530: 61 74 69 6f 6e 2e 0d 0a 20 20 20 20 20 20 20 20 ation...
d540: 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 /// </para>..
d550: 20 20 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 /// </summa
d560: 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ry>.. ///
d570: 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 43 <param name="pC
d580: 75 72 73 6f 72 22 3e 0d 0a 20 20 20 20 20 20 20 ursor">..
d590: 20 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76 65 20 /// The native
d5a0: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 pointer to the s
d5b0: 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 qlite3_vtab_curs
d5c0: 6f 72 20 64 65 72 69 76 65 64 20 73 74 72 75 63 or derived struc
d5d0: 74 75 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f ture... /
d5e0: 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 // </param>..
d5f0: 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 /// <param
d600: 6e 61 6d 65 3d 22 72 6f 77 49 64 22 3e 0d 0a 20 name="rowId">..
d610: 20 20 20 20 20 20 20 2f 2f 2f 20 55 70 6f 6e 20 /// Upon
d620: 73 75 63 63 65 73 73 2c 20 74 68 69 73 20 70 61 success, this pa
d630: 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 rameter must be
d640: 6d 6f 64 69 66 69 65 64 20 74 6f 20 63 6f 6e 74 modified to cont
d650: 61 69 6e 20 74 68 65 20 75 6e 69 71 75 65 0d 0a ain the unique..
d660: 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e 74 65 /// inte
d670: 67 65 72 20 72 6f 77 20 69 64 65 6e 74 69 66 69 ger row identifi
d680: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 er for the curre
d690: 6e 74 20 72 6f 77 20 66 6f 72 20 74 68 65 20 73 nt row for the s
d6a0: 70 65 63 69 66 69 65 64 20 63 75 72 73 6f 72 2e pecified cursor.
d6b0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f .. /// </
d6c0: 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 param>..
d6d0: 2f 2f 2f 20 3c 72 65 74 75 72 6e 73 3e 0d 0a 20 /// <returns>..
d6e0: 20 20 20 20 20 20 20 2f 2f 2f 20 41 20 73 74 61 /// A sta
d6f0: 6e 64 61 72 64 20 53 51 4c 69 74 65 20 72 65 74 ndard SQLite ret
d700: 75 72 6e 20 63 6f 64 65 2e 0d 0a 20 20 20 20 20 urn code...
d710: 20 20 20 2f 2f 2f 20 3c 2f 72 65 74 75 72 6e 73 /// </returns
d720: 3e 0d 0a 20 20 20 20 20 20 20 20 53 51 4c 69 74 >.. SQLit
d730: 65 45 72 72 6f 72 43 6f 64 65 20 78 52 6f 77 49 eErrorCode xRowI
d740: 64 28 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 d(..
d750: 49 6e 74 50 74 72 20 70 43 75 72 73 6f 72 2c 0d IntPtr pCursor,.
d760: 0a 20 20 20 20 20 20 20 20 20 20 20 20 72 65 66 . ref
d770: 20 6c 6f 6e 67 20 72 6f 77 49 64 0d 0a 20 20 20 long rowId..
d780: 20 20 20 20 20 20 20 20 20 29 3b 0d 0a 0d 0a 20 );....
d790: 20 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f /////////
d7a0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
d7b0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
d7c0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
d7d0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a //////////////..
d7e0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 73 .. /// <s
d7f0: 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 ummary>..
d800: 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 /// <para><code
d810: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 >.. /// i
d820: 6e 74 20 28 2a 78 55 70 64 61 74 65 29 28 0d 0a nt (*xUpdate)(..
d830: 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 73 71 /// sq
d840: 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 lite3_vtab *pVTa
d850: 62 2c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 b,.. ///
d860: 20 20 69 6e 74 20 61 72 67 63 2c 0d 0a 20 20 20 int argc,..
d870: 20 20 20 20 20 2f 2f 2f 20 20 20 73 71 6c 69 74 /// sqlit
d880: 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 2c e3_value **argv,
d890: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 .. ///
d8a0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 2a 70 52 sqlite_int64 *pR
d8b0: 6f 77 69 64 0d 0a 20 20 20 20 20 20 20 20 2f 2f owid.. //
d8c0: 2f 20 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f / );.. //
d8d0: 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e / </code></para>
d8e0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 .. /// <p
d8f0: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ara>.. //
d900: 2f 20 41 6c 6c 20 63 68 61 6e 67 65 73 20 74 6f / All changes to
d910: 20 61 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 a virtual table
d920: 20 61 72 65 20 6d 61 64 65 20 75 73 69 6e 67 20 are made using
d930: 74 68 65 20 78 55 70 64 61 74 65 20 6d 65 74 68 the xUpdate meth
d940: 6f 64 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f od... ///
d950: 20 54 68 69 73 20 6f 6e 65 20 6d 65 74 68 6f 64 This one method
d960: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
d970: 69 6e 73 65 72 74 2c 20 64 65 6c 65 74 65 2c 20 insert, delete,
d980: 6f 72 20 75 70 64 61 74 65 2e 0d 0a 20 20 20 20 or update...
d990: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d /// </para>.
d9a0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 . /// <pa
d9b0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ra>.. ///
d9c0: 20 54 68 65 20 61 72 67 63 20 70 61 72 61 6d 65 The argc parame
d9d0: 74 65 72 20 73 70 65 63 69 66 69 65 73 20 74 68 ter specifies th
d9e0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6e 74 72 e number of entr
d9f0: 69 65 73 20 69 6e 20 74 68 65 20 61 72 67 76 20 ies in the argv
da00: 61 72 72 61 79 2e 20 0d 0a 20 20 20 20 20 20 20 array. ..
da10: 20 2f 2f 2f 20 54 68 65 20 76 61 6c 75 65 20 6f /// The value o
da20: 66 20 61 72 67 63 20 77 69 6c 6c 20 62 65 20 31 f argc will be 1
da30: 20 66 6f 72 20 61 20 70 75 72 65 20 64 65 6c 65 for a pure dele
da40: 74 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 72 20 te operation or
da50: 4e 2b 32 20 66 6f 72 20 61 6e 20 69 6e 73 65 72 N+2 for an inser
da60: 74 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6f t.. /// o
da70: 72 20 72 65 70 6c 61 63 65 20 6f 72 20 75 70 64 r replace or upd
da80: 61 74 65 20 77 68 65 72 65 20 4e 20 69 73 20 74 ate where N is t
da90: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c he number of col
daa0: 75 6d 6e 73 20 69 6e 20 74 68 65 20 74 61 62 6c umns in the tabl
dab0: 65 2e 20 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f e. .. //
dac0: 2f 20 49 6e 20 74 68 65 20 70 72 65 76 69 6f 75 / In the previou
dad0: 73 20 73 65 6e 74 65 6e 63 65 2c 20 4e 20 69 6e s sentence, N in
dae0: 63 6c 75 64 65 73 20 61 6e 79 20 68 69 64 64 65 cludes any hidde
daf0: 6e 20 63 6f 6c 75 6d 6e 73 2e 0d 0a 20 20 20 20 n columns...
db00: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d /// </para>.
db10: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 . /// <pa
db20: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ra>.. ///
db30: 20 45 76 65 72 79 20 61 72 67 76 20 65 6e 74 72 Every argv entr
db40: 79 20 77 69 6c 6c 20 68 61 76 65 20 61 20 6e 6f y will have a no
db50: 6e 2d 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 n-NULL value in
db60: 43 20 62 75 74 20 6d 61 79 20 63 6f 6e 74 61 69 C but may contai
db70: 6e 20 74 68 65 20 0d 0a 20 20 20 20 20 20 20 20 n the ..
db80: 2f 2f 2f 20 53 51 4c 20 76 61 6c 75 65 20 4e 55 /// SQL value NU
db90: 4c 4c 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f LL. In other wo
dba0: 72 64 73 2c 20 69 74 20 69 73 20 61 6c 77 61 79 rds, it is alway
dbb0: 73 20 74 72 75 65 20 74 68 61 74 0d 0a 20 20 20 s true that..
dbc0: 20 20 20 20 20 2f 2f 2f 20 3c 21 5b 43 44 41 54 /// <![CDAT
dbd0: 41 5b 3c 74 74 3e 5d 5d 3e 61 72 67 76 5b 69 5d A[<tt>]]>argv[i]
dbe0: 21 3d 30 3c 21 5b 43 44 41 54 41 5b 3c 2f 74 74 !=0<![CDATA[</tt
dbf0: 3e 5d 5d 3e 20 66 6f 72 20 3c 21 5b 43 44 41 54 >]]> for <![CDAT
dc00: 41 5b 3c 62 3e 5d 5d 3e 69 3c 21 5b 43 44 41 54 A[<b>]]>i<![CDAT
dc10: 41 5b 3c 2f 62 3e 5d 5d 3e 20 62 65 74 77 65 65 A[</b>]]> betwee
dc20: 6e 20 30 20 61 6e 64 20 3c 21 5b 43 44 41 54 41 n 0 and <![CDATA
dc30: 5b 3c 74 74 3e 5d 5d 3e 61 72 67 63 2d 31 3c 21 [<tt>]]>argc-1<!
dc40: 5b 43 44 41 54 41 5b 3c 2f 74 74 3e 5d 5d 3e 2e [CDATA[</tt>]]>.
dc50: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 48 6f .. /// Ho
dc60: 77 65 76 65 72 2c 20 69 74 20 6d 69 67 68 74 20 wever, it might
dc70: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 be the case that
dc80: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 21 .. /// <!
dc90: 5b 43 44 41 54 41 5b 3c 74 74 3e 5d 5d 3e 73 71 [CDATA[<tt>]]>sq
dca0: 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 lite3_value_type
dcb0: 28 61 72 67 76 5b 69 5d 29 3d 3d 53 51 4c 49 54 (argv[i])==SQLIT
dcc0: 45 5f 4e 55 4c 4c 3c 21 5b 43 44 41 54 41 5b 3c E_NULL<![CDATA[<
dcd0: 2f 74 74 3e 5d 5d 3e 2e 0d 0a 20 20 20 20 20 20 /tt>]]>...
dce0: 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 /// </para>..
dcf0: 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 /// <para
dd00: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 >.. /// T
dd10: 68 65 20 61 72 67 76 5b 30 5d 20 70 61 72 61 6d he argv[0] param
dd20: 65 74 65 72 20 69 73 20 74 68 65 20 72 6f 77 69 eter is the rowi
dd30: 64 20 6f 66 20 61 20 72 6f 77 20 69 6e 20 74 68 d of a row in th
dd40: 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 e virtual table
dd50: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 6f .. /// to
dd60: 20 62 65 20 64 65 6c 65 74 65 64 2e 20 49 66 20 be deleted. If
dd70: 61 72 67 76 5b 30 5d 20 69 73 20 61 6e 20 53 51 argv[0] is an SQ
dd80: 4c 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 L NULL, then no
dd90: 64 65 6c 65 74 69 6f 6e 20 6f 63 63 75 72 73 2e deletion occurs.
dda0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f .. /// </
ddb0: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f para>.. /
ddc0: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 // <para>..
ddd0: 20 20 20 2f 2f 2f 20 54 68 65 20 61 72 67 76 5b /// The argv[
dde0: 31 5d 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 1] parameter is
ddf0: 74 68 65 20 72 6f 77 69 64 20 6f 66 20 61 20 6e the rowid of a n
de00: 65 77 20 72 6f 77 20 74 6f 20 62 65 20 69 6e 73 ew row to be ins
de10: 65 72 74 65 64 20 0d 0a 20 20 20 20 20 20 20 20 erted ..
de20: 2f 2f 2f 20 69 6e 74 6f 20 74 68 65 20 76 69 72 /// into the vir
de30: 74 75 61 6c 20 74 61 62 6c 65 2e 20 49 66 20 61 tual table. If a
de40: 72 67 76 5b 31 5d 20 69 73 20 61 6e 20 53 51 4c rgv[1] is an SQL
de50: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 NULL, then the
de60: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 0d implementation .
de70: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6d 75 73 . /// mus
de80: 74 20 63 68 6f 6f 73 65 20 61 20 72 6f 77 69 64 t choose a rowid
de90: 20 66 6f 72 20 74 68 65 20 6e 65 77 6c 79 20 69 for the newly i
dea0: 6e 73 65 72 74 65 64 20 72 6f 77 2e 20 53 75 62 nserted row. Sub
deb0: 73 65 71 75 65 6e 74 20 61 72 67 76 5b 5d 20 0d sequent argv[] .
dec0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 65 6e 74 . /// ent
ded0: 72 69 65 73 20 63 6f 6e 74 61 69 6e 20 76 61 6c ries contain val
dee0: 75 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d ues of the colum
def0: 6e 73 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 ns of the virtua
df00: 6c 20 74 61 62 6c 65 2c 20 69 6e 20 74 68 65 20 l table, in the
df10: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6f 72 .. /// or
df20: 64 65 72 20 74 68 61 74 20 74 68 65 20 63 6f 6c der that the col
df30: 75 6d 6e 73 20 77 65 72 65 20 64 65 63 6c 61 72 umns were declar
df40: 65 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f ed. The number o
df50: 66 20 63 6f 6c 75 6d 6e 73 20 77 69 6c 6c 0d 0a f columns will..
df60: 20 20 20 20 20 20 20 20 2f 2f 2f 20 6d 61 74 63 /// matc
df70: 68 20 74 68 65 20 74 61 62 6c 65 20 64 65 63 6c h the table decl
df80: 61 72 61 74 69 6f 6e 20 74 68 61 74 20 74 68 65 aration that the
df90: 20 78 43 6f 6e 6e 65 63 74 20 6f 72 20 78 43 72 xConnect or xCr
dfa0: 65 61 74 65 20 6d 65 74 68 6f 64 20 6d 61 64 65 eate method made
dfb0: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 75 .. /// u
dfc0: 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 sing the sqlite3
dfd0: 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 29 20 _declare_vtab()
dfe0: 63 61 6c 6c 2e 20 20 41 6c 6c 20 68 69 64 64 65 call. All hidde
dff0: 6e 20 63 6f 6c 75 6d 6e 73 20 61 72 65 20 69 6e n columns are in
e000: 63 6c 75 64 65 64 2e 0d 0a 20 20 20 20 20 20 20 cluded...
e010: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 /// </para>..
e020: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e /// <para>
e030: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 57 68 .. /// Wh
e040: 65 6e 20 64 6f 69 6e 67 20 61 6e 20 69 6e 73 65 en doing an inse
e050: 72 74 20 77 69 74 68 6f 75 74 20 61 20 72 6f 77 rt without a row
e060: 69 64 20 28 61 72 67 63 3e 31 2c 20 61 72 67 76 id (argc>1, argv
e070: 5b 31 5d 20 69 73 20 61 6e 20 53 51 4c 20 4e 55 [1] is an SQL NU
e080: 4c 4c 29 2c 0d 0a 20 20 20 20 20 20 20 20 2f 2f LL),.. //
e090: 2f 20 6f 6e 20 61 20 76 69 72 74 75 61 6c 20 74 / on a virtual t
e0a0: 61 62 6c 65 20 74 68 61 74 20 75 73 65 73 20 52 able that uses R
e0b0: 4f 57 49 44 20 28 62 75 74 20 6e 6f 74 20 6f 6e OWID (but not on
e0c0: 20 61 20 57 49 54 48 4f 55 54 20 52 4f 57 49 44 a WITHOUT ROWID
e0d0: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 29 2c virtual table),
e0e0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 .. /// th
e0f0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
e100: 20 6d 75 73 74 20 73 65 74 20 2a 70 52 6f 77 69 must set *pRowi
e110: 64 20 74 6f 20 74 68 65 20 72 6f 77 69 64 20 6f d to the rowid o
e120: 66 20 74 68 65 20 6e 65 77 6c 79 20 69 6e 73 65 f the newly inse
e130: 72 74 65 64 20 72 6f 77 3b 20 0d 0a 20 20 20 20 rted row; ..
e140: 20 20 20 20 2f 2f 2f 20 74 68 69 73 20 77 69 6c /// this wil
e150: 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 76 61 6c l become the val
e160: 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 ue returned by t
e170: 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f he sqlite3_last_
e180: 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 0d 0a insert_rowid()..
e190: 20 20 20 20 20 20 20 20 2f 2f 2f 20 66 75 6e 63 /// func
e1a0: 74 69 6f 6e 2e 20 53 65 74 74 69 6e 67 20 74 68 tion. Setting th
e1b0: 69 73 20 76 61 6c 75 65 20 69 6e 20 61 6c 6c 20 is value in all
e1c0: 74 68 65 20 6f 74 68 65 72 20 63 61 73 65 73 20 the other cases
e1d0: 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f is a harmless no
e1e0: 2d 6f 70 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f -op;.. //
e1f0: 2f 20 74 68 65 20 53 51 4c 69 74 65 20 65 6e 67 / the SQLite eng
e200: 69 6e 65 20 69 67 6e 6f 72 65 73 20 74 68 65 20 ine ignores the
e210: 2a 70 52 6f 77 69 64 20 72 65 74 75 72 6e 20 76 *pRowid return v
e220: 61 6c 75 65 20 69 66 20 61 72 67 63 3d 3d 31 20 alue if argc==1
e230: 6f 72 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f or .. ///
e240: 20 61 72 67 76 5b 31 5d 20 69 73 20 6e 6f 74 20 argv[1] is not
e250: 61 6e 20 53 51 4c 20 4e 55 4c 4c 2e 0d 0a 20 20 an SQL NULL...
e260: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 /// </para
e270: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c >.. /// <
e280: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f para>.. /
e290: 2f 2f 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 // Each call to
e2a0: 78 55 70 64 61 74 65 20 77 69 6c 6c 20 66 61 6c xUpdate will fal
e2b0: 6c 20 69 6e 74 6f 20 6f 6e 65 20 6f 66 20 63 61 l into one of ca
e2c0: 73 65 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e ses shown below.
e2d0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 4e 6f .. /// No
e2e0: 74 20 74 68 61 74 20 72 65 66 65 72 65 6e 63 65 t that reference
e2f0: 73 20 74 6f 20 3c 21 5b 43 44 41 54 41 5b 3c 62 s to <![CDATA[<b
e300: 3e 5d 5d 3e 61 72 67 76 5b 69 5d 3c 21 5b 43 44 >]]>argv[i]<![CD
e310: 41 54 41 5b 3c 2f 62 3e 5d 5d 3e 20 6d 65 61 6e ATA[</b>]]> mean
e320: 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 0d 0a the SQL value..
e330: 20 20 20 20 20 20 20 20 2f 2f 2f 20 68 65 6c 64 /// held
e340: 20 77 69 74 68 69 6e 20 74 68 65 20 61 72 67 76 within the argv
e350: 5b 69 5d 20 6f 62 6a 65 63 74 2c 20 6e 6f 74 20 [i] object, not
e360: 74 68 65 20 61 72 67 76 5b 69 5d 0d 0a 20 20 20 the argv[i]..
e370: 20 20 20 20 20 2f 2f 2f 20 6f 62 6a 65 63 74 20 /// object
e380: 69 74 73 65 6c 66 2e 0d 0a 20 20 20 20 20 20 20 itself...
e390: 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 /// </para>..
e3a0: 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e /// <para>
e3b0: 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 <code>..
e3c0: 2f 2f 2f 20 3c 21 5b 43 44 41 54 41 5b 3c 64 6c /// <![CDATA[<dl
e3d0: 3e 5d 5d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f >]]>.. //
e3e0: 2f 20 3c 21 5b 43 44 41 54 41 5b 3c 64 74 3e 5d / <![CDATA[<dt>]
e3f0: 5d 3e 3c 21 5b 43 44 41 54 41 5b 3c 62 3e 5d 5d ]><![CDATA[<b>]]
e400: 3e 61 72 67 63 20 3d 20 31 20 3c 21 5b 43 44 41 >argc = 1 <![CDA
e410: 54 41 5b 3c 62 72 3e 5d 5d 3e 20 61 72 67 76 5b TA[<br>]]> argv[
e420: 30 5d 20 26 23 38 38 30 30 3b 20 4e 55 4c 4c 3c 0] ≠ NULL<
e430: 21 5b 43 44 41 54 41 5b 3c 2f 62 3e 5d 5d 3e 0d ![CDATA[</b>]]>.
e440: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 21 5b . /// <![
e450: 43 44 41 54 41 5b 3c 2f 64 74 3e 5d 5d 3e 3c 21 CDATA[</dt>]]><!
e460: 5b 43 44 41 54 41 5b 3c 64 64 3e 5d 5d 3e 0d 0a [CDATA[<dd>]]>..
e470: 20 20 20 20 20 20 20 20 2f 2f 2f 20 44 45 4c 45 /// DELE
e480: 54 45 3a 20 54 68 65 20 73 69 6e 67 6c 65 20 72 TE: The single r
e490: 6f 77 20 77 69 74 68 20 72 6f 77 69 64 20 6f 72 ow with rowid or
e4a0: 20 50 52 49 4d 41 52 59 20 4b 45 59 20 65 71 75 PRIMARY KEY equ
e4b0: 61 6c 20 74 6f 20 61 72 67 76 5b 30 5d 20 69 73 al to argv[0] is
e4c0: 20 64 65 6c 65 74 65 64 2e 20 0d 0a 20 20 20 20 deleted. ..
e4d0: 20 20 20 20 2f 2f 2f 20 4e 6f 20 69 6e 73 65 72 /// No inser
e4e0: 74 20 6f 63 63 75 72 73 2e 0d 0a 20 20 20 20 20 t occurs...
e4f0: 20 20 20 2f 2f 2f 20 3c 21 5b 43 44 41 54 41 5b /// <![CDATA[
e500: 3c 2f 64 64 3e 5d 5d 3e 3c 21 5b 43 44 41 54 41 </dd>]]><![CDATA
e510: 5b 3c 64 74 3e 5d 5d 3e 3c 21 5b 43 44 41 54 41 [<dt>]]><![CDATA
e520: 5b 3c 62 3e 5d 5d 3e 61 72 67 63 20 26 67 74 3b [<b>]]>argc >
e530: 20 31 20 3c 21 5b 43 44 41 54 41 5b 3c 62 72 3e 1 <![CDATA[<br>
e540: 5d 5d 3e 20 61 72 67 76 5b 30 5d 20 3d 20 4e 55 ]]> argv[0] = NU
e550: 4c 4c 3c 21 5b 43 44 41 54 41 5b 3c 2f 62 3e 5d LL<![CDATA[</b>]
e560: 5d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 ]>.. ///
e570: 3c 21 5b 43 44 41 54 41 5b 3c 2f 64 74 3e 5d 5d <![CDATA[</dt>]]
e580: 3e 3c 21 5b 43 44 41 54 41 5b 3c 64 64 3e 5d 5d ><![CDATA[<dd>]]
e590: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 49 >.. /// I
e5a0: 4e 53 45 52 54 3a 20 41 20 6e 65 77 20 72 6f 77 NSERT: A new row
e5b0: 20 69 73 20 69 6e 73 65 72 74 65 64 20 77 69 74 is inserted wit
e5c0: 68 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 20 h column values
e5d0: 74 61 6b 65 6e 20 66 72 6f 6d 0d 0a 20 20 20 20 taken from..
e5e0: 20 20 20 20 2f 2f 2f 20 61 72 67 76 5b 32 5d 20 /// argv[2]
e5f0: 61 6e 64 20 66 6f 6c 6c 6f 77 69 6e 67 2e 20 20 and following.
e600: 49 6e 20 61 20 72 6f 77 69 64 20 76 69 72 74 75 In a rowid virtu
e610: 61 6c 20 74 61 62 6c 65 2c 20 69 66 20 61 72 67 al table, if arg
e620: 76 5b 31 5d 20 69 73 20 61 6e 20 53 51 4c 20 4e v[1] is an SQL N
e630: 55 4c 4c 2c 0d 0a 20 20 20 20 20 20 20 20 2f 2f ULL,.. //
e640: 2f 20 74 68 65 6e 20 61 20 6e 65 77 20 75 6e 69 / then a new uni
e650: 71 75 65 20 72 6f 77 69 64 20 69 73 20 67 65 6e que rowid is gen
e660: 65 72 61 74 65 64 20 61 75 74 6f 6d 61 74 69 63 erated automatic
e670: 61 6c 6c 79 2e 20 20 54 68 65 20 61 72 67 76 5b ally. The argv[
e680: 31 5d 20 77 69 6c 6c 20 62 65 20 4e 55 4c 4c 0d 1] will be NULL.
e690: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 66 6f 72 . /// for
e6a0: 20 61 20 57 49 54 48 4f 55 54 20 52 4f 57 49 44 a WITHOUT ROWID
e6b0: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2c 20 virtual table,
e6c0: 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 in which case th
e6d0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
e6e0: 20 73 68 6f 75 6c 64 0d 0a 20 20 20 20 20 20 20 should..
e6f0: 20 2f 2f 2f 20 74 61 6b 65 20 74 68 65 20 50 52 /// take the PR
e700: 49 4d 41 52 59 20 4b 45 59 20 76 61 6c 75 65 20 IMARY KEY value
e710: 66 72 6f 6d 20 74 68 65 20 61 70 70 72 6f 70 72 from the appropr
e720: 69 61 74 65 20 63 6f 6c 75 6d 6e 20 69 6e 20 61 iate column in a
e730: 72 67 76 5b 32 5d 20 61 6e 64 20 66 6f 6c 6c 6f rgv[2] and follo
e740: 77 69 6e 67 2e 0d 0a 20 20 20 20 20 20 20 20 2f wing... /
e750: 2f 2f 20 3c 21 5b 43 44 41 54 41 5b 3c 2f 64 64 // <![CDATA[</dd
e760: 3e 5d 5d 3e 3c 21 5b 43 44 41 54 41 5b 3c 64 74 >]]><![CDATA[<dt
e770: 3e 5d 5d 3e 3c 21 5b 43 44 41 54 41 5b 3c 62 3e >]]><![CDATA[<b>
e780: 5d 5d 3e 61 72 67 63 20 26 67 74 3b 20 31 20 3c ]]>argc > 1 <
e790: 21 5b 43 44 41 54 41 5b 3c 62 72 3e 5d 5d 3e 20 ![CDATA[<br>]]>
e7a0: 61 72 67 76 5b 30 5d 20 26 23 38 38 30 30 3b 20 argv[0] ≠
e7b0: 4e 55 4c 4c 20 3c 21 5b 43 44 41 54 41 5b 3c 62 NULL <![CDATA[<b
e7c0: 72 3e 5d 5d 3e 20 61 72 67 76 5b 30 5d 20 3d 20 r>]]> argv[0] =
e7d0: 61 72 67 76 5b 31 5d 3c 21 5b 43 44 41 54 41 5b argv[1]<![CDATA[
e7e0: 3c 2f 62 3e 5d 5d 3e 0d 0a 20 20 20 20 20 20 20 </b>]]>..
e7f0: 20 2f 2f 2f 20 3c 21 5b 43 44 41 54 41 5b 3c 2f /// <![CDATA[</
e800: 64 74 3e 5d 5d 3e 3c 21 5b 43 44 41 54 41 5b 3c dt>]]><![CDATA[<
e810: 64 64 3e 5d 5d 3e 0d 0a 20 20 20 20 20 20 20 20 dd>]]>..
e820: 2f 2f 2f 20 55 50 44 41 54 45 3a 0d 0a 20 20 20 /// UPDATE:..
e830: 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 72 6f 77 /// The row
e840: 20 77 69 74 68 20 72 6f 77 69 64 20 6f 72 20 50 with rowid or P
e850: 52 49 4d 41 52 59 20 4b 45 59 20 61 72 67 76 5b RIMARY KEY argv[
e860: 30 5d 20 69 73 20 75 70 64 61 74 65 64 20 77 69 0] is updated wi
e870: 74 68 20 6e 65 77 20 76 61 6c 75 65 73 20 0d 0a th new values ..
e880: 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e 20 61 /// in a
e890: 72 67 76 5b 32 5d 20 61 6e 64 20 66 6f 6c 6c 6f rgv[2] and follo
e8a0: 77 69 6e 67 20 70 61 72 61 6d 65 74 65 72 73 2e wing parameters.
e8b0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 21 .. /// <!
e8c0: 5b 43 44 41 54 41 5b 3c 2f 64 64 3e 5d 5d 3e 3c [CDATA[</dd>]]><
e8d0: 21 5b 43 44 41 54 41 5b 3c 64 74 3e 5d 5d 3e 3c ![CDATA[<dt>]]><
e8e0: 21 5b 43 44 41 54 41 5b 3c 62 3e 5d 5d 3e 61 72 ![CDATA[<b>]]>ar
e8f0: 67 63 20 26 67 74 3b 20 31 20 3c 21 5b 43 44 41 gc > 1 <![CDA
e900: 54 41 5b 3c 62 72 3e 5d 5d 3e 20 61 72 67 76 5b TA[<br>]]> argv[
e910: 30 5d 20 26 23 38 38 30 30 3b 20 4e 55 4c 4c 20 0] ≠ NULL
e920: 3c 21 5b 43 44 41 54 41 5b 3c 62 72 3e 5d 5d 3e <![CDATA[<br>]]>
e930: 20 61 72 67 76 5b 30 5d 20 26 23 38 38 30 30 3b argv[0] ≠
e940: 20 61 72 67 76 5b 31 5d 3c 21 5b 43 44 41 54 41 argv[1]<![CDATA
e950: 5b 3c 2f 62 3e 5d 5d 3e 0d 0a 20 20 20 20 20 20 [</b>]]>..
e960: 20 20 2f 2f 2f 20 3c 21 5b 43 44 41 54 41 5b 3c /// <![CDATA[<
e970: 2f 64 74 3e 5d 5d 3e 3c 21 5b 43 44 41 54 41 5b /dt>]]><![CDATA[
e980: 3c 64 64 3e 5d 5d 3e 0d 0a 20 20 20 20 20 20 20 <dd>]]>..
e990: 20 2f 2f 2f 20 55 50 44 41 54 45 20 77 69 74 68 /// UPDATE with
e9a0: 20 72 6f 77 69 64 20 6f 72 20 50 52 49 4d 41 52 rowid or PRIMAR
e9b0: 59 20 4b 45 59 20 63 68 61 6e 67 65 3a 0d 0a 20 Y KEY change:..
e9c0: 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 72 /// The r
e9d0: 6f 77 20 77 69 74 68 20 72 6f 77 69 64 20 6f 72 ow with rowid or
e9e0: 20 50 52 49 4d 41 52 59 20 4b 45 59 20 61 72 67 PRIMARY KEY arg
e9f0: 76 5b 30 5d 20 69 73 20 75 70 64 61 74 65 64 20 v[0] is updated
ea00: 77 69 74 68 20 0d 0a 20 20 20 20 20 20 20 20 2f with .. /
ea10: 2f 2f 20 74 68 65 20 72 6f 77 69 64 20 6f 72 20 // the rowid or
ea20: 50 52 49 4d 41 52 59 20 4b 45 59 20 69 6e 20 61 PRIMARY KEY in a
ea30: 72 67 76 5b 31 5d 20 0d 0a 20 20 20 20 20 20 20 rgv[1] ..
ea40: 20 2f 2f 2f 20 61 6e 64 20 6e 65 77 20 76 61 6c /// and new val
ea50: 75 65 73 20 69 6e 20 61 72 67 76 5b 32 5d 20 61 ues in argv[2] a
ea60: 6e 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 61 72 nd following par
ea70: 61 6d 65 74 65 72 73 2e 20 54 68 69 73 20 77 69 ameters. This wi
ea80: 6c 6c 20 6f 63 63 75 72 20 0d 0a 20 20 20 20 20 ll occur ..
ea90: 20 20 20 2f 2f 2f 20 77 68 65 6e 20 61 6e 20 53 /// when an S
eaa0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 70 64 QL statement upd
eab0: 61 74 65 73 20 61 20 72 6f 77 69 64 2c 20 61 73 ates a rowid, as
eac0: 20 69 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e in the statemen
ead0: 74 3a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 t:.. ///
eae0: 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 <para><code>..
eaf0: 20 20 20 20 20 20 2f 2f 2f 20 20 20 20 55 50 44 /// UPD
eb00: 41 54 45 20 74 61 62 6c 65 20 53 45 54 20 72 6f ATE table SET ro
eb10: 77 69 64 3d 72 6f 77 69 64 2b 31 20 57 48 45 52 wid=rowid+1 WHER
eb20: 45 20 2e 2e 2e 3b 20 0d 0a 20 20 20 20 20 20 20 E ...; ..
eb30: 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 /// </code></pa
eb40: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ra>.. ///
eb50: 20 3c 21 5b 43 44 41 54 41 5b 3c 2f 64 64 3e 5d <![CDATA[</dd>]
eb60: 5d 3e 3c 21 5b 43 44 41 54 41 5b 3c 2f 64 6c 3e ]><![CDATA[</dl>
eb70: 5d 5d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ]]>.. ///
eb80: 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d </code></para>.
eb90: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 . /// <pa
eba0: 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ra>.. ///
ebb0: 20 54 68 65 20 78 55 70 64 61 74 65 20 6d 65 74 The xUpdate met
ebc0: 68 6f 64 20 6d 75 73 74 20 72 65 74 75 72 6e 20 hod must return
ebd0: 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 SQLITE_OK if and
ebe0: 20 6f 6e 6c 79 20 69 66 20 69 74 20 69 73 0d 0a only if it is..
ebf0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 73 75 63 63 /// succ
ec00: 65 73 73 66 75 6c 2e 20 20 49 66 20 61 20 66 61 essful. If a fa
ec10: 69 6c 75 72 65 20 6f 63 63 75 72 73 2c 20 74 68 ilure occurs, th
ec20: 65 20 78 55 70 64 61 74 65 20 6d 75 73 74 20 72 e xUpdate must r
ec30: 65 74 75 72 6e 20 61 6e 20 61 70 70 72 6f 70 72 eturn an appropr
ec40: 69 61 74 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f iate.. //
ec50: 2f 20 65 72 72 6f 72 20 63 6f 64 65 2e 20 20 4f / error code. O
ec60: 6e 20 61 20 66 61 69 6c 75 72 65 2c 20 74 68 65 n a failure, the
ec70: 20 70 56 54 61 62 2d 3e 7a 45 72 72 4d 73 67 20 pVTab->zErrMsg
ec80: 65 6c 65 6d 65 6e 74 20 6d 61 79 20 6f 70 74 69 element may opti
ec90: 6f 6e 61 6c 6c 79 0d 0a 20 20 20 20 20 20 20 20 onally..
eca0: 2f 2f 2f 20 62 65 20 72 65 70 6c 61 63 65 64 20 /// be replaced
ecb0: 77 69 74 68 20 65 72 72 6f 72 20 6d 65 73 73 61 with error messa
ecc0: 67 65 20 74 65 78 74 20 73 74 6f 72 65 64 20 69 ge text stored i
ecd0: 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 n memory allocat
ece0: 65 64 20 66 72 6f 6d 20 53 51 4c 69 74 65 20 0d ed from SQLite .
ecf0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 75 73 69 . /// usi
ed00: 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 73 75 63 ng functions suc
ed10: 68 20 61 73 20 73 71 6c 69 74 65 33 5f 6d 70 72 h as sqlite3_mpr
ed20: 69 6e 74 66 28 29 20 6f 72 20 73 71 6c 69 74 65 intf() or sqlite
ed30: 33 5f 6d 61 6c 6c 6f 63 28 29 2e 0d 0a 20 20 20 3_malloc()...
ed40: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e /// </para>
ed50: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 .. /// <p
ed60: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ara>.. //
ed70: 2f 20 49 66 20 74 68 65 20 78 55 70 64 61 74 65 / If the xUpdate
ed80: 20 6d 65 74 68 6f 64 20 76 69 6f 6c 61 74 65 73 method violates
ed90: 20 73 6f 6d 65 20 63 6f 6e 73 74 72 61 69 6e 74 some constraint
eda0: 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 of the virtual
edb0: 74 61 62 6c 65 0d 0a 20 20 20 20 20 20 20 20 2f table.. /
edc0: 2f 2f 20 28 69 6e 63 6c 75 64 69 6e 67 2c 20 62 // (including, b
edd0: 75 74 20 6e 6f 74 20 6c 69 6d 69 74 65 64 20 74 ut not limited t
ede0: 6f 2c 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f o, attempting to
edf0: 20 73 74 6f 72 65 20 61 20 76 61 6c 75 65 20 6f store a value o
ee00: 66 20 74 68 65 20 77 72 6f 6e 67 20 0d 0a 20 20 f the wrong ..
ee10: 20 20 20 20 20 20 2f 2f 2f 20 64 61 74 61 74 79 /// dataty
ee20: 70 65 2c 20 61 74 74 65 6d 70 74 69 6e 67 20 74 pe, attempting t
ee30: 6f 20 73 74 6f 72 65 20 61 20 76 61 6c 75 65 20 o store a value
ee40: 74 68 61 74 20 69 73 20 74 6f 6f 0d 0a 20 20 20 that is too..
ee50: 20 20 20 20 20 2f 2f 2f 20 6c 61 72 67 65 20 6f /// large o
ee60: 72 20 74 6f 6f 20 73 6d 61 6c 6c 2c 20 6f 72 20 r too small, or
ee70: 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 68 attempting to ch
ee80: 61 6e 67 65 20 61 20 72 65 61 64 2d 6f 6e 6c 79 ange a read-only
ee90: 20 76 61 6c 75 65 29 20 74 68 65 6e 20 74 68 65 value) then the
eea0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 78 55 .. /// xU
eeb0: 70 64 61 74 65 20 6d 75 73 74 20 66 61 69 6c 20 pdate must fail
eec0: 77 69 74 68 20 61 6e 20 61 70 70 72 6f 70 72 69 with an appropri
eed0: 61 74 65 20 65 72 72 6f 72 20 63 6f 64 65 2e 0d ate error code..
eee0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 . /// </p
eef0: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ara>.. //
ef00: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 / <para>..
ef10: 20 20 2f 2f 2f 20 49 66 20 74 68 65 20 78 55 70 /// If the xUp
ef20: 64 61 74 65 20 6d 65 74 68 6f 64 20 69 73 20 70 date method is p
ef30: 65 72 66 6f 72 6d 69 6e 67 20 61 6e 20 55 50 44 erforming an UPD
ef40: 41 54 45 2c 20 74 68 65 6e 0d 0a 20 20 20 20 20 ATE, then..
ef50: 20 20 20 2f 2f 2f 20 73 71 6c 69 74 65 33 5f 76 /// sqlite3_v
ef60: 61 6c 75 65 5f 6e 6f 63 68 61 6e 67 65 28 58 29 alue_nochange(X)
ef70: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
ef80: 64 69 73 63 6f 76 65 72 20 77 68 69 63 68 20 63 discover which c
ef90: 6f 6c 75 6d 6e 73 0d 0a 20 20 20 20 20 20 20 20 olumns..
efa0: 2f 2f 2f 20 6f 66 20 74 68 65 20 76 69 72 74 75 /// of the virtu
efb0: 61 6c 20 74 61 62 6c 65 20 77 65 72 65 20 61 63 al table were ac
efc0: 74 75 61 6c 6c 79 20 6d 6f 64 69 66 69 65 64 20 tually modified
efd0: 62 79 20 74 68 65 20 55 50 44 41 54 45 0d 0a 20 by the UPDATE..
efe0: 20 20 20 20 20 20 20 2f 2f 2f 20 73 74 61 74 65 /// state
eff0: 6d 65 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 ment. The sqlit
f000: 65 33 5f 76 61 6c 75 65 5f 6e 6f 63 68 61 6e 67 e3_value_nochang
f010: 65 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 e(X) interface r
f020: 65 74 75 72 6e 73 0d 0a 20 20 20 20 20 20 20 20 eturns..
f030: 2f 2f 2f 20 74 72 75 65 20 66 6f 72 20 63 6f 6c /// true for col
f040: 75 6d 6e 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 umns that do not
f050: 20 63 68 61 6e 67 65 2e 0d 0a 20 20 20 20 20 20 change...
f060: 20 20 2f 2f 2f 20 4f 6e 20 65 76 65 72 79 20 55 /// On every U
f070: 50 44 41 54 45 2c 20 53 51 4c 69 74 65 20 77 69 PDATE, SQLite wi
f080: 6c 6c 20 66 69 72 73 74 20 69 6e 76 6f 6b 65 0d ll first invoke.
f090: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 78 43 6f . /// xCo
f0a0: 6c 75 6d 6e 20 73 65 70 61 72 61 74 65 6c 79 20 lumn separately
f0b0: 66 6f 72 20 65 61 63 68 20 75 6e 63 68 61 6e 67 for each unchang
f0c0: 69 6e 67 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 ing column in th
f0d0: 65 20 74 61 62 6c 65 20 74 6f 20 0d 0a 20 20 20 e table to ..
f0e0: 20 20 20 20 20 2f 2f 2f 20 6f 62 74 61 69 6e 20 /// obtain
f0f0: 74 68 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 the value for th
f100: 61 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 at column. The
f110: 78 43 6f 6c 75 6d 6e 20 6d 65 74 68 6f 64 20 63 xColumn method c
f120: 61 6e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 an.. ///
f130: 63 68 65 63 6b 20 74 6f 20 73 65 65 20 69 66 20 check to see if
f140: 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e the column is un
f150: 63 68 61 6e 67 65 64 20 61 74 20 74 68 65 20 53 changed at the S
f160: 51 4c 20 6c 65 76 65 6c 0d 0a 20 20 20 20 20 20 QL level..
f170: 20 20 2f 2f 2f 20 62 79 20 69 6e 76 6f 6b 69 6e /// by invokin
f180: 67 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6e g sqlite3_vtab_n
f190: 6f 63 68 61 6e 67 65 28 29 2e 20 20 49 66 20 78 ochange(). If x
f1a0: 43 6f 6c 75 6d 6e 20 73 65 65 73 20 74 68 61 74 Column sees that
f1b0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 .. /// th
f1c0: 65 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 6f 74 20 e column is not
f1d0: 62 65 69 6e 67 20 6d 6f 64 69 66 69 65 64 2c 20 being modified,
f1e0: 69 74 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e it should return
f1f0: 20 77 69 74 68 6f 75 74 20 73 65 74 74 69 6e 67 without setting
f200: 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 61 .. /// a
f210: 20 72 65 73 75 6c 74 20 75 73 69 6e 67 20 6f 6e result using on
f220: 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 e of the sqlite3
f230: 5f 72 65 73 75 6c 74 5f 78 78 78 78 78 28 29 0d _result_xxxxx().
f240: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e 74 . /// int
f250: 65 72 66 61 63 65 73 2e 20 20 4f 6e 6c 79 20 69 erfaces. Only i
f260: 6e 20 74 68 61 74 20 63 61 73 65 20 73 71 6c 69 n that case sqli
f270: 74 65 33 5f 76 61 6c 75 65 5f 6e 6f 63 68 61 6e te3_value_nochan
f280: 67 65 28 29 20 77 69 6c 6c 20 62 65 0d 0a 20 20 ge() will be..
f290: 20 20 20 20 20 20 2f 2f 2f 20 74 72 75 65 20 77 /// true w
f2a0: 69 74 68 69 6e 20 74 68 65 20 78 55 70 64 61 74 ithin the xUpdat
f2b0: 65 20 6d 65 74 68 6f 64 2e 20 20 49 66 20 78 43 e method. If xC
f2c0: 6f 6c 75 6d 6e 20 64 6f 65 73 0d 0a 20 20 20 20 olumn does..
f2d0: 20 20 20 20 2f 2f 2f 20 69 6e 76 6f 6b 65 20 6f /// invoke o
f2e0: 6e 65 20 6f 72 20 6d 6f 72 65 20 73 71 6c 69 74 ne or more sqlit
f2f0: 65 33 5f 72 65 73 75 6c 74 5f 78 78 78 78 78 28 e3_result_xxxxx(
f300: 29 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 ).. /// i
f310: 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 6e 20 nterfaces, then
f320: 53 51 4c 69 74 65 20 75 6e 64 65 72 73 74 61 6e SQLite understan
f330: 64 73 20 74 68 61 74 20 61 73 20 61 20 63 68 61 ds that as a cha
f340: 6e 67 65 20 69 6e 20 74 68 65 20 76 61 6c 75 65 nge in the value
f350: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6f 66 .. /// of
f360: 20 74 68 65 20 63 6f 6c 75 6d 6e 20 61 6e 64 20 the column and
f370: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 the sqlite3_valu
f380: 65 5f 6e 6f 63 68 61 6e 67 65 28 29 20 63 61 6c e_nochange() cal
f390: 6c 20 66 6f 72 20 74 68 61 74 0d 0a 20 20 20 20 l for that..
f3a0: 20 20 20 20 2f 2f 2f 20 63 6f 6c 75 6d 6e 20 77 /// column w
f3b0: 69 74 68 69 6e 20 78 55 70 64 61 74 65 20 77 69 ithin xUpdate wi
f3c0: 6c 6c 20 72 65 74 75 72 6e 20 66 61 6c 73 65 2e ll return false.
f3d0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f .. /// </
f3e0: 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f para>.. /
f3f0: 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 // <para>..
f400: 20 20 20 2f 2f 2f 20 54 68 65 72 65 20 6d 69 67 /// There mig
f410: 68 74 20 62 65 20 6f 6e 65 20 6f 72 20 6d 6f 72 ht be one or mor
f420: 65 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 e sqlite3_vtab_c
f430: 75 72 73 6f 72 20 6f 62 6a 65 63 74 73 20 6f 70 ursor objects op
f440: 65 6e 20 61 6e 64 20 69 6e 20 75 73 65 20 0d 0a en and in use ..
f450: 20 20 20 20 20 20 20 20 2f 2f 2f 20 6f 6e 20 74 /// on t
f460: 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 he virtual table
f470: 20 69 6e 73 74 61 6e 63 65 20 61 6e 64 20 70 65 instance and pe
f480: 72 68 61 70 73 20 65 76 65 6e 20 6f 6e 20 74 68 rhaps even on th
f490: 65 20 72 6f 77 20 6f 66 20 74 68 65 20 76 69 72 e row of the vir
f4a0: 74 75 61 6c 0d 0a 20 20 20 20 20 20 20 20 2f 2f tual.. //
f4b0: 2f 20 74 61 62 6c 65 20 77 68 65 6e 20 74 68 65 / table when the
f4c0: 20 78 55 70 64 61 74 65 20 6d 65 74 68 6f 64 20 xUpdate method
f4d0: 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 54 68 65 is invoked. The
f4e0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
f4f0: 6f 66 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 of.. ///
f500: 78 55 70 64 61 74 65 20 6d 75 73 74 20 62 65 20 xUpdate must be
f510: 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 74 74 prepared for att
f520: 65 6d 70 74 73 20 74 6f 20 64 65 6c 65 74 65 20 empts to delete
f530: 6f 72 20 6d 6f 64 69 66 79 20 72 6f 77 73 20 6f or modify rows o
f540: 66 20 74 68 65 20 74 61 62 6c 65 0d 0a 20 20 20 f the table..
f550: 20 20 20 20 20 2f 2f 2f 20 6f 75 74 20 66 72 6f /// out fro
f560: 6d 20 6f 74 68 65 72 20 65 78 69 73 74 69 6e 67 m other existing
f570: 20 63 75 72 73 6f 72 73 2e 20 20 49 66 20 74 68 cursors. If th
f580: 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 e virtual table
f590: 63 61 6e 6e 6f 74 20 61 63 63 6f 6d 6d 6f 64 61 cannot accommoda
f5a0: 74 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 te.. ///
f5b0: 73 75 63 68 20 63 68 61 6e 67 65 73 2c 20 74 68 such changes, th
f5c0: 65 20 78 55 70 64 61 74 65 20 6d 65 74 68 6f 64 e xUpdate method
f5d0: 20 6d 75 73 74 20 72 65 74 75 72 6e 20 61 6e 20 must return an
f5e0: 65 72 72 6f 72 20 63 6f 64 65 2e 0d 0a 20 20 20 error code...
f5f0: 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e /// </para>
f600: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 .. /// <p
f610: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ara>.. //
f620: 2f 20 54 68 65 20 78 55 70 64 61 74 65 20 6d 65 / The xUpdate me
f630: 74 68 6f 64 20 69 73 20 6f 70 74 69 6f 6e 61 6c thod is optional
f640: 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 49 ... /// I
f650: 66 20 74 68 65 20 78 55 70 64 61 74 65 20 70 6f f the xUpdate po
f660: 69 6e 74 65 72 20 69 6e 20 74 68 65 20 73 71 6c inter in the sql
f670: 69 74 65 33 5f 6d 6f 64 75 6c 65 20 66 6f 72 20 ite3_module for
f680: 61 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 0d a virtual table.
f690: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 73 20 . /// is
f6a0: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 a NULL pointer,
f6b0: 74 68 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c then the virtual
f6c0: 20 74 61 62 6c 65 20 69 73 20 72 65 61 64 2d 6f table is read-o
f6d0: 6e 6c 79 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f nly... //
f6e0: 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 / </para>..
f6f0: 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79 /// </summary
f700: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c >.. /// <
f710: 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 56 74 61 param name="pVta
f720: 62 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f b">.. ///
f730: 20 54 68 65 20 6e 61 74 69 76 65 20 70 6f 69 6e The native poin
f740: 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ter to the sqlit
f750: 65 33 5f 76 74 61 62 20 64 65 72 69 76 65 64 20 e3_vtab derived
f760: 73 74 72 75 63 74 75 72 65 2e 0d 0a 20 20 20 20 structure...
f770: 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e /// </param>
f780: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 .. /// <p
f790: 61 72 61 6d 20 6e 61 6d 65 3d 22 61 72 67 63 22 aram name="argc"
f7a0: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 >.. /// T
f7b0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e 65 77 he number of new
f7c0: 20 6f 72 20 6d 6f 64 69 66 69 65 64 20 63 6f 6c or modified col
f7d0: 75 6d 6e 20 76 61 6c 75 65 73 20 63 6f 6e 74 61 umn values conta
f7e0: 69 6e 65 64 20 69 6e 0d 0a 20 20 20 20 20 20 20 ined in..
f7f0: 20 2f 2f 2f 20 3c 70 61 72 61 6d 72 65 66 20 6e /// <paramref n
f800: 61 6d 65 3d 22 61 72 67 76 22 20 2f 3e 2e 0d 0a ame="argv" />...
f810: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 /// </pa
f820: 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ram>.. //
f830: 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 61 / <param name="a
f840: 72 67 76 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f rgv">.. /
f850: 2f 2f 20 54 68 65 20 61 72 72 61 79 20 6f 66 20 // The array of
f860: 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72 73 20 native pointers
f870: 74 6f 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 to sqlite3_value
f880: 20 73 74 72 75 63 74 75 72 65 73 20 63 6f 6e 74 structures cont
f890: 61 69 6e 69 6e 67 0d 0a 20 20 20 20 20 20 20 20 aining..
f8a0: 2f 2f 2f 20 74 68 65 20 6e 65 77 20 6f 72 20 6d /// the new or m
f8b0: 6f 64 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 76 odified column v
f8c0: 61 6c 75 65 73 2c 20 69 66 20 61 6e 79 2e 0d 0a alues, if any...
f8d0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 /// </pa
f8e0: 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ram>.. //
f8f0: 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 72 / <param name="r
f900: 6f 77 49 64 22 3e 0d 0a 20 20 20 20 20 20 20 20 owId">..
f910: 2f 2f 2f 20 55 70 6f 6e 20 73 75 63 63 65 73 73 /// Upon success
f920: 2c 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 , this parameter
f930: 20 6d 75 73 74 20 62 65 20 6d 6f 64 69 66 69 65 must be modifie
f940: 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 74 68 65 d to contain the
f950: 20 75 6e 69 71 75 65 0d 0a 20 20 20 20 20 20 20 unique..
f960: 20 2f 2f 2f 20 69 6e 74 65 67 65 72 20 72 6f 77 /// integer row
f970: 20 69 64 65 6e 74 69 66 69 65 72 20 66 6f 72 20 identifier for
f980: 74 68 65 20 72 6f 77 20 74 68 61 74 20 77 61 73 the row that was
f990: 20 69 6e 73 65 72 74 65 64 2c 20 69 66 20 61 6e inserted, if an
f9a0: 79 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 y... ///
f9b0: 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 </param>..
f9c0: 20 20 2f 2f 2f 20 3c 72 65 74 75 72 6e 73 3e 0d /// <returns>.
f9d0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 20 73 . /// A s
f9e0: 74 61 6e 64 61 72 64 20 53 51 4c 69 74 65 20 72 tandard SQLite r
f9f0: 65 74 75 72 6e 20 63 6f 64 65 2e 0d 0a 20 20 20 eturn code...
fa00: 20 20 20 20 20 2f 2f 2f 20 3c 2f 72 65 74 75 72 /// </retur
fa10: 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 53 51 4c ns>.. SQL
fa20: 69 74 65 45 72 72 6f 72 43 6f 64 65 20 78 55 70 iteErrorCode xUp
fa30: 64 61 74 65 28 0d 0a 20 20 20 20 20 20 20 20 20 date(..
fa40: 20 20 20 49 6e 74 50 74 72 20 70 56 74 61 62 2c IntPtr pVtab,
fa50: 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 69 6e .. in
fa60: 74 20 61 72 67 63 2c 0d 0a 20 20 20 20 20 20 20 t argc,..
fa70: 20 20 20 20 20 49 6e 74 50 74 72 20 61 72 67 76 IntPtr argv
fa80: 2c 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 72 ,.. r
fa90: 65 66 20 6c 6f 6e 67 20 72 6f 77 49 64 0d 0a 20 ef long rowId..
faa0: 20 20 20 20 20 20 20 20 20 20 20 29 3b 0d 0a 0d );...
fab0: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f . ///////
fac0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
fad0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
fae0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
faf0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
fb00: 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 .... ///
fb10: 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 <summary>..
fb20: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f /// <para><co
fb30: 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f de>.. ///
fb40: 20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29 28 73 int (*xBegin)(s
fb50: 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 qlite3_vtab *pVT
fb60: 61 62 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f ab);.. //
fb70: 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e / </code></para>
fb80: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 .. /// <p
fb90: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ara>.. //
fba0: 2f 20 54 68 69 73 20 6d 65 74 68 6f 64 20 62 65 / This method be
fbb0: 67 69 6e 73 20 61 20 74 72 61 6e 73 61 63 74 69 gins a transacti
fbc0: 6f 6e 20 6f 6e 20 61 20 76 69 72 74 75 61 6c 20 on on a virtual
fbd0: 74 61 62 6c 65 2e 0d 0a 20 20 20 20 20 20 20 20 table...
fbe0: 2f 2f 2f 20 54 68 69 73 20 69 73 20 6d 65 74 68 /// This is meth
fbf0: 6f 64 20 69 73 20 6f 70 74 69 6f 6e 61 6c 2e 20 od is optional.
fc00: 20 54 68 65 20 78 42 65 67 69 6e 20 70 6f 69 6e The xBegin poin
fc10: 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d ter of sqlite3_m
fc20: 6f 64 75 6c 65 0d 0a 20 20 20 20 20 20 20 20 2f odule.. /
fc30: 2f 2f 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0d // may be NULL..
fc40: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 . /// </p
fc50: 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ara>.. //
fc60: 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 / <para>..
fc70: 20 20 2f 2f 2f 20 54 68 69 73 20 6d 65 74 68 6f /// This metho
fc80: 64 20 69 73 20 61 6c 77 61 79 73 20 66 6f 6c 6c d is always foll
fc90: 6f 77 65 64 20 62 79 20 6f 6e 65 20 63 61 6c 6c owed by one call
fca0: 20 74 6f 20 65 69 74 68 65 72 20 74 68 65 0d 0a to either the..
fcb0: 20 20 20 20 20 20 20 20 2f 2f 2f 20 78 43 6f 6d /// xCom
fcc0: 6d 69 74 20 6f 72 20 78 52 6f 6c 6c 62 61 63 6b mit or xRollback
fcd0: 20 6d 65 74 68 6f 64 2e 20 20 56 69 72 74 75 61 method. Virtua
fce0: 6c 20 74 61 62 6c 65 20 74 72 61 6e 73 61 63 74 l table transact
fcf0: 69 6f 6e 73 20 64 6f 0d 0a 20 20 20 20 20 20 20 ions do..
fd00: 20 2f 2f 2f 20 6e 6f 74 20 6e 65 73 74 2c 20 73 /// not nest, s
fd10: 6f 20 74 68 65 20 78 42 65 67 69 6e 20 6d 65 74 o the xBegin met
fd20: 68 6f 64 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 hod will not be
fd30: 69 6e 76 6f 6b 65 64 20 6d 6f 72 65 20 74 68 61 invoked more tha
fd40: 6e 20 6f 6e 63 65 0d 0a 20 20 20 20 20 20 20 20 n once..
fd50: 2f 2f 2f 20 6f 6e 20 61 20 73 69 6e 67 6c 65 20 /// on a single
fd60: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 0d 0a 20 virtual table..
fd70: 20 20 20 20 20 20 20 2f 2f 2f 20 77 69 74 68 6f /// witho
fd80: 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e ut an intervenin
fd90: 67 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 g call to either
fda0: 20 78 43 6f 6d 6d 69 74 20 6f 72 20 78 52 6f 6c xCommit or xRol
fdb0: 6c 62 61 63 6b 2e 0d 0a 20 20 20 20 20 20 20 20 lback...
fdc0: 2f 2f 2f 20 4d 75 6c 74 69 70 6c 65 20 63 61 6c /// Multiple cal
fdd0: 6c 73 20 74 6f 20 6f 74 68 65 72 20 6d 65 74 68 ls to other meth
fde0: 6f 64 73 20 63 61 6e 20 61 6e 64 20 6c 69 6b 65 ods can and like
fdf0: 6c 79 20 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e ly will occur in
fe00: 20 62 65 74 77 65 65 6e 0d 0a 20 20 20 20 20 20 between..
fe10: 20 20 2f 2f 2f 20 74 68 65 20 78 42 65 67 69 6e /// the xBegin
fe20: 20 61 6e 64 20 74 68 65 20 63 6f 72 72 65 73 70 and the corresp
fe30: 6f 6e 64 69 6e 67 20 78 43 6f 6d 6d 69 74 20 6f onding xCommit o
fe40: 72 20 78 52 6f 6c 6c 62 61 63 6b 2e 0d 0a 20 20 r xRollback...
fe50: 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 /// </para
fe60: 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c >.. /// <
fe70: 2f 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 /summary>..
fe80: 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 /// <param na
fe90: 6d 65 3d 22 70 56 74 61 62 22 3e 0d 0a 20 20 20 me="pVtab">..
fea0: 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e 61 74 /// The nat
feb0: 69 76 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 ive pointer to t
fec0: 68 65 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 he sqlite3_vtab
fed0: 64 65 72 69 76 65 64 20 73 74 72 75 63 74 75 72 derived structur
fee0: 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 e... ///
fef0: 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 </param>..
ff00: 20 20 2f 2f 2f 20 3c 72 65 74 75 72 6e 73 3e 0d /// <returns>.
ff10: 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 20 73 . /// A s
ff20: 74 61 6e 64 61 72 64 20 53 51 4c 69 74 65 20 72 tandard SQLite r
ff30: 65 74 75 72 6e 20 63 6f 64 65 2e 0d 0a 20 20 20 eturn code...
ff40: 20 20 20 20 20 2f 2f 2f 20 3c 2f 72 65 74 75 72 /// </retur
ff50: 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 53 51 4c ns>.. SQL
ff60: 69 74 65 45 72 72 6f 72 43 6f 64 65 20 78 42 65 iteErrorCode xBe
ff70: 67 69 6e 28 0d 0a 20 20 20 20 20 20 20 20 20 20 gin(..
ff80: 20 20 49 6e 74 50 74 72 20 70 56 74 61 62 0d 0a IntPtr pVtab..
ff90: 20 20 20 20 20 20 20 20 20 20 20 20 29 3b 0d 0a );..
ffa0: 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f .. //////
ffb0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
ffc0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
ffd0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
ffe0: 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
fff0: 2f 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f /.... ///
10000 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 <summary>..
10010 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 /// <para><c
10020 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ode>.. //
10030 2f 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 / int (*xSync)(s
10040 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 qlite3_vtab *pVT
10050 61 62 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f ab);.. //
10060 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e / </code></para>
10070 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 .. /// <p
10080 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ara>.. //
10090 2f 20 54 68 69 73 20 6d 65 74 68 6f 64 20 73 69 / This method si
100a0 67 6e 61 6c 73 20 74 68 65 20 73 74 61 72 74 20 gnals the start
100b0 6f 66 20 61 20 74 77 6f 2d 70 68 61 73 65 20 63 of a two-phase c
100c0 6f 6d 6d 69 74 20 6f 6e 20 61 20 76 69 72 74 75 ommit on a virtu
100d0 61 6c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 al.. ///
100e0 74 61 62 6c 65 2e 0d 0a 20 20 20 20 20 20 20 20 table...
100f0 2f 2f 2f 20 54 68 69 73 20 69 73 20 6d 65 74 68 /// This is meth
10100 6f 64 20 69 73 20 6f 70 74 69 6f 6e 61 6c 2e 20 od is optional.
10110 20 54 68 65 20 78 53 79 6e 63 20 70 6f 69 6e 74 The xSync point
10120 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d 6f er of sqlite3_mo
10130 64 75 6c 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f dule.. //
10140 2f 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0d 0a / may be NULL...
10150 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 /// </pa
10160 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ra>.. ///
10170 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 <para>..
10180 20 2f 2f 2f 20 54 68 69 73 20 6d 65 74 68 6f 64 /// This method
10190 20 69 73 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 64 is only invoked
101a0 20 61 66 74 65 72 20 63 61 6c 6c 20 74 6f 20 74 after call to t
101b0 68 65 20 78 42 65 67 69 6e 20 6d 65 74 68 6f 64 he xBegin method
101c0 20 61 6e 64 0d 0a 20 20 20 20 20 20 20 20 2f 2f and.. //
101d0 2f 20 70 72 69 6f 72 20 74 6f 20 61 6e 20 78 43 / prior to an xC
101e0 6f 6d 6d 69 74 20 6f 72 20 78 52 6f 6c 6c 62 61 ommit or xRollba
101f0 63 6b 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f ck. In order to
10200 20 69 6d 70 6c 65 6d 65 6e 74 20 74 77 6f 2d 70 implement two-p
10210 68 61 73 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f hase.. //
10220 2f 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20 78 53 / commit, the xS
10230 79 6e 63 20 6d 65 74 68 6f 64 20 6f 6e 20 61 6c ync method on al
10240 6c 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 l virtual tables
10250 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f is invoked prio
10260 72 20 74 6f 0d 0a 20 20 20 20 20 20 20 20 2f 2f r to.. //
10270 2f 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 78 / invoking the x
10280 43 6f 6d 6d 69 74 20 6d 65 74 68 6f 64 20 6f 6e Commit method on
10290 20 61 6e 79 20 76 69 72 74 75 61 6c 20 74 61 62 any virtual tab
102a0 6c 65 2e 20 20 49 66 20 61 6e 79 20 6f 66 20 74 le. If any of t
102b0 68 65 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f he .. ///
102c0 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 73 20 66 xSync methods f
102d0 61 69 6c 2c 20 74 68 65 20 65 6e 74 69 72 65 20 ail, the entire
102e0 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 72 transaction is r
102f0 6f 6c 6c 65 64 20 62 61 63 6b 2e 0d 0a 20 20 20 olled back...
10300 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e /// </para>
10310 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f .. /// </
10320 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 summary>..
10330 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d /// <param nam
10340 65 3d 22 70 56 74 61 62 22 3e 0d 0a 20 20 20 20 e="pVtab">..
10350 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e 61 74 69 /// The nati
10360 76 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 ve pointer to th
10370 65 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 64 e sqlite3_vtab d
10380 65 72 69 76 65 64 20 73 74 72 75 63 74 75 72 65 erived structure
10390 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c ... /// <
103a0 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 /param>..
103b0 20 2f 2f 2f 20 3c 72 65 74 75 72 6e 73 3e 0d 0a /// <returns>..
103c0 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 20 73 74 /// A st
103d0 61 6e 64 61 72 64 20 53 51 4c 69 74 65 20 72 65 andard SQLite re
103e0 74 75 72 6e 20 63 6f 64 65 2e 0d 0a 20 20 20 20 turn code...
103f0 20 20 20 20 2f 2f 2f 20 3c 2f 72 65 74 75 72 6e /// </return
10400 73 3e 0d 0a 20 20 20 20 20 20 20 20 53 51 4c 69 s>.. SQLi
10410 74 65 45 72 72 6f 72 43 6f 64 65 20 78 53 79 6e teErrorCode xSyn
10420 63 28 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 c(..
10430 49 6e 74 50 74 72 20 70 56 74 61 62 0d 0a 20 20 IntPtr pVtab..
10440 20 20 20 20 20 20 20 20 20 20 29 3b 0d 0a 0d 0a );....
10450 20 20 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f ////////
10460 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
10470 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
10480 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
10490 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d ///////////////.
104a0 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c ... /// <
104b0 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 summary>..
104c0 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 /// <para><cod
104d0 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 e>.. ///
104e0 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 int (*xCommit)(s
104f0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 qlite3_vtab *pVT
10500 61 62 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f ab);.. //
10510 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e / </code></para>
10520 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 .. /// <p
10530 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ara>.. //
10540 2f 20 54 68 69 73 20 6d 65 74 68 6f 64 20 63 61 / This method ca
10550 75 73 65 73 20 61 20 76 69 72 74 75 61 6c 20 74 uses a virtual t
10560 61 62 6c 65 20 74 72 61 6e 73 61 63 74 69 6f 6e able transaction
10570 20 74 6f 20 63 6f 6d 6d 69 74 2e 0d 0a 20 20 20 to commit...
10580 20 20 20 20 20 2f 2f 2f 20 54 68 69 73 20 69 73 /// This is
10590 20 6d 65 74 68 6f 64 20 69 73 20 6f 70 74 69 6f method is optio
105a0 6e 61 6c 2e 20 20 54 68 65 20 78 43 6f 6d 6d 69 nal. The xCommi
105b0 74 20 70 6f 69 6e 74 65 72 20 6f 66 20 73 71 6c t pointer of sql
105c0 69 74 65 33 5f 6d 6f 64 75 6c 65 0d 0a 20 20 20 ite3_module..
105d0 20 20 20 20 20 2f 2f 2f 20 6d 61 79 20 62 65 20 /// may be
105e0 4e 55 4c 4c 2e 0d 0a 20 20 20 20 20 20 20 20 2f NULL... /
105f0 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 // </para>..
10600 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a /// <para>..
10610 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 20 63 61 /// A ca
10620 6c 6c 20 74 6f 20 74 68 69 73 20 6d 65 74 68 6f ll to this metho
10630 64 20 61 6c 77 61 79 73 20 66 6f 6c 6c 6f 77 73 d always follows
10640 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f a prior call to
10650 20 78 42 65 67 69 6e 20 61 6e 64 0d 0a 20 20 20 xBegin and..
10660 20 20 20 20 20 2f 2f 2f 20 78 53 79 6e 63 2e 0d /// xSync..
10670 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 . /// </p
10680 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ara>.. //
10690 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 / </summary>..
106a0 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d /// <param
106b0 20 6e 61 6d 65 3d 22 70 56 74 61 62 22 3e 0d 0a name="pVtab">..
106c0 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 /// The
106d0 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72 20 74 native pointer t
106e0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 74 o the sqlite3_vt
106f0 61 62 20 64 65 72 69 76 65 64 20 73 74 72 75 63 ab derived struc
10700 74 75 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f ture... /
10710 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 // </param>..
10720 20 20 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72 6e /// <return
10730 73 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 s>.. ///
10740 41 20 73 74 61 6e 64 61 72 64 20 53 51 4c 69 74 A standard SQLit
10750 65 20 72 65 74 75 72 6e 20 63 6f 64 65 2e 0d 0a e return code...
10760 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72 65 /// </re
10770 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 turns>..
10780 53 51 4c 69 74 65 45 72 72 6f 72 43 6f 64 65 20 SQLiteErrorCode
10790 78 43 6f 6d 6d 69 74 28 0d 0a 20 20 20 20 20 20 xCommit(..
107a0 20 20 20 20 20 20 49 6e 74 50 74 72 20 70 56 74 IntPtr pVt
107b0 61 62 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 ab..
107c0 29 3b 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f );.... //
107d0 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
107e0 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
107f0 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
10800 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
10810 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 20 20 20 /////....
10820 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a /// <summary>..
10830 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 /// <par
10840 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20 a><code>..
10850 20 20 2f 2f 2f 20 69 6e 74 20 28 2a 78 52 6f 6c /// int (*xRol
10860 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 lback)(sqlite3_v
10870 74 61 62 20 2a 70 56 54 61 62 29 3b 0d 0a 20 20 tab *pVTab);..
10880 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 /// </code
10890 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 ></para>..
108a0 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 /// <para>..
108b0 20 20 20 20 20 20 2f 2f 2f 20 54 68 69 73 20 6d /// This m
108c0 65 74 68 6f 64 20 63 61 75 73 65 73 20 61 20 76 ethod causes a v
108d0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 74 72 61 irtual table tra
108e0 6e 73 61 63 74 69 6f 6e 20 74 6f 20 72 6f 6c 6c nsaction to roll
108f0 62 61 63 6b 2e 0d 0a 20 20 20 20 20 20 20 20 2f back... /
10900 2f 2f 20 54 68 69 73 20 69 73 20 6d 65 74 68 6f // This is metho
10910 64 20 69 73 20 6f 70 74 69 6f 6e 61 6c 2e 20 20 d is optional.
10920 54 68 65 20 78 52 6f 6c 6c 62 61 63 6b 20 70 6f The xRollback po
10930 69 6e 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 inter of sqlite3
10940 5f 6d 6f 64 75 6c 65 0d 0a 20 20 20 20 20 20 20 _module..
10950 20 2f 2f 2f 20 6d 61 79 20 62 65 20 4e 55 4c 4c /// may be NULL
10960 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c ... /// <
10970 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 /para>..
10980 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 /// <para>..
10990 20 20 20 20 2f 2f 2f 20 41 20 63 61 6c 6c 20 74 /// A call t
109a0 6f 20 74 68 69 73 20 6d 65 74 68 6f 64 20 61 6c o this method al
109b0 77 61 79 73 20 66 6f 6c 6c 6f 77 73 20 61 20 70 ways follows a p
109c0 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 42 65 rior call to xBe
109d0 67 69 6e 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f gin... //
109e0 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 / </para>..
109f0 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79 /// </summary
10a00 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c >.. /// <
10a10 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 56 74 61 param name="pVta
10a20 62 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f b">.. ///
10a30 20 54 68 65 20 6e 61 74 69 76 65 20 70 6f 69 6e The native poin
10a40 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ter to the sqlit
10a50 65 33 5f 76 74 61 62 20 64 65 72 69 76 65 64 20 e3_vtab derived
10a60 73 74 72 75 63 74 75 72 65 2e 0d 0a 20 20 20 20 structure...
10a70 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e /// </param>
10a80 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 72 .. /// <r
10a90 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 eturns>..
10aa0 20 2f 2f 2f 20 41 20 73 74 61 6e 64 61 72 64 20 /// A standard
10ab0 53 51 4c 69 74 65 20 72 65 74 75 72 6e 20 63 6f SQLite return co
10ac0 64 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f de... ///
10ad0 20 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 </returns>..
10ae0 20 20 20 20 20 53 51 4c 69 74 65 45 72 72 6f 72 SQLiteError
10af0 43 6f 64 65 20 78 52 6f 6c 6c 62 61 63 6b 28 0d Code xRollback(.
10b00 0a 20 20 20 20 20 20 20 20 20 20 20 20 49 6e 74 . Int
10b10 50 74 72 20 70 56 74 61 62 0d 0a 20 20 20 20 20 Ptr pVtab..
10b20 20 20 20 20 20 20 20 29 3b 0d 0a 0d 0a 20 20 20 );....
10b30 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ///////////
10b40 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
10b50 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
10b60 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
10b70 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a ////////////....
10b80 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 73 75 6d /// <sum
10b90 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f mary>.. /
10ba0 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d // <para><code>.
10bb0 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e 74 . /// int
10bc0 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e (*xFindFunction
10bd0 29 28 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 )(.. ///
10be0 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a sqlite3_vtab *
10bf0 70 56 74 61 62 2c 0d 0a 20 20 20 20 20 20 20 20 pVtab,..
10c00 2f 2f 2f 20 20 20 69 6e 74 20 6e 41 72 67 2c 0d /// int nArg,.
10c10 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 20 63 . /// c
10c20 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
10c30 2c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 20 ,.. ///
10c40 20 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 void (**pxFunc)
10c50 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
10c60 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
10c70 6c 75 65 2a 2a 29 2c 0d 0a 20 20 20 20 20 20 20 lue**),..
10c80 20 2f 2f 2f 20 20 20 76 6f 69 64 20 2a 2a 70 70 /// void **pp
10c90 41 72 67 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f Arg.. ///
10ca0 20 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f );.. ///
10cb0 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d </code></para>.
10cc0 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 . /// <pa
10cd0 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ra>.. ///
10ce0 20 54 68 69 73 20 6d 65 74 68 6f 64 20 69 73 20 This method is
10cf0 63 61 6c 6c 65 64 20 64 75 72 69 6e 67 20 73 71 called during sq
10d00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 lite3_prepare()
10d10 74 6f 20 67 69 76 65 20 74 68 65 20 76 69 72 74 to give the virt
10d20 75 61 6c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ual.. ///
10d30 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 table implement
10d40 61 74 69 6f 6e 20 61 6e 20 6f 70 70 6f 72 74 75 ation an opportu
10d50 6e 69 74 79 20 74 6f 20 6f 76 65 72 6c 6f 61 64 nity to overload
10d60 20 66 75 6e 63 74 69 6f 6e 73 2e 20 0d 0a 20 20 functions. ..
10d70 20 20 20 20 20 20 2f 2f 2f 20 54 68 69 73 20 6d /// This m
10d80 65 74 68 6f 64 20 6d 61 79 20 62 65 20 73 65 74 ethod may be set
10d90 20 74 6f 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 to NULL in whic
10da0 68 20 63 61 73 65 20 6e 6f 20 6f 76 65 72 6c 6f h case no overlo
10db0 61 64 69 6e 67 20 6f 63 63 75 72 73 2e 0d 0a 20 ading occurs...
10dc0 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 /// </par
10dd0 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 a>.. ///
10de0 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 <para>..
10df0 2f 2f 2f 20 57 68 65 6e 20 61 20 66 75 6e 63 74 /// When a funct
10e00 69 6f 6e 20 75 73 65 73 20 61 20 63 6f 6c 75 6d ion uses a colum
10e10 6e 20 66 72 6f 6d 20 61 20 76 69 72 74 75 61 6c n from a virtual
10e20 20 74 61 62 6c 65 20 61 73 20 69 74 73 20 66 69 table as its fi
10e30 72 73 74 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f rst .. //
10e40 2f 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 69 73 / argument, this
10e50 20 6d 65 74 68 6f 64 20 69 73 20 63 61 6c 6c 65 method is calle
10e60 64 20 74 6f 20 73 65 65 20 69 66 20 74 68 65 20 d to see if the
10e70 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 77 6f virtual table wo
10e80 75 6c 64 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f uld .. //
10e90 2f 20 6c 69 6b 65 20 74 6f 20 6f 76 65 72 6c 6f / like to overlo
10ea0 61 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2e ad the function.
10eb0 20 54 68 65 20 66 69 72 73 74 20 74 68 72 65 65 The first three
10ec0 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 parameters are
10ed0 69 6e 70 75 74 73 3a 20 0d 0a 20 20 20 20 20 20 inputs: ..
10ee0 20 20 2f 2f 2f 20 74 68 65 20 76 69 72 74 75 61 /// the virtua
10ef0 6c 20 74 61 62 6c 65 2c 20 74 68 65 20 6e 75 6d l table, the num
10f00 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 ber of arguments
10f10 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e to the function
10f20 2c 20 61 6e 64 20 74 68 65 20 0d 0a 20 20 20 20 , and the ..
10f30 20 20 20 20 2f 2f 2f 20 6e 61 6d 65 20 6f 66 20 /// name of
10f40 74 68 65 20 66 75 6e 63 74 69 6f 6e 2e 20 49 66 the function. If
10f50 20 6e 6f 20 6f 76 65 72 6c 6f 61 64 69 6e 67 20 no overloading
10f60 69 73 20 64 65 73 69 72 65 64 2c 20 74 68 69 73 is desired, this
10f70 20 6d 65 74 68 6f 64 0d 0a 20 20 20 20 20 20 20 method..
10f80 20 2f 2f 2f 20 72 65 74 75 72 6e 73 20 30 2e 20 /// returns 0.
10f90 54 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 To overload the
10fa0 66 75 6e 63 74 69 6f 6e 2c 20 74 68 69 73 20 6d function, this m
10fb0 65 74 68 6f 64 20 77 72 69 74 65 73 20 74 68 65 ethod writes the
10fc0 20 6e 65 77 20 0d 0a 20 20 20 20 20 20 20 20 2f new .. /
10fd0 2f 2f 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c // function impl
10fe0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 ementation into
10ff0 2a 70 78 46 75 6e 63 20 61 6e 64 20 77 72 69 74 *pxFunc and writ
11000 65 73 20 75 73 65 72 20 64 61 74 61 20 69 6e 74 es user data int
11010 6f 20 2a 70 70 41 72 67 20 0d 0a 20 20 20 20 20 o *ppArg ..
11020 20 20 20 2f 2f 2f 20 61 6e 64 20 72 65 74 75 72 /// and retur
11030 6e 73 20 65 69 74 68 65 72 20 31 20 6f 72 20 61 ns either 1 or a
11040 20 6e 75 6d 62 65 72 20 62 65 74 77 65 65 6e 0d number between.
11050 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 53 51 4c . /// SQL
11060 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 ITE_INDEX_CONSTR
11070 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 61 6e AINT_FUNCTION an
11080 64 20 32 35 35 2e 0d 0a 20 20 20 20 20 20 20 20 d 255...
11090 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 /// </para>..
110a0 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d /// <para>.
110b0 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 48 69 73 . /// His
110c0 74 6f 72 69 63 61 6c 6c 79 2c 20 74 68 65 20 72 torically, the r
110d0 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d eturn value from
110e0 20 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 28 29 xFindFunction()
110f0 20 77 61 73 20 65 69 74 68 65 72 20 7a 65 72 6f was either zero
11100 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6f 72 .. /// or
11110 20 6f 6e 65 2e 20 20 5a 65 72 6f 20 6d 65 61 6e one. Zero mean
11120 73 20 74 68 61 74 20 74 68 65 20 66 75 6e 63 74 s that the funct
11130 69 6f 6e 20 69 73 20 6e 6f 74 20 6f 76 65 72 6c ion is not overl
11140 6f 61 64 65 64 20 61 6e 64 20 6f 6e 65 20 6d 65 oaded and one me
11150 61 6e 73 20 74 68 61 74 0d 0a 20 20 20 20 20 20 ans that..
11160 20 20 2f 2f 2f 20 69 74 20 69 73 20 6f 76 65 72 /// it is over
11170 6c 6f 61 64 2e 20 20 54 68 65 20 61 62 69 6c 69 load. The abili
11180 74 79 20 74 6f 20 72 65 74 75 72 6e 20 76 61 6c ty to return val
11190 75 65 73 20 6f 66 20 0d 0a 20 20 20 20 20 20 20 ues of ..
111a0 20 2f 2f 2f 20 53 51 4c 49 54 45 5f 49 4e 44 45 /// SQLITE_INDE
111b0 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e X_CONSTRAINT_FUN
111c0 43 54 49 4f 4e 20 6f 72 20 67 72 65 61 74 65 72 CTION or greater
111d0 20 77 61 73 20 61 64 64 65 64 20 69 6e 0d 0a 20 was added in..
111e0 20 20 20 20 20 20 20 2f 2f 2f 20 76 65 72 73 69 /// versi
111f0 6f 6e 20 33 2e 32 35 2e 30 20 28 32 30 31 38 2d on 3.25.0 (2018-
11200 30 39 2d 31 35 29 2e 20 20 49 66 20 78 46 69 6e 09-15). If xFin
11210 64 46 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e dFunction return
11220 73 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 53 s.. /// S
11230 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 QLITE_INDEX_CONS
11240 54 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 TRAINT_FUNCTION
11250 6f 72 20 67 72 65 61 74 65 72 2c 20 74 68 61 6e or greater, than
11260 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 means that the
11270 66 75 6e 63 74 69 6f 6e 0d 0a 20 20 20 20 20 20 function..
11280 20 20 2f 2f 2f 20 74 61 6b 65 73 20 74 77 6f 20 /// takes two
11290 61 72 67 75 6d 65 6e 74 73 20 61 6e 64 20 74 68 arguments and th
112a0 65 20 66 75 6e 63 74 69 6f 6e 0d 0a 20 20 20 20 e function..
112b0 20 20 20 20 2f 2f 2f 20 63 61 6e 20 62 65 20 75 /// can be u
112c0 73 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e sed as a boolean
112d0 20 69 6e 20 74 68 65 20 57 48 45 52 45 20 63 6c in the WHERE cl
112e0 61 75 73 65 20 6f 66 20 61 20 71 75 65 72 79 20 ause of a query
112f0 61 6e 64 20 74 68 61 74 0d 0a 20 20 20 20 20 20 and that..
11300 20 20 2f 2f 2f 20 74 68 65 20 76 69 72 74 75 61 /// the virtua
11310 6c 20 74 61 62 6c 65 20 69 73 20 61 62 6c 65 20 l table is able
11320 74 6f 20 65 78 70 6c 6f 69 74 20 74 68 61 74 20 to exploit that
11330 66 75 6e 63 74 69 6f 6e 20 74 6f 20 73 70 65 65 function to spee
11340 64 20 75 70 20 74 68 65 20 71 75 65 72 79 0d 0a d up the query..
11350 20 20 20 20 20 20 20 20 2f 2f 2f 20 72 65 73 75 /// resu
11360 6c 74 2e 20 20 57 68 65 6e 20 78 46 69 6e 64 46 lt. When xFindF
11370 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
11380 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e SQLITE_INDEX_CON
11390 53 54 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e STRAINT_FUNCTION
113a0 20 6f 72 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f or .. //
113b0 2f 20 6c 61 72 67 65 72 2c 20 74 68 65 20 76 61 / larger, the va
113c0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 65 63 lue returned bec
113d0 6f 6d 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 omes the sqlite3
113e0 5f 69 6e 64 65 78 5f 69 6e 66 6f 2e 61 43 6f 6e _index_info.aCon
113f0 73 74 72 61 69 6e 74 2e 6f 70 0d 0a 20 20 20 20 straint.op..
11400 20 20 20 20 2f 2f 2f 20 76 61 6c 75 65 20 66 6f /// value fo
11410 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e r one of the con
11420 73 74 72 61 69 6e 74 73 20 70 61 73 73 65 64 20 straints passed
11430 69 6e 74 6f 20 78 42 65 73 74 49 6e 64 65 78 28 into xBestIndex(
11440 29 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 ) and the second
11450 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 61 72 .. /// ar
11460 67 75 6d 65 6e 74 20 62 65 63 6f 6d 65 73 20 74 gument becomes t
11470 68 65 20 76 61 6c 75 65 20 63 6f 72 72 65 73 70 he value corresp
11480 6f 6e 64 69 6e 67 20 74 6f 20 74 68 61 74 20 63 onding to that c
11490 6f 6e 73 74 72 61 69 6e 74 20 74 68 61 74 20 69 onstraint that i
114a0 73 20 70 61 73 73 65 64 0d 0a 20 20 20 20 20 20 s passed..
114b0 20 20 2f 2f 2f 20 74 6f 20 78 46 69 6c 74 65 72 /// to xFilter
114c0 28 29 2e 20 20 54 68 69 73 20 65 6e 61 62 6c 65 (). This enable
114d0 73 20 74 68 65 0d 0a 20 20 20 20 20 20 20 20 2f s the.. /
114e0 2f 2f 20 78 42 65 73 74 49 6e 64 65 78 28 29 2f // xBestIndex()/
114f0 78 46 69 6c 74 65 72 20 69 6d 70 6c 65 6d 65 6e xFilter implemen
11500 74 61 74 69 6f 6e 73 20 74 6f 20 75 73 65 20 74 tations to use t
11510 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 73 he function to s
11520 70 65 65 64 0d 0a 20 20 20 20 20 20 20 20 2f 2f peed.. //
11530 2f 20 69 74 73 20 73 65 61 72 63 68 2e 0d 0a 20 / its search...
11540 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 /// </par
11550 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 a>.. ///
11560 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 <para>..
11570 2f 2f 2f 20 54 68 65 20 74 65 63 68 6e 69 71 75 /// The techniqu
11580 65 20 6f 66 20 68 61 76 69 6e 67 20 78 46 69 6e e of having xFin
11590 64 46 75 6e 63 74 69 6f 6e 28 29 20 72 65 74 75 dFunction() retu
115a0 72 6e 20 76 61 6c 75 65 73 20 6f 66 0d 0a 20 20 rn values of..
115b0 20 20 20 20 20 20 2f 2f 2f 20 53 51 4c 49 54 45 /// SQLITE
115c0 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e _INDEX_CONSTRAIN
115d0 54 5f 46 55 4e 43 54 49 4f 4e 20 77 61 73 20 69 T_FUNCTION was i
115e0 6e 69 74 69 61 6c 6c 79 20 75 73 65 64 20 69 6e nitially used in
115f0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 the implementat
11600 69 6f 6e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ion.. ///
11610 20 6f 66 20 74 68 65 20 47 65 6f 70 6f 6c 79 20 of the Geopoly
11620 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 78 46 69 module. The xFi
11630 6e 64 46 75 6e 63 74 69 6f 6e 28 29 20 6d 65 74 ndFunction() met
11640 68 6f 64 20 6f 66 20 74 68 61 74 20 6d 6f 64 75 hod of that modu
11650 6c 65 20 72 65 74 75 72 6e 73 0d 0a 20 20 20 20 le returns..
11660 20 20 20 20 2f 2f 2f 20 53 51 4c 49 54 45 5f 49 /// SQLITE_I
11670 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f NDEX_CONSTRAINT_
11680 46 55 4e 43 54 49 4f 4e 20 66 6f 72 20 74 68 65 FUNCTION for the
11690 20 67 65 6f 70 6f 6c 79 5f 6f 76 65 72 6c 61 70 geopoly_overlap
116a0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0d () SQL function.
116b0 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 61 6e 64 . /// and
116c0 20 69 74 20 72 65 74 75 72 6e 73 0d 0a 20 20 20 it returns..
116d0 20 20 20 20 20 2f 2f 2f 20 53 51 4c 49 54 45 5f /// SQLITE_
116e0 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 INDEX_CONSTRAINT
116f0 5f 46 55 4e 43 54 49 4f 4e 2b 31 20 66 6f 72 20 _FUNCTION+1 for
11700 74 68 65 20 67 65 6f 70 6f 6c 79 5f 77 69 74 68 the geopoly_with
11710 69 6e 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f in() SQL functio
11720 6e 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 n... ///
11730 54 68 69 73 20 70 65 72 6d 69 74 73 20 73 65 61 This permits sea
11740 72 63 68 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e rch optimization
11750 73 20 66 6f 72 20 71 75 65 72 69 65 73 20 73 75 s for queries su
11760 63 68 20 61 73 3a 0d 0a 20 20 20 20 20 20 20 20 ch as:..
11770 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 /// </para>..
11780 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 3c /// <para><
11790 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 2f code>.. /
117a0 2f 2f 20 53 45 4c 45 43 54 20 2a 20 46 52 4f 4d // SELECT * FROM
117b0 20 67 65 6f 70 6f 6c 79 74 61 62 20 57 48 45 52 geopolytab WHER
117c0 45 20 67 65 6f 70 6f 6c 79 5f 6f 76 65 72 6c 61 E geopoly_overla
117d0 70 28 5f 73 68 61 70 65 2c 20 24 71 75 65 72 79 p(_shape, $query
117e0 5f 70 6f 6c 79 67 6f 6e 29 3b 0d 0a 20 20 20 20 _polygon);..
117f0 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 65 3e 3c /// </code><
11800 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 /para>..
11810 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 /// <para>..
11820 20 20 20 20 2f 2f 2f 20 4e 6f 74 65 20 74 68 61 /// Note tha
11830 74 20 69 6e 66 69 78 20 66 75 6e 63 74 69 6f 6e t infix function
11840 73 20 28 4c 49 4b 45 2c 20 47 4c 4f 42 2c 20 52 s (LIKE, GLOB, R
11850 45 47 45 58 50 2c 20 61 6e 64 20 4d 41 54 43 48 EGEXP, and MATCH
11860 29 20 72 65 76 65 72 73 65 20 0d 0a 20 20 20 20 ) reverse ..
11870 20 20 20 20 2f 2f 2f 20 74 68 65 20 6f 72 64 65 /// the orde
11880 72 20 6f 66 20 74 68 65 69 72 20 61 72 67 75 6d r of their argum
11890 65 6e 74 73 2e 20 53 6f 20 22 6c 69 6b 65 28 41 ents. So "like(A
118a0 2c 42 29 22 20 69 73 20 65 71 75 69 76 61 6c 65 ,B)" is equivale
118b0 6e 74 20 74 6f 20 22 42 20 6c 69 6b 65 20 41 22 nt to "B like A"
118c0 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 . .. ///
118d0 46 6f 72 20 74 68 65 20 66 6f 72 6d 20 22 42 20 For the form "B
118e0 6c 69 6b 65 20 41 22 20 74 68 65 20 42 20 74 65 like A" the B te
118f0 72 6d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 rm is considered
11900 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
11910 65 6e 74 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f ent .. //
11920 2f 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f / to the functio
11930 6e 2e 20 42 75 74 20 66 6f 72 20 22 6c 69 6b 65 n. But for "like
11940 28 41 2c 42 29 22 20 74 68 65 20 41 20 74 65 72 (A,B)" the A ter
11950 6d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 m is considered
11960 74 68 65 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f the .. //
11970 2f 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 / first argument
11980 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c ... /// <
11990 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 /para>..
119a0 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 /// <para>..
119b0 20 20 20 20 2f 2f 2f 20 54 68 65 20 66 75 6e 63 /// The func
119c0 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 72 65 74 tion pointer ret
119d0 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f urned by this ro
119e0 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 76 61 utine must be va
119f0 6c 69 64 20 66 6f 72 0d 0a 20 20 20 20 20 20 20 lid for..
11a00 20 2f 2f 2f 20 74 68 65 20 6c 69 66 65 74 69 6d /// the lifetim
11a10 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 e of the sqlite3
11a20 5f 76 74 61 62 20 6f 62 6a 65 63 74 20 67 69 76 _vtab object giv
11a30 65 6e 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 en in the first
11a40 70 61 72 61 6d 65 74 65 72 2e 0d 0a 20 20 20 20 parameter...
11a50 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d /// </para>.
11a60 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 73 . /// </s
11a70 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 ummary>..
11a80 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 /// <param name
11a90 3d 22 70 56 74 61 62 22 3e 0d 0a 20 20 20 20 20 ="pVtab">..
11aa0 20 20 20 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76 /// The nativ
11ab0 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 e pointer to the
11ac0 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 64 65 sqlite3_vtab de
11ad0 72 69 76 65 64 20 73 74 72 75 63 74 75 72 65 2e rived structure.
11ae0 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f .. /// </
11af0 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 param>..
11b00 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d /// <param name=
11b10 22 6e 41 72 67 22 3e 0d 0a 20 20 20 20 20 20 20 "nArg">..
11b20 20 2f 2f 2f 20 54 68 65 20 6e 75 6d 62 65 72 20 /// The number
11b30 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 of arguments to
11b40 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 the function bei
11b50 6e 67 20 73 6f 75 67 68 74 2e 0d 0a 20 20 20 20 ng sought...
11b60 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e /// </param>
11b70 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 .. /// <p
11b80 61 72 61 6d 20 6e 61 6d 65 3d 22 7a 4e 61 6d 65 aram name="zName
11b90 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 ">.. ///
11ba0 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 The name of the
11bb0 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 73 function being s
11bc0 6f 75 67 68 74 2e 0d 0a 20 20 20 20 20 20 20 20 ought...
11bd0 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 /// </param>..
11be0 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d /// <param
11bf0 20 6e 61 6d 65 3d 22 63 61 6c 6c 62 61 63 6b 22 name="callback"
11c00 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 55 >.. /// U
11c10 70 6f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 69 pon success, thi
11c20 73 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 s parameter must
11c30 20 62 65 20 6d 6f 64 69 66 69 65 64 20 74 6f 20 be modified to
11c40 63 6f 6e 74 61 69 6e 20 74 68 65 0d 0a 20 20 20 contain the..
11c50 20 20 20 20 20 2f 2f 2f 20 64 65 6c 65 67 61 74 /// delegat
11c60 65 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f e responsible fo
11c70 72 20 69 6d 70 6c 65 6d 65 6e 74 69 6e 67 20 74 r implementing t
11c80 68 65 20 73 70 65 63 69 66 69 65 64 20 66 75 6e he specified fun
11c90 63 74 69 6f 6e 2e 0d 0a 20 20 20 20 20 20 20 20 ction...
11ca0 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 /// </param>..
11cb0 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d /// <param
11cc0 20 6e 61 6d 65 3d 22 70 43 6c 69 65 6e 74 44 61 name="pClientDa
11cd0 74 61 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ta">.. //
11ce0 2f 20 55 70 6f 6e 20 73 75 63 63 65 73 73 2c 20 / Upon success,
11cf0 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 6d this parameter m
11d00 75 73 74 20 62 65 20 6d 6f 64 69 66 69 65 64 20 ust be modified
11d10 74 6f 20 63 6f 6e 74 61 69 6e 20 74 68 65 0d 0a to contain the..
11d20 20 20 20 20 20 20 20 20 2f 2f 2f 20 6e 61 74 69 /// nati
11d30 76 65 20 75 73 65 72 2d 64 61 74 61 20 70 6f 69 ve user-data poi
11d40 6e 74 65 72 20 61 73 73 6f 63 69 61 74 65 64 20 nter associated
11d50 77 69 74 68 0d 0a 20 20 20 20 20 20 20 20 2f 2f with.. //
11d60 2f 20 3c 70 61 72 61 6d 72 65 66 20 6e 61 6d 65 / <paramref name
11d70 3d 22 63 61 6c 6c 62 61 63 6b 22 20 2f 3e 2e 0d ="callback" />..
11d80 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 . /// </p
11d90 61 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f aram>.. /
11da0 2f 2f 20 3c 72 65 74 75 72 6e 73 3e 0d 0a 20 20 // <returns>..
11db0 20 20 20 20 20 20 2f 2f 2f 20 4e 6f 6e 2d 7a 65 /// Non-ze
11dc0 72 6f 20 69 66 20 74 68 65 20 73 70 65 63 69 66 ro if the specif
11dd0 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 ied function was
11de0 20 66 6f 75 6e 64 3b 20 7a 65 72 6f 20 6f 74 68 found; zero oth
11df0 65 72 77 69 73 65 2e 0d 0a 20 20 20 20 20 20 20 erwise...
11e00 20 2f 2f 2f 20 3c 2f 72 65 74 75 72 6e 73 3e 0d /// </returns>.
11e10 0a 20 20 20 20 20 20 20 20 69 6e 74 20 78 46 69 . int xFi
11e20 6e 64 46 75 6e 63 74 69 6f 6e 28 0d 0a 20 20 20 ndFunction(..
11e30 20 20 20 20 20 20 20 20 20 49 6e 74 50 74 72 20 IntPtr
11e40 70 56 74 61 62 2c 0d 0a 20 20 20 20 20 20 20 20 pVtab,..
11e50 20 20 20 20 69 6e 74 20 6e 41 72 67 2c 0d 0a 20 int nArg,..
11e60 20 20 20 20 20 20 20 20 20 20 20 49 6e 74 50 74 IntPt
11e70 72 20 7a 4e 61 6d 65 2c 0d 0a 20 20 20 20 20 20 r zName,..
11e80 20 20 20 20 20 20 72 65 66 20 53 51 4c 69 74 65 ref SQLite
11e90 43 61 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 Callback callbac
11ea0 6b 2c 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 k,..
11eb0 72 65 66 20 49 6e 74 50 74 72 20 70 43 6c 69 65 ref IntPtr pClie
11ec0 6e 74 44 61 74 61 0d 0a 20 20 20 20 20 20 20 20 ntData..
11ed0 20 20 20 20 29 3b 0d 0a 0d 0a 20 20 20 20 20 20 );....
11ee0 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f //////////////
11ef0 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
11f00 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
11f10 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
11f20 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 /////////....
11f30 20 20 20 20 20 2f 2f 2f 20 3c 73 75 6d 6d 61 72 /// <summar
11f40 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 y>.. ///
11f50 3c 70 61 72 61 3e 3c 63 6f 64 65 3e 0d 0a 20 20 <para><code>..
11f60 20 20 20 20 20 20 2f 2f 2f 20 69 6e 74 20 28 2a /// int (*
11f70 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 xRename)(sqlite3
11f80 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 63 6f _vtab *pVtab, co
11f90 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 29 3b nst char *zNew);
11fa0 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f .. /// </
11fb0 63 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 code></para>..
11fc0 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e /// <para>
11fd0 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 .. /// Th
11fe0 69 73 20 6d 65 74 68 6f 64 20 70 72 6f 76 69 64 is method provid
11ff0 65 73 20 6e 6f 74 69 66 69 63 61 74 69 6f 6e 20 es notification
12000 74 68 61 74 20 74 68 65 20 76 69 72 74 75 61 6c that the virtual
12010 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 table implement
12020 61 74 69 6f 6e 0d 0a 20 20 20 20 20 20 20 20 2f ation.. /
12030 2f 2f 20 74 68 61 74 20 74 68 65 20 76 69 72 74 // that the virt
12040 75 61 6c 20 74 61 62 6c 65 20 77 69 6c 6c 20 62 ual table will b
12050 65 20 67 69 76 65 6e 20 61 20 6e 65 77 20 6e 61 e given a new na
12060 6d 65 2e 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f me. .. //
12070 2f 20 49 66 20 74 68 69 73 20 6d 65 74 68 6f 64 / If this method
12080 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f returns SQLITE_
12090 4f 4b 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 OK then SQLite r
120a0 65 6e 61 6d 65 73 20 74 68 65 20 74 61 62 6c 65 enames the table
120b0 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 49 ... /// I
120c0 66 20 74 68 69 73 20 6d 65 74 68 6f 64 20 72 65 f this method re
120d0 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 20 63 turns an error c
120e0 6f 64 65 20 74 68 65 6e 20 74 68 65 20 72 65 6e ode then the ren
120f0 61 6d 69 6e 67 20 69 73 20 70 72 65 76 65 6e 74 aming is prevent
12100 65 64 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ed... ///
12110 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 </para>..
12120 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 /// <para>..
12130 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 78 52 /// The xR
12140 65 6e 61 6d 65 20 6d 65 74 68 6f 64 20 69 73 20 ename method is
12150 6f 70 74 69 6f 6e 61 6c 2e 20 20 49 66 20 6f 6d optional. If om
12160 69 74 74 65 64 2c 20 74 68 65 6e 20 74 68 65 20 itted, then the
12170 76 69 72 74 75 61 6c 0d 0a 20 20 20 20 20 20 20 virtual..
12180 20 2f 2f 2f 20 74 61 62 6c 65 20 6d 61 79 20 6e /// table may n
12190 6f 74 20 62 65 20 72 65 6e 61 6d 65 64 20 75 73 ot be renamed us
121a0 69 6e 67 20 74 68 65 20 41 4c 54 45 52 20 54 41 ing the ALTER TA
121b0 42 4c 45 20 52 45 4e 41 4d 45 20 63 6f 6d 6d 61 BLE RENAME comma
121c0 6e 64 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f nd... ///
121d0 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 </para>..
121e0 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 20 /// <para>..
121f0 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 50 52 /// The PR
12200 41 47 4d 41 20 6c 65 67 61 63 79 5f 61 6c 74 65 AGMA legacy_alte
12210 72 5f 74 61 62 6c 65 20 73 65 74 74 69 6e 67 20 r_table setting
12220 69 73 20 65 6e 61 62 6c 65 64 20 70 72 69 6f 72 is enabled prior
12230 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 74 68 69 to invoking thi
12240 73 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 6d s.. /// m
12250 65 74 68 6f 64 2c 20 61 6e 64 20 74 68 65 20 76 ethod, and the v
12260 61 6c 75 65 20 66 6f 72 20 6c 65 67 61 63 79 5f alue for legacy_
12270 61 6c 74 65 72 5f 74 61 62 6c 65 20 69 73 20 72 alter_table is r
12280 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 74 68 estored after th
12290 69 73 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 is.. ///
122a0 6d 65 74 68 6f 64 20 66 69 6e 69 73 68 65 73 2e method finishes.
122b0 20 20 54 68 69 73 20 69 73 20 6e 65 63 65 73 73 This is necess
122c0 61 72 79 20 66 6f 72 20 74 68 65 20 63 6f 72 72 ary for the corr
122d0 65 63 74 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 ect operation of
122e0 20 76 69 72 74 75 61 6c 0d 0a 20 20 20 20 20 20 virtual..
122f0 20 20 2f 2f 2f 20 74 61 62 6c 65 73 20 74 68 61 /// tables tha
12300 74 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 73 68 t make use of sh
12310 61 64 6f 77 20 74 61 62 6c 65 73 20 77 68 65 72 adow tables wher
12320 65 20 74 68 65 20 73 68 61 64 6f 77 20 74 61 62 e the shadow tab
12330 6c 65 73 20 6d 75 73 74 20 62 65 0d 0a 20 20 20 les must be..
12340 20 20 20 20 20 2f 2f 2f 20 72 65 6e 61 6d 65 64 /// renamed
12350 20 74 6f 20 6d 61 74 63 68 20 74 68 65 20 6e 65 to match the ne
12360 77 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 w virtual table
12370 6e 61 6d 65 2e 20 20 49 66 20 74 68 65 20 6c 65 name. If the le
12380 67 61 63 79 5f 61 6c 74 65 72 5f 66 6f 72 6d 61 gacy_alter_forma
12390 74 20 69 73 0d 0a 20 20 20 20 20 20 20 20 2f 2f t is.. //
123a0 2f 20 6f 66 66 2c 20 74 68 65 6e 20 74 68 65 20 / off, then the
123b0 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64 20 xConnect method
123c0 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 will be invoked
123d0 66 6f 72 20 74 68 65 20 76 69 72 74 75 61 6c 20 for the virtual
123e0 74 61 62 6c 65 20 65 76 65 72 79 0d 0a 20 20 20 table every..
123f0 20 20 20 20 20 2f 2f 2f 20 74 69 6d 65 20 74 68 /// time th
12400 65 20 78 52 65 6e 61 6d 65 20 6d 65 74 68 6f 64 e xRename method
12410 20 74 72 69 65 73 20 74 6f 20 63 68 61 6e 67 65 tries to change
12420 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
12430 20 73 68 61 64 6f 77 20 74 61 62 6c 65 2e 0d 0a shadow table...
12440 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 /// </pa
12450 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ra>.. ///
12460 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 20 </summary>..
12470 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 /// <param
12480 6e 61 6d 65 3d 22 70 56 74 61 62 22 3e 0d 0a 20 name="pVtab">..
12490 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e /// The n
124a0 61 74 69 76 65 20 70 6f 69 6e 74 65 72 20 74 6f ative pointer to
124b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 74 61 the sqlite3_vta
124c0 62 20 64 65 72 69 76 65 64 20 73 74 72 75 63 74 b derived struct
124d0 75 72 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ure... //
124e0 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 / </param>..
124f0 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 6d 20 6e /// <param n
12500 61 6d 65 3d 22 7a 4e 65 77 22 3e 0d 0a 20 20 20 ame="zNew">..
12510 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 6e 61 74 /// The nat
12520 69 76 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 ive pointer to t
12530 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 he UTF-8 encoded
12540 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 string containi
12550 6e 67 20 74 68 65 20 6e 65 77 0d 0a 20 20 20 20 ng the new..
12560 20 20 20 20 2f 2f 2f 20 6e 61 6d 65 20 66 6f 72 /// name for
12570 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 the virtual tab
12580 6c 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f le... ///
12590 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 20 </param>..
125a0 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72 6e 73 3e /// <returns>
125b0 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 20 .. /// A
125c0 73 74 61 6e 64 61 72 64 20 53 51 4c 69 74 65 20 standard SQLite
125d0 72 65 74 75 72 6e 20 63 6f 64 65 2e 0d 0a 20 20 return code...
125e0 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72 65 74 75 /// </retu
125f0 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 53 51 rns>.. SQ
12600 4c 69 74 65 45 72 72 6f 72 43 6f 64 65 20 78 52 LiteErrorCode xR
12610 65 6e 61 6d 65 28 0d 0a 20 20 20 20 20 20 20 20 ename(..
12620 20 20 20 20 49 6e 74 50 74 72 20 70 56 74 61 62 IntPtr pVtab
12630 2c 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 49 ,.. I
12640 6e 74 50 74 72 20 7a 4e 65 77 0d 0a 20 20 20 20 ntPtr zNew..
12650 20 20 20 20 20 20 20 20 29 3b 0d 0a 0d 0a 20 20 );....
12660 20 20 20 20 20 20 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f //////////
12670 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
12680 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
12690 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
126a0 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 0d 0a 0d /////////////...
126b0 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 73 75 . /// <su
126c0 6d 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 mmary>..
126d0 2f 2f 2f 20 3c 70 61 72 61 3e 3c 63 6f 64 65 3e /// <para><code>
126e0 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e .. /// in
126f0 74 20 28 2a 78 53 61 76 65 70 6f 69 6e 74 29 28 t (*xSavepoint)(
12700 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 sqlite3_vtab *pV
12710 74 61 62 2c 20 69 6e 74 29 3b 0d 0a 20 20 20 20 tab, int);..
12720 20 20 20 20 2f 2f 2f 20 69 6e 74 20 28 2a 78 52 /// int (*xR
12730 65 6c 65 61 73 65 29 28 73 71 6c 69 74 65 33 5f elease)(sqlite3_
12740 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 vtab *pVtab, int
12750 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 );.. ///
12760 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 54 int (*xRollbackT
12770 6f 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 o)(sqlite3_vtab
12780 2a 70 56 74 61 62 2c 20 69 6e 74 29 3b 0d 0a 20 *pVtab, int);..
12790 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 63 6f 64 /// </cod
127a0 65 3e 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 e></para>..
127b0 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 /// <para>..
127c0 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 73 65 /// These
127d0 20 6d 65 74 68 6f 64 73 20 70 72 6f 76 69 64 65 methods provide
127e0 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 the virtual tab
127f0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
12800 6e 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 n an opportunity
12810 20 74 6f 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f to.. ///
12820 20 69 6d 70 6c 65 6d 65 6e 74 20 6e 65 73 74 65 implement neste
12830 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 2e 20 d transactions.
12840 20 54 68 65 79 20 61 72 65 20 61 6c 77 61 79 73 They are always
12850 20 6f 70 74 69 6f 6e 61 6c 20 61 6e 64 20 77 69 optional and wi
12860 6c 6c 20 6f 6e 6c 79 20 62 65 0d 0a 20 20 20 20 ll only be..
12870 20 20 20 20 2f 2f 2f 20 63 61 6c 6c 65 64 20 69 /// called i
12880 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e n SQLite version
12890 20 33 2e 37 2e 37 20 28 32 30 31 31 2d 30 36 2d 3.7.7 (2011-06-
128a0 32 33 29 20 61 6e 64 20 6c 61 74 65 72 2e 0d 0a 23) and later...
128b0 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 /// </pa
128c0 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ra>.. ///
128d0 20 3c 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 <para>..
128e0 20 2f 2f 2f 20 57 68 65 6e 20 78 53 61 76 65 70 /// When xSavep
128f0 6f 69 6e 74 28 58 2c 4e 29 20 69 73 20 69 6e 76 oint(X,N) is inv
12900 6f 6b 65 64 2c 20 74 68 61 74 20 69 73 20 61 20 oked, that is a
12910 73 69 67 6e 61 6c 20 74 6f 20 74 68 65 20 76 69 signal to the vi
12920 72 74 75 61 6c 20 74 61 62 6c 65 20 58 0d 0a 20 rtual table X..
12930 20 20 20 20 20 20 20 2f 2f 2f 20 74 68 61 74 20 /// that
12940 69 74 20 73 68 6f 75 6c 64 20 73 61 76 65 20 69 it should save i
12950 74 73 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 ts current state
12960 20 61 73 20 73 61 76 65 70 6f 69 6e 74 20 4e 2e as savepoint N.
12970 20 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 .. ///
12980 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c A subsequent cal
12990 6c 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 l.. /// t
129a0 6f 20 78 52 6f 6c 6c 62 61 63 6b 54 6f 28 58 2c o xRollbackTo(X,
129b0 52 29 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 R) means that th
129c0 65 20 73 74 61 74 65 20 6f 66 20 74 68 65 20 76 e state of the v
129d0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 73 68 6f irtual table sho
129e0 75 6c 64 20 72 65 74 75 72 6e 0d 0a 20 20 20 20 uld return..
129f0 20 20 20 20 2f 2f 2f 20 74 6f 20 77 68 61 74 20 /// to what
12a00 69 74 20 77 61 73 20 77 68 65 6e 20 78 53 61 76 it was when xSav
12a10 65 70 6f 69 6e 74 28 58 2c 52 29 20 77 61 73 20 epoint(X,R) was
12a20 6c 61 73 74 20 63 61 6c 6c 65 64 2e 20 20 0d 0a last called. ..
12a30 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 65 20 /// The
12a40 63 61 6c 6c 0d 0a 20 20 20 20 20 20 20 20 2f 2f call.. //
12a50 2f 20 74 6f 20 78 52 6f 6c 6c 62 61 63 6b 54 6f / to xRollbackTo
12a60 28 58 2c 52 29 20 77 69 6c 6c 20 69 6e 76 61 6c (X,R) will inval
12a70 69 64 61 74 65 20 61 6c 6c 20 73 61 76 65 70 6f idate all savepo
12a80 69 6e 74 73 20 77 69 74 68 20 4e 3e 52 3b 20 6e ints with N>R; n
12a90 6f 6e 65 20 6f 66 20 74 68 65 0d 0a 20 20 20 20 one of the..
12aa0 20 20 20 20 2f 2f 2f 20 69 6e 76 61 6c 69 64 65 /// invalide
12ab0 64 20 73 61 76 65 70 6f 69 6e 74 73 20 77 69 6c d savepoints wil
12ac0 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b l be rolled back
12ad0 20 6f 72 20 72 65 6c 65 61 73 65 64 20 77 69 74 or released wit
12ae0 68 6f 75 74 20 66 69 72 73 74 0d 0a 20 20 20 20 hout first..
12af0 20 20 20 20 2f 2f 2f 20 62 65 69 6e 67 20 72 65 /// being re
12b00 69 6e 69 74 69 61 6c 69 7a 65 64 20 62 79 20 61 initialized by a
12b10 20 63 61 6c 6c 20 74 6f 20 78 53 61 76 65 70 6f call to xSavepo
12b20 69 6e 74 28 29 2e 20 20 0d 0a 20 20 20 20 20 20 int(). ..
12b30 20 20 2f 2f 2f 20 41 20 63 61 6c 6c 20 74 6f 20 /// A call to
12b40 78 52 65 6c 65 61 73 65 28 58 2c 4d 29 20 69 6e xRelease(X,M) in
12b50 76 61 6c 69 64 61 74 65 73 20 61 6c 6c 20 73 61 validates all sa
12b60 76 65 70 6f 69 6e 74 73 20 77 68 65 72 65 20 4e vepoints where N
12b70 3e 3d 4d 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f >=M... //
12b80 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 / </para>..
12b90 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 /// <para>..
12ba0 20 20 20 20 20 20 20 2f 2f 2f 20 4e 6f 6e 65 20 /// None
12bb0 6f 66 20 74 68 65 20 78 53 61 76 65 70 6f 69 6e of the xSavepoin
12bc0 74 28 29 2c 20 78 52 65 6c 65 61 73 65 28 29 2c t(), xRelease(),
12bd0 20 6f 72 20 78 52 6f 6c 6c 62 61 63 6b 54 6f 28 or xRollbackTo(
12be0 29 20 6d 65 74 68 6f 64 73 20 77 69 6c 6c 20 65 ) methods will e
12bf0 76 65 72 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ver.. ///
12c00 20 62 65 20 63 61 6c 6c 65 64 20 65 78 63 65 70 be called excep
12c10 74 20 69 6e 20 62 65 74 77 65 65 6e 20 63 61 6c t in between cal
12c20 6c 73 20 74 6f 20 78 42 65 67 69 6e 28 29 20 61 ls to xBegin() a
12c30 6e 64 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f nd .. ///
12c40 20 65 69 74 68 65 72 20 78 43 6f 6d 6d 69 74 28 either xCommit(
12c50 29 20 6f 72 20 78 52 6f 6c 6c 62 61 63 6b 28 29 ) or xRollback()
12c60 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c ... /// <
12c70 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 /para>..
12c80 2f 2f 2f 20 3c 2f 73 75 6d 6d 61 72 79 3e 0d 0a /// </summary>..
12c90 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 /// <par
12ca0 61 6d 20 6e 61 6d 65 3d 22 70 56 74 61 62 22 3e am name="pVtab">
12cb0 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 54 68 .. /// Th
12cc0 65 20 6e 61 74 69 76 65 20 70 6f 69 6e 74 65 72 e native pointer
12cd0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
12ce0 76 74 61 62 20 64 65 72 69 76 65 64 20 73 74 72 vtab derived str
12cf0 75 63 74 75 72 65 2e 0d 0a 20 20 20 20 20 20 20 ucture...
12d00 20 2f 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 /// </param>..
12d10 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 /// <para
12d20 6d 20 6e 61 6d 65 3d 22 69 53 61 76 65 70 6f 69 m name="iSavepoi
12d30 6e 74 22 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f nt">.. //
12d40 2f 20 54 68 69 73 20 69 73 20 61 6e 20 69 6e 74 / This is an int
12d50 65 67 65 72 20 69 64 65 6e 74 69 66 69 65 72 20 eger identifier
12d60 75 6e 64 65 72 20 77 68 69 63 68 20 74 68 65 20 under which the
12d70 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 the current stat
12d80 65 20 6f 66 0d 0a 20 20 20 20 20 20 20 20 2f 2f e of.. //
12d90 2f 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 / the virtual ta
12da0 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 73 61 ble should be sa
12db0 76 65 64 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ved... //
12dc0 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 20 / </param>..
12dd0 20 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72 6e 73 /// <returns
12de0 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 >.. /// A
12df0 20 73 74 61 6e 64 61 72 64 20 53 51 4c 69 74 65 standard SQLite
12e00 20 72 65 74 75 72 6e 20 63 6f 64 65 2e 0d 0a 20 return code...
12e10 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72 65 74 /// </ret
12e20 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 53 urns>.. S
12e30 51 4c 69 74 65 45 72 72 6f 72 43 6f 64 65 20 78 QLiteErrorCode x
12e40 53 61 76 65 70 6f 69 6e 74 28 0d 0a 20 20 20 20 Savepoint(..
12e50 20 20 20 20 20 20 20 20 49 6e 74 50 74 72 20 70 IntPtr p
12e60 56 74 61 62 2c 0d 0a 20 20 20 20 20 20 20 20 20 Vtab,..
12e70 20 20 20 69 6e 74 20 69 53 61 76 65 70 6f 69 6e int iSavepoin
12e80 74 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 29 t.. )
12e90 3b 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ;.... ///
12ea0 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
12eb0 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
12ec0 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
12ed0 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
12ee0 2f 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 20 20 20 20 ////....
12ef0 2f 2f 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20 /// <summary>..
12f00 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 /// <para
12f10 3e 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20 ><code>..
12f20 20 2f 2f 2f 20 69 6e 74 20 28 2a 78 53 61 76 65 /// int (*xSave
12f30 70 6f 69 6e 74 29 28 73 71 6c 69 74 65 33 5f 76 point)(sqlite3_v
12f40 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 29 tab *pVtab, int)
12f50 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 ;.. /// i
12f60 6e 74 20 28 2a 78 52 65 6c 65 61 73 65 29 28 73 nt (*xRelease)(s
12f70 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 qlite3_vtab *pVt
12f80 61 62 2c 20 69 6e 74 29 3b 0d 0a 20 20 20 20 20 ab, int);..
12f90 20 20 20 2f 2f 2f 20 69 6e 74 20 28 2a 78 52 6f /// int (*xRo
12fa0 6c 6c 62 61 63 6b 54 6f 29 28 73 71 6c 69 74 65 llbackTo)(sqlite
12fb0 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69 3_vtab *pVtab, i
12fc0 6e 74 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f nt);.. //
12fd0 2f 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e / </code></para>
12fe0 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 .. /// <p
12ff0 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ara>.. //
13000 2f 20 54 68 65 73 65 20 6d 65 74 68 6f 64 73 20 / These methods
13010 70 72 6f 76 69 64 65 20 74 68 65 20 76 69 72 74 provide the virt
13020 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d ual table implem
13030 65 6e 74 61 74 69 6f 6e 20 61 6e 20 6f 70 70 6f entation an oppo
13040 72 74 75 6e 69 74 79 20 74 6f 0d 0a 20 20 20 20 rtunity to..
13050 20 20 20 20 2f 2f 2f 20 69 6d 70 6c 65 6d 65 6e /// implemen
13060 74 20 6e 65 73 74 65 64 20 74 72 61 6e 73 61 63 t nested transac
13070 74 69 6f 6e 73 2e 20 20 54 68 65 79 20 61 72 65 tions. They are
13080 20 61 6c 77 61 79 73 20 6f 70 74 69 6f 6e 61 6c always optional
13090 20 61 6e 64 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 and will only b
130a0 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 63 e.. /// c
130b0 61 6c 6c 65 64 20 69 6e 20 53 51 4c 69 74 65 20 alled in SQLite
130c0 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 20 28 32 version 3.7.7 (2
130d0 30 31 31 2d 30 36 2d 32 33 29 20 61 6e 64 20 6c 011-06-23) and l
130e0 61 74 65 72 2e 0d 0a 20 20 20 20 20 20 20 20 2f ater... /
130f0 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 // </para>..
13100 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a /// <para>..
13110 20 20 20 20 20 20 20 20 2f 2f 2f 20 57 68 65 6e /// When
13120 20 78 53 61 76 65 70 6f 69 6e 74 28 58 2c 4e 29 xSavepoint(X,N)
13130 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 61 is invoked, tha
13140 74 20 69 73 20 61 20 73 69 67 6e 61 6c 20 74 6f t is a signal to
13150 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 the virtual tab
13160 6c 65 20 58 0d 0a 20 20 20 20 20 20 20 20 2f 2f le X.. //
13170 2f 20 74 68 61 74 20 69 74 20 73 68 6f 75 6c 64 / that it should
13180 20 73 61 76 65 20 69 74 73 20 63 75 72 72 65 6e save its curren
13190 74 20 73 74 61 74 65 20 61 73 20 73 61 76 65 70 t state as savep
131a0 6f 69 6e 74 20 4e 2e 20 20 0d 0a 20 20 20 20 20 oint N. ..
131b0 20 20 20 2f 2f 2f 20 41 20 73 75 62 73 65 71 75 /// A subsequ
131c0 65 6e 74 20 63 61 6c 6c 0d 0a 20 20 20 20 20 20 ent call..
131d0 20 20 2f 2f 2f 20 74 6f 20 78 52 6f 6c 6c 62 61 /// to xRollba
131e0 63 6b 54 6f 28 58 2c 52 29 20 6d 65 61 6e 73 20 ckTo(X,R) means
131f0 74 68 61 74 20 74 68 65 20 73 74 61 74 65 20 6f that the state o
13200 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 f the virtual ta
13210 62 6c 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 ble should retur
13220 6e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 n.. /// t
13230 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 77 68 o what it was wh
13240 65 6e 20 78 53 61 76 65 70 6f 69 6e 74 28 58 2c en xSavepoint(X,
13250 52 29 20 77 61 73 20 6c 61 73 74 20 63 61 6c 6c R) was last call
13260 65 64 2e 20 20 0d 0a 20 20 20 20 20 20 20 20 2f ed. .. /
13270 2f 2f 20 54 68 65 20 63 61 6c 6c 0d 0a 20 20 20 // The call..
13280 20 20 20 20 20 2f 2f 2f 20 74 6f 20 78 52 6f 6c /// to xRol
13290 6c 62 61 63 6b 54 6f 28 58 2c 52 29 20 77 69 6c lbackTo(X,R) wil
132a0 6c 20 69 6e 76 61 6c 69 64 61 74 65 20 61 6c 6c l invalidate all
132b0 20 73 61 76 65 70 6f 69 6e 74 73 20 77 69 74 68 savepoints with
132c0 20 4e 3e 52 3b 20 6e 6f 6e 65 20 6f 66 20 74 68 N>R; none of th
132d0 65 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 e.. /// i
132e0 6e 76 61 6c 69 64 65 64 20 73 61 76 65 70 6f 69 nvalided savepoi
132f0 6e 74 73 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c nts will be roll
13300 65 64 20 62 61 63 6b 20 6f 72 20 72 65 6c 65 61 ed back or relea
13310 73 65 64 20 77 69 74 68 6f 75 74 20 66 69 72 73 sed without firs
13320 74 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 62 t.. /// b
13330 65 69 6e 67 20 72 65 69 6e 69 74 69 61 6c 69 7a eing reinitializ
13340 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 ed by a call to
13350 78 53 61 76 65 70 6f 69 6e 74 28 29 2e 20 20 0d xSavepoint(). .
13360 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 20 63 . /// A c
13370 61 6c 6c 20 74 6f 20 78 52 65 6c 65 61 73 65 28 all to xRelease(
13380 58 2c 4d 29 20 69 6e 76 61 6c 69 64 61 74 65 73 X,M) invalidates
13390 20 61 6c 6c 20 73 61 76 65 70 6f 69 6e 74 73 20 all savepoints
133a0 77 68 65 72 65 20 4e 3e 3d 4d 2e 0d 0a 20 20 20 where N>=M...
133b0 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e /// </para>
133c0 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 .. /// <p
133d0 61 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ara>.. //
133e0 2f 20 4e 6f 6e 65 20 6f 66 20 74 68 65 20 78 53 / None of the xS
133f0 61 76 65 70 6f 69 6e 74 28 29 2c 20 78 52 65 6c avepoint(), xRel
13400 65 61 73 65 28 29 2c 20 6f 72 20 78 52 6f 6c 6c ease(), or xRoll
13410 62 61 63 6b 54 6f 28 29 20 6d 65 74 68 6f 64 73 backTo() methods
13420 20 77 69 6c 6c 20 65 76 65 72 0d 0a 20 20 20 20 will ever..
13430 20 20 20 20 2f 2f 2f 20 62 65 20 63 61 6c 6c 65 /// be calle
13440 64 20 65 78 63 65 70 74 20 69 6e 20 62 65 74 77 d except in betw
13450 65 65 6e 20 63 61 6c 6c 73 20 74 6f 20 78 42 65 een calls to xBe
13460 67 69 6e 28 29 20 61 6e 64 20 0d 0a 20 20 20 20 gin() and ..
13470 20 20 20 20 2f 2f 2f 20 65 69 74 68 65 72 20 78 /// either x
13480 43 6f 6d 6d 69 74 28 29 20 6f 72 20 78 52 6f 6c Commit() or xRol
13490 6c 62 61 63 6b 28 29 2e 0d 0a 20 20 20 20 20 20 lback()...
134a0 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 /// </para>..
134b0 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d /// </sum
134c0 6d 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f mary>.. /
134d0 2f 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 // <param name="
134e0 70 56 74 61 62 22 3e 0d 0a 20 20 20 20 20 20 20 pVtab">..
134f0 20 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76 65 20 /// The native
13500 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 pointer to the s
13510 71 6c 69 74 65 33 5f 76 74 61 62 20 64 65 72 69 qlite3_vtab deri
13520 76 65 64 20 73 74 72 75 63 74 75 72 65 2e 0d 0a ved structure...
13530 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 /// </pa
13540 72 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ram>.. //
13550 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 69 / <param name="i
13560 53 61 76 65 70 6f 69 6e 74 22 3e 0d 0a 20 20 20 Savepoint">..
13570 20 20 20 20 20 2f 2f 2f 20 54 68 69 73 20 69 73 /// This is
13580 20 61 6e 20 69 6e 74 65 67 65 72 20 75 73 65 64 an integer used
13590 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 to indicate tha
135a0 74 20 61 6e 79 20 73 61 76 65 64 20 73 74 61 74 t any saved stat
135b0 65 73 20 77 69 74 68 20 61 6e 0d 0a 20 20 20 20 es with an..
135c0 20 20 20 20 2f 2f 2f 20 69 64 65 6e 74 69 66 69 /// identifi
135d0 65 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 er greater than
135e0 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 69 73 or equal to this
135f0 20 73 68 6f 75 6c 64 20 62 65 20 64 65 6c 65 74 should be delet
13600 65 64 20 62 79 20 74 68 65 0d 0a 20 20 20 20 20 ed by the..
13610 20 20 20 2f 2f 2f 20 76 69 72 74 75 61 6c 20 74 /// virtual t
13620 61 62 6c 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f able... /
13630 2f 2f 20 3c 2f 70 61 72 61 6d 3e 0d 0a 20 20 20 // </param>..
13640 20 20 20 20 20 2f 2f 2f 20 3c 72 65 74 75 72 6e /// <return
13650 73 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 s>.. ///
13660 41 20 73 74 61 6e 64 61 72 64 20 53 51 4c 69 74 A standard SQLit
13670 65 20 72 65 74 75 72 6e 20 63 6f 64 65 2e 0d 0a e return code...
13680 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 72 65 /// </re
13690 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 20 20 20 turns>..
136a0 53 51 4c 69 74 65 45 72 72 6f 72 43 6f 64 65 20 SQLiteErrorCode
136b0 78 52 65 6c 65 61 73 65 28 0d 0a 20 20 20 20 20 xRelease(..
136c0 20 20 20 20 20 20 20 49 6e 74 50 74 72 20 70 56 IntPtr pV
136d0 74 61 62 2c 0d 0a 20 20 20 20 20 20 20 20 20 20 tab,..
136e0 20 20 69 6e 74 20 69 53 61 76 65 70 6f 69 6e 74 int iSavepoint
136f0 0d 0a 20 20 20 20 20 20 20 20 20 20 20 20 29 3b .. );
13700 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 2f .... ////
13710 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
13720 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
13730 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
13740 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f 2f ////////////////
13750 2f 2f 2f 0d 0a 0d 0a 20 20 20 20 20 20 20 20 2f ///.... /
13760 2f 2f 20 3c 73 75 6d 6d 61 72 79 3e 0d 0a 20 20 // <summary>..
13770 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e /// <para>
13780 3c 63 6f 64 65 3e 0d 0a 20 20 20 20 20 20 20 20 <code>..
13790 2f 2f 2f 20 69 6e 74 20 28 2a 78 53 61 76 65 70 /// int (*xSavep
137a0 6f 69 6e 74 29 28 73 71 6c 69 74 65 33 5f 76 74 oint)(sqlite3_vt
137b0 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 29 3b ab *pVtab, int);
137c0 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e .. /// in
137d0 74 20 28 2a 78 52 65 6c 65 61 73 65 29 28 73 71 t (*xRelease)(sq
137e0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 lite3_vtab *pVta
137f0 62 2c 20 69 6e 74 29 3b 0d 0a 20 20 20 20 20 20 b, int);..
13800 20 20 2f 2f 2f 20 69 6e 74 20 28 2a 78 52 6f 6c /// int (*xRol
13810 6c 62 61 63 6b 54 6f 29 28 73 71 6c 69 74 65 33 lbackTo)(sqlite3
13820 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e _vtab *pVtab, in
13830 74 29 3b 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f t);.. ///
13840 20 3c 2f 63 6f 64 65 3e 3c 2f 70 61 72 61 3e 0d </code></para>.
13850 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 . /// <pa
13860 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ra>.. ///
13870 20 54 68 65 73 65 20 6d 65 74 68 6f 64 73 20 70 These methods p
13880 72 6f 76 69 64 65 20 74 68 65 20 76 69 72 74 75 rovide the virtu
13890 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 al table impleme
138a0 6e 74 61 74 69 6f 6e 20 61 6e 20 6f 70 70 6f 72 ntation an oppor
138b0 74 75 6e 69 74 79 20 74 6f 0d 0a 20 20 20 20 20 tunity to..
138c0 20 20 20 2f 2f 2f 20 69 6d 70 6c 65 6d 65 6e 74 /// implement
138d0 20 6e 65 73 74 65 64 20 74 72 61 6e 73 61 63 74 nested transact
138e0 69 6f 6e 73 2e 20 20 54 68 65 79 20 61 72 65 20 ions. They are
138f0 61 6c 77 61 79 73 20 6f 70 74 69 6f 6e 61 6c 20 always optional
13900 61 6e 64 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 and will only be
13910 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 63 61 .. /// ca
13920 6c 6c 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 lled in SQLite v
13930 65 72 73 69 6f 6e 20 33 2e 37 2e 37 20 28 32 30 ersion 3.7.7 (20
13940 31 31 2d 30 36 2d 32 33 29 20 61 6e 64 20 6c 61 11-06-23) and la
13950 74 65 72 2e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ter... //
13960 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 20 20 20 / </para>..
13970 20 20 20 2f 2f 2f 20 3c 70 61 72 61 3e 0d 0a 20 /// <para>..
13980 20 20 20 20 20 20 20 2f 2f 2f 20 57 68 65 6e 20 /// When
13990 78 53 61 76 65 70 6f 69 6e 74 28 58 2c 4e 29 20 xSavepoint(X,N)
139a0 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 61 74 is invoked, that
139b0 20 69 73 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 is a signal to
139c0 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c the virtual tabl
139d0 65 20 58 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f e X.. ///
139e0 20 74 68 61 74 20 69 74 20 73 68 6f 75 6c 64 20 that it should
139f0 73 61 76 65 20 69 74 73 20 63 75 72 72 65 6e 74 save its current
13a00 20 73 74 61 74 65 20 61 73 20 73 61 76 65 70 6f state as savepo
13a10 69 6e 74 20 4e 2e 20 20 0d 0a 20 20 20 20 20 20 int N. ..
13a20 20 20 2f 2f 2f 20 41 20 73 75 62 73 65 71 75 65 /// A subseque
13a30 6e 74 20 63 61 6c 6c 0d 0a 20 20 20 20 20 20 20 nt call..
13a40 20 2f 2f 2f 20 74 6f 20 78 52 6f 6c 6c 62 61 63 /// to xRollbac
13a50 6b 54 6f 28 58 2c 52 29 20 6d 65 61 6e 73 20 74 kTo(X,R) means t
13a60 68 61 74 20 74 68 65 20 73 74 61 74 65 20 6f 66 hat the state of
13a70 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 the virtual tab
13a80 6c 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e le should return
13a90 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 74 6f .. /// to
13aa0 20 77 68 61 74 20 69 74 20 77 61 73 20 77 68 65 what it was whe
13ab0 6e 20 78 53 61 76 65 70 6f 69 6e 74 28 58 2c 52 n xSavepoint(X,R
13ac0 29 20 77 61 73 20 6c 61 73 74 20 63 61 6c 6c 65 ) was last calle
13ad0 64 2e 20 20 0d 0a 20 20 20 20 20 20 20 20 2f 2f d. .. //
13ae0 2f 20 54 68 65 20 63 61 6c 6c 0d 0a 20 20 20 20 / The call..
13af0 20 20 20 20 2f 2f 2f 20 74 6f 20 78 52 6f 6c 6c /// to xRoll
13b00 62 61 63 6b 54 6f 28 58 2c 52 29 20 77 69 6c 6c backTo(X,R) will
13b10 20 69 6e 76 61 6c 69 64 61 74 65 20 61 6c 6c 20 invalidate all
13b20 73 61 76 65 70 6f 69 6e 74 73 20 77 69 74 68 20 savepoints with
13b30 4e 3e 52 3b 20 6e 6f 6e 65 20 6f 66 20 74 68 65 N>R; none of the
13b40 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 69 6e .. /// in
13b50 76 61 6c 69 64 65 64 20 73 61 76 65 70 6f 69 6e valided savepoin
13b60 74 73 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 ts will be rolle
13b70 64 20 62 61 63 6b 20 6f 72 20 72 65 6c 65 61 73 d back or releas
13b80 65 64 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 ed without first
13b90 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 62 65 .. /// be
13ba0 69 6e 67 20 72 65 69 6e 69 74 69 61 6c 69 7a 65 ing reinitialize
13bb0 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 78 d by a call to x
13bc0 53 61 76 65 70 6f 69 6e 74 28 29 2e 20 20 0d 0a Savepoint(). ..
13bd0 20 20 20 20 20 20 20 20 2f 2f 2f 20 41 20 63 61 /// A ca
13be0 6c 6c 20 74 6f 20 78 52 65 6c 65 61 73 65 28 58 ll to xRelease(X
13bf0 2c 4d 29 20 69 6e 76 61 6c 69 64 61 74 65 73 20 ,M) invalidates
13c00 61 6c 6c 20 73 61 76 65 70 6f 69 6e 74 73 20 77 all savepoints w
13c10 68 65 72 65 20 4e 3e 3d 4d 2e 0d 0a 20 20 20 20 here N>=M...
13c20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d /// </para>.
13c30 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 3c 70 61 . /// <pa
13c40 72 61 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f ra>.. ///
13c50 20 4e 6f 6e 65 20 6f 66 20 74 68 65 20 78 53 61 None of the xSa
13c60 76 65 70 6f 69 6e 74 28 29 2c 20 78 52 65 6c 65 vepoint(), xRele
13c70 61 73 65 28 29 2c 20 6f 72 20 78 52 6f 6c 6c 62 ase(), or xRollb
13c80 61 63 6b 54 6f 28 29 20 6d 65 74 68 6f 64 73 20 ackTo() methods
13c90 77 69 6c 6c 20 65 76 65 72 0d 0a 20 20 20 20 20 will ever..
13ca0 20 20 20 2f 2f 2f 20 62 65 20 63 61 6c 6c 65 64 /// be called
13cb0 20 65 78 63 65 70 74 20 69 6e 20 62 65 74 77 65 except in betwe
13cc0 65 6e 20 63 61 6c 6c 73 20 74 6f 20 78 42 65 67 en calls to xBeg
13cd0 69 6e 28 29 20 61 6e 64 20 0d 0a 20 20 20 20 20 in() and ..
13ce0 20 20 20 2f 2f 2f 20 65 69 74 68 65 72 20 78 43 /// either xC
13cf0 6f 6d 6d 69 74 28 29 20 6f 72 20 78 52 6f 6c 6c ommit() or xRoll
13d00 62 61 63 6b 28 29 2e 0d 0a 20 20 20 20 20 20 20 back()...
13d10 20 2f 2f 2f 20 3c 2f 70 61 72 61 3e 0d 0a 20 20 /// </para>..
13d20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 73 75 6d 6d /// </summ
13d30 61 72 79 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f ary>.. //
13d40 2f 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 70 / <param name="p
13d50 56 74 61 62 22 3e 0d 0a 20 20 20 20 20 20 20 20 Vtab">..
13d60 2f 2f 2f 20 54 68 65 20 6e 61 74 69 76 65 20 70 /// The native p
13d70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 71 ointer to the sq
13d80 6c 69 74 65 33 5f 76 74 61 62 20 64 65 72 69 76 lite3_vtab deriv
13d90 65 64 20 73 74 72 75 63 74 75 72 65 2e 0d 0a 20 ed structure...
13da0 20 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 /// </par
13db0 61 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f am>.. ///
13dc0 20 3c 70 61 72 61 6d 20 6e 61 6d 65 3d 22 69 53 <param name="iS
13dd0 61 76 65 70 6f 69 6e 74 22 3e 0d 0a 20 20 20 20 avepoint">..
13de0 20 20 20 20 2f 2f 2f 20 54 68 69 73 20 69 73 20 /// This is
13df0 61 6e 20 69 6e 74 65 67 65 72 20 69 64 65 6e 74 an integer ident
13e00 69 66 69 65 72 20 75 73 65 64 20 74 6f 20 73 70 ifier used to sp
13e10 65 63 69 66 79 20 61 20 73 70 65 63 69 66 69 63 ecify a specific
13e20 20 73 61 76 65 64 0d 0a 20 20 20 20 20 20 20 20 saved..
13e30 2f 2f 2f 20 73 74 61 74 65 20 66 6f 72 20 74 68 /// state for th
13e40 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 e virtual table
13e50 66 6f 72 20 69 74 20 74 6f 20 72 65 73 74 6f 72 for it to restor
13e60 65 20 69 74 73 65 6c 66 20 62 61 63 6b 20 74 6f e itself back to
13e70 2c 20 77 68 69 63 68 0d 0a 20 20 20 20 20 20 20 , which..
13e80 20 2f 2f 2f 20 73 68 6f 75 6c 64 20 61 6c 73 6f /// should also
13e90 20 68 61 76 65 20 74 68 65 20 65 66 66 65 63 74 have the effect
13ea0 20 6f 66 20 64 65 6c 65 74 69 6e 67 20 61 6c 6c of deleting all
13eb0 20 73 61 76 65 64 20 73 74 61 74 65 73 20 77 69 saved states wi
13ec0 74 68 20 61 6e 0d 0a 20 20 20 20 20 20 20 20 2f th an.. /
13ed0 2f 2f 20 69 6e 74 65 67 65 72 20 69 64 65 6e 74 // integer ident
13ee0 69 66 69 65 72 20 67 72 65 61 74 65 72 20 74 68 ifier greater th
13ef0 61 6e 20 74 68 69 73 20 6f 6e 65 2e 0d 0a 20 20 an this one...
13f00 20 20 20 20 20 20 2f 2f 2f 20 3c 2f 70 61 72 61 /// </para
13f10 6d 3e 0d 0a 20 20 20 20 20 20 20 20 2f 2f 2f 20 m>.. ///
13f20 3c 72 65 74 75 72 6e 73 3e 0d 0a 20 20 20 20 20 <returns>..
13f30 20 20 20 2f 2f 2f 20 41 20 73 74 61 6e 64 61 72 /// A standar
13f40 64 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 20 d SQLite return
13f50 63 6f 64 65 2e 0d 0a 20 20 20 20 20 20 20 20 2f code... /
13f60 2f 2f 20 3c 2f 72 65 74 75 72 6e 73 3e 0d 0a 20 // </returns>..
13f70 20 20 20 20 20 20 20 53 51 4c 69 74 65 45 72 72 SQLiteErr
13f80 6f 72 43 6f 64 65 20 78 52 6f 6c 6c 62 61 63 6b orCode xRollback
13f90 54 6f 28 0d 0a 20 20 20 20 20 20 20 20 20 20 20 To(..
13fa0 20 49 6e 74 50 74 72 20 70 56 74 61 62 2c 0d 0a IntPtr pVtab,..
13fb0 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 int
13fc0 69 53 61 76 65 70 6f 69 6e 74 0d 0a 20 20 20 20 iSavepoint..
13fd0 20 20 20 20 20 20 20 20 29 3b 0d 0a 20 20 20 20 );..
13fe0 7d 0d 0a 20 20 20 20 23 65 6e 64 72 65 67 69 6f }.. #endregio
13ff0 6e 0d 0a 7d 0d 0a n..}..