0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65 /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69 e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20 ms copyright to
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a . In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73 , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d sing:.**.** M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 nd not evil..**
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 May you find
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20 forgiveness for
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 give others..**
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65 May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 aking more than
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68 ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65 that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73 library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70 ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43 rograms. If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63 -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64 ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69 ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20 s file, then it
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20 ite, is subject
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64 t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72 should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53 grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74 e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70 arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70 erimental". Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65 y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64 s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20 to SQLite. We
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74 do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 74 6f e changes .** to
0390: 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e experimental in
03a0: 74 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 terfaces but res
03b0: 65 72 76 65 20 74 6f 20 6d 61 6b 65 20 6d 69 6e erve to make min
03c0: 6f 72 20 63 68 61 6e 67 65 73 20 69 66 0a 2a 2a or changes if.**
03d0: 20 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d experience from
03e0: 20 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c use "in the wil
03f0: 64 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20 d" suggest such
0400: 63 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64 changes are prud
0410: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f ent..**.** The o
0420: 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 fficial C-langua
0430: 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 ge API documenta
0440: 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 tion for SQLite
0450: 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 is derived.** fr
0460: 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 om comments in t
0470: 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20 his file. This
0480: 66 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68 file is the auth
0490: 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65 oritative source
04a0: 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 .** on how SQLit
04b0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 e interfaces are
04c0: 20 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 suppose to oper
04d0: 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e ate..**.** The n
04e0: 61 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65 ame of this file
04f0: 20 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61 under configura
0500: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 tion management
0510: 69 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 is "sqlite.h.in"
0520: 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c ..** The makefil
0530: 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e e makes some min
0540: 6f 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 or changes to th
0550: 69 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73 is file (such as
0560: 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 inserting.** th
0570: 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 e version number
0580: 29 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74 ) and changes it
0590: 73 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 s name to "sqlit
05a0: 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 e3.h" as.** part
05b0: 20 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72 of the build pr
05c0: 6f 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 40 28 23 ocess..**.** @(#
05d0: 29 20 24 49 64 3a 20 73 71 6c 69 74 65 2e 68 2e ) $Id: sqlite.h.
05e0: 69 6e 2c 76 20 31 2e 32 31 37 20 32 30 30 37 2f in,v 1.217 2007/
05f0: 30 36 2f 32 37 20 31 35 3a 35 33 3a 33 35 20 64 06/27 15:53:35 d
0600: 61 6e 69 65 6c 6b 31 39 37 37 20 45 78 70 20 24 anielk1977 Exp $
0610: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c .*/.#ifndef _SQL
0620: 49 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 ITE3_H_.#define
0630: 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 _SQLITE3_H_.#inc
0640: 6c 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 lude <stdarg.h>
0650: 20 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f /* Needed fo
0660: 72 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e r the definition
0670: 20 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a of va_list */..
0680: 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 /*.** Make sure
0690: 77 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 we can call this
06a0: 20 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e stuff from C++.
06b0: 0a 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c .*/.#ifdef __cpl
06c0: 75 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 usplus.extern "C
06d0: 22 20 7b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a " {.#endif../*.*
06e0: 2a 20 4d 61 6b 65 20 73 75 72 65 20 74 68 65 73 * Make sure thes
06f0: 65 20 73 79 6d 62 6f 6c 73 20 77 68 65 72 65 20 e symbols where
0700: 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 not defined by s
0710: 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 ome previous hea
0720: 64 65 72 0a 2a 2a 20 66 69 6c 65 2e 0a 2a 2f 0a der.** file..*/.
0730: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 #ifdef SQLITE_VE
0740: 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 RSION.# undef SQ
0750: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e LITE_VERSION.#en
0760: 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 dif.#ifdef SQLIT
0770: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 E_VERSION_NUMBER
0780: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f .# undef SQLITE_
0790: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 VERSION_NUMBER.#
07a0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 endif../*.** CAP
07b0: 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 I3REF: Compile-T
07c0: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 ime Library Vers
07d0: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a ion Numbers.**.*
07e0: 2a 20 54 68 65 20 76 65 72 73 69 6f 6e 20 6f 66 * The version of
07f0: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 the SQLite libr
0800: 61 72 79 20 69 73 20 63 6f 6e 74 61 69 6e 65 64 ary is contained
0810: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 2e in the sqlite3.
0820: 68 0a 2a 2a 20 68 65 61 64 65 72 20 66 69 6c 65 h.** header file
0830: 20 69 6e 20 61 20 23 64 65 66 69 6e 65 20 6e 61 in a #define na
0840: 6d 65 64 20 53 51 4c 49 54 45 5f 56 45 52 53 49 med SQLITE_VERSI
0850: 4f 4e 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f ON. The SQLITE_
0860: 56 45 52 53 49 4f 4e 0a 2a 2a 20 6d 61 63 72 6f VERSION.** macro
0870: 20 72 65 73 6f 6c 76 65 73 20 74 6f 20 61 20 73 resolves to a s
0880: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 0a tring constant..
0890: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 72 6d 61 74 **.** The format
08a0: 20 6f 66 20 74 68 65 20 76 65 72 73 69 6f 6e 20 of the version
08b0: 73 74 72 69 6e 67 20 69 73 20 22 58 2e 59 2e 5a string is "X.Y.Z
08c0: 22 2c 20 77 68 65 72 65 0a 2a 2a 20 58 20 69 73 ", where.** X is
08d0: 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69 the major versi
08e0: 6f 6e 20 6e 75 6d 62 65 72 2c 20 59 20 69 73 20 on number, Y is
08f0: 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f the minor versio
0900: 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 0a 2a n number and Z.*
0910: 2a 20 69 73 20 74 68 65 20 72 65 6c 65 61 73 65 * is the release
0920: 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 58 2e number. The X.
0930: 59 2e 5a 20 6d 69 67 68 74 20 62 65 20 66 6f 6c Y.Z might be fol
0940: 6c 6f 77 65 64 20 62 79 20 22 61 6c 70 68 61 22 lowed by "alpha"
0950: 20 6f 72 20 22 62 65 74 61 22 2e 0a 2a 2a 20 46 or "beta"..** F
0960: 6f 72 20 65 78 61 6d 70 6c 65 20 22 33 2e 31 2e or example "3.1.
0970: 31 62 65 74 61 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 1beta"..**.** Th
0980: 65 20 58 20 76 61 6c 75 65 20 69 73 20 61 6c 77 e X value is alw
0990: 61 79 73 20 33 20 69 6e 20 53 51 4c 69 74 65 2e ays 3 in SQLite.
09a0: 20 20 54 68 65 20 58 20 76 61 6c 75 65 20 6f 6e The X value on
09b0: 6c 79 20 63 68 61 6e 67 65 73 20 77 68 65 6e 0a ly changes when.
09c0: 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d ** backwards com
09d0: 70 61 74 69 62 69 6c 69 74 79 20 69 73 20 62 72 patibility is br
09e0: 6f 6b 65 6e 20 61 6e 64 20 77 65 20 69 6e 74 65 oken and we inte
09f0: 6e 64 20 74 6f 20 6e 65 76 65 72 20 62 72 65 61 nd to never brea
0a00: 6b 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 k.** backwards c
0a10: 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 54 ompatibility. T
0a20: 68 65 20 59 20 76 61 6c 75 65 20 6f 6e 6c 79 20 he Y value only
0a30: 63 68 61 6e 67 65 73 20 77 68 65 6e 0a 2a 2a 20 changes when.**
0a40: 74 68 65 72 65 20 61 72 65 20 6d 61 6a 6f 72 20 there are major
0a50: 66 65 61 74 75 72 65 20 65 6e 68 61 6e 63 65 6d feature enhancem
0a60: 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 66 6f ents that are fo
0a70: 72 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 6c rwards compatibl
0a80: 65 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 62 61 63 e.** but not bac
0a90: 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 6c kwards compatibl
0aa0: 65 2e 20 20 54 68 65 20 5a 20 76 61 6c 75 65 20 e. The Z value
0ab0: 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 77 is incremented w
0ac0: 69 74 68 0a 2a 2a 20 65 61 63 68 20 72 65 6c 65 ith.** each rele
0ad0: 61 73 65 20 62 75 74 20 72 65 73 65 74 73 20 62 ase but resets b
0ae0: 61 63 6b 20 74 6f 20 30 20 77 68 65 6e 20 59 20 ack to 0 when Y
0af0: 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 2e 0a is incremented..
0b00: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 **.** The SQLITE
0b10: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 _VERSION_NUMBER
0b20: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 69 is an integer wi
0b30: 74 68 20 74 68 65 20 76 61 6c 75 65 20 0a 2a 2a th the value .**
0b40: 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a (X*1000000 + Y*
0b50: 31 30 30 30 20 2b 20 5a 29 2e 20 46 6f 72 20 65 1000 + Z). For e
0b60: 78 61 6d 70 6c 65 2c 20 66 6f 72 20 76 65 72 73 xample, for vers
0b70: 69 6f 6e 20 22 33 2e 31 2e 31 62 65 74 61 22 2c ion "3.1.1beta",
0b80: 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 56 45 52 53 .** SQLITE_VERS
0b90: 49 4f 4e 5f 4e 55 4d 42 45 52 20 69 73 20 73 65 ION_NUMBER is se
0ba0: 74 20 74 6f 20 33 30 30 31 30 30 31 2e 20 54 6f t to 3001001. To
0bb0: 20 64 65 74 65 63 74 20 69 66 20 74 68 65 79 20 detect if they
0bc0: 61 72 65 20 75 73 69 6e 67 20 0a 2a 2a 20 76 65 are using .** ve
0bd0: 72 73 69 6f 6e 20 33 2e 31 2e 31 20 6f 72 20 67 rsion 3.1.1 or g
0be0: 72 65 61 74 65 72 20 61 74 20 63 6f 6d 70 69 6c reater at compil
0bf0: 65 20 74 69 6d 65 2c 20 70 72 6f 67 72 61 6d 73 e time, programs
0c00: 20 6d 61 79 20 75 73 65 20 74 68 65 20 74 65 73 may use the tes
0c10: 74 20 0a 2a 2a 20 28 53 51 4c 49 54 45 5f 56 45 t .** (SQLITE_VE
0c20: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 3e 3d 33 30 RSION_NUMBER>=30
0c30: 30 31 30 30 31 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 01001)..**.** Se
0c40: 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
0c50: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 20 61 _libversion()] a
0c60: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 nd [sqlite3_libv
0c70: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d ersion_number()]
0c80: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
0c90: 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 ITE_VERSION
0ca0: 20 20 20 20 22 33 2e 34 2e 30 22 0a 23 64 65 66 "3.4.0".#def
0cb0: 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 ine SQLITE_VERSI
0cc0: 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 30 34 30 30 ON_NUMBER 300400
0cd0: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 0../*.** CAPI3RE
0ce0: 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 F: Run-Time Libr
0cf0: 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 ary Version Numb
0d00: 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ers.**.** These
0d10: 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
0d20: 76 61 6c 75 65 73 20 65 71 75 69 76 61 6c 65 6e values equivalen
0d30: 74 20 74 6f 20 74 68 65 20 68 65 61 64 65 72 20 t to the header
0d40: 63 6f 6e 73 74 61 6e 74 73 0a 2a 2a 20 5b 53 51 constants.** [SQ
0d50: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 61 6e LITE_VERSION] an
0d60: 64 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f d [SQLITE_VERSIO
0d70: 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 54 68 65 20 N_NUMBER]. The
0d80: 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 0a values returned.
0d90: 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 ** by this routi
0da0: 6e 65 73 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 nes should only
0db0: 62 65 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f be different fro
0dc0: 6d 20 74 68 65 20 68 65 61 64 65 72 20 76 61 6c m the header val
0dd0: 75 65 73 0a 2a 2a 20 69 66 20 79 6f 75 20 63 6f ues.** if you co
0de0: 6d 70 69 6c 65 20 79 6f 75 72 20 70 72 6f 67 72 mpile your progr
0df0: 61 6d 20 75 73 69 6e 67 20 61 6e 20 73 71 6c 69 am using an sqli
0e00: 74 65 33 2e 68 20 68 65 61 64 65 72 20 66 72 6f te3.h header fro
0e10: 6d 20 61 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 m a.** different
0e20: 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 version of SQLi
0e30: 74 65 20 74 68 61 74 20 74 68 65 20 76 65 72 73 te that the vers
0e40: 69 6f 6e 20 6f 66 20 74 68 65 20 6c 69 62 72 61 ion of the libra
0e50: 72 79 20 79 6f 75 0a 2a 2a 20 6c 69 6e 6b 20 61 ry you.** link a
0e60: 67 61 69 6e 73 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 gainst..**.** Th
0e70: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f e sqlite3_versio
0e80: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 n[] string const
0e90: 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 ant contains the
0ea0: 20 74 65 78 74 20 6f 66 20 74 68 65 0a 2a 2a 20 text of the.**
0eb0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d [SQLITE_VERSION]
0ec0: 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 73 71 string. The sq
0ed0: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e lite3_libversion
0ee0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 () function retu
0ef0: 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 65 72 20 rns.** a poiner
0f00: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 to the sqlite3_v
0f10: 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 ersion[] string
0f20: 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 66 constant. The f
0f30: 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 73 20 70 72 unction.** is pr
0f40: 6f 76 69 64 65 64 20 66 6f 72 20 44 4c 4c 20 75 ovided for DLL u
0f50: 73 65 72 73 20 77 68 6f 20 63 61 6e 20 6f 6e 6c sers who can onl
0f60: 79 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f y access functio
0f70: 6e 73 20 61 6e 64 20 6e 6f 74 0a 2a 2a 20 63 6f ns and not.** co
0f80: 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 nstants within t
0f90: 68 65 20 44 4c 4c 2e 0a 2a 2f 0a 65 78 74 65 72 he DLL..*/.exter
0fa0: 6e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c n const char sql
0fb0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a ite3_version[];.
0fc0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 const char *sqli
0fd0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 te3_libversion(v
0fe0: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 oid);.int sqlite
0ff0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 3_libversion_num
1000: 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a ber(void);../*.*
1010: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 * CAPI3REF: Data
1020: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 base Connection
1030: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 45 61 63 Handle.**.** Eac
1040: 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61 h open SQLite da
1050: 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65 73 tabase is repres
1060: 65 6e 74 65 64 20 62 79 20 70 6f 69 6e 74 65 72 ented by pointer
1070: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 to an instance
1080: 6f 66 20 74 68 65 0a 2a 2a 20 6f 70 61 71 75 65 of the.** opaque
1090: 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 structure named
10a0: 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 "sqlite3". It
10b0: 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 is useful to thi
10c0: 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 nk of an sqlite3
10d0: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 .** pointer as a
10e0: 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b n object. The [
10f0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5d 20 69 6e sqlite3_open] in
1100: 74 65 72 66 61 63 65 20 69 73 20 69 74 73 20 63 terface is its c
1110: 6f 6e 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 6e onstructor.** an
1120: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 d [sqlite3_close
1130: 5d 20 69 73 20 69 74 73 20 64 65 73 74 72 75 63 ] is its destruc
1140: 74 6f 72 2e 20 20 54 68 65 72 65 20 61 72 65 20 tor. There are
1150: 6d 61 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 72 many other inter
1160: 66 61 63 65 73 0a 2a 2a 20 28 73 75 63 68 20 61 faces.** (such a
1170: 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 s [sqlite3_prepa
1180: 72 65 5f 76 32 5d 2c 20 5b 73 71 6c 69 74 65 33 re_v2], [sqlite3
1190: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
11a0: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 ], and.** [sqlit
11b0: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d e3_busy_timeout]
11c0: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 to name but thr
11d0: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 ee) that are met
11e0: 68 6f 64 73 20 6f 6e 20 74 68 69 73 0a 2a 2a 20 hods on this.**
11f0: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 object..*/.typed
1200: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
1210: 33 20 73 71 6c 69 74 65 33 3b 0a 0a 0a 2f 2a 0a 3 sqlite3;.../*.
1220: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d ** CAPI3REF: 64-
1230: 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 Bit Integer Type
1240: 73 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 63 6f 6d s.**.** Some com
1250: 70 69 6c 65 72 73 20 64 6f 20 6e 6f 74 20 73 75 pilers do not su
1260: 70 70 6f 72 74 20 74 68 65 20 22 6c 6f 6e 67 20 pport the "long
1270: 6c 6f 6e 67 22 20 64 61 74 61 74 79 70 65 2e 20 long" datatype.
1280: 20 53 6f 20 77 65 20 68 61 76 65 0a 2a 2a 20 74 So we have.** t
1290: 6f 20 64 6f 20 63 6f 6d 70 69 6c 65 72 2d 73 70 o do compiler-sp
12a0: 65 63 69 66 69 63 20 74 79 70 65 64 65 66 73 20 ecific typedefs
12b0: 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 for 64-bit signe
12c0: 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 d and unsigned i
12d0: 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4d ntegers..**.** M
12e0: 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 any SQLite inter
12f0: 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 face functions r
1300: 65 71 75 69 72 65 20 61 20 36 34 2d 62 69 74 20 equire a 64-bit
1310: 69 6e 74 65 67 65 72 20 61 72 67 75 6d 65 6e 74 integer argument
1320: 73 2e 0a 2a 2a 20 54 68 6f 73 65 20 69 6e 74 65 s..** Those inte
1330: 72 66 61 63 65 73 20 61 72 65 20 64 65 63 6c 61 rfaces are decla
1340: 72 65 64 20 75 73 69 6e 67 20 74 68 69 73 20 74 red using this t
1350: 79 70 65 64 65 66 2e 0a 2a 2f 0a 23 69 66 64 65 ypedef..*/.#ifde
1360: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 f SQLITE_INT64_T
1370: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 YPE. typedef SQ
1380: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 LITE_INT64_TYPE
1390: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 sqlite_int64;.
13a0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 typedef unsigned
13b0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 SQLITE_INT64_TY
13c0: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 PE sqlite_uint64
13d0: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 ;.#elif defined(
13e0: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 _MSC_VER) || def
13f0: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f ined(__BORLANDC_
1400: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 _). typedef __i
1410: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 nt64 sqlite_int6
1420: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 4;. typedef uns
1430: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 igned __int64 sq
1440: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c lite_uint64;.#el
1450: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e se. typedef lon
1460: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 g long int sqlit
1470: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 e_int64;. typed
1480: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 ef unsigned long
1490: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 long int sqlite
14a0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a _uint64;.#endif.
14b0: 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c ./*.** If compil
14c0: 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73 ing for a proces
14d0: 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66 sor that lacks f
14e0: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 loating point su
14f0: 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 pport,.** substi
1500: 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72 tute integer for
1510: 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 0a floating-point.
1520: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 */.#ifdef SQLITE
1530: 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 _OMIT_FLOATING_P
1540: 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f OINT.# define do
1550: 75 62 6c 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 uble sqlite_int6
1560: 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4.#endif../*.**
1570: 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e CAPI3REF: Closin
1580: 67 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e g A Database Con
1590: 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 43 61 nection.**.** Ca
15a0: 6c 6c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e ll this function
15b0: 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 with a pointer
15c0: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 to a structure t
15d0: 68 61 74 20 77 61 73 20 70 72 65 76 69 6f 75 73 hat was previous
15e0: 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 ly.** returned f
15f0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 rom [sqlite3_ope
1600: 6e 28 29 5d 20 61 6e 64 20 74 68 65 20 63 6f 72 n()] and the cor
1610: 72 65 73 70 6f 6e 64 69 6e 67 20 64 61 74 61 62 responding datab
1620: 61 73 65 20 77 69 6c 6c 20 62 79 0a 2a 2a 20 63 ase will by.** c
1630: 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6c 6c losed..**.** All
1640: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
1650: 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 5b prepared using [
1660: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
1670: 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c v2()] or.** [sql
1680: 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
1690: 32 28 29 5d 20 6d 75 73 74 20 62 65 20 64 65 73 2()] must be des
16a0: 74 72 6f 79 65 64 20 75 73 69 6e 67 20 5b 73 71 troyed using [sq
16b0: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
16c0: 5d 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 69 73 ].** before this
16d0: 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c routine is call
16e0: 65 64 2e 20 4f 74 68 65 72 77 69 73 65 2c 20 53 ed. Otherwise, S
16f0: 51 4c 49 54 45 5f 42 55 53 59 20 69 73 20 72 65 QLITE_BUSY is re
1700: 74 75 72 6e 65 64 20 61 6e 64 20 74 68 65 0a 2a turned and the.*
1710: 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
1720: 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 6f 70 ction remains op
1730: 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 en..*/.int sqlit
1740: 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 e3_close(sqlite3
1750: 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 *);../*.** The
1760: 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 type for a callb
1770: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a ack function..**
1780: 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 This is legacy
1790: 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 and deprecated.
17a0: 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 It is included
17b0: 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a for historical.*
17c0: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 * compatibility
17d0: 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d and is not docum
17e0: 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 ented..*/.typede
17f0: 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f f int (*sqlite3_
1800: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c callback)(void*,
1810: 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 int,char**, char
1820: 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 **);../*.** CAPI
1830: 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 3REF: One-Step Q
1840: 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 uery Execution I
1850: 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 nterface.**.** T
1860: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 his interface is
1870: 20 75 73 65 64 20 74 6f 20 64 6f 20 61 20 6f 6e used to do a on
1880: 65 2d 74 69 6d 65 20 65 76 61 6c 75 61 74 61 74 e-time evaluatat
1890: 69 6f 6e 20 6f 66 20 7a 65 72 6f 0a 2a 2a 20 6f ion of zero.** o
18a0: 72 20 6d 6f 72 65 20 53 51 4c 20 73 74 61 74 65 r more SQL state
18b0: 6d 65 6e 74 73 2e 20 20 55 54 46 2d 38 20 74 65 ments. UTF-8 te
18c0: 78 74 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 xt of the SQL st
18d0: 61 74 65 6d 65 6e 74 73 20 74 6f 0a 2a 2a 20 62 atements to.** b
18e0: 65 20 65 76 61 6c 75 74 65 64 20 69 73 20 70 61 e evaluted is pa
18f0: 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 20 73 ssed in as the s
1900: 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e econd parameter.
1910: 20 20 54 68 65 20 73 74 61 74 65 6d 65 6e 74 73 The statements
1920: 0a 2a 2a 20 61 72 65 20 70 72 65 70 61 72 65 64 .** are prepared
1930: 20 6f 6e 65 20 62 79 20 6f 6e 65 20 75 73 69 6e one by one usin
1940: 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 g [sqlite3_prepa
1950: 72 65 28 29 5d 2c 20 65 76 61 6c 75 61 74 65 64 re()], evaluated
1960: 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 .** using [sqlit
1970: 65 33 5f 73 74 65 70 28 29 5d 2c 20 74 68 65 6e e3_step()], then
1980: 20 64 65 73 74 72 6f 79 65 64 20 75 73 69 6e 67 destroyed using
1990: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
19a0: 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 ze()]..**.** If
19b0: 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 one or more of t
19c0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
19d0: 73 20 61 72 65 20 71 75 65 72 69 65 73 2c 20 74 s are queries, t
19e0: 68 65 6e 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 62 hen.** the callb
19f0: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 70 65 ack function spe
1a00: 63 69 66 69 65 64 20 62 79 20 74 68 65 20 33 72 cified by the 3r
1a10: 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a d parameter is.*
1a20: 2a 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 * invoked once f
1a30: 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20 74 or each row of t
1a40: 68 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 2e he query result.
1a50: 20 20 54 68 69 73 20 63 61 6c 6c 62 61 63 6b 0a This callback.
1a60: 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 72 6d 61 6c ** should normal
1a70: 6c 79 20 72 65 74 75 72 6e 20 30 2e 20 20 49 66 ly return 0. If
1a80: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 the callback re
1a90: 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f turns a non-zero
1aa0: 0a 2a 2a 20 76 61 6c 75 65 20 74 68 65 6e 20 74 .** value then t
1ab0: 68 65 20 71 75 65 72 79 20 69 73 20 61 62 6f 72 he query is abor
1ac0: 74 65 64 2c 20 61 6c 6c 20 73 75 62 73 65 71 75 ted, all subsequ
1ad0: 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ent SQL statemen
1ae0: 74 73 0a 2a 2a 20 61 72 65 20 73 6b 69 70 70 65 ts.** are skippe
1af0: 64 20 61 6e 64 20 74 68 65 20 73 71 6c 69 74 65 d and the sqlite
1b00: 33 5f 65 78 65 63 28 29 20 66 75 6e 63 74 69 6f 3_exec() functio
1b10: 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 53 51 n returns the SQ
1b20: 4c 49 54 45 5f 41 42 4f 52 54 2e 0a 2a 2a 0a 2a LITE_ABORT..**.*
1b30: 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 6d 65 * The 4th parame
1b40: 74 65 72 20 74 6f 20 74 68 69 73 20 69 6e 74 65 ter to this inte
1b50: 72 66 61 63 65 20 69 73 20 61 6e 20 61 72 62 69 rface is an arbi
1b60: 74 72 61 72 79 20 70 6f 69 6e 74 65 72 20 74 68 trary pointer th
1b70: 61 74 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 at is.** passed
1b80: 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63 through to the c
1b90: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
1ba0: 20 61 73 20 69 74 73 20 66 69 72 73 74 20 70 61 as its first pa
1bb0: 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 rameter..**.** T
1bc0: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 he 2nd parameter
1bd0: 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
1be0: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 function is the
1bf0: 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 6f number of.** co
1c00: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 71 75 65 lumns in the que
1c10: 72 79 20 72 65 73 75 6c 74 2e 20 20 54 68 65 20 ry result. The
1c20: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 3rd parameter to
1c30: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a the callback.**
1c40: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 is an array of
1c50: 73 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e 67 20 strings holding
1c60: 74 68 65 20 76 61 6c 75 65 73 20 66 6f 72 20 65 the values for e
1c70: 61 63 68 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 73 ach column.** as
1c80: 20 65 78 74 72 61 63 74 65 64 20 75 73 69 6e 67 extracted using
1c90: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
1ca0: 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 _text()]..** The
1cb0: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 4th parameter t
1cc0: 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 o the callback i
1cd0: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 73 74 s an array of st
1ce0: 72 69 6e 67 73 0a 2a 2a 20 6f 62 74 61 69 6e 65 rings.** obtaine
1cf0: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 d using [sqlite3
1d00: 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 _column_name()]
1d10: 61 6e 64 20 68 6f 6c 64 69 6e 67 0a 2a 2a 20 74 and holding.** t
1d20: 68 65 20 6e 61 6d 65 73 20 6f 66 20 65 61 63 68 he names of each
1d30: 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 column..**.** T
1d40: 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 he callback func
1d50: 74 69 6f 6e 20 6d 61 79 20 62 65 20 4e 55 4c 4c tion may be NULL
1d60: 2c 20 65 76 65 6e 20 66 6f 72 20 71 75 65 72 69 , even for queri
1d70: 65 73 2e 20 20 41 20 4e 55 4c 4c 0a 2a 2a 20 63 es. A NULL.** c
1d80: 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 61 allback is not a
1d90: 6e 20 65 72 72 6f 72 2e 20 20 49 74 20 6a 75 73 n error. It jus
1da0: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 6e 6f 20 t means that no
1db0: 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 77 69 6c 6c callback.** will
1dc0: 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a be invoked..**.
1dd0: 2a 2a 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f ** If an error o
1de0: 63 63 75 72 73 20 77 68 69 6c 65 20 70 61 72 73 ccurs while pars
1df0: 69 6e 67 20 6f 72 20 65 76 61 6c 75 61 74 69 6e ing or evaluatin
1e00: 67 20 74 68 65 20 53 51 4c 20 28 62 75 74 0a 2a g the SQL (but.*
1e10: 2a 20 6e 6f 74 20 77 68 69 6c 65 20 65 78 65 63 * not while exec
1e20: 75 74 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 uting the callba
1e30: 63 6b 29 20 74 68 65 6e 20 61 6e 20 61 70 70 72 ck) then an appr
1e40: 6f 70 72 69 61 74 65 20 65 72 72 6f 72 0a 2a 2a opriate error.**
1e50: 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 74 message is writ
1e60: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 ten into memory
1e70: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 obtained from [s
1e80: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
1e90: 20 61 6e 64 0a 2a 2a 20 2a 65 72 72 6d 73 67 20 and.** *errmsg
1ea0: 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 is made to point
1eb0: 20 74 6f 20 74 68 61 74 20 6d 65 73 73 61 67 65 to that message
1ec0: 2e 20 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 . The calling f
1ed0: 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 73 20 72 65 unction.** is re
1ee0: 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 sponsible for fr
1ef0: 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 eeing the memory
1f00: 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 that holds the
1f10: 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 error.** message
1f20: 2e 20 20 20 55 73 65 20 5b 73 71 6c 69 74 65 33 . Use [sqlite3
1f30: 5f 66 72 65 65 28 29 5d 20 66 6f 72 20 74 68 69 _free()] for thi
1f40: 73 2e 20 20 49 66 20 65 72 72 6d 73 67 3d 3d 4e s. If errmsg==N
1f50: 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 6e 6f 20 ULL,.** then no
1f60: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 error message is
1f70: 20 65 76 65 72 20 77 72 69 74 74 65 6e 2e 0a 2a ever written..*
1f80: 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 20 *.** The return
1f90: 76 61 6c 75 65 20 69 73 20 69 73 20 53 51 4c 49 value is is SQLI
1fa0: 54 45 5f 4f 4b 20 69 66 20 74 68 65 72 65 20 61 TE_OK if there a
1fb0: 72 65 20 6e 6f 20 65 72 72 6f 72 73 20 61 6e 64 re no errors and
1fc0: 0a 2a 2a 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b .** some other [
1fd0: 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 74 75 SQLITE_OK | retu
1fe0: 72 6e 20 63 6f 64 65 5d 20 69 66 20 74 68 65 72 rn code] if ther
1ff0: 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 20 e is an error.
2000: 0a 2a 2a 20 54 68 65 20 70 61 72 74 69 63 75 6c .** The particul
2010: 61 72 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 ar return value
2020: 64 65 70 65 6e 64 73 20 6f 6e 20 74 68 65 20 74 depends on the t
2030: 79 70 65 20 6f 66 20 65 72 72 6f 72 2e 20 0a 2a ype of error. .*
2040: 2a 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 *.*/.int sqlite3
2050: 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 _exec(. sqlite3
2060: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 *,
2070: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2080: 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 /* An open d
2090: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e atabase */. con
20a0: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 st char *sql,
20b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
20c0: 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 /* SQL t
20d0: 6f 20 62 65 20 65 76 61 6c 75 74 65 64 20 2a 2f o be evaluted */
20e0: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 . int (*callbac
20f0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 k)(void*,int,cha
2100: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a r**,char**), /*
2110: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 Callback functi
2120: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 on */. void *,
2130: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2140: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2150: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 /* 1st argume
2160: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a nt to callback *
2170: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 /. char **errms
2180: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 g
2190: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
21a0: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 * Error msg writ
21b0: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a ten here */.);..
21c0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
21d0: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 Result Codes.**
21e0: 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 KEYWORDS: SQLITE
21f0: 5f 4f 4b 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 _OK.**.** Many S
2200: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 QLite functions
2210: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 return an intege
2220: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 r result code fr
2230: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e om the set shown
2240: 0a 2a 2a 20 61 62 6f 76 65 20 69 6e 20 6f 72 64 .** above in ord
2250: 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 er to indicates
2260: 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 success or failu
2270: 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 re..**.** The re
2280: 73 75 6c 74 20 63 6f 64 65 73 20 61 62 6f 76 65 sult codes above
2290: 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6f 6e are the only on
22a0: 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 es returned by S
22b0: 51 4c 69 74 65 20 69 6e 20 69 74 73 0a 2a 2a 20 QLite in its.**
22c0: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 default configur
22d0: 61 74 69 6f 6e 2e 20 20 48 6f 77 65 76 65 72 2c ation. However,
22e0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 the [sqlite3_ex
22f0: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f tended_result_co
2300: 64 65 73 28 29 5d 0a 2a 2a 20 41 50 49 20 63 61 des()].** API ca
2310: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 73 65 74 n be used to set
2320: 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a database conn
2330: 65 63 74 6f 69 6e 20 74 6f 20 72 65 74 75 72 6e ectoin to return
2340: 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 0a 2a more detailed.*
2350: 2a 20 72 65 73 75 6c 74 20 63 6f 64 65 73 2e 0a * result codes..
2360: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
2370: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 [SQLITE_IOERR_RE
2380: 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 AD | extended re
2390: 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a 2a 0a 2a sult codes].**.*
23a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
23b0: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 _OK 0
23c0: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 /* Successful
23d0: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 result */./* beg
23e0: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d inning-of-error-
23f0: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 codes */.#define
2400: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 SQLITE_ERROR
2410: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 1 /* SQL
2420: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 error or missing
2430: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 database */.#de
2440: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 fine SQLITE_INTE
2450: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 RNAL 2 /*
2460: 4e 4f 54 20 55 53 45 44 2e 20 49 6e 74 65 72 6e NOT USED. Intern
2470: 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 al logic error i
2480: 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 n SQLite */.#def
2490: 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 ine SQLITE_PERM
24a0: 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 3 /* A
24b0: 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e ccess permission
24c0: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 denied */.#defi
24d0: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 ne SQLITE_ABORT
24e0: 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 4 /* Ca
24f0: 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 llback routine r
2500: 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 equested an abor
2510: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
2520: 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 ITE_BUSY
2530: 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 5 /* The data
2540: 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 base file is loc
2550: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ked */.#define S
2560: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 QLITE_LOCKED
2570: 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 6 /* A tabl
2580: 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 e in the databas
2590: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 e is locked */.#
25a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f define SQLITE_NO
25b0: 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f MEM 7 /
25c0: 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 * A malloc() fai
25d0: 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 led */.#define S
25e0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 QLITE_READONLY
25f0: 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 8 /* Attemp
2600: 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 t to write a rea
2610: 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a donly database *
2620: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
2630: 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 _INTERRUPT 9
2640: 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 /* Operation t
2650: 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c erminated by sql
2660: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
2670: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
2680: 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 E_IOERR 10
2690: 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 /* Some kind
26a0: 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f of disk I/O erro
26b0: 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 r occurred */.#d
26c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 efine SQLITE_COR
26d0: 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a RUPT 11 /*
26e0: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69 The database di
26f0: 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 sk image is malf
2700: 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 ormed */.#define
2710: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 SQLITE_NOTFOUND
2720: 20 20 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20 12 /* NOT
2730: 55 53 45 44 2e 20 54 61 62 6c 65 20 6f 72 20 72 USED. Table or r
2740: 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20 ecord not found
2750: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
2760: 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 E_FULL 13
2770: 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 /* Insertion
2780: 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 failed because d
2790: 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 atabase is full
27a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
27b0: 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 E_CANTOPEN 14
27c0: 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 /* Unable to
27d0: 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 open the databas
27e0: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e e file */.#defin
27f0: 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f e SQLITE_PROTOCO
2800: 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54 L 15 /* NOT
2810: 20 55 53 45 44 2e 20 44 61 74 61 62 61 73 65 20 USED. Database
2820: 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 lock protocol er
2830: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ror */.#define S
2840: 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 QLITE_EMPTY
2850: 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 16 /* Databa
2860: 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 se is empty */.#
2870: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 define SQLITE_SC
2880: 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f HEMA 17 /
2890: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 * The database s
28a0: 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f chema changed */
28b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
28c0: 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 TOOBIG 18
28d0: 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c /* String or BL
28e0: 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 OB exceeds size
28f0: 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 limit */.#define
2900: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 SQLITE_CONSTRAI
2910: 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 NT 19 /* Abor
2920: 74 20 64 75 65 20 74 6f 20 63 6f 6e 74 72 61 69 t due to contrai
2930: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a nt violation */.
2940: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d #define SQLITE_M
2950: 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 ISMATCH 20
2960: 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 /* Data type mis
2970: 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 match */.#define
2980: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 SQLITE_MISUSE
2990: 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 21 /* Libr
29a0: 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 ary used incorre
29b0: 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ctly */.#define
29c0: 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 SQLITE_NOLFS
29d0: 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 22 /* Uses
29e0: 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 OS features not
29f0: 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 supported on hos
2a00: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
2a10: 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 ITE_AUTH
2a20: 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 23 /* Authoriz
2a30: 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a ation denied */.
2a40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
2a50: 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 ORMAT 24
2a60: 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 /* Auxiliary dat
2a70: 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 abase format err
2a80: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 or */.#define SQ
2a90: 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 LITE_RANGE
2aa0: 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 25 /* 2nd par
2ab0: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
2ac0: 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 3_bind out of ra
2ad0: 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nge */.#define S
2ae0: 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 QLITE_NOTADB
2af0: 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 26 /* File o
2b00: 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f pened that is no
2b10: 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c t a database fil
2b20: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e */.#define SQL
2b30: 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 ITE_ROW
2b40: 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 100 /* sqlite3_
2b50: 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 step() has anoth
2b60: 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a er row ready */.
2b70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
2b80: 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20 ONE 101
2b90: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 /* sqlite3_step(
2ba0: 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 ) has finished e
2bb0: 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 xecuting */./* e
2bc0: 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 nd-of-error-code
2bd0: 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 s */../*.** CAPI
2be0: 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 3REF: Extended R
2bf0: 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a esult Codes.**.*
2c00: 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 * In its default
2c10: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 configuration,
2c20: 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 SQLite API routi
2c30: 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f nes return one o
2c40: 66 20 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 f 26 integer.**
2c50: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 64 65 73 result codes des
2c60: 63 72 69 62 65 64 20 61 74 20 72 65 73 75 6c 74 cribed at result
2c70: 2d 63 6f 64 65 73 2e 20 20 48 6f 77 65 76 65 72 -codes. However
2c80: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 , experience has
2c90: 20 73 68 6f 77 6e 20 74 68 61 74 0a 2a 2a 20 6d shown that.** m
2ca0: 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 65 73 any of these res
2cb0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f ult codes are to
2cc0: 6f 20 63 6f 75 72 73 65 2d 67 72 61 69 6e 65 64 o course-grained
2cd0: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 . They do not p
2ce0: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 rovide as.** muc
2cf0: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 h information ab
2d00: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 out problems as
2d10: 75 73 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 users might like
2d20: 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 . In an effort
2d30: 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68 to.** address th
2d40: 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f is, newer versio
2d50: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65 ns of SQLite (ve
2d60: 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 rsion 3.3.8 and
2d70: 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a later) include.*
2d80: 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 * support for ad
2d90: 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 ditional result
2da0: 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 codes that provi
2db0: 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 de more detailed
2dc0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 information.**
2dd0: 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 20 54 about errors. T
2de0: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 he extended resu
2df0: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61 lt codes are ena
2e00: 62 6c 65 64 20 28 6f 72 20 64 69 73 61 62 6c 65 bled (or disable
2e10: 64 29 20 66 6f 72 20 0a 2a 2a 20 65 61 63 68 20 d) for .** each
2e20: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
2e30: 65 63 74 69 6f 6e 20 75 73 69 6e 67 20 74 68 65 ection using the
2e40: 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 [sqlite3_extend
2e50: 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 ed_result_codes(
2e60: 29 5d 20 41 50 49 2e 0a 2a 2a 20 0a 2a 2a 20 53 )] API..** .** S
2e70: 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c ome of the avail
2e80: 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 able extended re
2e90: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c sult codes are l
2ea0: 69 73 74 65 64 20 61 62 6f 76 65 2e 0a 2a 2a 20 isted above..**
2eb0: 57 65 20 65 78 70 65 63 74 20 74 68 65 20 6e 75 We expect the nu
2ec0: 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64 65 64 mber of extended
2ed0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 77 69 result codes wi
2ee0: 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20 ll be expand.**
2ef0: 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f 66 74 over time. Soft
2f00: 77 61 72 65 20 74 68 61 74 20 75 73 65 73 20 65 ware that uses e
2f10: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
2f20: 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78 70 65 odes should expe
2f30: 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77 ct.** to see new
2f40: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 69 6e result codes in
2f50: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
2f60: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 0a of SQLite..** .
2f70: 2a 2a 20 54 68 65 20 73 79 6d 62 6f 6c 69 63 20 ** The symbolic
2f80: 6e 61 6d 65 20 66 6f 72 20 61 6e 20 65 78 74 65 name for an exte
2f90: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
2fa0: 20 61 6c 77 61 79 73 20 63 6f 6e 74 61 69 6e 73 always contains
2fb0: 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 70 72 a related.** pr
2fc0: 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64 imary result cod
2fd0: 65 20 61 73 20 61 20 70 72 65 66 69 78 2e 20 20 e as a prefix.
2fe0: 50 72 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63 Primary result c
2ff0: 6f 64 65 73 20 63 6f 6e 74 61 69 6e 20 61 20 73 odes contain a s
3000: 69 6e 67 6c 65 0a 2a 2a 20 22 5f 22 20 63 68 61 ingle.** "_" cha
3010: 72 61 63 74 65 72 2e 20 20 45 78 74 65 6e 64 65 racter. Extende
3020: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 63 d result codes c
3030: 6f 6e 74 61 69 6e 20 74 77 6f 20 6f 72 20 6d 6f ontain two or mo
3040: 72 65 20 22 5f 22 20 63 68 61 72 61 63 74 65 72 re "_" character
3050: 73 2e 0a 2a 2a 20 54 68 65 20 6e 75 6d 65 72 69 s..** The numeri
3060: 63 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 65 78 c value of an ex
3070: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
3080: 64 65 20 63 61 6e 20 62 65 20 63 6f 6e 76 65 72 de can be conver
3090: 74 65 64 20 74 6f 20 69 74 73 0a 2a 2a 20 63 6f ted to its.** co
30a0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 70 72 69 6d rresponding prim
30b0: 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 ary result code
30c0: 62 79 20 6d 61 73 6b 69 6e 67 20 6f 66 66 20 74 by masking off t
30d0: 68 65 20 6c 6f 77 65 72 20 38 20 62 79 74 65 73 he lower 8 bytes
30e0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 ..**.** The SQLI
30f0: 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64 TE_OK result cod
3100: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20 e will never be
3110: 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69 extended. It wi
3120: 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 ll always.** be
3130: 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f exactly zero..*/
3140: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3150: 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 IOERR_READ
3160: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
3170: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 R | (1<<8)).#def
3180: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
3190: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 28 _SHORT_READ (
31a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
31b0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 2<<8)).#define S
31c0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 QLITE_IOERR_WRIT
31d0: 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 E (SQLIT
31e0: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 E_IOERR | (3<<8)
31f0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
3200: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 _IOERR_FSYNC
3210: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
3220: 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 RR | (4<<8)).#de
3230: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
3240: 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 R_DIR_FSYNC
3250: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
3260: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (5<<8)).#define
3270: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 SQLITE_IOERR_TRU
3280: 4e 43 41 54 45 20 20 20 20 20 20 28 53 51 4c 49 NCATE (SQLI
3290: 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 TE_IOERR | (6<<8
32a0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
32b0: 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 E_IOERR_FSTAT
32c0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
32d0: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 ERR | (7<<8)).#d
32e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
32f0: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 RR_UNLOCK
3300: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
3310: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (8<<8)).#define
3320: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 SQLITE_IOERR_RD
3330: 4c 4f 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c LOCK (SQL
3340: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c ITE_IOERR | (9<<
3350: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
3360: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 TE_IOERR_DELETE
3370: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
3380: 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a OERR | (10<<8)).
3390: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
33a0: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 OERR_BLOCKED
33b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
33c0: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 0a 2f 2a 0a | (11<<8))../*.
33d0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 ** CAPI3REF: Ena
33e0: 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 ble Or Disable E
33f0: 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 xtended Result C
3400: 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 odes.**.** This
3410: 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 routine enables
3420: 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a or disables the.
3430: 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 ** [SQLITE_IOERR
3440: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 _READ | extended
3450: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 result codes] f
3460: 65 61 74 75 72 65 2e 0a 2a 2a 20 42 79 20 64 65 eature..** By de
3470: 66 61 75 6c 74 2c 20 53 51 4c 69 74 65 20 41 50 fault, SQLite AP
3480: 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 I routines retur
3490: 6e 20 6f 6e 65 20 6f 66 20 6f 6e 6c 79 20 32 36 n one of only 26
34a0: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c integer.** [SQL
34b0: 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 ITE_OK | result
34c0: 63 6f 64 65 73 5d 2e 20 20 57 68 65 6e 20 65 78 codes]. When ex
34d0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
34e0: 64 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c des.** are enabl
34f0: 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 ed by this routi
3500: 6e 65 2c 20 74 68 65 20 72 65 70 65 74 6f 69 72 ne, the repetoir
3510: 65 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 64 65 e of result code
3520: 73 20 63 61 6e 20 62 65 0a 2a 2a 20 6d 75 63 68 s can be.** much
3530: 20 6c 61 72 67 65 72 20 61 6e 64 20 63 61 6e 20 larger and can
3540: 28 68 6f 70 65 66 75 6c 6c 79 29 20 70 72 6f 76 (hopefully) prov
3550: 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 ide more detaile
3560: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a d information.**
3570: 20 61 62 6f 75 74 20 74 68 65 20 63 61 75 73 65 about the cause
3580: 20 6f 66 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a of an error..**
3590: 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 .** The second a
35a0: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 62 6f 6f rgument is a boo
35b0: 6c 65 61 6e 20 76 61 6c 75 65 20 74 68 61 74 20 lean value that
35c0: 74 75 72 6e 73 20 65 78 74 65 6e 64 65 64 20 72 turns extended r
35d0: 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 6f esult.** codes o
35e0: 6e 20 61 6e 64 20 6f 66 66 2e 20 20 45 78 74 65 n and off. Exte
35f0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
3600: 73 20 61 72 65 20 6f 66 66 20 62 79 20 64 65 66 s are off by def
3610: 61 75 6c 74 20 66 6f 72 0a 2a 2a 20 62 61 63 6b ault for.** back
3620: 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c wards compatibil
3630: 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 76 ity with older v
3640: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
3650: 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 e..*/.int sqlite
3660: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 3_extended_resul
3670: 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a t_codes(sqlite3*
3680: 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f , int onoff);../
3690: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c *.** CAPI3REF: L
36a0: 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 ast Insert Rowid
36b0: 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74 72 .**.** Each entr
36c0: 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 y in an SQLite t
36d0: 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 able has a uniqu
36e0: 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 e 64-bit signed
36f0: 69 6e 74 65 67 65 72 20 6b 65 79 0a 2a 2a 20 63 integer key.** c
3700: 61 6c 6c 65 64 20 74 68 65 20 22 72 6f 77 69 64 alled the "rowid
3710: 22 2e 20 54 68 65 20 72 6f 77 69 64 20 69 73 20 ". The rowid is
3720: 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 always available
3730: 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 as an undeclare
3740: 64 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 d.** column name
3750: 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 d ROWID, OID, or
3760: 20 5f 52 4f 57 49 44 5f 2e 20 20 49 66 20 74 68 _ROWID_. If th
3770: 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f e table has a co
3780: 6c 75 6d 6e 20 6f 66 0a 2a 2a 20 74 79 70 65 20 lumn of.** type
3790: 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 INTEGER PRIMARY
37a0: 4b 45 59 20 74 68 65 6e 20 74 68 61 74 20 63 6f KEY then that co
37b0: 6c 75 6d 6e 20 69 73 20 61 6e 6f 74 68 65 72 20 lumn is another
37c0: 61 6e 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 an alias for the
37d0: 0a 2a 2a 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a .** rowid..**.**
37e0: 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 This routine re
37f0: 74 75 72 6e 73 20 74 68 65 20 72 6f 77 69 64 20 turns the rowid
3800: 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 of the most rece
3810: 6e 74 20 49 4e 53 45 52 54 20 69 6e 74 6f 0a 2a nt INSERT into.*
3820: 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 * the database f
3830: 72 6f 6d 20 74 68 65 20 64 61 74 61 62 61 73 65 rom the database
3840: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 67 69 76 65 connection give
3850: 6e 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 0a n in the first .
3860: 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 ** argument. If
3870: 20 6e 6f 20 69 6e 73 65 72 74 73 20 68 61 76 65 no inserts have
3880: 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f ever occurred o
3890: 6e 20 74 68 69 73 20 64 61 74 61 62 61 73 65 0a n this database.
38a0: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a ** connection, z
38b0: 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e ero is returned.
38c0: 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 49 4e 53 .**.** If an INS
38d0: 45 52 54 20 6f 63 63 75 72 73 20 77 69 74 68 69 ERT occurs withi
38e0: 6e 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65 n a trigger, the
38f0: 6e 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 n the rowid of t
3900: 68 65 0a 2a 2a 20 69 6e 73 65 72 74 65 64 20 72 he.** inserted r
3910: 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 ow is returned b
3920: 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 y this routine a
3930: 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 s long as the tr
3940: 69 67 67 65 72 0a 2a 2a 20 69 73 20 72 75 6e 6e igger.** is runn
3950: 69 6e 67 2e 20 20 42 75 74 20 6f 6e 63 65 20 74 ing. But once t
3960: 68 65 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 he trigger termi
3970: 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 nates, the value
3980: 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 returned.** by
3990: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 this routine rev
39a0: 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 erts to the last
39b0: 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 value inserted
39c0: 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 74 72 before the.** tr
39d0: 69 67 67 65 72 20 66 69 72 65 64 2e 0a 2a 2f 0a igger fired..*/.
39e0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c sqlite_int64 sql
39f0: 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 ite3_last_insert
3a00: 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 _rowid(sqlite3*)
3a10: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
3a20: 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d F: Count The Num
3a30: 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 ber Of Rows Modi
3a40: 66 69 65 64 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 fied.**.** This
3a50: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
3a60: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 the number of d
3a70: 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 atabase rows tha
3a80: 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a t were changed.*
3a90: 2a 20 28 6f 72 20 69 6e 73 65 72 74 65 64 20 6f * (or inserted o
3aa0: 72 20 64 65 6c 65 74 65 64 29 20 62 79 20 74 68 r deleted) by th
3ab0: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 53 51 e most recent SQ
3ac0: 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4f 6e L statement. On
3ad0: 6c 79 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 68 ly.** changes th
3ae0: 61 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 at are directly
3af0: 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 specified by the
3b00: 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c INSERT, UPDATE,
3b10: 20 6f 72 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 or.** DELETE st
3b20: 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e atement are coun
3b30: 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 ted. Auxiliary
3b40: 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 changes caused b
3b50: 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 61 72 y.** triggers ar
3b60: 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 e not counted.
3b70: 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 Use the [sqlite3
3b80: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 _total_changes()
3b90: 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 6f ] function.** to
3ba0: 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 find the total
3bb0: 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 number of change
3bc0: 73 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e s including chan
3bd0: 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72 ges caused by tr
3be0: 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 57 69 iggers..**.** Wi
3bf0: 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 thin the body of
3c00: 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65 20 a trigger, the
3c10: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 sqlite3_changes(
3c20: 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 ) interface can
3c30: 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 74 6f 20 be.** called to
3c40: 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 find the number
3c50: 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e of.** changes in
3c60: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
3c70: 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 ly completed INS
3c80: 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 ERT, UPDATE, or
3c90: 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d DELETE.** statem
3ca0: 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 ent within the b
3cb0: 6f 64 79 20 6f 66 20 74 68 65 20 74 72 69 67 67 ody of the trigg
3cc0: 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 6c 6c 20 63 68 er..**.** All ch
3cd0: 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 anges are counte
3ce0: 64 2c 20 65 76 65 6e 20 69 66 20 74 68 65 79 20 d, even if they
3cf0: 77 65 72 65 20 6c 61 74 65 72 20 75 6e 64 6f 6e were later undon
3d00: 65 20 62 79 20 61 0a 2a 2a 20 52 4f 4c 4c 42 41 e by a.** ROLLBA
3d10: 43 4b 20 6f 72 20 41 42 4f 52 54 2e 20 20 45 78 CK or ABORT. Ex
3d20: 63 65 70 74 2c 20 63 68 61 6e 67 65 73 20 61 73 cept, changes as
3d30: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 63 72 sociated with cr
3d40: 65 61 74 69 6e 67 20 61 6e 64 0a 2a 2a 20 64 72 eating and.** dr
3d50: 6f 70 70 69 6e 67 20 74 61 62 6c 65 73 20 61 72 opping tables ar
3d60: 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a e not counted..*
3d70: 2a 0a 2a 2a 20 49 66 20 61 20 63 61 6c 6c 62 61 *.** If a callba
3d80: 63 6b 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 ck invokes [sqli
3d90: 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b te3_exec()] or [
3da0: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
3db0: 72 65 63 75 72 73 69 76 65 6c 79 2c 0a 2a 2a 20 recursively,.**
3dc0: 74 68 65 6e 20 74 68 65 20 63 68 61 6e 67 65 73 then the changes
3dd0: 20 69 6e 20 74 68 65 20 69 6e 6e 65 72 2c 20 72 in the inner, r
3de0: 65 63 75 72 73 69 76 65 20 63 61 6c 6c 20 61 72 ecursive call ar
3df0: 65 20 63 6f 75 6e 74 65 64 20 74 6f 67 65 74 68 e counted togeth
3e00: 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 63 er.** with the c
3e10: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6f 75 hanges in the ou
3e20: 74 65 72 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 ter call..**.**
3e30: 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 SQLite implement
3e40: 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 s the command "D
3e50: 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 ELETE FROM table
3e60: 22 20 77 69 74 68 6f 75 74 20 61 20 57 48 45 52 " without a WHER
3e70: 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64 E clause.** by d
3e80: 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72 ropping and recr
3e90: 65 61 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65 eating the table
3ea0: 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75 63 68 . (This is much
3eb0: 20 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f 69 faster than goi
3ec0: 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e ng.** through an
3ed0: 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 d deleting indiv
3ee0: 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 idual elements f
3ef0: 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e 29 20 rom the table.)
3f00: 20 42 65 63 61 75 73 65 20 6f 66 0a 2a 2a 20 74 Because of.** t
3f10: 68 69 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e his optimization
3f20: 2c 20 74 68 65 20 63 68 61 6e 67 65 20 63 6f 75 , the change cou
3f30: 6e 74 20 66 6f 72 20 22 44 45 4c 45 54 45 20 46 nt for "DELETE F
3f40: 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 6c 6c 20 ROM table" will
3f50: 62 65 0a 2a 2a 20 7a 65 72 6f 20 72 65 67 61 72 be.** zero regar
3f60: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d dless of the num
3f70: 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 ber of elements
3f80: 74 68 61 74 20 77 65 72 65 20 6f 72 69 67 69 6e that were origin
3f90: 61 6c 6c 79 20 69 6e 20 74 68 65 0a 2a 2a 20 74 ally in the.** t
3fa0: 61 62 6c 65 2e 20 54 6f 20 67 65 74 20 61 6e 20 able. To get an
3fb0: 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f accurate count o
3fc0: 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 f the number of
3fd0: 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73 rows deleted, us
3fe0: 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f e.** "DELETE FRO
3ff0: 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20 31 22 M table WHERE 1"
4000: 20 69 6e 73 74 65 61 64 2e 0a 2a 2f 0a 69 6e 74 instead..*/.int
4010: 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 sqlite3_changes
4020: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
4030: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 ** CAPI3REF: Tot
4040: 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 al Number Of Row
4050: 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 2a 0a 2a s Modified.***.*
4060: 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 * This function
4070: 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
4080: 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 er of database r
4090: 6f 77 73 20 74 68 61 74 20 68 61 76 65 20 62 65 ows that have be
40a0: 65 6e 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 62 en.** modified b
40b0: 79 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 y INSERT, UPDATE
40c0: 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 or DELETE state
40d0: 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 ments since the
40e0: 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 0a database handle.
40f0: 2a 2a 20 77 61 73 20 6f 70 65 6e 65 64 2e 20 54 ** was opened. T
4100: 68 69 73 20 69 6e 63 6c 75 64 65 73 20 55 50 44 his includes UPD
4110: 41 54 45 2c 20 49 4e 53 45 52 54 20 61 6e 64 20 ATE, INSERT and
4120: 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 DELETE statement
4130: 73 20 65 78 65 63 75 74 65 64 0a 2a 2a 20 61 73 s executed.** as
4140: 20 70 61 72 74 20 6f 66 20 74 72 69 67 67 65 72 part of trigger
4150: 20 70 72 6f 67 72 61 6d 73 2e 20 41 6c 6c 20 63 programs. All c
4160: 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 hanges are count
4170: 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 ed as soon as th
4180: 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 e.** statement t
4190: 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 hat makes them i
41a0: 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 s completed (whe
41b0: 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 n the statement
41c0: 68 61 6e 64 6c 65 20 69 73 0a 2a 2a 20 70 61 73 handle is.** pas
41d0: 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f sed to [sqlite3_
41e0: 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c reset()] or [sql
41f0: 69 74 65 5f 66 69 6e 61 6c 69 73 65 28 29 5d 29 ite_finalise()])
4200: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
4210: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 the [sqlite3_ch
4220: 61 6e 67 65 28 29 5d 20 69 6e 74 65 72 66 61 63 ange()] interfac
4230: 65 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 e..**.** SQLite
4240: 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 implements the c
4250: 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46 ommand "DELETE F
4260: 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f ROM table" witho
4270: 75 74 20 61 20 57 48 45 52 45 20 63 6c 61 75 73 ut a WHERE claus
4280: 65 0a 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 e.** by dropping
4290: 20 61 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20 and recreating
42a0: 74 68 65 20 74 61 62 6c 65 2e 20 20 28 54 68 69 the table. (Thi
42b0: 73 20 69 73 20 6d 75 63 68 20 66 61 73 74 65 72 s is much faster
42c0: 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 than going.** t
42d0: 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 74 hrough and delet
42e0: 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20 65 ing individual e
42f0: 6c 65 6d 65 6e 74 73 20 66 6f 72 6d 20 74 68 65 lements form the
4300: 20 74 61 62 6c 65 2e 29 20 20 42 65 63 61 75 73 table.) Becaus
4310: 65 20 6f 66 0a 2a 2a 20 74 68 69 73 20 6f 70 74 e of.** this opt
4320: 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 63 imization, the c
4330: 68 61 6e 67 65 20 63 6f 75 6e 74 20 66 6f 72 20 hange count for
4340: 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 "DELETE FROM tab
4350: 6c 65 22 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 7a le" will be.** z
4360: 65 72 6f 20 72 65 67 61 72 64 6c 65 73 73 20 6f ero regardless o
4370: 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 f the number of
4380: 65 6c 65 6d 65 6e 74 73 20 74 68 61 74 20 77 65 elements that we
4390: 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e re originally in
43a0: 20 74 68 65 0a 2a 2a 20 74 61 62 6c 65 2e 20 54 the.** table. T
43b0: 6f 20 67 65 74 20 61 6e 20 61 63 63 75 72 61 74 o get an accurat
43c0: 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e e count of the n
43d0: 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65 umber of rows de
43e0: 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 leted, use.** "D
43f0: 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 ELETE FROM table
4400: 20 57 48 45 52 45 20 31 22 20 69 6e 73 74 65 61 WHERE 1" instea
4410: 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 d..*/.int sqlite
4420: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 3_total_changes(
4430: 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a sqlite3*);../*.*
4440: 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 * CAPI3REF: Inte
4450: 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e rrupt A Long-Run
4460: 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a ning Query.**.**
4470: 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 This function c
4480: 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e auses any pendin
4490: 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 g database opera
44a0: 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e tion to abort an
44b0: 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 d.** return at i
44c0: 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f ts earliest oppo
44d0: 72 74 75 6e 69 74 79 2e 20 20 54 68 69 73 20 72 rtunity. This r
44e0: 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 outine is typica
44f0: 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e lly.** called in
4500: 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 response to a u
4510: 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 ser action such
4520: 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e as pressing "Can
4530: 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d cel".** or Ctrl-
4540: 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72 C where the user
4550: 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 wants a long qu
4560: 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f ery operation to
4570: 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 halt.** immedia
4580: 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 tely..**.** It i
4590: 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 s safe to call t
45a0: 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d his routine from
45b0: 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72 a thread differ
45c0: 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 ent from the.**
45d0: 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63 thread that is c
45e0: 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 urrently running
45f0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 the database op
4600: 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 eration..**.** T
4610: 68 65 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e he SQL operation
4620: 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 that is interru
4630: 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e pted will return
4640: 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 [SQLITE_INTERRU
4650: 50 54 5d 2e 0a 2a 2a 20 49 66 20 61 6e 20 69 6e PT]..** If an in
4660: 74 65 72 72 75 70 74 65 64 20 6f 70 65 72 61 74 terrupted operat
4670: 69 6f 6e 20 77 61 73 20 61 6e 20 75 70 64 61 74 ion was an updat
4680: 65 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 e that is inside
4690: 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 an.** explicit
46a0: 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 transaction, the
46b0: 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 n the entire tra
46c0: 6e 73 61 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 nsaction will be
46d0: 20 72 6f 6c 6c 65 64 0a 2a 2a 20 62 61 63 6b 20 rolled.** back
46e0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a automatically..*
46f0: 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 /.void sqlite3_i
4700: 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 nterrupt(sqlite3
4710: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
4720: 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 REF: Determine I
4730: 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 f An SQL Stateme
4740: 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a nt Is Complete.*
4750: 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 *.** These funct
4760: 69 6f 6e 73 20 72 65 74 75 72 6e 20 74 72 75 65 ions return true
4770: 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 69 6e if the given in
4780: 70 75 74 20 73 74 72 69 6e 67 20 63 6f 6d 70 72 put string compr
4790: 69 73 65 73 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d ises.** one or m
47a0: 6f 72 65 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c ore complete SQL
47b0: 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 46 6f 72 statements. For
47c0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d the sqlite3_com
47d0: 70 6c 65 74 65 28 29 20 63 61 6c 6c 2c 0a 2a 2a plete() call,.**
47e0: 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d the parameter m
47f0: 75 73 74 20 62 65 20 61 20 6e 75 6c 2d 74 65 72 ust be a nul-ter
4800: 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 minated UTF-8 st
4810: 72 69 6e 67 2e 20 46 6f 72 0a 2a 2a 20 73 71 6c ring. For.** sql
4820: 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 ite3_complete16(
4830: 29 2c 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 ), a nul-termina
4840: 74 65 64 20 6d 61 63 68 69 6e 65 20 62 79 74 65 ted machine byte
4850: 20 6f 72 64 65 72 20 55 54 46 2d 31 36 20 73 74 order UTF-16 st
4860: 72 69 6e 67 0a 2a 2a 20 69 73 20 72 65 71 75 69 ring.** is requi
4870: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 red..**.** These
4880: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 routines are us
4890: 65 66 75 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64 eful for command
48a0: 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 -line input to d
48b0: 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a etermine if the.
48c0: 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 ** currently ent
48d0: 65 72 65 64 20 74 65 78 74 20 66 6f 72 6d 73 20 ered text forms
48e0: 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 6f 6d 70 one or more comp
48f0: 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 lete SQL stateme
4900: 6e 74 73 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 nts or.** if add
4910: 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 itional input is
4920: 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 needed before s
4930: 65 6e 64 69 6e 67 20 74 68 65 20 73 74 61 74 65 ending the state
4940: 6d 65 6e 74 73 20 69 6e 74 6f 0a 2a 2a 20 53 51 ments into.** SQ
4950: 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 Lite for parsing
4960: 2e 20 54 68 65 20 61 6c 67 6f 72 69 74 68 6d 20 . The algorithm
4970: 69 73 20 73 69 6d 70 6c 65 2e 20 20 49 66 20 74 is simple. If t
4980: 68 65 20 0a 2a 2a 20 6c 61 73 74 20 74 6f 6b 65 he .** last toke
4990: 6e 20 6f 74 68 65 72 20 74 68 61 6e 20 73 70 61 n other than spa
49a0: 63 65 73 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 ces and comments
49b0: 20 69 73 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 2c is a semicolon,
49c0: 20 74 68 65 6e 20 72 65 74 75 72 6e 20 0a 2a 2a then return .**
49d0: 20 74 72 75 65 2e 20 20 41 63 74 75 61 6c 6c 79 true. Actually
49e0: 2c 20 74 68 65 20 61 6c 67 6f 72 69 74 68 6d 20 , the algorithm
49f0: 69 73 20 61 20 6c 69 74 74 6c 65 20 6d 6f 72 65 is a little more
4a00: 20 63 6f 6d 70 6c 69 63 61 74 65 64 20 74 68 61 complicated tha
4a10: 6e 20 74 68 61 74 0a 2a 2a 20 69 6e 20 6f 72 64 n that.** in ord
4a20: 65 72 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 er to deal with
4a30: 74 72 69 67 67 65 72 73 2c 20 62 75 74 20 74 68 triggers, but th
4a40: 65 20 62 61 73 69 63 20 69 64 65 61 20 69 73 20 e basic idea is
4a50: 74 68 65 20 73 61 6d 65 3a 20 20 74 68 65 0a 2a the same: the.*
4a60: 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e * statement is n
4a70: 6f 74 20 63 6f 6d 70 6c 65 74 65 20 75 6e 6c 65 ot complete unle
4a80: 73 73 20 69 74 20 65 6e 64 73 20 69 6e 20 61 20 ss it ends in a
4a90: 73 65 6d 69 63 6f 6c 6f 6e 2e 0a 2a 2f 0a 69 6e semicolon..*/.in
4aa0: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 t sqlite3_comple
4ab0: 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 te(const char *s
4ac0: 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 ql);.int sqlite3
4ad0: 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 _complete16(cons
4ae0: 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f t void *sql);../
4af0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
4b00: 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 egister A Callba
4b10: 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c ck To Handle SQL
4b20: 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a ITE_BUSY Errors.
4b30: 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
4b40: 6e 65 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 ne identifies a
4b50: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
4b60: 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 n that might be
4b70: 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 65 invoked.** whene
4b80: 76 65 72 20 61 6e 20 61 74 74 65 6d 70 74 20 69 ver an attempt i
4b90: 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 s made to open a
4ba0: 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 database table
4bb0: 0a 2a 2a 20 74 68 61 74 20 61 6e 6f 74 68 65 72 .** that another
4bc0: 20 74 68 72 65 61 64 20 6f 72 20 70 72 6f 63 65 thread or proce
4bd0: 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a ss has locked..*
4be0: 2a 20 49 66 20 74 68 65 20 62 75 73 79 20 63 61 * If the busy ca
4bf0: 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 llback is NULL,
4c00: 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 then [SQLITE_BUS
4c10: 59 5d 0a 2a 2a 20 28 6f 72 20 73 6f 6d 65 74 69 Y].** (or someti
4c20: 6d 65 73 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 mes [SQLITE_IOER
4c30: 52 5f 42 4c 4f 43 4b 45 44 5d 29 0a 2a 2a 20 69 R_BLOCKED]).** i
4c40: 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 s returned immed
4c50: 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f iately upon enco
4c60: 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 untering the loc
4c70: 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73 k..** If the bus
4c80: 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f y callback is no
4c90: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 t NULL, then the
4ca0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c .** callback wil
4cb0: 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 l be invoked wit
4cc0: 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e h two arguments.
4cd0: 20 20 54 68 65 0a 2a 2a 20 66 69 72 73 74 20 61 The.** first a
4ce0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 68 rgument to the h
4cf0: 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 andler is a copy
4d00: 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f of the void* po
4d10: 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 inter which.** i
4d20: 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 s the third argu
4d30: 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 72 6f 75 ment to this rou
4d40: 74 69 6e 65 2e 20 20 54 68 65 20 73 65 63 6f 6e tine. The secon
4d50: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a d argument to.**
4d60: 20 74 68 65 20 68 61 6e 64 6c 65 72 20 69 73 20 the handler is
4d70: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 the number of ti
4d80: 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 mes that the bus
4d90: 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a y handler has.**
4da0: 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f been invoked fo
4db0: 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 r this locking e
4dc0: 76 65 6e 74 2e 20 49 66 20 74 68 65 0a 2a 2a 20 vent. If the.**
4dd0: 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 busy callback re
4de0: 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f turns 0, then no
4df0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 additional atte
4e00: 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f mpts are made to
4e10: 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 .** access the d
4e20: 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c atabase and [SQL
4e30: 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 ITE_BUSY] or [SQ
4e40: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b LITE_IOERR_BLOCK
4e50: 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e ED] is returned.
4e60: 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62 .** If the callb
4e70: 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d ack returns non-
4e80: 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 zero, then anoth
4e90: 65 72 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 er attempt is ma
4ea0: 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 0a 2a de to open the.*
4eb0: 2a 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 * database for r
4ec0: 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 eading and the c
4ed0: 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a ycle repeats..**
4ee0: 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 .** The presence
4ef0: 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c of a busy handl
4f00: 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 er does not guar
4f10: 61 6e 74 65 65 20 74 68 61 74 0a 2a 2a 20 69 74 antee that.** it
4f20: 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 will be invoked
4f30: 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c when there is l
4f40: 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 0a ock contention..
4f50: 2a 2a 20 49 66 20 53 51 4c 69 74 65 20 64 65 74 ** If SQLite det
4f60: 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 ermines that inv
4f70: 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 oking the busy h
4f80: 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 andler could res
4f90: 75 6c 74 20 69 6e 0a 2a 2a 20 61 20 64 65 61 64 ult in.** a dead
4fa0: 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 72 65 lock, it will re
4fb0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 turn [SQLITE_BUS
4fc0: 59 5d 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 20 43 Y] instead..** C
4fd0: 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 onsider a scenar
4fe0: 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f io where one pro
4ff0: 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 cess is holding
5000: 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 a read lock that
5010: 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 .** it is trying
5020: 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 to promote to a
5030: 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 reserved lock a
5040: 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 nd.** a second p
5050: 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e rocess is holdin
5060: 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 g a reserved loc
5070: 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 k that it is try
5080: 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 ing.** to promot
5090: 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 e to an exclusiv
50a0: 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 e lock. The fir
50b0: 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f st process canno
50c0: 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 t proceed.** bec
50d0: 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b ause it is block
50e0: 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 ed by the second
50f0: 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 and the second
5100: 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a process cannot.*
5110: 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 * proceed becaus
5120: 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 e it is blocked
5130: 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 by the first. I
5140: 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 f both processes
5150: 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 .** invoke the b
5160: 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 usy handlers, ne
5170: 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 ither will make
5180: 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 any progress. T
5190: 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c herefore,.** SQL
51a0: 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ite returns [SQL
51b0: 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 ITE_BUSY] for th
51c0: 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c e first process,
51d0: 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 hoping that thi
51e0: 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 s.** will induce
51f0: 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 the first proce
5200: 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 ss to release it
5210: 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 s read lock and
5220: 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 allow.** the sec
5230: 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 ond process to p
5240: 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 roceed..**.** Th
5250: 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 e default busy c
5260: 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e allback is NULL.
5270: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 .**.** The [SQLI
5280: 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 TE_BUSY] error i
5290: 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b s converted to [
52a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f SQLITE_IOERR_BLO
52b0: 43 4b 45 44 5d 20 77 68 65 6e 0a 2a 2a 20 53 51 CKED] when.** SQ
52c0: 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d Lite is in the m
52d0: 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 iddle of a large
52e0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 transaction whe
52f0: 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 re all the.** ch
5300: 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 anges will not f
5310: 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d it into the in-m
5320: 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 emory cache. SQ
5330: 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 Lite will.** alr
5340: 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 eady hold a RESE
5350: 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 RVED lock on the
5360: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 database file,
5370: 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 but it needs.**
5380: 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 to promote this
5390: 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 lock to EXCLUSIV
53a0: 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e E so that it can
53b0: 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 spill cache.**
53c0: 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 pages into the d
53d0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 atabase file wit
53e0: 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e hout harm to con
53f0: 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 current.** reade
5400: 72 73 2e 20 20 49 66 20 69 74 20 69 73 20 75 6e rs. If it is un
5410: 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 able to promote
5420: 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 the lock, then t
5430: 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 he in-memory.**
5440: 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 cache will be le
5450: 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 ft in an inconsi
5460: 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 stent state and
5470: 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 so the error.**
5480: 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 code is promoted
5490: 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 from the relati
54a0: 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c vely benign [SQL
54b0: 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 ITE_BUSY] to.**
54c0: 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 the more severe
54d0: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c [SQLITE_IOERR_BL
54e0: 4f 43 4b 45 44 5d 2e 20 20 54 68 69 73 20 65 72 OCKED]. This er
54f0: 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 ror code promoti
5500: 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 on.** forces an
5510: 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 automatic rollba
5520: 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 ck of the change
5530: 73 2e 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 s. See the.** <a
5540: 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 href="http://ww
5550: 77 2e 73 71 6c 69 74 65 2e 6f 72 67 2f 63 76 73 w.sqlite.org/cvs
5560: 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 trac/wiki?p=Corr
5570: 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 uptionFollowingB
5580: 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f usyError">.** Co
5590: 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e rruptionFollowin
55a0: 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 gBusyError</a> w
55b0: 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 iki page for a d
55c0: 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 iscussion of why
55d0: 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f .** this is impo
55e0: 72 74 61 6e 74 2e 0a 2a 2a 09 0a 2a 2a 20 53 71 rtant..**..** Sq
55f0: 6c 69 74 65 20 69 73 20 72 65 2d 65 6e 74 72 61 lite is re-entra
5600: 6e 74 2c 20 73 6f 20 74 68 65 20 62 75 73 79 20 nt, so the busy
5610: 68 61 6e 64 6c 65 72 20 6d 61 79 20 73 74 61 72 handler may star
5620: 74 20 61 20 6e 65 77 20 71 75 65 72 79 2e 20 0a t a new query. .
5630: 2a 2a 20 28 49 74 20 69 73 20 6e 6f 74 20 63 6c ** (It is not cl
5640: 65 61 72 20 77 68 79 20 61 6e 79 6f 6e 65 20 77 ear why anyone w
5650: 6f 75 6c 64 20 65 76 65 72 79 20 77 61 6e 74 20 ould every want
5660: 74 6f 20 64 6f 20 74 68 69 73 2c 20 62 75 74 20 to do this, but
5670: 69 74 0a 2a 2a 20 69 73 20 61 6c 6c 6f 77 65 64 it.** is allowed
5680: 2c 20 69 6e 20 74 68 65 6f 72 79 2e 29 20 20 42 , in theory.) B
5690: 75 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ut the busy hand
56a0: 6c 65 72 20 6d 61 79 20 6e 6f 74 20 63 6c 6f 73 ler may not clos
56b0: 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 e the.** databas
56c0: 65 2e 20 20 43 6c 6f 73 69 6e 67 20 74 68 65 20 e. Closing the
56d0: 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 61 20 database from a
56e0: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 77 69 6c busy handler wil
56f0: 6c 20 64 65 6c 65 74 65 20 0a 2a 2a 20 64 61 74 l delete .** dat
5700: 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 75 74 a structures out
5710: 20 66 72 6f 6d 20 75 6e 64 65 72 20 74 68 65 20 from under the
5720: 65 78 65 63 75 74 69 6e 67 20 71 75 65 72 79 20 executing query
5730: 61 6e 64 20 77 69 6c 6c 20 0a 2a 2a 20 70 72 6f and will .** pro
5740: 62 61 62 6c 79 20 72 65 73 75 6c 74 20 69 6e 20 bably result in
5750: 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 a segmentation f
5760: 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 72 75 ault or other ru
5770: 6e 74 69 6d 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a ntime error..**.
5780: 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c ** There can onl
5790: 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 y be a single bu
57a0: 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e sy handler defin
57b0: 65 64 20 66 6f 72 20 65 61 63 68 20 64 61 74 61 ed for each data
57c0: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 base.** connecti
57d0: 6f 6e 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e on. Setting a n
57e0: 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 ew busy handler
57f0: 63 6c 65 61 72 73 20 61 6e 79 20 70 72 65 76 69 clears any previ
5800: 6f 75 73 20 6f 6e 65 2e 0a 2a 2a 20 4e 6f 74 65 ous one..** Note
5810: 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 that calling [s
5820: 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 qlite3_busy_time
5830: 6f 75 74 28 29 5d 20 77 69 6c 6c 20 61 6c 73 6f out()] will also
5840: 20 73 65 74 20 6f 72 20 63 6c 65 61 72 0a 2a 2a set or clear.**
5850: 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 the busy handle
5860: 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 r..*/.int sqlite
5870: 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 3_busy_handler(s
5880: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 qlite3*, int(*)(
5890: 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 void*,int), void
58a0: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
58b0: 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 REF: Set A Busy
58c0: 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 54 68 Timeout.**.** Th
58d0: 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 is routine sets
58e0: 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 74 a busy handler t
58f0: 68 61 74 20 73 6c 65 65 70 73 20 66 6f 72 20 61 hat sleeps for a
5900: 20 77 68 69 6c 65 20 77 68 65 6e 20 61 0a 2a 2a while when a.**
5910: 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 table is locked
5920: 2e 20 20 54 68 65 20 68 61 6e 64 6c 65 72 20 77 . The handler w
5930: 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 ill sleep multip
5940: 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 0a le times until .
5950: 2a 2a 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 ** at least "ms"
5960: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 milliseconds of
5970: 20 73 6c 65 65 70 69 6e 67 20 68 61 76 65 20 62 sleeping have b
5980: 65 65 6e 20 64 6f 6e 65 2e 20 20 41 66 74 65 72 een done. After
5990: 0a 2a 2a 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 .** "ms" millise
59a0: 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e conds of sleepin
59b0: 67 2c 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 g, the handler r
59c0: 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 0a 2a eturns 0 which.*
59d0: 2a 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 * causes [sqlite
59e0: 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 3_step()] to ret
59f0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 urn [SQLITE_BUSY
5a00: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 ] or [SQLITE_IOE
5a10: 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a RR_BLOCKED]..**.
5a20: 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 ** Calling this
5a30: 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 routine with an
5a40: 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 argument less th
5a50: 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a an or equal to z
5a60: 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 ero.** turns off
5a70: 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 all busy handle
5a80: 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 rs..**.** There
5a90: 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 can only be a si
5aa0: 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 ngle busy handle
5ab0: 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c r for a particul
5ac0: 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 ar database.** c
5ad0: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 49 66 20 61 onnection. If a
5ae0: 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 nother busy hand
5af0: 6c 65 72 20 77 61 73 20 64 65 66 69 6e 65 64 20 ler was defined
5b00: 20 0a 2a 2a 20 28 75 73 69 6e 67 20 5b 73 71 6c .** (using [sql
5b10: 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 ite3_busy_handle
5b20: 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 r()]) prior to c
5b30: 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 alling.** this r
5b40: 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 outine, that oth
5b50: 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 er busy handler
5b60: 69 73 20 63 6c 65 61 72 65 64 2e 0a 2a 2f 0a 69 is cleared..*/.i
5b70: 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f nt sqlite3_busy_
5b80: 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a timeout(sqlite3*
5b90: 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a , int ms);../*.*
5ba0: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 * CAPI3REF: Conv
5bb0: 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 enience Routines
5bc0: 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 For Running Que
5bd0: 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ries.**.** This
5be0: 6e 65 78 74 20 72 6f 75 74 69 6e 65 20 69 73 20 next routine is
5bf0: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 a convenience wr
5c00: 61 70 70 65 72 20 61 72 6f 75 6e 64 20 5b 73 71 apper around [sq
5c10: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 0a 2a lite3_exec()]..*
5c20: 2a 20 49 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 * Instead of inv
5c30: 6f 6b 69 6e 67 20 61 20 75 73 65 72 2d 73 75 70 oking a user-sup
5c40: 70 6c 69 65 64 20 63 61 6c 6c 62 61 63 6b 20 66 plied callback f
5c50: 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20 74 or each row of t
5c60: 68 65 0a 2a 2a 20 72 65 73 75 6c 74 2c 20 74 68 he.** result, th
5c70: 69 73 20 72 6f 75 74 69 6e 65 20 72 65 6d 65 6d is routine remem
5c80: 62 65 72 73 20 65 61 63 68 20 72 6f 77 20 6f 66 bers each row of
5c90: 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20 6d the result in m
5ca0: 65 6d 6f 72 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 emory.** obtaine
5cb0: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
5cc0: 6d 61 6c 6c 6f 63 28 29 5d 2c 20 74 68 65 6e 20 malloc()], then
5cd0: 72 65 74 75 72 6e 73 20 61 6c 6c 20 6f 66 20 74 returns all of t
5ce0: 68 65 20 72 65 73 75 6c 74 20 61 66 74 65 72 20 he result after
5cf0: 74 68 65 0a 2a 2a 20 71 75 65 72 79 20 68 61 73 the.** query has
5d00: 20 66 69 6e 69 73 68 65 64 2e 20 0a 2a 2a 0a 2a finished. .**.*
5d10: 2a 20 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 2c * As an example,
5d20: 20 73 75 70 70 6f 73 65 20 74 68 65 20 71 75 65 suppose the que
5d30: 72 79 20 72 65 73 75 6c 74 20 77 68 65 72 65 20 ry result where
5d40: 74 68 69 73 20 74 61 62 6c 65 3a 0a 2a 2a 0a 2a this table:.**.*
5d50: 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 * <pre>.**
5d60: 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 Name |
5d70: 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d Age.** --
5d80: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
5d90: 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 -----.**
5da0: 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 Alice | 43
5db0: 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 .** Bob
5dc0: 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 | 28.**
5dd0: 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 Cindy
5de0: 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e | 21.** </pre>
5df0: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 .**.** If the 3r
5e00: 64 20 61 72 67 75 6d 65 6e 74 20 77 65 72 65 20 d argument were
5e10: 26 61 7a 52 65 73 75 6c 74 20 74 68 65 6e 20 61 &azResult then a
5e20: 66 74 65 72 20 74 68 65 20 66 75 6e 63 74 69 6f fter the functio
5e30: 6e 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 7a 52 n returns.** azR
5e40: 65 73 75 6c 74 20 77 69 6c 6c 20 63 6f 6e 74 61 esult will conta
5e50: 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 in the following
5e60: 20 64 61 74 61 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 data:.**.** <pr
5e70: 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 e>.** azR
5e80: 65 73 75 6c 74 5b 30 5d 20 3d 20 22 4e 61 6d 65 esult[0] = "Name
5e90: 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
5ea0: 65 73 75 6c 74 5b 31 5d 20 3d 20 22 41 67 65 22 esult[1] = "Age"
5eb0: 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 ;.** azRe
5ec0: 73 75 6c 74 5b 32 5d 20 3d 20 22 41 6c 69 63 65 sult[2] = "Alice
5ed0: 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
5ee0: 65 73 75 6c 74 5b 33 5d 20 3d 20 22 34 33 22 3b esult[3] = "43";
5ef0: 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 .** azRes
5f00: 75 6c 74 5b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a ult[4] = "Bob";.
5f10: 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
5f20: 6c 74 5b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a lt[5] = "28";.**
5f30: 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
5f40: 5b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a [6] = "Cindy";.*
5f50: 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
5f60: 74 5b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 t[7] = "21";.**
5f70: 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 </pre>.**.** Not
5f80: 69 63 65 20 74 68 61 74 20 74 68 65 72 65 20 69 ice that there i
5f90: 73 20 61 6e 20 65 78 74 72 61 20 72 6f 77 20 6f s an extra row o
5fa0: 66 20 64 61 74 61 20 63 6f 6e 74 61 69 6e 69 6e f data containin
5fb0: 67 20 74 68 65 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 g the column.**
5fc0: 68 65 61 64 65 72 73 2e 20 20 42 75 74 20 74 68 headers. But th
5fd0: 65 20 2a 6e 72 6f 77 20 72 65 74 75 72 6e 20 76 e *nrow return v
5fe0: 61 6c 75 65 20 69 73 20 73 74 69 6c 6c 20 33 2e alue is still 3.
5ff0: 20 20 2a 6e 63 6f 6c 75 6d 6e 20 69 73 0a 2a 2a *ncolumn is.**
6000: 20 73 65 74 20 74 6f 20 32 2e 20 20 49 6e 20 67 set to 2. In g
6010: 65 6e 65 72 61 6c 2c 20 74 68 65 20 6e 75 6d 62 eneral, the numb
6020: 65 72 20 6f 66 20 76 61 6c 75 65 73 20 69 6e 73 er of values ins
6030: 65 72 74 65 64 20 69 6e 74 6f 20 61 7a 52 65 73 erted into azRes
6040: 75 6c 74 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 28 ult.** will be (
6050: 28 2a 6e 72 6f 77 29 20 2b 20 31 29 2a 28 2a 6e (*nrow) + 1)*(*n
6060: 63 6f 6c 75 6d 6e 29 2e 0a 2a 2a 0a 2a 2a 20 41 column)..**.** A
6070: 66 74 65 72 20 74 68 65 20 63 61 6c 6c 69 6e 67 fter the calling
6080: 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20 66 69 function has fi
6090: 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 65 nished using the
60a0: 20 72 65 73 75 6c 74 2c 20 69 74 20 73 68 6f 75 result, it shou
60b0: 6c 64 20 0a 2a 2a 20 70 61 73 73 20 74 68 65 20 ld .** pass the
60c0: 72 65 73 75 6c 74 20 64 61 74 61 20 70 6f 69 6e result data poin
60d0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 ter to sqlite3_f
60e0: 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f ree_table() in o
60f0: 72 64 65 72 20 74 6f 20 0a 2a 2a 20 72 65 6c 65 rder to .** rele
6100: 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 ase the memory t
6110: 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 2d 65 hat was malloc-e
6120: 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 d. Because of t
6130: 68 65 20 77 61 79 20 74 68 65 20 0a 2a 2a 20 5b he way the .** [
6140: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
6150: 5d 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 63 ] happens, the c
6160: 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 alling function
6170: 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 must not try to
6180: 63 61 6c 6c 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 call .** [sqlite
6190: 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 3_free()] direct
61a0: 6c 79 2e 20 20 4f 6e 6c 79 20 5b 73 71 6c 69 74 ly. Only [sqlit
61b0: 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d e3_free_table()]
61c0: 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 is able to rele
61d0: 61 73 65 20 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f ase .** the memo
61e0: 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 ry properly and
61f0: 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 safely..**.** Th
6200: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f e return value o
6210: 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 f this routine i
6220: 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 66 72 s the same as fr
6230: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 om [sqlite3_exec
6240: 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ()]..*/.int sqli
6250: 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 te3_get_table(.
6260: 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 sqlite3*,
6270: 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 /* An op
6280: 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 en database */.
6290: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c const char *sql
62a0: 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 , /* SQL t
62b0: 6f 20 62 65 20 65 78 65 63 75 74 65 64 20 2a 2f o be executed */
62c0: 0a 20 20 63 68 61 72 20 2a 2a 2a 72 65 73 75 6c . char ***resul
62d0: 74 70 2c 20 20 20 20 20 20 20 2f 2a 20 52 65 73 tp, /* Res
62e0: 75 6c 74 20 77 72 69 74 74 65 6e 20 74 6f 20 61 ult written to a
62f0: 20 63 68 61 72 20 2a 5b 5d 20 20 74 68 61 74 20 char *[] that
6300: 74 68 69 73 20 70 6f 69 6e 74 73 20 74 6f 20 2a this points to *
6310: 2f 0a 20 20 69 6e 74 20 2a 6e 72 6f 77 2c 20 20 /. int *nrow,
6320: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 /* Nu
6330: 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 mber of result r
6340: 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 ows written here
6350: 20 2a 2f 0a 20 20 69 6e 74 20 2a 6e 63 6f 6c 75 */. int *ncolu
6360: 6d 6e 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 mn, /*
6370: 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 Number of result
6380: 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e columns written
6390: 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 here */. char
63a0: 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 **errmsg
63b0: 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 /* Error msg w
63c0: 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 ritten here */.)
63d0: 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 ;.void sqlite3_f
63e0: 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a ree_table(char *
63f0: 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a *result);../*.**
6400: 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 CAPI3REF: Forma
6410: 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e tted String Prin
6420: 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a ting Functions.*
6430: 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
6440: 6e 65 73 20 61 72 65 20 77 6f 72 6b 61 6c 69 6b nes are workalik
6450: 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 es of the "print
6460: 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 f()" family of f
6470: 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d unctions.** from
6480: 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 the standard C
6490: 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 library..**.** T
64a0: 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e he sqlite3_mprin
64b0: 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 tf() and sqlite3
64c0: 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 _vmprintf() rout
64d0: 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 ines write their
64e0: 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f .** results into
64f0: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 memory obtained
6500: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 5f 6d 61 from [sqlite_ma
6510: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 lloc()]..** The
6520: 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 strings returned
6530: 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f by these two ro
6540: 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 utines should be
6550: 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 .** released by
6560: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
6570: 2e 20 20 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 . Both routines
6580: 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c return a.** NUL
6590: 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 L pointer if [sq
65a0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
65b0: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c is unable to all
65c0: 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 ocate enough.**
65d0: 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 memory to hold t
65e0: 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 he resulting str
65f0: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71 ing..**.** In sq
6600: 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 lite3_snprintf()
6610: 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 routine is simi
6620: 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 lar to "snprintf
6630: 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 ()" from.** the
6640: 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 standard C libra
6650: 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 ry. The result
6660: 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 is written into
6670: 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 the.** buffer su
6680: 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 pplied as the se
6690: 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 cond parameter w
66a0: 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 hose size is giv
66b0: 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 en by.** the fir
66c0: 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 20 4e st parameter. N
66d0: 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 ote that the ord
66e0: 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 er of the.** fir
66f0: 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 st two parameter
6700: 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 s is reversed fr
6710: 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 20 20 om snprintf().
6720: 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 This is an.** hi
6730: 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e storical acciden
6740: 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 t that cannot be
6750: 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 fixed without b
6760: 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 reaking.** backw
6770: 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 ards compatibili
6780: 74 79 2e 20 20 4e 6f 74 65 20 61 6c 73 6f 20 74 ty. Note also t
6790: 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 hat sqlite3_snpr
67a0: 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e intf().** return
67b0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 s a pointer to i
67c0: 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 ts buffer instea
67d0: 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 d of the number
67e0: 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 of.** characters
67f0: 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 actually writte
6800: 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 n into the buffe
6810: 72 2e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 r. We admit tha
6820: 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 t.** the number
6830: 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 of characters wr
6840: 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 itten would be a
6850: 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 more useful ret
6860: 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 urn.** value but
6870: 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 we cannot chang
6880: 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 e the implementa
6890: 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f tion of sqlite3_
68a0: 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f snprintf().** no
68b0: 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 w without breaki
68c0: 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ng compatibility
68d0: 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 ..**.** As long
68e0: 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 as the buffer si
68f0: 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 ze is greater th
6900: 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 an zero, sqlite3
6910: 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 _snprintf().** g
6920: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 uarantees that t
6930: 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 he buffer is alw
6940: 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 ays zero-termina
6950: 74 65 64 2e 20 20 54 68 65 20 66 69 72 73 74 0a ted. The first.
6960: 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 ** parameter "n"
6970: 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 is the total si
6980: 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 ze of the buffer
6990: 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 , including spac
69a0: 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 e for.** the zer
69b0: 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 o terminator. S
69c0: 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 o the longest st
69d0: 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 ring that can be
69e0: 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 completely.** w
69f0: 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e ritten will be n
6a00: 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a -1 characters..*
6a10: 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
6a20: 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e nes all implemen
6a30: 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 t some additiona
6a40: 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 l formatting.**
6a50: 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 options that are
6a60: 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 useful for cons
6a70: 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 tructing SQL sta
6a80: 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 tements..** All
6a90: 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 of the usual pri
6aa0: 6e 74 66 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f ntf formatting o
6ab0: 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 ptions apply. I
6ac0: 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 n addition, ther
6ad0: 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 e.** is are "%q"
6ae0: 20 61 6e 64 20 22 25 51 22 20 6f 70 74 69 6f 6e and "%Q" option
6af0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 s..**.** The %q
6b00: 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b option works lik
6b10: 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 e %s in that it
6b20: 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 substitutes a nu
6b30: 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ll-terminated.**
6b40: 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 string from the
6b50: 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 argument list.
6b60: 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 But %q also dou
6b70: 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 bles every '\''
6b80: 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 character..** %q
6b90: 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 is designed for
6ba0: 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 use inside a st
6bb0: 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 ring literal. B
6bc0: 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 y doubling each
6bd0: 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 '\''.** characte
6be0: 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61 r it escapes tha
6bf0: 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 t character and
6c00: 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 allows it to be
6c10: 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a inserted into.**
6c20: 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a the string..**.
6c30: 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 ** For example,
6c40: 73 6f 20 73 6f 6d 65 20 73 74 72 69 6e 67 20 76 so some string v
6c50: 61 72 69 61 62 6c 65 20 63 6f 6e 74 61 69 6e 73 ariable contains
6c60: 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 text as follows
6c70: 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
6c80: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 ote><pre>.** ch
6c90: 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 ar *zText = "It'
6ca0: 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b s a happy day!";
6cb0: 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
6cc0: 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e kquote>.**.** On
6cd0: 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 e can use this t
6ce0: 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 ext in an SQL st
6cf0: 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f atement as follo
6d00: 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b ws:.**.** <block
6d10: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
6d20: 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c char *zSQL = sql
6d30: 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e ite3_mprintf("IN
6d40: 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 SERT INTO table
6d50: 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a VALUES('%q')", z
6d60: 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 Text);.** sqlit
6d70: 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c e3_exec(db, zSQL
6d80: 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 , 0, 0, 0);.**
6d90: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 sqlite3_free(zSQ
6da0: 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 L);.** </pre></b
6db0: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
6dc0: 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20 Because the %q
6dd0: 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 format string is
6de0: 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 used, the '\''
6df0: 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 character in zTe
6e00: 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 xt.** is escaped
6e10: 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e and the SQL gen
6e20: 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c erated is as fol
6e30: 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f lows:.**.** <blo
6e40: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a ckquote><pre>.**
6e50: 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 INSERT INTO ta
6e60: 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 ble1 VALUES('It'
6e70: 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 's a happy day!'
6e80: 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f ).** </pre></blo
6e90: 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 ckquote>.**.** T
6ea0: 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 his is correct.
6eb0: 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20 Had we used %s
6ec0: 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 instead of %q, t
6ed0: 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c he generated SQL
6ee0: 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c .** would have l
6ef0: 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a ooked like this:
6f00: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
6f10: 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 te><pre>.** INS
6f20: 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 ERT INTO table1
6f30: 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 VALUES('It's a h
6f40: 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 appy day!');.**
6f50: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
6f60: 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 te>.**.** This s
6f70: 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 econd example is
6f80: 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 an SQL syntax e
6f90: 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 rror. As a gene
6fa0: 72 61 6c 20 72 75 6c 65 20 79 6f 75 0a 2a 2a 20 ral rule you.**
6fb0: 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 20 75 73 should always us
6fc0: 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 e %q instead of
6fd0: 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e %s when insertin
6fe0: 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 g text into a st
6ff0: 72 69 6e 67 20 0a 2a 2a 20 6c 69 74 65 72 61 6c ring .** literal
7000: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 51 20 6f ..**.** The %Q o
7010: 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 ption works like
7020: 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c %q except it al
7030: 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 so adds single q
7040: 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 uotes around.**
7050: 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 the outside of t
7060: 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e he total string.
7070: 20 20 4f 72 20 69 66 20 74 68 65 20 70 61 72 61 Or if the para
7080: 6d 65 74 65 72 20 69 6e 20 74 68 65 20 61 72 67 meter in the arg
7090: 75 6d 65 6e 74 0a 2a 2a 20 6c 69 73 74 20 69 73 ument.** list is
70a0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
70b0: 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 %Q substitutes
70c0: 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 the text "NULL"
70d0: 28 77 69 74 68 6f 75 74 20 73 69 6e 67 6c 65 0a (without single.
70e0: 2a 2a 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c ** quotes) in pl
70f0: 61 63 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70 ace of the %Q op
7100: 74 69 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65 tion. So, for e
7110: 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c xample, one coul
7120: 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c d say:.**.** <bl
7130: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
7140: 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 * char *zSQL =
7150: 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 sqlite3_mprintf(
7160: 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 "INSERT INTO tab
7170: 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 le VALUES(%Q)",
7180: 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 zText);.** sqli
7190: 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 te3_exec(db, zSQ
71a0: 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 L, 0, 0, 0);.**
71b0: 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 sqlite3_free(zS
71c0: 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f QL);.** </pre></
71d0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
71e0: 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 * The code above
71f0: 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 will render a c
7200: 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 orrect SQL state
7210: 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c ment in the zSQL
7220: 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 .** variable eve
7230: 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 n if the zText v
7240: 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c ariable is a NUL
7250: 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 63 68 L pointer..*/.ch
7260: 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 ar *sqlite3_mpri
7270: 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c ntf(const char*,
7280: 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 ...);.char *sqli
7290: 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e te3_vmprintf(con
72a0: 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 st char*, va_lis
72b0: 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 t);.char *sqlite
72c0: 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 3_snprintf(int,c
72d0: 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a har*,const char*
72e0: 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 , ...);../*.** C
72f0: 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 API3REF: Memory
7300: 41 6c 6c 6f 63 61 74 69 6f 6e 20 46 75 6e 63 74 Allocation Funct
7310: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 ions.**.** SQLit
7320: 65 20 75 73 65 73 20 69 74 73 20 6f 77 6e 20 6d e uses its own m
7330: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e emory allocator.
7340: 20 20 4f 6e 20 73 6f 6d 65 20 69 6e 73 74 61 6c On some instal
7350: 6c 61 74 69 6f 6e 73 2c 20 74 68 69 73 0a 2a 2a lations, this.**
7360: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
7370: 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 r is identical t
7380: 6f 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 6d o the standard m
7390: 61 6c 6c 6f 63 28 29 2f 72 65 61 6c 6c 6f 63 28 alloc()/realloc(
73a0: 29 2f 66 72 65 65 28 29 0a 2a 2a 20 61 6e 64 20 )/free().** and
73b0: 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 can be used inte
73c0: 72 63 68 61 6e 67 61 62 6c 65 2e 20 20 4f 6e 20 rchangable. On
73d0: 6f 74 68 65 72 73 2c 20 74 68 65 20 69 6d 70 6c others, the impl
73e0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 61 72 65 0a ementations are.
73f0: 2a 2a 20 64 69 66 66 65 72 65 6e 74 2e 20 20 46 ** different. F
7400: 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 or maximum porta
7410: 62 69 6c 69 74 79 2c 20 69 74 20 69 73 20 62 65 bility, it is be
7420: 73 74 20 6e 6f 74 20 74 6f 20 6d 69 78 20 63 61 st not to mix ca
7430: 6c 6c 73 0a 2a 2a 20 74 6f 20 74 68 65 20 73 74 lls.** to the st
7440: 61 6e 64 61 72 64 20 6d 61 6c 6c 6f 63 2f 72 65 andard malloc/re
7450: 61 6c 6c 6f 63 2f 66 72 65 65 20 77 69 74 68 20 alloc/free with
7460: 74 68 65 20 73 71 6c 69 74 65 20 76 65 72 73 69 the sqlite versi
7470: 6f 6e 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 ons..*/.void *sq
7480: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 lite3_malloc(int
7490: 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 );.void *sqlite3
74a0: 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 _realloc(void*,
74b0: 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 int);.void sqlit
74c0: 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a e3_free(void*);.
74d0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
74e0: 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 Compile-Time Au
74f0: 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c thorization Call
7500: 62 61 63 6b 73 0a 2a 2a 2a 0a 2a 2a 20 54 68 69 backs.***.** Thi
7510: 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 s routine regist
7520: 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72 ers a authorizer
7530: 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 74 callback with t
7540: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 he SQLite librar
7550: 79 2e 20 20 0a 2a 2a 20 54 68 65 20 61 75 74 68 y. .** The auth
7560: 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
7570: 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 is invoked as SQ
7580: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 L statements are
7590: 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a being compiled.
75a0: 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 ** by [sqlite3_p
75b0: 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 repare()] or its
75c0: 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 variants [sqlit
75d0: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
75e0: 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 ,.** [sqlite3_pr
75f0: 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b epare16()] and [
7600: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
7610: 36 5f 76 32 28 29 5d 2e 20 20 41 74 20 76 61 72 6_v2()]. At var
7620: 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 ious.** points d
7630: 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c uring the compil
7640: 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 ation process, a
7650: 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 s logic is being
7660: 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 created.** to p
7670: 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 erform various a
7680: 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 ctions, the auth
7690: 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
76a0: 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a is invoked to.**
76b0: 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 see if those ac
76c0: 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 tions are allowe
76d0: 64 2e 20 20 54 68 65 20 61 75 74 68 6f 72 69 7a d. The authoriz
76e0: 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 er callback shou
76f0: 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 53 51 4c ld.** return SQL
7700: 49 54 45 5f 4f 4b 20 74 6f 20 61 6c 6c 6f 77 20 ITE_OK to allow
7710: 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c the action, [SQL
7720: 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 ITE_IGNORE] to d
7730: 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 isallow the.** s
7740: 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 pecific action b
7750: 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c ut allow the SQL
7760: 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f statement to co
7770: 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 ntinue to be.**
7780: 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 compiled, or [SQ
7790: 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 LITE_DENY] to ca
77a0: 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 use the entire S
77b0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 QL statement to
77c0: 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 be.** rejected w
77d0: 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 0a ith an error. .
77e0: 2a 2a 0a 2a 2a 20 44 65 70 65 6e 64 69 6e 67 20 **.** Depending
77f0: 6f 6e 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 74 on the action, t
7800: 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 he [SQLITE_IGNOR
7810: 45 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 44 E] and [SQLITE_D
7820: 45 4e 59 5d 20 72 65 74 75 72 6e 0a 2a 2a 20 63 ENY] return.** c
7830: 6f 64 65 73 20 6d 69 67 68 74 20 6d 65 61 6e 20 odes might mean
7840: 73 6f 6d 65 74 68 69 6e 67 20 64 69 66 66 65 72 something differ
7850: 65 6e 74 20 6f 72 20 74 68 65 79 20 6d 69 67 68 ent or they migh
7860: 74 20 6d 65 61 6e 20 74 68 65 20 73 61 6d 65 0a t mean the same.
7870: 2a 2a 20 74 68 69 6e 67 2e 20 20 49 66 20 74 68 ** thing. If th
7880: 65 20 61 63 74 69 6f 6e 20 69 73 2c 20 66 6f 72 e action is, for
7890: 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 70 65 72 example, to per
78a0: 66 6f 72 6d 20 61 20 64 65 6c 65 74 65 20 6f 70 form a delete op
78b0: 65 72 74 69 6f 6e 2c 0a 2a 2a 20 74 68 65 6e 20 ertion,.** then
78c0: 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 [SQLITE_IGNORE]
78d0: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 and [SQLITE_DENY
78e0: 5d 20 62 6f 74 68 20 63 61 75 73 65 20 74 68 65 ] both cause the
78f0: 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 statement compi
7900: 6c 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 61 69 lation.** to fai
7910: 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e l with an error.
7920: 20 20 42 75 74 20 69 66 20 74 68 65 20 61 63 74 But if the act
7930: 69 6f 6e 20 69 73 20 74 6f 20 72 65 61 64 20 61 ion is to read a
7940: 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e specific column
7950: 0a 2a 2a 20 66 72 6f 6d 20 61 20 73 70 65 63 69 .** from a speci
7960: 66 69 63 20 74 61 62 6c 65 2c 20 74 68 65 6e 20 fic table, then
7970: 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 77 69 [SQLITE_DENY] wi
7980: 6c 6c 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 ll cause the ent
7990: 69 72 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 ire.** statement
79a0: 20 74 6f 20 66 61 69 6c 20 62 75 74 20 5b 53 51 to fail but [SQ
79b0: 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 77 69 6c LITE_IGNORE] wil
79c0: 6c 20 63 61 75 73 65 20 61 20 4e 55 4c 4c 20 76 l cause a NULL v
79d0: 61 6c 75 65 20 74 6f 20 62 65 0a 2a 2a 20 72 65 alue to be.** re
79e0: 61 64 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 ad instead of th
79f0: 65 20 61 63 74 75 61 6c 20 63 6f 6c 75 6d 6e 20 e actual column
7a00: 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 value..**.** The
7a10: 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
7a20: 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a to the authoriz
7a30: 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 er callback is a
7a40: 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 copy of.** the
7a50: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
7a60: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 to the sqlite3_s
7a70: 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 et_authorizer()
7a80: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 54 68 interface..** Th
7a90: 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
7aa0: 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 er to the callba
7ab0: 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 ck is an integer
7ac0: 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 50 .** [SQLITE_COP
7ad0: 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d Y | action code]
7ae0: 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 that specifies
7af0: 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 the particular a
7b00: 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 62 65 20 61 ction.** to be a
7b10: 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 uthorized. The
7b20: 61 76 61 69 6c 61 62 6c 65 20 61 63 74 69 6f 6e available action
7b30: 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 5b 53 codes are.** [S
7b40: 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 64 6f 63 QLITE_COPY | doc
7b50: 75 6d 65 6e 74 65 64 20 73 65 70 61 72 61 74 65 umented separate
7b60: 6c 79 5d 2e 20 20 54 68 65 20 74 68 69 72 64 20 ly]. The third
7b70: 74 68 72 6f 75 67 68 20 73 69 78 74 68 0a 2a 2a through sixth.**
7b80: 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 parameters to t
7b90: 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 he callback are
7ba0: 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e strings that con
7bb0: 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a tain additional.
7bc0: 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 ** details about
7bd0: 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 the action to b
7be0: 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a e authorized..**
7bf0: 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 .** An authorize
7c00: 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 70 r is used when p
7c10: 72 65 70 61 72 69 6e 67 20 53 51 4c 20 73 74 61 reparing SQL sta
7c20: 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 tements from an
7c30: 75 6e 74 72 75 73 74 65 64 0a 2a 2a 20 73 6f 75 untrusted.** sou
7c40: 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 rce, to ensure t
7c50: 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 hat the SQL stat
7c60: 65 6d 65 6e 74 73 20 64 6f 20 6e 6f 74 20 74 72 ements do not tr
7c70: 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 y to access data
7c80: 0a 2a 2a 20 74 68 61 74 20 74 68 65 79 20 61 72 .** that they ar
7c90: 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f e not allowed to
7ca0: 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 see, or that th
7cb0: 65 79 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f ey do not try to
7cc0: 0a 2a 2a 20 65 78 65 63 75 74 65 20 6d 61 6c 69 .** execute mali
7cd0: 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 cious statements
7ce0: 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 that damage the
7cf0: 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a database. For.
7d00: 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 ** example, an a
7d10: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 pplication may a
7d20: 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 llow a user to e
7d30: 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a nter arbitrary.*
7d40: 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f * SQL queries fo
7d50: 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 r evaluation by
7d60: 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 a database. But
7d70: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
7d80: 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e does.** not wan
7d90: 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 t the user to be
7da0: 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 able to make ar
7db0: 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 bitrary changes
7dc0: 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 to the.** databa
7dd0: 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a se. An authoriz
7de0: 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 er could then be
7df0: 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 put in place wh
7e00: 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d ile the.** user-
7e10: 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 entered SQL is b
7e20: 65 69 6e 67 20 70 72 65 70 61 72 65 64 20 74 68 eing prepared th
7e30: 61 74 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 at disallows eve
7e40: 72 79 74 68 69 6e 67 0a 2a 2a 20 65 78 63 65 70 rything.** excep
7e50: 74 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 t SELECT stateme
7e60: 6e 74 73 2e 20 20 0a 2a 2a 0a 2a 2a 20 4f 6e 6c nts. .**.** Onl
7e70: 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f y a single autho
7e80: 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 rizer can be in
7e90: 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 place on a datab
7ea0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase connection.*
7eb0: 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 * at a time. Ea
7ec0: 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 ch call to sqlit
7ed0: 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
7ee0: 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a r overrides the.
7ef0: 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c ** previous call
7f00: 2e 20 20 41 20 4e 55 4c 4c 20 61 75 74 68 6f 72 . A NULL author
7f10: 69 7a 65 72 20 6d 65 61 6e 73 20 74 68 61 74 20 izer means that
7f20: 6e 6f 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e no authorization
7f30: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 .** callback is
7f40: 69 6e 76 6f 6b 65 64 2e 20 20 54 68 65 20 64 65 invoked. The de
7f50: 66 61 75 6c 74 20 61 75 74 68 6f 72 69 7a 65 72 fault authorizer
7f60: 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 is NULL..**.**
7f70: 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 Note that the au
7f80: 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
7f90: 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c k is invoked onl
7fa0: 79 20 64 75 72 69 6e 67 20 0a 2a 2a 20 5b 73 71 y during .** [sq
7fb0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d lite3_prepare()]
7fc0: 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 or its variants
7fd0: 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e . Authorization
7fe0: 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f is not.** perfo
7ff0: 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 rmed during stat
8000: 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e ement evaluation
8010: 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 in [sqlite3_ste
8020: 70 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c p()]..*/.int sql
8030: 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
8040: 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c zer(. sqlite3*,
8050: 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 . int (*xAuth)(
8060: 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 void*,int,const
8070: 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 char*,const char
8080: 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f *,const char*,co
8090: 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f nst char*),. vo
80a0: 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b id *pUserData.);
80b0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
80c0: 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 : Authorizer Ret
80d0: 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 urn Codes.**.**
80e0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 The [sqlite3_set
80f0: 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 _authorizer | au
8100: 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
8110: 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 k function] must
8120: 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 .** return eithe
8130: 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 r [SQLITE_OK] or
8140: 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 one of these tw
8150: 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f o constants in o
8160: 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 rder.** to signa
8170: 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 l SQLite whether
8180: 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 or not the acti
8190: 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e on is permitted.
81a0: 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 See the.** [sq
81b0: 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
81c0: 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 izer | authorize
81d0: 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d r documentation]
81e0: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a for additional.
81f0: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a ** information..
8200: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
8210: 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 E_DENY 1 /*
8220: 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 Abort the SQL st
8230: 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 atement with an
8240: 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 error */.#define
8250: 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 SQLITE_IGNORE 2
8260: 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f /* Don't allo
8270: 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f w access, but do
8280: 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 n't generate an
8290: 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 error */../*.**
82a0: 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 CAPI3REF: Author
82b0: 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 izer Action Code
82c0: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c s.**.** The [sql
82d0: 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
82e0: 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 zer()] interface
82f0: 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c registers a cal
8300: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a lback function.*
8310: 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 * that is invoke
8320: 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 72 20 d to authorizer
8330: 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 certain SQL stat
8340: 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 ement actions.
8350: 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 The.** second pa
8360: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 rameter to the c
8370: 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e allback is an in
8380: 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 teger code that
8390: 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 specifies.** wha
83a0: 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e t action is bein
83b0: 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 g authorized. T
83c0: 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 hese are the int
83d0: 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 eger action code
83e0: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 s that.** the au
83f0: 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
8400: 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e k may be passed.
8410: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 .**.** These act
8420: 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 ion code values
8430: 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e signify what kin
8440: 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 d of operation i
8450: 73 20 74 6f 20 62 65 20 0a 2a 2a 20 61 75 74 68 s to be .** auth
8460: 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 orized. The 3rd
8470: 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 and 4th paramet
8480: 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f ers to the autho
8490: 72 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 rization callbac
84a0: 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 k.** function wi
84b0: 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 ll be parameters
84c0: 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 or NULL dependi
84d0: 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 ng on which of t
84e0: 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 hese.** codes is
84f0: 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 used as the sec
8500: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 ond parameter.
8510: 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 The 5th paramete
8520: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 r to the.** auth
8530: 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
8540: 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 is the name of t
8550: 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 he database ("ma
8560: 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 0a 2a 2a in", "temp", .**
8570: 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 etc.) if applic
8580: 61 62 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70 able. The 6th p
8590: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
85a0: 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
85b0: 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 ack.** is the na
85c0: 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d me of the inner-
85d0: 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 most trigger or
85e0: 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 view that is res
85f0: 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 ponsible for.**
8600: 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d the access attem
8610: 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 pt or NULL if th
8620: 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 is access attemp
8630: 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 t is directly fr
8640: 6f 6d 20 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c om .** top-level
8650: 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a SQL code..*/./*
8660: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
8670: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
8680: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a ********** 3rd *
8690: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 *********** 4th
86a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 ***********/.#de
86b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
86c0: 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 TE_INDEX
86d0: 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 1 /* Index N
86e0: 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e ame Table N
86f0: 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
8700: 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
8710: 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 E_TABLE
8720: 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 2 /* Table Na
8730: 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
8740: 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
8750: 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
8760: 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 _TEMP_INDEX
8770: 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 3 /* Index Nam
8780: 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d e Table Nam
8790: 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
87a0: 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
87b0: 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 TEMP_TABLE 4
87c0: 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
87d0: 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
87e0: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
87f0: 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 SQLITE_CREATE_T
8800: 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 EMP_TRIGGER 5
8810: 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d /* Trigger Nam
8820: 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 e Table Name
8830: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
8840: 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 SQLITE_CREATE_TE
8850: 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 MP_VIEW 6
8860: 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 /* View Name
8870: 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
8880: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
8890: 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 QLITE_CREATE_TRI
88a0: 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20 GGER 7
88b0: 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 /* Trigger Name
88c0: 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
88d0: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
88e0: 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 LITE_CREATE_VIEW
88f0: 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 8 /
8900: 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 * View Name
8910: 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
8920: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
8930: 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 ITE_DELETE
8940: 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 9 /*
8950: 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
8960: 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
8970: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
8980: 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 TE_DROP_INDEX
8990: 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 10 /*
89a0: 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 Index Name
89b0: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
89c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
89d0: 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 E_DROP_TABLE
89e0: 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 11 /* T
89f0: 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e able Name N
8a00: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
8a10: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
8a20: 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 _DROP_TEMP_INDEX
8a30: 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 12 /* In
8a40: 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 dex Name Ta
8a50: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
8a60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8a70: 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 DROP_TEMP_TABLE
8a80: 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 13 /* Tab
8a90: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
8aa0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
8ab0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
8ac0: 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 ROP_TEMP_TRIGGER
8ad0: 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 14 /* Trig
8ae0: 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c ger Name Tabl
8af0: 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
8b00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
8b10: 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 OP_TEMP_VIEW
8b20: 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 15 /* View
8b30: 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
8b40: 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
8b50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
8b60: 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 P_TRIGGER
8b70: 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 16 /* Trigge
8b80: 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 r Name Table
8b90: 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
8ba0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
8bb0: 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 _VIEW
8bc0: 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 17 /* View Na
8bd0: 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 me NULL
8be0: 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
8bf0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 ine SQLITE_INSER
8c00: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 T
8c10: 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 18 /* Table Na
8c20: 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
8c30: 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
8c40: 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 ne SQLITE_PRAGMA
8c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 1
8c60: 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 9 /* Pragma Na
8c70: 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f me 1st arg o
8c80: 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e r NULL */.#defin
8c90: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 e SQLITE_READ
8ca0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20
8cb0: 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
8cc0: 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d Column Nam
8cd0: 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 e */.#define
8ce0: 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 SQLITE_SELECT
8cf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20 21
8d00: 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 /* NULL
8d10: 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
8d20: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
8d30: 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 SQLITE_TRANSACTI
8d40: 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20 ON 22
8d50: 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 /* NULL
8d60: 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
8d70: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
8d80: 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 QLITE_UPDATE
8d90: 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20 23
8da0: 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
8db0: 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 Column Name
8dc0: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
8dd0: 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 LITE_ATTACH
8de0: 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 24 /
8df0: 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 * Filename
8e00: 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
8e10: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
8e20: 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 ITE_DETACH
8e30: 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 25 /*
8e40: 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 Database Name
8e50: 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
8e60: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
8e70: 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 TE_ALTER_TABLE
8e80: 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 26 /*
8e90: 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 Database Name
8ea0: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
8eb0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
8ec0: 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 E_REINDEX
8ed0: 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 27 /* I
8ee0: 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e ndex Name N
8ef0: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
8f00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
8f10: 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 _ANALYZE
8f20: 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 28 /* Ta
8f30: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
8f40: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
8f50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8f60: 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 CREATE_VTABLE
8f70: 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 29 /* Tab
8f80: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 le Name Mod
8f90: 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a ule Name */.
8fa0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
8fb0: 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 ROP_VTABLE
8fc0: 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 30 /* Tabl
8fd0: 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 e Name Modu
8fe0: 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 le Name */.#
8ff0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 define SQLITE_FU
9000: 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 NCTION
9010: 20 20 20 33 31 20 20 20 2f 2a 20 46 75 6e 63 74 31 /* Funct
9020: 69 6f 6e 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 ion Name NULL
9030: 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
9040: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 efine SQLITE_COP
9050: 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 Y
9060: 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 0 /* No lon
9070: 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a ger used */../*.
9080: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 ** CAPI3REF: Tra
9090: 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 cing And Profili
90a0: 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a ng Functions.**.
90b0: 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
90c0: 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 s register callb
90d0: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 ack functions th
90e0: 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 at can be used f
90f0: 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e or.** tracing an
9100: 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 d profiling the
9110: 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c execution of SQL
9120: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 statements..**
9130: 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e The callback fun
9140: 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 ction registered
9150: 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 by sqlite3_trac
9160: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a e() is invoked.*
9170: 2a 20 61 74 20 74 68 65 20 66 69 72 73 74 20 5b * at the first [
9180: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
9190: 66 6f 72 20 74 68 65 20 65 76 61 6c 75 61 74 69 for the evaluati
91a0: 6f 6e 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 on of an SQL sta
91b0: 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 63 tement..** The c
91c0: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
91d0: 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 registered by s
91e0: 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 qlite3_profile()
91f0: 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 is invoked.** a
9200: 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 s each SQL state
9210: 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 20 61 6e ment finishes an
9220: 64 20 69 6e 63 6c 75 64 65 73 0a 2a 2a 20 69 6e d includes.** in
9230: 66 6f 72 6d 61 74 69 6f 6e 20 6f 6e 20 68 6f 77 formation on how
9240: 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 long that state
9250: 6d 65 6e 74 20 72 61 6e 2e 0a 2a 2a 0a 2a 2a 20 ment ran..**.**
9260: 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 The sqlite3_prof
9270: 69 6c 65 28 29 20 41 50 49 20 69 73 20 63 75 72 ile() API is cur
9280: 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 rently considere
9290: 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 d experimental a
92a0: 6e 64 0a 2a 2a 20 69 73 20 73 75 62 6a 65 63 74 nd.** is subject
92b0: 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 76 to change..*/.v
92c0: 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 oid *sqlite3_tra
92d0: 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 ce(sqlite3*, voi
92e0: 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a d(*xTrace)(void*
92f0: 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 ,const char*), v
9300: 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c oid*);.void *sql
9310: 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c ite3_profile(sql
9320: 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a ite3*,. void(*
9330: 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c xProfile)(void*,
9340: 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 const char*,sqli
9350: 74 65 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 te_uint64), void
9360: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
9370: 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 REF: Query Progr
9380: 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a ess Callbacks.**
9390: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
93a0: 20 63 6f 6e 66 69 67 75 72 65 73 20 61 20 63 61 configures a ca
93b0: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
93c0: 2d 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 - the progress c
93d0: 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74 0a 2a allback - that.*
93e0: 2a 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 * is invoked per
93f0: 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 iodically during
9400: 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 long running ca
9410: 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
9420: 65 78 65 63 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c exec()],.** [sql
9430: 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 ite3_step()] and
9440: 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 [sqlite3_get_ta
9450: 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d ble()]. An exam
9460: 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 ple use for this
9470: 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 .** interface i
9480: 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 s to keep a GUI
9490: 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 updated during a
94a0: 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a large query..**
94b0: 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 .** The progress
94c0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
94d0: 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 76 oked once for ev
94e0: 65 72 79 20 4e 20 76 69 72 74 75 61 6c 20 6d 61 ery N virtual ma
94f0: 63 68 69 6e 65 20 6f 70 63 6f 64 65 73 2c 0a 2a chine opcodes,.*
9500: 2a 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 * where N is the
9510: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
9520: 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f to this functio
9530: 6e 2e 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 n. The progress
9540: 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 74 73 65 callback.** itse
9550: 6c 66 20 69 73 20 69 64 65 6e 74 69 66 69 65 64 lf is identified
9560: 20 62 79 20 74 68 65 20 74 68 69 72 64 20 61 72 by the third ar
9570: 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 66 gument to this f
9580: 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 66 6f 75 unction. The fou
9590: 72 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 rth.** argument
95a0: 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e to this function
95b0: 20 69 73 20 61 20 76 6f 69 64 20 70 6f 69 6e 74 is a void point
95c0: 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 er passed to the
95d0: 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 progress callba
95e0: 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 65 ck.** function e
95f0: 61 63 68 20 74 69 6d 65 20 69 74 20 69 73 20 69 ach time it is i
9600: 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 nvoked..**.** If
9610: 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 a call to [sqli
9620: 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 te3_exec()], [sq
9630: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 6f lite3_step()], o
9640: 72 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 r [sqlite3_get_t
9650: 61 62 6c 65 28 29 5d 0a 2a 2a 20 72 65 73 75 6c able()].** resul
9660: 74 73 20 69 6e 20 66 65 77 65 72 20 74 68 61 6e ts in fewer than
9670: 20 4e 20 6f 70 63 6f 64 65 73 20 62 65 69 6e 67 N opcodes being
9680: 20 65 78 65 63 75 74 65 64 2c 20 74 68 65 6e 20 executed, then
9690: 74 68 65 20 70 72 6f 67 72 65 73 73 20 0a 2a 2a the progress .**
96a0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 65 76 callback is nev
96b0: 65 72 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 0a er invoked..** .
96c0: 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 ** Only a single
96d0: 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 progress callba
96e0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 ck function may
96f0: 62 65 20 72 65 67 69 73 74 65 72 65 64 20 66 6f be registered fo
9700: 72 20 65 61 63 68 0a 2a 2a 20 6f 70 65 6e 20 64 r each.** open d
9710: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
9720: 6f 6e 2e 20 20 45 76 65 72 79 20 63 61 6c 6c 20 on. Every call
9730: 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 to sqlite3_progr
9740: 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 0a 2a 2a ess_handler().**
9750: 20 6f 76 65 72 77 72 69 74 65 73 20 74 68 65 20 overwrites the
9760: 72 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 70 results of the p
9770: 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 0a 2a 2a revious call..**
9780: 20 54 6f 20 72 65 6d 6f 76 65 20 74 68 65 20 70 To remove the p
9790: 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b rogress callback
97a0: 20 61 6c 74 6f 67 65 74 68 65 72 2c 20 70 61 73 altogether, pas
97b0: 73 20 4e 55 4c 4c 20 61 73 20 74 68 65 20 74 68 s NULL as the th
97c0: 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 ird.** argument
97d0: 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e to this function
97e0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 70 ..**.** If the p
97f0: 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b rogress callback
9800: 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c returns a resul
9810: 74 20 6f 74 68 65 72 20 74 68 61 6e 20 30 2c 20 t other than 0,
9820: 74 68 65 6e 20 74 68 65 20 63 75 72 72 65 6e 74 then the current
9830: 20 0a 2a 2a 20 71 75 65 72 79 20 69 73 20 69 6d .** query is im
9840: 6d 65 64 69 61 74 65 6c 79 20 74 65 72 6d 69 6e mediately termin
9850: 61 74 65 64 20 61 6e 64 20 61 6e 79 20 64 61 74 ated and any dat
9860: 61 62 61 73 65 20 63 68 61 6e 67 65 73 20 72 6f abase changes ro
9870: 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 54 68 lled back..** Th
9880: 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 5b 73 71 e containing [sq
9890: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b lite3_exec()], [
98a0: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c sqlite3_step()],
98b0: 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
98c0: 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 63 61 6c get_table()] cal
98d0: 6c 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 l returns SQLITE
98e0: 5f 49 4e 54 45 52 52 55 50 54 2e 20 20 20 54 68 _INTERRUPT. Th
98f0: 69 73 20 66 65 61 74 75 72 65 0a 2a 2a 20 63 61 is feature.** ca
9900: 6e 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 n be used, for e
9910: 78 61 6d 70 6c 65 2c 20 74 6f 20 69 6d 70 6c 65 xample, to imple
9920: 6d 65 6e 74 20 74 68 65 20 22 43 61 6e 63 65 6c ment the "Cancel
9930: 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 0a 2a 2a " button on a.**
9940: 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 progress dialog
9950: 20 62 6f 78 20 69 6e 20 61 20 47 55 49 2e 0a 2a box in a GUI..*
9960: 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 /.void sqlite3_p
9970: 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 rogress_handler(
9980: 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 sqlite3*, int, i
9990: 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f nt(*)(void*), vo
99a0: 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 id*);../*.** CAP
99b0: 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 I3REF: Opening A
99c0: 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f New Database Co
99d0: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 4f nnection.**.** O
99e0: 70 65 6e 20 74 68 65 20 73 71 6c 69 74 65 20 64 pen the sqlite d
99f0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 66 69 atabase file "fi
9a00: 6c 65 6e 61 6d 65 22 2e 20 20 54 68 65 20 22 66 lename". The "f
9a10: 69 6c 65 6e 61 6d 65 22 20 69 73 20 55 54 46 2d ilename" is UTF-
9a20: 38 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 66 6f 72 8.** encoded for
9a30: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 sqlite3_open()
9a40: 61 6e 64 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 and UTF-16 encod
9a50: 65 64 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 ed in the native
9a60: 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 66 byte order.** f
9a70: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 or sqlite3_open1
9a80: 36 28 29 2e 20 20 41 6e 20 5b 73 71 6c 69 74 65 6(). An [sqlite
9a90: 33 2a 5d 20 68 61 6e 64 6c 65 20 69 73 20 72 65 3*] handle is re
9aa0: 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c turned in *ppDb,
9ab0: 20 65 76 65 6e 0a 2a 2a 20 69 66 20 61 6e 20 65 even.** if an e
9ac0: 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 49 66 20 rror occurs. If
9ad0: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 the database is
9ae0: 6f 70 65 6e 65 64 20 28 6f 72 20 63 72 65 61 74 opened (or creat
9af0: 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 ed) successfully
9b00: 2c 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 49 54 45 ,.** then SQLITE
9b10: 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e _OK is returned.
9b20: 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 Otherwise an er
9b30: 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 ror code is retu
9b40: 72 6e 65 64 2e 20 54 68 65 0a 2a 2a 20 73 71 6c rned. The.** sql
9b50: 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 6f 72 ite3_errmsg() or
9b60: 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 sqlite3_errmsg1
9b70: 36 28 29 20 20 72 6f 75 74 69 6e 65 73 20 63 61 6() routines ca
9b80: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 n be used to obt
9b90: 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 ain.** an Englis
9ba0: 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 h language descr
9bb0: 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 iption of the er
9bc0: 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ror..**.** If th
9bd0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
9be0: 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 2c 20 does not exist,
9bf0: 74 68 65 6e 20 61 20 6e 65 77 20 64 61 74 61 62 then a new datab
9c00: 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 ase will be crea
9c10: 74 65 64 0a 2a 2a 20 61 73 20 6e 65 65 64 65 64 ted.** as needed
9c20: 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 65 . The default e
9c30: 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 ncoding for the
9c40: 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 database will be
9c50: 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c UTF-8 if.** sql
9c60: 69 74 65 33 5f 6f 70 65 6e 28 29 20 69 73 20 63 ite3_open() is c
9c70: 61 6c 6c 65 64 20 61 6e 64 20 55 54 46 2d 31 36 alled and UTF-16
9c80: 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e if sqlite3_open
9c90: 31 36 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 16 is used..**.*
9ca0: 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 * Whether or not
9cb0: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 an error occurs
9cc0: 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e when it is open
9cd0: 65 64 2c 20 72 65 73 6f 75 72 63 65 73 20 61 73 ed, resources as
9ce0: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 sociated.** with
9cf0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20 the [sqlite3*]
9d00: 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 handle should be
9d10: 20 72 65 6c 65 61 73 65 64 20 62 79 20 70 61 73 released by pas
9d20: 73 69 6e 67 20 69 74 20 74 6f 0a 2a 2a 20 73 71 sing it to.** sq
9d30: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 77 68 lite3_close() wh
9d40: 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 en it is no long
9d50: 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a er required..**.
9d60: 2a 2a 20 4e 6f 74 65 20 74 6f 20 77 69 6e 64 6f ** Note to windo
9d70: 77 73 20 75 73 65 72 73 3a 20 20 54 68 65 20 65 ws users: The e
9d80: 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 ncoding used for
9d90: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 the filename ar
9da0: 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c gument.** of sql
9db0: 69 74 65 33 5f 6f 70 65 6e 28 29 20 6d 75 73 74 ite3_open() must
9dc0: 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 be UTF-8, not w
9dd0: 68 61 74 65 76 65 72 20 63 6f 64 65 70 61 67 65 hatever codepage
9de0: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a is currently.**
9df0: 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e defined. Filen
9e00: 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 ames containing
9e10: 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 20 63 68 international ch
9e20: 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 aracters must be
9e30: 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 74 6f converted.** to
9e40: 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 UTF-8 prior to
9e50: 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 passing them int
9e60: 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 o sqlite3_open()
9e70: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
9e80: 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 _open(. const c
9e90: 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 har *filename,
9ea0: 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c /* Database fil
9eb0: 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f ename (UTF-8) */
9ec0: 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 . sqlite3 **ppD
9ed0: 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 b /* OU
9ee0: 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e T: SQLite db han
9ef0: 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 dle */.);.int sq
9f00: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 lite3_open16(.
9f10: 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 const void *file
9f20: 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 name, /* Datab
9f30: 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 ase filename (UT
9f40: 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 F-16) */. sqlit
9f50: 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 e3 **ppDb
9f60: 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 /* OUT: SQLit
9f70: 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 e db handle */.)
9f80: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
9f90: 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 F: Error Codes A
9fa0: 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a nd Messages.**.*
9fb0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 * The sqlite3_er
9fc0: 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 rcode() interfac
9fd0: 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 e returns the nu
9fe0: 6d 65 72 69 63 0a 2a 2a 20 5b 53 51 4c 49 54 45 meric.** [SQLITE
9ff0: 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 _OK | result cod
a000: 65 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f e] or [SQLITE_IO
a010: 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e ERR_READ | exten
a020: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d ded result code]
a030: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 .** for the most
a040: 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 recent failed s
a050: 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c qlite3_* API cal
a060: 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 l associated.**
a070: 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5d 20 68 with [sqlite3] h
a080: 61 6e 64 6c 65 20 27 64 62 27 2e 20 20 49 66 20 andle 'db'. If
a090: 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c a prior API call
a0a0: 20 66 61 69 6c 65 64 20 62 75 74 20 74 68 65 0a failed but the.
a0b0: 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 ** most recent A
a0c0: 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 PI call succeede
a0d0: 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 d, the return va
a0e0: 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 lue from sqlite3
a0f0: 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 73 _errcode().** is
a100: 20 75 6e 64 65 66 69 6e 65 64 2e 20 0a 2a 2a 0a undefined. .**.
a110: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 ** The sqlite3_e
a120: 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 rrmsg() and sqli
a130: 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 te3_errmsg16() r
a140: 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 eturn English-la
a150: 6e 67 61 75 67 65 0a 2a 2a 20 74 65 78 74 20 74 ngauge.** text t
a160: 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 hat describes th
a170: 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 e error, as eith
a180: 65 72 20 55 54 46 38 20 6f 72 20 55 54 46 31 36 er UTF8 or UTF16
a190: 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a respectively..*
a1a0: 2a 20 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 * Memory to hold
a1b0: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 the error messa
a1c0: 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e ge string is man
a1d0: 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e aged internally.
a1e0: 20 20 54 68 65 20 0a 2a 2a 20 73 74 72 69 6e 67 The .** string
a1f0: 20 6d 61 79 20 62 65 20 6f 76 65 72 77 72 69 74 may be overwrit
a200: 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 ten or deallocat
a210: 65 64 20 62 79 20 73 75 62 73 65 71 75 65 6e 74 ed by subsequent
a220: 20 63 61 6c 6c 73 20 74 6f 20 53 51 4c 69 74 65 calls to SQLite
a230: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66 75 .** interface fu
a240: 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 43 nctions..**.** C
a250: 61 6c 6c 73 20 74 6f 20 6d 61 6e 79 20 73 71 6c alls to many sql
a260: 69 74 65 33 5f 2a 20 66 75 6e 63 74 69 6f 6e 73 ite3_* functions
a270: 20 73 65 74 20 74 68 65 20 65 72 72 6f 72 20 63 set the error c
a280: 6f 64 65 20 61 6e 64 20 73 74 72 69 6e 67 20 72 ode and string r
a290: 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 eturned.** by [s
a2a0: 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 qlite3_errcode()
a2b0: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d ], [sqlite3_errm
a2c0: 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 sg()], and [sqli
a2d0: 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 0a te3_errmsg16()].
a2e0: 2a 2a 20 28 6f 76 65 72 77 72 69 74 69 6e 67 20 ** (overwriting
a2f0: 74 68 65 20 70 72 65 76 69 6f 75 73 20 76 61 6c the previous val
a300: 75 65 73 29 2e 20 4e 6f 74 65 20 74 68 61 74 20 ues). Note that
a310: 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
a320: 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 3_errcode()],.**
a330: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
a340: 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 ()], and [sqlite
a350: 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 74 68 3_errmsg16()] th
a360: 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 emselves do not
a370: 61 66 66 65 63 74 20 74 68 65 0a 2a 2a 20 72 65 affect the.** re
a380: 73 75 6c 74 73 20 6f 66 20 66 75 74 75 72 65 20 sults of future
a390: 69 6e 76 6f 63 61 74 69 6f 6e 73 2e 20 20 43 61 invocations. Ca
a3a0: 6c 6c 73 20 74 6f 20 41 50 49 20 72 6f 75 74 69 lls to API routi
a3b0: 6e 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 nes that do not
a3c0: 72 65 74 75 72 6e 0a 2a 2a 20 61 6e 20 65 72 72 return.** an err
a3d0: 6f 72 20 63 6f 64 65 20 28 65 78 61 6d 70 6c 65 or code (example
a3e0: 73 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 s: [sqlite3_data
a3f0: 5f 63 6f 75 6e 74 28 29 5d 20 6f 72 20 5b 73 71 _count()] or [sq
a400: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d lite3_mprintf()]
a410: 29 20 64 6f 0a 2a 2a 20 6e 6f 74 20 63 68 61 6e ) do.** not chan
a420: 67 65 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 ge the error cod
a430: 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 e returned by th
a440: 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a 2a is routine..**.*
a450: 2a 20 41 73 73 75 6d 69 6e 67 20 6e 6f 20 6f 74 * Assuming no ot
a460: 68 65 72 20 69 6e 74 65 72 76 65 6e 69 6e 67 20 her intervening
a470: 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 sqlite3_* API ca
a480: 6c 6c 73 20 61 72 65 20 6d 61 64 65 2c 20 74 68 lls are made, th
a490: 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 e error.** code
a4a0: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 returned by this
a4b0: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 73 73 function is ass
a4c0: 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 ociated with the
a4d0: 20 73 61 6d 65 20 65 72 72 6f 72 20 61 73 0a 2a same error as.*
a4e0: 2a 20 74 68 65 20 73 74 72 69 6e 67 73 20 72 65 * the strings re
a4f0: 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
a500: 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 e3_errmsg()] and
a510: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
a520: 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 16()]..*/.int sq
a530: 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 lite3_errcode(sq
a540: 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 lite3 *db);.cons
a550: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
a560: 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 errmsg(sqlite3*)
a570: 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 ;.const void *sq
a580: 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 lite3_errmsg16(s
a590: 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
a5a0: 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 CAPI3REF: SQL S
a5b0: 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a tatement Object.
a5c0: 2a 2a 0a 2a 2a 20 49 6e 73 74 61 6e 63 65 20 6f **.** Instance o
a5d0: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 f this object re
a5e0: 70 72 65 73 65 6e 74 20 73 69 6e 67 6c 65 20 53 present single S
a5f0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 QL statements.
a600: 54 68 69 73 0a 2a 2a 20 69 73 20 76 61 72 69 6f This.** is vario
a610: 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 usly known as a
a620: 22 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d "prepared statem
a630: 65 6e 74 22 20 6f 72 20 61 20 0a 2a 2a 20 22 63 ent" or a .** "c
a640: 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 ompiled SQL stat
a650: 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 ement" or simply
a660: 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 as a "statement
a670: 22 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 6c 69 "..** .** The li
a680: 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e fe of a statemen
a690: 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f t object goes so
a6a0: 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 mething like thi
a6b0: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a s:.**.** <ol>.**
a6c0: 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 <li> Create the
a6d0: 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 object using [s
a6e0: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
a6f0: 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 2()] or a relate
a700: 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69 d.** functi
a710: 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 on..** <li> Bind
a720: 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 values to host
a730: 70 61 72 61 6d 65 74 65 72 73 20 75 73 69 6e 67 parameters using
a740: 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74 65 .** [sqlite
a750: 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 3_bind_blob | sq
a760: 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 69 6e 74 lite3_bind_* int
a770: 65 72 66 61 63 65 73 5d 2e 0a 2a 2a 20 3c 6c 69 erfaces]..** <li
a780: 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 > Run the SQL by
a790: 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
a7a0: 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 3_step()] one or
a7b0: 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 more times..**
a7c0: 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 <li> Reset the s
a7d0: 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b tatement using [
a7e0: 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
a7f0: 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a then go back.**
a800: 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e to step 2.
a810: 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f Do this zero o
a820: 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a r more times..**
a830: 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 <li> Destroy th
a840: 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b e object using [
a850: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
a860: 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a ()]..** </ol>.**
a870: 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 .** Refer to doc
a880: 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e umentation on in
a890: 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 dividual methods
a8a0: 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 above for addit
a8b0: 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 ional.** informa
a8c0: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 tion..*/.typedef
a8d0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
a8e0: 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d stmt sqlite3_stm
a8f0: 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 t;../*.** CAPI3R
a900: 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e EF: Compiling An
a910: 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a SQL Statement.*
a920: 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 *.** To execute
a930: 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 an SQL query, it
a940: 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 must first be c
a950: 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 ompiled into a b
a960: 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 yte-code.** prog
a970: 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 ram using one of
a980: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e these routines.
a990: 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 .**.** The firs
a9a0: 74 20 61 72 67 75 6d 65 6e 74 20 22 64 62 22 20 t argument "db"
a9b0: 69 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 20 7c is an [sqlite3 |
a9c0: 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 SQLite database
a9d0: 20 68 61 6e 64 6c 65 5d 20 0a 2a 2a 20 6f 62 74 handle] .** obt
a9e0: 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 ained from a pri
a9f0: 6f 72 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 or call to [sqli
aa00: 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b te3_open()] or [
aa10: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
aa20: 5d 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 ]..** The second
aa30: 20 61 72 67 75 6d 65 6e 74 20 22 7a 53 71 6c 22 argument "zSql"
aa40: 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e is the statemen
aa50: 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 t to be compiled
aa60: 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 , encoded.** as
aa70: 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 either UTF-8 or
aa80: 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c UTF-16. The sql
aa90: 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 ite3_prepare() a
aaa0: 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nd sqlite3_prepa
aab0: 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 re_v2().** inter
aac0: 66 61 63 65 73 20 75 73 65 73 20 55 54 46 2d 38 faces uses UTF-8
aad0: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 and sqlite3_pre
aae0: 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c pare16() and sql
aaf0: 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
ab00: 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 2().** use UTF-1
ab10: 36 2e 20 49 66 20 74 68 65 20 6e 65 78 74 20 61 6. If the next a
ab20: 72 67 75 6d 65 6e 74 2c 20 22 6e 42 79 74 65 73 rgument, "nBytes
ab30: 22 2c 20 69 73 20 6c 65 73 73 0a 2a 2a 20 74 68 ", is less.** th
ab40: 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 an zero, then zS
ab50: 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f ql is read up to
ab60: 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 the first zero
ab70: 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 49 66 0a terminator. If.
ab80: 2a 2a 20 22 6e 42 79 74 65 73 22 20 69 73 20 6e ** "nBytes" is n
ab90: 6f 74 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 ot less than zer
aba0: 6f 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 o, then it is th
abb0: 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 e length of the
abc0: 73 74 72 69 6e 67 20 7a 53 71 6c 0a 2a 2a 20 69 string zSql.** i
abd0: 6e 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 n bytes (not cha
abe0: 72 61 63 74 65 72 73 29 2e 0a 2a 2a 0a 2a 2a 20 racters)..**.**
abf0: 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 *pzTail is made
ac00: 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 to point to the
ac10: 66 69 72 73 74 20 62 79 74 65 20 70 61 73 74 20 first byte past
ac20: 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 the end of the f
ac30: 69 72 73 74 0a 2a 2a 20 53 51 4c 20 73 74 61 74 irst.** SQL stat
ac40: 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 ement in zSql.
ac50: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c This routine onl
ac60: 79 20 63 6f 6d 70 69 6c 65 73 20 74 68 65 20 66 y compiles the f
ac70: 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 0a 2a irst statement.*
ac80: 2a 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 * in zSql, so *p
ac90: 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f zTail is left po
aca0: 69 6e 74 69 6e 67 20 74 6f 20 77 68 61 74 20 72 inting to what r
acb0: 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 emains uncompile
acc0: 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 d..**.** *ppStmt
acd0: 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e is left pointin
ace0: 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 g to a compiled
acf0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d .** [sqlite3_stm
ad00: 74 20 7c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e t | SQL statemen
ad10: 74 20 73 74 72 75 63 74 75 72 65 5d 20 74 68 61 t structure] tha
ad20: 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 t can be.** exec
ad30: 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 uted using [sqli
ad40: 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 4f 72 te3_step()]. Or
ad50: 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 if there is an
ad60: 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 6d error, *ppStmt m
ad70: 61 79 20 62 65 0a 2a 2a 20 73 65 74 20 74 6f 20 ay be.** set to
ad80: 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 69 6e NULL. If the in
ad90: 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e put text contain
ada0: 65 64 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 ed no SQL (if th
adb0: 65 20 69 6e 70 75 74 20 69 73 20 61 6e 64 0a 2a e input is and.*
adc0: 2a 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f * empty string o
add0: 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 r a comment) the
ade0: 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 n *ppStmt is set
adf0: 20 74 6f 20 4e 55 4c 4c 2e 20 20 54 68 65 20 63 to NULL. The c
ae00: 61 6c 6c 69 6e 67 0a 2a 2a 20 70 72 6f 63 65 64 alling.** proced
ae10: 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 ure is responsib
ae20: 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 le for deleting
ae30: 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c the compiled SQL
ae40: 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 75 73 statement.** us
ae50: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e ing [sqlite3_fin
ae60: 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 alize()] after i
ae70: 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 t has finished w
ae80: 69 74 68 20 69 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e ith it..**.** On
ae90: 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 success, [SQLIT
aea0: 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 E_OK] is returne
aeb0: 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e d. Otherwise an
aec0: 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 .** [SQLITE_ERR
aed0: 4f 52 20 7c 20 65 72 72 6f 72 20 63 6f 64 65 5d OR | error code]
aee0: 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
aef0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
af00: 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 prepare_v2() and
af10: 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
af20: 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 16_v2() interfac
af30: 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d es are.** recomm
af40: 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 ended for all ne
af50: 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 w programs. The
af60: 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 two older interf
af70: 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 aces are retaine
af80: 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 d.** for backwar
af90: 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ds compatibility
afa0: 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 , but their use
afb0: 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a is discouraged..
afc0: 2a 2a 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 ** In the "v2" i
afd0: 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 nterfaces, the p
afe0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
aff0: 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 t.** that is ret
b000: 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 urned (the [sqli
b010: 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 te3_stmt] object
b020: 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 ) contains a cop
b030: 79 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6f 72 69 y of the .** ori
b040: 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 ginal SQL text.
b050: 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 This causes the
b060: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
b070: 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a interface to.**
b080: 20 62 65 68 61 76 65 20 61 20 64 69 66 66 65 72 behave a differ
b090: 65 6e 74 6c 79 20 69 6e 20 74 77 6f 20 77 61 79 ently in two way
b0a0: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a s:.**.** <ol>.**
b0b0: 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65 20 <li>.** If the
b0c0: 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 database schema
b0d0: 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 changes, instead
b0e0: 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 of returning [S
b0f0: 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 QLITE_SCHEMA] as
b100: 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 it.** always us
b110: 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 ed to do, [sqlit
b120: 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 e3_step()] will
b130: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 automatically re
b140: 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a compile the SQL.
b150: 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 ** statement and
b160: 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 try to run it a
b170: 67 61 69 6e 2e 20 20 49 66 20 74 68 65 20 73 63 gain. If the sc
b180: 68 65 6d 61 20 68 61 73 20 63 68 61 6e 67 65 64 hema has changed
b190: 20 69 6e 20 61 20 77 61 79 0a 2a 2a 20 74 68 61 in a way.** tha
b1a0: 74 20 6d 61 6b 65 73 20 74 68 65 20 73 74 61 74 t makes the stat
b1b0: 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 ement no longer
b1c0: 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f valid, [sqlite3_
b1d0: 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 69 step()] will sti
b1e0: 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 ll.** return [SQ
b1f0: 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42 LITE_SCHEMA]. B
b200: 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65 ut unlike the le
b210: 67 61 63 79 20 62 65 68 61 76 69 6f 72 2c 20 5b gacy behavior, [
b220: 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 69 SQLITE_SCHEMA] i
b230: 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61 6c s.** now a fatal
b240: 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 error. Calling
b250: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
b260: 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20 77 69 e_v2()] again wi
b270: 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a ll not make the.
b280: 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77 61 79 ** error go away
b290: 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71 . Note: use [sq
b2a0: 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 lite3_errmsg()]
b2b0: 74 6f 20 66 69 6e 64 20 74 68 65 20 74 65 78 74 to find the text
b2c0: 20 6f 66 20 74 68 65 20 70 61 72 73 69 6e 67 0a of the parsing.
b2d0: 2a 2a 20 65 72 72 6f 72 20 74 68 61 74 20 72 65 ** error that re
b2e0: 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c sults in an [SQL
b2f0: 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 65 74 75 ITE_SCHEMA] retu
b300: 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a rn..** </li>.**.
b310: 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20 ** <li>.** When
b320: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c an error occurs,
b330: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 .** [sqlite3_st
b340: 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 ep()] will retur
b350: 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 n one of the det
b360: 61 69 6c 65 64 20 0a 2a 2a 20 5b 53 51 4c 49 54 ailed .** [SQLIT
b370: 45 5f 45 52 52 4f 52 20 7c 20 72 65 73 75 6c 74 E_ERROR | result
b380: 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 53 codes] or.** [S
b390: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 QLITE_IOERR_READ
b3a0: 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 | extended resu
b3b0: 6c 74 20 63 6f 64 65 73 5d 20 73 75 63 68 20 61 lt codes] such a
b3c0: 73 20 64 69 72 65 63 74 6c 79 2e 0a 2a 2a 20 54 s directly..** T
b3d0: 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 he legacy behavi
b3e0: 6f 72 20 77 61 73 20 74 68 61 74 20 5b 73 71 6c or was that [sql
b3f0: 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 ite3_step()] wou
b400: 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 ld only return a
b410: 20 67 65 6e 65 72 69 63 0a 2a 2a 20 5b 53 51 4c generic.** [SQL
b420: 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c ITE_ERROR] resul
b430: 74 20 63 6f 64 65 20 61 6e 64 20 79 6f 75 20 77 t code and you w
b440: 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b ould have to mak
b450: 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 e a second call
b460: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 to.** [sqlite3_r
b470: 65 73 65 74 28 29 5d 20 69 6e 20 6f 72 64 65 72 eset()] in order
b480: 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 to find the und
b490: 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 erlying cause of
b4a0: 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 0a 2a 2a the problem..**
b4b0: 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 With the "v2" p
b4c0: 72 65 70 61 72 65 20 69 6e 74 65 72 66 61 63 65 repare interface
b4d0: 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e s, the underlyin
b4e0: 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 g reason for the
b4f0: 20 65 72 72 6f 72 20 69 73 0a 2a 2a 20 72 65 74 error is.** ret
b500: 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c urned immediatel
b510: 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c y..** </li>.** <
b520: 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 /ol>.*/.int sqli
b530: 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 te3_prepare(. s
b540: 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
b550: 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 /* Databa
b560: 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 se handle */. c
b570: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c onst char *zSql,
b580: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 /* SQL st
b590: 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 atement, UTF-8 e
b5a0: 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 ncoded */. int
b5b0: 6e 42 79 74 65 73 2c 20 20 20 20 20 20 20 20 20 nBytes,
b5c0: 20 20 20 20 2f 2a 20 4c 65 6e 67 74 68 20 6f 66 /* Length of
b5d0: 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 zSql in bytes.
b5e0: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d */. sqlite3_stm
b5f0: 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 t **ppStmt, /*
b600: 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 OUT: Statement h
b610: 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
b620: 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 char **pzTail
b630: 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 /* OUT: Point
b640: 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 er to unused por
b650: 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a tion of zSql */.
b660: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 );.int sqlite3_p
b670: 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c repare_v2(. sql
b680: 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
b690: 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
b6a0: 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
b6b0: 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 st char *zSql,
b6c0: 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 /* SQL stat
b6d0: 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 ement, UTF-8 enc
b6e0: 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 oded */. int nB
b6f0: 79 74 65 73 2c 20 20 20 20 20 20 20 20 20 20 20 ytes,
b700: 20 20 2f 2a 20 4c 65 6e 67 74 68 20 6f 66 20 7a /* Length of z
b710: 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f Sql in bytes. */
b720: 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 . sqlite3_stmt
b730: 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 **ppStmt, /* OU
b740: 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e T: Statement han
b750: 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 dle */. const c
b760: 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 har **pzTail
b770: 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 /* OUT: Pointer
b780: 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 to unused porti
b790: 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b on of zSql */.);
b7a0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 .int sqlite3_pre
b7b0: 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 pare16(. sqlite
b7c0: 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
b7d0: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 /* Database ha
b7e0: 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
b7f0: 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 void *zSql,
b800: 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 /* SQL stateme
b810: 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 nt, UTF-16 encod
b820: 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 ed */. int nByt
b830: 65 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 es,
b840: 2f 2a 20 4c 65 6e 67 74 68 20 6f 66 20 7a 53 71 /* Length of zSq
b850: 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 l in bytes. */.
b860: 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a sqlite3_stmt **
b870: 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a ppStmt, /* OUT:
b880: 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c Statement handl
b890: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 e */. const voi
b8a0: 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f d **pzTail /
b8b0: 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 * OUT: Pointer t
b8c0: 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e o unused portion
b8d0: 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 of zSql */.);.i
b8e0: 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nt sqlite3_prepa
b8f0: 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 re16_v2(. sqlit
b900: 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
b910: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 /* Database h
b920: 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
b930: 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 void *zSql,
b940: 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d /* SQL statem
b950: 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f ent, UTF-16 enco
b960: 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 ded */. int nBy
b970: 74 65 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 tes,
b980: 20 2f 2a 20 4c 65 6e 67 74 68 20 6f 66 20 7a 53 /* Length of zS
b990: 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a ql in bytes. */.
b9a0: 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a sqlite3_stmt *
b9b0: 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 *ppStmt, /* OUT
b9c0: 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 : Statement hand
b9d0: 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f le */. const vo
b9e0: 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 id **pzTail
b9f0: 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 /* OUT: Pointer
ba00: 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f to unused portio
ba10: 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a n of zSql */.);.
ba20: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
ba30: 20 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 Dynamically Ty
ba40: 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 ped Value Object
ba50: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 .**.** SQLite us
ba60: 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e es dynamic typin
ba70: 67 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 g for the values
ba80: 20 69 74 20 73 74 6f 72 65 73 2e 20 20 56 61 6c it stores. Val
ba90: 75 65 73 20 63 61 6e 20 0a 2a 2a 20 62 65 20 69 ues can .** be i
baa0: 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e ntegers, floatin
bab0: 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 g point values,
bac0: 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 strings, BLOBs,
bad0: 6f 72 20 4e 55 4c 4c 2e 20 20 57 68 65 6e 0a 2a or NULL. When.*
bae0: 2a 20 70 61 73 73 69 6e 67 20 61 72 6f 75 6e 64 * passing around
baf0: 20 76 61 6c 75 65 73 20 69 6e 74 65 72 6e 61 6c values internal
bb00: 6c 79 2c 20 65 61 63 68 20 76 61 6c 75 65 20 69 ly, each value i
bb10: 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 s represented as
bb20: 0a 2a 2a 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 .** an instance
bb30: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 of the sqlite3_v
bb40: 61 6c 75 65 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a alue object..*/.
bb50: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d typedef struct M
bb60: 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 em sqlite3_value
bb70: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
bb80: 46 3a 20 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e F: SQL Function
bb90: 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a Context Object.
bba0: 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 **.** The contex
bbb0: 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 t in which an SQ
bbc0: 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 L function execu
bbd0: 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e tes is stored in
bbe0: 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 an.** sqlite3_c
bbf0: 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 ontext object.
bc00: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 75 63 A pointer to suc
bc10: 68 20 61 6e 20 6f 62 6a 65 63 74 20 69 73 20 74 h an object is t
bc20: 68 65 0a 2a 2a 20 66 69 72 73 74 20 70 61 72 61 he.** first para
bc30: 6d 65 74 65 72 20 74 6f 20 75 73 65 72 2d 64 65 meter to user-de
bc40: 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 fined SQL functi
bc50: 6f 6e 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ons..*/.typedef
bc60: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 struct sqlite3_c
bc70: 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 ontext sqlite3_c
bc80: 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ontext;../*.** C
bc90: 41 50 49 33 52 45 46 3a 20 20 42 69 6e 64 69 6e API3REF: Bindin
bca0: 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 g Values To Prep
bcb0: 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a ared Statements.
bcc0: 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 53 51 4c **.** In the SQL
bcd0: 20 73 74 72 69 6e 67 73 20 69 6e 70 75 74 20 74 strings input t
bce0: 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 o [sqlite3_prepa
bcf0: 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 re_v2()] and its
bd00: 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6f 6e variants,.** on
bd10: 65 20 6f 72 20 6d 6f 72 65 20 6c 69 74 65 72 61 e or more litera
bd20: 6c 73 20 63 61 6e 20 62 65 20 72 65 70 6c 61 63 ls can be replac
bd30: 65 20 62 79 20 61 20 70 61 72 61 6d 65 74 65 72 e by a parameter
bd40: 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 in one of these
bd50: 0a 2a 2a 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a .** forms:.**.**
bd60: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f <ul>.** <li> ?
bd70: 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a .** <li> ?NNN.*
bd80: 2a 20 3c 6c 69 3e 20 20 3a 41 41 41 0a 2a 2a 20 * <li> :AAA.**
bd90: 3c 6c 69 3e 20 20 40 41 41 41 0a 2a 2a 20 3c 6c <li> @AAA.** <l
bda0: 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c i> $VVV.** </ul
bdb0: 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70 >.**.** In the p
bdc0: 61 72 61 6d 65 74 65 72 20 66 6f 72 6d 73 20 73 arameter forms s
bdd0: 68 6f 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69 hown above NNN i
bde0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 s an integer lit
bdf0: 65 72 61 6c 2c 0a 2a 2a 20 41 41 41 20 69 73 20 eral,.** AAA is
be00: 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 an alphanumeric
be10: 69 64 65 6e 74 69 66 69 65 72 20 61 6e 64 20 56 identifier and V
be20: 56 56 20 69 73 20 61 20 76 61 72 69 61 62 6c 65 VV is a variable
be30: 20 6e 61 6d 65 20 61 63 63 6f 72 64 69 6e 67 0a name according.
be40: 2a 2a 20 74 6f 20 74 68 65 20 73 79 6e 74 61 78 ** to the syntax
be50: 20 72 75 6c 65 73 20 6f 66 20 74 68 65 20 54 43 rules of the TC
be60: 4c 20 70 72 6f 67 72 61 6d 6d 69 6e 67 20 6c 61 L programming la
be70: 6e 67 75 61 67 65 2e 0a 2a 2a 20 54 68 65 20 76 nguage..** The v
be80: 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 20 70 alues of these p
be90: 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 arameters (also
bea0: 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 called "host par
beb0: 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 29 0a 2a ameter names").*
bec0: 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 * can be set usi
bed0: 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 ng the sqlite3_b
bee0: 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 ind_*() routines
bef0: 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a defined here..*
bf00: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 *.** The first a
bf10: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 rgument to the s
bf20: 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 qlite3_bind_*()
bf30: 72 6f 75 74 69 6e 65 73 20 61 6c 77 61 79 73 20 routines always
bf40: 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 is a pointer.**
bf50: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
bf60: 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 stmt] object ret
bf70: 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 urned from [sqli
bf80: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
bf90: 5d 20 6f 72 0a 2a 2a 20 69 74 73 20 76 61 72 69 ] or.** its vari
bfa0: 61 6e 74 73 2e 20 20 54 68 65 20 73 65 63 6f 6e ants. The secon
bfb0: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 d.** argument is
bfc0: 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 the index of th
bfd0: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 e parameter to b
bfe0: 65 20 73 65 74 2e 20 20 54 68 65 20 66 69 72 73 e set. The firs
bff0: 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 0a t parameter has.
c000: 2a 2a 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 ** an index of 1
c010: 2e 20 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 . When the same
c020: 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 named parameter
c030: 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 is used more tha
c040: 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 0a 2a n once, second.*
c050: 2a 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 * and subsequent
c060: 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 .** occurrences
c070: 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e have the same in
c080: 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 dex as the first
c090: 20 6f 63 63 75 72 72 65 6e 63 65 2e 20 20 54 68 occurrence. Th
c0a0: 65 20 69 6e 64 65 78 20 66 6f 72 0a 2a 2a 20 6e e index for.** n
c0b0: 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 amed parameters
c0c0: 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 can be looked up
c0d0: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 using the.** [s
c0e0: 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
c0f0: 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 20 41 50 meter_name()] AP
c100: 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 54 I if desired. T
c110: 68 65 20 69 6e 64 65 78 20 66 6f 72 20 22 3f 4e he index for "?N
c120: 4e 4e 22 0a 2a 2a 20 70 61 72 61 6d 65 74 65 73 NN".** parametes
c130: 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 is the value of
c140: 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e NNN..** The NNN
c150: 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 value must be b
c160: 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 etween 1 and the
c170: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a compile-time.**
c180: 20 70 61 72 61 6d 65 74 65 72 20 53 51 4c 49 54 parameter SQLIT
c190: 45 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e E_MAX_VARIABLE_N
c1a0: 55 4d 42 45 52 20 28 64 65 66 61 75 6c 74 20 76 UMBER (default v
c1b0: 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 20 53 alue: 999)..** S
c1c0: 65 65 20 3c 61 20 68 72 65 66 3d 22 6c 69 6d 69 ee <a href="limi
c1d0: 74 73 2e 68 74 6d 6c 22 3e 6c 69 6d 69 74 73 2e ts.html">limits.
c1e0: 68 74 6d 6c 3c 2f 61 3e 20 66 6f 72 20 61 64 64 html</a> for add
c1f0: 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 itional informat
c200: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 ion..**.** The t
c210: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 hird argument is
c220: 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 the value to bi
c230: 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 nd to the parame
c240: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 ter..**.** In th
c250: 6f 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 ose.** routines
c260: 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 that have a four
c270: 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 th argument, its
c280: 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 6e 75 value is the nu
c290: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a mber of bytes.**
c2a0: 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 in the paramete
c2b0: 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a r. To be clear:
c2c0: 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 the value is th
c2d0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
c2e0: 73 20 69 6e 20 74 68 65 0a 2a 2a 20 73 74 72 69 s in the.** stri
c2f0: 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 ng, not the numb
c300: 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 er of characters
c310: 2e 20 20 54 68 65 20 6e 75 6d 62 65 72 0a 2a 2a . The number.**
c320: 20 6f 66 20 62 79 74 65 73 20 64 6f 65 73 20 6e of bytes does n
c330: 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a ot include the z
c340: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 61 ero-terminator a
c350: 74 20 74 68 65 20 65 6e 64 20 6f 66 20 73 74 72 t the end of str
c360: 69 6e 67 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 ings..** If the
c370: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
c380: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 is negative, th
c390: 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 e length of the
c3a0: 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 6e 75 6d string is.** num
c3b0: 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 ber of bytes up
c3c0: 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 to the first zer
c3d0: 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a o terminator..**
c3e0: 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 61 72 .** The fifth ar
c3f0: 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 gument to sqlite
c400: 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 3_bind_blob(), s
c410: 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
c420: 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 (), and.** sqlit
c430: 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 e3_bind_text16()
c440: 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 is a destructor
c450: 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 used to dispose
c460: 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a of the BLOB or.
c470: 2a 2a 20 74 65 78 74 20 61 66 74 65 72 20 53 51 ** text after SQ
c480: 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 Lite has finishe
c490: 64 20 77 69 74 68 20 69 74 2e 20 20 49 66 20 74 d with it. If t
c4a0: 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e he fifth argumen
c4b0: 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 70 65 63 t is the.** spec
c4c0: 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 ial value [SQLIT
c4d0: 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 E_STATIC], then
c4e0: 74 68 65 20 6c 69 62 72 61 72 79 20 61 73 73 75 the library assu
c4f0: 6d 65 73 20 74 68 61 74 20 74 68 65 20 69 6e 66 mes that the inf
c500: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 ormation.** is i
c510: 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 n static, unmana
c520: 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f ged space and do
c530: 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 es not need to b
c540: 65 20 66 72 65 65 64 2e 20 20 49 66 20 74 68 65 e freed. If the
c550: 0a 2a 2a 20 66 69 66 74 68 20 61 72 67 75 6d 65 .** fifth argume
c560: 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 nt has the value
c570: 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 [SQLITE_TRANSIE
c580: 4e 54 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 NT], then SQLite
c590: 20 6d 61 6b 65 73 20 69 74 73 0a 2a 2a 20 6f 77 makes its.** ow
c5a0: 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f n private copy o
c5b0: 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 f the data immed
c5c0: 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 iately, before t
c5d0: 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
c5e0: 2a 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 *().** routine r
c5f0: 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 eturns..**.** Th
c600: 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a e sqlite3_bind_z
c610: 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e eroblob() routin
c620: 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f e binds a BLOB o
c630: 66 20 6c 65 6e 67 74 68 20 6e 20 74 68 61 74 0a f length n that.
c640: 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 ** is filled wit
c650: 68 20 7a 65 72 6f 73 2e 20 20 41 20 7a 65 72 6f h zeros. A zero
c660: 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 blob uses a fixe
c670: 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f d amount of memo
c680: 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 ry.** (just an i
c690: 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 nteger to hold i
c6a0: 74 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 t size) while it
c6b0: 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 is being proces
c6c0: 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 sed..** Zeroblob
c6d0: 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 s are intended t
c6e0: 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 o serve as place
c6f0: 2d 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f -holders for BLO
c700: 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 Bs whose.** cont
c710: 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 ent is later wri
c720: 74 74 65 6e 20 75 73 69 6e 67 20 0a 2a 2a 20 5b tten using .** [
c730: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 sqlite3_blob_ope
c740: 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 20 42 4c n | increment BL
c750: 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 OB I/O] routines
c760: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
c770: 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 te3_bind_*() rou
c780: 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 tines must be ca
c790: 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b 73 lled after.** [s
c7a0: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
c7b0: 32 28 29 5d 20 28 61 6e 64 20 69 74 73 20 76 61 2()] (and its va
c7c0: 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c 69 riants) or [sqli
c7d0: 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 6e 64 te3_reset()] and
c7e0: 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 .** before [sqli
c7f0: 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 te3_step()]..**
c800: 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 Bindings are not
c810: 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 cleared by the
c820: 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
c830: 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e ] routine..** Un
c840: 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 bound parameters
c850: 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 are interpreted
c860: 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 as NULL..**.**
c870: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
c880: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b eturn [SQLITE_OK
c890: 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 ] on success or
c8a0: 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69 66 an error code if
c8b0: 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 .** anything goe
c8c0: 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49 54 s wrong. [SQLIT
c8d0: 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 E_RANGE] is retu
c8e0: 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 rned if the para
c8f0: 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 meter.** index i
c900: 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 s out of range.
c910: 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 [SQLITE_NOMEM]
c920: 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d is returned if m
c930: 61 6c 6c 6f 63 20 66 61 69 6c 73 2e 0a 2a 2a 20 alloc fails..**
c940: 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 [SQLITE_MISUSE]
c950: 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 is returned if t
c960: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
c970: 65 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 76 69 e called on a vi
c980: 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 rtual.** machine
c990: 20 74 68 61 74 20 69 73 20 74 68 65 20 77 72 6f that is the wro
c9a0: 6e 67 20 73 74 61 74 65 20 6f 72 20 77 68 69 63 ng state or whic
c9b0: 68 20 68 61 73 20 61 6c 72 65 61 64 79 20 62 65 h has already be
c9c0: 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2f en finalized..*/
c9d0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
c9e0: 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 d_blob(sqlite3_s
c9f0: 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 tmt*, int, const
ca00: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 void*, int n, v
ca10: 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
ca20: 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
ca30: 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f _double(sqlite3_
ca40: 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 stmt*, int, doub
ca50: 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 le);.int sqlite3
ca60: 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 _bind_int(sqlite
ca70: 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 3_stmt*, int, in
ca80: 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f t);.int sqlite3_
ca90: 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 bind_int64(sqlit
caa0: 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 e3_stmt*, int, s
cab0: 71 6c 69 74 65 5f 69 6e 74 36 34 29 3b 0a 69 6e qlite_int64);.in
cac0: 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e t sqlite3_bind_n
cad0: 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ull(sqlite3_stmt
cae0: 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c *, int);.int sql
caf0: 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 ite3_bind_text(s
cb00: 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
cb10: 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 t, const char*,
cb20: 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 int n, void(*)(v
cb30: 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 oid*));.int sqli
cb40: 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 te3_bind_text16(
cb50: 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
cb60: 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c nt, const void*,
cb70: 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f int, void(*)(vo
cb80: 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 id*));.int sqlit
cb90: 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 e3_bind_value(sq
cba0: 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
cbb0: 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f , const sqlite3_
cbc0: 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c value*);.int sql
cbd0: 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c ite3_bind_zerobl
cbe0: 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ob(sqlite3_stmt*
cbf0: 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a , int, int n);..
cc00: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
cc10: 4e 75 6d 62 65 72 20 4f 66 20 48 6f 73 74 20 50 Number Of Host P
cc20: 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 arameters.**.**
cc30: 52 65 74 75 72 6e 20 74 68 65 20 6c 61 72 67 65 Return the large
cc40: 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 st host paramete
cc50: 72 20 69 6e 64 65 78 20 69 6e 20 74 68 65 20 70 r index in the p
cc60: 72 65 63 6f 6d 70 69 6c 65 64 20 73 74 61 74 65 recompiled state
cc70: 6d 65 6e 74 20 67 69 76 65 6e 0a 2a 2a 20 61 73 ment given.** as
cc80: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 2e 20 20 the argument.
cc90: 57 68 65 6e 20 74 68 65 20 68 6f 73 74 20 70 61 When the host pa
cca0: 72 61 6d 65 74 65 72 73 20 61 72 65 20 6f 66 20 rameters are of
ccb0: 74 68 65 20 66 6f 72 6d 73 20 6c 69 6b 65 20 22 the forms like "
ccc0: 3a 41 41 41 22 0a 2a 2a 20 6f 72 20 22 3f 22 2c :AAA".** or "?",
ccd0: 20 74 68 65 6e 20 74 68 65 79 20 61 72 65 20 61 then they are a
cce0: 73 73 69 67 6e 65 64 20 73 65 71 75 65 6e 74 69 ssigned sequenti
ccf0: 61 6c 20 69 6e 63 72 65 61 73 69 6e 67 20 6e 75 al increasing nu
cd00: 6d 62 65 72 73 20 62 65 67 69 6e 6e 69 6e 67 0a mbers beginning.
cd10: 2a 2a 20 77 69 74 68 20 6f 6e 65 2c 20 73 6f 20 ** with one, so
cd20: 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
cd30: 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 ed is the number
cd40: 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 2e 20 of parameters.
cd50: 20 48 6f 77 65 76 65 72 0a 2a 2a 20 69 66 20 74 However.** if t
cd60: 68 65 20 73 61 6d 65 20 68 6f 73 74 20 70 61 72 he same host par
cd70: 61 6d 65 74 65 72 20 6e 61 6d 65 20 69 73 20 75 ameter name is u
cd80: 73 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d sed multiple tim
cd90: 65 73 2c 20 65 61 63 68 20 6f 63 63 75 72 72 61 es, each occurra
cda0: 6e 63 65 0a 2a 2a 20 69 73 20 67 69 76 65 6e 20 nce.** is given
cdb0: 74 68 65 20 73 61 6d 65 20 6e 75 6d 62 65 72 2c the same number,
cdc0: 20 73 6f 20 74 68 65 20 76 61 6c 75 65 20 72 65 so the value re
cdd0: 74 75 72 6e 65 64 20 69 6e 20 74 68 61 74 20 63 turned in that c
cde0: 61 73 65 20 69 73 20 74 68 65 20 6e 75 6d 62 65 ase is the numbe
cdf0: 72 0a 2a 2a 20 6f 66 20 75 6e 69 71 75 65 20 68 r.** of unique h
ce00: 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 ost parameter na
ce10: 6d 65 73 2e 20 20 49 66 20 68 6f 73 74 20 70 61 mes. If host pa
ce20: 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 rameters of the
ce30: 66 6f 72 6d 20 22 3f 4e 4e 4e 22 0a 2a 2a 20 61 form "?NNN".** a
ce40: 72 65 20 75 73 65 64 20 28 77 68 65 72 65 20 4e re used (where N
ce50: 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 NN is an integer
ce60: 29 20 74 68 65 6e 20 74 68 65 72 65 20 6d 69 67 ) then there mig
ce70: 68 74 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 ht be gaps in th
ce80: 65 0a 2a 2a 20 6e 75 6d 62 65 72 69 6e 67 20 61 e.** numbering a
ce90: 6e 64 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 nd the value ret
cea0: 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 69 6e urned by this in
ceb0: 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 69 terface is the i
cec0: 6e 64 65 78 20 6f 66 20 74 68 65 0a 2a 2a 20 68 ndex of the.** h
ced0: 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 77 69 ost parameter wi
cee0: 74 68 20 74 68 65 20 6c 61 72 67 65 73 74 20 69 th the largest i
cef0: 6e 64 65 78 20 76 61 6c 75 65 2e 0a 2a 2f 0a 69 ndex value..*/.i
cf00: 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
cf10: 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 parameter_count(
cf20: 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a sqlite3_stmt*);.
cf30: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
cf40: 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 Name Of A Host
cf50: 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 Parameter.**.**
cf60: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 This routine ret
cf70: 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
cf80: 6f 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 o the name of th
cf90: 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 e n-th parameter
cfa0: 20 69 6e 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 in a .** [sqlit
cfb0: 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 e3_stmt | prepar
cfc0: 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a ed statement]..*
cfd0: 2a 20 48 6f 73 74 20 70 61 72 61 6d 65 74 65 72 * Host parameter
cfe0: 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3a s of the form ":
cff0: 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f AAA" or "@AAA" o
d000: 72 20 22 24 56 56 56 22 20 68 61 76 65 20 61 20 r "$VVV" have a
d010: 6e 61 6d 65 0a 2a 2a 20 77 68 69 63 68 20 69 73 name.** which is
d020: 20 74 68 65 20 73 74 72 69 6e 67 20 22 3a 41 41 the string ":AA
d030: 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 A" or "@AAA" or
d040: 22 24 56 56 56 22 2e 20 20 0a 2a 2a 20 49 6e 20 "$VVV". .** In
d050: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 other words, the
d060: 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 initial ":" or
d070: 22 24 22 20 6f 72 20 22 40 22 0a 2a 2a 20 69 73 "$" or "@".** is
d080: 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 included as par
d090: 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 0a 2a t of the name..*
d0a0: 2a 20 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 * Parameters of
d0b0: 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 6f 72 20 the form "?" or
d0c0: 22 3f 4e 4e 4e 22 20 68 61 76 65 20 6e 6f 20 6e "?NNN" have no n
d0d0: 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 ame..**.** The f
d0e0: 69 72 73 74 20 62 6f 75 6e 64 20 70 61 72 61 6d irst bound param
d0f0: 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 eter has an inde
d100: 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a x of 1, not 0..*
d110: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 76 61 6c 75 *.** If the valu
d120: 65 20 6e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 e n is out of ra
d130: 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 6e 2d nge or if the n-
d140: 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 th parameter is
d150: 6e 61 6d 65 6c 65 73 73 2c 0a 2a 2a 20 74 68 65 nameless,.** the
d160: 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e n NULL is return
d170: 65 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 ed. The returne
d180: 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 d string is alwa
d190: 79 73 20 69 6e 20 74 68 65 0a 2a 2a 20 55 54 46 ys in the.** UTF
d1a0: 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e -8 encoding even
d1b0: 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 if the named pa
d1c0: 72 61 6d 65 74 65 72 20 77 61 73 20 6f 72 69 67 rameter was orig
d1d0: 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 inally specified
d1e0: 0a 2a 2a 20 61 73 20 55 54 46 2d 31 36 20 69 6e .** as UTF-16 in
d1f0: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
d200: 65 31 36 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 e16()] or [sqlit
d210: 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
d220: 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 )]..*/.const cha
d230: 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f r *sqlite3_bind_
d240: 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 parameter_name(s
d250: 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
d260: 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
d270: 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 REF: Index Of A
d280: 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 Parameter With A
d290: 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a Given Name.**.*
d2a0: 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 * This routine r
d2b0: 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 eturns the index
d2c0: 20 6f 66 20 61 20 68 6f 73 74 20 70 61 72 61 6d of a host param
d2d0: 65 74 65 72 20 77 69 74 68 20 74 68 65 20 67 69 eter with the gi
d2e0: 76 65 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 ven name..** The
d2f0: 20 6e 61 6d 65 20 6d 75 73 74 20 6d 61 74 63 68 name must match
d300: 20 65 78 61 63 74 6c 79 2e 20 20 49 66 20 6e 6f exactly. If no
d310: 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 parameter with
d320: 74 68 65 20 67 69 76 65 6e 20 6e 61 6d 65 20 69 the given name i
d330: 73 20 0a 2a 2a 20 66 6f 75 6e 64 2c 20 72 65 74 s .** found, ret
d340: 75 72 6e 20 30 2e 20 20 50 61 72 61 6d 65 74 65 urn 0. Paramete
d350: 72 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20 r names must be
d360: 55 54 46 38 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c UTF8..*/.int sql
d370: 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
d380: 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 ter_index(sqlite
d390: 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 3_stmt*, const c
d3a0: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a har *zName);../*
d3b0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 .** CAPI3REF: Re
d3c0: 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 set All Bindings
d3d0: 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 On A Prepared S
d3e0: 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 43 tatement.**.** C
d3f0: 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 ontrary to the i
d400: 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 ntuition of many
d410: 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 , [sqlite3_reset
d420: 28 29 5d 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 ()] does not.**
d430: 72 65 73 65 74 20 74 68 65 20 5b 73 71 6c 69 74 reset the [sqlit
d440: 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 e3_bind_blob | b
d450: 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 0a 2a indings] on a .*
d460: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 * [sqlite3_stmt
d470: 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 | prepared state
d480: 6d 65 6e 74 5d 2e 20 20 55 73 65 20 74 68 69 73 ment]. Use this
d490: 20 72 6f 75 74 69 6e 65 20 74 6f 0a 2a 2a 20 72 routine to.** r
d4a0: 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 eset all host pa
d4b0: 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c rameters to NULL
d4c0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
d4d0: 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 _clear_bindings(
d4e0: 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a sqlite3_stmt*);.
d4f0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
d500: 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d Number Of Colum
d510: 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 ns In A Result S
d520: 65 74 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 et.**.** Return
d530: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f the number of co
d540: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 lumns in the res
d550: 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 ult set returned
d560: 20 62 79 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c by the .** [sql
d570: 69 74 65 33 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 ite3_stmt | comp
d580: 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 iled SQL stateme
d590: 6e 74 5d 2e 20 54 68 69 73 20 72 6f 75 74 69 6e nt]. This routin
d5a0: 65 20 72 65 74 75 72 6e 73 20 30 0a 2a 2a 20 69 e returns 0.** i
d5b0: 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 f pStmt is an SQ
d5c0: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 L statement that
d5d0: 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e does not return
d5e0: 20 64 61 74 61 20 28 66 6f 72 20 0a 2a 2a 20 65 data (for .** e
d5f0: 78 61 6d 70 6c 65 20 61 6e 20 55 50 44 41 54 45 xample an UPDATE
d600: 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 )..*/.int sqlite
d610: 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 3_column_count(s
d620: 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
d630: 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
d640: 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 3REF: Column Nam
d650: 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 es In A Result S
d660: 65 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 et.**.** These r
d670: 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 outines return t
d680: 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 he name assigned
d690: 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 to a particular
d6a0: 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 column.** in th
d6b0: 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 e result set of
d6c0: 61 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 a SELECT stateme
d6d0: 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 nt. The sqlite3
d6e0: 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a _column_name().*
d6f0: 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 * interface retu
d700: 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
d710: 20 61 20 55 54 46 38 20 73 74 72 69 6e 67 20 61 a UTF8 string a
d720: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nd sqlite3_colum
d730: 6e 5f 6e 61 6d 65 31 36 28 29 0a 2a 2a 20 72 65 n_name16().** re
d740: 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
d750: 74 6f 20 61 20 55 54 46 31 36 20 73 74 72 69 6e to a UTF16 strin
d760: 67 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 g. The first pa
d770: 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a rameter is the.*
d780: 2a 20 5b 73 71 6c 69 74 65 5f 73 74 6d 74 20 7c * [sqlite_stmt |
d790: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
d7a0: 65 6e 74 5d 20 74 68 61 74 20 69 6d 70 6c 65 6d ent] that implem
d7b0: 65 6e 74 73 20 74 68 65 20 53 45 4c 45 43 54 20 ents the SELECT
d7c0: 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 statement..** Th
d7d0: 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
d7e0: 65 72 20 69 73 20 74 68 65 20 63 6f 6c 75 6d 6e er is the column
d7f0: 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 6c 65 number. The le
d800: 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 ft-most column i
d810: 73 0a 2a 2a 20 6e 75 6d 62 65 72 20 30 2e 0a 2a s.** number 0..*
d820: 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 *.** The returne
d830: 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 d string pointer
d840: 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 is valid until
d850: 65 69 74 68 65 72 20 74 68 65 20 0a 2a 2a 20 5b either the .** [
d860: 73 71 6c 69 74 65 5f 73 74 6d 74 20 7c 20 70 72 sqlite_stmt | pr
d870: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
d880: 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 ] is destroyed b
d890: 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c y [sqlite3_final
d8a0: 69 7a 65 28 29 5d 0a 2a 2a 20 6f 72 20 75 6e 74 ize()].** or unt
d8b0: 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c il the next call
d8c0: 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
d8d0: 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 name() or sqlite
d8e0: 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 3_column_name16(
d8f0: 29 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 ).** on the same
d900: 20 63 6f 6c 75 6d 6e 2e 0a 2a 2f 0a 63 6f 6e 73 column..*/.cons
d910: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
d920: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 column_name(sqli
d930: 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e te3_stmt*, int N
d940: 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
d950: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
d960: 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d me16(sqlite3_stm
d970: 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a t*, int N);../*.
d980: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 ** CAPI3REF: Sou
d990: 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 rce Of Data In A
d9a0: 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a Query Result.**
d9b0: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
d9c0: 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 es provide a mea
d9d0: 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 ns to determine
d9e0: 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 77 what column of w
d9f0: 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69 6e 20 hat.** table in
da00: 77 68 69 63 68 20 64 61 74 61 62 61 73 65 20 61 which database a
da10: 20 72 65 73 75 6c 74 20 6f 66 20 61 20 53 45 4c result of a SEL
da20: 45 43 54 20 73 74 61 74 65 6d 65 6e 74 20 63 6f ECT statement co
da30: 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65 mes from..** The
da40: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 name of the dat
da50: 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f abase or table o
da60: 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 r column can be
da70: 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 returned as.** e
da80: 69 74 68 65 72 20 61 20 55 54 46 38 20 6f 72 20 ither a UTF8 or
da90: 55 54 46 31 36 20 73 74 72 69 6e 67 2e 20 20 54 UTF16 string. T
daa0: 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f he _database_ ro
dab0: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a utines return.**
dac0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 the database na
dad0: 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 me, the _table_
dae0: 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
daf0: 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 the table name,
db00: 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 and.** the origi
db10: 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 n_ routines retu
db20: 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 rn the column na
db30: 6d 65 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 me..** The retur
db40: 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 ned string is va
db50: 6c 69 64 20 75 6e 74 69 6c 0a 2a 2a 20 74 68 65 lid until.** the
db60: 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c [sqlite3_stmt |
db70: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
db80: 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 ent] is destroye
db90: 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 d using.** [sqli
dba0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
dbb0: 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d or until the sam
dbc0: 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 e information is
dbd0: 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 requested.** ag
dbe0: 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 ain in a differe
dbf0: 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a nt encoding..**.
dc00: 2a 2a 20 54 68 65 20 6e 61 6d 65 73 20 72 65 74 ** The names ret
dc10: 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 urned are the or
dc20: 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 iginal un-aliase
dc30: 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a d names of the.*
dc40: 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c * database, tabl
dc50: 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a e, and column..*
dc60: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 *.** The first a
dc70: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 66 rgument to the f
dc80: 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c 73 20 69 ollowing calls i
dc90: 73 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 s a .** [sqlite3
dca0: 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64 _stmt | compiled
dcb0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e SQL statement].
dcc0: 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 .** These functi
dcd0: 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 ons return infor
dce0: 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 mation about the
dcf0: 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 Nth column retu
dd00: 72 6e 65 64 20 62 79 20 0a 2a 2a 20 74 68 65 20 rned by .** the
dd10: 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 statement, where
dd20: 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 N is the second
dd30: 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 function argume
dd40: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 nt..**.** If the
dd50: 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 Nth column retu
dd60: 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 rned by the stat
dd70: 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 ement is an expr
dd80: 65 73 73 69 6f 6e 0a 2a 2a 20 6f 72 20 73 75 62 ession.** or sub
dd90: 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 query and is not
dda0: 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c a column value,
ddb0: 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 then all of the
ddc0: 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 se functions.**
ddd0: 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 20 4f 74 68 return NULL. Oth
dde0: 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 erwise, they ret
ddf0: 75 72 6e 20 74 68 65 20 0a 2a 2a 20 6e 61 6d 65 urn the .** name
de00: 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64 of the attached
de10: 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 database, table
de20: 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74 and column that
de30: 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a query result.**
de40: 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 column was extr
de50: 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a acted from..**.*
de60: 2a 20 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 * As with all ot
de70: 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c her SQLite APIs,
de80: 20 74 68 6f 73 65 20 70 6f 73 74 66 69 78 65 64 those postfixed
de90: 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 with "16" retur
dea0: 6e 20 55 54 46 2d 31 36 0a 2a 2a 20 65 6e 63 6f n UTF-16.** enco
deb0: 64 65 64 20 73 74 72 69 6e 67 73 2c 20 74 68 65 ded strings, the
dec0: 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 other functions
ded0: 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a return UTF-8..*
dee0: 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20 *.** These APIs
def0: 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 are only availab
df00: 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 le if the librar
df10: 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 y was compiled w
df20: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 ith the .** SQLI
df30: 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e TE_ENABLE_COLUMN
df40: 5f 4d 45 54 41 44 41 54 41 20 70 72 65 70 72 6f _METADATA prepro
df50: 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 cessor symbol de
df60: 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 fined..*/.const
df70: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
df80: 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 lumn_database_na
df90: 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
dfa0: 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 ,int);.const voi
dfb0: 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
dfc0: 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 n_database_name1
dfd0: 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
dfe0: 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 int);.const char
dff0: 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
e000: 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 _table_name(sqli
e010: 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
e020: 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
e030: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 te3_column_table
e040: 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f _name16(sqlite3_
e050: 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 stmt*,int);.cons
e060: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
e070: 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 column_origin_na
e080: 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
e090: 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 ,int);.const voi
e0a0: 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
e0b0: 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 n_origin_name16(
e0c0: 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
e0d0: 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
e0e0: 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 REF: Declared Da
e0f0: 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 tatype Of A Quer
e100: 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 54 y Result.**.** T
e110: 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
e120: 65 72 20 69 73 20 61 20 5b 73 71 6c 69 74 65 33 er is a [sqlite3
e130: 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64 _stmt | compiled
e140: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e SQL statement].
e150: 20 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 .** If this sta
e160: 74 65 6d 65 6e 74 20 69 73 20 61 20 53 45 4c 45 tement is a SELE
e170: 43 54 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 CT statement and
e180: 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
e190: 6f 66 20 74 68 65 20 0a 2a 2a 20 72 65 74 75 72 of the .** retur
e1a0: 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 20 ned result set
e1b0: 6f 66 20 74 68 61 74 20 53 45 4c 45 43 54 20 69 of that SELECT i
e1c0: 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e s a table column
e1d0: 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 (not an.** expr
e1e0: 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 ession or subque
e1f0: 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 ry) then the dec
e200: 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 lared type of th
e210: 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d e table.** colum
e220: 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 49 n is returned. I
e230: 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e f the Nth column
e240: 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 of the result s
e250: 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 et is an.** expr
e260: 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 ession or subque
e270: 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 ry, then a NULL
e280: 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 pointer is retur
e290: 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 ned..** The retu
e2a0: 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 rned string is a
e2b0: 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f lways UTF-8 enco
e2c0: 64 65 64 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 ded. For example
e2d0: 2c 20 69 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 , in.** the data
e2e0: 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a base schema:.**.
e2f0: 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 ** CREATE TABLE
e300: 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a t1(c1 VARIANT);.
e310: 2a 2a 0a 2a 2a 20 41 6e 64 20 74 68 65 20 66 6f **.** And the fo
e320: 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e llowing statemen
e330: 74 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a t compiled:.**.*
e340: 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c * SELECT c1 + 1,
e350: 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a c1 FROM t1;.**.
e360: 2a 2a 20 54 68 65 6e 20 74 68 69 73 20 72 6f 75 ** Then this rou
e370: 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 tine would retur
e380: 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 n the string "VA
e390: 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 RIANT" for the s
e3a0: 65 63 6f 6e 64 0a 2a 2a 20 72 65 73 75 6c 74 20 econd.** result
e3b0: 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 column (i==1), a
e3c0: 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 nd a NULL pointe
e3d0: 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 r for the first
e3e0: 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a result column.**
e3f0: 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 (i==0)..**.** S
e400: 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d QLite uses dynam
e410: 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 ic run-time typi
e420: 6e 67 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 63 ng. So just bec
e430: 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a ause a column.**
e440: 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 is declared to
e450: 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 contain a partic
e460: 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e ular type does n
e470: 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 ot mean that the
e480: 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 .** data stored
e490: 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 in that column i
e4a0: 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 s of the declare
e4b0: 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 d type. SQLite
e4c0: 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 is.** strongly t
e4d0: 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 yped, but the ty
e4e0: 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 ping is dynamic
e4f0: 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 54 79 70 not static. Typ
e500: 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 e.** is associat
e510: 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 ed with individu
e520: 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 al values, not w
e530: 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 ith the containe
e540: 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f rs.** used to ho
e550: 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e ld those values.
e560: 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a .*/.const char *
e570: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
e580: 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f ecltype(sqlite3_
e590: 73 74 6d 74 20 2a 2c 20 69 6e 74 20 69 29 3b 0a stmt *, int i);.
e5a0: 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
e5b0: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 te3_column_declt
e5c0: 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ype16(sqlite3_st
e5d0: 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 20 0a 2a mt*,int);../* .*
e5e0: 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 76 61 * CAPI3REF: Eva
e5f0: 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 luate An SQL Sta
e600: 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 tement.**.** Aft
e610: 65 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 73 er an [sqlite3_s
e620: 74 6d 74 20 7c 20 53 51 4c 20 73 74 61 74 65 6d tmt | SQL statem
e630: 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 ent] has been pr
e640: 65 70 61 72 65 64 20 77 69 74 68 20 61 20 63 61 epared with a ca
e650: 6c 6c 0a 2a 2a 20 74 6f 20 65 69 74 68 65 72 20 ll.** to either
e660: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
e670: 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 _v2()] or [sqlit
e680: 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
e690: 29 5d 20 6f 72 20 74 6f 20 6f 6e 65 20 6f 66 0a )] or to one of.
e6a0: 2a 2a 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e ** the legacy in
e6b0: 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 terfaces [sqlite
e6c0: 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 3_prepare()] or
e6d0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
e6e0: 31 36 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 16()],.** then t
e6f0: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 his function mus
e700: 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 t be called one
e710: 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f or more times to
e720: 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 0a 2a evaluate the .*
e730: 2a 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a * statement..**.
e740: 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f ** The details o
e750: 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f f the behavior o
e760: 66 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f 73 f this sqlite3_s
e770: 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 tep() interface
e780: 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 depend.** on whe
e790: 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 ther the stateme
e7a0: 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 nt was prepared
e7b0: 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 using the newer
e7c0: 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a "v2" interface.*
e7d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
e7e0: 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 re_v2()] and [sq
e7f0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
e800: 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 v2()] or the old
e810: 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 er legacy.** int
e820: 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f erface [sqlite3_
e830: 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b prepare()] and [
e840: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
e850: 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 6()]. The use o
e860: 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 f the.** new "v2
e870: 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 " interface is r
e880: 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e ecommended for n
e890: 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 ew applications
e8a0: 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a but the legacy.*
e8b0: 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c * interface will
e8c0: 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 continue to be
e8d0: 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a supported..**.**
e8e0: 20 49 6e 20 74 68 65 20 6c 61 67 61 63 79 20 69 In the lagacy i
e8f0: 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 nterface, the re
e900: 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 turn value will
e910: 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 be either [SQLIT
e920: 45 5f 42 55 53 59 5d 2c 20 0a 2a 2a 20 5b 53 51 E_BUSY], .** [SQ
e930: 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c LITE_DONE], [SQL
e940: 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 ITE_ROW], [SQLIT
e950: 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 E_ERROR], or [SQ
e960: 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a LITE_MISUSE]..**
e970: 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 With the "v2" i
e980: 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 nterface, any of
e990: 20 74 68 65 20 6f 74 68 65 72 20 5b 53 51 4c 49 the other [SQLI
e9a0: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 TE_OK | result c
e9b0: 6f 64 65 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 ode].** or [SQLI
e9c0: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 TE_IOERR_READ |
e9d0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
e9e0: 63 6f 64 65 5d 20 6d 69 67 68 74 20 62 65 20 72 code] might be r
e9f0: 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 77 65 eturned as.** we
ea00: 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 ll..**.** [SQLIT
ea10: 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 E_BUSY] means th
ea20: 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 at the database
ea30: 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c engine was unabl
ea40: 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 e to acquire the
ea50: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 .** database loc
ea60: 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 ks it needs to d
ea70: 6f 20 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 o its job. If t
ea80: 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 he statement is
ea90: 61 20 43 4f 4d 4d 49 54 0a 2a 2a 20 6f 72 20 6f a COMMIT.** or o
eaa0: 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 ccurs outside of
eab0: 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 an explicit tra
eac0: 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 nsaction, then y
ead0: 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 ou can retry the
eae0: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 .** statement.
eaf0: 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 If the statement
eb00: 20 69 73 20 6e 6f 74 20 61 20 43 4f 4d 4d 49 54 is not a COMMIT
eb10: 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 and occurs with
eb20: 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 in a.** explicit
eb30: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 transaction the
eb40: 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c n you should rol
eb50: 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 lback the transa
eb60: 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 ction before.**
eb70: 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a continuing..**.*
eb80: 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 * [SQLITE_DONE]
eb90: 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 means that the s
eba0: 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e tatement has fin
ebb0: 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a ished executing.
ebc0: 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e ** successfully.
ebd0: 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 sqlite3_step()
ebe0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 should not be c
ebf0: 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 alled again on t
ec00: 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d his virtual.** m
ec10: 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 achine without f
ec20: 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 irst calling [sq
ec30: 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 lite3_reset()] t
ec40: 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 o reset the virt
ec50: 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 ual.** machine b
ec60: 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 ack to its initi
ec70: 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 al state..**.**
ec80: 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 If the SQL state
ec90: 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 ment being execu
eca0: 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 ted returns any
ecb0: 64 61 74 61 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b data, then .** [
ecc0: 53 51 4c 49 54 45 5f 52 4f 57 5d 20 69 73 20 72 SQLITE_ROW] is r
ecd0: 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d eturned each tim
ece0: 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 e a new row of d
ecf0: 61 74 61 20 69 73 20 72 65 61 64 79 0a 2a 2a 20 ata is ready.**
ed00: 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 for processing b
ed10: 79 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 54 68 y the caller. Th
ed20: 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 e values may be
ed30: 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 0a 2a accessed using.*
ed40: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 * the [sqlite3_c
ed50: 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 63 6f 6c 75 olumn_int | colu
ed60: 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 mn access functi
ed70: 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 ons]..** sqlite3
ed80: 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 _step() is calle
ed90: 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 d again to retri
eda0: 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 eve the next row
edb0: 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 20 0a 2a 2a of data..** .**
edc0: 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
edd0: 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e means that a run
ede0: 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 -time error (suc
edf0: 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e h as a constrain
ee00: 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 t.** violation)
ee10: 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 has occurred. s
ee20: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 qlite3_step() sh
ee30: 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c ould not be call
ee40: 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 ed again on.** t
ee50: 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f he VM. More info
ee60: 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 rmation may be f
ee70: 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 ound by calling
ee80: 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 [sqlite3_errmsg(
ee90: 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 )]..** With the
eea0: 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 legacy interface
eeb0: 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 , a more specifi
eec0: 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 65 78 c error code (ex
eed0: 61 6d 70 6c 65 3a 0a 2a 2a 20 5b 53 51 4c 49 54 ample:.** [SQLIT
eee0: 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 E_INTERRUPT], [S
eef0: 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b QLITE_SCHEMA], [
ef00: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c SQLITE_CORRUPT],
ef10: 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a and so forth).*
ef20: 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 * can be obtaine
ef30: 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 d by calling [sq
ef40: 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f lite3_reset()] o
ef50: 6e 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 n the.** [sqlite
ef60: 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64 _stmt | prepared
ef70: 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e statement]. In
ef80: 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 the "v2" interf
ef90: 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 ace,.** the more
efa0: 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 specific error
efb0: 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 code is returned
efc0: 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c directly by sql
efd0: 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a ite3_step()..**.
efe0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 ** [SQLITE_MISUS
eff0: 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 E] means that th
f000: 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 e this routine w
f010: 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 as called inappr
f020: 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 opriately..** Pe
f030: 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c rhaps it was cal
f040: 6c 65 64 20 6f 6e 20 61 20 5b 73 71 6c 69 74 65 led on a [sqlite
f050: 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64 _stmt | prepared
f060: 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 statement] that
f070: 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 has.** already
f080: 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 been [sqlite3_fi
f090: 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a nalize | finaliz
f0a0: 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 ed] or on one th
f0b0: 61 74 20 68 61 64 20 0a 2a 2a 20 70 72 65 76 69 at had .** previ
f0c0: 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b ously returned [
f0d0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 SQLITE_ERROR] or
f0e0: 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 [SQLITE_DONE].
f0f0: 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 Or it could.**
f100: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 be the case that
f110: 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 the same databa
f120: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
f130: 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 being used by t
f140: 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 wo or.** more th
f150: 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d reads at the sam
f160: 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 e moment in time
f170: 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 ..**.** <b>Goofy
f180: 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 Interface Alert
f190: 3a 3c 2f 62 3e 0a 2a 2a 20 49 6e 20 74 68 65 20 :</b>.** In the
f1a0: 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 legacy interface
f1b0: 2c 20 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 , .** the sqlite
f1c0: 33 5f 73 74 65 70 28 29 20 41 50 49 20 61 6c 77 3_step() API alw
f1d0: 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 ays returns a ge
f1e0: 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 neric error code
f1f0: 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 ,.** [SQLITE_ERR
f200: 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 OR], following a
f210: 6e 79 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 ny error other t
f220: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 han [SQLITE_BUSY
f230: 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c 49 54 45 ].** and [SQLITE
f240: 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d _MISUSE]. You m
f250: 75 73 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 ust call [sqlite
f260: 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 3_reset()] or.**
f270: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
f280: 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 ze()] in order t
f290: 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 o find one of th
f2a0: 65 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 5b 53 e specific.** [S
f2b0: 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72 65 QLITE_ERROR | re
f2c0: 73 75 6c 74 20 63 6f 64 65 73 5d 20 74 68 61 74 sult codes] that
f2d0: 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 better describe
f2e0: 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 s the error..**
f2f0: 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 We admit that th
f300: 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 is is a goofy de
f310: 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c sign. The probl
f320: 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 em has been fixe
f330: 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 d.** with the "v
f340: 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 2" interface. I
f350: 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c f you prepare al
f360: 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 l of your SQL st
f370: 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e atements.** usin
f380: 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 g either [sqlite
f390: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
f3a0: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 or [sqlite3_prep
f3b0: 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 are16_v2()] inst
f3c0: 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 ead.** of the le
f3d0: 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 gacy [sqlite3_pr
f3e0: 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 epare()] and [sq
f3f0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
f400: 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 0a 2a 2a )], then the .**
f410: 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b more specific [
f420: 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72 SQLITE_ERROR | r
f430: 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 esult codes] are
f440: 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 returned direct
f450: 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 ly.** by sqlite3
f460: 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 _step(). The us
f470: 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e e of the "v2" in
f480: 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d terface is recom
f490: 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 mended..*/.int s
f4a0: 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 qlite3_step(sqli
f4b0: 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a te3_stmt*);../*.
f4c0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 0a 2a 2a 0a ** CAPI3REF:.**.
f4d0: 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 6e 75 ** Return the nu
f4e0: 6d 62 65 72 20 6f 66 20 76 61 6c 75 65 73 20 69 mber of values i
f4f0: 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f n the current ro
f500: 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 w of the result
f510: 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 set..**.** After
f520: 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 a call to [sqli
f530: 74 65 33 5f 73 74 65 70 28 29 5d 20 74 68 61 74 te3_step()] that
f540: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
f550: 5f 52 4f 57 5d 2c 20 74 68 69 73 20 72 6f 75 74 _ROW], this rout
f560: 69 6e 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 ine.** will retu
f570: 72 6e 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 rn the same valu
f580: 65 20 61 73 20 74 68 65 20 5b 73 71 6c 69 74 65 e as the [sqlite
f590: 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 3_column_count()
f5a0: 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 41 ] function..** A
f5b0: 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 fter [sqlite3_st
f5c0: 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e ep()] has return
f5d0: 65 64 20 61 6e 20 5b 53 51 4c 49 54 45 5f 44 4f ed an [SQLITE_DO
f5e0: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 NE], [SQLITE_BUS
f5f0: 59 5d 2c 20 6f 72 0a 2a 2a 20 61 20 5b 53 51 4c Y], or.** a [SQL
f600: 49 54 45 5f 45 52 52 4f 52 20 7c 20 65 72 72 6f ITE_ERROR | erro
f610: 72 20 63 6f 64 65 5d 2c 20 6f 72 20 62 65 66 6f r code], or befo
f620: 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 re [sqlite3_step
f630: 28 29 5d 20 68 61 73 20 62 65 65 6e 20 0a 2a 2a ()] has been .**
f640: 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 5b called on the [
f650: 73 71 6c 69 74 65 5f 73 74 6d 74 20 7c 20 70 72 sqlite_stmt | pr
f660: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
f670: 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 ] for the first
f680: 74 69 6d 65 2c 0a 2a 2a 20 74 68 69 73 20 72 6f time,.** this ro
f690: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 utine returns ze
f6a0: 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ro..*/.int sqlit
f6b0: 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 e3_data_count(sq
f6c0: 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d lite3_stmt *pStm
f6d0: 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
f6e0: 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c REF: Fundamental
f6f0: 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 0a 2a 2a Datatypes.**.**
f700: 20 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 Every value in
f710: 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f SQLite has one o
f720: 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 f five fundament
f730: 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a al datatypes:.**
f740: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
f750: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 64-bit signed i
f760: 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 nteger.** <li> 6
f770: 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 4-bit IEEE float
f780: 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 ing point number
f790: 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a .** <li> string.
f7a0: 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 ** <li> BLOB.**
f7b0: 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 <li> NULL.** </u
f7c0: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 l>.**.** These c
f7d0: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 onstants are cod
f7e0: 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 es for each of t
f7f0: 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a hose types..**.*
f800: 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 * Note that the
f810: 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 SQLITE_TEXT cons
f820: 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 tant was also us
f830: 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 ed in SQLite ver
f840: 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 sion 2.** for a
f850: 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 completely diffe
f860: 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 rent meaning. S
f870: 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e oftware that lin
f880: 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a ks against both.
f890: 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f ** SQLite versio
f8a0: 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 n 2 and SQLite v
f8b0: 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 ersion 3 should
f8c0: 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 use SQLITE3_TEXT
f8d0: 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 not.** SQLITE_T
f8e0: 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 EXT..*/.#define
f8f0: 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 SQLITE_INTEGER
f900: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
f910: 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 _FLOAT 2.#def
f920: 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 ine SQLITE_BLOB
f930: 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4.#define SQ
f940: 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a LITE_NULL 5.
f950: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 #ifdef SQLITE_TE
f960: 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 XT.# undef SQLIT
f970: 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 E_TEXT.#else.# d
f980: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 efine SQLITE_TEX
f990: 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 T 3.#endif.#
f9a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 define SQLITE3_T
f9b0: 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a EXT 3../*.**
f9c0: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c CAPI3REF: Resul
f9d0: 74 73 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 ts Values From A
f9e0: 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 Query.**.** The
f9f0: 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 se routines retu
fa00: 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 rn information a
fa10: 62 6f 75 74 20 74 68 65 20 69 6e 66 6f 72 6d 61 bout the informa
fa20: 74 69 6f 6e 0a 2a 2a 20 69 6e 20 61 20 73 69 6e tion.** in a sin
fa30: 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 gle column of th
fa40: 65 20 63 75 72 72 65 6e 74 20 72 65 73 75 6c 74 e current result
fa50: 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e row of a query.
fa60: 20 20 49 6e 20 65 76 65 72 79 0a 2a 2a 20 63 61 In every.** ca
fa70: 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 se the first arg
fa80: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 ument is a point
fa90: 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 73 er to the .** [s
faa0: 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 53 51 qlite3_stmt | SQ
fab0: 4c 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 L statement] tha
fac0: 74 20 69 73 20 62 65 69 6e 67 0a 2a 2a 20 65 76 t is being.** ev
fad0: 61 6c 75 61 74 65 20 28 74 68 65 20 5b 73 71 6c aluate (the [sql
fae0: 69 74 65 5f 73 74 6d 74 2a 5d 20 74 68 61 74 20 ite_stmt*] that
faf0: 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f was returned fro
fb00: 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 m .** [sqlite3_p
fb10: 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
fb20: 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 one of its varia
fb30: 6e 74 73 29 20 61 6e 64 0a 2a 2a 20 74 68 65 20 nts) and.** the
fb40: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
fb50: 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 is the index of
fb60: 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 the column for w
fb70: 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e hich information
fb80: 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 .** should be r
fb90: 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 6c 65 eturned. The le
fba0: 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 68 ft-most column h
fbb0: 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 30 as an index of 0
fbc0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 ..**.** If the S
fbd0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 QL statement is
fbe0: 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f not currently po
fbf0: 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 int to a valid r
fc00: 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a ow, or if the.**
fc10: 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 the column inde
fc20: 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 x is out of rang
fc30: 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 e, the result is
fc40: 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
fc50: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f * The sqlite3_co
fc60: 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 lumn_type() rout
fc70: 69 6e 65 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 ine returns .**
fc80: 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 [SQLITE_INTEGER
fc90: 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d | datatype code]
fca0: 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c for the initial
fcb0: 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 data type.** of
fcc0: 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 the result colu
fcd0: 6d 6e 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 mn. The returne
fce0: 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f d value is one o
fcf0: 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 f [SQLITE_INTEGE
fd00: 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 R],.** [SQLITE_F
fd10: 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 LOAT], [SQLITE_T
fd20: 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c EXT], [SQLITE_BL
fd30: 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f OB], or [SQLITE_
fd40: 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 NULL]. The valu
fd50: 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 e.** returned by
fd60: 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
fd70: 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d type() is only m
fd80: 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 eaningful if no
fd90: 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 type.** conversi
fda0: 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 ons have occurre
fdb0: 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62 d as described b
fdc0: 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 elow. After a t
fdd0: 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a ype conversion,.
fde0: 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 ** the value ret
fdf0: 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
fe00: 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 _column_type() i
fe10: 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 s undefined. Fu
fe20: 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 ture.** versions
fe30: 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 of SQLite may c
fe40: 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 hange the behavi
fe50: 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f or of sqlite3_co
fe60: 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 lumn_type().** f
fe70: 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 ollowing a type
fe80: 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a conversion..**.*
fe90: 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 * If the result
fea0: 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 is a BLOB or UTF
feb0: 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 -8 string then t
fec0: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d he sqlite3_colum
fed0: 6e 5f 62 79 74 65 73 28 29 20 0a 2a 2a 20 72 6f n_bytes() .** ro
fee0: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 utine returns th
fef0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
ff00: 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f s in that BLOB o
ff10: 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49 66 20 r string..** If
ff20: 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 the result is a
ff30: 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 UTF-16 string, t
ff40: 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 hen sqlite3_colu
ff50: 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 mn_bytes() conve
ff60: 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e rts.** the strin
ff70: 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 g to UTF-8 and t
ff80: 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 hen returns the
ff90: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e number of bytes.
ffa0: 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c .** If the resul
ffb0: 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 t is a numeric v
ffc0: 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 alue then sqlite
ffd0: 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
ffe0: 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 uses.** [sqlite
fff0: 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 3_snprintf()] to
10000 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 convert that va
10010 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 lue to a UTF-8 s
10020 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e tring and return
10030 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 s.** the number
10040 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 of bytes in that
10050 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 string..** The
10060 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 64 value returned d
10070 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 oes not include
10080 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 the zero termina
10090 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a 2a tor at the end.*
100a0 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e * of the string.
100b0 20 20 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 For clarity: t
100c0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
100d0 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 d is the number
100e0 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 of.** bytes in t
100f0 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 he string, not t
10100 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 he number of cha
10110 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 racters..**.** T
10120 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d he sqlite3_colum
10130 6e 5f 62 79 74 65 73 31 36 28 29 20 72 6f 75 74 n_bytes16() rout
10140 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 ine is similar t
10150 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e o sqlite3_column
10160 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 _bytes().** but
10170 6c 65 61 76 65 73 20 74 68 65 20 72 65 73 75 6c leaves the resul
10180 74 20 69 6e 20 55 54 46 2d 31 36 20 69 6e 73 74 t in UTF-16 inst
10190 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 20 20 0a ead of UTF-8. .
101a0 2a 2a 20 54 68 65 20 7a 65 72 6f 20 74 65 72 6d ** The zero term
101b0 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e inator is not in
101c0 63 6c 75 64 65 64 20 69 6e 20 74 68 69 73 20 63 cluded in this c
101d0 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ount..**.** Thes
101e0 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d e routines attem
101f0 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 pt to convert th
10200 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 e value where ap
10210 70 72 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a propriate. For.
10220 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 ** example, if t
10230 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 he internal repr
10240 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c esentation is FL
10250 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 OAT and a text r
10260 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 esult.** is requ
10270 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f ested, [sqlite3_
10280 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 snprintf()] is u
10290 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 sed internally t
102a0 6f 20 64 6f 20 74 68 65 20 63 6f 6e 76 65 72 73 o do the convers
102b0 69 6f 6e 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 ion.** automatic
102c0 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c 6f ally. The follo
102d0 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 wing table detai
102e0 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f ls the conversio
102f0 6e 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 61 ns that.** are a
10300 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 pplied:.**.** <b
10310 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 lockquote>.** <t
10320 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e able border="1">
10330 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 .** <tr><th> Int
10340 65 72 6e 61 6c 20 3c 74 68 3e 20 52 65 71 75 65 ernal <th> Reque
10350 73 74 65 64 20 3c 74 68 3e 20 0a 2a 2a 20 3c 74 sted <th> .** <t
10360 72 3e 3c 74 68 3e 20 20 54 79 70 65 20 20 20 20 r><th> Type
10370 3c 74 68 3e 20 20 20 20 54 79 70 65 20 20 20 3c <th> Type <
10380 74 68 3e 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a th> Conversion.*
10390 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e *.** <tr><td> N
103a0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 ULL <td> INTE
103b0 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c GER <td> Resul
103c0 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 t is 0.** <tr><t
103d0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e d> NULL <td>
103e0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 FLOAT <td>
103f0 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a Result is 0.0.**
10400 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 <tr><td> NULL
10410 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 <td> TEXT
10420 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 <td> Result is
10430 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a NULL pointer.**
10440 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 <tr><td> NULL
10450 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 <td> BLOB
10460 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 <td> Result is
10470 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a NULL pointer.**
10480 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 <tr><td> INTEGE
10490 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 R <td> FLOAT
104a0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 <td> Convert f
104b0 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 rom integer to f
104c0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e loat.** <tr><td>
104d0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 INTEGER <td>
104e0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 TEXT <td> AS
104f0 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 CII rendering of
10500 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 the integer.**
10510 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 <tr><td> INTEGER
10520 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 <td> BLOB
10530 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 66 6f <td> Same as fo
10540 72 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a r INTEGER->TEXT.
10550 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f ** <tr><td> FLO
10560 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 AT <td> INTEGE
10570 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 R <td> Convert
10580 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 from float to i
10590 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 nteger.** <tr><t
105a0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e d> FLOAT <td>
105b0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 TEXT <td>
105c0 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 ASCII rendering
105d0 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 of the float.**
105e0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 <tr><td> FLOAT
105f0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 <td> BLOB
10600 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c <td> Same as FL
10610 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 OAT->TEXT.** <tr
10620 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c ><td> TEXT <
10630 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 td> INTEGER <t
10640 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a d> Use atoi().**
10650 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 <tr><td> TEXT
10660 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 <td> FLOAT
10670 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 <td> Use atof(
10680 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 ).** <tr><td> T
10690 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c EXT <td> BL
106a0 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 OB <td> No ch
106b0 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e ange.** <tr><td>
106c0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 BLOB <td> I
106d0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f NTEGER <td> Co
106e0 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 nvert to TEXT th
106f0 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a en use atoi().**
10700 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 <tr><td> BLOB
10710 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 <td> FLOAT
10720 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 <td> Convert t
10730 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 o TEXT then use
10740 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 atof().** <tr><t
10750 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e d> BLOB <td>
10760 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 TEXT <td>
10770 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 Add a zero termi
10780 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a nator if needed.
10790 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c ** </table>.** <
107a0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
107b0 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f ** The table abo
107c0 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e ve makes referen
107d0 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 ce to standard C
107e0 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f library functio
107f0 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 ns atoi().** and
10800 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 atof(). SQLite
10810 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 does not really
10820 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 use these funct
10830 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 ions. It has it
10840 73 0a 2a 2a 20 6f 6e 20 65 71 75 61 76 61 6c 65 s.** on equavale
10850 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 nt internal rout
10860 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 ines. The atoi(
10870 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d ) and atof() nam
10880 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 es are.** used i
10890 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 n the table for
108a0 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 brevity and beca
108b0 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d use they are fam
108c0 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a iliar to most.**
108d0 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a C programmers..
108e0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 **.** Note that
108f0 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 when type conver
10900 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 sions occur, poi
10910 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 nters returned b
10920 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 y prior.** calls
10930 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 to sqlite3_colu
10940 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 mn_blob(), sqlit
10950 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
10960 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 , and/or.** sqli
10970 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
10980 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 6() may be inval
10990 69 64 61 74 65 64 2e 20 0a 2a 2a 20 54 79 70 65 idated. .** Type
109a0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 conversions and
109b0 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 pointer invalid
109c0 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 ations might occ
109d0 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c ur.** in the fol
109e0 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a lowing cases:.**
109f0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
10a00 3c 70 3e 20 20 54 68 65 20 69 6e 69 74 69 61 6c <p> The initial
10a10 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c content is a BL
10a20 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 OB and sqlite3_c
10a30 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 0a 2a 2a olumn_text() .**
10a40 20 20 20 20 20 20 20 20 20 20 6f 72 20 73 71 6c or sql
10a50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
10a60 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 16() is called.
10a70 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 A zero-terminat
10a80 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 or might.**
10a90 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 need to be
10aa0 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 added to the str
10ab0 69 6e 67 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a ing.</p></li>.**
10ac0 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 .** <li><p> The
10ad0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 initial content
10ae0 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 is UTF-8 text a
10af0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nd sqlite3_colum
10b00 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a n_bytes16() or.*
10b10 2a 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 * sqlit
10b20 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
10b30 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 () is called. T
10b40 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 he content must
10b50 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 be converted.**
10b60 20 20 20 20 20 20 20 20 20 74 6f 20 55 54 46 2d to UTF-
10b70 31 36 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 16.</p></li>.**.
10b80 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 ** <li><p> The
10b90 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 initial content
10ba0 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 is UTF-16 text a
10bb0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nd sqlite3_colum
10bc0 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 n_bytes() or.**
10bd0 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 sqlite3
10be0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 _column_text() i
10bf0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 s called. The c
10c00 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 ontent must be c
10c10 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 onverted.**
10c20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f to UTF-8.</
10c30 70 3e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e p></li>.** </ul>
10c40 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f .**.** Conversio
10c50 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 ns between UTF-1
10c60 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 6be and UTF-16le
10c70 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 are always done
10c80 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f in place and do
10c90 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 .** not invalida
10ca0 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 te a prior point
10cb0 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f er, though of co
10cc0 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 urse the content
10cd0 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a of the buffer.*
10ce0 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 * that the prior
10cf0 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 pointer points
10d00 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 to will have bee
10d10 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 n modified. Oth
10d20 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 er kinds.** of c
10d30 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f onversion are do
10d40 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e ne in place when
10d50 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c it is possible,
10d60 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 20 69 74 but sometime it
10d70 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 is.** not possi
10d80 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 ble and in those
10d90 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 cases prior poi
10da0 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 nters are invali
10db0 64 61 74 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 dated. .**.** T
10dc0 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 he safest and ea
10dd0 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 siest to remembe
10de0 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 r policy is to i
10df0 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 nvoke these rout
10e00 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f ines.** in one o
10e10 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 f the following
10e20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 20 3c 75 6c ways:.**.** <ul
10e30 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 >.** <li>sqlite
10e40 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 3_column_text()
10e50 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 followed by sqli
10e60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
10e70 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e ()</li>.** <li>
10e80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
10e90 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 lob() followed b
10ea0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e y sqlite3_column
10eb0 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a _bytes()</li>.**
10ec0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f <li>sqlite3_co
10ed0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f lumn_text16() fo
10ee0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 llowed by sqlite
10ef0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
10f00 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 2f 75 6c ()</li>.** </ul
10f10 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 >.**.** In other
10f20 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 words, you shou
10f30 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f ld call sqlite3_
10f40 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 73 column_text(), s
10f50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
10f60 6f 62 28 29 2c 0a 2a 2a 20 6f 72 20 73 71 6c 69 ob(),.** or sqli
10f70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
10f80 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 6() first to for
10f90 63 65 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e ce the result in
10fa0 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 0a 2a to the desired.*
10fb0 2a 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 * format, then i
10fc0 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f nvoke sqlite3_co
10fd0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 20 lumn_bytes() or
10fe0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
10ff0 79 74 65 73 31 36 28 29 20 74 6f 0a 2a 2a 20 66 ytes16() to.** f
11000 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 ind the size of
11010 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 the result. Do
11020 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 20 74 6f 20 not mix call to
11030 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
11040 65 78 74 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 ext() or.** sqli
11050 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
11060 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 ) with calls to
11070 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
11080 79 74 65 73 31 36 28 29 2e 20 20 41 6e 64 20 64 ytes16(). And d
11090 6f 20 6e 6f 74 0a 2a 2a 20 6d 69 78 20 63 61 6c o not.** mix cal
110a0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ls to sqlite3_co
110b0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 77 69 lumn_text16() wi
110c0 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 th calls to sqli
110d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
110e0 28 29 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 ()..*/.const voi
110f0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
11100 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 n_blob(sqlite3_s
11110 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
11120 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c .int sqlite3_col
11130 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 umn_bytes(sqlite
11140 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
11150 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f l);.int sqlite3_
11160 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 column_bytes16(s
11170 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
11180 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 t iCol);.double
11190 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
111a0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 ouble(sqlite3_st
111b0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
111c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 int sqlite3_colu
111d0 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 mn_int(sqlite3_s
111e0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
111f0 0a 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 .sqlite_int64 sq
11200 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 lite3_column_int
11210 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 64(sqlite3_stmt*
11220 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e , int iCol);.con
11230 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 st unsigned char
11240 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
11250 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 _text(sqlite3_st
11260 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
11270 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
11280 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
11290 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
112a0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 int iCol);.int
112b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
112c0 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ype(sqlite3_stmt
112d0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 *, int iCol);.sq
112e0 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c lite3_value *sql
112f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 ite3_column_valu
11300 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
11310 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a int iCol);../*.
11320 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 ** CAPI3REF: Des
11330 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 troy A Prepared
11340 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 Statement Object
11350 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
11360 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 e3_finalize() fu
11370 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 nction is called
11380 20 74 6f 20 64 65 6c 65 74 65 20 61 20 0a 2a 2a to delete a .**
11390 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c [sqlite3_stmt |
113a0 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 compiled SQL st
113b0 61 74 65 6d 65 6e 74 5d 2e 20 49 66 20 74 68 65 atement]. If the
113c0 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a statement was.*
113d0 2a 20 65 78 65 63 75 74 65 64 20 73 75 63 63 65 * executed succe
113e0 73 73 66 75 6c 6c 79 2c 20 6f 72 20 6e 6f 74 20 ssfully, or not
113f0 65 78 65 63 75 74 65 64 20 61 74 20 61 6c 6c 2c executed at all,
11400 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 then SQLITE_OK
11410 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 is returned..**
11420 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 If execution of
11430 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61 the statement fa
11440 69 6c 65 64 20 74 68 65 6e 20 61 6e 20 0a 2a 2a iled then an .**
11450 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c [SQLITE_ERROR |
11460 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 error code] or
11470 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 [SQLITE_IOERR_RE
11480 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 65 72 AD | extended er
11490 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 69 73 20 ror code].** is
114a0 72 65 74 75 72 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a returned. .**.**
114b0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 This routine ca
114c0 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 n be called at a
114d0 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 ny point during
114e0 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 the execution of
114f0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
11500 5f 73 74 6d 74 20 7c 20 76 69 72 74 75 61 6c 20 _stmt | virtual
11510 6d 61 63 68 69 6e 65 5d 2e 20 20 49 66 20 74 68 machine]. If th
11520 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e e virtual machin
11530 65 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 63 6f e has not .** co
11540 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f mpleted executio
11550 6e 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74 n when this rout
11560 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 ine is called, t
11570 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 hat is like.** e
11580 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 ncountering an e
11590 72 72 6f 72 20 6f 72 20 61 6e 20 69 6e 74 65 72 rror or an inter
115a0 72 75 70 74 2e 20 20 28 53 65 65 20 5b 73 71 6c rupt. (See [sql
115b0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
115c0 5d 2e 29 20 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 ].) .** Incomple
115d0 74 65 20 75 70 64 61 74 65 73 20 6d 61 79 20 62 te updates may b
115e0 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e e rolled back an
115f0 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 d transactions c
11600 61 6e 63 65 6c 6c 65 64 2c 20 20 0a 2a 2a 20 64 ancelled, .** d
11610 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 epending on the
11620 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61 circumstances, a
11630 6e 64 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 nd the .** [SQLI
11640 54 45 5f 45 52 52 4f 52 20 7c 20 72 65 73 75 6c TE_ERROR | resul
11650 74 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64 t code] returned
11660 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 will be [SQLITE
11670 5f 41 42 4f 52 54 5d 2e 0a 2a 2f 0a 69 6e 74 20 _ABORT]..*/.int
11680 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
11690 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 (sqlite3_stmt *p
116a0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Stmt);../*.** CA
116b0 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 PI3REF: Reset A
116c0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 Prepared Stateme
116d0 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 nt Object.**.**
116e0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 The sqlite3_rese
116f0 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 t() function is
11700 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 called to reset
11710 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 73 74 a .** [sqlite_st
11720 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51 mt | compiled SQ
11730 4c 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a L statement] obj
11740 65 63 74 2e 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 ect..** back to
11750 69 74 27 73 20 69 6e 69 74 69 61 6c 20 73 74 61 it's initial sta
11760 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 te, ready to be
11770 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 re-executed..**
11780 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e Any SQL statemen
11790 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 t variables that
117a0 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e had values boun
117b0 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a d to them using.
117c0 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f ** the [sqlite3_
117d0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 bind_blob | sqli
117e0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 te3_bind_*() API
117f0 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 ] retain their v
11800 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 alues..** Use [s
11810 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e qlite3_clear_bin
11820 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 dings()] to rese
11830 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a t the bindings..
11840 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 */.int sqlite3_r
11850 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d eset(sqlite3_stm
11860 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
11870 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 * CAPI3REF: Crea
11880 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 te Or Redefine S
11890 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a QL Functions.**.
118a0 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 ** The following
118b0 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 61 two functions a
118c0 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 re used to add S
118d0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 QL functions or
118e0 61 67 67 72 65 67 61 74 65 73 0a 2a 2a 20 6f 72 aggregates.** or
118f0 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 to redefine the
11900 20 62 65 68 61 76 69 6f 72 20 6f 66 20 65 78 69 behavior of exi
11910 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 sting SQL functi
11920 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 ons or aggregate
11930 73 2e 20 20 54 68 65 0a 2a 2a 20 64 69 66 66 65 s. The.** diffe
11940 72 65 6e 63 65 20 6f 6e 6c 79 20 62 65 74 77 65 rence only betwe
11950 65 6e 20 74 68 65 20 74 77 6f 20 69 73 20 74 68 en the two is th
11960 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 at the second pa
11970 72 61 6d 65 74 65 72 2c 20 74 68 65 0a 2a 2a 20 rameter, the.**
11980 6e 61 6d 65 20 6f 66 20 74 68 65 20 28 73 63 61 name of the (sca
11990 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72 lar) function or
119a0 20 61 67 67 72 65 67 61 74 65 2c 20 69 73 20 65 aggregate, is e
119b0 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 20 ncoded in UTF-8
119c0 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 for.** sqlite3_c
119d0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
119e0 20 61 6e 64 20 55 54 46 2d 31 36 20 66 6f 72 20 and UTF-16 for
119f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
11a00 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a unction16()..**.
11a10 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 ** The first arg
11a20 75 6d 65 6e 74 20 69 73 20 74 68 65 20 5b 73 71 ument is the [sq
11a30 6c 69 74 65 33 20 7c 20 64 61 74 61 62 61 73 65 lite3 | database
11a40 20 68 61 6e 64 6c 65 5d 20 74 68 61 74 20 68 6f handle] that ho
11a50 6c 64 73 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 lds the.** SQL f
11a60 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 unction or aggre
11a70 67 61 74 65 20 69 73 20 74 6f 20 62 65 20 61 64 gate is to be ad
11a80 64 65 64 20 6f 72 20 72 65 64 65 66 69 6e 65 64 ded or redefined
11a90 2e 20 49 66 20 61 20 73 69 6e 67 6c 65 0a 2a 2a . If a single.**
11aa0 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 6d 6f program uses mo
11ab0 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 re than one data
11ac0 62 61 73 65 20 68 61 6e 64 6c 65 20 69 6e 74 65 base handle inte
11ad0 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c rnally, then SQL
11ae0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 .** functions or
11af0 20 61 67 67 72 65 67 61 74 65 73 20 6d 75 73 74 aggregates must
11b00 20 62 65 20 61 64 64 65 64 20 69 6e 64 69 76 69 be added indivi
11b10 64 75 61 6c 6c 79 20 74 6f 20 65 61 63 68 20 64 dually to each d
11b20 61 74 61 62 61 73 65 0a 2a 2a 20 68 61 6e 64 6c atabase.** handl
11b30 65 20 77 69 74 68 20 77 68 69 63 68 20 74 68 65 e with which the
11b40 79 20 77 69 6c 6c 20 62 65 20 75 73 65 64 2e 0a y will be used..
11b50 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 **.** The second
11b60 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
11b70 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 e name of the SQ
11b80 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 L function to be
11b90 20 63 72 65 61 74 65 64 0a 2a 2a 20 6f 72 20 72 created.** or r
11ba0 65 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 edefined..** The
11bb0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e length of the n
11bc0 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 ame is limited t
11bd0 6f 20 32 35 35 20 62 79 74 65 73 2c 20 65 78 63 o 255 bytes, exc
11be0 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 0a 2a lusive of the .*
11bf0 2a 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f * zero-terminato
11c00 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 r. Note that th
11c10 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69 e name length li
11c20 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65 73 2c mit is in bytes,
11c30 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74 65 not.** characte
11c40 72 73 2e 20 20 41 6e 79 20 61 74 74 65 6d 70 74 rs. Any attempt
11c50 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e to create a fun
11c60 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e ction with a lon
11c70 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c ger name.** will
11c80 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 53 51 result in an SQ
11c90 4c 49 54 45 5f 45 52 52 4f 52 20 65 72 72 6f 72 LITE_ERROR error
11ca0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 ..**.** The thir
11cb0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 d parameter is t
11cc0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 he number of arg
11cd0 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 uments that the
11ce0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a SQL function or.
11cf0 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b ** aggregate tak
11d00 65 73 2e 20 49 66 20 74 68 69 73 20 70 61 72 61 es. If this para
11d10 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 meter is negativ
11d20 65 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 e, then the SQL
11d30 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 function or.** a
11d40 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b ggregate may tak
11d50 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 e any number of
11d60 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a arguments..**.**
11d70 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 The fourth para
11d80 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c meter, eTextRep,
11d90 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 20 specifies what
11da0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 .** [SQLITE_UTF8
11db0 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 | text encoding
11dc0 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 ] this SQL funct
11dd0 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a ion prefers for.
11de0 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 ** its parameter
11df0 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e 63 s. Any SQL func
11e00 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 tion implementat
11e10 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61 62 ion should be ab
11e20 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f le to work.** wo
11e30 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 rk with UTF-8, U
11e40 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d TF-16le, or UTF-
11e50 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 16be. But some
11e60 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
11e70 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 may be.** more e
11e80 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e fficient with on
11e90 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 e encoding than
11ea0 61 6e 6f 74 68 65 72 2e 20 20 49 74 20 69 73 20 another. It is
11eb0 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20 69 6e allowed to.** in
11ec0 76 6f 6b 65 20 73 71 6c 69 74 65 5f 63 72 65 61 voke sqlite_crea
11ed0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 te_function() or
11ee0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
11ef0 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c function16() mul
11f00 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 tiple.** times w
11f10 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e ith the same fun
11f20 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64 ction but with d
11f30 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20 ifferent values
11f40 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 of eTextRep..**
11f50 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d When multiple im
11f60 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 plementations of
11f70 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 the same functi
11f80 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 on are available
11f90 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c , SQLite.** will
11fa0 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 pick the one th
11fb0 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 at involves the
11fc0 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 least amount of
11fd0 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e data conversion.
11fe0 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 .** If there is
11ff0 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d only a single im
12000 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 plementation whi
12010 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 ch does not care
12020 20 77 68 61 74 0a 2a 2a 20 74 65 78 74 20 65 6e what.** text en
12030 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 coding is used,
12040 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 then the fourth
12050 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 argument should
12060 62 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 41 4e be.** [SQLITE_AN
12070 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 Y]..**.** The fi
12080 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 fth parameter is
12090 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f an arbitrary po
120a0 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c inter. The impl
120b0 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 ementation.** of
120c0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 63 61 the function ca
120d0 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f n gain access to
120e0 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 this pointer us
120f0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 75 ing.** [sqlite_u
12100 73 65 72 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a ser_data()]..**.
12110 2a 2a 20 54 68 65 20 73 65 76 65 6e 74 68 2c 20 ** The seventh,
12120 65 69 67 68 74 68 20 61 6e 64 20 6e 69 6e 74 68 eighth and ninth
12130 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 parameters, xFu
12140 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 nc, xStep and xF
12150 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 inal, are.** poi
12160 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 nters to C-langu
12170 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 age functions th
12180 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 at implement the
12190 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e SQL.** function
121a0 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 20 41 or aggregate. A
121b0 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 scalar SQL func
121c0 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e tion requires an
121d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
121e0 6f 66 0a 2a 2a 20 74 68 65 20 78 46 75 6e 63 20 of.** the xFunc
121f0 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e callback only, N
12200 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 73 68 6f ULL pointers sho
12210 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 61 73 uld be passed as
12220 20 74 68 65 20 78 53 74 65 70 0a 2a 2a 20 61 6e the xStep.** an
12230 64 20 78 46 69 6e 61 6c 20 70 61 72 61 6d 65 74 d xFinal paramet
12240 65 72 73 2e 20 41 6e 20 61 67 67 72 65 67 61 74 ers. An aggregat
12250 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 e SQL function r
12260 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 equires an imple
12270 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 mentation.** of
12280 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c xStep and xFinal
12290 20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 and NULL should
122a0 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 be passed for x
122b0 46 75 6e 63 2e 20 54 6f 20 64 65 6c 65 74 65 20 Func. To delete
122c0 61 6e 0a 2a 2a 20 65 78 69 73 74 69 6e 67 20 53 an.** existing S
122d0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 QL function or a
122e0 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e ggregate, pass N
122f0 55 4c 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 ULL for all thre
12300 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 e function.** ca
12310 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 74 llback..**.** It
12320 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f is permitted to
12330 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 register multip
12340 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
12350 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a ns of the same.*
12360 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 * functions with
12370 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 the same name b
12380 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64 ut with either d
12390 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 iffering numbers
123a0 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 of.** arguments
123b0 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 65 or differing pe
123c0 72 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 rferred text enc
123d0 6f 64 69 6e 67 73 2e 20 20 53 51 4c 69 74 65 20 odings. SQLite
123e0 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 will use.** the
123f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d implementation m
12400 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 ost closely matc
12410 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 hes the way in w
12420 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 hich the.** SQL
12430 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 function is used
12440 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
12450 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
12460 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 2c 0a 20 (. sqlite3 *,.
12470 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 const char *zFu
12480 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e nctionName,. in
12490 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 t nArg,. int eT
124a0 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 2a 2c extRep,. void*,
124b0 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 . void (*xFunc)
124c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
124d0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
124e0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
124f0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f *xStep)(sqlite3_
12500 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c context*,int,sql
12510 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 ite3_value**),.
12520 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 void (*xFinal)(
12530 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
12540 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 ).);.int sqlite3
12550 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
12560 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 16(. sqlite3*,.
12570 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 const void *zF
12580 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 unctionName,. i
12590 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 nt nArg,. int e
125a0 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 2a TextRep,. void*
125b0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 ,. void (*xFunc
125c0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 )(sqlite3_contex
125d0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 t*,int,sqlite3_v
125e0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 alue**),. void
125f0 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 (*xStep)(sqlite3
12600 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 _context*,int,sq
12610 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a lite3_value**),.
12620 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 void (*xFinal)
12630 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
12640 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 *).);../*.** CAP
12650 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f I3REF: Text Enco
12660 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 dings.**.** Thes
12670 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e e constant defin
12680 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 e integer codes
12690 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 that represent t
126a0 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 he various.** te
126b0 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 xt encodings sup
126c0 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 ported by SQLite
126d0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
126e0 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 ITE_UTF8
126f0 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 1.#define SQL
12700 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 ITE_UTF16LE
12710 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 2.#define SQL
12720 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 ITE_UTF16BE
12730 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 3.#define SQL
12740 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 ITE_UTF16
12750 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 4 /* Use n
12760 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
12770 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
12780 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 TE_ANY
12790 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 5 /* sqlite
127a0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
127b0 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e n only */.#defin
127c0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 e SQLITE_UTF16_A
127d0 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 LIGNED 8 /*
127e0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
127f0 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f ollation only */
12800 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
12810 3a 20 4f 62 73 6f 6c 65 74 65 20 46 75 6e 63 74 : Obsolete Funct
12820 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ions.**.** These
12830 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 61 functions are a
12840 6c 6c 20 6e 6f 77 20 6f 62 73 6f 6c 65 74 65 2e ll now obsolete.
12850 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 In order to ma
12860 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 intain.** backwa
12870 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 rds compatibilit
12880 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 y with older cod
12890 65 2c 20 77 65 20 63 6f 6e 74 69 6e 75 65 20 74 e, we continue t
128a0 6f 20 73 75 70 70 6f 72 74 0a 2a 2a 20 74 68 65 o support.** the
128b0 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 48 se functions. H
128c0 6f 77 65 76 65 72 2c 20 6e 65 77 20 64 65 76 65 owever, new deve
128d0 6c 6f 70 6d 65 6e 74 20 70 72 6f 6a 65 63 74 73 lopment projects
128e0 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a should avoid.**
128f0 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 the use of thes
12900 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f e functions. To
12910 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 help encourage
12920 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a people to avoid.
12930 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 ** using these f
12940 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 unctions, we are
12950 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 not going to te
12960 6c 6c 20 79 6f 75 20 77 61 6e 74 20 74 68 65 79 ll you want they
12970 20 64 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 do..*/.int sqli
12980 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
12990 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 unt(sqlite3_cont
129a0 65 78 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 ext*);.int sqlit
129b0 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 e3_expired(sqlit
129c0 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 e3_stmt*);.int s
129d0 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f qlite3_transfer_
129e0 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 bindings(sqlite3
129f0 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f _stmt*, sqlite3_
12a00 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 stmt*);.int sqli
12a10 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 te3_global_recov
12a20 65 72 28 76 6f 69 64 29 3b 0a 0a 0a 2f 2a 0a 2a er(void);.../*.*
12a30 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 * CAPI3REF: Obta
12a40 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 ining SQL Functi
12a50 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c on Parameter Val
12a60 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d ues.**.** The C-
12a70 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 language impleme
12a80 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 ntation of SQL f
12a90 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 unctions and agg
12aa0 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 regates uses.**
12ab0 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 this set of inte
12ac0 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 rface routines t
12ad0 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 o access the par
12ae0 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e ameter values on
12af0 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e .** the function
12b00 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a or aggregate..*
12b10 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 *.** The xFunc (
12b20 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 for scalar funct
12b30 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 ions) or xStep (
12b40 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 for aggregates)
12b50 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f parameters.** to
12b60 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
12b70 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 _function()] and
12b80 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
12b90 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a _function16()].*
12ba0 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 * define callbac
12bb0 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e ks that implemen
12bc0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 t the SQL functi
12bd0 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 ons and aggregat
12be0 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 es..** The 4th p
12bf0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 arameter to thes
12c00 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 e callbacks is a
12c10 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 n array of point
12c20 65 72 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 ers to.** [sqlit
12c30 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
12c40 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 s. There is one
12c50 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d [sqlite3_value]
12c60 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 object for.** e
12c70 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f ach parameter to
12c80 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
12c90 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e n. These routin
12ca0 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a es are used to.*
12cb0 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 * extract values
12cc0 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 from the [sqlit
12cd0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
12ce0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 s..**.** These r
12cf0 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 outines work jus
12d00 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 t like the corre
12d10 73 70 6f 6e 64 69 6e 67 20 0a 2a 2a 20 5b 73 71 sponding .** [sq
12d20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
12d30 62 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 b | sqlite3_colu
12d40 6d 6e 5f 2a 20 72 6f 75 74 69 6e 65 73 5d 20 65 mn_* routines] e
12d50 78 63 65 70 74 20 74 68 61 74 20 0a 2a 2a 20 74 xcept that .** t
12d60 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 hese routines ta
12d70 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 73 71 6c ke a single [sql
12d80 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 6f 69 ite3_value*] poi
12d90 6e 74 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 nter instead.**
12da0 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 73 of an [sqlite3_s
12db0 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e tmt*] pointer an
12dc0 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c d an integer col
12dd0 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a umn number..**.*
12de0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 * The sqlite3_va
12df0 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 lue_text16() int
12e00 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 erface extracts
12e10 61 20 55 54 46 31 36 20 73 74 72 69 6e 67 0a 2a a UTF16 string.*
12e20 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 * in the native
12e30 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 byte-order of th
12e40 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 e host machine.
12e50 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f The.** sqlite3_
12e60 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 value_text16be()
12e70 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c and sqlite3_val
12e80 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e ue_text16le() in
12e90 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 terfaces.** extr
12ea0 61 63 74 20 55 54 46 31 36 20 73 74 72 69 6e 67 act UTF16 string
12eb0 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 s as big-endian
12ec0 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 and little-endia
12ed0 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a n respectively..
12ee0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
12ef0 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 3_value_numeric_
12f00 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 type() interface
12f10 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 attempts to app
12f20 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 ly.** numeric af
12f30 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 finity to the va
12f40 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 lue. This means
12f50 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 that an attempt
12f60 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 is.** made to c
12f70 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 onvert the value
12f80 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f to an integer o
12f90 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 r floating point
12fa0 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 . If.** such a
12fb0 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f conversion is po
12fc0 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c ssible without l
12fd0 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 oss of informati
12fe0 6f 6e 20 28 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 on (in order.**
12ff0 77 6f 72 64 73 20 69 66 20 74 68 65 20 76 61 6c words if the val
13000 75 65 20 69 73 20 6f 72 69 67 69 6e 61 6c 20 61 ue is original a
13010 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f string that loo
13020 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 ks like a number
13030 29 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 ).** then it is
13040 64 6f 6e 65 2e 20 20 4f 74 68 65 72 77 69 73 65 done. Otherwise
13050 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f no conversion o
13060 63 63 75 72 73 2e 20 20 54 68 65 20 0a 2a 2a 20 ccurs. The .**
13070 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 [SQLITE_INTEGER
13080 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 | datatype] afte
13090 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 r conversion is
130a0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
130b0 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69 Please pay parti
130c0 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 cular attention
130d0 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74 to the fact that
130e0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 the pointer tha
130f0 74 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 t.** is returned
13100 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 from [sqlite3_v
13110 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 alue_blob()], [s
13120 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
13130 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c t()], or.** [sql
13140 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
13150 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6()] can be inva
13160 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 lidated by a sub
13170 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a sequent call to.
13180 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ** [sqlite3_valu
13190 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c e_bytes()], [sql
131a0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 ite3_value_bytes
131b0 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 5f 76 16()], [sqlite_v
131c0 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a alue_text()],.**
131d0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c or [sqlite3_val
131e0 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 20 20 0a ue_text16()]. .
131f0 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 */.const void *s
13200 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f qlite3_value_blo
13210 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a b(sqlite3_value*
13220 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 );.int sqlite3_v
13230 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 alue_bytes(sqlit
13240 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 e3_value*);.int
13250 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 sqlite3_value_by
13260 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 tes16(sqlite3_va
13270 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 lue*);.double sq
13280 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 lite3_value_doub
13290 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 le(sqlite3_value
132a0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f *);.int sqlite3_
132b0 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 value_int(sqlite
132c0 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 3_value*);.sqlit
132d0 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f e_int64 sqlite3_
132e0 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 value_int64(sqli
132f0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e te3_value*);.con
13300 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 st unsigned char
13310 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f *sqlite3_value_
13320 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c text(sqlite3_val
13330 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 ue*);.const void
13340 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f *sqlite3_value_
13350 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 text16(sqlite3_v
13360 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f alue*);.const vo
13370 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 id *sqlite3_valu
13380 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 e_text16le(sqlit
13390 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 e3_value*);.cons
133a0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
133b0 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 value_text16be(s
133c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
133d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 int sqlite3_valu
133e0 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 e_type(sqlite3_v
133f0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 alue*);.int sqli
13400 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 te3_value_numeri
13410 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 c_type(sqlite3_v
13420 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 alue*);../*.** C
13430 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 API3REF: Obtain
13440 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 Aggregate Functi
13450 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a on Context.**.**
13460 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 The implementat
13470 69 6f 6e 20 6f 66 20 61 67 67 72 65 67 61 74 65 ion of aggregate
13480 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 SQL functions u
13490 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 se this routine
134a0 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61 to allocate.** a
134b0 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 73 structure for s
134c0 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 toring their sta
134d0 74 65 2e 20 20 54 68 65 20 66 69 72 73 74 20 74 te. The first t
134e0 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 ime this routine
134f0 0a 2a 2a 20 69 73 20 63 61 6c 6c 65 64 20 66 6f .** is called fo
13500 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 r a particular a
13510 67 67 72 65 67 61 74 65 2c 20 61 20 6e 65 77 20 ggregate, a new
13520 73 74 72 75 63 74 75 72 65 20 6f 66 20 73 69 7a structure of siz
13530 65 20 6e 42 79 74 65 73 0a 2a 2a 20 69 73 20 61 e nBytes.** is a
13540 6c 6c 6f 63 61 74 65 64 2c 20 7a 65 72 6f 65 64 llocated, zeroed
13550 2c 20 61 6e 64 20 72 65 74 75 72 6e 65 64 2e 20 , and returned.
13560 20 4f 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 On subsequent c
13570 61 6c 6c 73 20 28 66 6f 72 20 74 68 65 0a 2a 2a alls (for the.**
13580 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 same aggregate
13590 69 6e 73 74 61 6e 63 65 29 20 74 68 65 20 73 61 instance) the sa
135a0 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74 me buffer is ret
135b0 75 72 6e 65 64 2e 20 20 54 68 65 20 69 6d 70 6c urned. The impl
135c0 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 ementation.** of
135d0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 63 the aggregate c
135e0 61 6e 20 75 73 65 20 74 68 65 20 72 65 74 75 72 an use the retur
135f0 6e 65 64 20 62 75 66 66 65 72 20 74 6f 20 61 63 ned buffer to ac
13600 63 75 6d 75 6c 61 74 65 20 64 61 74 61 2e 0a 2a cumulate data..*
13610 2a 0a 2a 2a 20 54 68 65 20 62 75 66 66 65 72 20 *.** The buffer
13620 61 6c 6c 6f 63 61 74 65 64 20 69 73 20 66 72 65 allocated is fre
13630 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ed automatically
13640 20 62 79 20 53 51 4c 69 74 65 20 77 68 61 6e 20 by SQLite whan
13650 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a the aggregate.**
13660 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 query concludes
13670 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 ..**.** The firs
13680 74 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 t parameter shou
13690 6c 64 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 ld be a copy of
136a0 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the .** [sqlite3
136b0 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 _context | SQL f
136c0 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d unction context]
136d0 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72 that is the fir
136e0 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 st.** parameter
136f0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 to the callback
13700 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 routine that imp
13710 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 lements the aggr
13720 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f egate.** functio
13730 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 n..*/.void *sqli
13740 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
13750 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f ntext(sqlite3_co
13760 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 ntext*, int nByt
13770 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 es);../*.** CAPI
13780 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 3REF: User Data
13790 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a For Functions.**
137a0 0a 2a 2a 20 54 68 65 20 70 55 73 65 72 44 61 74 .** The pUserDat
137b0 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 a parameter to t
137c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 he [sqlite3_crea
137d0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a te_function()].*
137e0 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 * and [sqlite3_c
137f0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
13800 28 29 5d 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 ()] routines.**
13810 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 used to register
13820 20 75 73 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 user functions
13830 69 73 20 61 76 61 69 6c 61 62 6c 65 20 74 6f 0a is available to.
13840 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 ** the implement
13850 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 66 75 6e ation of the fun
13860 63 74 69 6f 6e 20 75 73 69 6e 67 20 74 68 69 73 ction using this
13870 20 63 61 6c 6c 2e 0a 2a 2f 0a 76 6f 69 64 20 2a call..*/.void *
13880 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 sqlite3_user_dat
13890 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 a(sqlite3_contex
138a0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
138b0 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 3REF: Function A
138c0 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a uxiliary Data.**
138d0 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e .** The followin
138e0 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 g two functions
138f0 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73 may be used by s
13900 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 calar SQL functi
13910 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 ons to.** associ
13920 61 74 65 20 6d 65 74 61 2d 64 61 74 61 20 77 69 ate meta-data wi
13930 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 th argument valu
13940 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 es. If the same
13950 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 value is passed
13960 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 to.** multiple i
13970 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 nvocations of th
13980 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 e same SQL funct
13990 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 ion during query
139a0 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 execution, unde
139b0 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d r.** some circum
139c0 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f stances the asso
139d0 63 69 61 74 65 64 20 6d 65 74 61 2d 64 61 74 61 ciated meta-data
139e0 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 may be preserve
139f0 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 d. This may.** b
13a00 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d e used, for exam
13a10 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 ple, to add a re
13a20 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e gular-expression
13a30 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 matching scalar
13a40 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 .** function. Th
13a50 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 e compiled versi
13a60 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 on of the regula
13a70 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 r expression is
13a80 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 stored as.** met
13a90 61 2d 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 a-data associate
13aa0 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 d with the SQL v
13ab0 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 alue passed as t
13ac0 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 he regular expre
13ad0 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e ssion.** pattern
13ae0 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 . The compiled
13af0 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 regular expressi
13b00 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 on can be reused
13b10 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 on multiple.**
13b20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 invocations of t
13b30 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e he same function
13b40 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 so that the ori
13b50 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 ginal pattern st
13b60 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 ring.** does not
13b70 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f need to be reco
13b80 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 mpiled on each i
13b90 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a nvocation..**.**
13ba0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 The sqlite3_get
13bb0 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 _auxdata() inter
13bc0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 face returns a p
13bd0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 ointer to the me
13be0 74 61 2d 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 ta-data.** assoc
13bf0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 4e iated with the N
13c00 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 th argument valu
13c10 65 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 e to the current
13c20 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a SQL function.**
13c30 20 63 61 6c 6c 2c 20 77 68 65 72 65 20 4e 20 69 call, where N i
13c40 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 s the second par
13c50 61 6d 65 74 65 72 2e 20 49 66 20 6e 6f 20 6d 65 ameter. If no me
13c60 74 61 2d 64 61 74 61 20 68 61 73 20 62 65 65 6e ta-data has been
13c70 20 73 65 74 20 66 6f 72 0a 2a 2a 20 74 68 61 74 set for.** that
13c80 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 20 4e value, then a N
13c90 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 ULL pointer is r
13ca0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 eturned..**.** T
13cb0 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 he sqlite3_set_a
13cc0 75 78 64 61 74 61 28 29 20 69 73 20 75 73 65 64 uxdata() is used
13cd0 20 74 6f 20 61 73 73 6f 63 69 61 74 65 20 6d 65 to associate me
13ce0 74 61 2d 64 61 74 61 20 77 69 74 68 20 61 6e 20 ta-data with an
13cf0 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 SQL.** function
13d00 61 72 67 75 6d 65 6e 74 2e 20 54 68 65 20 74 68 argument. The th
13d10 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ird parameter is
13d20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
13d30 65 20 6d 65 74 61 2d 64 61 74 61 0a 2a 2a 20 74 e meta-data.** t
13d40 6f 20 62 65 20 61 73 73 6f 63 69 61 74 65 64 20 o be associated
13d50 77 69 74 68 20 74 68 65 20 4e 74 68 20 75 73 65 with the Nth use
13d60 72 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d r function argum
13d70 65 6e 74 20 76 61 6c 75 65 2e 20 54 68 65 20 66 ent value. The f
13d80 6f 75 72 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 ourth.** paramet
13d90 65 72 20 73 70 65 63 69 66 69 65 73 20 61 20 64 er specifies a d
13da0 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 77 estructor that w
13db0 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e ill be called on
13dc0 20 74 68 65 20 6d 65 74 61 2d 0a 2a 2a 20 64 61 the meta-.** da
13dd0 74 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 72 65 ta pointer to re
13de0 6c 65 61 73 65 20 69 74 20 77 68 65 6e 20 69 74 lease it when it
13df0 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 is no longer re
13e00 71 75 69 72 65 64 2e 20 49 66 20 74 68 65 20 0a quired. If the .
13e10 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 ** destructor is
13e20 20 4e 55 4c 4c 2c 20 69 74 20 69 73 20 6e 6f 74 NULL, it is not
13e30 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 invoked..**.**
13e40 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 In practice, met
13e50 61 2d 64 61 74 61 20 69 73 20 70 72 65 73 65 72 a-data is preser
13e60 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 ved between func
13e70 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a tion calls for.*
13e80 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 * expressions th
13e90 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 at are constant
13ea0 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e at compile time.
13eb0 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c This includes l
13ec0 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 iteral.** values
13ed0 20 61 6e 64 20 53 51 4c 20 76 61 72 69 61 62 6c and SQL variabl
13ee0 65 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c es..*/.void *sql
13ef0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 ite3_get_auxdata
13f00 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
13f10 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 *, int);.void sq
13f20 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 lite3_set_auxdat
13f30 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 a(sqlite3_contex
13f40 74 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 2a 2c 20 t*, int, void*,
13f50 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 void (*)(void*))
13f60 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 ;.../*.** CAPI3R
13f70 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 EF: Constants De
13f80 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 fining Special D
13f90 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 estructor Behavi
13fa0 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 or.**.** These a
13fb0 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 re special value
13fc0 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 for the destruc
13fd0 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73 tor that is pass
13fe0 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 ed in as the.**
13ff0 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 final argument t
14000 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 o routines like
14010 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
14020 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20 74 68 65 blob()]. If the
14030 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 destructor.** a
14040 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 rgument is SQLIT
14050 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 E_STATIC, it mea
14060 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 ns that the cont
14070 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 ent pointer is c
14080 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 onstant.** and w
14090 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 ill never change
140a0 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e . It does not n
140b0 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f eed to be destro
140c0 79 65 64 2e 20 20 54 68 65 20 0a 2a 2a 20 53 51 yed. The .** SQ
140d0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 LITE_TRANSIENT v
140e0 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 alue means that
140f0 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c the content will
14100 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 likely change i
14110 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 n.** the near fu
14120 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 ture and that SQ
14130 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 Lite should make
14140 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 its own private
14150 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 copy of.** the
14160 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 content before r
14170 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 eturning..**.**
14180 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e The typedef is n
14190 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b ecessary to work
141a0 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 around problems
141b0 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 in certain.** C
141c0 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 ++ compilers. S
141d0 65 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e ee ticket #2191.
141e0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 .*/.typedef void
141f0 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 (*sqlite3_destr
14200 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 uctor_type)(void
14210 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 *);.#define SQLI
14220 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 TE_STATIC (
14230 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 (sqlite3_destruc
14240 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 tor_type)0).#def
14250 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 ine SQLITE_TRANS
14260 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 IENT ((sqlite3
14270 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 _destructor_type
14280 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 )-1)../*.** CAPI
14290 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 3REF: Setting Th
142a0 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 e Result Of An S
142b0 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a QL Function.**.*
142c0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
142d0 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 are used by the
142e0 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c xFunc or xFinal
142f0 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a callbacks that.
14300 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c ** implement SQL
14310 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 functions and a
14320 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a ggregates. See.
14330 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 ** [sqlite3_crea
14340 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 te_function()] a
14350 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 nd [sqlite3_crea
14360 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d te_function16()]
14370 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e .** for addition
14380 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a al information..
14390 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 **.** These func
143a0 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 tions work very
143b0 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 0a 2a much like the .*
143c0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
143d0 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 blob | sqlite3_b
143e0 69 6e 64 5f 2a 5d 20 66 61 6d 69 6c 79 20 6f 66 ind_*] family of
143f0 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 0a functions used.
14400 2a 2a 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 ** to bind value
14410 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 s to host parame
14420 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 ters in prepared
14430 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 statements..**
14440 52 65 66 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 Refer to the.**
14450 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
14460 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e ob | sqlite3_bin
14470 64 5f 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f d_* documentatio
14480 6e 5d 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 n] for.** additi
14490 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
144a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
144b0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
144c0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 () and sqlite3_r
144d0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 esult_error16()
144e0 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 functions.** cau
144f0 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 se the implement
14500 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 ed SQL function
14510 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 to throw an exce
14520 70 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 70 ption. The.** p
14530 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
14540 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
14550 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 () or sqlite3_re
14560 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a sult_error16().*
14570 2a 20 69 73 20 74 68 65 20 74 65 78 74 20 6f 66 * is the text of
14580 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 an error messag
14590 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c e..**.** The sql
145a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 ite3_result_toob
145b0 69 67 28 29 20 63 61 75 73 65 20 74 68 65 20 66 ig() cause the f
145c0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e unction implemen
145d0 74 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 72 tation.** to thr
145e0 6f 77 20 61 6e 64 20 65 72 72 6f 72 20 69 6e 64 ow and error ind
145f0 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 icating that a s
14600 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 tring or BLOB is
14610 20 74 6f 20 6c 6f 6e 67 0a 2a 2a 20 74 6f 20 72 to long.** to r
14620 65 70 72 65 73 65 6e 74 2e 0a 2a 2f 0a 76 6f 69 epresent..*/.voi
14630 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
14640 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f _blob(sqlite3_co
14650 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f ntext*, const vo
14660 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a id*, int, void(*
14670 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 )(void*));.void
14680 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 sqlite3_result_d
14690 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f ouble(sqlite3_co
146a0 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b ntext*, double);
146b0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
146c0 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 sult_error(sqlit
146d0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e e3_context*, con
146e0 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a st char*, int);.
146f0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
14700 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 ult_error16(sqli
14710 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f te3_context*, co
14720 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b nst void*, int);
14730 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
14740 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 sult_error_toobi
14750 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 g(sqlite3_contex
14760 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 t*);.void sqlite
14770 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 3_result_int(sql
14780 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 ite3_context*, i
14790 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 nt);.void sqlite
147a0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 3_result_int64(s
147b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
147c0 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 29 3b 0a sqlite_int64);.
147d0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
147e0 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 ult_null(sqlite3
147f0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 _context*);.void
14800 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
14810 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e text(sqlite3_con
14820 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 text*, const cha
14830 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 r*, int, void(*)
14840 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 (void*));.void s
14850 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
14860 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e xt16(sqlite3_con
14870 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 text*, const voi
14880 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 d*, int, void(*)
14890 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 (void*));.void s
148a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
148b0 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 xt16le(sqlite3_c
148c0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 ontext*, const v
148d0 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a oid*, int,void(*
148e0 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 )(void*));.void
148f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
14900 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f ext16be(sqlite3_
14910 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
14920 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 void*, int,void(
14930 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 *)(void*));.void
14940 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
14950 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f value(sqlite3_co
14960 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f ntext*, sqlite3_
14970 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 value*);.void sq
14980 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 lite3_result_zer
14990 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f oblob(sqlite3_co
149a0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a ntext*, int n);.
149b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
149c0 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c Define New Coll
149d0 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a ating Sequences.
149e0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 **.** These func
149f0 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 tions are used t
14a00 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 o add new collat
14a10 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f ion sequences to
14a20 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
14a30 2a 5d 20 68 61 6e 64 6c 65 20 73 70 65 63 69 66 *] handle specif
14a40 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 ied as the first
14a50 20 61 72 67 75 6d 65 6e 74 2e 20 0a 2a 2a 0a 2a argument. .**.*
14a60 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 * The name of th
14a70 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 e new collation
14a80 73 65 71 75 65 6e 63 65 20 69 73 20 73 70 65 63 sequence is spec
14a90 69 66 69 65 64 20 61 73 20 61 20 55 54 46 2d 38 ified as a UTF-8
14aa0 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 string.** for s
14ab0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
14ac0 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 llation() and sq
14ad0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
14ae0 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 lation_v2().** a
14af0 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 nd a UTF-16 stri
14b00 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 ng for sqlite3_c
14b10 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 reate_collation1
14b20 36 28 29 2e 20 20 49 6e 20 61 6c 6c 20 63 61 73 6(). In all cas
14b30 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 es.** the name i
14b40 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 s passed as the
14b50 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 second function
14b60 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 argument..**.**
14b70 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 The third argume
14b80 6e 74 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f nt must be one o
14b90 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 f the constants
14ba0 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a [SQLITE_UTF8],.*
14bb0 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c * [SQLITE_UTF16L
14bc0 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 E] or [SQLITE_UT
14bd0 46 31 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 F16BE], indicati
14be0 6e 67 20 74 68 61 74 20 74 68 65 20 75 73 65 72 ng that the user
14bf0 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 -supplied.** rou
14c00 74 69 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20 tine expects to
14c10 62 65 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65 be passed pointe
14c20 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e rs to strings en
14c30 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d coded using UTF-
14c40 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 8,.** UTF-16 lit
14c50 74 6c 65 2d 65 6e 64 69 61 6e 20 6f 72 20 55 54 tle-endian or UT
14c60 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 20 F-16 big-endian
14c70 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a respectively..**
14c80 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f .** A pointer to
14c90 20 74 68 65 20 75 73 65 72 20 73 75 70 70 6c 69 the user suppli
14ca0 65 64 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 ed routine must
14cb0 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 be passed as the
14cc0 20 66 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 fifth.** argume
14cd0 6e 74 2e 20 49 66 20 69 74 20 69 73 20 4e 55 4c nt. If it is NUL
14ce0 4c 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 73 L, this is the s
14cf0 61 6d 65 20 61 73 20 64 65 6c 65 74 69 6e 67 20 ame as deleting
14d00 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a the collation.**
14d10 20 73 65 71 75 65 6e 63 65 20 28 73 6f 20 74 68 sequence (so th
14d20 61 74 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 at SQLite cannot
14d30 20 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 call it anymore
14d40 29 2e 20 45 61 63 68 20 74 69 6d 65 20 74 68 65 ). Each time the
14d50 20 75 73 65 72 0a 2a 2a 20 73 75 70 70 6c 69 65 user.** supplie
14d60 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e d function is in
14d70 76 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 61 73 voked, it is pas
14d80 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 sed a copy of th
14d90 65 20 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61 e void* passed a
14da0 73 0a 2a 2a 20 74 68 65 20 66 6f 75 72 74 68 20 s.** the fourth
14db0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
14dc0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
14dd0 74 69 6f 6e 28 29 20 6f 72 0a 2a 2a 20 73 71 6c tion() or.** sql
14de0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
14df0 61 74 69 6f 6e 31 36 28 29 20 61 73 20 69 74 73 ation16() as its
14e00 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
14e10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d 61 ..**.** The rema
14e20 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 ining arguments
14e30 74 6f 20 74 68 65 20 75 73 65 72 2d 73 75 70 70 to the user-supp
14e40 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 61 72 65 lied routine are
14e50 20 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a two strings,.**
14e60 20 65 61 63 68 20 72 65 70 72 65 73 65 6e 74 65 each represente
14e70 64 20 62 79 20 61 20 5b 6c 65 6e 67 74 68 2c 20 d by a [length,
14e80 64 61 74 61 5d 20 70 61 69 72 20 61 6e 64 20 65 data] pair and e
14e90 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 20 65 6e ncoded in the en
14ea0 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 coding.** that w
14eb0 61 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 as passed as the
14ec0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 third argument
14ed0 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 when the collati
14ee0 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 61 73 0a on sequence was.
14ef0 2a 2a 20 72 65 67 69 73 74 65 72 65 64 2e 20 54 ** registered. T
14f00 68 65 20 75 73 65 72 20 72 6f 75 74 69 6e 65 20 he user routine
14f10 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 6e 65 should return ne
14f20 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 gative, zero or
14f30 70 6f 73 69 74 69 76 65 20 69 66 0a 2a 2a 20 74 positive if.** t
14f40 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 he first string
14f50 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 is less than, eq
14f60 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 ual to, or great
14f70 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f er than the seco
14f80 6e 64 0a 2a 2a 20 73 74 72 69 6e 67 2e 20 69 2e nd.** string. i.
14f90 65 2e 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54 e. (STRING1 - ST
14fa0 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 RING2)..**.** Th
14fb0 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 e sqlite3_create
14fc0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 _collation_v2()
14fd0 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 works like sqlit
14fe0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
14ff0 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 61 70 74 20 ion().** excapt
15000 74 68 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e that it takes an
15010 20 65 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20 extra argument
15020 77 68 69 63 68 20 69 73 20 61 20 64 65 73 74 72 which is a destr
15030 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 uctor for.** the
15040 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65 collation. The
15050 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 destructor is c
15060 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 63 alled when the c
15070 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 ollation is.** d
15080 65 73 74 72 6f 79 65 64 20 61 6e 64 20 69 73 20 estroyed and is
15090 70 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66 passed a copy of
150a0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
150b0 6d 65 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e meter void* poin
150c0 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 ter.** of the sq
150d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
150e0 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 20 20 43 6f lation_v2(). Co
150f0 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 64 65 73 llations are des
15100 74 72 6f 79 65 64 20 77 68 65 6e 0a 2a 2a 20 74 troyed when.** t
15110 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 hey are overridd
15120 65 6e 20 62 79 20 6c 61 74 65 72 20 63 61 6c 6c en by later call
15130 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 s to the collati
15140 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 on creation func
15150 74 69 6f 6e 73 0a 2a 2a 20 6f 72 20 77 68 65 6e tions.** or when
15160 20 74 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20 the [sqlite3*]
15170 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 database handle
15180 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 is closed using
15190 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 [sqlite3_close()
151a0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c ]..**.** The sql
151b0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
151c0 61 74 69 6f 6e 5f 76 32 28 29 20 69 6e 74 65 72 ation_v2() inter
151d0 66 61 63 65 20 69 73 20 65 78 70 65 72 69 6d 65 face is experime
151e0 6e 74 61 6c 20 61 6e 64 0a 2a 2a 20 73 75 62 6a ntal and.** subj
151f0 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e ect to change in
15200 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
15210 2e 20 20 54 68 65 20 6f 74 68 65 72 20 63 6f 6c . The other col
15220 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 0a lation creation.
15230 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 ** functions are
15240 20 73 74 61 62 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 stable..*/.int
15250 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
15260 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 ollation(. sqli
15270 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 te3*, . const c
15280 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 har *zName, . i
15290 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 nt eTextRep, .
152a0 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 void*,. int(*xC
152b0 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e ompare)(void*,in
152c0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e t,const void*,in
152d0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 t,const void*).)
152e0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 ;.int sqlite3_cr
152f0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 eate_collation_v
15300 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 2(. sqlite3*, .
15310 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e const char *zN
15320 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 ame, . int eTex
15330 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a tRep, . void*,.
15340 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 int(*xCompare)
15350 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 (void*,int,const
15360 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 void*,int,const
15370 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 void*),. void(
15380 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a *xDestroy)(void*
15390 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 ).);.int sqlite3
153a0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
153b0 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c n16(. sqlite3*,
153c0 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a . const char *
153d0 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 zName, . int eT
153e0 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a extRep, . void*
153f0 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 ,. int(*xCompar
15400 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e e)(void*,int,con
15410 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e st void*,int,con
15420 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a st void*).);../*
15430 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
15440 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 llation Needed C
15450 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 54 allbacks.**.** T
15460 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 o avoid having t
15470 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 o register all c
15480 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 ollation sequenc
15490 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 es before a data
154a0 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 base.** can be u
154b0 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 sed, a single ca
154c0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
154d0 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 may be registere
154e0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 64 61 d with the.** da
154f0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74 6f tabase handle to
15500 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 be called whene
15510 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 ver an undefined
15520 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 collation seque
15530 6e 63 65 20 69 73 0a 2a 2a 20 72 65 71 75 69 72 nce is.** requir
15540 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 ed..**.** If the
15550 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 function is reg
15560 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 istered using th
15570 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 e sqlite3_collat
15580 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 ion_needed() API
15590 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 ,.** then it is
155a0 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 passed the names
155b0 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f of undefined co
155c0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 llation sequence
155d0 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 s as strings.**
155e0 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 encoded in UTF-8
155f0 2e 20 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c . If sqlite3_col
15600 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 lation_needed16(
15610 29 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 6e ) is used, the n
15620 61 6d 65 73 0a 2a 2a 20 61 72 65 20 70 61 73 73 ames.** are pass
15630 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 ed as UTF-16 in
15640 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 machine native b
15650 79 74 65 20 6f 72 64 65 72 2e 20 41 20 63 61 6c yte order. A cal
15660 6c 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 66 l to either.** f
15670 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 unction replaces
15680 20 61 6e 79 20 65 78 69 73 74 69 6e 67 20 63 61 any existing ca
15690 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 llback..**.** Wh
156a0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 en the callback
156b0 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 is invoked, the
156c0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 first argument p
156d0 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a assed is a copy.
156e0 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 ** of the second
156f0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c argument to sql
15700 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e ite3_collation_n
15710 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 eeded() or.** sq
15720 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
15730 6e 65 65 64 65 64 31 36 28 29 2e 20 54 68 65 20 needed16(). The
15740 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
15750 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a is the database.
15760 2a 2a 20 68 61 6e 64 6c 65 2e 20 54 68 65 20 74 ** handle. The t
15770 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 hird argument is
15780 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f one of [SQLITE_
15790 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 UTF8], [SQLITE_U
157a0 54 46 31 36 42 45 5d 2c 20 6f 72 0a 2a 2a 20 5b TF16BE], or.** [
157b0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c SQLITE_UTF16LE],
157c0 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 indicating the
157d0 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 most desirable f
157e0 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 orm of the colla
157f0 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 tion.** sequence
15800 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 function requir
15810 65 64 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 ed. The fourth p
15820 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 arameter is the
15830 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 name of the.** r
15840 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f equired collatio
15850 6e 20 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a n sequence..**.*
15860 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 * The callback f
15870 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 unction should r
15880 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69 egister the desi
15890 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 red collation us
158a0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
158b0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
158c0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 ()], [sqlite3_cr
158d0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 eate_collation16
158e0 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 ()], or.** [sqli
158f0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
15900 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 tion_v2()]..*/.i
15910 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 nt sqlite3_colla
15920 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 tion_needed(. s
15930 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 qlite3*, . void
15940 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f *, . void(*)(vo
15950 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 id*,sqlite3*,int
15960 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 eTextRep,const
15970 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 char*).);.int sq
15980 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
15990 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 needed16(. sqli
159a0 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a te3*, . void*,.
159b0 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c void(*)(void*,
159c0 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 sqlite3*,int eTe
159d0 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 xtRep,const void
159e0 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 *).);../*.** Spe
159f0 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 cify the key for
15a00 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 an encrypted da
15a10 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f tabase. This ro
15a20 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a utine should be.
15a30 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 ** called right
15a40 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 after sqlite3_op
15a50 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 en()..**.** The
15a60 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e code to implemen
15a70 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f t this API is no
15a80 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 t available in t
15a90 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 he public releas
15aa0 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a e.** of SQLite..
15ab0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b */.int sqlite3_k
15ac0 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 ey(. sqlite3 *d
15ad0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 b,
15ae0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
15af0 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a to be rekeyed *
15b00 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a /. const void *
15b10 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 pKey, int nKey
15b20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f /* The key */
15b30 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 .);../*.** Chang
15b40 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 e the key on an
15b50 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 open database.
15b60 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 If the current d
15b70 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a atabase is not.*
15b80 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 * encrypted, thi
15b90 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 s routine will e
15ba0 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 ncrypt it. If p
15bb0 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d New==0 or nNew==
15bc0 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 0, the.** databa
15bd0 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64 2e se is decrypted.
15be0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 .**.** The code
15bf0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 to implement thi
15c00 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 s API is not ava
15c10 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 ilable in the pu
15c20 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 blic release.**
15c30 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e of SQLite..*/.in
15c40 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 t sqlite3_rekey(
15c50 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
15c60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
15c70 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f /* Database to
15c80 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 be rekeyed */.
15c90 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 const void *pKe
15ca0 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 y, int nKey
15cb0 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a /* The new key *
15cc0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.);../*.** CAPI
15cd0 33 52 45 46 3a 20 20 53 75 73 70 65 6e 64 20 45 3REF: Suspend E
15ce0 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 xecution For A S
15cf0 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 hort Time.**.**
15d00 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 This function ca
15d10 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 uses the current
15d20 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 thread to suspe
15d30 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 nd execution.**
15d40 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c a number of mill
15d50 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 iseconds specifi
15d60 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 ed in its parame
15d70 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ter..**.** If th
15d80 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 e operating syst
15d90 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 em does not supp
15da0 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 ort sleep reques
15db0 74 73 20 77 69 74 68 20 0a 2a 2a 20 6d 69 6c 6c ts with .** mill
15dc0 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 isecond time res
15dd0 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 olution, then th
15de0 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 e time will be r
15df0 6f 75 6e 64 65 64 20 75 70 20 74 6f 20 0a 2a 2a ounded up to .**
15e00 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 the nearest sec
15e10 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 ond. The number
15e20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 of milliseconds
15e30 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c of sleep actuall
15e40 79 20 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 y .** requested
15e50 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 from the operati
15e60 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 ng system is ret
15e70 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 urned..*/.int sq
15e80 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 lite3_sleep(int)
15e90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
15ea0 46 3a 20 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 F: Name Of The
15eb0 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 Folder Holding T
15ec0 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a emporary Files.*
15ed0 2a 0a 2a 2a 20 49 66 20 74 68 69 73 20 67 6c 6f *.** If this glo
15ee0 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 bal variable is
15ef0 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f made to point to
15f00 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 a string which
15f10 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f is.** the name o
15f20 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 61 f a folder (a.ka
15f30 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 . directory), th
15f40 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 en all temporary
15f50 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 files.** create
15f60 64 20 62 79 20 53 51 4c 69 74 65 20 77 69 6c 6c d by SQLite will
15f70 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 be placed in th
15f80 61 74 20 64 69 72 65 63 74 6f 72 79 2e 20 20 49 at directory. I
15f90 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a f this variable.
15fa0 2a 2a 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 ** is NULL point
15fb0 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 er, then SQLite
15fc0 64 6f 65 73 20 61 20 73 65 61 72 63 68 20 66 6f does a search fo
15fd0 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 r an appropriate
15fe0 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 66 69 temporary.** fi
15ff0 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a le directory..**
16000 0a 2a 2a 20 4f 6e 63 65 20 5b 73 71 6c 69 74 65 .** Once [sqlite
16010 33 5f 6f 70 65 6e 28 29 5d 20 68 61 73 20 62 65 3_open()] has be
16020 65 6e 20 63 61 6c 6c 65 64 2c 20 63 68 61 6e 67 en called, chang
16030 69 6e 67 20 74 68 69 73 20 76 61 72 69 61 62 6c ing this variabl
16040 65 20 77 69 6c 6c 0a 2a 2a 20 69 6e 76 61 6c 69 e will.** invali
16050 64 61 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 date the current
16060 20 74 65 6d 70 6f 72 61 72 79 20 64 61 74 61 62 temporary datab
16070 61 73 65 2c 20 69 66 20 61 6e 79 2e 20 20 47 65 ase, if any. Ge
16080 6e 65 72 61 6c 6c 79 20 73 70 65 61 6b 69 6e 67 nerally speaking
16090 2c 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 73 ,.** it is not s
160a0 61 66 65 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 afe to invoke th
160b0 69 73 20 72 6f 75 74 69 6e 65 20 61 66 74 65 72 is routine after
160c0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
160d0 5d 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 63 61 ] has.** been ca
160e0 6c 6c 65 64 2e 0a 2a 2f 0a 65 78 74 65 72 6e 20 lled..*/.extern
160f0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 char *sqlite3_te
16100 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f mp_directory;../
16110 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 *.** CAPI3REF:
16120 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 Test To See If T
16130 68 65 20 44 61 74 61 62 73 65 20 49 73 20 49 6e he Databse Is In
16140 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 Auto-Commit Mod
16150 65 0a 2a 2a 0a 2a 2a 20 54 65 73 74 20 74 6f 20 e.**.** Test to
16160 73 65 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e see whether or n
16170 6f 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ot the database
16180 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e connection is in
16190 20 61 75 74 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 6d autocommit.** m
161a0 6f 64 65 2e 20 20 52 65 74 75 72 6e 20 54 52 55 ode. Return TRU
161b0 45 20 69 66 20 69 74 20 69 73 20 61 6e 64 20 46 E if it is and F
161c0 41 4c 53 45 20 69 66 20 6e 6f 74 2e 20 20 41 75 ALSE if not. Au
161d0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 tocommit mode is
161e0 20 6f 6e 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c on.** by defaul
161f0 74 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 69 t. Autocommit i
16200 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 s disabled by a
16210 42 45 47 49 4e 20 73 74 61 74 65 6d 65 6e 74 20 BEGIN statement
16220 61 6e 64 20 72 65 65 6e 61 62 6c 65 64 0a 2a 2a and reenabled.**
16230 20 62 79 20 74 68 65 20 6e 65 78 74 20 43 4f 4d by the next COM
16240 4d 49 54 20 6f 72 20 52 4f 4c 4c 42 41 43 4b 2e MIT or ROLLBACK.
16250 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
16260 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 get_autocommit(s
16270 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
16280 20 43 41 50 49 33 52 45 46 3a 20 20 46 69 6e 64 CAPI3REF: Find
16290 20 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61 The Database Ha
162a0 6e 64 6c 65 20 41 73 73 6f 63 69 61 74 65 64 20 ndle Associated
162b0 57 69 74 68 20 41 20 50 72 65 70 61 72 65 64 20 With A Prepared
162c0 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 Statement.**.**
162d0 52 65 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 Return the [sqli
162e0 74 65 33 2a 5d 20 64 61 74 61 62 61 73 65 20 68 te3*] database h
162f0 61 6e 64 6c 65 20 74 6f 20 77 68 69 63 68 20 61 andle to which a
16300 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d .** [sqlite3_stm
16310 74 20 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 t | prepared sta
16320 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e tement] belongs.
16330 0a 2a 2a 20 54 68 69 73 20 69 73 20 74 68 65 20 .** This is the
16340 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 68 61 same database ha
16350 6e 64 6c 65 20 74 68 61 74 20 77 61 73 0a 2a 2a ndle that was.**
16360 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
16370 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 ent to the [sqli
16380 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
16390 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 ] or its variant
163a0 73 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 75 73 s.** that was us
163b0 65 64 20 74 6f 20 63 72 65 61 74 65 20 74 68 65 ed to create the
163c0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 statement in th
163d0 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a e first place..*
163e0 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 /.sqlite3 *sqlit
163f0 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c e3_db_handle(sql
16400 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 0a 2f ite3_stmt*);.../
16410 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
16420 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 ommit And Rollba
16430 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 ck Notification
16440 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 Callbacks.**.**
16450 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a These routines.*
16460 2a 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 * register callb
16470 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f ack functions to
16480 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e be invoked when
16490 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 ever a transacti
164a0 6f 6e 0a 2a 2a 20 69 73 20 63 6f 6d 6d 69 74 74 on.** is committ
164b0 65 64 20 6f 72 20 72 6f 6c 6c 65 64 20 62 61 63 ed or rolled bac
164c0 6b 2e 20 20 54 68 65 20 70 41 72 67 20 61 72 67 k. The pArg arg
164d0 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 ument is passed
164e0 74 68 72 6f 75 67 68 0a 2a 2a 20 74 6f 20 74 68 through.** to th
164f0 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66 20 e callback. If
16500 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 the callback on
16510 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 a commit hook fu
16520 6e 63 74 69 6f 6e 20 0a 2a 2a 20 72 65 74 75 72 nction .** retur
16530 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 ns non-zero, the
16540 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 n the commit is
16550 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 converted into a
16560 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a rollback..**.**
16570 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 If another func
16580 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 tion was previou
16590 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 sly registered,
165a0 69 74 73 20 70 41 72 67 20 76 61 6c 75 65 20 69 its pArg value i
165b0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f s returned..** O
165c0 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 therwise NULL is
165d0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
165e0 20 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e Registering a N
165f0 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 ULL function dis
16600 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61 ables the callba
16610 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 ck..**.** For th
16620 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 e purposes of th
16630 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 is API, a transa
16640 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f ction is said to
16650 20 68 61 76 65 20 62 65 65 6e 20 0a 2a 2a 20 72 have been .** r
16660 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e olled back if an
16670 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 explicit "ROLLB
16680 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69 ACK" statement i
16690 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a s executed, or.*
166a0 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f * an error or co
166b0 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65 73 20 nstraint causes
166c0 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c an implicit roll
166d0 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 20 54 back to occur. T
166e0 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 he .** callback
166f0 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 is not invoked i
16700 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 f a transaction
16710 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 is automatically
16720 20 72 6f 6c 6c 65 64 0a 2a 2a 20 62 61 63 6b 20 rolled.** back
16730 62 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61 because the data
16740 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
16750 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a is closed..**.**
16760 20 54 68 65 73 65 20 61 72 65 20 65 78 70 65 72 These are exper
16770 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 imental interfac
16780 65 73 20 61 6e 64 20 61 72 65 20 73 75 62 6a 65 es and are subje
16790 63 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f ct to change..*/
167a0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 .void *sqlite3_c
167b0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 ommit_hook(sqlit
167c0 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 e3*, int(*)(void
167d0 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 *), void*);.void
167e0 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 *sqlite3_rollba
167f0 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a ck_hook(sqlite3*
16800 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a , void(*)(void *
16810 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a ), void*);../*.*
16820 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 * CAPI3REF: Data
16830 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 Change Notifica
16840 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a tion Callbacks.*
16850 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 20 61 20 *.** Register a
16860 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
16870 6e 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62 n with the datab
16880 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ase connection i
16890 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 dentified by the
168a0 20 0a 2a 2a 20 66 69 72 73 74 20 61 72 67 75 6d .** first argum
168b0 65 6e 74 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 ent to be invoke
168c0 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 d whenever a row
168d0 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 is updated, ins
168e0 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 erted or deleted
168f0 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 ..** Any callbac
16900 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 k set by a previ
16910 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 ous call to this
16920 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 74 68 function for th
16930 65 20 73 61 6d 65 20 0a 2a 2a 20 64 61 74 61 62 e same .** datab
16940 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ase connection i
16950 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a s overridden..**
16960 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 .** The second a
16970 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 rgument is a poi
16980 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 nter to the func
16990 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 tion to invoke w
169a0 68 65 6e 20 61 20 0a 2a 2a 20 72 6f 77 20 69 73 hen a .** row is
169b0 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 updated, insert
169c0 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 20 54 ed or deleted. T
169d0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
169e0 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 t to the callbac
169f0 6b 20 69 73 0a 2a 2a 20 61 20 63 6f 70 79 20 6f k is.** a copy o
16a00 66 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 f the third argu
16a10 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f ment to sqlite3_
16a20 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 20 54 update_hook(). T
16a30 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 he second callba
16a40 63 6b 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 ck .** argument
16a50 69 73 20 6f 6e 65 20 6f 66 20 53 51 4c 49 54 45 is one of SQLITE
16a60 5f 49 4e 53 45 52 54 2c 20 53 51 4c 49 54 45 5f _INSERT, SQLITE_
16a70 44 45 4c 45 54 45 20 6f 72 20 53 51 4c 49 54 45 DELETE or SQLITE
16a80 5f 55 50 44 41 54 45 2c 20 64 65 70 65 6e 64 69 _UPDATE, dependi
16a90 6e 67 0a 2a 2a 20 6f 6e 20 74 68 65 20 6f 70 65 ng.** on the ope
16aa0 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 ration that caus
16ab0 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 ed the callback
16ac0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 20 54 to be invoked. T
16ad0 68 65 20 74 68 69 72 64 20 61 6e 64 20 0a 2a 2a he third and .**
16ae0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 fourth argument
16af0 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 s to the callbac
16b00 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 k contain pointe
16b10 72 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 rs to the databa
16b20 73 65 20 61 6e 64 20 0a 2a 2a 20 74 61 62 6c 65 se and .** table
16b30 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 name containing
16b40 20 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f the affected ro
16b50 77 2e 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c w. The final cal
16b60 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 lback parameter
16b70 69 73 20 0a 2a 2a 20 74 68 65 20 72 6f 77 69 64 is .** the rowid
16b80 20 6f 66 20 74 68 65 20 72 6f 77 2e 20 49 6e 20 of the row. In
16b90 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75 the case of an u
16ba0 70 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 74 pdate, this is t
16bb0 68 65 20 72 6f 77 69 64 20 61 66 74 65 72 20 0a he rowid after .
16bc0 2a 2a 20 74 68 65 20 75 70 64 61 74 65 20 74 61 ** the update ta
16bd0 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a kes place..**.**
16be0 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b The update hook
16bf0 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 is not invoked
16c00 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 when internal sy
16c10 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a stem tables are.
16c20 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 ** modified (i.e
16c30 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 . sqlite_master
16c40 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 and sqlite_seque
16c50 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 nce)..**.** If a
16c60 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 nother function
16c70 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 was previously r
16c80 65 67 69 73 74 65 72 65 64 2c 20 69 74 73 20 70 egistered, its p
16c90 41 72 67 20 76 61 6c 75 65 20 69 73 20 72 65 74 Arg value is ret
16ca0 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 urned..** Otherw
16cb0 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 ise NULL is retu
16cc0 72 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 rned..*/.void *s
16cd0 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f qlite3_update_ho
16ce0 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 ok(. sqlite3*,
16cf0 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 . void(*)(void
16d00 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 *,int ,char cons
16d10 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a t *,char const *
16d20 2c 73 71 6c 69 74 65 5f 69 6e 74 36 34 29 2c 0a ,sqlite_int64),.
16d30 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a void*.);../*.*
16d40 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 6e 61 * CAPI3REF: Ena
16d50 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 ble Or Disable S
16d60 68 61 72 65 64 20 50 61 67 65 72 20 43 61 63 68 hared Pager Cach
16d70 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 e.**.** This rou
16d80 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 tine enables or
16d90 64 69 73 61 62 6c 65 73 20 74 68 65 20 73 68 61 disables the sha
16da0 72 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 ring of the data
16db0 62 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e base cache.** an
16dc0 64 20 73 63 68 65 6d 61 20 64 61 74 61 20 73 74 d schema data st
16dd0 72 75 63 74 75 72 65 73 20 62 65 74 77 65 65 6e ructures between
16de0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 74 6f 20 connections to
16df0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
16e00 65 2e 0a 2a 2a 20 53 68 61 72 69 6e 67 20 69 73 e..** Sharing is
16e10 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 enabled if the
16e20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 argument is true
16e30 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66 and disabled if
16e40 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a the argument.**
16e50 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a is false..**.**
16e60 20 43 61 63 68 65 20 73 68 61 72 69 6e 67 20 69 Cache sharing i
16e70 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 s enabled and di
16e80 73 61 62 6c 65 64 20 6f 6e 20 61 20 74 68 72 65 sabled on a thre
16e90 61 64 2d 62 79 2d 74 68 72 65 61 64 20 62 61 73 ad-by-thread bas
16ea0 69 73 2e 0a 2a 2a 20 45 61 63 68 20 63 61 6c 6c is..** Each call
16eb0 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 to this routine
16ec0 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 enables or disa
16ed0 62 6c 65 73 20 63 61 63 68 65 20 73 68 61 72 69 bles cache shari
16ee0 6e 67 20 6f 6e 6c 79 20 66 6f 72 0a 2a 2a 20 63 ng only for.** c
16ef0 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 72 65 61 74 onnections creat
16f00 65 64 20 69 6e 20 74 68 65 20 73 61 6d 65 20 74 ed in the same t
16f10 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 74 hread in which t
16f20 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63 his routine is c
16f30 61 6c 6c 65 64 2e 0a 2a 2a 20 54 68 65 72 65 20 alled..** There
16f40 69 73 20 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20 is no mechanism
16f50 66 6f 72 20 73 68 61 72 69 6e 67 20 63 61 63 68 for sharing cach
16f60 65 20 62 65 74 77 65 65 6e 20 64 61 74 61 62 61 e between databa
16f70 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a se connections.*
16f80 2a 20 72 75 6e 6e 69 6e 67 20 69 6e 20 64 69 66 * running in dif
16f90 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 2e 0a ferent threads..
16fa0 2a 2a 0a 2a 2a 20 53 68 61 72 69 6e 67 20 6d 75 **.** Sharing mu
16fb0 73 74 20 62 65 20 64 69 73 61 62 6c 65 64 20 70 st be disabled p
16fc0 72 69 6f 72 20 74 6f 20 73 68 75 74 74 69 6e 67 rior to shutting
16fd0 20 64 6f 77 6e 20 61 20 74 68 72 65 61 64 20 6f down a thread o
16fe0 72 20 65 6c 73 65 0a 2a 2a 20 74 68 65 20 74 68 r else.** the th
16ff0 72 65 61 64 20 77 69 6c 6c 20 6c 65 61 6b 20 6d read will leak m
17000 65 6d 6f 72 79 2e 20 20 43 61 6c 6c 20 74 68 69 emory. Call thi
17010 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 s routine with a
17020 6e 20 61 72 67 75 6d 65 6e 74 20 6f 66 0a 2a 2a n argument of.**
17030 20 30 20 74 6f 20 74 75 72 6e 20 6f 66 66 20 73 0 to turn off s
17040 68 61 72 69 6e 67 2e 20 20 4f 72 20 75 73 65 20 haring. Or use
17050 74 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 the sqlite3_thre
17060 61 64 5f 63 6c 65 61 6e 75 70 28 29 20 41 50 49 ad_cleanup() API
17070 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 ..**.** This rou
17080 74 69 6e 65 20 6d 75 73 74 20 6e 6f 74 20 62 65 tine must not be
17090 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 61 6e 79 called when any
170a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
170b0 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 63 74 tions.** are act
170c0 69 76 65 20 69 6e 20 74 68 65 20 63 75 72 72 65 ive in the curre
170d0 6e 74 20 74 68 72 65 61 64 2e 20 20 45 6e 61 62 nt thread. Enab
170e0 6c 69 6e 67 20 6f 72 20 64 69 73 61 62 6c 69 6e ling or disablin
170f0 67 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 g shared.** cach
17100 65 20 77 68 69 6c 65 20 74 68 65 72 65 20 61 72 e while there ar
17110 65 20 61 63 74 69 76 65 20 64 61 74 61 62 61 73 e active databas
17120 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 77 69 e connections wi
17130 6c 6c 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 ll result.** in
17140 6d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f memory corruptio
17150 6e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 n..**.** When th
17160 65 20 73 68 61 72 65 64 20 63 61 63 68 65 20 69 e shared cache i
17170 73 20 65 6e 61 62 6c 65 64 2c 20 74 68 65 0a 2a s enabled, the.*
17180 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 72 6f 75 74 * following rout
17190 69 6e 65 73 20 6d 75 73 74 20 61 6c 77 61 79 73 ines must always
171a0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 be called from
171b0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 3a the same thread:
171c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 .** [sqlite3_ope
171d0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 n()], [sqlite3_p
171e0 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 repare_v2()], [s
171f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 0a qlite3_step()],.
17200 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ** [sqlite3_rese
17210 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 t()], [sqlite3_f
17220 69 6e 61 6c 69 7a 65 28 29 5d 2c 20 61 6e 64 20 inalize()], and
17230 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 [sqlite3_close()
17240 5d 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 75 ]..** This is du
17250 65 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 e to the fact th
17260 61 74 20 74 68 65 20 73 68 61 72 65 64 20 63 61 at the shared ca
17270 63 68 65 20 6d 61 6b 65 73 20 75 73 65 20 6f 66 che makes use of
17280 0a 2a 2a 20 74 68 72 65 61 64 2d 73 70 65 63 69 .** thread-speci
17290 66 69 63 20 73 74 6f 72 61 67 65 20 73 6f 20 74 fic storage so t
172a0 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 61 hat it will be a
172b0 76 61 69 6c 61 62 6c 65 20 66 6f 72 20 73 68 61 vailable for sha
172c0 72 69 6e 67 0a 2a 2a 20 77 69 74 68 20 6f 74 68 ring.** with oth
172d0 65 72 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a er connections..
172e0 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 **.** Virtual ta
172f0 62 6c 65 73 20 63 61 6e 6e 6f 74 20 62 65 20 75 bles cannot be u
17300 73 65 64 20 77 69 74 68 20 61 20 73 68 61 72 65 sed with a share
17310 64 20 63 61 63 68 65 2e 20 20 57 68 65 6e 20 73 d cache. When s
17320 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 hared.** cache i
17330 73 20 65 6e 61 62 6c 65 64 2c 20 74 68 65 20 73 s enabled, the s
17340 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f qlite3_create_mo
17350 64 75 6c 65 28 29 20 41 50 49 20 75 73 65 64 20 dule() API used
17360 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 76 to register.** v
17370 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 77 69 irtual tables wi
17380 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e ll always return
17390 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a an error..**.**
173a0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 This routine re
173b0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b turns [SQLITE_OK
173c0 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68 ] if shared cach
173d0 65 20 77 61 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 e was.** enabled
173e0 20 6f 72 20 64 69 73 61 62 6c 65 64 20 73 75 63 or disabled suc
173f0 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b cessfully. An [
17400 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 65 SQLITE_ERROR | e
17410 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 69 73 rror code].** is
17420 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 returned otherw
17430 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65 ise..**.** Share
17440 64 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62 d cache is disab
17450 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 led by default f
17460 6f 72 20 62 61 63 6b 77 61 72 64 20 63 6f 6d 70 or backward comp
17470 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e atibility..*/.in
17480 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 t sqlite3_enable
17490 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 69 6e _shared_cache(in
174a0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
174b0 52 45 46 3a 20 20 41 74 74 65 6d 70 74 20 54 6f REF: Attempt To
174c0 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72 Free Heap Memor
174d0 79 0a 2a 2a 0a 2a 2a 20 41 74 74 65 6d 70 74 20 y.**.** Attempt
174e0 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73 20 to free N bytes
174f0 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 of heap memory b
17500 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e y deallocating n
17510 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 0a 2a 2a 20 on-essential.**
17520 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
17530 6e 73 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 ns held by the d
17540 61 74 61 62 61 73 65 20 6c 69 62 72 61 72 79 20 atabase library
17550 28 65 78 61 6d 70 6c 65 3a 20 6d 65 6d 6f 72 79 (example: memory
17560 20 0a 2a 2a 20 75 73 65 64 20 74 6f 20 63 61 63 .** used to cac
17570 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 he database page
17580 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 s to improve per
17590 66 6f 72 6d 61 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a formance)..**.**
175a0 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 This function i
175b0 73 20 6e 6f 74 20 61 20 70 61 72 74 20 6f 66 20 s not a part of
175c0 73 74 61 6e 64 61 72 64 20 62 75 69 6c 64 73 2e standard builds.
175d0 20 20 49 74 20 69 73 20 6f 6e 6c 79 20 63 72 65 It is only cre
175e0 61 74 65 64 0a 2a 2a 20 69 66 20 53 51 4c 69 74 ated.** if SQLit
175f0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
17600 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 45 4e th the SQLITE_EN
17610 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 ABLE_MEMORY_MANA
17620 47 45 4d 45 4e 54 20 6d 61 63 72 6f 2e 0a 2a 2f GEMENT macro..*/
17630 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c .int sqlite3_rel
17640 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 ease_memory(int)
17650 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
17660 46 3a 20 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d F: Impose A Lim
17670 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 0a it On Heap Size.
17680 2a 2a 0a 2a 2a 20 50 6c 61 63 65 20 61 20 22 73 **.** Place a "s
17690 6f 66 74 22 20 6c 69 6d 69 74 20 6f 6e 20 74 68 oft" limit on th
176a0 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 e amount of heap
176b0 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 memory that may
176c0 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 be allocated by
176d0 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 74 68 69 .** SQLite withi
176e0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 n the current th
176f0 72 65 61 64 2e 20 49 66 20 61 6e 20 69 6e 74 65 read. If an inte
17700 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 rnal allocation
17710 69 73 20 72 65 71 75 65 73 74 65 64 20 0a 2a 2a is requested .**
17720 20 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65 that would exce
17730 65 64 20 74 68 65 20 73 70 65 63 69 66 69 65 64 ed the specified
17740 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74 65 33 limit, [sqlite3
17750 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 _release_memory(
17760 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a )] is invoked.**
17770 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d one or more tim
17780 65 73 20 74 6f 20 66 72 65 65 20 75 70 20 73 6f es to free up so
17790 6d 65 20 73 70 61 63 65 20 62 65 66 6f 72 65 20 me space before
177a0 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 the allocation i
177b0 73 20 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 s made..**.** Th
177c0 65 20 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 e limit is calle
177d0 64 20 22 73 6f 66 74 22 2c 20 62 65 63 61 75 73 d "soft", becaus
177e0 65 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 72 65 e if [sqlite3_re
177f0 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 lease_memory()]
17800 63 61 6e 6e 6f 74 20 66 72 65 65 0a 2a 2a 20 73 cannot free.** s
17810 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 ufficient memory
17820 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 65 20 to prevent the
17830 6c 69 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 limit from being
17840 20 65 78 63 65 65 64 65 64 2c 20 74 68 65 20 6d exceeded, the m
17850 65 6d 6f 72 79 20 69 73 0a 2a 2a 20 61 6c 6c 6f emory is.** allo
17860 63 61 74 65 64 20 61 6e 79 77 61 79 20 61 6e 64 cated anyway and
17870 20 74 68 65 20 63 75 72 72 65 6e 74 20 6f 70 65 the current ope
17880 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e ration proceeds.
17890 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 .**.** Prior to
178a0 73 68 75 74 74 69 6e 67 20 64 6f 77 6e 20 61 20 shutting down a
178b0 74 68 72 65 61 64 20 73 71 6c 69 74 65 33 5f 73 thread sqlite3_s
178c0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 oft_heap_limit()
178d0 20 6d 75 73 74 20 62 65 20 73 65 74 20 74 6f 20 must be set to
178e0 0a 2a 2a 20 7a 65 72 6f 20 28 74 68 65 20 64 65 .** zero (the de
178f0 66 61 75 6c 74 29 20 6f 72 20 65 6c 73 65 20 74 fault) or else t
17900 68 65 20 74 68 72 65 61 64 20 77 69 6c 6c 20 6c he thread will l
17910 65 61 6b 20 6d 65 6d 6f 72 79 2e 20 41 6c 74 65 eak memory. Alte
17920 72 6e 61 74 69 76 65 6c 79 2c 20 75 73 65 0a 2a rnatively, use.*
17930 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 * the [sqlite3_t
17940 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 29 5d hread_cleanup()]
17950 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e 65 API..**.** A ne
17960 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f 20 76 gative or zero v
17970 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65 61 6e 73 alue for N means
17980 20 74 68 61 74 20 74 68 65 72 65 20 69 73 20 6e that there is n
17990 6f 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 o soft heap limi
179a0 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 t and.** [sqlite
179b0 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 3_release_memory
179c0 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 ()] will only be
179d0 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d called when mem
179e0 6f 72 79 20 69 73 20 65 78 68 61 75 73 65 64 2e ory is exhaused.
179f0 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 .** The default
17a00 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 73 6f value for the so
17a10 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 ft heap limit is
17a20 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c zero..**.** SQL
17a30 69 74 65 20 6d 61 6b 65 73 20 61 20 62 65 73 74 ite makes a best
17a40 20 65 66 66 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 effort to honor
17a50 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c the soft heap l
17a60 69 6d 69 74 2e 20 20 42 75 74 20 69 66 20 69 74 imit. But if it
17a70 0a 2a 2a 20 69 73 20 75 6e 61 62 6c 65 20 74 6f .** is unable to
17a80 20 72 65 64 75 63 65 20 6d 65 6d 6f 72 79 20 75 reduce memory u
17a90 73 61 67 65 20 62 65 6c 6f 77 20 74 68 65 20 73 sage below the s
17aa0 6f 66 74 20 6c 69 6d 69 74 2c 20 65 78 65 63 75 oft limit, execu
17ab0 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e tion will.** con
17ac0 74 69 6e 75 65 20 77 69 74 68 6f 75 74 20 65 72 tinue without er
17ad0 72 6f 72 20 6f 72 20 6e 6f 74 69 66 69 63 61 74 ror or notificat
17ae0 69 6f 6e 2e 20 20 54 68 69 73 20 69 73 20 77 68 ion. This is wh
17af0 79 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 0a y the limit is .
17b00 2a 2a 20 63 61 6c 6c 65 64 20 61 20 22 73 6f 66 ** called a "sof
17b10 74 22 20 6c 69 6d 69 74 2e 20 20 49 74 20 69 73 t" limit. It is
17b20 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a advisory only..
17b30 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 **.** This funct
17b40 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 ion is only avai
17b50 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 lable if the lib
17b60 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 rary was compile
17b70 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 d with the .** S
17b80 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d QLITE_ENABLE_MEM
17b90 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 20 6f ORY_MANAGEMENT o
17ba0 70 74 69 6f 6e 20 73 65 74 2e 0a 2a 2a 20 6d 65 ption set..** me
17bb0 6d 6f 72 79 2d 6d 61 6e 61 67 65 6d 65 6e 74 20 mory-management
17bc0 68 61 73 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 has been enabled
17bd0 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 ..*/.void sqlite
17be0 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 3_soft_heap_limi
17bf0 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 t(int);../*.** C
17c00 41 50 49 33 52 45 46 3a 20 20 43 6c 65 61 6e 20 API3REF: Clean
17c10 55 70 20 54 68 72 65 61 64 20 4c 6f 63 61 6c 20 Up Thread Local
17c20 53 74 6f 72 61 67 65 0a 2a 2a 0a 2a 2a 20 54 68 Storage.**.** Th
17c30 69 73 20 72 6f 75 74 69 6e 65 20 6d 61 6b 65 73 is routine makes
17c40 20 73 75 72 65 20 74 68 61 74 20 61 6c 6c 20 74 sure that all t
17c50 68 72 65 61 64 2d 6c 6f 63 61 6c 20 73 74 6f 72 hread-local stor
17c60 61 67 65 20 68 61 73 20 62 65 65 6e 0a 2a 2a 20 age has been.**
17c70 64 65 61 6c 6c 6f 63 61 74 65 64 20 66 6f 72 20 deallocated for
17c80 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 the current thre
17c90 61 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 ad..**.** This r
17ca0 6f 75 74 69 6e 65 20 69 73 20 6e 6f 74 20 74 65 outine is not te
17cb0 63 68 6e 69 63 61 6c 6c 79 20 6e 65 63 65 73 73 chnically necess
17cc0 61 72 79 2e 20 20 41 6c 6c 20 74 68 72 65 61 64 ary. All thread
17cd0 2d 6c 6f 63 61 6c 20 73 74 6f 72 61 67 65 0a 2a -local storage.*
17ce0 2a 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 * will be automa
17cf0 74 69 63 61 6c 6c 79 20 64 65 61 6c 6c 6f 63 61 tically dealloca
17d00 74 65 64 20 6f 6e 63 65 20 6d 65 6d 6f 72 79 2d ted once memory-
17d10 6d 61 6e 61 67 65 6d 65 6e 74 20 61 6e 64 0a 2a management and.*
17d20 2a 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 61 * shared-cache a
17d30 72 65 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 re disabled and
17d40 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 the soft heap li
17d50 6d 69 74 20 68 61 73 20 62 65 65 6e 20 73 65 74 mit has been set
17d60 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2e 20 20 54 68 .** to zero. Th
17d70 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 70 72 is routine is pr
17d80 6f 76 69 64 65 64 20 61 73 20 61 20 63 6f 6e 76 ovided as a conv
17d90 65 6e 69 65 6e 63 65 20 66 6f 72 20 75 73 65 72 enience for user
17da0 73 20 77 68 6f 0a 2a 2a 20 77 61 6e 74 20 74 6f s who.** want to
17db0 20 6d 61 6b 65 20 61 62 73 6f 6c 75 74 65 6c 79 make absolutely
17dc0 20 73 75 72 65 20 74 68 65 79 20 68 61 76 65 20 sure they have
17dd0 6e 6f 74 20 66 6f 72 67 6f 74 74 65 6e 20 73 6f not forgotten so
17de0 6d 65 74 68 69 6e 67 0a 2a 2a 20 70 72 69 6f 72 mething.** prior
17df0 20 74 6f 20 6b 69 6c 6c 69 6e 67 20 6f 66 66 20 to killing off
17e00 61 20 74 68 72 65 61 64 2e 0a 2a 2f 0a 76 6f 69 a thread..*/.voi
17e10 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 d sqlite3_thread
17e20 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a _cleanup(void);.
17e30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
17e40 20 20 45 78 74 72 61 63 74 20 4d 65 74 61 64 61 Extract Metada
17e50 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d ta About A Colum
17e60 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a 2a 0a n Of A Table.**.
17e70 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 0a ** This routine.
17e80 2a 2a 20 72 65 74 75 72 6e 73 20 6d 65 74 61 2d ** returns meta-
17e90 64 61 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 data about a spe
17ea0 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 cific column of
17eb0 61 20 73 70 65 63 69 66 69 63 20 64 61 74 61 62 a specific datab
17ec0 61 73 65 0a 2a 2a 20 74 61 62 6c 65 20 61 63 63 ase.** table acc
17ed0 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 essible using th
17ee0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e e connection han
17ef0 64 6c 65 20 70 61 73 73 65 64 20 61 73 20 74 68 dle passed as th
17f00 65 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e e first function
17f10 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 0a 2a .** argument..*
17f20 2a 0a 2a 2a 20 54 68 65 20 63 6f 6c 75 6d 6e 20 *.** The column
17f30 69 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 is identified by
17f40 20 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 the second, thi
17f50 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 rd and fourth pa
17f60 72 61 6d 65 74 65 72 73 20 74 6f 20 0a 2a 2a 20 rameters to .**
17f70 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54 this function. T
17f80 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
17f90 74 65 72 20 69 73 20 65 69 74 68 65 72 20 74 68 ter is either th
17fa0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 e name of the da
17fb0 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 tabase.** (i.e.
17fc0 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 20 6f "main", "temp" o
17fd0 72 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 r an attached da
17fe0 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 tabase) containi
17ff0 6e 67 20 74 68 65 20 73 70 65 63 69 66 69 65 64 ng the specified
18000 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c .** table or NUL
18010 4c 2e 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c L. If it is NULL
18020 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 , then all attac
18030 68 65 64 20 64 61 74 61 62 61 73 65 73 20 61 72 hed databases ar
18040 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f e searched.** fo
18050 72 20 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e r the table usin
18060 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 g the same algor
18070 69 74 68 6d 20 61 73 20 74 68 65 20 64 61 74 61 ithm as the data
18080 62 61 73 65 20 65 6e 67 69 6e 65 20 75 73 65 73 base engine uses
18090 20 74 6f 20 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 to .** resolve
180a0 75 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c unqualified tabl
180b0 65 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a e references..**
180c0 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e .** The third an
180d0 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 d fourth paramet
180e0 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 ers to this func
180f0 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62 tion are the tab
18100 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 0a 2a le and column .*
18110 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 * name of the de
18120 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 sired column, re
18130 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 spectively. Neit
18140 68 65 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 her of these par
18150 61 6d 65 74 65 72 73 20 0a 2a 2a 20 6d 61 79 20 ameters .** may
18160 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d be NULL..**.** M
18170 65 74 61 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 eta information
18180 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 77 is returned by w
18190 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 riting to the me
181a0 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 mory locations p
181b0 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 assed as.** the
181c0 35 74 68 20 61 6e 64 20 73 75 62 73 65 71 75 65 5th and subseque
181d0 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f nt parameters to
181e0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 this function.
181f0 41 6e 79 20 6f 66 20 74 68 65 73 65 20 0a 2a 2a Any of these .**
18200 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 arguments may b
18210 65 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 e NULL, in which
18220 20 63 61 73 65 20 74 68 65 20 63 6f 72 72 65 73 case the corres
18230 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 ponding element
18240 6f 66 20 6d 65 74 61 20 0a 2a 2a 20 69 6e 66 6f of meta .** info
18250 72 6d 61 74 69 6f 6e 20 69 73 20 6f 6d 6d 69 74 rmation is ommit
18260 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e ted..**.** <pre>
18270 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 20 20 20 .** Parameter
18280 20 20 4f 75 74 70 75 74 20 54 79 70 65 20 20 20 Output Type
18290 20 20 20 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a Description.*
182a0 2a 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d * --------------
182b0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
182c0 2d 2d 2d 2d 2d 0a 2a 2a 0a 2a 2a 20 20 20 35 74 -----.**.** 5t
182d0 68 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74 20 h const
182e0 63 68 61 72 2a 20 20 20 20 20 20 44 61 74 61 20 char* Data
182f0 74 79 70 65 0a 2a 2a 20 20 20 36 74 68 20 20 20 type.** 6th
18300 20 20 20 20 20 20 63 6f 6e 73 74 20 63 68 61 72 const char
18310 2a 20 20 20 20 20 20 4e 61 6d 65 20 6f 66 20 74 * Name of t
18320 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 he default colla
18330 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 0a 2a tion sequence .*
18340 2a 20 20 20 37 74 68 20 20 20 20 20 20 20 20 20 * 7th
18350 69 6e 74 20 20 20 20 20 20 20 20 20 20 20 20 20 int
18360 20 54 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c True if the col
18370 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 umn has a NOT NU
18380 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a LL constraint.**
18390 20 20 20 38 74 68 20 20 20 20 20 20 20 20 20 69 8th i
183a0 6e 74 20 20 20 20 20 20 20 20 20 20 20 20 20 20 nt
183b0 54 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75 True if the colu
183c0 6d 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 mn is part of th
183d0 65 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a e PRIMARY KEY.**
183e0 20 20 20 39 74 68 20 20 20 20 20 20 20 20 20 69 9th i
183f0 6e 74 20 20 20 20 20 20 20 20 20 20 20 20 20 20 nt
18400 54 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75 True if the colu
18410 6d 6e 20 69 73 20 41 55 54 4f 49 4e 43 52 45 4d mn is AUTOINCREM
18420 45 4e 54 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a ENT.** </pre>.**
18430 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 .**.** The memor
18440 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 y pointed to by
18450 74 68 65 20 63 68 61 72 61 63 74 65 72 20 70 6f the character po
18460 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 inters returned
18470 66 6f 72 20 74 68 65 20 0a 2a 2a 20 64 65 63 6c for the .** decl
18480 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 aration type and
18490 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 collation seque
184a0 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c nce is valid onl
184b0 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 y until the next
184c0 20 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79 .** call to any
184d0 20 73 71 6c 69 74 65 20 41 50 49 20 66 75 6e 63 sqlite API func
184e0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 tion..**.** If t
184f0 68 65 20 73 70 65 63 69 66 69 65 64 20 74 61 62 he specified tab
18500 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79 20 61 le is actually a
18510 20 76 69 65 77 2c 20 74 68 65 6e 20 61 6e 20 65 view, then an e
18520 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 rror is returned
18530 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 ..**.** If the s
18540 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 pecified column
18550 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 is "rowid", "oid
18560 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 " or "_rowid_" a
18570 6e 64 20 61 6e 20 0a 2a 2a 20 49 4e 54 45 47 45 nd an .** INTEGE
18580 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20 63 6f R PRIMARY KEY co
18590 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 65 78 lumn has been ex
185a0 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 plicitly declare
185b0 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 d, then the outp
185c0 75 74 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ut .** parameter
185d0 73 20 61 72 65 20 73 65 74 20 66 6f 72 20 74 68 s are set for th
185e0 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 e explicitly dec
185f0 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 49 66 lared column. If
18600 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 there is no.**
18610 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 explicitly decla
18620 72 65 64 20 49 50 4b 20 63 6f 6c 75 6d 6e 2c 20 red IPK column,
18630 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 20 then the output
18640 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 parameters are s
18650 65 74 20 61 73 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 et as .** follow
18660 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a s:.**.** <pre>.*
18670 2a 20 20 20 20 20 64 61 74 61 20 74 79 70 65 3a * data type:
18680 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 "INTEGER".**
18690 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 collation sequ
186a0 65 6e 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a ence: "BINARY".*
186b0 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 * not null:
186c0 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79 0.** primary
186d0 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 key: 1.** a
186e0 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 uto increment: 0
186f0 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a .** </pre>.**.**
18700 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d This function m
18710 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d ay load one or m
18720 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f 6d ore schemas from
18730 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e database files.
18740 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 If an.** error
18750 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 occurs during th
18760 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 is process, or i
18770 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 f the requested
18780 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a table or column.
18790 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 ** cannot be fou
187a0 6e 64 2c 20 61 6e 20 53 51 4c 49 54 45 20 65 72 nd, an SQLITE er
187b0 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 ror code is retu
187c0 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 72 72 6f rned and an erro
187d0 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 6c 65 66 r message.** lef
187e0 74 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 t in the databas
187f0 65 20 68 61 6e 64 6c 65 20 28 74 6f 20 62 65 20 e handle (to be
18800 72 65 74 72 69 65 76 65 64 20 75 73 69 6e 67 20 retrieved using
18810 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 sqlite3_errmsg()
18820 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 )..**.** This AP
18830 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 I is only availa
18840 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 ble if the libra
18850 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 ry was compiled
18860 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 with the.** SQLI
18870 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e TE_ENABLE_COLUMN
18880 5f 4d 45 54 41 44 41 54 41 20 70 72 65 70 72 6f _METADATA prepro
18890 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 cessor symbol de
188a0 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 fined..*/.int sq
188b0 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 lite3_table_colu
188c0 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73 mn_metadata(. s
188d0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
188e0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f /* Co
188f0 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 nnection handle
18900 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
18910 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 *zDbName,
18920 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6e 61 6d /* Database nam
18930 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 e or NULL */. c
18940 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c onst char *zTabl
18950 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 eName, /* Ta
18960 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f ble name */. co
18970 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d nst char *zColum
18980 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c nName, /* Col
18990 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 umn name */. ch
189a0 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 ar const **pzDat
189b0 61 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 aType, /* OUT
189c0 50 55 54 3a 20 44 65 63 6c 61 72 65 64 20 64 61 PUT: Declared da
189d0 74 61 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 ta type */. cha
189e0 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c r const **pzColl
189f0 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 Seq, /* OUTP
18a00 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 UT: Collation se
18a10 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 quence name */.
18a20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 int *pNotNull,
18a30 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
18a40 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 OUTPUT: True if
18a50 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 NOT NULL constra
18a60 69 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 int exists */.
18a70 69 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 int *pPrimaryKey
18a80 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f , /* O
18a90 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 UTPUT: True if c
18aa0 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b olumn part of PK
18ab0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f */. int *pAuto
18ac0 69 6e 63 20 20 20 20 20 20 20 20 20 20 20 20 20 inc
18ad0 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 /* OUTPUT: Tru
18ae0 65 20 69 66 20 63 6f 6c 75 6d 73 20 69 73 20 61 e if colums is a
18af0 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f uto-increment */
18b00 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
18b10 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 REF: Load An Ext
18b20 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 41 74 74 ension.**.** Att
18b30 65 6d 70 74 20 74 6f 20 6c 6f 61 64 20 61 6e 20 empt to load an
18b40 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e SQLite extension
18b50 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e library contain
18b60 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65 0a 2a ed in the file.*
18b70 2a 20 7a 46 69 6c 65 2e 20 20 54 68 65 20 65 6e * zFile. The en
18b80 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 72 try point is zPr
18b90 6f 63 2e 20 20 7a 50 72 6f 63 20 6d 61 79 20 62 oc. zProc may b
18ba0 65 20 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 e 0 in which cas
18bb0 65 20 74 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 e the.** name of
18bc0 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 the entry point
18bd0 20 64 65 66 61 75 6c 74 73 20 74 6f 20 22 73 71 defaults to "sq
18be0 6c 69 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f lite3_extension_
18bf0 69 6e 69 74 22 2e 0a 2a 2a 0a 2a 2a 20 52 65 74 init"..**.** Ret
18c00 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 urn [SQLITE_OK]
18c10 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b on success and [
18c20 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 SQLITE_ERROR] if
18c30 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 something goes
18c40 77 72 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 wrong..**.** If
18c50 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 an error occurs
18c60 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20 and pzErrMsg is
18c70 6e 6f 74 20 30 2c 20 74 68 65 6e 20 66 69 6c 6c not 0, then fill
18c80 20 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20 *pzErrMsg with
18c90 0a 2a 2a 20 65 72 72 6f 72 20 6d 65 73 73 61 67 .** error messag
18ca0 65 20 74 65 78 74 2e 20 20 54 68 65 20 63 61 6c e text. The cal
18cb0 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68 ling function sh
18cc0 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d ould free this m
18cd0 65 6d 6f 72 79 0a 2a 2a 20 62 79 20 63 61 6c 6c emory.** by call
18ce0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 ing [sqlite3_fre
18cf0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 45 78 74 65 e()]..**.** Exte
18d00 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 nsion loading mu
18d10 73 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73 st be enabled us
18d20 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 ing [sqlite3_ena
18d30 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 ble_load_extensi
18d40 6f 6e 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 on()].** prior t
18d50 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 o calling this A
18d60 50 49 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 77 PI or an error w
18d70 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e ill be returned.
18d80 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
18d90 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a load_extension(.
18da0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
18db0 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 /* Load
18dc0 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e the extension in
18dd0 74 6f 20 74 68 69 73 20 64 61 74 61 62 61 73 65 to this database
18de0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 connection */.
18df0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 const char *zFi
18e00 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f le, /* Name o
18e10 66 20 74 68 65 20 73 68 61 72 65 64 20 6c 69 62 f the shared lib
18e20 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 rary containing
18e30 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 extension */. c
18e40 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 onst char *zProc
18e50 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f , /* Entry po
18e60 69 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66 72 int. Derived fr
18e70 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f om zFile if 0 */
18e80 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d . char **pzErrM
18e90 73 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20 sg /* Put
18ea0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65 error message he
18eb0 72 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 re if not 0 */.)
18ec0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
18ed0 46 3a 20 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 F: Enable Or Di
18ee0 73 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 sable Extension
18ef0 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 53 6f Loading.**.** So
18f00 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 as not to open
18f10 73 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69 security holes i
18f20 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74 n older applicat
18f30 69 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a ions that are.**
18f40 20 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64 unprepared to d
18f50 65 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69 eal with extensi
18f60 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 on loading, and
18f70 61 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 as a means of di
18f80 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e sabling.** exten
18f90 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 sion loading whi
18fa0 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73 le evaluating us
18fb0 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 er-entered SQL,
18fc0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a the following.**
18fd0 20 41 50 49 20 69 73 20 70 72 6f 76 69 64 65 64 API is provided
18fe0 20 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71 to turn the [sq
18ff0 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e lite3_load_exten
19000 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 sion()] mechanis
19010 6d 20 6f 6e 20 61 6e 64 0a 2a 2a 20 6f 66 66 2e m on and.** off.
19020 20 20 49 74 20 69 73 20 6f 66 66 20 62 79 20 64 It is off by d
19030 65 66 61 75 6c 74 2e 20 20 53 65 65 20 74 69 63 efault. See tic
19040 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 0a 2a 2a ket #1863..**.**
19050 20 43 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 Call this routi
19060 6e 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 ne with onoff==1
19070 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69 to turn extensi
19080 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 0a 2a 2a on loading on.**
19090 20 61 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 and call it wit
190a0 68 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 h onoff==0 to tu
190b0 72 6e 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61 rn it back off a
190c0 67 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c gain..*/.int sql
190d0 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 ite3_enable_load
190e0 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 _extension(sqlit
190f0 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 e3 *db, int onof
19100 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 f);../*.** CAPI3
19110 52 45 46 3a 20 4d 61 6b 65 20 41 72 72 61 6e 67 REF: Make Arrang
19120 65 6d 65 6e 74 73 20 54 6f 20 41 75 74 6f 6d 61 ements To Automa
19130 74 69 63 61 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 tically Load An
19140 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 Extension.**.**
19150 52 65 67 69 73 74 65 72 20 61 6e 20 65 78 74 65 Register an exte
19160 6e 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e nsion entry poin
19170 74 20 74 68 61 74 20 69 73 20 61 75 74 6f 6d 61 t that is automa
19180 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 0a tically invoked.
19190 2a 2a 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65 ** whenever a ne
191a0 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 w database conne
191b0 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 20 ction is opened
191c0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 using.** [sqlite
191d0 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 3_open()] or [sq
191e0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e lite3_open16()].
191f0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 .**.** This API
19200 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65 64 20 61 can be invoked a
19210 74 20 70 72 6f 67 72 61 6d 20 73 74 61 72 74 75 t program startu
19220 70 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 72 65 p in order to re
19230 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 gister.** one or
19240 20 6d 6f 72 65 20 73 74 61 74 69 63 61 6c 6c 79 more statically
19250 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e 73 69 6f linked extensio
19260 6e 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 ns that will be
19270 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20 available.** to
19280 61 6c 6c 20 6e 65 77 20 64 61 74 61 62 61 73 65 all new database
19290 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a connections..**
192a0 0a 2a 2a 20 44 75 70 6c 69 63 61 74 65 20 65 78 .** Duplicate ex
192b0 74 65 6e 73 69 6f 6e 73 20 61 72 65 20 64 65 74 tensions are det
192c0 65 63 74 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67 ected so calling
192d0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 this routine mu
192e0 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 ltiple.** times
192f0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 65 78 with the same ex
19300 74 65 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c tension is harml
19310 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ess..**.** This
19320 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61 routine stores a
19330 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
19340 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 extension in an
19350 61 72 72 61 79 0a 2a 2a 20 74 68 61 74 20 69 73 array.** that is
19360 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 6d obtained from m
19370 61 6c 6c 6f 63 28 29 2e 20 20 49 66 20 79 6f 75 alloc(). If you
19380 20 72 75 6e 20 61 20 6d 65 6d 6f 72 79 20 6c 65 run a memory le
19390 61 6b 0a 2a 2a 20 63 68 65 63 6b 65 72 20 6f 6e ak.** checker on
193a0 20 79 6f 75 72 20 70 72 6f 67 72 61 6d 20 61 6e your program an
193b0 64 20 69 74 20 72 65 70 6f 72 74 73 20 61 20 6c d it reports a l
193c0 65 61 6b 20 62 65 63 61 75 73 65 20 6f 66 20 74 eak because of t
193d0 68 69 73 0a 2a 2a 20 61 72 72 61 79 2c 20 74 68 his.** array, th
193e0 65 6e 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 en invoke [sqlit
193f0 65 33 5f 61 75 74 6f 6d 61 74 69 63 5f 65 78 74 e3_automatic_ext
19400 65 6e 73 69 6f 6e 5f 72 65 73 65 74 28 29 5d 20 ension_reset()]
19410 70 72 69 6f 72 0a 2a 2a 20 74 6f 20 73 68 75 74 prior.** to shut
19420 64 6f 77 6e 20 74 6f 20 66 72 65 65 20 74 68 65 down to free the
19430 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 memory..**.** A
19440 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 utomatic extensi
19450 6f 6e 73 20 61 70 70 6c 79 20 61 63 72 6f 73 73 ons apply across
19460 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a all threads..**
19470 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 .** This interfa
19480 63 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 ce is experiment
19490 61 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 al and is subjec
194a0 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a t to change or.*
194b0 2a 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 * removal in fut
194c0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 ure releases of
194d0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 SQLite..*/.int s
194e0 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 qlite3_auto_exte
194f0 6e 73 69 6f 6e 28 76 6f 69 64 20 2a 78 45 6e 74 nsion(void *xEnt
19500 72 79 50 6f 69 6e 74 29 3b 0a 0a 0a 2f 2a 0a 2a ryPoint);.../*.*
19510 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 * CAPI3REF: Rese
19520 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78 74 65 t Automatic Exte
19530 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a nsion Loading.**
19540 0a 2a 2a 20 44 69 73 61 62 6c 65 20 61 6c 6c 20 .** Disable all
19550 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 previously regis
19560 74 65 72 65 64 20 61 75 74 6f 6d 61 74 69 63 20 tered automatic
19570 65 78 74 65 6e 73 69 6f 6e 73 2e 20 20 54 68 69 extensions. Thi
19580 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 s.** routine und
19590 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f oes the effect o
195a0 66 20 61 6c 6c 20 70 72 69 6f 72 20 5b 73 71 6c f all prior [sql
195b0 69 74 65 33 5f 61 75 74 6f 6d 61 74 69 63 5f 65 ite3_automatic_e
195c0 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 63 xtension()].** c
195d0 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 alls..**.** This
195e0 20 63 61 6c 6c 20 64 69 73 61 62 6c 65 64 20 61 call disabled a
195f0 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 utomatic extensi
19600 6f 6e 73 20 69 6e 20 61 6c 6c 20 74 68 72 65 61 ons in all threa
19610 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 ds..**.** This i
19620 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65 nterface is expe
19630 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 rimental and is
19640 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 subject to chang
19650 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 e or.** removal
19660 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
19670 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f es of SQLite..*/
19680 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
19690 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 set_auto_extensi
196a0 6f 6e 28 76 6f 69 64 29 3b 0a 0a 0a 2f 2a 0a 2a on(void);.../*.*
196b0 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 ***** EXPERIMENT
196c0 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 AL - subject to
196d0 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e change without n
196e0 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a otice **********
196f0 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 ****.**.** The i
19700 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 nterface to the
19710 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 virtual-table me
19720 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65 chanism is curre
19730 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a ntly considered.
19740 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d ** to be experim
19750 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 ental. The inte
19760 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e rface might chan
19770 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 ge in incompatib
19780 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 le ways..** If t
19790 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d his is a problem
197a0 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 for you, do not
197b0 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 use the interfa
197c0 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e ce at this time.
197d0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 .**.** When the
197e0 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 virtual-table me
197f0 63 68 61 6e 69 73 6d 20 73 74 61 62 6c 69 7a 65 chanism stablize
19800 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 s, we will decla
19810 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 re the.** interf
19820 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f ace fixed, suppo
19830 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 rt it indefinite
19840 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 ly, and remove t
19850 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a his comment..*/.
19860 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 ./*.** Structure
19870 73 20 75 73 65 64 20 62 79 20 74 68 65 20 76 69 s used by the vi
19880 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 rtual table inte
19890 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 rface.*/.typedef
198a0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
198b0 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61 vtab sqlite3_vta
198c0 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 b;.typedef struc
198d0 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f t sqlite3_index_
198e0 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 info sqlite3_ind
198f0 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 ex_info;.typedef
19900 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
19910 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 vtab_cursor sqli
19920 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b te3_vtab_cursor;
19930 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
19940 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 sqlite3_module s
19950 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a qlite3_module;..
19960 2f 2a 0a 2a 2a 20 41 20 6d 6f 64 75 6c 65 20 69 /*.** A module i
19970 73 20 61 20 63 6c 61 73 73 20 6f 66 20 76 69 72 s a class of vir
19980 74 75 61 6c 20 74 61 62 6c 65 73 2e 20 20 45 61 tual tables. Ea
19990 63 68 20 6d 6f 64 75 6c 65 20 69 73 20 64 65 66 ch module is def
199a0 69 6e 65 64 0a 2a 2a 20 62 79 20 61 6e 20 69 6e ined.** by an in
199b0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 66 6f stance of the fo
199c0 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 llowing structur
199d0 65 2e 20 20 54 68 69 73 20 73 74 72 75 63 74 75 e. This structu
199e0 72 65 20 63 6f 6e 73 69 73 74 73 0a 2a 2a 20 6d re consists.** m
199f0 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 ostly of methods
19a00 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e for the module.
19a10 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 .*/.struct sqlit
19a20 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e e3_module {. in
19a30 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e t iVersion;. in
19a40 74 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c t (*xCreate)(sql
19a50 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 ite3*, void *pAu
19a60 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 x,.
19a70 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 int argc, cons
19a80 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 t char *const*ar
19a90 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 gv,.
19aa0 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 sqlite3_vtab
19ab0 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a **ppVTab, char**
19ac0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e );. int (*xConn
19ad0 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 ect)(sqlite3*, v
19ae0 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 oid *pAux,.
19af0 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 int ar
19b00 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a gc, const char *
19b10 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 const*argv,.
19b20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 sqlit
19b30 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 e3_vtab **ppVTab
19b40 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 , char**);. int
19b50 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 (*xBestIndex)(s
19b60 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 qlite3_vtab *pVT
19b70 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 ab, sqlite3_inde
19b80 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 x_info*);. int
19b90 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 (*xDisconnect)(s
19ba0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 qlite3_vtab *pVT
19bb0 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 ab);. int (*xDe
19bc0 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 stroy)(sqlite3_v
19bd0 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 tab *pVTab);. i
19be0 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 nt (*xOpen)(sqli
19bf0 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c te3_vtab *pVTab,
19c00 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 sqlite3_vtab_cu
19c10 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 rsor **ppCursor)
19c20 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 ;. int (*xClose
19c30 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 )(sqlite3_vtab_c
19c40 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 ursor*);. int (
19c50 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 *xFilter)(sqlite
19c60 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 3_vtab_cursor*,
19c70 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 int idxNum, cons
19c80 74 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a t char *idxStr,.
19c90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
19ca0 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 int argc, sqlite
19cb0 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 3_value **argv);
19cc0 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 . int (*xNext)(
19cd0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 sqlite3_vtab_cur
19ce0 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 sor*);. int (*x
19cf0 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61 Eof)(sqlite3_vta
19d00 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e b_cursor*);. in
19d10 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c t (*xColumn)(sql
19d20 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 ite3_vtab_cursor
19d30 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 *, sqlite3_conte
19d40 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 xt*, int);. int
19d50 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74 (*xRowid)(sqlit
19d60 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c e3_vtab_cursor*,
19d70 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 2a 70 sqlite_int64 *p
19d80 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a Rowid);. int (*
19d90 78 55 70 64 61 74 65 29 28 73 71 6c 69 74 65 33 xUpdate)(sqlite3
19da0 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71 _vtab *, int, sq
19db0 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 lite3_value **,
19dc0 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 2a 29 3b sqlite_int64 *);
19dd0 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29 . int (*xBegin)
19de0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 (sqlite3_vtab *p
19df0 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 VTab);. int (*x
19e00 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76 74 Sync)(sqlite3_vt
19e10 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e ab *pVTab);. in
19e20 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c t (*xCommit)(sql
19e30 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 ite3_vtab *pVTab
19e40 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c );. int (*xRoll
19e50 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 74 back)(sqlite3_vt
19e60 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e ab *pVTab);. in
19e70 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f t (*xFindFunctio
19e80 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 n)(sqlite3_vtab
19e90 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72 67 *pVtab, int nArg
19ea0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
19eb0 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20 20 ame,.
19ec0 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 void
19ed0 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c 69 (**pxFunc)(sqli
19ee0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 te3_context*,int
19ef0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a ,sqlite3_value**
19f00 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 ),.
19f10 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 2a void *
19f20 2a 70 70 41 72 67 29 3b 0a 0a 20 20 69 6e 74 20 *ppArg);.. int
19f30 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 (*xRename)(sqlit
19f40 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 e3_vtab *pVtab,
19f50 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 const char *zNew
19f60 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 );.};../*.** The
19f70 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 sqlite3_index_i
19f80 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20 61 6e nfo structure an
19f90 64 20 69 74 73 20 73 75 62 73 74 72 75 63 74 75 d its substructu
19fa0 72 65 73 20 69 73 20 75 73 65 64 20 74 6f 0a 2a res is used to.*
19fb0 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d 61 74 69 * pass informati
19fc0 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65 63 65 on into and rece
19fd0 69 76 65 20 74 68 65 20 72 65 70 6c 79 20 66 72 ive the reply fr
19fe0 6f 6d 20 74 68 65 20 78 42 65 73 74 49 6e 64 65 om the xBestInde
19ff0 78 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61 x.** method of a
1a000 6e 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 n sqlite3_module
1a010 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e . The fields un
1a020 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 der **Inputs** a
1a030 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 re the.** inputs
1a040 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61 to xBestIndex a
1a050 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 nd are read-only
1a060 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e . xBestIndex in
1a070 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 serts its.** res
1a080 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a ults into the **
1a090 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 Outputs** fields
1a0a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43 6f 6e ..**.** The aCon
1a0b0 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 straint[] array
1a0c0 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c records WHERE cl
1a0d0 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 ause constraints
1a0e0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 3a of the.** form:
1a0f0 0a 2a 2a 0a 2a 2a 20 20 20 20 20 20 20 20 20 63 .**.** c
1a100 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 0a 2a 2a olumn OP expr.**
1a110 0a 2a 2a 20 57 68 65 72 65 20 4f 50 20 69 73 20 .** Where OP is
1a120 3d 2c 20 3c 2c 20 3c 3d 2c 20 3e 2c 20 6f 72 20 =, <, <=, >, or
1a130 3e 3d 2e 20 20 54 68 65 20 70 61 72 74 69 63 75 >=. The particu
1a140 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69 73 20 lar operator is
1a150 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 43 6f stored.** in aCo
1a160 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e 20 20 nstraint[].op.
1a170 54 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 The index of the
1a180 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65 column is store
1a190 64 20 69 6e 20 0a 2a 2a 20 61 43 6f 6e 73 74 72 d in .** aConstr
1a1a0 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 20 aint[].iColumn.
1a1b0 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 aConstraint[].u
1a1c0 73 61 62 6c 65 20 69 73 20 54 52 55 45 20 69 66 sable is TRUE if
1a1d0 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 the.** expr on
1a1e0 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 the right-hand s
1a1f0 69 64 65 20 63 61 6e 20 62 65 20 65 76 61 6c 75 ide can be evalu
1a200 61 74 65 64 20 28 61 6e 64 20 74 68 75 73 20 74 ated (and thus t
1a210 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a he constraint.**
1a220 20 69 73 20 75 73 61 62 6c 65 29 20 61 6e 64 20 is usable) and
1a230 66 61 6c 73 65 20 69 66 20 69 74 20 63 61 6e 6e false if it cann
1a240 6f 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 70 ot..**.** The op
1a250 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 timizer automati
1a260 63 61 6c 6c 79 20 69 6e 76 65 72 74 73 20 74 65 cally inverts te
1a270 72 6d 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 rms of the form
1a280 22 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 "expr OP column"
1a290 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 .** and makes ot
1a2a0 68 65 72 20 73 69 6d 70 6c 69 66 69 63 61 74 69 her simplificati
1a2b0 6e 6f 73 20 74 6f 20 74 68 65 20 57 48 45 52 45 nos to the WHERE
1a2c0 20 63 6c 61 75 73 65 20 69 6e 20 61 6e 20 61 74 clause in an at
1a2d0 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 tempt to.** get
1a2e0 61 73 20 6d 61 6e 79 20 57 48 45 52 45 20 63 6c as many WHERE cl
1a2f0 61 75 73 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 ause terms into
1a300 74 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 the form shown a
1a310 62 6f 76 65 20 61 73 20 70 6f 73 73 69 62 6c 65 bove as possible
1a320 2e 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74 72 ..** The aConstr
1a330 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c aint[] array onl
1a340 79 20 72 65 70 6f 72 74 73 20 57 48 45 52 45 20 y reports WHERE
1a350 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e 20 clause terms in
1a360 74 68 65 20 63 6f 72 72 65 63 74 0a 2a 2a 20 66 the correct.** f
1a370 6f 72 6d 20 74 68 61 74 20 72 65 66 65 72 20 74 orm that refer t
1a380 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 o the particular
1a390 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 62 virtual table b
1a3a0 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a eing queried..**
1a3b0 0a 2a 2a 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 .** Information
1a3c0 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52 20 about the ORDER
1a3d0 42 59 20 63 6c 61 75 73 65 20 69 73 20 73 74 6f BY clause is sto
1a3e0 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42 79 5b red in aOrderBy[
1a3f0 5d 2e 0a 2a 2a 20 45 61 63 68 20 74 65 72 6d 20 ]..** Each term
1a400 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65 63 6f of aOrderBy reco
1a410 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 rds a column of
1a420 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 the ORDER BY cla
1a430 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 use..**.** The x
1a440 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64 BestIndex method
1a450 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73 must fill aCons
1a460 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 77 69 traintUsage[] wi
1a470 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a th information.*
1a480 2a 20 61 62 6f 75 74 20 77 68 61 74 20 70 61 72 * about what par
1a490 61 6d 65 74 65 72 73 20 74 6f 20 70 61 73 73 20 ameters to pass
1a4a0 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 49 66 20 to xFilter. If
1a4b0 61 72 67 76 49 6e 64 65 78 3e 30 20 74 68 65 6e argvIndex>0 then
1a4c0 0a 2a 2a 20 74 68 65 20 72 69 67 68 74 2d 68 61 .** the right-ha
1a4d0 6e 64 20 73 69 64 65 20 6f 66 20 74 68 65 20 63 nd side of the c
1a4e0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f orresponding aCo
1a4f0 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 65 76 nstraint[] is ev
1a500 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62 aluated.** and b
1a510 65 63 6f 6d 65 73 20 74 68 65 20 61 72 67 76 49 ecomes the argvI
1a520 6e 64 65 78 2d 74 68 20 65 6e 74 72 79 20 69 6e ndex-th entry in
1a530 20 61 72 67 76 2e 20 20 49 66 20 61 43 6f 6e 73 argv. If aCons
1a540 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d traintUsage[].om
1a550 69 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20 74 it.** is true, t
1a560 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 72 61 69 hen the constrai
1a570 6e 74 20 69 73 20 61 73 73 75 6d 65 64 20 74 6f nt is assumed to
1a580 20 62 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65 be fully handle
1a590 64 20 62 79 20 74 68 65 0a 2a 2a 20 76 69 72 74 d by the.** virt
1a5a0 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 69 73 ual table and is
1a5b0 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 61 67 61 not checked aga
1a5c0 69 6e 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a in by SQLite..**
1a5d0 0a 2a 2a 20 54 68 65 20 69 64 78 4e 75 6d 20 61 .** The idxNum a
1a5e0 6e 64 20 69 64 78 50 74 72 20 76 61 6c 75 65 73 nd idxPtr values
1a5f0 20 61 72 65 20 72 65 63 6f 72 64 65 64 20 61 6e are recorded an
1a600 64 20 70 61 73 73 65 64 20 69 6e 74 6f 20 78 46 d passed into xF
1a610 69 6c 74 65 72 2e 0a 2a 2a 20 73 71 6c 69 74 65 ilter..** sqlite
1a620 33 5f 66 72 65 65 28 29 20 69 73 20 75 73 65 64 3_free() is used
1a630 20 74 6f 20 66 72 65 65 20 69 64 78 50 74 72 20 to free idxPtr
1a640 69 66 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 if needToFreeIdx
1a650 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a Ptr is true..**.
1a660 2a 2a 20 54 68 65 20 6f 72 64 65 72 42 79 43 6f ** The orderByCo
1a670 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 nsumed means tha
1a680 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 78 46 t output from xF
1a690 69 6c 74 65 72 20 77 69 6c 6c 20 6f 63 63 75 72 ilter will occur
1a6a0 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 72 65 in.** the corre
1a6b0 63 74 20 6f 72 64 65 72 20 74 6f 20 73 61 74 69 ct order to sati
1a6c0 73 66 79 20 74 68 65 20 4f 52 44 45 52 20 42 59 sfy the ORDER BY
1a6d0 20 63 6c 61 75 73 65 20 73 6f 20 74 68 61 74 20 clause so that
1a6e0 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 73 no separate.** s
1a6f0 6f 72 74 69 6e 67 20 73 74 65 70 20 69 73 20 72 orting step is r
1a700 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 equired..**.** T
1a710 68 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 he estimatedCost
1a720 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65 73 74 value is an est
1a730 69 6d 61 74 65 20 6f 66 20 74 68 65 20 63 6f 73 imate of the cos
1a740 74 20 6f 66 20 64 6f 69 6e 67 20 74 68 65 0a 2a t of doing the.*
1a750 2a 20 70 61 72 74 69 63 75 6c 61 72 20 6c 6f 6f * particular loo
1a760 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20 73 63 61 kup. A full sca
1a770 6e 20 6f 66 20 61 20 74 61 62 6c 65 20 77 69 74 n of a table wit
1a780 68 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 h N entries shou
1a790 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20 63 6f 73 ld have.** a cos
1a7a0 74 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e 61 72 t of N. A binar
1a7b0 79 20 73 65 61 72 63 68 20 6f 66 20 61 20 74 61 y search of a ta
1a7c0 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69 65 73 ble of N entries
1a7d0 20 73 68 6f 75 6c 64 20 68 61 76 65 20 61 0a 2a should have a.*
1a7e0 2a 20 63 6f 73 74 20 6f 66 20 61 70 70 72 6f 78 * cost of approx
1a7f0 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a imately log(N)..
1a800 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 */.struct sqlite
1a810 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a 20 3_index_info {.
1a820 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20 20 /* Inputs */.
1a830 63 6f 6e 73 74 20 69 6e 74 20 6e 43 6f 6e 73 74 const int nConst
1a840 72 61 69 6e 74 3b 20 20 20 20 20 2f 2a 20 4e 75 raint; /* Nu
1a850 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20 mber of entries
1a860 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 20 2a in aConstraint *
1a870 2f 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 /. const struct
1a880 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 sqlite3_index_c
1a890 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20 20 onstraint {.
1a8a0 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 int iColumn;
1a8b0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f /* Co
1a8c0 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 6e lumn on left-han
1a8d0 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74 72 d side of constr
1a8e0 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e 73 aint */. uns
1a8f0 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20 20 igned char op;
1a900 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74 72 /* Constr
1a910 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a 2f aint operator */
1a920 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 . unsigned c
1a930 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20 20 har usable;
1a940 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69 73 20 /* True if this
1a950 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75 73 constraint is us
1a960 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e 74 able */. int
1a970 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20 20 iTermOffset;
1a980 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69 /* Used i
1a990 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65 73 nternally - xBes
1a9a0 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69 67 tIndex should ig
1a9b0 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 63 6f 6e nore */. } *con
1a9c0 73 74 20 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 st aConstraint;
1a9d0 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f 66 /* Table of
1a9e0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f WHERE clause co
1a9f0 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20 63 nstraints */. c
1aa00 6f 6e 73 74 20 69 6e 74 20 6e 4f 72 64 65 72 42 onst int nOrderB
1aa10 79 3b 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d y; /* Num
1aa20 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 ber of terms in
1aa30 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 the ORDER BY cla
1aa40 75 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 use */. const s
1aa50 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e truct sqlite3_in
1aa60 64 65 78 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 dex_orderby {.
1aa70 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 int iColumn;
1aa80 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
1aa90 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f Column number */
1aaa0 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 . unsigned c
1aab0 68 61 72 20 64 65 73 63 3b 20 20 20 20 20 20 20 har desc;
1aac0 2f 2a 20 54 72 75 65 20 66 6f 72 20 44 45 53 43 /* True for DESC
1aad0 2e 20 20 46 61 6c 73 65 20 66 6f 72 20 41 53 43 . False for ASC
1aae0 2e 20 2a 2f 0a 20 20 7d 20 2a 63 6f 6e 73 74 20 . */. } *const
1aaf0 61 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 aOrderBy;
1ab00 20 20 2f 2a 20 54 68 65 20 4f 52 44 45 52 20 42 /* The ORDER B
1ab10 59 20 63 6c 61 75 73 65 20 2a 2f 0a 0a 20 20 2f Y clause */.. /
1ab20 2a 20 4f 75 74 70 75 74 73 20 2a 2f 0a 20 20 73 * Outputs */. s
1ab30 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e truct sqlite3_in
1ab40 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 5f 75 dex_constraint_u
1ab50 73 61 67 65 20 7b 0a 20 20 20 20 69 6e 74 20 61 sage {. int a
1ab60 72 67 76 49 6e 64 65 78 3b 20 20 20 20 20 20 20 rgvIndex;
1ab70 20 20 20 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f /* if >0, co
1ab80 6e 73 74 72 61 69 6e 74 20 69 73 20 70 61 72 74 nstraint is part
1ab90 20 6f 66 20 61 72 67 76 20 74 6f 20 78 46 69 6c of argv to xFil
1aba0 74 65 72 20 2a 2f 0a 20 20 20 20 75 6e 73 69 67 ter */. unsig
1abb0 6e 65 64 20 63 68 61 72 20 6f 6d 69 74 3b 20 20 ned char omit;
1abc0 20 20 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f /* Do not co
1abd0 64 65 20 61 20 74 65 73 74 20 66 6f 72 20 74 68 de a test for th
1abe0 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f is constraint */
1abf0 0a 20 20 7d 20 2a 63 6f 6e 73 74 20 61 43 6f 6e . } *const aCon
1ac00 73 74 72 61 69 6e 74 55 73 61 67 65 3b 0a 20 20 straintUsage;.
1ac10 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20 20 20 20 int idxNum;
1ac20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 /* Nu
1ac30 6d 62 65 72 20 75 73 65 64 20 74 6f 20 69 64 65 mber used to ide
1ac40 6e 74 69 66 79 20 74 68 65 20 69 6e 64 65 78 20 ntify the index
1ac50 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64 78 53 74 */. char *idxSt
1ac60 72 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 r;
1ac70 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f 73 73 69 /* String, possi
1ac80 62 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f bly obtained fro
1ac90 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 m sqlite3_malloc
1aca0 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 64 54 6f */. int needTo
1acb0 46 72 65 65 49 64 78 53 74 72 3b 20 20 20 20 20 FreeIdxStr;
1acc0 20 2f 2a 20 46 72 65 65 20 69 64 78 53 74 72 20 /* Free idxStr
1acd0 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 using sqlite3_fr
1ace0 65 65 28 29 20 69 66 20 74 72 75 65 20 2a 2f 0a ee() if true */.
1acf0 20 20 69 6e 74 20 6f 72 64 65 72 42 79 43 6f 6e int orderByCon
1ad00 73 75 6d 65 64 3b 20 20 20 20 20 20 20 2f 2a 20 sumed; /*
1ad10 54 72 75 65 20 69 66 20 6f 75 74 70 75 74 20 69 True if output i
1ad20 73 20 61 6c 72 65 61 64 79 20 6f 72 64 65 72 65 s already ordere
1ad30 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 20 65 73 d */. double es
1ad40 74 69 6d 61 74 65 64 43 6f 73 74 3b 20 20 20 20 timatedCost;
1ad50 20 20 2f 2a 20 45 73 74 69 6d 61 74 65 64 20 63 /* Estimated c
1ad60 6f 73 74 20 6f 66 20 75 73 69 6e 67 20 74 68 69 ost of using thi
1ad70 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 23 64 s index */.};.#d
1ad80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 efine SQLITE_IND
1ad90 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 EX_CONSTRAINT_EQ
1ada0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 2.#define SQ
1adb0 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 LITE_INDEX_CONST
1adc0 52 41 49 4e 54 5f 47 54 20 20 20 20 34 0a 23 64 RAINT_GT 4.#d
1add0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 efine SQLITE_IND
1ade0 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 EX_CONSTRAINT_LE
1adf0 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 8.#define SQ
1ae00 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 LITE_INDEX_CONST
1ae10 52 41 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23 RAINT_LT 16.#
1ae20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e define SQLITE_IN
1ae30 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 DEX_CONSTRAINT_G
1ae40 45 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20 E 32.#define
1ae50 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e SQLITE_INDEX_CON
1ae60 53 54 52 41 49 4e 54 5f 4d 41 54 43 48 20 36 34 STRAINT_MATCH 64
1ae70 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 ../*.** This rou
1ae80 74 69 6e 65 20 69 73 20 75 73 65 64 20 74 6f 20 tine is used to
1ae90 72 65 67 69 73 74 65 72 20 61 20 6e 65 77 20 6d register a new m
1aea0 6f 64 75 6c 65 20 6e 61 6d 65 20 77 69 74 68 20 odule name with
1aeb0 61 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 6e an SQLite.** con
1aec0 6e 65 63 74 69 6f 6e 2e 20 20 4d 6f 64 75 6c 65 nection. Module
1aed0 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20 72 names must be r
1aee0 65 67 69 73 74 65 72 65 64 20 62 65 66 6f 72 65 egistered before
1aef0 20 63 72 65 61 74 69 6e 67 20 6e 65 77 0a 2a 2a creating new.**
1af00 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 virtual tables
1af10 6f 6e 20 74 68 65 20 6d 6f 64 75 6c 65 2c 20 6f on the module, o
1af20 72 20 62 65 66 6f 72 65 20 75 73 69 6e 67 20 70 r before using p
1af30 72 65 65 78 69 73 74 69 6e 67 20 76 69 72 74 75 reexisting virtu
1af40 61 6c 0a 2a 2a 20 74 61 62 6c 65 73 20 6f 66 20 al.** tables of
1af50 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a 69 the module..*/.i
1af60 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 nt sqlite3_creat
1af70 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69 e_module(. sqli
1af80 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
1af90 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 /* SQLite
1afa0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 connection to r
1afb0 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 egister module w
1afc0 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 ith */. const c
1afd0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 har *zName,
1afe0 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 /* Name of t
1aff0 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 he module */. c
1b000 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 onst sqlite3_mod
1b010 75 6c 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 ule *, /* Met
1b020 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 hods for the mod
1b030 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 20 ule */. void *
1b040 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1b050 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 /* Client da
1b060 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 ta for xCreate/x
1b070 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a 2f Connect */.);../
1b080 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
1b090 65 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 e is identical t
1b0a0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72 o the sqlite3_cr
1b0b0 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 20 6d 65 eate_module() me
1b0c0 74 68 6f 64 20 61 62 6f 76 65 2c 0a 2a 2a 20 65 thod above,.** e
1b0d0 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c xcept that it al
1b0e0 6c 6f 77 73 20 61 20 64 65 73 74 72 75 63 74 6f lows a destructo
1b0f0 72 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 r function to be
1b100 20 73 70 65 63 69 66 69 65 64 2e 20 49 74 20 69 specified. It i
1b110 73 0a 2a 2a 20 65 76 65 6e 20 6d 6f 72 65 20 65 s.** even more e
1b120 78 70 65 72 69 6d 65 6e 74 61 6c 20 74 68 61 6e xperimental than
1b130 20 74 68 65 20 72 65 73 74 20 6f 66 20 74 68 65 the rest of the
1b140 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 virtual tables
1b150 41 50 49 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 API..*/.int sqli
1b160 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c te3_create_modul
1b170 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 e_v2(. sqlite3
1b180 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
1b190 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e /* SQLite con
1b1a0 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 nection to regis
1b1b0 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 ter module with
1b1c0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
1b1d0 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 *zName,
1b1e0 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d /* Name of the m
1b1f0 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 odule */. const
1b200 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 sqlite3_module
1b210 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 *, /* Methods
1b220 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 for the module
1b230 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 */. void *,
1b240 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1b250 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 /* Client data f
1b260 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e or xCreate/xConn
1b270 65 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 ect */. void(*x
1b280 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 20 Destroy)(void*)
1b290 20 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 /* Module de
1b2a0 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f structor functio
1b2b0 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 45 n */.);../*.** E
1b2c0 76 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70 6c very module impl
1b2d0 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 ementation uses
1b2e0 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 a subclass of th
1b2f0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 e following stru
1b300 63 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73 63 cture.** to desc
1b310 72 69 62 65 20 61 20 70 61 72 74 69 63 75 6c 61 ribe a particula
1b320 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 r instance of th
1b330 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 e module. Each
1b340 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a subclass will.**
1b350 20 62 65 20 74 61 79 6c 6f 72 65 64 20 74 6f 20 be taylored to
1b360 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 the specific nee
1b370 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 ds of the module
1b380 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e implementation.
1b390 20 20 20 54 68 65 0a 2a 2a 20 70 75 72 70 6f 73 The.** purpos
1b3a0 65 20 6f 66 20 74 68 69 73 20 73 75 70 65 72 63 e of this superc
1b3b0 6c 61 73 73 20 69 73 20 74 6f 20 64 65 66 69 6e lass is to defin
1b3c0 65 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64 73 e certain fields
1b3d0 20 74 68 61 74 20 61 72 65 20 63 6f 6d 6d 6f 6e that are common
1b3e0 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c .** to all modul
1b3f0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
1b400 73 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c s..**.** Virtual
1b410 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 73 20 tables methods
1b420 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72 6f 72 can set an error
1b430 20 6d 65 73 73 61 67 65 20 62 79 20 61 73 73 69 message by assi
1b440 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e gning a.** strin
1b450 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 g obtained from
1b460 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 sqlite3_mprintf(
1b470 29 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54 ) to zErrMsg. T
1b480 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 he method should
1b490 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20 74 68 .** take care th
1b4a0 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73 74 72 at any prior str
1b4b0 69 6e 67 20 69 73 20 66 72 65 65 64 20 62 79 20 ing is freed by
1b4c0 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 a call to sqlite
1b4d0 33 5f 66 72 65 65 28 29 0a 2a 2a 20 70 72 69 6f 3_free().** prio
1b4e0 72 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 61 r to assigning a
1b4f0 20 6e 65 77 20 73 74 72 69 6e 67 20 74 6f 20 7a new string to z
1b500 45 72 72 4d 73 67 2e 20 20 41 66 74 65 72 20 74 ErrMsg. After t
1b510 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 he error message
1b520 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 65 64 .** is delivered
1b530 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69 65 6e up to the clien
1b540 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 t application, t
1b550 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 he string will b
1b560 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a e automatically.
1b570 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71 6c 69 ** freed by sqli
1b580 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64 20 74 te3_free() and t
1b590 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 he zErrMsg field
1b5a0 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e will be zeroed.
1b5b0 20 20 4e 6f 74 65 0a 2a 2a 20 74 68 61 74 20 73 Note.** that s
1b5c0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 qlite3_mprintf()
1b5d0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 66 72 65 and sqlite3_fre
1b5e0 65 28 29 20 61 72 65 20 75 73 65 64 20 6f 6e 20 e() are used on
1b5f0 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c the zErrMsg fiel
1b600 64 0a 2a 2a 20 73 69 6e 63 65 20 76 69 72 74 75 d.** since virtu
1b610 61 6c 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f al tables are co
1b620 6d 6d 6f 6e 6c 79 20 69 6d 70 6c 65 6d 65 6e 74 mmonly implement
1b630 65 64 20 69 6e 20 6c 6f 61 64 61 62 6c 65 20 65 ed in loadable e
1b640 78 74 65 6e 73 69 6f 6e 73 20 77 68 69 63 68 0a xtensions which.
1b650 2a 2a 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 61 ** do not have a
1b660 63 63 65 73 73 20 74 6f 20 73 71 6c 69 74 65 33 ccess to sqlite3
1b670 4d 50 72 69 6e 74 66 28 29 20 6f 72 20 73 71 6c MPrintf() or sql
1b680 69 74 65 33 46 72 65 65 28 29 2e 0a 2a 2f 0a 73 ite3Free()..*/.s
1b690 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 truct sqlite3_vt
1b6a0 61 62 20 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c ab {. const sql
1b6b0 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f ite3_module *pMo
1b6c0 64 75 6c 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f dule; /* The mo
1b6d0 64 75 6c 65 20 66 6f 72 20 74 68 69 73 20 76 69 dule for this vi
1b6e0 72 74 75 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 rtual table */.
1b6f0 20 69 6e 74 20 6e 52 65 66 3b 20 20 20 20 20 20 int nRef;
1b700 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1b710 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61 /* Used interna
1b720 6c 6c 79 20 2a 2f 0a 20 20 63 68 61 72 20 2a 7a lly */. char *z
1b730 45 72 72 4d 73 67 3b 20 20 20 20 20 20 20 20 20 ErrMsg;
1b740 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f /* Erro
1b750 72 20 6d 65 73 73 61 67 65 20 66 72 6f 6d 20 73 r message from s
1b760 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 qlite3_mprintf()
1b770 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c */. /* Virtual
1b780 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 table implement
1b790 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 ations will typi
1b7a0 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 cally add additi
1b7b0 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d onal fields */.}
1b7c0 3b 0a 0a 2f 2a 20 45 76 65 72 79 20 6d 6f 64 75 ;../* Every modu
1b7d0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
1b7e0 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 n uses a subclas
1b7f0 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 s of the followi
1b800 6e 67 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 ng structure.**
1b810 74 6f 20 64 65 73 63 72 69 62 65 20 63 75 72 73 to describe curs
1b820 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74 20 69 ors that point i
1b830 6e 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 20 nto the virtual
1b840 74 61 62 6c 65 20 61 6e 64 20 61 72 65 20 75 73 table and are us
1b850 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74 68 ed.** to loop th
1b860 72 6f 75 67 68 20 74 68 65 20 76 69 72 74 75 61 rough the virtua
1b870 6c 20 74 61 62 6c 65 2e 20 20 43 75 72 73 6f 72 l table. Cursor
1b880 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 s are created us
1b890 69 6e 67 20 74 68 65 0a 2a 2a 20 78 4f 70 65 6e ing the.** xOpen
1b8a0 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 6d method of the m
1b8b0 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64 odule. Each mod
1b8c0 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ule implementati
1b8d0 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a on will define.*
1b8e0 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 * the content of
1b8f0 20 61 20 63 75 72 73 6f 72 20 73 74 72 75 63 74 a cursor struct
1b900 75 72 65 20 74 6f 20 73 75 69 74 20 69 74 73 20 ure to suit its
1b910 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a own needs..**.**
1b920 20 54 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 This superclass
1b930 20 65 78 69 73 74 73 20 69 6e 20 6f 72 64 65 72 exists in order
1b940 20 74 6f 20 64 65 66 69 6e 65 20 66 69 65 6c 64 to define field
1b950 73 20 6f 66 20 74 68 65 20 63 75 72 73 6f 72 20 s of the cursor
1b960 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d that.** are comm
1b970 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d on to all implem
1b980 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 entations..*/.st
1b990 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 ruct sqlite3_vta
1b9a0 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73 71 6c b_cursor {. sql
1b9b0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 ite3_vtab *pVtab
1b9c0 3b 20 20 20 20 20 20 2f 2a 20 56 69 72 74 75 61 ; /* Virtua
1b9d0 6c 20 74 61 62 6c 65 20 6f 66 20 74 68 69 73 20 l table of this
1b9e0 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 cursor */. /* V
1b9f0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 irtual table imp
1ba00 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c lementations wil
1ba10 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 l typically add
1ba20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 additional field
1ba30 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 54 s */.};../*.** T
1ba40 68 65 20 78 43 72 65 61 74 65 20 61 6e 64 20 78 he xCreate and x
1ba50 43 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64 73 20 Connect methods
1ba60 6f 66 20 61 20 6d 6f 64 75 6c 65 20 75 73 65 20 of a module use
1ba70 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 the following AP
1ba80 49 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72 65 20 I.** to declare
1ba90 74 68 65 20 66 6f 72 6d 61 74 20 28 74 68 65 20 the format (the
1baa0 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 61 74 79 names and dataty
1bab0 70 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d pes of the colum
1bac0 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20 76 69 ns) of.** the vi
1bad0 72 74 75 61 6c 20 74 61 62 6c 65 73 20 74 68 65 rtual tables the
1bae0 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a y implement..*/.
1baf0 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 65 63 6c int sqlite3_decl
1bb00 61 72 65 5f 76 74 61 62 28 73 71 6c 69 74 65 33 are_vtab(sqlite3
1bb10 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
1bb20 43 72 65 61 74 65 54 61 62 6c 65 29 3b 0a 0a 2f CreateTable);../
1bb30 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 *.** Virtual tab
1bb40 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64 65 20 les can provide
1bb50 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70 6c alternative impl
1bb60 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66 ementations of f
1bb70 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e unctions.** usin
1bb80 67 20 74 68 65 20 78 46 69 6e 64 46 75 6e 63 74 g the xFindFunct
1bb90 69 6f 6e 20 6d 65 74 68 6f 64 2e 20 20 42 75 74 ion method. But
1bba0 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 73 global versions
1bbb0 20 6f 66 20 74 68 6f 73 65 20 66 75 6e 63 74 69 of those functi
1bbc0 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69 73 ons.** must exis
1bbd0 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 62 65 t in order to be
1bbe0 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a overloaded..**.
1bbf0 2a 2a 20 54 68 69 73 20 41 50 49 20 6d 61 6b 65 ** This API make
1bc00 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61 6c 20 s sure a global
1bc10 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 75 6e version of a fun
1bc20 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70 61 72 ction with a par
1bc30 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20 ticular.** name
1bc40 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 and number of pa
1bc50 72 61 6d 65 74 65 72 73 20 65 78 69 73 74 73 2e rameters exists.
1bc60 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66 75 6e If no such fun
1bc70 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a 20 ction exists.**
1bc80 62 65 66 6f 72 65 20 74 68 69 73 20 41 50 49 20 before this API
1bc90 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65 77 is called, a new
1bca0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 72 65 function is cre
1bcb0 61 74 65 64 2e 20 20 54 68 65 20 69 6d 70 6c 65 ated. The imple
1bcc0 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 mentation.** of
1bcd0 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e the new function
1bce0 20 61 6c 77 61 79 73 20 63 61 75 73 65 73 20 61 always causes a
1bcf0 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f 20 62 n exception to b
1bd00 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a e thrown. So.**
1bd10 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f the new functio
1bd20 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20 66 6f n is not good fo
1bd30 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20 69 74 r anything by it
1bd40 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c 79 0a self. Its only.
1bd50 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20 74 6f ** purpose is to
1bd60 20 62 65 20 61 20 70 6c 61 63 65 2d 68 6f 6c 64 be a place-hold
1bd70 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 er function that
1bd80 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61 64 can be overload
1bd90 65 64 0a 2a 2a 20 62 79 20 76 69 72 74 75 61 6c ed.** by virtual
1bda0 20 74 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 tables..**.** T
1bdb0 68 69 73 20 41 50 49 20 73 68 6f 75 6c 64 20 62 his API should b
1bdc0 65 20 63 6f 6e 73 69 64 65 72 65 64 20 70 61 72 e considered par
1bdd0 74 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c t of the virtual
1bde0 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61 63 65 table interface
1bdf0 2c 0a 2a 2a 20 77 68 69 63 68 20 69 73 20 65 78 ,.** which is ex
1be00 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 73 perimental and s
1be10 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 ubject to change
1be20 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
1be30 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 _overload_functi
1be40 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e on(sqlite3*, con
1be50 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 st char *zFuncNa
1be60 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a me, int nArg);..
1be70 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 /*.** The interf
1be80 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 ace to the virtu
1be90 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 al-table mechani
1bea0 73 6d 20 64 65 66 69 6e 65 64 20 61 62 6f 76 65 sm defined above
1beb0 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 (back up.** to
1bec0 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b a comment remark
1bed0 61 62 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 ably similar to
1bee0 74 68 69 73 20 6f 6e 65 29 20 69 73 20 63 75 72 this one) is cur
1bef0 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 rently considere
1bf00 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 d.** to be exper
1bf10 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e imental. The in
1bf20 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 terface might ch
1bf30 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 ange in incompat
1bf40 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 ible ways..** If
1bf50 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c this is a probl
1bf60 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e em for you, do n
1bf70 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 ot use the inter
1bf80 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d face at this tim
1bf90 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 e..**.** When th
1bfa0 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 e virtual-table
1bfb0 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 6c 69 mechanism stabli
1bfc0 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 zes, we will dec
1bfd0 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 lare the.** inte
1bfe0 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 rface fixed, sup
1bff0 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 port it indefini
1c000 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 tely, and remove
1c010 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a this comment..*
1c020 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d *.****** EXPERIM
1c030 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 ENTAL - subject
1c040 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 to change withou
1c050 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a t notice *******
1c060 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a *******.*/../*.*
1c070 2a 20 43 41 50 49 33 52 45 46 3a 20 41 20 48 61 * CAPI3REF: A Ha
1c080 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e 20 ndle To An Open
1c090 42 4c 4f 42 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e BLOB.**.** An in
1c0a0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 66 6f stance of the fo
1c0b0 6c 6c 6f 77 69 6e 67 20 6f 70 61 71 75 65 20 73 llowing opaque s
1c0c0 74 72 75 63 74 75 72 65 20 69 73 20 75 73 65 64 tructure is used
1c0d0 20 74 6f 20 0a 2a 2a 20 72 65 70 72 65 73 65 6e to .** represen
1c0e0 74 20 61 6e 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 t an blob-handle
1c0f0 2e 20 20 41 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 . A blob-handle
1c100 20 69 73 20 63 72 65 61 74 65 64 20 62 79 0a 2a is created by.*
1c110 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f * [sqlite3_blob_
1c120 6f 70 65 6e 28 29 5d 20 61 6e 64 20 64 65 73 74 open()] and dest
1c130 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 royed by [sqlite
1c140 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 3_blob_close()].
1c150 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 .** The [sqlite3
1c160 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e _blob_read()] an
1c170 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f d [sqlite3_blob_
1c180 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66 61 write()] interfa
1c190 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 ces.** can be us
1c1a0 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 ed to read or wr
1c1b0 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 63 ite small subsec
1c1c0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 6c 6f tions of the blo
1c1d0 62 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 74 69 b..** The [sqlti
1c1e0 65 33 5f 62 6c 6f 62 5f 73 69 7a 65 28 29 5d 20 e3_blob_size()]
1c1f0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
1c200 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 s the size of th
1c210 65 0a 2a 2a 20 62 6c 6f 62 20 69 6e 20 62 79 74 e.** blob in byt
1c220 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 es..*/.typedef s
1c230 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62 6c truct sqlite3_bl
1c240 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b ob sqlite3_blob;
1c250 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1c260 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f : Open A BLOB Fo
1c270 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f r Incremental I/
1c280 4f 0a 2a 2a 0a 2a 2a 20 4f 70 65 6e 20 61 20 68 O.**.** Open a h
1c290 61 6e 64 6c 65 20 74 6f 20 74 68 65 20 62 6c 6f andle to the blo
1c2a0 62 20 6c 6f 63 61 74 65 64 20 69 6e 20 72 6f 77 b located in row
1c2b0 20 69 52 6f 77 2c 2c 20 63 6f 6c 75 6d 6e 20 7a iRow,, column z
1c2c0 43 6f 6c 75 6d 6e 2c 20 0a 2a 2a 20 74 61 62 6c Column, .** tabl
1c2d0 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61 74 61 e zTable in data
1c2e0 62 61 73 65 20 7a 44 62 2e 20 69 2e 65 2e 20 74 base zDb. i.e. t
1c2f0 68 65 20 73 61 6d 65 20 62 6c 6f 62 20 74 68 61 he same blob tha
1c300 74 20 77 6f 75 6c 64 0a 2a 2a 20 62 65 20 73 65 t would.** be se
1c310 6c 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a lected by:.**.**
1c320 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 <pre>.** SE
1c330 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f LECT zColumn FRO
1c340 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 M zDb.zTable WHE
1c350 52 45 20 72 6f 77 69 64 20 3d 20 69 52 6f 77 3b RE rowid = iRow;
1c360 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a .** </pre>.**.**
1c370 20 49 66 20 74 68 65 20 66 6c 61 67 73 20 70 61 If the flags pa
1c380 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a rameter is non-z
1c390 65 72 6f 2c 20 74 68 65 20 62 6c 6f 62 20 69 73 ero, the blob is
1c3a0 20 6f 70 65 6e 65 64 20 66 6f 72 20 0a 2a 2a 20 opened for .**
1c3b0 72 65 61 64 20 61 6e 64 20 77 72 69 74 65 20 61 read and write a
1c3c0 63 63 65 73 73 2e 20 49 66 20 69 74 20 69 73 20 ccess. If it is
1c3d0 7a 65 72 6f 2c 20 74 68 65 20 62 6c 6f 62 20 69 zero, the blob i
1c3e0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 s opened for rea
1c3f0 64 20 0a 2a 2a 20 61 63 63 65 73 73 2e 0a 2a 2a d .** access..**
1c400 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 .** On success,
1c410 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 [SQLITE_OK] is r
1c420 65 74 75 72 6e 65 64 20 61 6e 64 20 74 68 65 20 eturned and the
1c430 6e 65 77 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 new .** [sqlite3
1c440 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 20 68 61 6e _blob | blob han
1c450 64 6c 65 5d 20 69 73 20 77 72 69 74 74 65 6e 20 dle] is written
1c460 74 6f 20 2a 70 70 42 6c 6f 62 2e 0a 2a 2a 20 4f to *ppBlob..** O
1c470 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f therwise an erro
1c480 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e r code is return
1c490 65 64 20 61 6e 64 20 0a 2a 2a 20 61 6e 79 20 76 ed and .** any v
1c4a0 61 6c 75 65 20 77 72 69 74 74 65 6e 20 74 6f 20 alue written to
1c4b0 2a 70 70 42 6c 6f 62 20 73 68 6f 75 6c 64 20 6e *ppBlob should n
1c4c0 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 74 68 ot be used by th
1c4d0 65 20 63 61 6c 6c 65 72 2e 0a 2a 2a 20 54 68 69 e caller..** Thi
1c4e0 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 s function sets
1c4f0 74 68 65 20 64 61 74 61 62 61 73 65 2d 68 61 6e the database-han
1c500 64 6c 65 20 65 72 72 6f 72 20 63 6f 64 65 20 61 dle error code a
1c510 6e 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20 61 63 nd message.** ac
1c520 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73 71 cessible via [sq
1c530 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d lite3_errcode()]
1c540 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 and [sqlite3_er
1c550 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 rmsg()]..*/.int
1c560 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 sqlite3_blob_ope
1c570 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 n(. sqlite3*,.
1c580 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 const char *zDb
1c590 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a ,. const char *
1c5a0 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 zTable,. const
1c5b0 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 char *zColumn,.
1c5c0 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 69 52 sqlite_int64 iR
1c5d0 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c ow,. int flags,
1c5e0 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 . sqlite3_blob
1c5f0 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a **ppBlob.);../*.
1c600 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 43 6c ** CAPI3REF: Cl
1c610 6f 73 65 20 41 20 42 4c 4f 42 20 48 61 6e 64 6c ose A BLOB Handl
1c620 65 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 65 20 61 6e e.**.** Close an
1c630 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 62 open [sqlite3_b
1c640 6c 6f 62 20 7c 20 62 6c 6f 62 20 68 61 6e 64 6c lob | blob handl
1c650 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 e]..*/.int sqlit
1c660 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71 e3_blob_close(sq
1c670 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a lite3_blob *);..
1c680 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1c690 20 52 65 74 75 72 6e 20 54 68 65 20 53 69 7a 65 Return The Size
1c6a0 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 Of An Open BLOB
1c6b0 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 .**.** Return th
1c6c0 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73 20 e size in bytes
1c6d0 6f 66 20 74 68 65 20 62 6c 6f 62 20 61 63 63 65 of the blob acce
1c6e0 73 73 69 62 6c 65 20 76 69 61 20 74 68 65 20 6f ssible via the o
1c6f0 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 pen .** [sqlite3
1c700 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 61 6e _blob | blob-han
1c710 64 6c 65 5d 20 70 61 73 73 65 64 20 61 73 20 61 dle] passed as a
1c720 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2f 0a 69 n argument..*/.i
1c730 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f nt sqlite3_blob_
1c740 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 62 6c bytes(sqlite3_bl
1c750 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ob *);../*.** CA
1c760 50 49 33 52 45 46 3a 20 20 52 65 61 64 20 44 61 PI3REF: Read Da
1c770 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49 ta From A BLOB I
1c780 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a ncrementally.**.
1c790 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e ** This function
1c7a0 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 61 64 is used to read
1c7b0 20 64 61 74 61 20 66 72 6f 6d 20 61 6e 20 6f 70 data from an op
1c7c0 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f en .** [sqlite3_
1c7d0 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 61 6e 64 blob | blob-hand
1c7e0 6c 65 5d 20 69 6e 74 6f 20 61 20 63 61 6c 6c 65 le] into a calle
1c7f0 72 20 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 r supplied buffe
1c800 72 2e 0a 2a 2a 20 6e 20 62 79 74 65 73 20 6f 66 r..** n bytes of
1c810 20 64 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 data are copied
1c820 20 69 6e 74 6f 20 62 75 66 66 65 72 0a 2a 2a 20 into buffer.**
1c830 7a 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 6e 20 z from the open
1c840 62 6c 6f 62 2c 20 73 74 61 72 74 69 6e 67 20 61 blob, starting a
1c850 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 t offset iOffset
1c860 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 ..**.** On succe
1c870 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 ss, SQLITE_OK is
1c880 20 72 65 74 75 72 6e 65 64 2e 20 4f 74 68 65 72 returned. Other
1c890 77 69 73 65 2c 20 61 6e 20 0a 2a 2a 20 5b 53 51 wise, an .** [SQ
1c8a0 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 53 51 4c LITE_ERROR | SQL
1c8b0 69 74 65 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 ite error code]
1c8c0 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 or an.** [SQLITE
1c8d0 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 _IOERR_READ | ex
1c8e0 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 tended error cod
1c8f0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a e] is returned..
1c900 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 */.int sqlite3_b
1c910 6c 6f 62 5f 72 65 61 64 28 73 71 6c 69 74 65 33 lob_read(sqlite3
1c920 5f 62 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 2a 7a _blob *, void *z
1c930 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 , int n, int iOf
1c940 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 fset);../*.** CA
1c950 50 49 33 52 45 46 3a 20 20 57 72 69 74 65 20 44 PI3REF: Write D
1c960 61 74 61 20 49 6e 74 6f 20 41 20 42 4c 4f 42 20 ata Into A BLOB
1c970 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a Incrementally.**
1c980 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f .** This functio
1c990 6e 20 69 73 20 75 73 65 64 20 74 6f 20 77 72 69 n is used to wri
1c9a0 74 65 20 64 61 74 61 20 69 6e 74 6f 20 61 6e 20 te data into an
1c9b0 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 open .** [sqlite
1c9c0 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 61 3_blob | blob-ha
1c9d0 6e 64 6c 65 5d 20 66 72 6f 6d 20 61 20 75 73 65 ndle] from a use
1c9e0 72 20 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 r supplied buffe
1c9f0 72 2e 0a 2a 2a 20 6e 20 62 79 74 65 73 20 6f 66 r..** n bytes of
1ca00 20 64 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 data are copied
1ca10 20 66 72 6f 6d 20 74 68 65 20 62 75 66 66 65 72 from the buffer
1ca20 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 .** pointed to b
1ca30 79 20 7a 20 69 6e 74 6f 20 74 68 65 20 6f 70 65 y z into the ope
1ca40 6e 20 62 6c 6f 62 2c 20 73 74 61 72 74 69 6e 67 n blob, starting
1ca50 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73 at offset iOffs
1ca60 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 et..**.** If the
1ca70 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c [sqlite3_blob |
1ca80 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 70 61 blob-handle] pa
1ca90 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 ssed as the firs
1caa0 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 61 t argument.** wa
1cab0 73 20 6e 6f 74 20 6f 70 65 6e 65 64 20 66 6f 72 s not opened for
1cac0 20 77 72 69 74 69 6e 67 20 28 74 68 65 20 66 6c writing (the fl
1cad0 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f ags parameter to
1cae0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f [sqlite3_blob_o
1caf0 70 65 6e 28 29 5d 0a 2a 2a 2a 20 77 61 73 20 7a pen()].*** was z
1cb00 65 72 6f 29 2c 20 74 68 69 73 20 66 75 6e 63 74 ero), this funct
1cb10 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ion returns [SQL
1cb20 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a ITE_READONLY]..*
1cb30 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 *.** This functi
1cb40 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 on may only modi
1cb50 66 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 fy the contents
1cb60 6f 66 20 74 68 65 20 62 6c 6f 62 2c 20 69 74 20 of the blob, it
1cb70 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 is.** not possib
1cb80 6c 65 20 74 6f 20 69 6e 63 72 65 61 73 65 20 74 le to increase t
1cb90 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f he size of a blo
1cba0 62 20 75 73 69 6e 67 20 74 68 69 73 20 41 50 49 b using this API
1cbb0 2e 20 49 66 0a 2a 2a 20 6f 66 66 73 65 74 20 69 . If.** offset i
1cbc0 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 Offset is less t
1cbd0 68 61 6e 20 6e 20 62 79 74 65 73 20 66 72 6f 6d han n bytes from
1cbe0 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 the end of the
1cbf0 62 6c 6f 62 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 blob, .** [SQLIT
1cc00 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 E_ERROR] is retu
1cc10 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 rned and no data
1cc20 20 69 73 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a is written..**.
1cc30 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 53 ** On success, S
1cc40 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 QLITE_OK is retu
1cc50 72 6e 65 64 2e 20 4f 74 68 65 72 77 69 73 65 2c rned. Otherwise,
1cc60 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f an .** [SQLITE_
1cc70 45 52 52 4f 52 20 7c 20 53 51 4c 69 74 65 20 65 ERROR | SQLite e
1cc80 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e rror code] or an
1cc90 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 .** [SQLITE_IOER
1cca0 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 R_READ | extende
1ccb0 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 d error code] is
1ccc0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e returned..*/.in
1ccd0 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 t sqlite3_blob_w
1cce0 72 69 74 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f rite(sqlite3_blo
1ccf0 62 20 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 20 b *, const void
1cd00 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69 *z, int n, int i
1cd10 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 Offset);../*.**
1cd20 55 6e 64 6f 20 74 68 65 20 68 61 63 6b 20 74 68 Undo the hack th
1cd30 61 74 20 63 6f 6e 76 65 72 74 73 20 66 6c 6f 61 at converts floa
1cd40 74 69 6e 67 20 70 6f 69 6e 74 20 74 79 70 65 73 ting point types
1cd50 20 74 6f 20 69 6e 74 65 67 65 72 20 66 6f 72 0a to integer for.
1cd60 2a 2a 20 62 75 69 6c 64 73 20 6f 6e 20 70 72 6f ** builds on pro
1cd70 63 65 73 73 6f 72 73 20 77 69 74 68 6f 75 74 20 cessors without
1cd80 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 floating point s
1cd90 75 70 70 6f 72 74 2e 0a 2a 2f 0a 23 69 66 64 65 upport..*/.#ifde
1cda0 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c f SQLITE_OMIT_FL
1cdb0 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 75 OATING_POINT.# u
1cdc0 6e 64 65 66 20 64 6f 75 62 6c 65 0a 23 65 6e 64 ndef double.#end
1cdd0 69 66 0a 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c if..#ifdef __cpl
1cde0 75 73 70 6c 75 73 0a 7d 20 20 2f 2a 20 45 6e 64 usplus.} /* End
1cdf0 20 6f 66 20 74 68 65 20 27 65 78 74 65 72 6e 20 of the 'extern
1ce00 22 43 22 27 20 62 6c 6f 63 6b 20 2a 2f 0a 23 65 "C"' block */.#e
1ce10 6e 64 69 66 0a 23 65 6e 64 69 66 0a ndif.#endif.