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 38 20 32 30 30 37 2f in,v 1.218 2007/
05f0: 30 37 2f 31 39 20 31 32 3a 34 31 3a 34 30 20 64 07/19 12:41:40 d
0600: 72 68 20 45 78 70 20 24 0a 2a 2f 0a 23 69 66 6e rh Exp $.*/.#ifn
0610: 64 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a def _SQLITE3_H_.
0620: 23 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33 #define _SQLITE3
0630: 5f 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 _H_.#include <st
0640: 64 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e darg.h> /* N
0650: 65 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65 eeded for the de
0660: 66 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c finition of va_l
0670: 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 ist */../*.** Ma
0680: 6b 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63 ke sure we can c
0690: 61 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66 all this stuff f
06a0: 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 rom C++..*/.#ifd
06b0: 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 ef __cplusplus.e
06c0: 78 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 xtern "C" {.#end
06d0: 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 if../*.** Make s
06e0: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c ure these symbol
06f0: 73 20 77 68 65 72 65 20 6e 6f 74 20 64 65 66 69 s where not defi
0700: 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 ned by some prev
0710: 69 6f 75 73 20 68 65 61 64 65 72 0a 2a 2a 20 66 ious header.** f
0720: 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 ile..*/.#ifdef S
0730: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 QLITE_VERSION.#
0740: 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 undef SQLITE_VER
0750: 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 SION.#endif.#ifd
0760: 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f ef SQLITE_VERSIO
0770: 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 N_NUMBER.# undef
0780: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f SQLITE_VERSION_
0790: 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f NUMBER.#endif../
07a0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
07b0: 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 ompile-Time Libr
07c0: 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 ary Version Numb
07d0: 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 65 ers.**.** The ve
07e0: 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c rsion of the SQL
07f0: 69 74 65 20 6c 69 62 72 61 72 79 20 69 73 20 63 ite library is c
0800: 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 65 20 ontained in the
0810: 73 71 6c 69 74 65 33 2e 68 0a 2a 2a 20 68 65 61 sqlite3.h.** hea
0820: 64 65 72 20 66 69 6c 65 20 69 6e 20 61 20 23 64 der file in a #d
0830: 65 66 69 6e 65 20 6e 61 6d 65 64 20 53 51 4c 49 efine named SQLI
0840: 54 45 5f 56 45 52 53 49 4f 4e 2e 20 20 54 68 65 TE_VERSION. The
0850: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a SQLITE_VERSION.
0860: 2a 2a 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 ** macro resolve
0870: 73 20 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f s to a string co
0880: 6e 73 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 nstant..**.** Th
0890: 65 20 66 6f 72 6d 61 74 20 6f 66 20 74 68 65 20 e format of the
08a0: 76 65 72 73 69 6f 6e 20 73 74 72 69 6e 67 20 69 version string i
08b0: 73 20 22 58 2e 59 2e 5a 22 2c 20 77 68 65 72 65 s "X.Y.Z", where
08c0: 0a 2a 2a 20 58 20 69 73 20 74 68 65 20 6d 61 6a .** X is the maj
08d0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 or version numbe
08e0: 72 2c 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f r, Y is the mino
08f0: 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 r version number
0900: 20 61 6e 64 20 5a 0a 2a 2a 20 69 73 20 74 68 65 and Z.** is the
0910: 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e release number.
0920: 20 20 54 68 65 20 58 2e 59 2e 5a 20 6d 69 67 68 The X.Y.Z migh
0930: 74 20 62 65 20 66 6f 6c 6c 6f 77 65 64 20 62 79 t be followed by
0940: 20 22 61 6c 70 68 61 22 20 6f 72 20 22 62 65 74 "alpha" or "bet
0950: 61 22 2e 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 a"..** For examp
0960: 6c 65 20 22 33 2e 31 2e 31 62 65 74 61 22 2e 0a le "3.1.1beta"..
0970: 2a 2a 0a 2a 2a 20 54 68 65 20 58 20 76 61 6c 75 **.** The X valu
0980: 65 20 69 73 20 61 6c 77 61 79 73 20 33 20 69 6e e is always 3 in
0990: 20 53 51 4c 69 74 65 2e 20 20 54 68 65 20 58 20 SQLite. The X
09a0: 76 61 6c 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67 value only chang
09b0: 65 73 20 77 68 65 6e 0a 2a 2a 20 62 61 63 6b 77 es when.** backw
09c0: 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 ards compatibili
09d0: 74 79 20 69 73 20 62 72 6f 6b 65 6e 20 61 6e 64 ty is broken and
09e0: 20 77 65 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65 we intend to ne
09f0: 76 65 72 20 62 72 65 61 6b 0a 2a 2a 20 62 61 63 ver break.** bac
0a00: 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 kwards compatibi
0a10: 6c 69 74 79 2e 20 20 54 68 65 20 59 20 76 61 6c lity. The Y val
0a20: 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 ue only changes
0a30: 77 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 61 72 when.** there ar
0a40: 65 20 6d 61 6a 6f 72 20 66 65 61 74 75 72 65 20 e major feature
0a50: 65 6e 68 61 6e 63 65 6d 65 6e 74 73 20 74 68 61 enhancements tha
0a60: 74 20 61 72 65 20 66 6f 72 77 61 72 64 73 20 63 t are forwards c
0a70: 6f 6d 70 61 74 69 62 6c 65 0a 2a 2a 20 62 75 74 ompatible.** but
0a80: 20 6e 6f 74 20 62 61 63 6b 77 61 72 64 73 20 63 not backwards c
0a90: 6f 6d 70 61 74 69 62 6c 65 2e 20 20 54 68 65 20 ompatible. The
0aa0: 5a 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 Z value is incre
0ab0: 6d 65 6e 74 65 64 20 77 69 74 68 0a 2a 2a 20 65 mented with.** e
0ac0: 61 63 68 20 72 65 6c 65 61 73 65 20 62 75 74 20 ach release but
0ad0: 72 65 73 65 74 73 20 62 61 63 6b 20 74 6f 20 30 resets back to 0
0ae0: 20 77 68 65 6e 20 59 20 69 73 20 69 6e 63 72 65 when Y is incre
0af0: 6d 65 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 mented..**.** Th
0b00: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e e SQLITE_VERSION
0b10: 5f 4e 55 4d 42 45 52 20 69 73 20 61 6e 20 69 6e _NUMBER is an in
0b20: 74 65 67 65 72 20 77 69 74 68 20 74 68 65 20 76 teger with the v
0b30: 61 6c 75 65 20 0a 2a 2a 20 28 58 2a 31 30 30 30 alue .** (X*1000
0b40: 30 30 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 000 + Y*1000 + Z
0b50: 29 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 ). For example,
0b60: 66 6f 72 20 76 65 72 73 69 6f 6e 20 22 33 2e 31 for version "3.1
0b70: 2e 31 62 65 74 61 22 2c 20 0a 2a 2a 20 53 51 4c .1beta", .** SQL
0b80: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 ITE_VERSION_NUMB
0b90: 45 52 20 69 73 20 73 65 74 20 74 6f 20 33 30 30 ER is set to 300
0ba0: 31 30 30 31 2e 20 54 6f 20 64 65 74 65 63 74 20 1001. To detect
0bb0: 69 66 20 74 68 65 79 20 61 72 65 20 75 73 69 6e if they are usin
0bc0: 67 20 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e g .** version 3.
0bd0: 31 2e 31 20 6f 72 20 67 72 65 61 74 65 72 20 61 1.1 or greater a
0be0: 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2c 20 t compile time,
0bf0: 70 72 6f 67 72 61 6d 73 20 6d 61 79 20 75 73 65 programs may use
0c00: 20 74 68 65 20 74 65 73 74 20 0a 2a 2a 20 28 53 the test .** (S
0c10: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 QLITE_VERSION_NU
0c20: 4d 42 45 52 3e 3d 33 30 30 31 30 30 31 29 2e 0a MBER>=3001001)..
0c30: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
0c40: 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 [sqlite3_libvers
0c50: 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 ion()] and [sqli
0c60: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e te3_libversion_n
0c70: 75 6d 62 65 72 28 29 5d 2e 0a 2a 2f 0a 23 64 65 umber()]..*/.#de
0c80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 fine SQLITE_VERS
0c90: 49 4f 4e 20 20 20 20 20 20 20 20 20 22 33 2e 34 ION "3.4
0ca0: 2e 31 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .1".#define SQLI
0cb0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 TE_VERSION_NUMBE
0cc0: 52 20 33 30 30 34 30 30 31 0a 0a 2f 2a 0a 2a 2a R 3004001../*.**
0cd0: 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 CAPI3REF: Run-T
0ce0: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 ime Library Vers
0cf0: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a ion Numbers.**.*
0d00: 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
0d10: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 20 65 return values e
0d20: 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 74 68 65 quivalent to the
0d30: 20 68 65 61 64 65 72 20 63 6f 6e 73 74 61 6e 74 header constant
0d40: 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 s.** [SQLITE_VER
0d50: 53 49 4f 4e 5d 20 61 6e 64 20 5b 53 51 4c 49 54 SION] and [SQLIT
0d60: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 E_VERSION_NUMBER
0d70: 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 72 ]. The values r
0d80: 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 74 68 eturned.** by th
0d90: 69 73 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 is routines shou
0da0: 6c 64 20 6f 6e 6c 79 20 62 65 20 64 69 66 66 65 ld only be diffe
0db0: 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 68 65 rent from the he
0dc0: 61 64 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 69 ader values.** i
0dd0: 66 20 79 6f 75 20 63 6f 6d 70 69 6c 65 20 79 6f f you compile yo
0de0: 75 72 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 ur program using
0df0: 20 61 6e 20 73 71 6c 69 74 65 33 2e 68 20 68 65 an sqlite3.h he
0e00: 61 64 65 72 20 66 72 6f 6d 20 61 0a 2a 2a 20 64 ader from a.** d
0e10: 69 66 66 65 72 65 6e 74 20 76 65 72 73 69 6f 6e ifferent version
0e20: 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20 of SQLite that
0e30: 74 68 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 the version of t
0e40: 68 65 20 6c 69 62 72 61 72 79 20 79 6f 75 0a 2a he library you.*
0e50: 2a 20 6c 69 6e 6b 20 61 67 61 69 6e 73 74 2e 0a * link against..
0e60: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
0e70: 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 3_version[] stri
0e80: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 ng constant cont
0e90: 61 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 ains the text of
0ea0: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
0eb0: 56 45 52 53 49 4f 4e 5d 20 73 74 72 69 6e 67 2e VERSION] string.
0ec0: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 The sqlite3_li
0ed0: 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 bversion() funct
0ee0: 69 6f 6e 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 ion returns.** a
0ef0: 20 70 6f 69 6e 65 72 20 74 6f 20 74 68 65 20 73 poiner to the s
0f00: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d qlite3_version[]
0f10: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 string constant
0f20: 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 0a . The function.
0f30: 2a 2a 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 ** is provided f
0f40: 6f 72 20 44 4c 4c 20 75 73 65 72 73 20 77 68 6f or DLL users who
0f50: 20 63 61 6e 20 6f 6e 6c 79 20 61 63 63 65 73 73 can only access
0f60: 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 6e functions and n
0f70: 6f 74 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 ot.** constants
0f80: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 0a within the DLL..
0f90: 2a 2f 0a 65 78 74 65 72 6e 20 63 6f 6e 73 74 20 */.extern const
0fa0: 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 char sqlite3_ver
0fb0: 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 sion[];.const ch
0fc0: 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 ar *sqlite3_libv
0fd0: 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 69 6e ersion(void);.in
0fe0: 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 t sqlite3_libver
0ff0: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 sion_number(void
1000: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1010: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e EF: Database Con
1020: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a nection Handle.*
1030: 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 *.** Each open S
1040: 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 QLite database i
1050: 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 s represented by
1060: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
1070: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 0a 2a nstance of the.*
1080: 2a 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 * opaque structu
1090: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 re named "sqlite
10a0: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 3". It is usefu
10b0: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e l to think of an
10c0: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e sqlite3.** poin
10d0: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 ter as an object
10e0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f . The [sqlite3_
10f0: 6f 70 65 6e 5d 20 69 6e 74 65 72 66 61 63 65 20 open] interface
1100: 69 73 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 is its construct
1110: 6f 72 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 or.** and [sqlit
1120: 65 33 5f 63 6c 6f 73 65 5d 20 69 73 20 69 74 73 e3_close] is its
1130: 20 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 destructor. Th
1140: 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 ere are many oth
1150: 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a er interfaces.**
1160: 20 28 73 75 63 68 20 61 73 20 5b 73 71 6c 69 74 (such as [sqlit
1170: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 5d 2c 20 e3_prepare_v2],
1180: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
1190: 66 75 6e 63 74 69 6f 6e 5d 2c 20 61 6e 64 0a 2a function], and.*
11a0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f * [sqlite3_busy_
11b0: 74 69 6d 65 6f 75 74 5d 20 74 6f 20 6e 61 6d 65 timeout] to name
11c0: 20 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74 but three) that
11d0: 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 are methods on
11e0: 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 2e 0a this.** object..
11f0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
1200: 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 t sqlite3 sqlite
1210: 33 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 3;.../*.** CAPI3
1220: 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 REF: 64-Bit Inte
1230: 67 65 72 20 54 79 70 65 73 0a 2a 2a 0a 2a 2a 20 ger Types.**.**
1240: 53 6f 6d 65 20 63 6f 6d 70 69 6c 65 72 73 20 64 Some compilers d
1250: 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 74 68 o not support th
1260: 65 20 22 6c 6f 6e 67 20 6c 6f 6e 67 22 20 64 61 e "long long" da
1270: 74 61 74 79 70 65 2e 20 20 53 6f 20 77 65 20 68 tatype. So we h
1280: 61 76 65 0a 2a 2a 20 74 6f 20 64 6f 20 63 6f 6d ave.** to do com
1290: 70 69 6c 65 72 2d 73 70 65 63 69 66 69 63 20 74 piler-specific t
12a0: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 ypedefs for 64-b
12b0: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e it signed and un
12c0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e signed integers.
12d0: 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 .**.** Many SQLi
12e0: 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e te interface fun
12f0: 63 74 69 6f 6e 73 20 72 65 71 75 69 72 65 20 61 ctions require a
1300: 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 64-bit integer
1310: 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 arguments..** Th
1320: 6f 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 ose interfaces a
1330: 72 65 20 64 65 63 6c 61 72 65 64 20 75 73 69 6e re declared usin
1340: 67 20 74 68 69 73 20 74 79 70 65 64 65 66 2e 0a g this typedef..
1350: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 */.#ifdef SQLITE
1360: 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 _INT64_TYPE. ty
1370: 70 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 pedef SQLITE_INT
1380: 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 64_TYPE sqlite_i
1390: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 nt64;. typedef
13a0: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f unsigned SQLITE_
13b0: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 INT64_TYPE sqlit
13c0: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 e_uint64;.#elif
13d0: 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 defined(_MSC_VER
13e0: 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 ) || defined(__B
13f0: 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 ORLANDC__). typ
1400: 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c edef __int64 sql
1410: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 ite_int64;. typ
1420: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f edef unsigned __
1430: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e int64 sqlite_uin
1440: 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 t64;.#else. typ
1450: 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 edef long long i
1460: 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b nt sqlite_int64;
1470: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 . typedef unsig
1480: 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e ned long long in
1490: 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b t sqlite_uint64;
14a0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 49 .#endif../*.** I
14b0: 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 f compiling for
14c0: 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 a processor that
14d0: 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 lacks floating
14e0: 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a point support,.*
14f0: 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 * substitute int
1500: 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e eger for floatin
1510: 67 2d 70 6f 69 6e 74 0a 2a 2f 0a 23 69 66 64 65 g-point.*/.#ifde
1520: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c f SQLITE_OMIT_FL
1530: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 OATING_POINT.# d
1540: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c efine double sql
1550: 69 74 65 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 ite_int64.#endif
1560: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1570: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 : Closing A Data
1580: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a base Connection.
1590: 2a 2a 0a 2a 2a 20 43 61 6c 6c 20 74 68 69 73 20 **.** Call this
15a0: 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 function with a
15b0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 pointer to a str
15c0: 75 63 74 75 72 65 20 74 68 61 74 20 77 61 73 20 ucture that was
15d0: 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 72 65 previously.** re
15e0: 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c turned from [sql
15f0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 ite3_open()] and
1600: 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 the correspondi
1610: 6e 67 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c ng database will
1620: 20 62 79 0a 2a 2a 20 63 6c 6f 73 65 64 2e 0a 2a by.** closed..*
1630: 2a 0a 2a 2a 20 41 6c 6c 20 53 51 4c 20 73 74 61 *.** All SQL sta
1640: 74 65 6d 65 6e 74 73 20 70 72 65 70 61 72 65 64 tements prepared
1650: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
1660: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
1670: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
1680: 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6d 75 73 pare16_v2()] mus
1690: 74 20 62 65 20 64 65 73 74 72 6f 79 65 64 20 75 t be destroyed u
16a0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 sing [sqlite3_fi
16b0: 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 62 65 66 nalize()].** bef
16c0: 6f 72 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 ore this routine
16d0: 20 69 73 20 63 61 6c 6c 65 64 2e 20 4f 74 68 65 is called. Othe
16e0: 72 77 69 73 65 2c 20 53 51 4c 49 54 45 5f 42 55 rwise, SQLITE_BU
16f0: 53 59 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 SY is returned a
1700: 6e 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 nd the.** databa
1710: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 72 65 se connection re
1720: 6d 61 69 6e 73 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 mains open..*/.i
1730: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 nt sqlite3_close
1740: 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a (sqlite3 *);../*
1750: 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 .** The type for
1760: 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 a callback func
1770: 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 tion..** This is
1780: 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 legacy and depr
1790: 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 ecated. It is i
17a0: 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 ncluded for hist
17b0: 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 orical.** compat
17c0: 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e ibility and is n
17d0: 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a ot documented..*
17e0: 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a /.typedef int (*
17f0: 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b sqlite3_callback
1800: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 )(void*,int,char
1810: 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a **, char**);../*
1820: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e .** CAPI3REF: On
1830: 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 e-Step Query Exe
1840: 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 cution Interface
1850: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 .**.** This inte
1860: 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f rface is used to
1870: 20 64 6f 20 61 20 6f 6e 65 2d 74 69 6d 65 20 65 do a one-time e
1880: 76 61 6c 75 61 74 61 74 69 6f 6e 20 6f 66 20 7a valuatation of z
1890: 65 72 6f 0a 2a 2a 20 6f 72 20 6d 6f 72 65 20 53 ero.** or more S
18a0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 QL statements.
18b0: 55 54 46 2d 38 20 74 65 78 74 20 6f 66 20 74 68 UTF-8 text of th
18c0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 e SQL statements
18d0: 20 74 6f 0a 2a 2a 20 62 65 20 65 76 61 6c 75 74 to.** be evalut
18e0: 65 64 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 ed is passed in
18f0: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 as the second pa
1900: 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 73 74 rameter. The st
1910: 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 72 65 20 atements.** are
1920: 70 72 65 70 61 72 65 64 20 6f 6e 65 20 62 79 20 prepared one by
1930: 6f 6e 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 one using [sqlit
1940: 65 33 5f 70 72 65 70 61 72 65 28 29 5d 2c 20 65 e3_prepare()], e
1950: 76 61 6c 75 61 74 65 64 0a 2a 2a 20 75 73 69 6e valuated.** usin
1960: 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 g [sqlite3_step(
1970: 29 5d 2c 20 74 68 65 6e 20 64 65 73 74 72 6f 79 )], then destroy
1980: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ed using [sqlite
1990: 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 3_finalize()]..*
19a0: 2a 0a 2a 2a 20 49 66 20 6f 6e 65 20 6f 72 20 6d *.** If one or m
19b0: 6f 72 65 20 6f 66 20 74 68 65 20 53 51 4c 20 73 ore of the SQL s
19c0: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 71 75 tatements are qu
19d0: 65 72 69 65 73 2c 20 74 68 65 6e 0a 2a 2a 20 74 eries, then.** t
19e0: 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 he callback func
19f0: 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 tion specified b
1a00: 79 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 y the 3rd parame
1a10: 74 65 72 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 ter is.** invoke
1a20: 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 d once for each
1a30: 72 6f 77 20 6f 66 20 74 68 65 20 71 75 65 72 79 row of the query
1a40: 20 72 65 73 75 6c 74 2e 20 20 54 68 69 73 20 63 result. This c
1a50: 61 6c 6c 62 61 63 6b 0a 2a 2a 20 73 68 6f 75 6c allback.** shoul
1a60: 64 20 6e 6f 72 6d 61 6c 6c 79 20 72 65 74 75 72 d normally retur
1a70: 6e 20 30 2e 20 20 49 66 20 74 68 65 20 63 61 6c n 0. If the cal
1a80: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 lback returns a
1a90: 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 76 61 6c 75 non-zero.** valu
1aa0: 65 20 74 68 65 6e 20 74 68 65 20 71 75 65 72 79 e then the query
1ab0: 20 69 73 20 61 62 6f 72 74 65 64 2c 20 61 6c 6c is aborted, all
1ac0: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 subsequent SQL
1ad0: 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 72 statements.** ar
1ae0: 65 20 73 6b 69 70 70 65 64 20 61 6e 64 20 74 68 e skipped and th
1af0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 e sqlite3_exec()
1b00: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e function return
1b10: 73 20 74 68 65 20 53 51 4c 49 54 45 5f 41 42 4f s the SQLITE_ABO
1b20: 52 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 34 74 RT..**.** The 4t
1b30: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
1b40: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 his interface is
1b50: 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f an arbitrary po
1b60: 69 6e 74 65 72 20 74 68 61 74 20 69 73 0a 2a 2a inter that is.**
1b70: 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 passed through
1b80: 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 to the callback
1b90: 66 75 6e 63 74 69 6f 6e 20 61 73 20 69 74 73 20 function as its
1ba0: 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e first parameter.
1bb0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 32 6e 64 20 70 .**.** The 2nd p
1bc0: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
1bd0: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
1be0: 6e 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 n is the number
1bf0: 6f 66 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 69 6e of.** columns in
1c00: 20 74 68 65 20 71 75 65 72 79 20 72 65 73 75 6c the query resul
1c10: 74 2e 20 20 54 68 65 20 33 72 64 20 70 61 72 61 t. The 3rd para
1c20: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c meter to the cal
1c30: 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 61 6e 20 61 lback.** is an a
1c40: 72 72 61 79 20 6f 66 20 73 74 72 69 6e 67 73 20 rray of strings
1c50: 68 6f 6c 64 69 6e 67 20 74 68 65 20 76 61 6c 75 holding the valu
1c60: 65 73 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 es for each colu
1c70: 6d 6e 0a 2a 2a 20 61 73 20 65 78 74 72 61 63 74 mn.** as extract
1c80: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ed using [sqlite
1c90: 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 3_column_text()]
1ca0: 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 ..** The 4th par
1cb0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 ameter to the ca
1cc0: 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 llback is an arr
1cd0: 61 79 20 6f 66 20 73 74 72 69 6e 67 73 0a 2a 2a ay of strings.**
1ce0: 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e 67 20 obtained using
1cf0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
1d00: 6e 61 6d 65 28 29 5d 20 61 6e 64 20 68 6f 6c 64 name()] and hold
1d10: 69 6e 67 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 ing.** the names
1d20: 20 6f 66 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e of each column.
1d30: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 .**.** The callb
1d40: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 ack function may
1d50: 20 62 65 20 4e 55 4c 4c 2c 20 65 76 65 6e 20 66 be NULL, even f
1d60: 6f 72 20 71 75 65 72 69 65 73 2e 20 20 41 20 4e or queries. A N
1d70: 55 4c 4c 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 ULL.** callback
1d80: 69 73 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 2e is not an error.
1d90: 20 20 49 74 20 6a 75 73 74 20 6d 65 61 6e 73 20 It just means
1da0: 74 68 61 74 20 6e 6f 20 63 61 6c 6c 62 61 63 6b that no callback
1db0: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f .** will be invo
1dc0: 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e ked..**.** If an
1dd0: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 error occurs wh
1de0: 69 6c 65 20 70 61 72 73 69 6e 67 20 6f 72 20 65 ile parsing or e
1df0: 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 valuating the SQ
1e00: 4c 20 28 62 75 74 0a 2a 2a 20 6e 6f 74 20 77 68 L (but.** not wh
1e10: 69 6c 65 20 65 78 65 63 75 74 69 6e 67 20 74 68 ile executing th
1e20: 65 20 63 61 6c 6c 62 61 63 6b 29 20 74 68 65 6e e callback) then
1e30: 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 an appropriate
1e40: 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 error.** message
1e50: 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f is written into
1e60: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 memory obtained
1e70: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
1e80: 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 0a 2a 2a 20 alloc()] and.**
1e90: 2a 65 72 72 6d 73 67 20 69 73 20 6d 61 64 65 20 *errmsg is made
1ea0: 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 61 74 to point to that
1eb0: 20 6d 65 73 73 61 67 65 2e 20 20 54 68 65 20 63 message. The c
1ec0: 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a alling function.
1ed0: 2a 2a 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c ** is responsibl
1ee0: 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68 e for freeing th
1ef0: 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 68 6f e memory that ho
1f00: 6c 64 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a lds the error.**
1f10: 20 6d 65 73 73 61 67 65 2e 20 20 20 55 73 65 20 message. Use
1f20: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
1f30: 20 66 6f 72 20 74 68 69 73 2e 20 20 49 66 20 65 for this. If e
1f40: 72 72 6d 73 67 3d 3d 4e 55 4c 4c 2c 0a 2a 2a 20 rrmsg==NULL,.**
1f50: 74 68 65 6e 20 6e 6f 20 65 72 72 6f 72 20 6d 65 then no error me
1f60: 73 73 61 67 65 20 69 73 20 65 76 65 72 20 77 72 ssage is ever wr
1f70: 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 itten..**.** The
1f80: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 return value is
1f90: 20 69 73 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 is SQLITE_OK if
1fa0: 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 65 72 there are no er
1fb0: 72 6f 72 73 20 61 6e 64 0a 2a 2a 20 73 6f 6d 65 rors and.** some
1fc0: 20 6f 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f other [SQLITE_O
1fd0: 4b 20 7c 20 72 65 74 75 72 6e 20 63 6f 64 65 5d K | return code]
1fe0: 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 if there is an
1ff0: 65 72 72 6f 72 2e 20 20 0a 2a 2a 20 54 68 65 20 error. .** The
2000: 70 61 72 74 69 63 75 6c 61 72 20 72 65 74 75 72 particular retur
2010: 6e 20 76 61 6c 75 65 20 64 65 70 65 6e 64 73 20 n value depends
2020: 6f 6e 20 74 68 65 20 74 79 70 65 20 6f 66 20 65 on the type of e
2030: 72 72 6f 72 2e 20 0a 2a 2a 0a 2a 2f 0a 69 6e 74 rror. .**.*/.int
2040: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 sqlite3_exec(.
2050: 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 sqlite3*,
2060: 20 20 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 2f 2a 20 41 /* A
2080: 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 n open database
2090: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
20a0: 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 *sql,
20b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
20c0: 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 /* SQL to be eva
20d0: 6c 75 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 luted */. int (
20e0: 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a *callback)(void*
20f0: 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 ,int,char**,char
2100: 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 **), /* Callbac
2110: 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 k function */.
2120: 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 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 2f 2a 20 31 73 /* 1s
2150: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 t argument to ca
2160: 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 llback */. char
2170: 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 **errmsg
2180: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2190: 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 /* Error
21a0: 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 msg written here
21b0: 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.);../*.** CA
21c0: 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 PI3REF: Result C
21d0: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 odes.** KEYWORDS
21e0: 3a 20 53 51 4c 49 54 45 5f 4f 4b 0a 2a 2a 0a 2a : SQLITE_OK.**.*
21f0: 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 * Many SQLite fu
2200: 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 nctions return a
2210: 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 n integer result
2220: 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 code from the s
2230: 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 61 62 6f 76 et shown.** abov
2240: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e e in order to in
2250: 64 69 63 61 74 65 73 20 73 75 63 63 65 73 73 20 dicates success
2260: 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a or failure..**.*
2270: 2a 20 54 68 65 20 72 65 73 75 6c 74 20 63 6f 64 * The result cod
2280: 65 73 20 61 62 6f 76 65 20 61 72 65 20 74 68 65 es above are the
2290: 20 6f 6e 6c 79 20 6f 6e 65 73 20 72 65 74 75 72 only ones retur
22a0: 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e ned by SQLite in
22b0: 20 69 74 73 0a 2a 2a 20 64 65 66 61 75 6c 74 20 its.** default
22c0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2e 20 20 configuration.
22d0: 48 6f 77 65 76 65 72 2c 20 74 68 65 20 5b 73 71 However, the [sq
22e0: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 lite3_extended_r
22f0: 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 0a 2a esult_codes()].*
2300: 2a 20 41 50 49 20 63 61 6e 20 62 65 20 75 73 65 * API can be use
2310: 64 20 74 6f 20 73 65 74 20 61 20 64 61 74 61 62 d to set a datab
2320: 61 73 65 20 63 6f 6e 6e 65 63 74 6f 69 6e 20 74 ase connectoin t
2330: 6f 20 72 65 74 75 72 6e 20 6d 6f 72 65 20 64 65 o return more de
2340: 74 61 69 6c 65 64 0a 2a 2a 20 72 65 73 75 6c 74 tailed.** result
2350: 20 63 6f 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 codes..**.** Se
2360: 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f e also: [SQLITE_
2370: 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 IOERR_READ | ext
2380: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
2390: 65 73 5d 0a 2a 2a 0a 2a 2f 0a 23 64 65 66 69 6e es].**.*/.#defin
23a0: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 e SQLITE_OK
23b0: 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 0 /* Suc
23c0: 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a cessful result *
23d0: 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f /./* beginning-o
23e0: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f f-error-codes */
23f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2400: 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 ERROR 1
2410: 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 /* SQL error or
2420: 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 missing databas
2430: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e */.#define SQL
2440: 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 ITE_INTERNAL
2450: 20 32 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2 /* NOT USED
2460: 2e 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 . Internal logic
2470: 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 error in SQLite
2480: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
2490: 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 TE_PERM
24a0: 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 3 /* Access pe
24b0: 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 rmission denied
24c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
24d0: 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 E_ABORT 4
24e0: 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 /* Callback r
24f0: 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 outine requested
2500: 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 an abort */.#de
2510: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 fine SQLITE_BUSY
2520: 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 5 /*
2530: 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c The database fil
2540: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 e is locked */.#
2550: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f define SQLITE_LO
2560: 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20 2f CKED 6 /
2570: 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 * A table in the
2580: 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 database is loc
2590: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ked */.#define S
25a0: 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 QLITE_NOMEM
25b0: 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 7 /* A mall
25c0: 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 oc() failed */.#
25d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 define SQLITE_RE
25e0: 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f ADONLY 8 /
25f0: 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 * Attempt to wri
2600: 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 te a readonly da
2610: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e tabase */.#defin
2620: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 e SQLITE_INTERRU
2630: 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 PT 9 /* Ope
2640: 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 ration terminate
2650: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 d by sqlite3_int
2660: 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 errupt()*/.#defi
2670: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 ne SQLITE_IOERR
2680: 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 10 /* So
2690: 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 me kind of disk
26a0: 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 I/O error occurr
26b0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ed */.#define SQ
26c0: 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 LITE_CORRUPT
26d0: 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 11 /* The dat
26e0: 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 abase disk image
26f0: 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f is malformed */
2700: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2710: 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 NOTFOUND 12
2720: 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 /* NOT USED. Ta
2730: 62 6c 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f ble or record no
2740: 74 20 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 t found */.#defi
2750: 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 ne SQLITE_FULL
2760: 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 13 /* In
2770: 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 sertion failed b
2780: 65 63 61 75 73 65 20 64 61 74 61 62 61 73 65 20 ecause database
2790: 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 is full */.#defi
27a0: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 ne SQLITE_CANTOP
27b0: 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e EN 14 /* Un
27c0: 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 able to open the
27d0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a database file *
27e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
27f0: 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 _PROTOCOL 15
2800: 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 44 /* NOT USED. D
2810: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f atabase lock pro
2820: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 tocol error */.#
2830: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d define SQLITE_EM
2840: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f PTY 16 /
2850: 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d * Database is em
2860: 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 pty */.#define S
2870: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 QLITE_SCHEMA
2880: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 17 /* The da
2890: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 tabase schema ch
28a0: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 anged */.#define
28b0: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 SQLITE_TOOBIG
28c0: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 18 /* Stri
28d0: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 ng or BLOB excee
28e0: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f ds size limit */
28f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2900: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 CONSTRAINT 19
2910: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f /* Abort due to
2920: 20 63 6f 6e 74 72 61 69 6e 74 20 76 69 6f 6c 61 contraint viola
2930: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 tion */.#define
2940: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 SQLITE_MISMATCH
2950: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 20 /* Data
2960: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f type mismatch */
2970: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2980: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 MISUSE 21
2990: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 /* Library used
29a0: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a incorrectly */.
29b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e #define SQLITE_N
29c0: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 OLFS 22
29d0: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 /* Uses OS featu
29e0: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 res not supporte
29f0: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 d on host */.#de
2a00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 fine SQLITE_AUTH
2a10: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 23 /*
2a20: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 Authorization de
2a30: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 nied */.#define
2a40: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 SQLITE_FORMAT
2a50: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 24 /* Auxil
2a60: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f iary database fo
2a70: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 rmat error */.#d
2a80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e efine SQLITE_RAN
2a90: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a GE 25 /*
2aa0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 2nd parameter t
2ab0: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f o sqlite3_bind o
2ac0: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 ut of range */.#
2ad0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f define SQLITE_NO
2ae0: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f TADB 26 /
2af0: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 * File opened th
2b00: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 at is not a data
2b10: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 base file */.#de
2b20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 fine SQLITE_ROW
2b30: 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 100 /*
2b40: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 sqlite3_step() h
2b50: 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 as another row r
2b60: 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 eady */.#define
2b70: 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 SQLITE_DONE
2b80: 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 101 /* sqlit
2b90: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 e3_step() has fi
2ba0: 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 nished executing
2bb0: 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 */./* end-of-er
2bc0: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a ror-codes */../*
2bd0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 .** CAPI3REF: Ex
2be0: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f tended Result Co
2bf0: 64 65 73 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 des.**.** In its
2c00: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 default configu
2c10: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 ration, SQLite A
2c20: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 PI routines retu
2c30: 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 rn one of 26 int
2c40: 65 67 65 72 0a 2a 2a 20 72 65 73 75 6c 74 20 63 eger.** result c
2c50: 6f 64 65 73 20 64 65 73 63 72 69 62 65 64 20 61 odes described a
2c60: 74 20 72 65 73 75 6c 74 2d 63 6f 64 65 73 2e 20 t result-codes.
2c70: 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 However, experi
2c80: 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 ence has shown t
2c90: 68 61 74 0a 2a 2a 20 6d 61 6e 79 20 6f 66 20 74 hat.** many of t
2ca0: 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 hese result code
2cb0: 73 20 61 72 65 20 74 6f 6f 20 63 6f 75 72 73 65 s are too course
2cc0: 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 -grained. They
2cd0: 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 do not provide a
2ce0: 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d s.** much inform
2cf0: 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 ation about prob
2d00: 6c 65 6d 73 20 61 73 20 75 73 65 72 73 20 6d 69 lems as users mi
2d10: 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e ght like. In an
2d20: 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 effort to.** ad
2d30: 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 dress this, newe
2d40: 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 r versions of SQ
2d50: 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e Lite (version 3.
2d60: 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 3.8 and later) i
2d70: 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 nclude.** suppor
2d80: 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c t for additional
2d90: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 result codes th
2da0: 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 at provide more
2db0: 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 detailed informa
2dc0: 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 tion.** about er
2dd0: 72 6f 72 73 2e 20 20 54 68 65 20 65 78 74 65 6e rors. The exten
2de0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
2df0: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 28 6f 72 are enabled (or
2e00: 20 64 69 73 61 62 6c 65 64 29 20 66 6f 72 20 0a disabled) for .
2e10: 2a 2a 20 65 61 63 68 20 64 61 74 61 62 61 73 65 ** each database
2e20: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 .** connection u
2e30: 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 sing the [sqlite
2e40: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 3_extended_resul
2e50: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a t_codes()] API..
2e60: 2a 2a 20 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 ** .** Some of t
2e70: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 he available ext
2e80: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
2e90: 65 73 20 61 72 65 20 6c 69 73 74 65 64 20 61 62 es are listed ab
2ea0: 6f 76 65 2e 0a 2a 2a 20 57 65 20 65 78 70 65 63 ove..** We expec
2eb0: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 t the number of
2ec0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
2ed0: 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 codes will be ex
2ee0: 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d pand.** over tim
2ef0: 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 e. Software tha
2f00: 74 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 t uses extended
2f10: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f result codes sho
2f20: 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f uld expect.** to
2f30: 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 see new result
2f40: 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 codes in future
2f50: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 releases of SQLi
2f60: 74 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 73 te..** .** The s
2f70: 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 66 6f 72 ymbolic name for
2f80: 20 61 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 an extended res
2f90: 75 6c 74 20 63 6f 64 65 20 61 6c 77 61 79 73 20 ult code always
2fa0: 63 6f 6e 74 61 69 6e 73 20 61 20 72 65 6c 61 74 contains a relat
2fb0: 65 64 0a 2a 2a 20 70 72 69 6d 61 72 79 20 72 65 ed.** primary re
2fc0: 73 75 6c 74 20 63 6f 64 65 20 61 73 20 61 20 70 sult code as a p
2fd0: 72 65 66 69 78 2e 20 20 50 72 69 6d 61 72 79 20 refix. Primary
2fe0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 63 6f 6e result codes con
2ff0: 74 61 69 6e 20 61 20 73 69 6e 67 6c 65 0a 2a 2a tain a single.**
3000: 20 22 5f 22 20 63 68 61 72 61 63 74 65 72 2e 20 "_" character.
3010: 20 45 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 Extended result
3020: 20 63 6f 64 65 73 20 63 6f 6e 74 61 69 6e 20 74 codes contain t
3030: 77 6f 20 6f 72 20 6d 6f 72 65 20 22 5f 22 20 63 wo or more "_" c
3040: 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 54 68 haracters..** Th
3050: 65 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 e numeric value
3060: 6f 66 20 61 6e 20 65 78 74 65 6e 64 65 64 20 72 of an extended r
3070: 65 73 75 6c 74 20 63 6f 64 65 20 63 61 6e 20 62 esult code can b
3080: 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 69 e converted to i
3090: 74 73 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 ts.** correspond
30a0: 69 6e 67 20 70 72 69 6d 61 72 79 20 72 65 73 75 ing primary resu
30b0: 6c 74 20 63 6f 64 65 20 62 79 20 6d 61 73 6b 69 lt code by maski
30c0: 6e 67 20 6f 66 66 20 74 68 65 20 6c 6f 77 65 72 ng off the lower
30d0: 20 38 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 8 bytes..**.**
30e0: 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 The SQLITE_OK re
30f0: 73 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e sult code will n
3100: 65 76 65 72 20 62 65 20 65 78 74 65 6e 64 65 64 ever be extended
3110: 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 . It will alway
3120: 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20 s.** be exactly
3130: 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 zero..*/.#define
3140: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 SQLITE_IOERR_RE
3150: 41 44 20 20 20 20 20 20 20 20 20 20 28 53 51 4c AD (SQL
3160: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c ITE_IOERR | (1<<
3170: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
3180: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 TE_IOERR_SHORT_R
3190: 45 41 44 20 20 20 20 28 53 51 4c 49 54 45 5f 49 EAD (SQLITE_I
31a0: 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 OERR | (2<<8)).#
31b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
31c0: 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 ERR_WRITE
31d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
31e0: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (3<<8)).#defin
31f0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 e SQLITE_IOERR_F
3200: 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 SYNC (SQ
3210: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c LITE_IOERR | (4<
3220: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
3230: 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 ITE_IOERR_DIR_FS
3240: 59 4e 43 20 20 20 20 20 28 53 51 4c 49 54 45 5f YNC (SQLITE_
3250: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a IOERR | (5<<8)).
3260: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
3270: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 OERR_TRUNCATE
3280: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
3290: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 | (6<<8)).#defi
32a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
32b0: 46 53 54 41 54 20 20 20 20 20 20 20 20 20 28 53 FSTAT (S
32c0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 QLITE_IOERR | (7
32d0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
32e0: 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 LITE_IOERR_UNLOC
32f0: 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 K (SQLITE
3300: 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 _IOERR | (8<<8))
3310: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3320: 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 IOERR_RDLOCK
3330: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
3340: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 R | (9<<8)).#def
3350: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
3360: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 28 _DELETE (
3370: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
3380: 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 10<<8)).#define
3390: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f SQLITE_IOERR_BLO
33a0: 43 4b 45 44 20 20 20 20 20 20 20 28 53 51 4c 49 CKED (SQLI
33b0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c TE_IOERR | (11<<
33c0: 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 8))../*.** CAPI3
33d0: 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 REF: Enable Or D
33e0: 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 isable Extended
33f0: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a Result Codes.**.
3400: 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
3410: 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 enables or disab
3420: 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 les the.** [SQLI
3430: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 TE_IOERR_READ |
3440: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
3450: 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 2e 0a codes] feature..
3460: 2a 2a 20 42 79 20 64 65 66 61 75 6c 74 2c 20 53 ** By default, S
3470: 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e QLite API routin
3480: 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 es return one of
3490: 20 6f 6e 6c 79 20 32 36 20 69 6e 74 65 67 65 72 only 26 integer
34a0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c .** [SQLITE_OK |
34b0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 result codes].
34c0: 20 57 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 When extended r
34d0: 65 73 75 6c 74 20 63 6f 64 65 73 0a 2a 2a 20 61 esult codes.** a
34e0: 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 74 68 re enabled by th
34f0: 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 65 20 is routine, the
3500: 72 65 70 65 74 6f 69 72 65 20 6f 66 20 72 65 73 repetoire of res
3510: 75 6c 74 20 63 6f 64 65 73 20 63 61 6e 20 62 65 ult codes can be
3520: 0a 2a 2a 20 6d 75 63 68 20 6c 61 72 67 65 72 20 .** much larger
3530: 61 6e 64 20 63 61 6e 20 28 68 6f 70 65 66 75 6c and can (hopeful
3540: 6c 79 29 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 ly) provide more
3550: 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d detailed inform
3560: 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 74 ation.** about t
3570: 68 65 20 63 61 75 73 65 20 6f 66 20 61 6e 20 65 he cause of an e
3580: 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 rror..**.** The
3590: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
35a0: 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 76 61 6c is a boolean val
35b0: 75 65 20 74 68 61 74 20 74 75 72 6e 73 20 65 78 ue that turns ex
35c0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a tended result.**
35d0: 20 63 6f 64 65 73 20 6f 6e 20 61 6e 64 20 6f 66 codes on and of
35e0: 66 2e 20 20 45 78 74 65 6e 64 65 64 20 72 65 73 f. Extended res
35f0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6f 66 ult codes are of
3600: 66 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 f by default for
3610: 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f .** backwards co
3620: 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 mpatibility with
3630: 20 6f 6c 64 65 72 20 76 65 72 73 69 6f 6e 73 20 older versions
3640: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e of SQLite..*/.in
3650: 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 t sqlite3_extend
3660: 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 ed_result_codes(
3670: 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e sqlite3*, int on
3680: 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 off);../*.** CAP
3690: 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 I3REF: Last Inse
36a0: 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 45 rt Rowid.**.** E
36b0: 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 ach entry in an
36c0: 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 SQLite table has
36d0: 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 a unique 64-bit
36e0: 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 signed integer
36f0: 6b 65 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 74 68 key.** called th
3700: 65 20 22 72 6f 77 69 64 22 2e 20 54 68 65 20 72 e "rowid". The r
3710: 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 owid is always a
3720: 76 61 69 6c 61 62 6c 65 20 61 73 20 61 6e 20 75 vailable as an u
3730: 6e 64 65 63 6c 61 72 65 64 0a 2a 2a 20 63 6f 6c ndeclared.** col
3740: 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c umn named ROWID,
3750: 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f OID, or _ROWID_
3760: 2e 20 20 49 66 20 74 68 65 20 74 61 62 6c 65 20 . If the table
3770: 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 0a has a column of.
3780: 2a 2a 20 74 79 70 65 20 49 4e 54 45 47 45 52 20 ** type INTEGER
3790: 50 52 49 4d 41 52 59 20 4b 45 59 20 74 68 65 6e PRIMARY KEY then
37a0: 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 that column is
37b0: 61 6e 6f 74 68 65 72 20 61 6e 20 61 6c 69 61 73 another an alias
37c0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 72 6f 77 69 for the.** rowi
37d0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f d..**.** This ro
37e0: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 utine returns th
37f0: 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 6d e rowid of the m
3800: 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 ost recent INSER
3810: 54 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 64 61 T into.** the da
3820: 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 tabase from the
3830: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
3840: 69 6f 6e 20 67 69 76 65 6e 20 69 6e 20 74 68 65 ion given in the
3850: 20 66 69 72 73 74 20 0a 2a 2a 20 61 72 67 75 6d first .** argum
3860: 65 6e 74 2e 20 20 49 66 20 6e 6f 20 69 6e 73 65 ent. If no inse
3870: 72 74 73 20 68 61 76 65 20 65 76 65 72 20 6f 63 rts have ever oc
3880: 63 75 72 72 65 64 20 6f 6e 20 74 68 69 73 20 64 curred on this d
3890: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 atabase.** conne
38a0: 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 ction, zero is r
38b0: 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 eturned..**.** I
38c0: 66 20 61 6e 20 49 4e 53 45 52 54 20 6f 63 63 75 f an INSERT occu
38d0: 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 rs within a trig
38e0: 67 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 6f ger, then the ro
38f0: 77 69 64 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6e wid of the.** in
3900: 73 65 72 74 65 64 20 72 6f 77 20 69 73 20 72 65 serted row is re
3910: 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 turned by this r
3920: 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 outine as long a
3930: 73 20 74 68 65 20 74 72 69 67 67 65 72 0a 2a 2a s the trigger.**
3940: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 42 75 is running. Bu
3950: 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 t once the trigg
3960: 65 72 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 er terminates, t
3970: 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
3980: 64 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 d.** by this rou
3990: 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 tine reverts to
39a0: 74 68 65 20 6c 61 73 74 20 76 61 6c 75 65 20 69 the last value i
39b0: 6e 73 65 72 74 65 64 20 62 65 66 6f 72 65 20 74 nserted before t
39c0: 68 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 66 69 he.** trigger fi
39d0: 72 65 64 2e 0a 2a 2f 0a 73 71 6c 69 74 65 5f 69 red..*/.sqlite_i
39e0: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 nt64 sqlite3_las
39f0: 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 t_insert_rowid(s
3a00: 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
3a10: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 CAPI3REF: Count
3a20: 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 The Number Of R
3a30: 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a ows Modified.**.
3a40: 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e ** This function
3a50: 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
3a60: 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 ber of database
3a70: 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63 rows that were c
3a80: 68 61 6e 67 65 64 0a 2a 2a 20 28 6f 72 20 69 6e hanged.** (or in
3a90: 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 serted or delete
3aa0: 64 29 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 d) by the most r
3ab0: 65 63 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d ecent SQL statem
3ac0: 65 6e 74 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 63 68 ent. Only.** ch
3ad0: 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64 anges that are d
3ae0: 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 irectly specifie
3af0: 64 20 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c d by the INSERT,
3b00: 20 55 50 44 41 54 45 2c 20 6f 72 0a 2a 2a 20 44 UPDATE, or.** D
3b10: 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 ELETE statement
3b20: 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 are counted. Au
3b30: 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 xiliary changes
3b40: 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 caused by.** tri
3b50: 67 67 65 72 73 20 61 72 65 20 6e 6f 74 20 63 6f ggers are not co
3b60: 75 6e 74 65 64 2e 20 20 55 73 65 20 74 68 65 20 unted. Use the
3b70: 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 [sqlite3_total_c
3b80: 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 hanges()] functi
3b90: 6f 6e 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 on.** to find th
3ba0: 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f e total number o
3bb0: 66 20 63 68 61 6e 67 65 73 20 69 6e 63 6c 75 64 f changes includ
3bc0: 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 ing changes caus
3bd0: 65 64 20 62 79 20 74 72 69 67 67 65 72 73 2e 0a ed by triggers..
3be0: 2a 2a 0a 2a 2a 20 57 69 74 68 69 6e 20 74 68 65 **.** Within the
3bf0: 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 body of a trigg
3c00: 65 72 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f er, the sqlite3_
3c10: 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 changes() interf
3c20: 61 63 65 20 63 61 6e 20 62 65 0a 2a 2a 20 63 61 ace can be.** ca
3c30: 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 lled to find the
3c40: 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 number of.** ch
3c50: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 anges in the mos
3c60: 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c t recently compl
3c70: 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 eted INSERT, UPD
3c80: 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a ATE, or DELETE.*
3c90: 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 * statement with
3ca0: 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 in the body of t
3cb0: 68 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a he trigger..**.*
3cc0: 2a 20 41 6c 6c 20 63 68 61 6e 67 65 73 20 61 72 * All changes ar
3cd0: 65 20 63 6f 75 6e 74 65 64 2c 20 65 76 65 6e 20 e counted, even
3ce0: 69 66 20 74 68 65 79 20 77 65 72 65 20 6c 61 74 if they were lat
3cf0: 65 72 20 75 6e 64 6f 6e 65 20 62 79 20 61 0a 2a er undone by a.*
3d00: 2a 20 52 4f 4c 4c 42 41 43 4b 20 6f 72 20 41 42 * ROLLBACK or AB
3d10: 4f 52 54 2e 20 20 45 78 63 65 70 74 2c 20 63 68 ORT. Except, ch
3d20: 61 6e 67 65 73 20 61 73 73 6f 63 69 61 74 65 64 anges associated
3d30: 20 77 69 74 68 20 63 72 65 61 74 69 6e 67 20 61 with creating a
3d40: 6e 64 0a 2a 2a 20 64 72 6f 70 70 69 6e 67 20 74 nd.** dropping t
3d50: 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 20 63 6f ables are not co
3d60: 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 unted..**.** If
3d70: 61 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 6b a callback invok
3d80: 65 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 es [sqlite3_exec
3d90: 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
3da0: 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 step()] recursiv
3db0: 65 6c 79 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ely,.** then the
3dc0: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 changes in the
3dd0: 69 6e 6e 65 72 2c 20 72 65 63 75 72 73 69 76 65 inner, recursive
3de0: 20 63 61 6c 6c 20 61 72 65 20 63 6f 75 6e 74 65 call are counte
3df0: 64 20 74 6f 67 65 74 68 65 72 0a 2a 2a 20 77 69 d together.** wi
3e00: 74 68 20 74 68 65 20 63 68 61 6e 67 65 73 20 69 th the changes i
3e10: 6e 20 74 68 65 20 6f 75 74 65 72 20 63 61 6c 6c n the outer call
3e20: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 ..**.** SQLite i
3e30: 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f mplements the co
3e40: 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52 mmand "DELETE FR
3e50: 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75 OM table" withou
3e60: 74 20 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 t a WHERE clause
3e70: 0a 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 20 .** by dropping
3e80: 61 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20 74 and recreating t
3e90: 68 65 20 74 61 62 6c 65 2e 20 20 28 54 68 69 73 he table. (This
3ea0: 20 69 73 20 6d 75 63 68 20 66 61 73 74 65 72 20 is much faster
3eb0: 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 than going.** th
3ec0: 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69 rough and deleti
3ed0: 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c ng individual el
3ee0: 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 ements from the
3ef0: 74 61 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65 table.) Because
3f00: 20 6f 66 0a 2a 2a 20 74 68 69 73 20 6f 70 74 69 of.** this opti
3f10: 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 63 68 mization, the ch
3f20: 61 6e 67 65 20 63 6f 75 6e 74 20 66 6f 72 20 22 ange count for "
3f30: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c DELETE FROM tabl
3f40: 65 22 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 7a 65 e" will be.** ze
3f50: 72 6f 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 ro regardless of
3f60: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 the number of e
3f70: 6c 65 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72 lements that wer
3f80: 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20 e originally in
3f90: 74 68 65 0a 2a 2a 20 74 61 62 6c 65 2e 20 54 6f the.** table. To
3fa0: 20 67 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 get an accurate
3fb0: 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 count of the nu
3fc0: 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c mber of rows del
3fd0: 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 eted, use.** "DE
3fe0: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 LETE FROM table
3ff0: 57 48 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 WHERE 1" instead
4000: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
4010: 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 _changes(sqlite3
4020: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
4030: 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 REF: Total Numbe
4040: 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 r Of Rows Modifi
4050: 65 64 0a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 ed.***.** This f
4060: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
4070: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 the number of da
4080: 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 tabase rows that
4090: 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 6d 6f have been.** mo
40a0: 64 69 66 69 65 64 20 62 79 20 49 4e 53 45 52 54 dified by INSERT
40b0: 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 , UPDATE or DELE
40c0: 54 45 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 TE statements si
40d0: 6e 63 65 20 74 68 65 20 64 61 74 61 62 61 73 65 nce the database
40e0: 20 68 61 6e 64 6c 65 0a 2a 2a 20 77 61 73 20 6f handle.** was o
40f0: 70 65 6e 65 64 2e 20 54 68 69 73 20 69 6e 63 6c pened. This incl
4100: 75 64 65 73 20 55 50 44 41 54 45 2c 20 49 4e 53 udes UPDATE, INS
4110: 45 52 54 20 61 6e 64 20 44 45 4c 45 54 45 20 73 ERT and DELETE s
4120: 74 61 74 65 6d 65 6e 74 73 20 65 78 65 63 75 74 tatements execut
4130: 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 ed.** as part of
4140: 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d trigger program
4150: 73 2e 20 41 6c 6c 20 63 68 61 6e 67 65 73 20 61 s. All changes a
4160: 72 65 20 63 6f 75 6e 74 65 64 20 61 73 20 73 6f re counted as so
4170: 6f 6e 20 61 73 20 74 68 65 0a 2a 2a 20 73 74 61 on as the.** sta
4180: 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 tement that make
4190: 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 s them is comple
41a0: 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 ted (when the st
41b0: 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 69 atement handle i
41c0: 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f 20 5b s.** passed to [
41d0: 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
41e0: 20 6f 72 20 5b 73 71 6c 69 74 65 5f 66 69 6e 61 or [sqlite_fina
41f0: 6c 69 73 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 lise()])..**.**
4200: 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 See also the [sq
4210: 6c 69 74 65 33 5f 63 68 61 6e 67 65 28 29 5d 20 lite3_change()]
4220: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a interface..**.**
4230: 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e SQLite implemen
4240: 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 ts the command "
4250: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c DELETE FROM tabl
4260: 65 22 20 77 69 74 68 6f 75 74 20 61 20 57 48 45 e" without a WHE
4270: 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20 RE clause.** by
4280: 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65 63 dropping and rec
4290: 72 65 61 74 69 6e 67 20 74 68 65 20 74 61 62 6c reating the tabl
42a0: 65 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75 63 e. (This is muc
42b0: 68 20 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f h faster than go
42c0: 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 ing.** through a
42d0: 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 nd deleting indi
42e0: 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 vidual elements
42f0: 66 6f 72 6d 20 74 68 65 20 74 61 62 6c 65 2e 29 form the table.)
4300: 20 20 42 65 63 61 75 73 65 20 6f 66 0a 2a 2a 20 Because of.**
4310: 74 68 69 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f this optimizatio
4320: 6e 2c 20 74 68 65 20 63 68 61 6e 67 65 20 63 6f n, the change co
4330: 75 6e 74 20 66 6f 72 20 22 44 45 4c 45 54 45 20 unt for "DELETE
4340: 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 6c 6c FROM table" will
4350: 20 62 65 0a 2a 2a 20 7a 65 72 6f 20 72 65 67 61 be.** zero rega
4360: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75 rdless of the nu
4370: 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 mber of elements
4380: 20 74 68 61 74 20 77 65 72 65 20 6f 72 69 67 69 that were origi
4390: 6e 61 6c 6c 79 20 69 6e 20 74 68 65 0a 2a 2a 20 nally in the.**
43a0: 74 61 62 6c 65 2e 20 54 6f 20 67 65 74 20 61 6e table. To get an
43b0: 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20 accurate count
43c0: 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 of the number of
43d0: 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75 rows deleted, u
43e0: 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 se.** "DELETE FR
43f0: 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20 31 OM table WHERE 1
4400: 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2f 0a 69 6e " instead..*/.in
4410: 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f t sqlite3_total_
4420: 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a changes(sqlite3*
4430: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
4440: 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 EF: Interrupt A
4450: 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 Long-Running Que
4460: 72 79 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 ry.**.** This fu
4470: 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e nction causes an
4480: 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 y pending databa
4490: 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 se operation to
44a0: 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 abort and.** ret
44b0: 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 urn at its earli
44c0: 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e est opportunity.
44d0: 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 This routine i
44e0: 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 s typically.** c
44f0: 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 alled in respons
4500: 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 e to a user acti
4510: 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73 on such as press
4520: 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 ing "Cancel".**
4530: 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 or Ctrl-C where
4540: 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 the user wants a
4550: 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 long query oper
4560: 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a ation to halt.**
4570: 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a immediately..**
4580: 0a 2a 2a 20 49 74 20 69 73 20 73 61 66 65 20 74 .** It is safe t
4590: 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 o call this rout
45a0: 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 ine from a threa
45b0: 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d d different from
45c0: 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 the.** thread t
45d0: 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 hat is currently
45e0: 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 running the dat
45f0: 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e abase operation.
4600: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 20 6f .**.** The SQL o
4610: 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 peration that is
4620: 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c interrupted wil
4630: 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 l return [SQLITE
4640: 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 _INTERRUPT]..**
4650: 49 66 20 61 6e 20 69 6e 74 65 72 72 75 70 74 65 If an interrupte
4660: 64 20 6f 70 65 72 61 74 69 6f 6e 20 77 61 73 20 d operation was
4670: 61 6e 20 75 70 64 61 74 65 20 74 68 61 74 20 69 an update that i
4680: 73 20 69 6e 73 69 64 65 20 61 6e 0a 2a 2a 20 65 s inside an.** e
4690: 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 xplicit transact
46a0: 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e ion, then the en
46b0: 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e tire transaction
46c0: 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 0a will be rolled.
46d0: 2a 2a 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 ** back automati
46e0: 63 61 6c 6c 79 2e 0a 2a 2f 0a 76 6f 69 64 20 73 cally..*/.void s
46f0: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
4700: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
4710: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 ** CAPI3REF: Det
4720: 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c ermine If An SQL
4730: 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f Statement Is Co
4740: 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 mplete.**.** The
4750: 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 se functions ret
4760: 75 72 6e 20 74 72 75 65 20 69 66 20 74 68 65 20 urn true if the
4770: 67 69 76 65 6e 20 69 6e 70 75 74 20 73 74 72 69 given input stri
4780: 6e 67 20 63 6f 6d 70 72 69 73 65 73 0a 2a 2a 20 ng comprises.**
4790: 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 6f 6d 70 one or more comp
47a0: 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 lete SQL stateme
47b0: 6e 74 73 2e 20 46 6f 72 20 74 68 65 20 73 71 6c nts. For the sql
47c0: 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 20 ite3_complete()
47d0: 63 61 6c 6c 2c 0a 2a 2a 20 74 68 65 20 70 61 72 call,.** the par
47e0: 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 ameter must be a
47f0: 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 20 nul-terminated
4800: 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 20 46 6f UTF-8 string. Fo
4810: 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d r.** sqlite3_com
4820: 70 6c 65 74 65 31 36 28 29 2c 20 61 20 6e 75 6c plete16(), a nul
4830: 2d 74 65 72 6d 69 6e 61 74 65 64 20 6d 61 63 68 -terminated mach
4840: 69 6e 65 20 62 79 74 65 20 6f 72 64 65 72 20 55 ine byte order U
4850: 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 TF-16 string.**
4860: 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a is required..**.
4870: 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
4880: 73 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 s are useful for
4890: 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e command-line in
48a0: 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 put to determine
48b0: 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 if the.** curre
48c0: 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 ntly entered tex
48d0: 74 20 66 6f 72 6d 73 20 6f 6e 65 20 6f 72 20 6d t forms one or m
48e0: 6f 72 65 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c ore complete SQL
48f0: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72 0a 2a statements or.*
4900: 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 * if additional
4910: 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 input is needed
4920: 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 before sending t
4930: 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e he statements in
4940: 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 to.** SQLite for
4950: 20 70 61 72 73 69 6e 67 2e 20 54 68 65 20 61 6c parsing. The al
4960: 67 6f 72 69 74 68 6d 20 69 73 20 73 69 6d 70 6c gorithm is simpl
4970: 65 2e 20 20 49 66 20 74 68 65 20 0a 2a 2a 20 6c e. If the .** l
4980: 61 73 74 20 74 6f 6b 65 6e 20 6f 74 68 65 72 20 ast token other
4990: 74 68 61 6e 20 73 70 61 63 65 73 20 61 6e 64 20 than spaces and
49a0: 63 6f 6d 6d 65 6e 74 73 20 69 73 20 61 20 73 65 comments is a se
49b0: 6d 69 63 6f 6c 6f 6e 2c 20 74 68 65 6e 20 72 65 micolon, then re
49c0: 74 75 72 6e 20 0a 2a 2a 20 74 72 75 65 2e 20 20 turn .** true.
49d0: 41 63 74 75 61 6c 6c 79 2c 20 74 68 65 20 61 6c Actually, the al
49e0: 67 6f 72 69 74 68 6d 20 69 73 20 61 20 6c 69 74 gorithm is a lit
49f0: 74 6c 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 tle more complic
4a00: 61 74 65 64 20 74 68 61 6e 20 74 68 61 74 0a 2a ated than that.*
4a10: 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 * in order to de
4a20: 61 6c 20 77 69 74 68 20 74 72 69 67 67 65 72 73 al with triggers
4a30: 2c 20 62 75 74 20 74 68 65 20 62 61 73 69 63 20 , but the basic
4a40: 69 64 65 61 20 69 73 20 74 68 65 20 73 61 6d 65 idea is the same
4a50: 3a 20 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d : the.** statem
4a60: 65 6e 74 20 69 73 20 6e 6f 74 20 63 6f 6d 70 6c ent is not compl
4a70: 65 74 65 20 75 6e 6c 65 73 73 20 69 74 20 65 6e ete unless it en
4a80: 64 73 20 69 6e 20 61 20 73 65 6d 69 63 6f 6c 6f ds in a semicolo
4a90: 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 n..*/.int sqlite
4aa0: 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 3_complete(const
4ab0: 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 char *sql);.int
4ac0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 sqlite3_complet
4ad0: 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a e16(const void *
4ae0: 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 sql);../*.** CAP
4af0: 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 I3REF: Register
4b00: 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 A Callback To Ha
4b10: 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 ndle SQLITE_BUSY
4b20: 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 54 68 Errors.**.** Th
4b30: 69 73 20 72 6f 75 74 69 6e 65 20 69 64 65 6e 74 is routine ident
4b40: 69 66 69 65 73 20 61 20 63 61 6c 6c 62 61 63 6b ifies a callback
4b50: 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d function that m
4b60: 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 0a ight be invoked.
4b70: 2a 2a 20 77 68 65 6e 65 76 65 72 20 61 6e 20 61 ** whenever an a
4b80: 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 ttempt is made t
4b90: 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 o open a databas
4ba0: 65 20 74 61 62 6c 65 20 0a 2a 2a 20 74 68 61 74 e table .** that
4bb0: 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 another thread
4bc0: 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c or process has l
4bd0: 6f 63 6b 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 ocked..** If the
4be0: 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 busy callback i
4bf0: 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 s NULL, then [SQ
4c00: 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 28 6f LITE_BUSY].** (o
4c10: 72 20 73 6f 6d 65 74 69 6d 65 73 20 5b 53 51 4c r sometimes [SQL
4c20: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 ITE_IOERR_BLOCKE
4c30: 44 5d 29 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e D]).** is return
4c40: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 ed immediately u
4c50: 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 pon encountering
4c60: 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 49 66 the lock..** If
4c70: 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 the busy callba
4c80: 63 6b 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 ck is not NULL,
4c90: 74 68 65 6e 20 74 68 65 0a 2a 2a 20 63 61 6c 6c then the.** call
4ca0: 62 61 63 6b 20 77 69 6c 6c 20 62 65 20 69 6e 76 back will be inv
4cb0: 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 oked with two ar
4cc0: 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 0a 2a 2a guments. The.**
4cd0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
4ce0: 74 6f 20 74 68 65 20 68 61 6e 64 6c 65 72 20 69 to the handler i
4cf0: 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 s a copy of the
4d00: 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 void* pointer wh
4d10: 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 ich.** is the th
4d20: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ird argument to
4d30: 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 20 20 54 this routine. T
4d40: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
4d50: 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61 6e nt to.** the han
4d60: 64 6c 65 72 20 69 73 20 74 68 65 20 6e 75 6d 62 dler is the numb
4d70: 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 er of times that
4d80: 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 the busy handle
4d90: 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e r has.** been in
4da0: 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c voked for this l
4db0: 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 49 66 ocking event. If
4dc0: 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c the.** busy cal
4dd0: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c lback returns 0,
4de0: 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f then no additio
4df0: 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 nal attempts are
4e00: 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 made to.** acce
4e10: 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ss the database
4e20: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 and [SQLITE_BUSY
4e30: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 ] or [SQLITE_IOE
4e40: 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 RR_BLOCKED] is r
4e50: 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 eturned..** If t
4e60: 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 he callback retu
4e70: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 rns non-zero, th
4e80: 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d en another attem
4e90: 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 pt is made to op
4ea0: 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 en the.** databa
4eb0: 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 se for reading a
4ec0: 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 nd the cycle rep
4ed0: 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 eats..**.** The
4ee0: 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 presence of a bu
4ef0: 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 sy handler does
4f00: 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 not guarantee th
4f10: 61 74 0a 2a 2a 20 69 74 20 77 69 6c 6c 20 62 65 at.** it will be
4f20: 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 invoked when th
4f30: 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 ere is lock cont
4f40: 65 6e 74 69 6f 6e 2e 0a 2a 2a 20 49 66 20 53 51 ention..** If SQ
4f50: 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 Lite determines
4f60: 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 that invoking th
4f70: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 e busy handler c
4f80: 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 0a 2a ould result in.*
4f90: 2a 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 * a deadlock, it
4fa0: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 will return [SQ
4fb0: 4c 49 54 45 5f 42 55 53 59 5d 20 69 6e 73 74 65 LITE_BUSY] inste
4fc0: 61 64 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 ad..** Consider
4fd0: 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 a scenario where
4fe0: 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 one process is
4ff0: 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c holding a read l
5000: 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 ock that.** it i
5010: 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d s trying to prom
5020: 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 ote to a reserve
5030: 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 d lock and.** a
5040: 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 second process i
5050: 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 s holding a rese
5060: 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 rved lock that i
5070: 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 t is trying.** t
5080: 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 o promote to an
5090: 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 exclusive lock.
50a0: 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 The first proce
50b0: 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 ss cannot procee
50c0: 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 d.** because it
50d0: 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 is blocked by th
50e0: 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 e second and the
50f0: 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 second process
5100: 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 cannot.** procee
5110: 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 d because it is
5120: 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 blocked by the f
5130: 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 irst. If both p
5140: 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f rocesses.** invo
5150: 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ke the busy hand
5160: 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 lers, neither wi
5170: 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 ll make any prog
5180: 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 ress. Therefore
5190: 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 ,.** SQLite retu
51a0: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 rns [SQLITE_BUSY
51b0: 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 ] for the first
51c0: 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 process, hoping
51d0: 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c that this.** wil
51e0: 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 l induce the fir
51f0: 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 st process to re
5200: 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c lease its read l
5210: 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a ock and allow.**
5220: 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 the second proc
5230: 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a ess to proceed..
5240: 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c **.** The defaul
5250: 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 t busy callback
5260: 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 is NULL..**.** T
5270: 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d he [SQLITE_BUSY]
5280: 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 error is conver
5290: 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 ted to [SQLITE_I
52a0: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 77 68 OERR_BLOCKED] wh
52b0: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 en.** SQLite is
52c0: 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 in the middle of
52d0: 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 a large transac
52e0: 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 tion where all t
52f0: 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 he.** changes wi
5300: 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 ll not fit into
5310: 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 the in-memory ca
5320: 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c che. SQLite wil
5330: 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c l.** already hol
5340: 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 d a RESERVED loc
5350: 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 k on the databas
5360: 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e e file, but it n
5370: 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f eeds.** to promo
5380: 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 te this lock to
5390: 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 EXCLUSIVE so tha
53a0: 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 t it can spill c
53b0: 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e ache.** pages in
53c0: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 to the database
53d0: 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 file without har
53e0: 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a m to concurrent.
53f0: 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 49 66 20 ** readers. If
5400: 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 it is unable to
5410: 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b promote the lock
5420: 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 , then the in-me
5430: 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 mory.** cache wi
5440: 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e ll be left in an
5450: 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 inconsistent st
5460: 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 ate and so the e
5470: 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 rror.** code is
5480: 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 promoted from th
5490: 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e e relatively ben
54a0: 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 ign [SQLITE_BUSY
54b0: 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 ] to.** the more
54c0: 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f severe [SQLITE_
54d0: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 IOERR_BLOCKED].
54e0: 20 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 This error code
54f0: 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f promotion.** fo
5500: 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 rces an automati
5510: 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 c rollback of th
5520: 65 20 63 68 61 6e 67 65 73 2e 20 53 65 65 20 74 e changes. See t
5530: 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68 he.** <a href="h
5540: 74 74 70 3a 2f 2f 77 77 77 2e 73 71 6c 69 74 65 ttp://www.sqlite
5550: 2e 6f 72 67 2f 63 76 73 74 72 61 63 2f 77 69 6b .org/cvstrac/wik
5560: 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f i?p=CorruptionFo
5570: 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 llowingBusyError
5580: 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e ">.** Corruption
5590: 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 FollowingBusyErr
55a0: 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 or</a> wiki page
55b0: 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f for a discussio
55c0: 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 n of why.** this
55d0: 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a is important..*
55e0: 2a 09 0a 2a 2a 20 53 71 6c 69 74 65 20 69 73 20 *..** Sqlite is
55f0: 72 65 2d 65 6e 74 72 61 6e 74 2c 20 73 6f 20 74 re-entrant, so t
5600: 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 he busy handler
5610: 6d 61 79 20 73 74 61 72 74 20 61 20 6e 65 77 20 may start a new
5620: 71 75 65 72 79 2e 20 0a 2a 2a 20 28 49 74 20 69 query. .** (It i
5630: 73 20 6e 6f 74 20 63 6c 65 61 72 20 77 68 79 20 s not clear why
5640: 61 6e 79 6f 6e 65 20 77 6f 75 6c 64 20 65 76 65 anyone would eve
5650: 72 79 20 77 61 6e 74 20 74 6f 20 64 6f 20 74 68 ry want to do th
5660: 69 73 2c 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 is, but it.** is
5670: 20 61 6c 6c 6f 77 65 64 2c 20 69 6e 20 74 68 65 allowed, in the
5680: 6f 72 79 2e 29 20 20 42 75 74 20 74 68 65 20 62 ory.) But the b
5690: 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 usy handler may
56a0: 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 0a 2a 2a not close the.**
56b0: 20 64 61 74 61 62 61 73 65 2e 20 20 43 6c 6f 73 database. Clos
56c0: 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 ing the database
56d0: 20 66 72 6f 6d 20 61 20 62 75 73 79 20 68 61 6e from a busy han
56e0: 64 6c 65 72 20 77 69 6c 6c 20 64 65 6c 65 74 65 dler will delete
56f0: 20 0a 2a 2a 20 64 61 74 61 20 73 74 72 75 63 74 .** data struct
5700: 75 72 65 73 20 6f 75 74 20 66 72 6f 6d 20 75 6e ures out from un
5710: 64 65 72 20 74 68 65 20 65 78 65 63 75 74 69 6e der the executin
5720: 67 20 71 75 65 72 79 20 61 6e 64 20 77 69 6c 6c g query and will
5730: 20 0a 2a 2a 20 70 72 6f 62 61 62 6c 79 20 72 65 .** probably re
5740: 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e sult in a segmen
5750: 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 tation fault or
5760: 6f 74 68 65 72 20 72 75 6e 74 69 6d 65 20 65 72 other runtime er
5770: 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 ror..**.** There
5780: 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 can only be a s
5790: 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c ingle busy handl
57a0: 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 er defined for e
57b0: 61 63 68 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 ach database.**
57c0: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 74 connection. Set
57d0: 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 ting a new busy
57e0: 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 handler clears a
57f0: 6e 79 20 70 72 65 76 69 6f 75 73 20 6f 6e 65 2e ny previous one.
5800: 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 63 61 .** Note that ca
5810: 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 lling [sqlite3_b
5820: 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 77 usy_timeout()] w
5830: 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 ill also set or
5840: 63 6c 65 61 72 0a 2a 2a 20 74 68 65 20 62 75 73 clear.** the bus
5850: 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e y handler..*/.in
5860: 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 t sqlite3_busy_h
5870: 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c andler(sqlite3*,
5880: 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e int(*)(void*,in
5890: 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a t), void*);../*.
58a0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 ** CAPI3REF: Set
58b0: 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a A Busy Timeout.
58c0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
58d0: 6e 65 20 73 65 74 73 20 61 20 62 75 73 79 20 68 ne sets a busy h
58e0: 61 6e 64 6c 65 72 20 74 68 61 74 20 73 6c 65 65 andler that slee
58f0: 70 73 20 66 6f 72 20 61 20 77 68 69 6c 65 20 77 ps for a while w
5900: 68 65 6e 20 61 0a 2a 2a 20 74 61 62 6c 65 20 69 hen a.** table i
5910: 73 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20 68 s locked. The h
5920: 61 6e 64 6c 65 72 20 77 69 6c 6c 20 73 6c 65 65 andler will slee
5930: 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 p multiple times
5940: 20 75 6e 74 69 6c 20 0a 2a 2a 20 61 74 20 6c 65 until .** at le
5950: 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 ast "ms" millise
5960: 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e conds of sleepin
5970: 67 20 68 61 76 65 20 62 65 65 6e 20 64 6f 6e 65 g have been done
5980: 2e 20 20 41 66 74 65 72 0a 2a 2a 20 22 6d 73 22 . After.** "ms"
5990: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 milliseconds of
59a0: 20 73 6c 65 65 70 69 6e 67 2c 20 74 68 65 20 68 sleeping, the h
59b0: 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 andler returns 0
59c0: 20 77 68 69 63 68 0a 2a 2a 20 63 61 75 73 65 73 which.** causes
59d0: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
59e0: 5d 20 74 6f 20 72 65 74 75 72 6e 20 5b 53 51 4c ] to return [SQL
59f0: 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 ITE_BUSY] or [SQ
5a00: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b LITE_IOERR_BLOCK
5a10: 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 ED]..**.** Calli
5a20: 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 ng this routine
5a30: 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 with an argument
5a40: 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 less than or eq
5a50: 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 ual to zero.** t
5a60: 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 urns off all bus
5a70: 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a y handlers..**.*
5a80: 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 * There can only
5a90: 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 be a single bus
5aa0: 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 y handler for a
5ab0: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 particular datab
5ac0: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f ase.** connectio
5ad0: 6e 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 n. If another b
5ae0: 75 73 79 20 68 61 6e 64 6c 65 72 20 77 61 73 20 usy handler was
5af0: 64 65 66 69 6e 65 64 20 20 0a 2a 2a 20 28 75 73 defined .** (us
5b00: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 ing [sqlite3_bus
5b10: 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 y_handler()]) pr
5b20: 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a ior to calling.*
5b30: 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 * this routine,
5b40: 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 that other busy
5b50: 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 handler is clear
5b60: 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ed..*/.int sqlit
5b70: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 e3_busy_timeout(
5b80: 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 sqlite3*, int ms
5b90: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
5ba0: 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 EF: Convenience
5bb0: 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e Routines For Run
5bc0: 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a ning Queries.**.
5bd0: 2a 2a 20 54 68 69 73 20 6e 65 78 74 20 72 6f 75 ** This next rou
5be0: 74 69 6e 65 20 69 73 20 61 20 63 6f 6e 76 65 6e tine is a conven
5bf0: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 ience wrapper ar
5c00: 6f 75 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 78 ound [sqlite3_ex
5c10: 65 63 28 29 5d 2e 0a 2a 2a 20 49 6e 73 74 65 61 ec()]..** Instea
5c20: 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 61 20 d of invoking a
5c30: 75 73 65 72 2d 73 75 70 70 6c 69 65 64 20 63 61 user-supplied ca
5c40: 6c 6c 62 61 63 6b 20 66 6f 72 20 65 61 63 68 20 llback for each
5c50: 72 6f 77 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 row of the.** re
5c60: 73 75 6c 74 2c 20 74 68 69 73 20 72 6f 75 74 69 sult, this routi
5c70: 6e 65 20 72 65 6d 65 6d 62 65 72 73 20 65 61 63 ne remembers eac
5c80: 68 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 h row of the res
5c90: 75 6c 74 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a ult in memory.**
5ca0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
5cb0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
5cc0: 5d 2c 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 ], then returns
5cd0: 61 6c 6c 20 6f 66 20 74 68 65 20 72 65 73 75 6c all of the resul
5ce0: 74 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 71 t after the.** q
5cf0: 75 65 72 79 20 68 61 73 20 66 69 6e 69 73 68 65 uery has finishe
5d00: 64 2e 20 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 d. .**.** As an
5d10: 65 78 61 6d 70 6c 65 2c 20 73 75 70 70 6f 73 65 example, suppose
5d20: 20 74 68 65 20 71 75 65 72 79 20 72 65 73 75 6c the query resul
5d30: 74 20 77 68 65 72 65 20 74 68 69 73 20 74 61 62 t where this tab
5d40: 6c 65 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a le:.**.** <pre>.
5d50: 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 ** Name
5d60: 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 | Age.**
5d70: 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------
5d80: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a -------------.**
5d90: 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 Alice
5da0: 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 | 43.**
5db0: 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c Bob |
5dc0: 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 28.** Ci
5dd0: 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a ndy | 21.*
5de0: 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 49 * </pre>.**.** I
5df0: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65 f the 3rd argume
5e00: 6e 74 20 77 65 72 65 20 26 61 7a 52 65 73 75 6c nt were &azResul
5e10: 74 20 74 68 65 6e 20 61 66 74 65 72 20 74 68 65 t then after the
5e20: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e function return
5e30: 73 0a 2a 2a 20 61 7a 52 65 73 75 6c 74 20 77 69 s.** azResult wi
5e40: 6c 6c 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 66 ll contain the f
5e50: 6f 6c 6c 6f 77 69 6e 67 20 64 61 74 61 3a 0a 2a ollowing data:.*
5e60: 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 *.** <pre>.**
5e70: 20 20 20 20 20 61 7a 52 65 73 75 6c 74 5b 30 5d azResult[0]
5e80: 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 = "Name";.**
5e90: 20 20 20 20 20 61 7a 52 65 73 75 6c 74 5b 31 5d azResult[1]
5ea0: 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 = "Age";.**
5eb0: 20 20 20 20 61 7a 52 65 73 75 6c 74 5b 32 5d 20 azResult[2]
5ec0: 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 = "Alice";.**
5ed0: 20 20 20 20 20 61 7a 52 65 73 75 6c 74 5b 33 5d azResult[3]
5ee0: 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 = "43";.**
5ef0: 20 20 20 61 7a 52 65 73 75 6c 74 5b 34 5d 20 3d azResult[4] =
5f00: 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 "Bob";.**
5f10: 20 20 61 7a 52 65 73 75 6c 74 5b 35 5d 20 3d 20 azResult[5] =
5f20: 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 "28";.**
5f30: 61 7a 52 65 73 75 6c 74 5b 36 5d 20 3d 20 22 43 azResult[6] = "C
5f40: 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 indy";.**
5f50: 20 61 7a 52 65 73 75 6c 74 5b 37 5d 20 3d 20 22 azResult[7] = "
5f60: 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 21";.** </pre>.*
5f70: 2a 0a 2a 2a 20 4e 6f 74 69 63 65 20 74 68 61 74 *.** Notice that
5f80: 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 78 74 there is an ext
5f90: 72 61 20 72 6f 77 20 6f 66 20 64 61 74 61 20 63 ra row of data c
5fa0: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 63 6f ontaining the co
5fb0: 6c 75 6d 6e 0a 2a 2a 20 68 65 61 64 65 72 73 2e lumn.** headers.
5fc0: 20 20 42 75 74 20 74 68 65 20 2a 6e 72 6f 77 20 But the *nrow
5fd0: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 20 return value is
5fe0: 73 74 69 6c 6c 20 33 2e 20 20 2a 6e 63 6f 6c 75 still 3. *ncolu
5ff0: 6d 6e 20 69 73 0a 2a 2a 20 73 65 74 20 74 6f 20 mn is.** set to
6000: 32 2e 20 20 49 6e 20 67 65 6e 65 72 61 6c 2c 20 2. In general,
6010: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 the number of va
6020: 6c 75 65 73 20 69 6e 73 65 72 74 65 64 20 69 6e lues inserted in
6030: 74 6f 20 61 7a 52 65 73 75 6c 74 0a 2a 2a 20 77 to azResult.** w
6040: 69 6c 6c 20 62 65 20 28 28 2a 6e 72 6f 77 29 20 ill be ((*nrow)
6050: 2b 20 31 29 2a 28 2a 6e 63 6f 6c 75 6d 6e 29 2e + 1)*(*ncolumn).
6060: 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 .**.** After the
6070: 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f calling functio
6080: 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 n has finished u
6090: 73 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2c sing the result,
60a0: 20 69 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 it should .** p
60b0: 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 64 ass the result d
60c0: 61 74 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 ata pointer to s
60d0: 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c qlite3_free_tabl
60e0: 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 e() in order to
60f0: 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 .** release the
6100: 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 memory that was
6110: 6d 61 6c 6c 6f 63 2d 65 64 2e 20 20 42 65 63 61 malloc-ed. Beca
6120: 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 use of the way t
6130: 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f he .** [sqlite3_
6140: 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e malloc()] happen
6150: 73 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 s, the calling f
6160: 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 unction must not
6170: 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 0a 2a 2a try to call .**
6180: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
6190: 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c ] directly. Onl
61a0: 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f y [sqlite3_free_
61b0: 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 table()] is able
61c0: 20 74 6f 20 72 65 6c 65 61 73 65 20 0a 2a 2a 20 to release .**
61d0: 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 the memory prope
61e0: 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a rly and safely..
61f0: 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e **.** The return
6200: 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 72 value of this r
6210: 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20 73 61 outine is the sa
6220: 6d 65 20 61 73 20 66 72 6f 6d 20 5b 73 71 6c 69 me as from [sqli
6230: 74 65 33 5f 65 78 65 63 28 29 5d 2e 0a 2a 2f 0a te3_exec()]..*/.
6240: 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f int sqlite3_get_
6250: 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 table(. sqlite3
6260: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 *,
6270: 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 /* An open datab
6280: 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 ase */. const c
6290: 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 har *sql,
62a0: 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 78 65 /* SQL to be exe
62b0: 63 75 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 cuted */. char
62c0: 2a 2a 2a 72 65 73 75 6c 74 70 2c 20 20 20 20 20 ***resultp,
62d0: 20 20 2f 2a 20 52 65 73 75 6c 74 20 77 72 69 74 /* Result writ
62e0: 74 65 6e 20 74 6f 20 61 20 63 68 61 72 20 2a 5b ten to a char *[
62f0: 5d 20 20 74 68 61 74 20 74 68 69 73 20 70 6f 69 ] that this poi
6300: 6e 74 73 20 74 6f 20 2a 2f 0a 20 20 69 6e 74 20 nts to */. int
6310: 2a 6e 72 6f 77 2c 20 20 20 20 20 20 20 20 20 20 *nrow,
6320: 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 /* Number of
6330: 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 result rows writ
6340: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e ten here */. in
6350: 74 20 2a 6e 63 6f 6c 75 6d 6e 2c 20 20 20 20 20 t *ncolumn,
6360: 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f /* Number o
6370: 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 f result columns
6380: 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f written here */
6390: 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 . char **errmsg
63a0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 /* Err
63b0: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 or msg written h
63c0: 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 ere */.);.void s
63d0: 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c qlite3_free_tabl
63e0: 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 e(char **result)
63f0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
6400: 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 F: Formatted Str
6410: 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e ing Printing Fun
6420: 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 ctions.**.** The
6430: 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
6440: 77 6f 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 workalikes of th
6450: 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d e "printf()" fam
6460: 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 ily of functions
6470: 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 .** from the sta
6480: 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e ndard C library.
6490: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
64a0: 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 e3_mprintf() and
64b0: 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 sqlite3_vmprint
64c0: 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 f() routines wri
64d0: 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 te their.** resu
64e0: 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 lts into memory
64f0: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 obtained from [s
6500: 71 6c 69 74 65 5f 6d 61 6c 6c 6f 63 28 29 5d 2e qlite_malloc()].
6510: 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 .** The strings
6520: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 returned by thes
6530: 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 e two routines s
6540: 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 hould be.** rele
6550: 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 ased by [sqlite3
6560: 5f 66 72 65 65 28 29 5d 2e 20 20 42 6f 74 68 20 _free()]. Both
6570: 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
6580: 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 a.** NULL pointe
6590: 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 r if [sqlite3_ma
65a0: 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c lloc()] is unabl
65b0: 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e e to allocate en
65c0: 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 ough.** memory t
65d0: 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c o hold the resul
65e0: 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a ting string..**.
65f0: 2a 2a 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e ** In sqlite3_sn
6600: 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 printf() routine
6610: 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 is similar to "
6620: 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d snprintf()" from
6630: 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 .** the standard
6640: 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 C library. The
6650: 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 result is writt
6660: 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 en into the.** b
6670: 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 uffer supplied a
6680: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 s the second par
6690: 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a ameter whose siz
66a0: 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a e is given by.**
66b0: 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
66c0: 65 74 65 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 eter. Note that
66d0: 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 the order of th
66e0: 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 e.** first two p
66f0: 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 arameters is rev
6700: 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 ersed from snpri
6710: 6e 74 66 28 29 2e 20 20 54 68 69 73 20 69 73 20 ntf(). This is
6720: 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c an.** historical
6730: 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 accident that c
6740: 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 annot be fixed w
6750: 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a ithout breaking.
6760: 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d ** backwards com
6770: 70 61 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 patibility. Not
6780: 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 e also that sqli
6790: 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a te3_snprintf().*
67a0: 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e * returns a poin
67b0: 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 ter to its buffe
67c0: 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 r instead of the
67d0: 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 number of.** ch
67e0: 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c aracters actuall
67f0: 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 y written into t
6800: 68 65 20 62 75 66 66 65 72 2e 20 20 57 65 20 61 he buffer. We a
6810: 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 dmit that.** the
6820: 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 number of chara
6830: 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f cters written wo
6840: 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 uld be a more us
6850: 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 eful return.** v
6860: 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e alue but we cann
6870: 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d ot change the im
6880: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
6890: 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
68a0: 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 ().** now withou
68b0: 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 t breaking compa
68c0: 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 tibility..**.**
68d0: 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 As long as the b
68e0: 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 uffer size is gr
68f0: 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c eater than zero,
6900: 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 sqlite3_snprint
6910: 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 f().** guarantee
6920: 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 s that the buffe
6930: 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f r is always zero
6940: 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 -terminated. Th
6950: 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d e first.** param
6960: 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 eter "n" is the
6970: 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 total size of th
6980: 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 e buffer, includ
6990: 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a ing space for.**
69a0: 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e the zero termin
69b0: 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f ator. So the lo
69c0: 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 ngest string tha
69d0: 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 t can be complet
69e0: 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 ely.** written w
69f0: 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 ill be n-1 chara
6a00: 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 cters..**.** The
6a10: 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 se routines all
6a20: 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 implement some a
6a30: 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 dditional format
6a40: 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 ting.** options
6a50: 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 that are useful
6a60: 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 for constructing
6a70: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e SQL statements.
6a80: 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 .** All of the u
6a90: 73 75 61 6c 20 70 72 69 6e 74 66 20 66 6f 72 6d sual printf form
6aa0: 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 atting options a
6ab0: 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 pply. In additi
6ac0: 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 on, there.** is
6ad0: 61 72 65 20 22 25 71 22 20 61 6e 64 20 22 25 51 are "%q" and "%Q
6ae0: 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a " options..**.**
6af0: 20 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 The %q option w
6b00: 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 orks like %s in
6b10: 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75 that it substitu
6b20: 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 tes a null-termi
6b30: 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 nated.** string
6b40: 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e from the argumen
6b50: 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 t list. But %q
6b60: 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 also doubles eve
6b70: 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 ry '\'' characte
6b80: 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 r..** %q is desi
6b90: 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 gned for use ins
6ba0: 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 ide a string lit
6bb0: 65 72 61 6c 2e 20 20 42 79 20 64 6f 75 62 6c 69 eral. By doubli
6bc0: 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 ng each '\''.**
6bd0: 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 character it esc
6be0: 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 apes that charac
6bf0: 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 ter and allows i
6c00: 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 t to be inserted
6c10: 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 into.** the str
6c20: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 ing..**.** For e
6c30: 78 61 6d 70 6c 65 2c 20 73 6f 20 73 6f 6d 65 20 xample, so some
6c40: 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 string variable
6c50: 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 contains text as
6c60: 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 follows:.**.**
6c70: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
6c80: 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 >.** char *zTex
6c90: 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 t = "It's a happ
6ca0: 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 y day!";.** </pr
6cb0: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a e></blockquote>.
6cc0: 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 **.** One can us
6cd0: 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 e this text in a
6ce0: 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 n SQL statement
6cf0: 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a as follows:.**.*
6d00: 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
6d10: 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 re>.** char *zS
6d20: 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 QL = sqlite3_mpr
6d30: 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 intf("INSERT INT
6d40: 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 O table VALUES('
6d50: 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a %q')", zText);.*
6d60: 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 * sqlite3_exec(
6d70: 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 db, zSQL, 0, 0,
6d80: 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 0);.** sqlite3_
6d90: 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c free(zSQL);.** <
6da0: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
6db0: 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 e>.**.** Because
6dc0: 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 the %q format s
6dd0: 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 tring is used, t
6de0: 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 he '\'' characte
6df0: 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 r in zText.** is
6e00: 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 escaped and the
6e10: 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 SQL generated i
6e20: 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a s as follows:.**
6e30: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
6e40: 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 <pre>.** INSERT
6e50: 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c INTO table1 VAL
6e60: 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 UES('It''s a hap
6e70: 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 py day!').** </p
6e80: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
6e90: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 .**.** This is c
6ea0: 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 orrect. Had we
6eb0: 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 used %s instead
6ec0: 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 of %q, the gener
6ed0: 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c ated SQL.** woul
6ee0: 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 d have looked li
6ef0: 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c ke this:.**.** <
6f00: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
6f10: 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f .** INSERT INTO
6f20: 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 table1 VALUES('
6f30: 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 It's a happy day
6f40: 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f !');.** </pre></
6f50: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
6f60: 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 * This second ex
6f70: 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 ample is an SQL
6f80: 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 syntax error. A
6f90: 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 s a general rule
6fa0: 20 79 6f 75 0a 2a 2a 20 73 68 6f 75 6c 64 20 61 you.** should a
6fb0: 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 lways use %q ins
6fc0: 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 tead of %s when
6fd0: 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 inserting text i
6fe0: 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 0a 2a 2a nto a string .**
6ff0: 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 literal..**.**
7000: 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f The %Q option wo
7010: 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 rks like %q exce
7020: 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 pt it also adds
7030: 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 single quotes ar
7040: 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 ound.** the outs
7050: 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c ide of the total
7060: 20 73 74 72 69 6e 67 2e 20 20 4f 72 20 69 66 20 string. Or if
7070: 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e the parameter in
7080: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a the argument.**
7090: 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 list is a NULL
70a0: 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 pointer, %Q subs
70b0: 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 titutes the text
70c0: 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 "NULL" (without
70d0: 20 73 69 6e 67 6c 65 0a 2a 2a 20 71 75 6f 74 65 single.** quote
70e0: 73 29 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 s) in place of t
70f0: 68 65 20 25 51 20 6f 70 74 69 6f 6e 2e 20 20 53 he %Q option. S
7100: 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 o, for example,
7110: 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a one could say:.*
7120: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
7130: 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 ><pre>.** char
7140: 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f *zSQL = sqlite3_
7150: 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 mprintf("INSERT
7160: 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 INTO table VALUE
7170: 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a S(%Q)", zText);.
7180: 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 ** sqlite3_exec
7190: 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c (db, zSQL, 0, 0,
71a0: 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 0);.** sqlite3
71b0: 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 _free(zSQL);.**
71c0: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
71d0: 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f te>.**.** The co
71e0: 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 de above will re
71f0: 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 nder a correct S
7200: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 QL statement in
7210: 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 the zSQL.** vari
7220: 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 able even if the
7230: 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 zText variable
7240: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
7250: 72 2e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 r..*/.char *sqli
7260: 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 te3_mprintf(cons
7270: 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 t char*,...);.ch
7280: 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 ar *sqlite3_vmpr
7290: 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a intf(const char*
72a0: 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 , va_list);.char
72b0: 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e *sqlite3_snprin
72c0: 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e tf(int,char*,con
72d0: 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a st char*, ...);.
72e0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
72f0: 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 Memory Allocati
7300: 6f 6e 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a on Functions.**.
7310: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 69 ** SQLite uses i
7320: 74 73 20 6f 77 6e 20 6d 65 6d 6f 72 79 20 61 6c ts own memory al
7330: 6c 6f 63 61 74 6f 72 2e 20 20 4f 6e 20 73 6f 6d locator. On som
7340: 65 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 73 2c e installations,
7350: 20 74 68 69 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 this.** memory
7360: 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 69 64 65 allocator is ide
7370: 6e 74 69 63 61 6c 20 74 6f 20 74 68 65 20 73 74 ntical to the st
7380: 61 6e 64 61 72 64 20 6d 61 6c 6c 6f 63 28 29 2f andard malloc()/
7390: 72 65 61 6c 6c 6f 63 28 29 2f 66 72 65 65 28 29 realloc()/free()
73a0: 0a 2a 2a 20 61 6e 64 20 63 61 6e 20 62 65 20 75 .** and can be u
73b0: 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 61 62 sed interchangab
73c0: 6c 65 2e 20 20 4f 6e 20 6f 74 68 65 72 73 2c 20 le. On others,
73d0: 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 the implementati
73e0: 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 69 66 66 65 ons are.** diffe
73f0: 72 65 6e 74 2e 20 20 46 6f 72 20 6d 61 78 69 6d rent. For maxim
7400: 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 20 um portability,
7410: 69 74 20 69 73 20 62 65 73 74 20 6e 6f 74 20 74 it is best not t
7420: 6f 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 o mix calls.** t
7430: 6f 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 6d o the standard m
7440: 61 6c 6c 6f 63 2f 72 65 61 6c 6c 6f 63 2f 66 72 alloc/realloc/fr
7450: 65 65 20 77 69 74 68 20 74 68 65 20 73 71 6c 69 ee with the sqli
7460: 74 65 20 76 65 72 73 69 6f 6e 73 2e 0a 2a 2f 0a te versions..*/.
7470: 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 void *sqlite3_ma
7480: 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 lloc(int);.void
7490: 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 *sqlite3_realloc
74a0: 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f (void*, int);.vo
74b0: 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 id sqlite3_free(
74c0: 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 void*);../*.** C
74d0: 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 API3REF: Compile
74e0: 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 -Time Authorizat
74f0: 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a ion Callbacks.**
7500: 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
7510: 65 20 72 65 67 69 73 74 65 72 73 20 61 20 61 75 e registers a au
7520: 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
7530: 6b 20 77 69 74 68 20 74 68 65 20 53 51 4c 69 74 k with the SQLit
7540: 65 20 6c 69 62 72 61 72 79 2e 20 20 0a 2a 2a 20 e library. .**
7550: 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 The authorizer c
7560: 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
7570: 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d ed as SQL statem
7580: 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 ents are being c
7590: 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 ompiled.** by [s
75a0: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
75b0: 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 ] or its variant
75c0: 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 s [sqlite3_prepa
75d0: 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 re_v2()],.** [sq
75e0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
75f0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
7600: 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e prepare16_v2()].
7610: 20 20 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 At various.**
7620: 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 points during th
7630: 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 e compilation pr
7640: 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 ocess, as logic
7650: 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 is being created
7660: 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 .** to perform v
7670: 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 arious actions,
7680: 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
7690: 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
76a0: 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 ed to.** see if
76b0: 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 those actions ar
76c0: 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20 e allowed. The
76d0: 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
76e0: 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 ack should.** re
76f0: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 74 turn SQLITE_OK t
7700: 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 o allow the acti
7710: 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f on, [SQLITE_IGNO
7720: 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 RE] to disallow
7730: 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 the.** specific
7740: 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 action but allow
7750: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
7760: 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 nt to continue t
7770: 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 o be.** compiled
7780: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e , or [SQLITE_DEN
7790: 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 Y] to cause the
77a0: 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 entire SQL state
77b0: 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 ment to be.** re
77c0: 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 jected with an e
77d0: 72 72 6f 72 2e 20 20 0a 2a 2a 0a 2a 2a 20 44 65 rror. .**.** De
77e0: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 61 pending on the a
77f0: 63 74 69 6f 6e 2c 20 74 68 65 20 5b 53 51 4c 49 ction, the [SQLI
7800: 54 45 5f 49 47 4e 4f 52 45 5d 20 61 6e 64 20 5b TE_IGNORE] and [
7810: 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 72 65 74 SQLITE_DENY] ret
7820: 75 72 6e 0a 2a 2a 20 63 6f 64 65 73 20 6d 69 67 urn.** codes mig
7830: 68 74 20 6d 65 61 6e 20 73 6f 6d 65 74 68 69 6e ht mean somethin
7840: 67 20 64 69 66 66 65 72 65 6e 74 20 6f 72 20 74 g different or t
7850: 68 65 79 20 6d 69 67 68 74 20 6d 65 61 6e 20 74 hey might mean t
7860: 68 65 20 73 61 6d 65 0a 2a 2a 20 74 68 69 6e 67 he same.** thing
7870: 2e 20 20 49 66 20 74 68 65 20 61 63 74 69 6f 6e . If the action
7880: 20 69 73 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 is, for example
7890: 2c 20 74 6f 20 70 65 72 66 6f 72 6d 20 61 20 64 , to perform a d
78a0: 65 6c 65 74 65 20 6f 70 65 72 74 69 6f 6e 2c 0a elete opertion,.
78b0: 2a 2a 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f ** then [SQLITE_
78c0: 49 47 4e 4f 52 45 5d 20 61 6e 64 20 5b 53 51 4c IGNORE] and [SQL
78d0: 49 54 45 5f 44 45 4e 59 5d 20 62 6f 74 68 20 63 ITE_DENY] both c
78e0: 61 75 73 65 20 74 68 65 20 73 74 61 74 65 6d 65 ause the stateme
78f0: 6e 74 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 0a 2a nt compilation.*
7900: 2a 20 74 6f 20 66 61 69 6c 20 77 69 74 68 20 61 * to fail with a
7910: 6e 20 65 72 72 6f 72 2e 20 20 42 75 74 20 69 66 n error. But if
7920: 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 74 the action is t
7930: 6f 20 72 65 61 64 20 61 20 73 70 65 63 69 66 69 o read a specifi
7940: 63 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 66 72 6f 6d c column.** from
7950: 20 61 20 73 70 65 63 69 66 69 63 20 74 61 62 6c a specific tabl
7960: 65 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f e, then [SQLITE_
7970: 44 45 4e 59 5d 20 77 69 6c 6c 20 63 61 75 73 65 DENY] will cause
7980: 20 74 68 65 20 65 6e 74 69 72 65 0a 2a 2a 20 73 the entire.** s
7990: 74 61 74 65 6d 65 6e 74 20 74 6f 20 66 61 69 6c tatement to fail
79a0: 20 62 75 74 20 5b 53 51 4c 49 54 45 5f 49 47 4e but [SQLITE_IGN
79b0: 4f 52 45 5d 20 77 69 6c 6c 20 63 61 75 73 65 20 ORE] will cause
79c0: 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 74 6f 20 a NULL value to
79d0: 62 65 0a 2a 2a 20 72 65 61 64 20 69 6e 73 74 65 be.** read inste
79e0: 61 64 20 6f 66 20 74 68 65 20 61 63 74 75 61 6c ad of the actual
79f0: 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2e 0a 2a column value..*
7a00: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 *.** The first p
7a10: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
7a20: 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
7a30: 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 ack is a copy of
7a40: 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 20 70 61 .** the third pa
7a50: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 rameter to the s
7a60: 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
7a70: 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 rizer() interfac
7a80: 65 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 e..** The second
7a90: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
7aa0: 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e e callback is an
7ab0: 20 69 6e 74 65 67 65 72 20 0a 2a 2a 20 5b 53 51 integer .** [SQ
7ac0: 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 LITE_COPY | acti
7ad0: 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 on code] that sp
7ae0: 65 63 69 66 69 65 73 20 74 68 65 20 70 61 72 74 ecifies the part
7af0: 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a 2a icular action.**
7b00: 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 to be authorize
7b10: 64 2e 20 20 54 68 65 20 61 76 61 69 6c 61 62 6c d. The availabl
7b20: 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 61 e action codes a
7b30: 72 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f re.** [SQLITE_CO
7b40: 50 59 20 7c 20 64 6f 63 75 6d 65 6e 74 65 64 20 PY | documented
7b50: 73 65 70 61 72 61 74 65 6c 79 5d 2e 20 20 54 68 separately]. Th
7b60: 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 e third through
7b70: 73 69 78 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 sixth.** paramet
7b80: 65 72 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 ers to the callb
7b90: 61 63 6b 20 61 72 65 20 73 74 72 69 6e 67 73 20 ack are strings
7ba0: 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 that contain add
7bb0: 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 itional.** detai
7bc0: 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 ls about the act
7bd0: 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 ion to be author
7be0: 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 ized..**.** An a
7bf0: 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 uthorizer is use
7c00: 64 20 77 68 65 6e 20 70 72 65 70 61 72 69 6e 67 d when preparing
7c10: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
7c20: 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 from an untruste
7c30: 64 0a 2a 2a 20 73 6f 75 72 63 65 2c 20 74 6f 20 d.** source, to
7c40: 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 ensure that the
7c50: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 64 SQL statements d
7c60: 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 o not try to acc
7c70: 65 73 73 20 64 61 74 61 0a 2a 2a 20 74 68 61 74 ess data.** that
7c80: 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c they are not al
7c90: 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 lowed to see, or
7ca0: 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f that they do no
7cb0: 74 20 74 72 79 20 74 6f 0a 2a 2a 20 65 78 65 63 t try to.** exec
7cc0: 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 ute malicious st
7cd0: 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 atements that da
7ce0: 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 mage the databas
7cf0: 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 e. For.** examp
7d00: 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 le, an applicati
7d10: 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 on may allow a u
7d20: 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 ser to enter arb
7d30: 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 itrary.** SQL qu
7d40: 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 eries for evalua
7d50: 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 tion by a databa
7d60: 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 se. But the app
7d70: 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a lication does.**
7d80: 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 not want the us
7d90: 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f er to be able to
7da0: 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 make arbitrary
7db0: 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a changes to the.*
7dc0: 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 * database. An
7dd0: 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 authorizer could
7de0: 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 then be put in
7df0: 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a place while the.
7e00: 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 ** user-entered
7e10: 53 51 4c 20 69 73 20 62 65 69 6e 67 20 70 72 65 SQL is being pre
7e20: 70 61 72 65 64 20 74 68 61 74 20 64 69 73 61 6c pared that disal
7e30: 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 0a lows everything.
7e40: 2a 2a 20 65 78 63 65 70 74 20 53 45 4c 45 43 54 ** except SELECT
7e50: 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 0a 2a statements. .*
7e60: 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e 67 *.** Only a sing
7e70: 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 le authorizer ca
7e80: 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e n be in place on
7e90: 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a database conn
7ea0: 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 ection.** at a t
7eb0: 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 ime. Each call
7ec0: 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 to sqlite3_set_a
7ed0: 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 uthorizer overri
7ee0: 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 des the.** previ
7ef0: 6f 75 73 20 63 61 6c 6c 2e 20 20 41 20 4e 55 4c ous call. A NUL
7f00: 4c 20 61 75 74 68 6f 72 69 7a 65 72 20 6d 65 61 L authorizer mea
7f10: 6e 73 20 74 68 61 74 20 6e 6f 20 61 75 74 68 6f ns that no autho
7f20: 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c rization.** call
7f30: 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e back is invoked.
7f40: 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 61 75 The default au
7f50: 74 68 6f 72 69 7a 65 72 20 69 73 20 4e 55 4c 4c thorizer is NULL
7f60: 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ..**.** Note tha
7f70: 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 t the authorizer
7f80: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
7f90: 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 oked only during
7fa0: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 .** [sqlite3_pr
7fb0: 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 epare()] or its
7fc0: 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f variants. Autho
7fd0: 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a rization is not.
7fe0: 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 ** performed dur
7ff0: 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 ing statement ev
8000: 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c aluation in [sql
8010: 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2f ite3_step()]..*/
8020: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 .int sqlite3_set
8030: 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 _authorizer(. s
8040: 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 qlite3*,. int (
8050: 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e *xAuth)(void*,in
8060: 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f t,const char*,co
8070: 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 nst char*,const
8080: 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 char*,const char
8090: 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 *),. void *pUse
80a0: 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 rData.);../*.**
80b0: 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 CAPI3REF: Author
80c0: 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 izer Return Code
80d0: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c s.**.** The [sql
80e0: 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
80f0: 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 zer | authorizer
8100: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
8110: 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 on] must.** retu
8120: 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 rn either [SQLIT
8130: 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 E_OK] or one of
8140: 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 these two consta
8150: 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 nts in order.**
8160: 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 to signal SQLite
8170: 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
8180: 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 the action is pe
8190: 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 rmitted. See th
81a0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 e.** [sqlite3_se
81b0: 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 t_authorizer | a
81c0: 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 uthorizer docume
81d0: 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 ntation] for add
81e0: 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 itional.** infor
81f0: 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 mation..*/.#defi
8200: 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 ne SQLITE_DENY
8210: 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 1 /* Abort th
8220: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
8230: 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f with an error */
8240: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8250: 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f IGNORE 2 /* Do
8260: 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 n't allow access
8270: 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 , but don't gene
8280: 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f rate an error */
8290: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
82a0: 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 : Authorizer Act
82b0: 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 ion Codes.**.**
82c0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 The [sqlite3_set
82d0: 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 _authorizer()] i
82e0: 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 nterface registe
82f0: 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 rs a callback fu
8300: 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 nction.** that i
8310: 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 s invoked to aut
8320: 68 6f 72 69 7a 65 72 20 63 65 72 74 61 69 6e 20 horizer certain
8330: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 SQL statement ac
8340: 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 tions. The.** s
8350: 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
8360: 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 to the callback
8370: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f is an integer co
8380: 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 de that specifie
8390: 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e s.** what action
83a0: 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 is being author
83b0: 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 ized. These are
83c0: 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 the integer act
83d0: 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a ion codes that.*
83e0: 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 * the authorizer
83f0: 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 callback may be
8400: 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 passed..**.** T
8410: 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 hese action code
8420: 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 values signify
8430: 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 what kind of ope
8440: 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 ration is to be
8450: 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 .** authorized.
8460: 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 The 3rd and 4th
8470: 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 parameters to t
8480: 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e he authorization
8490: 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e callback.** fun
84a0: 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 ction will be pa
84b0: 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c rameters or NULL
84c0: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 depending on wh
84d0: 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 ich of these.**
84e0: 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 codes is used as
84f0: 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 the second para
8500: 6d 65 74 65 72 2e 20 20 54 68 65 20 35 74 68 20 meter. The 5th
8510: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
8520: 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 .** authorizer c
8530: 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e allback is the n
8540: 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 ame of the datab
8550: 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 ase ("main", "te
8560: 6d 70 22 2c 20 0a 2a 2a 20 65 74 63 2e 29 20 69 mp", .** etc.) i
8570: 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 20 20 54 f applicable. T
8580: 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 he 6th parameter
8590: 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a to the authoriz
85a0: 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 er callback.** i
85b0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
85c0: 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 e inner-most tri
85d0: 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 gger or view tha
85e0: 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 t is responsible
85f0: 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 for.** the acce
8600: 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 ss attempt or NU
8610: 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 LL if this acces
8620: 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 s attempt is dir
8630: 65 63 74 6c 79 20 66 72 6f 6d 20 0a 2a 2a 20 74 ectly from .** t
8640: 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 op-level SQL cod
8650: 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a e..*/./*********
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 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a ** 3rd *********
8690: 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a *** 4th ********
86a0: 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ***/.#define SQL
86b0: 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 ITE_CREATE_INDEX
86c0: 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 1 /*
86d0: 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 Index Name
86e0: 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
86f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
8700: 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 TE_CREATE_TABLE
8710: 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 2 /*
8720: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
8730: 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
8740: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
8750: 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e E_CREATE_TEMP_IN
8760: 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 DEX 3 /* I
8770: 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 ndex Name T
8780: 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
8790: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
87a0: 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 _CREATE_TEMP_TAB
87b0: 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 LE 4 /* Ta
87c0: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
87d0: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
87e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
87f0: 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 CREATE_TEMP_TRIG
8800: 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 GER 5 /* Tri
8810: 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 gger Name Tab
8820: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
8830: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
8840: 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 REATE_TEMP_VIEW
8850: 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 6 /* View
8860: 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c Name NULL
8870: 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
8880: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
8890: 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 EATE_TRIGGER
88a0: 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 7 /* Trigg
88b0: 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 er Name Table
88c0: 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
88d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
88e0: 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 ATE_VIEW
88f0: 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 8 /* View N
8900: 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 ame NULL
8910: 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
8920: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 fine SQLITE_DELE
8930: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TE
8940: 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 9 /* Table N
8950: 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
8960: 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
8970: 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
8980: 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 INDEX
8990: 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 10 /* Index Na
89a0: 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 me Table Na
89b0: 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
89c0: 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
89d0: 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 ABLE 1
89e0: 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 1 /* Table Nam
89f0: 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
8a00: 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
8a10: 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 e SQLITE_DROP_TE
8a20: 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 MP_INDEX 12
8a30: 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 /* Index Name
8a40: 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 Table Name
8a50: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
8a60: 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d SQLITE_DROP_TEM
8a70: 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 P_TABLE 13
8a80: 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
8a90: 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
8aa0: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
8ab0: 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 SQLITE_DROP_TEMP
8ac0: 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20 _TRIGGER 14
8ad0: 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 /* Trigger Name
8ae0: 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
8af0: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
8b00: 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f QLITE_DROP_TEMP_
8b10: 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20 VIEW 15
8b20: 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 /* View Name
8b30: 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
8b40: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
8b50: 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 LITE_DROP_TRIGGE
8b60: 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f R 16 /
8b70: 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 * Trigger Name
8b80: 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
8b90: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
8ba0: 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 ITE_DROP_VIEW
8bb0: 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 17 /*
8bc0: 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 View Name
8bd0: 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
8be0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
8bf0: 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 TE_INSERT
8c00: 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 18 /*
8c10: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
8c20: 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
8c30: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
8c40: 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 E_PRAGMA
8c50: 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 19 /* P
8c60: 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 ragma Name 1
8c70: 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a st arg or NULL *
8c80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
8c90: 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 _READ
8ca0: 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 20 /* Ta
8cb0: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f ble Name Co
8cc0: 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f lumn Name */
8cd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8ce0: 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 SELECT
8cf0: 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 21 /* NUL
8d00: 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c L NUL
8d10: 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
8d20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
8d30: 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 RANSACTION
8d40: 20 20 20 20 32 32 20 20 20 2f 2a 20 4e 55 4c 4c 22 /* NULL
8d50: 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c NULL
8d60: 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
8d70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 define SQLITE_UP
8d80: 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 DATE
8d90: 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 23 /* Table
8da0: 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d Name Colum
8db0: 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 n Name */.#d
8dc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 efine SQLITE_ATT
8dd0: 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 ACH
8de0: 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 24 /* Filena
8df0: 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 me NULL
8e00: 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
8e10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 fine SQLITE_DETA
8e20: 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 CH
8e30: 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 25 /* Databas
8e40: 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 e Name NULL
8e50: 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
8e60: 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 ine SQLITE_ALTER
8e70: 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 _TABLE
8e80: 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 26 /* Database
8e90: 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 Name Table Na
8ea0: 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
8eb0: 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 ne SQLITE_REINDE
8ec0: 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 X 2
8ed0: 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 7 /* Index Nam
8ee0: 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
8ef0: 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
8f00: 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 e SQLITE_ANALYZE
8f10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38 28
8f20: 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
8f30: 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
8f40: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
8f50: 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 SQLITE_CREATE_V
8f60: 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 TABLE 29
8f70: 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
8f80: 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 Module Name
8f90: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
8fa0: 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 SQLITE_DROP_VTAB
8fb0: 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20 LE 30
8fc0: 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
8fd0: 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 Module Name
8fe0: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
8ff0: 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 QLITE_FUNCTION
9000: 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20 31
9010: 2f 2a 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 /* Function Name
9020: 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
9030: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
9040: 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 LITE_COPY
9050: 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 0 /
9060: 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 * No longer used
9070: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */../*.** CAPI3
9080: 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 REF: Tracing And
9090: 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 Profiling Funct
90a0: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ions.**.** These
90b0: 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 routines regist
90c0: 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 er callback func
90d0: 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 tions that can b
90e0: 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 e used for.** tr
90f0: 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c acing and profil
9100: 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f ing the executio
9110: 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 n of SQL stateme
9120: 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c nts..** The call
9130: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 back function re
9140: 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 gistered by sqli
9150: 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 te3_trace() is i
9160: 6e 76 6f 6b 65 64 0a 2a 2a 20 61 74 20 74 68 65 nvoked.** at the
9170: 20 66 69 72 73 74 20 5b 73 71 6c 69 74 65 33 5f first [sqlite3_
9180: 73 74 65 70 28 29 5d 20 66 6f 72 20 74 68 65 20 step()] for the
9190: 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e evaluation of an
91a0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a SQL statement..
91b0: 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 ** The callback
91c0: 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 function registe
91d0: 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 red by sqlite3_p
91e0: 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f rofile() is invo
91f0: 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 ked.** as each S
9200: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e QL statement fin
9210: 69 73 68 65 73 20 61 6e 64 20 69 6e 63 6c 75 64 ishes and includ
9220: 65 73 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f es.** informatio
9230: 6e 20 6f 6e 20 68 6f 77 20 6c 6f 6e 67 20 74 68 n on how long th
9240: 61 74 20 73 74 61 74 65 6d 65 6e 74 20 72 61 6e at statement ran
9250: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
9260: 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 41 50 te3_profile() AP
9270: 49 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 I is currently c
9280: 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69 onsidered experi
9290: 6d 65 6e 74 61 6c 20 61 6e 64 0a 2a 2a 20 69 73 mental and.** is
92a0: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e subject to chan
92b0: 67 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c ge..*/.void *sql
92c0: 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 ite3_trace(sqlit
92d0: 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 e3*, void(*xTrac
92e0: 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 e)(void*,const c
92f0: 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 har*), void*);.v
9300: 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f oid *sqlite3_pro
9310: 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 file(sqlite3*,.
9320: 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 void(*xProfile
9330: 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 )(void*,const ch
9340: 61 72 2a 2c 73 71 6c 69 74 65 5f 75 69 6e 74 36 ar*,sqlite_uint6
9350: 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 4), void*);../*.
9360: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 ** CAPI3REF: Que
9370: 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c ry Progress Call
9380: 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 backs.**.** This
9390: 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 routine configu
93a0: 72 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 res a callback f
93b0: 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65 20 70 72 unction - the pr
93c0: 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 ogress callback
93d0: 2d 20 74 68 61 74 0a 2a 2a 20 69 73 20 69 6e 76 - that.** is inv
93e0: 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c oked periodicall
93f0: 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 y during long ru
9400: 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b nning calls to [
9410: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c sqlite3_exec()],
9420: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 .** [sqlite3_ste
9430: 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 p()] and [sqlite
9440: 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20 3_get_table()].
9450: 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 An example use
9460: 66 6f 72 20 74 68 69 73 20 0a 2a 2a 20 69 6e 74 for this .** int
9470: 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 erface is to kee
9480: 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 p a GUI updated
9490: 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 during a large q
94a0: 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 uery..**.** The
94b0: 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 progress callbac
94c0: 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 k is invoked onc
94d0: 65 20 66 6f 72 20 65 76 65 72 79 20 4e 20 76 69 e for every N vi
94e0: 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 6f 70 rtual machine op
94f0: 63 6f 64 65 73 2c 0a 2a 2a 20 77 68 65 72 65 20 codes,.** where
9500: 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 N is the second
9510: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 argument to this
9520: 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 70 function. The p
9530: 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b rogress callback
9540: 0a 2a 2a 20 69 74 73 65 6c 66 20 69 73 20 69 64 .** itself is id
9550: 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 entified by the
9560: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 third argument t
9570: 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e o this function.
9580: 20 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20 61 The fourth.** a
9590: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 rgument to this
95a0: 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 76 6f function is a vo
95b0: 69 64 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 id pointer passe
95c0: 64 20 74 6f 20 74 68 65 20 70 72 6f 67 72 65 73 d to the progres
95d0: 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 s callback.** fu
95e0: 6e 63 74 69 6f 6e 20 65 61 63 68 20 74 69 6d 65 nction each time
95f0: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a it is invoked..
9600: 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 61 6c 6c 20 **.** If a call
9610: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 to [sqlite3_exec
9620: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 ()], [sqlite3_st
9630: 65 70 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 ep()], or [sqlit
9640: 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 0a e3_get_table()].
9650: 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 20 66 65 ** results in fe
9660: 77 65 72 20 74 68 61 6e 20 4e 20 6f 70 63 6f 64 wer than N opcod
9670: 65 73 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 es being execute
9680: 64 2c 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 d, then the prog
9690: 72 65 73 73 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 ress .** callbac
96a0: 6b 20 69 73 20 6e 65 76 65 72 20 69 6e 76 6f 6b k is never invok
96b0: 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 4f 6e 6c 79 20 ed..** .** Only
96c0: 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 a single progres
96d0: 73 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 s callback funct
96e0: 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 ion may be regis
96f0: 74 65 72 65 64 20 66 6f 72 20 65 61 63 68 0a 2a tered for each.*
9700: 2a 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 * open database
9710: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 45 76 65 connection. Eve
9720: 72 79 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 ry call to sqlit
9730: 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 e3_progress_hand
9740: 6c 65 72 28 29 0a 2a 2a 20 6f 76 65 72 77 72 69 ler().** overwri
9750: 74 65 73 20 74 68 65 20 72 65 73 75 6c 74 73 20 tes the results
9760: 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 of the previous
9770: 63 61 6c 6c 2e 0a 2a 2a 20 54 6f 20 72 65 6d 6f call..** To remo
9780: 76 65 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 ve the progress
9790: 63 61 6c 6c 62 61 63 6b 20 61 6c 74 6f 67 65 74 callback altoget
97a0: 68 65 72 2c 20 70 61 73 73 20 4e 55 4c 4c 20 61 her, pass NULL a
97b0: 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 s the third.** a
97c0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 rgument to this
97d0: 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 function..**.**
97e0: 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 If the progress
97f0: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
9800: 20 61 20 72 65 73 75 6c 74 20 6f 74 68 65 72 20 a result other
9810: 74 68 61 6e 20 30 2c 20 74 68 65 6e 20 74 68 65 than 0, then the
9820: 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 71 75 65 current .** que
9830: 72 79 20 69 73 20 69 6d 6d 65 64 69 61 74 65 6c ry is immediatel
9840: 79 20 74 65 72 6d 69 6e 61 74 65 64 20 61 6e 64 y terminated and
9850: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 68 any database ch
9860: 61 6e 67 65 73 20 72 6f 6c 6c 65 64 20 62 61 63 anges rolled bac
9870: 6b 2e 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 61 69 k..** The contai
9880: 6e 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 ning [sqlite3_ex
9890: 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f ec()], [sqlite3_
98a0: 73 74 65 70 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b step()], or.** [
98b0: 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
98c0: 65 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e e()] call return
98d0: 73 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 s SQLITE_INTERRU
98e0: 50 54 2e 20 20 20 54 68 69 73 20 66 65 61 74 75 PT. This featu
98f0: 72 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 re.** can be use
9900: 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 d, for example,
9910: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 to implement the
9920: 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e "Cancel" button
9930: 20 6f 6e 20 61 0a 2a 2a 20 70 72 6f 67 72 65 73 on a.** progres
9940: 73 20 64 69 61 6c 6f 67 20 62 6f 78 20 69 6e 20 s dialog box in
9950: 61 20 47 55 49 2e 0a 2a 2f 0a 76 6f 69 64 20 73 a GUI..*/.void s
9960: 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f qlite3_progress_
9970: 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a handler(sqlite3*
9980: 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f , int, int(*)(vo
9990: 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f id*), void*);../
99a0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
99b0: 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 pening A New Dat
99c0: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e abase Connection
99d0: 0a 2a 2a 0a 2a 2a 20 4f 70 65 6e 20 74 68 65 20 .**.** Open the
99e0: 73 71 6c 69 74 65 20 64 61 74 61 62 61 73 65 20 sqlite database
99f0: 66 69 6c 65 20 22 66 69 6c 65 6e 61 6d 65 22 2e file "filename".
9a00: 20 20 54 68 65 20 22 66 69 6c 65 6e 61 6d 65 22 The "filename"
9a10: 20 69 73 20 55 54 46 2d 38 0a 2a 2a 20 65 6e 63 is UTF-8.** enc
9a20: 6f 64 65 64 20 66 6f 72 20 73 71 6c 69 74 65 33 oded for sqlite3
9a30: 5f 6f 70 65 6e 28 29 20 61 6e 64 20 55 54 46 2d _open() and UTF-
9a40: 31 36 20 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 16 encoded in th
9a50: 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 e native byte or
9a60: 64 65 72 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 der.** for sqlit
9a70: 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 20 41 6e e3_open16(). An
9a80: 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64 [sqlite3*] hand
9a90: 6c 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 le is returned i
9aa0: 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 0a 2a 2a n *ppDb, even.**
9ab0: 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 if an error occ
9ac0: 75 72 73 2e 20 49 66 20 74 68 65 20 64 61 74 61 urs. If the data
9ad0: 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 base is opened (
9ae0: 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63 or created) succ
9af0: 65 73 73 66 75 6c 6c 79 2c 0a 2a 2a 20 74 68 65 essfully,.** the
9b00: 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 n SQLITE_OK is r
9b10: 65 74 75 72 6e 65 64 2e 20 4f 74 68 65 72 77 69 eturned. Otherwi
9b20: 73 65 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 se an error code
9b30: 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 54 68 is returned. Th
9b40: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 e.** sqlite3_err
9b50: 6d 73 67 28 29 20 6f 72 20 73 71 6c 69 74 65 33 msg() or sqlite3
9b60: 5f 65 72 72 6d 73 67 31 36 28 29 20 20 72 6f 75 _errmsg16() rou
9b70: 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 tines can be use
9b80: 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 d to obtain.** a
9b90: 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 n English langua
9ba0: 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f ge description o
9bb0: 66 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a f the error..**.
9bc0: 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 ** If the databa
9bd0: 73 65 20 66 69 6c 65 20 64 6f 65 73 20 6e 6f 74 se file does not
9be0: 20 65 78 69 73 74 2c 20 74 68 65 6e 20 61 20 6e exist, then a n
9bf0: 65 77 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c ew database will
9c00: 20 62 65 20 63 72 65 61 74 65 64 0a 2a 2a 20 61 be created.** a
9c10: 73 20 6e 65 65 64 65 64 2e 20 20 54 68 65 20 64 s needed. The d
9c20: 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 efault encoding
9c30: 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 for the database
9c40: 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 will be UTF-8 i
9c50: 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 f.** sqlite3_ope
9c60: 6e 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e n() is called an
9c70: 64 20 55 54 46 2d 31 36 20 69 66 20 73 71 6c 69 d UTF-16 if sqli
9c80: 74 65 33 5f 6f 70 65 6e 31 36 20 69 73 20 75 73 te3_open16 is us
9c90: 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 ed..**.** Whethe
9ca0: 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f r or not an erro
9cb0: 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 r occurs when it
9cc0: 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f is opened, reso
9cd0: 75 72 63 65 73 20 61 73 73 6f 63 69 61 74 65 64 urces associated
9ce0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71 .** with the [sq
9cf0: 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20 73 lite3*] handle s
9d00: 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 hould be release
9d10: 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 74 20 d by passing it
9d20: 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c to.** sqlite3_cl
9d30: 6f 73 65 28 29 20 77 68 65 6e 20 69 74 20 69 73 ose() when it is
9d40: 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 no longer requi
9d50: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 red..**.** Note
9d60: 74 6f 20 77 69 6e 64 6f 77 73 20 75 73 65 72 73 to windows users
9d70: 3a 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 : The encoding
9d80: 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c used for the fil
9d90: 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a ename argument.*
9da0: 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 * of sqlite3_ope
9db0: 6e 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d n() must be UTF-
9dc0: 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 20 8, not whatever
9dd0: 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 codepage is curr
9de0: 65 6e 74 6c 79 0a 2a 2a 20 64 65 66 69 6e 65 64 ently.** defined
9df0: 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e . Filenames con
9e00: 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 taining internat
9e10: 69 6f 6e 61 6c 20 63 68 61 72 61 63 74 65 72 73 ional characters
9e20: 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 must be convert
9e30: 65 64 0a 2a 2a 20 74 6f 20 55 54 46 2d 38 20 70 ed.** to UTF-8 p
9e40: 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 rior to passing
9e50: 74 68 65 6d 20 69 6e 74 6f 20 73 71 6c 69 74 65 them into sqlite
9e60: 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2f 0a 69 6e 74 3_open()..*/.int
9e70: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 sqlite3_open(.
9e80: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c const char *fil
9e90: 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 ename, /* Data
9ea0: 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 base filename (U
9eb0: 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 TF-8) */. sqlit
9ec0: 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 e3 **ppDb
9ed0: 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 /* OUT: SQLit
9ee0: 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 e db handle */.)
9ef0: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 ;.int sqlite3_op
9f00: 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f en16(. const vo
9f10: 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 id *filename,
9f20: 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 /* Database file
9f30: 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f name (UTF-16) */
9f40: 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 . sqlite3 **ppD
9f50: 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 b /* OU
9f60: 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e T: SQLite db han
9f70: 64 6c 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a dle */.);../*.**
9f80: 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 CAPI3REF: Error
9f90: 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 Codes And Messa
9fa0: 67 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ges.**.** The sq
9fb0: 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 lite3_errcode()
9fc0: 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
9fd0: 73 20 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a s the numeric.**
9fe0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 [SQLITE_OK | re
9ff0: 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 53 sult code] or [S
a000: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 QLITE_IOERR_READ
a010: 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 | extended resu
a020: 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20 66 6f 72 20 lt code].** for
a030: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
a040: 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a failed sqlite3_*
a050: 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 API call associ
a060: 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 5b 73 71 ated.** with [sq
a070: 6c 69 74 65 33 5d 20 68 61 6e 64 6c 65 20 27 64 lite3] handle 'd
a080: 62 27 2e 20 20 49 66 20 61 20 70 72 69 6f 72 20 b'. If a prior
a090: 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 20 API call failed
a0a0: 62 75 74 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 but the.** most
a0b0: 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 recent API call
a0c0: 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 succeeded, the r
a0d0: 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d eturn value from
a0e0: 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 sqlite3_errcode
a0f0: 28 29 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e ().** is undefin
a100: 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ed. .**.** The s
a110: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 qlite3_errmsg()
a120: 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d and sqlite3_errm
a130: 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e sg16() return En
a140: 67 6c 69 73 68 2d 6c 61 6e 67 61 75 67 65 0a 2a glish-langauge.*
a150: 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 * text that desc
a160: 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c ribes the error,
a170: 20 61 73 20 65 69 74 68 65 72 20 55 54 46 38 20 as either UTF8
a180: 6f 72 20 55 54 46 31 36 20 72 65 73 70 65 63 74 or UTF16 respect
a190: 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 ively..** Memory
a1a0: 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 to hold the err
a1b0: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e or message strin
a1c0: 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 g is managed int
a1d0: 65 72 6e 61 6c 6c 79 2e 20 20 54 68 65 20 0a 2a ernally. The .*
a1e0: 2a 20 73 74 72 69 6e 67 20 6d 61 79 20 62 65 20 * string may be
a1f0: 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 overwritten or d
a200: 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 75 eallocated by su
a210: 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 bsequent calls t
a220: 6f 20 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 o SQLite.** inte
a230: 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e rface functions.
a240: 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 73 20 74 6f 20 .**.** Calls to
a250: 6d 61 6e 79 20 73 71 6c 69 74 65 33 5f 2a 20 66 many sqlite3_* f
a260: 75 6e 63 74 69 6f 6e 73 20 73 65 74 20 74 68 65 unctions set the
a270: 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 error code and
a280: 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64 0a string returned.
a290: 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 ** by [sqlite3_e
a2a0: 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69 rrcode()], [sqli
a2b0: 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 te3_errmsg()], a
a2c0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d nd [sqlite3_errm
a2d0: 73 67 31 36 28 29 5d 0a 2a 2a 20 28 6f 76 65 72 sg16()].** (over
a2e0: 77 72 69 74 69 6e 67 20 74 68 65 20 70 72 65 76 writing the prev
a2f0: 69 6f 75 73 20 76 61 6c 75 65 73 29 2e 20 4e 6f ious values). No
a300: 74 65 20 74 68 61 74 20 63 61 6c 6c 73 20 74 6f te that calls to
a310: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 [sqlite3_errcod
a320: 65 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 e()],.** [sqlite
a330: 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64 3_errmsg()], and
a340: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
a350: 31 36 28 29 5d 20 74 68 65 6d 73 65 6c 76 65 73 16()] themselves
a360: 20 64 6f 20 6e 6f 74 20 61 66 66 65 63 74 20 74 do not affect t
a370: 68 65 0a 2a 2a 20 72 65 73 75 6c 74 73 20 6f 66 he.** results of
a380: 20 66 75 74 75 72 65 20 69 6e 76 6f 63 61 74 69 future invocati
a390: 6f 6e 73 2e 20 20 43 61 6c 6c 73 20 74 6f 20 41 ons. Calls to A
a3a0: 50 49 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 PI routines that
a3b0: 20 64 6f 20 6e 6f 74 20 72 65 74 75 72 6e 0a 2a do not return.*
a3c0: 2a 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 * an error code
a3d0: 28 65 78 61 6d 70 6c 65 73 3a 20 5b 73 71 6c 69 (examples: [sqli
a3e0: 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 te3_data_count()
a3f0: 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6d 70 ] or [sqlite3_mp
a400: 72 69 6e 74 66 28 29 5d 29 20 64 6f 0a 2a 2a 20 rintf()]) do.**
a410: 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 65 not change the e
a420: 72 72 6f 72 20 63 6f 64 65 20 72 65 74 75 72 6e rror code return
a430: 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 ed by this routi
a440: 6e 65 2e 0a 2a 2a 0a 2a 2a 20 41 73 73 75 6d 69 ne..**.** Assumi
a450: 6e 67 20 6e 6f 20 6f 74 68 65 72 20 69 6e 74 65 ng no other inte
a460: 72 76 65 6e 69 6e 67 20 73 71 6c 69 74 65 33 5f rvening sqlite3_
a470: 2a 20 41 50 49 20 63 61 6c 6c 73 20 61 72 65 20 * API calls are
a480: 6d 61 64 65 2c 20 74 68 65 20 65 72 72 6f 72 0a made, the error.
a490: 2a 2a 20 63 6f 64 65 20 72 65 74 75 72 6e 65 64 ** code returned
a4a0: 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f by this functio
a4b0: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 n is associated
a4c0: 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 65 72 with the same er
a4d0: 72 6f 72 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 ror as.** the st
a4e0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 rings returned b
a4f0: 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 y [sqlite3_errms
a500: 67 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 g()] and [sqlite
a510: 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 3_errmsg16()]..*
a520: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 /.int sqlite3_er
a530: 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 rcode(sqlite3 *d
a540: 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a b);.const char *
a550: 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 sqlite3_errmsg(s
a560: 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 qlite3*);.const
a570: 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 void *sqlite3_er
a580: 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 rmsg16(sqlite3*)
a590: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
a5a0: 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 F: SQL Statement
a5b0: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 49 6e Object.**.** In
a5c0: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f stance of this o
a5d0: 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 20 bject represent
a5e0: 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 single SQL state
a5f0: 6d 65 6e 74 73 2e 20 20 54 68 69 73 0a 2a 2a 20 ments. This.**
a600: 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f is variously kno
a610: 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 wn as a "prepare
a620: 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 d statement" or
a630: 61 20 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 a .** "compiled
a640: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f SQL statement" o
a650: 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 r simply as a "s
a660: 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 20 0a 2a tatement"..** .*
a670: 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 * The life of a
a680: 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 statement object
a690: 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 goes something
a6a0: 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a like this:.**.**
a6b0: 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 <ol>.** <li> Cr
a6c0: 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 eate the object
a6d0: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 using [sqlite3_p
a6e0: 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
a6f0: 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 a related.**
a700: 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c function..** <
a710: 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 li> Bind values
a720: 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 to host paramete
a730: 72 73 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 rs using.**
a740: 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
a750: 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 lob | sqlite3_bi
a760: 6e 64 5f 2a 20 69 6e 74 65 72 66 61 63 65 73 5d nd_* interfaces]
a770: 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 ..** <li> Run th
a780: 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 e SQL by calling
a790: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
a7a0: 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 ] one or more ti
a7b0: 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 mes..** <li> Res
a7c0: 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 et the statement
a7d0: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
a7e0: 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f reset()] then go
a7f0: 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f back.** to
a800: 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 step 2. Do thi
a810: 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 s zero or more t
a820: 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 imes..** <li> De
a830: 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 stroy the object
a840: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
a850: 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 finalize()]..**
a860: 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 </ol>.**.** Refe
a870: 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 r to documentati
a880: 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c on on individual
a890: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 methods above f
a8a0: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a or additional.**
a8b0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f information..*/
a8c0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
a8d0: 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c sqlite3_stmt sql
a8e0: 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a ite3_stmt;../*.*
a8f0: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 * CAPI3REF: Comp
a900: 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 iling An SQL Sta
a910: 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 tement.**.** To
a920: 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 execute an SQL q
a930: 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 uery, it must fi
a940: 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 rst be compiled
a950: 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 into a byte-code
a960: 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e .** program usin
a970: 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 g one of these r
a980: 6f 75 74 69 6e 65 73 2e 20 0a 2a 2a 0a 2a 2a 20 outines. .**.**
a990: 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
a9a0: 6e 74 20 22 64 62 22 20 69 73 20 61 6e 20 5b 73 nt "db" is an [s
a9b0: 71 6c 69 74 65 33 20 7c 20 53 51 4c 69 74 65 20 qlite3 | SQLite
a9c0: 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 5d database handle]
a9d0: 20 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 .** obtained fr
a9e0: 6f 6d 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 om a prior call
a9f0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e to [sqlite3_open
aa00: 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
aa10: 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 54 68 open16()]..** Th
aa20: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
aa30: 74 20 22 7a 53 71 6c 22 20 69 73 20 74 68 65 20 t "zSql" is the
aa40: 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 statement to be
aa50: 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 compiled, encode
aa60: 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 d.** as either U
aa70: 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 TF-8 or UTF-16.
aa80: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 The sqlite3_pre
aa90: 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 pare() and sqlit
aaa0: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a e3_prepare_v2().
aab0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 ** interfaces us
aac0: 65 73 20 55 54 46 2d 38 20 61 6e 64 20 73 71 6c es UTF-8 and sql
aad0: 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
aae0: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 and sqlite3_pre
aaf0: 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 pare16_v2().** u
ab00: 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a se UTF-16..**.**
ab10: 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 If the nByte ar
ab20: 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 0a 2a gument is less.*
ab30: 2a 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 * than zero, the
ab40: 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 n zSql is read u
ab50: 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a p to the first z
ab60: 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 ero terminator.
ab70: 20 49 66 0a 2a 2a 20 6e 42 79 74 65 20 69 73 20 If.** nByte is
ab80: 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 non-negative, th
ab90: 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 en it is the max
aba0: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 0a imum number of .
abb0: 2a 2a 20 62 79 74 65 73 20 72 65 61 64 20 66 72 ** bytes read fr
abc0: 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20 6e om zSql. When n
abd0: 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 Byte is non-nega
abe0: 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 tive, the.** zSq
abf0: 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 l string ends at
ac00: 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73 either the firs
ac10: 74 20 27 5c 30 30 30 27 20 63 68 61 72 61 63 74 t '\000' charact
ac20: 65 72 20 6f 72 20 0a 2a 2a 20 75 6e 74 69 6c 20 er or .** until
ac30: 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 the nByte-th byt
ac40: 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d e, whichever com
ac50: 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 es first..**.**
ac60: 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 *pzTail is made
ac70: 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 to point to the
ac80: 66 69 72 73 74 20 62 79 74 65 20 70 61 73 74 20 first byte past
ac90: 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 the end of the f
aca0: 69 72 73 74 0a 2a 2a 20 53 51 4c 20 73 74 61 74 irst.** SQL stat
acb0: 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 ement in zSql.
acc0: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c This routine onl
acd0: 79 20 63 6f 6d 70 69 6c 65 73 20 74 68 65 20 66 y compiles the f
ace0: 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 0a 2a irst statement.*
acf0: 2a 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 * in zSql, so *p
ad00: 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f zTail is left po
ad10: 69 6e 74 69 6e 67 20 74 6f 20 77 68 61 74 20 72 inting to what r
ad20: 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 emains uncompile
ad30: 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 d..**.** *ppStmt
ad40: 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e is left pointin
ad50: 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 g to a compiled
ad60: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d .** [sqlite3_stm
ad70: 74 20 7c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e t | SQL statemen
ad80: 74 20 73 74 72 75 63 74 75 72 65 5d 20 74 68 61 t structure] tha
ad90: 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 t can be.** exec
ada0: 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 uted using [sqli
adb0: 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 4f 72 te3_step()]. Or
adc0: 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 if there is an
add0: 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 6d error, *ppStmt m
ade0: 61 79 20 62 65 0a 2a 2a 20 73 65 74 20 74 6f 20 ay be.** set to
adf0: 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 69 6e NULL. If the in
ae00: 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e put text contain
ae10: 65 64 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 ed no SQL (if th
ae20: 65 20 69 6e 70 75 74 20 69 73 20 61 6e 64 0a 2a e input is and.*
ae30: 2a 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f * empty string o
ae40: 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 r a comment) the
ae50: 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 n *ppStmt is set
ae60: 20 74 6f 20 4e 55 4c 4c 2e 20 20 54 68 65 20 63 to NULL. The c
ae70: 61 6c 6c 69 6e 67 0a 2a 2a 20 70 72 6f 63 65 64 alling.** proced
ae80: 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 ure is responsib
ae90: 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 le for deleting
aea0: 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c the compiled SQL
aeb0: 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 75 73 statement.** us
aec0: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e ing [sqlite3_fin
aed0: 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 alize()] after i
aee0: 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 t has finished w
aef0: 69 74 68 20 69 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e ith it..**.** On
af00: 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 success, [SQLIT
af10: 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 E_OK] is returne
af20: 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e d. Otherwise an
af30: 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 .** [SQLITE_ERR
af40: 4f 52 20 7c 20 65 72 72 6f 72 20 63 6f 64 65 5d OR | error code]
af50: 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
af60: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
af70: 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 prepare_v2() and
af80: 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
af90: 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 16_v2() interfac
afa0: 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d es are.** recomm
afb0: 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 ended for all ne
afc0: 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 w programs. The
afd0: 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 two older interf
afe0: 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 aces are retaine
aff0: 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 d.** for backwar
b000: 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ds compatibility
b010: 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 , but their use
b020: 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a is discouraged..
b030: 2a 2a 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 ** In the "v2" i
b040: 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 nterfaces, the p
b050: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
b060: 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 t.** that is ret
b070: 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 urned (the [sqli
b080: 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 te3_stmt] object
b090: 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 ) contains a cop
b0a0: 79 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6f 72 69 y of the .** ori
b0b0: 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 ginal SQL text.
b0c0: 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 This causes the
b0d0: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
b0e0: 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a interface to.**
b0f0: 20 62 65 68 61 76 65 20 61 20 64 69 66 66 65 72 behave a differ
b100: 65 6e 74 6c 79 20 69 6e 20 74 77 6f 20 77 61 79 ently in two way
b110: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a s:.**.** <ol>.**
b120: 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65 20 <li>.** If the
b130: 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 database schema
b140: 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 changes, instead
b150: 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 of returning [S
b160: 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 QLITE_SCHEMA] as
b170: 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 it.** always us
b180: 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 ed to do, [sqlit
b190: 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 e3_step()] will
b1a0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 automatically re
b1b0: 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a compile the SQL.
b1c0: 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 ** statement and
b1d0: 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 try to run it a
b1e0: 67 61 69 6e 2e 20 20 49 66 20 74 68 65 20 73 63 gain. If the sc
b1f0: 68 65 6d 61 20 68 61 73 20 63 68 61 6e 67 65 64 hema has changed
b200: 20 69 6e 20 61 20 77 61 79 0a 2a 2a 20 74 68 61 in a way.** tha
b210: 74 20 6d 61 6b 65 73 20 74 68 65 20 73 74 61 74 t makes the stat
b220: 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 ement no longer
b230: 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f valid, [sqlite3_
b240: 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 69 step()] will sti
b250: 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 ll.** return [SQ
b260: 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42 LITE_SCHEMA]. B
b270: 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65 ut unlike the le
b280: 67 61 63 79 20 62 65 68 61 76 69 6f 72 2c 20 5b gacy behavior, [
b290: 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 69 SQLITE_SCHEMA] i
b2a0: 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61 6c s.** now a fatal
b2b0: 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 error. Calling
b2c0: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
b2d0: 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20 77 69 e_v2()] again wi
b2e0: 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a ll not make the.
b2f0: 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77 61 79 ** error go away
b300: 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71 . Note: use [sq
b310: 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 lite3_errmsg()]
b320: 74 6f 20 66 69 6e 64 20 74 68 65 20 74 65 78 74 to find the text
b330: 20 6f 66 20 74 68 65 20 70 61 72 73 69 6e 67 0a of the parsing.
b340: 2a 2a 20 65 72 72 6f 72 20 74 68 61 74 20 72 65 ** error that re
b350: 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c sults in an [SQL
b360: 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 65 74 75 ITE_SCHEMA] retu
b370: 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a rn..** </li>.**.
b380: 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20 ** <li>.** When
b390: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c an error occurs,
b3a0: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 .** [sqlite3_st
b3b0: 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 ep()] will retur
b3c0: 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 n one of the det
b3d0: 61 69 6c 65 64 20 0a 2a 2a 20 5b 53 51 4c 49 54 ailed .** [SQLIT
b3e0: 45 5f 45 52 52 4f 52 20 7c 20 72 65 73 75 6c 74 E_ERROR | result
b3f0: 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 53 codes] or.** [S
b400: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 QLITE_IOERR_READ
b410: 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 | extended resu
b420: 6c 74 20 63 6f 64 65 73 5d 20 73 75 63 68 20 61 lt codes] such a
b430: 73 20 64 69 72 65 63 74 6c 79 2e 0a 2a 2a 20 54 s directly..** T
b440: 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 he legacy behavi
b450: 6f 72 20 77 61 73 20 74 68 61 74 20 5b 73 71 6c or was that [sql
b460: 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 ite3_step()] wou
b470: 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 ld only return a
b480: 20 67 65 6e 65 72 69 63 0a 2a 2a 20 5b 53 51 4c generic.** [SQL
b490: 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c ITE_ERROR] resul
b4a0: 74 20 63 6f 64 65 20 61 6e 64 20 79 6f 75 20 77 t code and you w
b4b0: 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b ould have to mak
b4c0: 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 e a second call
b4d0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 to.** [sqlite3_r
b4e0: 65 73 65 74 28 29 5d 20 69 6e 20 6f 72 64 65 72 eset()] in order
b4f0: 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 to find the und
b500: 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 erlying cause of
b510: 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 0a 2a 2a the problem..**
b520: 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 With the "v2" p
b530: 72 65 70 61 72 65 20 69 6e 74 65 72 66 61 63 65 repare interface
b540: 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e s, the underlyin
b550: 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 g reason for the
b560: 20 65 72 72 6f 72 20 69 73 0a 2a 2a 20 72 65 74 error is.** ret
b570: 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c urned immediatel
b580: 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c y..** </li>.** <
b590: 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 /ol>.*/.int sqli
b5a0: 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 te3_prepare(. s
b5b0: 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
b5c0: 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 /* Databa
b5d0: 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 se handle */. c
b5e0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c onst char *zSql,
b5f0: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 /* SQL st
b600: 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 atement, UTF-8 e
b610: 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 ncoded */. int
b620: 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 nByte,
b630: 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c /* Maximum l
b640: 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e ength of zSql in
b650: 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c bytes. */. sql
b660: 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 ite3_stmt **ppSt
b670: 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 mt, /* OUT: Sta
b680: 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f tement handle */
b690: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a . const char **
b6a0: 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 pzTail /* OU
b6b0: 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e T: Pointer to un
b6c0: 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 used portion of
b6d0: 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 zSql */.);.int s
b6e0: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
b6f0: 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2(. sqlite3 *db
b700: 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 , /*
b710: 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 Database handle
b720: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
b730: 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 *zSql, /*
b740: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 SQL statement, U
b750: 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a TF-8 encoded */.
b760: 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 int nByte,
b770: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 /* Max
b780: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a imum length of z
b790: 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f Sql in bytes. */
b7a0: 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 . sqlite3_stmt
b7b0: 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 **ppStmt, /* OU
b7c0: 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e T: Statement han
b7d0: 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 dle */. const c
b7e0: 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 har **pzTail
b7f0: 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 /* OUT: Pointer
b800: 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 to unused porti
b810: 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b on of zSql */.);
b820: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 .int sqlite3_pre
b830: 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 pare16(. sqlite
b840: 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
b850: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 /* Database ha
b860: 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
b870: 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 void *zSql,
b880: 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 /* SQL stateme
b890: 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 nt, UTF-16 encod
b8a0: 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 ed */. int nByt
b8b0: 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 e,
b8c0: 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 /* Maximum lengt
b8d0: 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 h of zSql in byt
b8e0: 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 es. */. sqlite3
b8f0: 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 _stmt **ppStmt,
b900: 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 /* OUT: Stateme
b910: 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 nt handle */. c
b920: 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 onst void **pzTa
b930: 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 il /* OUT: P
b940: 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 ointer to unused
b950: 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c portion of zSql
b960: 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 */.);.int sqlit
b970: 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
b980: 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
b990: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 /* Da
b9a0: 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f tabase handle */
b9b0: 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a . const void *z
b9c0: 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 Sql, /* SQ
b9d0: 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 L statement, UTF
b9e0: 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 -16 encoded */.
b9f0: 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 int nByte,
ba00: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 /* Maxi
ba10: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 mum length of zS
ba20: 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a ql in bytes. */.
ba30: 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a sqlite3_stmt *
ba40: 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 *ppStmt, /* OUT
ba50: 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 : Statement hand
ba60: 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f le */. const vo
ba70: 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 id **pzTail
ba80: 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 /* OUT: Pointer
ba90: 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f to unused portio
baa0: 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a n of zSql */.);.
bab0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
bac0: 20 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 Dynamically Ty
bad0: 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 ped Value Object
bae0: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 .**.** SQLite us
baf0: 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e es dynamic typin
bb00: 67 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 g for the values
bb10: 20 69 74 20 73 74 6f 72 65 73 2e 20 20 56 61 6c it stores. Val
bb20: 75 65 73 20 63 61 6e 20 0a 2a 2a 20 62 65 20 69 ues can .** be i
bb30: 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e ntegers, floatin
bb40: 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 g point values,
bb50: 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 strings, BLOBs,
bb60: 6f 72 20 4e 55 4c 4c 2e 20 20 57 68 65 6e 0a 2a or NULL. When.*
bb70: 2a 20 70 61 73 73 69 6e 67 20 61 72 6f 75 6e 64 * passing around
bb80: 20 76 61 6c 75 65 73 20 69 6e 74 65 72 6e 61 6c values internal
bb90: 6c 79 2c 20 65 61 63 68 20 76 61 6c 75 65 20 69 ly, each value i
bba0: 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 s represented as
bbb0: 0a 2a 2a 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 .** an instance
bbc0: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 of the sqlite3_v
bbd0: 61 6c 75 65 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a alue object..*/.
bbe0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d typedef struct M
bbf0: 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 em sqlite3_value
bc00: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
bc10: 46 3a 20 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e F: SQL Function
bc20: 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a Context Object.
bc30: 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 **.** The contex
bc40: 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 t in which an SQ
bc50: 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 L function execu
bc60: 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e tes is stored in
bc70: 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 an.** sqlite3_c
bc80: 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 ontext object.
bc90: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 75 63 A pointer to suc
bca0: 68 20 61 6e 20 6f 62 6a 65 63 74 20 69 73 20 74 h an object is t
bcb0: 68 65 0a 2a 2a 20 66 69 72 73 74 20 70 61 72 61 he.** first para
bcc0: 6d 65 74 65 72 20 74 6f 20 75 73 65 72 2d 64 65 meter to user-de
bcd0: 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 fined SQL functi
bce0: 6f 6e 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ons..*/.typedef
bcf0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 struct sqlite3_c
bd00: 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 ontext sqlite3_c
bd10: 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ontext;../*.** C
bd20: 41 50 49 33 52 45 46 3a 20 20 42 69 6e 64 69 6e API3REF: Bindin
bd30: 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 g Values To Prep
bd40: 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a ared Statements.
bd50: 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 53 51 4c **.** In the SQL
bd60: 20 73 74 72 69 6e 67 73 20 69 6e 70 75 74 20 74 strings input t
bd70: 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 o [sqlite3_prepa
bd80: 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 re_v2()] and its
bd90: 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6f 6e variants,.** on
bda0: 65 20 6f 72 20 6d 6f 72 65 20 6c 69 74 65 72 61 e or more litera
bdb0: 6c 73 20 63 61 6e 20 62 65 20 72 65 70 6c 61 63 ls can be replac
bdc0: 65 20 62 79 20 61 20 70 61 72 61 6d 65 74 65 72 e by a parameter
bdd0: 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 in one of these
bde0: 0a 2a 2a 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a .** forms:.**.**
bdf0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f <ul>.** <li> ?
be00: 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a .** <li> ?NNN.*
be10: 2a 20 3c 6c 69 3e 20 20 3a 41 41 41 0a 2a 2a 20 * <li> :AAA.**
be20: 3c 6c 69 3e 20 20 40 41 41 41 0a 2a 2a 20 3c 6c <li> @AAA.** <l
be30: 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c i> $VVV.** </ul
be40: 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70 >.**.** In the p
be50: 61 72 61 6d 65 74 65 72 20 66 6f 72 6d 73 20 73 arameter forms s
be60: 68 6f 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69 hown above NNN i
be70: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 s an integer lit
be80: 65 72 61 6c 2c 0a 2a 2a 20 41 41 41 20 69 73 20 eral,.** AAA is
be90: 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 an alphanumeric
bea0: 69 64 65 6e 74 69 66 69 65 72 20 61 6e 64 20 56 identifier and V
beb0: 56 56 20 69 73 20 61 20 76 61 72 69 61 62 6c 65 VV is a variable
bec0: 20 6e 61 6d 65 20 61 63 63 6f 72 64 69 6e 67 0a name according.
bed0: 2a 2a 20 74 6f 20 74 68 65 20 73 79 6e 74 61 78 ** to the syntax
bee0: 20 72 75 6c 65 73 20 6f 66 20 74 68 65 20 54 43 rules of the TC
bef0: 4c 20 70 72 6f 67 72 61 6d 6d 69 6e 67 20 6c 61 L programming la
bf00: 6e 67 75 61 67 65 2e 0a 2a 2a 20 54 68 65 20 76 nguage..** The v
bf10: 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 20 70 alues of these p
bf20: 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 arameters (also
bf30: 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 called "host par
bf40: 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 29 0a 2a ameter names").*
bf50: 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 * can be set usi
bf60: 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 ng the sqlite3_b
bf70: 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 ind_*() routines
bf80: 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a defined here..*
bf90: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 *.** The first a
bfa0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 rgument to the s
bfb0: 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 qlite3_bind_*()
bfc0: 72 6f 75 74 69 6e 65 73 20 61 6c 77 61 79 73 20 routines always
bfd0: 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 is a pointer.**
bfe0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
bff0: 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 stmt] object ret
c000: 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 urned from [sqli
c010: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
c020: 5d 20 6f 72 0a 2a 2a 20 69 74 73 20 76 61 72 69 ] or.** its vari
c030: 61 6e 74 73 2e 20 20 54 68 65 20 73 65 63 6f 6e ants. The secon
c040: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 d.** argument is
c050: 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 the index of th
c060: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 e parameter to b
c070: 65 20 73 65 74 2e 20 20 54 68 65 20 66 69 72 73 e set. The firs
c080: 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 0a t parameter has.
c090: 2a 2a 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 ** an index of 1
c0a0: 2e 20 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 . When the same
c0b0: 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 named parameter
c0c0: 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 is used more tha
c0d0: 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 0a 2a n once, second.*
c0e0: 2a 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 * and subsequent
c0f0: 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 .** occurrences
c100: 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e have the same in
c110: 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 dex as the first
c120: 20 6f 63 63 75 72 72 65 6e 63 65 2e 20 20 54 68 occurrence. Th
c130: 65 20 69 6e 64 65 78 20 66 6f 72 0a 2a 2a 20 6e e index for.** n
c140: 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 amed parameters
c150: 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 can be looked up
c160: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 using the.** [s
c170: 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
c180: 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 20 41 50 meter_name()] AP
c190: 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 54 I if desired. T
c1a0: 68 65 20 69 6e 64 65 78 20 66 6f 72 20 22 3f 4e he index for "?N
c1b0: 4e 4e 22 0a 2a 2a 20 70 61 72 61 6d 65 74 65 73 NN".** parametes
c1c0: 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 is the value of
c1d0: 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e NNN..** The NNN
c1e0: 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 value must be b
c1f0: 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 etween 1 and the
c200: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a compile-time.**
c210: 20 70 61 72 61 6d 65 74 65 72 20 53 51 4c 49 54 parameter SQLIT
c220: 45 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e E_MAX_VARIABLE_N
c230: 55 4d 42 45 52 20 28 64 65 66 61 75 6c 74 20 76 UMBER (default v
c240: 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 20 53 alue: 999)..** S
c250: 65 65 20 3c 61 20 68 72 65 66 3d 22 6c 69 6d 69 ee <a href="limi
c260: 74 73 2e 68 74 6d 6c 22 3e 6c 69 6d 69 74 73 2e ts.html">limits.
c270: 68 74 6d 6c 3c 2f 61 3e 20 66 6f 72 20 61 64 64 html</a> for add
c280: 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 itional informat
c290: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 ion..**.** The t
c2a0: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 hird argument is
c2b0: 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 the value to bi
c2c0: 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 nd to the parame
c2d0: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 ter..**.** In th
c2e0: 6f 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 ose.** routines
c2f0: 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 that have a four
c300: 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 th argument, its
c310: 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 6e 75 value is the nu
c320: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a mber of bytes.**
c330: 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 in the paramete
c340: 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a r. To be clear:
c350: 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 the value is th
c360: 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
c370: 73 20 69 6e 20 74 68 65 0a 2a 2a 20 73 74 72 69 s in the.** stri
c380: 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 ng, not the numb
c390: 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 er of characters
c3a0: 2e 20 20 54 68 65 20 6e 75 6d 62 65 72 0a 2a 2a . The number.**
c3b0: 20 6f 66 20 62 79 74 65 73 20 64 6f 65 73 20 6e of bytes does n
c3c0: 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a ot include the z
c3d0: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 61 ero-terminator a
c3e0: 74 20 74 68 65 20 65 6e 64 20 6f 66 20 73 74 72 t the end of str
c3f0: 69 6e 67 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 ings..** If the
c400: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
c410: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 is negative, th
c420: 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 e length of the
c430: 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 6e 75 6d string is.** num
c440: 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 ber of bytes up
c450: 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 to the first zer
c460: 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a o terminator..**
c470: 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 61 72 .** The fifth ar
c480: 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 gument to sqlite
c490: 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 3_bind_blob(), s
c4a0: 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
c4b0: 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 (), and.** sqlit
c4c0: 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 e3_bind_text16()
c4d0: 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 is a destructor
c4e0: 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 used to dispose
c4f0: 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a of the BLOB or.
c500: 2a 2a 20 74 65 78 74 20 61 66 74 65 72 20 53 51 ** text after SQ
c510: 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 Lite has finishe
c520: 64 20 77 69 74 68 20 69 74 2e 20 20 49 66 20 74 d with it. If t
c530: 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e he fifth argumen
c540: 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 70 65 63 t is the.** spec
c550: 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 ial value [SQLIT
c560: 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 E_STATIC], then
c570: 74 68 65 20 6c 69 62 72 61 72 79 20 61 73 73 75 the library assu
c580: 6d 65 73 20 74 68 61 74 20 74 68 65 20 69 6e 66 mes that the inf
c590: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 ormation.** is i
c5a0: 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 n static, unmana
c5b0: 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f ged space and do
c5c0: 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 es not need to b
c5d0: 65 20 66 72 65 65 64 2e 20 20 49 66 20 74 68 65 e freed. If the
c5e0: 0a 2a 2a 20 66 69 66 74 68 20 61 72 67 75 6d 65 .** fifth argume
c5f0: 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 nt has the value
c600: 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 [SQLITE_TRANSIE
c610: 4e 54 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 NT], then SQLite
c620: 20 6d 61 6b 65 73 20 69 74 73 0a 2a 2a 20 6f 77 makes its.** ow
c630: 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f n private copy o
c640: 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 f the data immed
c650: 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 iately, before t
c660: 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
c670: 2a 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 *().** routine r
c680: 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 eturns..**.** Th
c690: 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a e sqlite3_bind_z
c6a0: 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e eroblob() routin
c6b0: 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f e binds a BLOB o
c6c0: 66 20 6c 65 6e 67 74 68 20 6e 20 74 68 61 74 0a f length n that.
c6d0: 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 ** is filled wit
c6e0: 68 20 7a 65 72 6f 73 2e 20 20 41 20 7a 65 72 6f h zeros. A zero
c6f0: 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 blob uses a fixe
c700: 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f d amount of memo
c710: 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 ry.** (just an i
c720: 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 nteger to hold i
c730: 74 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 t size) while it
c740: 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 is being proces
c750: 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 sed..** Zeroblob
c760: 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 s are intended t
c770: 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 o serve as place
c780: 2d 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f -holders for BLO
c790: 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 Bs whose.** cont
c7a0: 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 ent is later wri
c7b0: 74 74 65 6e 20 75 73 69 6e 67 20 0a 2a 2a 20 5b tten using .** [
c7c0: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 sqlite3_blob_ope
c7d0: 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 20 42 4c n | increment BL
c7e0: 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 OB I/O] routines
c7f0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
c800: 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 te3_bind_*() rou
c810: 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 tines must be ca
c820: 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b 73 lled after.** [s
c830: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
c840: 32 28 29 5d 20 28 61 6e 64 20 69 74 73 20 76 61 2()] (and its va
c850: 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c 69 riants) or [sqli
c860: 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 6e 64 te3_reset()] and
c870: 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 .** before [sqli
c880: 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 te3_step()]..**
c890: 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 Bindings are not
c8a0: 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 cleared by the
c8b0: 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
c8c0: 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e ] routine..** Un
c8d0: 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 bound parameters
c8e0: 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 are interpreted
c8f0: 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 as NULL..**.**
c900: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
c910: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b eturn [SQLITE_OK
c920: 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 ] on success or
c930: 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69 66 an error code if
c940: 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 .** anything goe
c950: 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49 54 s wrong. [SQLIT
c960: 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 E_RANGE] is retu
c970: 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 rned if the para
c980: 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 meter.** index i
c990: 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 s out of range.
c9a0: 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 [SQLITE_NOMEM]
c9b0: 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d is returned if m
c9c0: 61 6c 6c 6f 63 20 66 61 69 6c 73 2e 0a 2a 2a 20 alloc fails..**
c9d0: 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 [SQLITE_MISUSE]
c9e0: 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 is returned if t
c9f0: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
ca00: 65 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 76 69 e called on a vi
ca10: 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 rtual.** machine
ca20: 20 74 68 61 74 20 69 73 20 74 68 65 20 77 72 6f that is the wro
ca30: 6e 67 20 73 74 61 74 65 20 6f 72 20 77 68 69 63 ng state or whic
ca40: 68 20 68 61 73 20 61 6c 72 65 61 64 79 20 62 65 h has already be
ca50: 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2f en finalized..*/
ca60: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
ca70: 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 d_blob(sqlite3_s
ca80: 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 tmt*, int, const
ca90: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 void*, int n, v
caa0: 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
cab0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
cac0: 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f _double(sqlite3_
cad0: 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 stmt*, int, doub
cae0: 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 le);.int sqlite3
caf0: 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 _bind_int(sqlite
cb00: 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 3_stmt*, int, in
cb10: 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f t);.int sqlite3_
cb20: 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 bind_int64(sqlit
cb30: 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 e3_stmt*, int, s
cb40: 71 6c 69 74 65 5f 69 6e 74 36 34 29 3b 0a 69 6e qlite_int64);.in
cb50: 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e t sqlite3_bind_n
cb60: 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ull(sqlite3_stmt
cb70: 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c *, int);.int sql
cb80: 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 ite3_bind_text(s
cb90: 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
cba0: 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 t, const char*,
cbb0: 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 int n, void(*)(v
cbc0: 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 oid*));.int sqli
cbd0: 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 te3_bind_text16(
cbe0: 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
cbf0: 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c nt, const void*,
cc00: 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f int, void(*)(vo
cc10: 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 id*));.int sqlit
cc20: 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 e3_bind_value(sq
cc30: 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
cc40: 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f , const sqlite3_
cc50: 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c value*);.int sql
cc60: 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c ite3_bind_zerobl
cc70: 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ob(sqlite3_stmt*
cc80: 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a , int, int n);..
cc90: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
cca0: 4e 75 6d 62 65 72 20 4f 66 20 48 6f 73 74 20 50 Number Of Host P
ccb0: 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 arameters.**.**
ccc0: 52 65 74 75 72 6e 20 74 68 65 20 6c 61 72 67 65 Return the large
ccd0: 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 st host paramete
cce0: 72 20 69 6e 64 65 78 20 69 6e 20 74 68 65 20 70 r index in the p
ccf0: 72 65 63 6f 6d 70 69 6c 65 64 20 73 74 61 74 65 recompiled state
cd00: 6d 65 6e 74 20 67 69 76 65 6e 0a 2a 2a 20 61 73 ment given.** as
cd10: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 2e 20 20 the argument.
cd20: 57 68 65 6e 20 74 68 65 20 68 6f 73 74 20 70 61 When the host pa
cd30: 72 61 6d 65 74 65 72 73 20 61 72 65 20 6f 66 20 rameters are of
cd40: 74 68 65 20 66 6f 72 6d 73 20 6c 69 6b 65 20 22 the forms like "
cd50: 3a 41 41 41 22 0a 2a 2a 20 6f 72 20 22 3f 22 2c :AAA".** or "?",
cd60: 20 74 68 65 6e 20 74 68 65 79 20 61 72 65 20 61 then they are a
cd70: 73 73 69 67 6e 65 64 20 73 65 71 75 65 6e 74 69 ssigned sequenti
cd80: 61 6c 20 69 6e 63 72 65 61 73 69 6e 67 20 6e 75 al increasing nu
cd90: 6d 62 65 72 73 20 62 65 67 69 6e 6e 69 6e 67 0a mbers beginning.
cda0: 2a 2a 20 77 69 74 68 20 6f 6e 65 2c 20 73 6f 20 ** with one, so
cdb0: 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
cdc0: 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 ed is the number
cdd0: 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 2e 20 of parameters.
cde0: 20 48 6f 77 65 76 65 72 0a 2a 2a 20 69 66 20 74 However.** if t
cdf0: 68 65 20 73 61 6d 65 20 68 6f 73 74 20 70 61 72 he same host par
ce00: 61 6d 65 74 65 72 20 6e 61 6d 65 20 69 73 20 75 ameter name is u
ce10: 73 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d sed multiple tim
ce20: 65 73 2c 20 65 61 63 68 20 6f 63 63 75 72 72 61 es, each occurra
ce30: 6e 63 65 0a 2a 2a 20 69 73 20 67 69 76 65 6e 20 nce.** is given
ce40: 74 68 65 20 73 61 6d 65 20 6e 75 6d 62 65 72 2c the same number,
ce50: 20 73 6f 20 74 68 65 20 76 61 6c 75 65 20 72 65 so the value re
ce60: 74 75 72 6e 65 64 20 69 6e 20 74 68 61 74 20 63 turned in that c
ce70: 61 73 65 20 69 73 20 74 68 65 20 6e 75 6d 62 65 ase is the numbe
ce80: 72 0a 2a 2a 20 6f 66 20 75 6e 69 71 75 65 20 68 r.** of unique h
ce90: 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 ost parameter na
cea0: 6d 65 73 2e 20 20 49 66 20 68 6f 73 74 20 70 61 mes. If host pa
ceb0: 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 rameters of the
cec0: 66 6f 72 6d 20 22 3f 4e 4e 4e 22 0a 2a 2a 20 61 form "?NNN".** a
ced0: 72 65 20 75 73 65 64 20 28 77 68 65 72 65 20 4e re used (where N
cee0: 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 NN is an integer
cef0: 29 20 74 68 65 6e 20 74 68 65 72 65 20 6d 69 67 ) then there mig
cf00: 68 74 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 ht be gaps in th
cf10: 65 0a 2a 2a 20 6e 75 6d 62 65 72 69 6e 67 20 61 e.** numbering a
cf20: 6e 64 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 nd the value ret
cf30: 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 69 6e urned by this in
cf40: 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 69 terface is the i
cf50: 6e 64 65 78 20 6f 66 20 74 68 65 0a 2a 2a 20 68 ndex of the.** h
cf60: 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 77 69 ost parameter wi
cf70: 74 68 20 74 68 65 20 6c 61 72 67 65 73 74 20 69 th the largest i
cf80: 6e 64 65 78 20 76 61 6c 75 65 2e 0a 2a 2f 0a 69 ndex value..*/.i
cf90: 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
cfa0: 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 parameter_count(
cfb0: 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a sqlite3_stmt*);.
cfc0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
cfd0: 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 Name Of A Host
cfe0: 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 Parameter.**.**
cff0: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 This routine ret
d000: 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
d010: 6f 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 o the name of th
d020: 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 e n-th parameter
d030: 20 69 6e 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 in a .** [sqlit
d040: 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 e3_stmt | prepar
d050: 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a ed statement]..*
d060: 2a 20 48 6f 73 74 20 70 61 72 61 6d 65 74 65 72 * Host parameter
d070: 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3a s of the form ":
d080: 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f AAA" or "@AAA" o
d090: 72 20 22 24 56 56 56 22 20 68 61 76 65 20 61 20 r "$VVV" have a
d0a0: 6e 61 6d 65 0a 2a 2a 20 77 68 69 63 68 20 69 73 name.** which is
d0b0: 20 74 68 65 20 73 74 72 69 6e 67 20 22 3a 41 41 the string ":AA
d0c0: 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 A" or "@AAA" or
d0d0: 22 24 56 56 56 22 2e 20 20 0a 2a 2a 20 49 6e 20 "$VVV". .** In
d0e0: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 other words, the
d0f0: 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 initial ":" or
d100: 22 24 22 20 6f 72 20 22 40 22 0a 2a 2a 20 69 73 "$" or "@".** is
d110: 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 included as par
d120: 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 0a 2a t of the name..*
d130: 2a 20 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 * Parameters of
d140: 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 6f 72 20 the form "?" or
d150: 22 3f 4e 4e 4e 22 20 68 61 76 65 20 6e 6f 20 6e "?NNN" have no n
d160: 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 ame..**.** The f
d170: 69 72 73 74 20 62 6f 75 6e 64 20 70 61 72 61 6d irst bound param
d180: 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 eter has an inde
d190: 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a x of 1, not 0..*
d1a0: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 76 61 6c 75 *.** If the valu
d1b0: 65 20 6e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 e n is out of ra
d1c0: 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 6e 2d nge or if the n-
d1d0: 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 th parameter is
d1e0: 6e 61 6d 65 6c 65 73 73 2c 0a 2a 2a 20 74 68 65 nameless,.** the
d1f0: 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e n NULL is return
d200: 65 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 ed. The returne
d210: 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 d string is alwa
d220: 79 73 20 69 6e 20 74 68 65 0a 2a 2a 20 55 54 46 ys in the.** UTF
d230: 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e -8 encoding even
d240: 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 if the named pa
d250: 72 61 6d 65 74 65 72 20 77 61 73 20 6f 72 69 67 rameter was orig
d260: 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 inally specified
d270: 0a 2a 2a 20 61 73 20 55 54 46 2d 31 36 20 69 6e .** as UTF-16 in
d280: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
d290: 65 31 36 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 e16()] or [sqlit
d2a0: 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
d2b0: 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 )]..*/.const cha
d2c0: 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f r *sqlite3_bind_
d2d0: 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 parameter_name(s
d2e0: 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
d2f0: 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
d300: 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 REF: Index Of A
d310: 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 Parameter With A
d320: 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a Given Name.**.*
d330: 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 * This routine r
d340: 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 eturns the index
d350: 20 6f 66 20 61 20 68 6f 73 74 20 70 61 72 61 6d of a host param
d360: 65 74 65 72 20 77 69 74 68 20 74 68 65 20 67 69 eter with the gi
d370: 76 65 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 ven name..** The
d380: 20 6e 61 6d 65 20 6d 75 73 74 20 6d 61 74 63 68 name must match
d390: 20 65 78 61 63 74 6c 79 2e 20 20 49 66 20 6e 6f exactly. If no
d3a0: 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 parameter with
d3b0: 74 68 65 20 67 69 76 65 6e 20 6e 61 6d 65 20 69 the given name i
d3c0: 73 20 0a 2a 2a 20 66 6f 75 6e 64 2c 20 72 65 74 s .** found, ret
d3d0: 75 72 6e 20 30 2e 20 20 50 61 72 61 6d 65 74 65 urn 0. Paramete
d3e0: 72 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20 r names must be
d3f0: 55 54 46 38 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c UTF8..*/.int sql
d400: 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
d410: 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 ter_index(sqlite
d420: 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 3_stmt*, const c
d430: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a har *zName);../*
d440: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 .** CAPI3REF: Re
d450: 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 set All Bindings
d460: 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 On A Prepared S
d470: 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 43 tatement.**.** C
d480: 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 ontrary to the i
d490: 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 ntuition of many
d4a0: 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 , [sqlite3_reset
d4b0: 28 29 5d 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 ()] does not.**
d4c0: 72 65 73 65 74 20 74 68 65 20 5b 73 71 6c 69 74 reset the [sqlit
d4d0: 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 e3_bind_blob | b
d4e0: 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 0a 2a indings] on a .*
d4f0: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 * [sqlite3_stmt
d500: 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 | prepared state
d510: 6d 65 6e 74 5d 2e 20 20 55 73 65 20 74 68 69 73 ment]. Use this
d520: 20 72 6f 75 74 69 6e 65 20 74 6f 0a 2a 2a 20 72 routine to.** r
d530: 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 eset all host pa
d540: 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c rameters to NULL
d550: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
d560: 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 _clear_bindings(
d570: 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a sqlite3_stmt*);.
d580: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
d590: 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d Number Of Colum
d5a0: 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 ns In A Result S
d5b0: 65 74 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 et.**.** Return
d5c0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f the number of co
d5d0: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 lumns in the res
d5e0: 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 ult set returned
d5f0: 20 62 79 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c by the .** [sql
d600: 69 74 65 33 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 ite3_stmt | comp
d610: 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 iled SQL stateme
d620: 6e 74 5d 2e 20 54 68 69 73 20 72 6f 75 74 69 6e nt]. This routin
d630: 65 20 72 65 74 75 72 6e 73 20 30 0a 2a 2a 20 69 e returns 0.** i
d640: 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 f pStmt is an SQ
d650: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 L statement that
d660: 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e does not return
d670: 20 64 61 74 61 20 28 66 6f 72 20 0a 2a 2a 20 65 data (for .** e
d680: 78 61 6d 70 6c 65 20 61 6e 20 55 50 44 41 54 45 xample an UPDATE
d690: 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 )..*/.int sqlite
d6a0: 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 3_column_count(s
d6b0: 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
d6c0: 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
d6d0: 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 3REF: Column Nam
d6e0: 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 es In A Result S
d6f0: 65 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 et.**.** These r
d700: 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 outines return t
d710: 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 he name assigned
d720: 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 to a particular
d730: 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 column.** in th
d740: 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 e result set of
d750: 61 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 a SELECT stateme
d760: 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 nt. The sqlite3
d770: 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a _column_name().*
d780: 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 * interface retu
d790: 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
d7a0: 20 61 20 55 54 46 38 20 73 74 72 69 6e 67 20 61 a UTF8 string a
d7b0: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nd sqlite3_colum
d7c0: 6e 5f 6e 61 6d 65 31 36 28 29 0a 2a 2a 20 72 65 n_name16().** re
d7d0: 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
d7e0: 74 6f 20 61 20 55 54 46 31 36 20 73 74 72 69 6e to a UTF16 strin
d7f0: 67 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 g. The first pa
d800: 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a rameter is the.*
d810: 2a 20 5b 73 71 6c 69 74 65 5f 73 74 6d 74 20 7c * [sqlite_stmt |
d820: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
d830: 65 6e 74 5d 20 74 68 61 74 20 69 6d 70 6c 65 6d ent] that implem
d840: 65 6e 74 73 20 74 68 65 20 53 45 4c 45 43 54 20 ents the SELECT
d850: 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 statement..** Th
d860: 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
d870: 65 72 20 69 73 20 74 68 65 20 63 6f 6c 75 6d 6e er is the column
d880: 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 6c 65 number. The le
d890: 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 ft-most column i
d8a0: 73 0a 2a 2a 20 6e 75 6d 62 65 72 20 30 2e 0a 2a s.** number 0..*
d8b0: 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 *.** The returne
d8c0: 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 d string pointer
d8d0: 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 is valid until
d8e0: 65 69 74 68 65 72 20 74 68 65 20 0a 2a 2a 20 5b either the .** [
d8f0: 73 71 6c 69 74 65 5f 73 74 6d 74 20 7c 20 70 72 sqlite_stmt | pr
d900: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
d910: 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 ] is destroyed b
d920: 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c y [sqlite3_final
d930: 69 7a 65 28 29 5d 0a 2a 2a 20 6f 72 20 75 6e 74 ize()].** or unt
d940: 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c il the next call
d950: 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
d960: 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 name() or sqlite
d970: 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 3_column_name16(
d980: 29 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 ).** on the same
d990: 20 63 6f 6c 75 6d 6e 2e 0a 2a 2f 0a 63 6f 6e 73 column..*/.cons
d9a0: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
d9b0: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 column_name(sqli
d9c0: 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e te3_stmt*, int N
d9d0: 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
d9e0: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
d9f0: 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d me16(sqlite3_stm
da00: 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a t*, int N);../*.
da10: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 ** CAPI3REF: Sou
da20: 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 rce Of Data In A
da30: 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a Query Result.**
da40: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
da50: 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 es provide a mea
da60: 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 ns to determine
da70: 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 77 what column of w
da80: 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69 6e 20 hat.** table in
da90: 77 68 69 63 68 20 64 61 74 61 62 61 73 65 20 61 which database a
daa0: 20 72 65 73 75 6c 74 20 6f 66 20 61 20 53 45 4c result of a SEL
dab0: 45 43 54 20 73 74 61 74 65 6d 65 6e 74 20 63 6f ECT statement co
dac0: 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65 mes from..** The
dad0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 name of the dat
dae0: 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f abase or table o
daf0: 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 r column can be
db00: 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 returned as.** e
db10: 69 74 68 65 72 20 61 20 55 54 46 38 20 6f 72 20 ither a UTF8 or
db20: 55 54 46 31 36 20 73 74 72 69 6e 67 2e 20 20 54 UTF16 string. T
db30: 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f he _database_ ro
db40: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a utines return.**
db50: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 the database na
db60: 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 me, the _table_
db70: 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
db80: 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 the table name,
db90: 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 and.** the origi
dba0: 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 n_ routines retu
dbb0: 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 rn the column na
dbc0: 6d 65 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 me..** The retur
dbd0: 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 ned string is va
dbe0: 6c 69 64 20 75 6e 74 69 6c 0a 2a 2a 20 74 68 65 lid until.** the
dbf0: 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c [sqlite3_stmt |
dc00: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
dc10: 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 ent] is destroye
dc20: 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 d using.** [sqli
dc30: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
dc40: 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d or until the sam
dc50: 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 e information is
dc60: 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 requested.** ag
dc70: 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 ain in a differe
dc80: 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a nt encoding..**.
dc90: 2a 2a 20 54 68 65 20 6e 61 6d 65 73 20 72 65 74 ** The names ret
dca0: 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 urned are the or
dcb0: 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 iginal un-aliase
dcc0: 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a d names of the.*
dcd0: 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c * database, tabl
dce0: 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a e, and column..*
dcf0: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 *.** The first a
dd00: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 66 rgument to the f
dd10: 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c 73 20 69 ollowing calls i
dd20: 73 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 s a .** [sqlite3
dd30: 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64 _stmt | compiled
dd40: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e SQL statement].
dd50: 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 .** These functi
dd60: 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 ons return infor
dd70: 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 mation about the
dd80: 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 Nth column retu
dd90: 72 6e 65 64 20 62 79 20 0a 2a 2a 20 74 68 65 20 rned by .** the
dda0: 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 statement, where
ddb0: 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 N is the second
ddc0: 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 function argume
ddd0: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 nt..**.** If the
dde0: 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 Nth column retu
ddf0: 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 rned by the stat
de00: 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 ement is an expr
de10: 65 73 73 69 6f 6e 0a 2a 2a 20 6f 72 20 73 75 62 ession.** or sub
de20: 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 query and is not
de30: 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c a column value,
de40: 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 then all of the
de50: 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 se functions.**
de60: 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 20 4f 74 68 return NULL. Oth
de70: 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 erwise, they ret
de80: 75 72 6e 20 74 68 65 20 0a 2a 2a 20 6e 61 6d 65 urn the .** name
de90: 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64 of the attached
dea0: 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 database, table
deb0: 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74 and column that
dec0: 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a query result.**
ded0: 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 column was extr
dee0: 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a acted from..**.*
def0: 2a 20 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 * As with all ot
df00: 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c her SQLite APIs,
df10: 20 74 68 6f 73 65 20 70 6f 73 74 66 69 78 65 64 those postfixed
df20: 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 with "16" retur
df30: 6e 20 55 54 46 2d 31 36 0a 2a 2a 20 65 6e 63 6f n UTF-16.** enco
df40: 64 65 64 20 73 74 72 69 6e 67 73 2c 20 74 68 65 ded strings, the
df50: 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 other functions
df60: 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a return UTF-8..*
df70: 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20 *.** These APIs
df80: 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 are only availab
df90: 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 le if the librar
dfa0: 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 y was compiled w
dfb0: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 ith the .** SQLI
dfc0: 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e TE_ENABLE_COLUMN
dfd0: 5f 4d 45 54 41 44 41 54 41 20 70 72 65 70 72 6f _METADATA prepro
dfe0: 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 cessor symbol de
dff0: 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 fined..*/.const
e000: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
e010: 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 lumn_database_na
e020: 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
e030: 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 ,int);.const voi
e040: 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
e050: 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 n_database_name1
e060: 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
e070: 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 int);.const char
e080: 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
e090: 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 _table_name(sqli
e0a0: 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
e0b0: 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
e0c0: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 te3_column_table
e0d0: 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f _name16(sqlite3_
e0e0: 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 stmt*,int);.cons
e0f0: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
e100: 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 column_origin_na
e110: 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
e120: 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 ,int);.const voi
e130: 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
e140: 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 n_origin_name16(
e150: 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
e160: 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
e170: 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 REF: Declared Da
e180: 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 tatype Of A Quer
e190: 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 54 y Result.**.** T
e1a0: 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
e1b0: 65 72 20 69 73 20 61 20 5b 73 71 6c 69 74 65 33 er is a [sqlite3
e1c0: 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64 _stmt | compiled
e1d0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e SQL statement].
e1e0: 20 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 .** If this sta
e1f0: 74 65 6d 65 6e 74 20 69 73 20 61 20 53 45 4c 45 tement is a SELE
e200: 43 54 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 CT statement and
e210: 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
e220: 6f 66 20 74 68 65 20 0a 2a 2a 20 72 65 74 75 72 of the .** retur
e230: 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 20 ned result set
e240: 6f 66 20 74 68 61 74 20 53 45 4c 45 43 54 20 69 of that SELECT i
e250: 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e s a table column
e260: 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 (not an.** expr
e270: 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 ession or subque
e280: 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 ry) then the dec
e290: 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 lared type of th
e2a0: 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d e table.** colum
e2b0: 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 49 n is returned. I
e2c0: 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e f the Nth column
e2d0: 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 of the result s
e2e0: 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 et is an.** expr
e2f0: 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 ession or subque
e300: 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 ry, then a NULL
e310: 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 pointer is retur
e320: 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 ned..** The retu
e330: 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 rned string is a
e340: 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f lways UTF-8 enco
e350: 64 65 64 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 ded. For example
e360: 2c 20 69 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 , in.** the data
e370: 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a base schema:.**.
e380: 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 ** CREATE TABLE
e390: 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a t1(c1 VARIANT);.
e3a0: 2a 2a 0a 2a 2a 20 41 6e 64 20 74 68 65 20 66 6f **.** And the fo
e3b0: 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e llowing statemen
e3c0: 74 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a t compiled:.**.*
e3d0: 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c * SELECT c1 + 1,
e3e0: 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a c1 FROM t1;.**.
e3f0: 2a 2a 20 54 68 65 6e 20 74 68 69 73 20 72 6f 75 ** Then this rou
e400: 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 tine would retur
e410: 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 n the string "VA
e420: 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 RIANT" for the s
e430: 65 63 6f 6e 64 0a 2a 2a 20 72 65 73 75 6c 74 20 econd.** result
e440: 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 column (i==1), a
e450: 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 nd a NULL pointe
e460: 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 r for the first
e470: 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a result column.**
e480: 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 (i==0)..**.** S
e490: 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d QLite uses dynam
e4a0: 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 ic run-time typi
e4b0: 6e 67 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 63 ng. So just bec
e4c0: 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a ause a column.**
e4d0: 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 is declared to
e4e0: 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 contain a partic
e4f0: 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e ular type does n
e500: 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 ot mean that the
e510: 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 .** data stored
e520: 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 in that column i
e530: 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 s of the declare
e540: 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 d type. SQLite
e550: 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 is.** strongly t
e560: 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 yped, but the ty
e570: 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 ping is dynamic
e580: 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 54 79 70 not static. Typ
e590: 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 e.** is associat
e5a0: 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 ed with individu
e5b0: 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 al values, not w
e5c0: 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 ith the containe
e5d0: 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f rs.** used to ho
e5e0: 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e ld those values.
e5f0: 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a .*/.const char *
e600: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
e610: 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f ecltype(sqlite3_
e620: 73 74 6d 74 20 2a 2c 20 69 6e 74 20 69 29 3b 0a stmt *, int i);.
e630: 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
e640: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 te3_column_declt
e650: 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ype16(sqlite3_st
e660: 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 20 0a 2a mt*,int);../* .*
e670: 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 76 61 * CAPI3REF: Eva
e680: 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 luate An SQL Sta
e690: 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 tement.**.** Aft
e6a0: 65 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 73 er an [sqlite3_s
e6b0: 74 6d 74 20 7c 20 53 51 4c 20 73 74 61 74 65 6d tmt | SQL statem
e6c0: 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 ent] has been pr
e6d0: 65 70 61 72 65 64 20 77 69 74 68 20 61 20 63 61 epared with a ca
e6e0: 6c 6c 0a 2a 2a 20 74 6f 20 65 69 74 68 65 72 20 ll.** to either
e6f0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
e700: 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 _v2()] or [sqlit
e710: 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
e720: 29 5d 20 6f 72 20 74 6f 20 6f 6e 65 20 6f 66 0a )] or to one of.
e730: 2a 2a 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e ** the legacy in
e740: 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 terfaces [sqlite
e750: 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 3_prepare()] or
e760: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
e770: 31 36 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 16()],.** then t
e780: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 his function mus
e790: 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 t be called one
e7a0: 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f or more times to
e7b0: 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 0a 2a evaluate the .*
e7c0: 2a 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a * statement..**.
e7d0: 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f ** The details o
e7e0: 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f f the behavior o
e7f0: 66 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f 73 f this sqlite3_s
e800: 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 tep() interface
e810: 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 depend.** on whe
e820: 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 ther the stateme
e830: 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 nt was prepared
e840: 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 using the newer
e850: 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a "v2" interface.*
e860: 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
e870: 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 re_v2()] and [sq
e880: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
e890: 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 v2()] or the old
e8a0: 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 er legacy.** int
e8b0: 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f erface [sqlite3_
e8c0: 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b prepare()] and [
e8d0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
e8e0: 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 6()]. The use o
e8f0: 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 f the.** new "v2
e900: 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 " interface is r
e910: 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e ecommended for n
e920: 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 ew applications
e930: 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a but the legacy.*
e940: 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c * interface will
e950: 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 continue to be
e960: 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a supported..**.**
e970: 20 49 6e 20 74 68 65 20 6c 61 67 61 63 79 20 69 In the lagacy i
e980: 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 nterface, the re
e990: 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 turn value will
e9a0: 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 be either [SQLIT
e9b0: 45 5f 42 55 53 59 5d 2c 20 0a 2a 2a 20 5b 53 51 E_BUSY], .** [SQ
e9c0: 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c LITE_DONE], [SQL
e9d0: 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 ITE_ROW], [SQLIT
e9e0: 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 E_ERROR], or [SQ
e9f0: 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a LITE_MISUSE]..**
ea00: 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 With the "v2" i
ea10: 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 nterface, any of
ea20: 20 74 68 65 20 6f 74 68 65 72 20 5b 53 51 4c 49 the other [SQLI
ea30: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 TE_OK | result c
ea40: 6f 64 65 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 ode].** or [SQLI
ea50: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 TE_IOERR_READ |
ea60: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
ea70: 63 6f 64 65 5d 20 6d 69 67 68 74 20 62 65 20 72 code] might be r
ea80: 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 77 65 eturned as.** we
ea90: 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 ll..**.** [SQLIT
eaa0: 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 E_BUSY] means th
eab0: 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 at the database
eac0: 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c engine was unabl
ead0: 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 e to acquire the
eae0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 .** database loc
eaf0: 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 ks it needs to d
eb00: 6f 20 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 o its job. If t
eb10: 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 he statement is
eb20: 61 20 43 4f 4d 4d 49 54 0a 2a 2a 20 6f 72 20 6f a COMMIT.** or o
eb30: 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 ccurs outside of
eb40: 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 an explicit tra
eb50: 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 nsaction, then y
eb60: 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 ou can retry the
eb70: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 .** statement.
eb80: 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 If the statement
eb90: 20 69 73 20 6e 6f 74 20 61 20 43 4f 4d 4d 49 54 is not a COMMIT
eba0: 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 and occurs with
ebb0: 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 in a.** explicit
ebc0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 transaction the
ebd0: 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c n you should rol
ebe0: 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 lback the transa
ebf0: 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 ction before.**
ec00: 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a continuing..**.*
ec10: 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 * [SQLITE_DONE]
ec20: 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 means that the s
ec30: 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e tatement has fin
ec40: 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a ished executing.
ec50: 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e ** successfully.
ec60: 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 sqlite3_step()
ec70: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 should not be c
ec80: 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 alled again on t
ec90: 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d his virtual.** m
eca0: 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 achine without f
ecb0: 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 irst calling [sq
ecc0: 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 lite3_reset()] t
ecd0: 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 o reset the virt
ece0: 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 ual.** machine b
ecf0: 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 ack to its initi
ed00: 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 al state..**.**
ed10: 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 If the SQL state
ed20: 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 ment being execu
ed30: 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 ted returns any
ed40: 64 61 74 61 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b data, then .** [
ed50: 53 51 4c 49 54 45 5f 52 4f 57 5d 20 69 73 20 72 SQLITE_ROW] is r
ed60: 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d eturned each tim
ed70: 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 e a new row of d
ed80: 61 74 61 20 69 73 20 72 65 61 64 79 0a 2a 2a 20 ata is ready.**
ed90: 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 for processing b
eda0: 79 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 54 68 y the caller. Th
edb0: 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 e values may be
edc0: 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 0a 2a accessed using.*
edd0: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 * the [sqlite3_c
ede0: 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 63 6f 6c 75 olumn_int | colu
edf0: 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 mn access functi
ee00: 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 ons]..** sqlite3
ee10: 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 _step() is calle
ee20: 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 d again to retri
ee30: 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 eve the next row
ee40: 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 20 0a 2a 2a of data..** .**
ee50: 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
ee60: 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e means that a run
ee70: 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 -time error (suc
ee80: 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e h as a constrain
ee90: 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 t.** violation)
eea0: 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 has occurred. s
eeb0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 qlite3_step() sh
eec0: 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c ould not be call
eed0: 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 ed again on.** t
eee0: 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f he VM. More info
eef0: 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 rmation may be f
ef00: 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 ound by calling
ef10: 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 [sqlite3_errmsg(
ef20: 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 )]..** With the
ef30: 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 legacy interface
ef40: 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 , a more specifi
ef50: 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 65 78 c error code (ex
ef60: 61 6d 70 6c 65 3a 0a 2a 2a 20 5b 53 51 4c 49 54 ample:.** [SQLIT
ef70: 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 E_INTERRUPT], [S
ef80: 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b QLITE_SCHEMA], [
ef90: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c SQLITE_CORRUPT],
efa0: 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a and so forth).*
efb0: 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 * can be obtaine
efc0: 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 d by calling [sq
efd0: 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f lite3_reset()] o
efe0: 6e 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 n the.** [sqlite
eff0: 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64 _stmt | prepared
f000: 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e statement]. In
f010: 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 the "v2" interf
f020: 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 ace,.** the more
f030: 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 specific error
f040: 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 code is returned
f050: 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c directly by sql
f060: 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a ite3_step()..**.
f070: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 ** [SQLITE_MISUS
f080: 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 E] means that th
f090: 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 e this routine w
f0a0: 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 as called inappr
f0b0: 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 opriately..** Pe
f0c0: 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c rhaps it was cal
f0d0: 6c 65 64 20 6f 6e 20 61 20 5b 73 71 6c 69 74 65 led on a [sqlite
f0e0: 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64 _stmt | prepared
f0f0: 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 statement] that
f100: 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 has.** already
f110: 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 been [sqlite3_fi
f120: 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a nalize | finaliz
f130: 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 ed] or on one th
f140: 61 74 20 68 61 64 20 0a 2a 2a 20 70 72 65 76 69 at had .** previ
f150: 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b ously returned [
f160: 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 SQLITE_ERROR] or
f170: 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 [SQLITE_DONE].
f180: 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 Or it could.**
f190: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 be the case that
f1a0: 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 the same databa
f1b0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
f1c0: 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 being used by t
f1d0: 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 wo or.** more th
f1e0: 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d reads at the sam
f1f0: 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 e moment in time
f200: 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 ..**.** <b>Goofy
f210: 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 Interface Alert
f220: 3a 3c 2f 62 3e 0a 2a 2a 20 49 6e 20 74 68 65 20 :</b>.** In the
f230: 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 legacy interface
f240: 2c 20 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 , .** the sqlite
f250: 33 5f 73 74 65 70 28 29 20 41 50 49 20 61 6c 77 3_step() API alw
f260: 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 ays returns a ge
f270: 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 neric error code
f280: 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 ,.** [SQLITE_ERR
f290: 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 OR], following a
f2a0: 6e 79 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 ny error other t
f2b0: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 han [SQLITE_BUSY
f2c0: 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c 49 54 45 ].** and [SQLITE
f2d0: 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d _MISUSE]. You m
f2e0: 75 73 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 ust call [sqlite
f2f0: 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 3_reset()] or.**
f300: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
f310: 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 ze()] in order t
f320: 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 o find one of th
f330: 65 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 5b 53 e specific.** [S
f340: 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72 65 QLITE_ERROR | re
f350: 73 75 6c 74 20 63 6f 64 65 73 5d 20 74 68 61 74 sult codes] that
f360: 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 better describe
f370: 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 s the error..**
f380: 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 We admit that th
f390: 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 is is a goofy de
f3a0: 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c sign. The probl
f3b0: 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 em has been fixe
f3c0: 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 d.** with the "v
f3d0: 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 2" interface. I
f3e0: 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c f you prepare al
f3f0: 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 l of your SQL st
f400: 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e atements.** usin
f410: 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 g either [sqlite
f420: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
f430: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 or [sqlite3_prep
f440: 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 are16_v2()] inst
f450: 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 ead.** of the le
f460: 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 gacy [sqlite3_pr
f470: 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 epare()] and [sq
f480: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
f490: 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 0a 2a 2a )], then the .**
f4a0: 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b more specific [
f4b0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72 SQLITE_ERROR | r
f4c0: 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 esult codes] are
f4d0: 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 returned direct
f4e0: 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 ly.** by sqlite3
f4f0: 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 _step(). The us
f500: 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e e of the "v2" in
f510: 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d terface is recom
f520: 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 mended..*/.int s
f530: 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 qlite3_step(sqli
f540: 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a te3_stmt*);../*.
f550: 2a 2a 20 43 41 50 49 33 52 45 46 3a 0a 2a 2a 0a ** CAPI3REF:.**.
f560: 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 6e 75 ** Return the nu
f570: 6d 62 65 72 20 6f 66 20 76 61 6c 75 65 73 20 69 mber of values i
f580: 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f n the current ro
f590: 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 w of the result
f5a0: 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 set..**.** After
f5b0: 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 a call to [sqli
f5c0: 74 65 33 5f 73 74 65 70 28 29 5d 20 74 68 61 74 te3_step()] that
f5d0: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
f5e0: 5f 52 4f 57 5d 2c 20 74 68 69 73 20 72 6f 75 74 _ROW], this rout
f5f0: 69 6e 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 ine.** will retu
f600: 72 6e 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 rn the same valu
f610: 65 20 61 73 20 74 68 65 20 5b 73 71 6c 69 74 65 e as the [sqlite
f620: 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 3_column_count()
f630: 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 41 ] function..** A
f640: 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 fter [sqlite3_st
f650: 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e ep()] has return
f660: 65 64 20 61 6e 20 5b 53 51 4c 49 54 45 5f 44 4f ed an [SQLITE_DO
f670: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 NE], [SQLITE_BUS
f680: 59 5d 2c 20 6f 72 0a 2a 2a 20 61 20 5b 53 51 4c Y], or.** a [SQL
f690: 49 54 45 5f 45 52 52 4f 52 20 7c 20 65 72 72 6f ITE_ERROR | erro
f6a0: 72 20 63 6f 64 65 5d 2c 20 6f 72 20 62 65 66 6f r code], or befo
f6b0: 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 re [sqlite3_step
f6c0: 28 29 5d 20 68 61 73 20 62 65 65 6e 20 0a 2a 2a ()] has been .**
f6d0: 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 5b called on the [
f6e0: 73 71 6c 69 74 65 5f 73 74 6d 74 20 7c 20 70 72 sqlite_stmt | pr
f6f0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
f700: 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 ] for the first
f710: 74 69 6d 65 2c 0a 2a 2a 20 74 68 69 73 20 72 6f time,.** this ro
f720: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 utine returns ze
f730: 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ro..*/.int sqlit
f740: 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 e3_data_count(sq
f750: 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d lite3_stmt *pStm
f760: 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
f770: 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c REF: Fundamental
f780: 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 0a 2a 2a Datatypes.**.**
f790: 20 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 Every value in
f7a0: 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f SQLite has one o
f7b0: 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 f five fundament
f7c0: 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a al datatypes:.**
f7d0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
f7e0: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 64-bit signed i
f7f0: 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 nteger.** <li> 6
f800: 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 4-bit IEEE float
f810: 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 ing point number
f820: 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a .** <li> string.
f830: 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 ** <li> BLOB.**
f840: 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 <li> NULL.** </u
f850: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 l>.**.** These c
f860: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 onstants are cod
f870: 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 es for each of t
f880: 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a hose types..**.*
f890: 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 * Note that the
f8a0: 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 SQLITE_TEXT cons
f8b0: 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 tant was also us
f8c0: 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 ed in SQLite ver
f8d0: 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 sion 2.** for a
f8e0: 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 completely diffe
f8f0: 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 rent meaning. S
f900: 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e oftware that lin
f910: 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a ks against both.
f920: 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f ** SQLite versio
f930: 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 n 2 and SQLite v
f940: 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 ersion 3 should
f950: 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 use SQLITE3_TEXT
f960: 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 not.** SQLITE_T
f970: 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 EXT..*/.#define
f980: 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 SQLITE_INTEGER
f990: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
f9a0: 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 _FLOAT 2.#def
f9b0: 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 ine SQLITE_BLOB
f9c0: 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4.#define SQ
f9d0: 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a LITE_NULL 5.
f9e0: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 #ifdef SQLITE_TE
f9f0: 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 XT.# undef SQLIT
fa00: 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 E_TEXT.#else.# d
fa10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 efine SQLITE_TEX
fa20: 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 T 3.#endif.#
fa30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 define SQLITE3_T
fa40: 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a EXT 3../*.**
fa50: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c CAPI3REF: Resul
fa60: 74 73 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 ts Values From A
fa70: 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 Query.**.** The
fa80: 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 se routines retu
fa90: 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 rn information a
faa0: 62 6f 75 74 20 74 68 65 20 69 6e 66 6f 72 6d 61 bout the informa
fab0: 74 69 6f 6e 0a 2a 2a 20 69 6e 20 61 20 73 69 6e tion.** in a sin
fac0: 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 gle column of th
fad0: 65 20 63 75 72 72 65 6e 74 20 72 65 73 75 6c 74 e current result
fae0: 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e row of a query.
faf0: 20 20 49 6e 20 65 76 65 72 79 0a 2a 2a 20 63 61 In every.** ca
fb00: 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 se the first arg
fb10: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 ument is a point
fb20: 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 73 er to the .** [s
fb30: 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 53 51 qlite3_stmt | SQ
fb40: 4c 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 L statement] tha
fb50: 74 20 69 73 20 62 65 69 6e 67 0a 2a 2a 20 65 76 t is being.** ev
fb60: 61 6c 75 61 74 65 20 28 74 68 65 20 5b 73 71 6c aluate (the [sql
fb70: 69 74 65 5f 73 74 6d 74 2a 5d 20 74 68 61 74 20 ite_stmt*] that
fb80: 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f was returned fro
fb90: 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 m .** [sqlite3_p
fba0: 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
fbb0: 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 one of its varia
fbc0: 6e 74 73 29 20 61 6e 64 0a 2a 2a 20 74 68 65 20 nts) and.** the
fbd0: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
fbe0: 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 is the index of
fbf0: 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 the column for w
fc00: 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e hich information
fc10: 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 .** should be r
fc20: 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 6c 65 eturned. The le
fc30: 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 68 ft-most column h
fc40: 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 30 as an index of 0
fc50: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 ..**.** If the S
fc60: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 QL statement is
fc70: 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f not currently po
fc80: 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 int to a valid r
fc90: 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a ow, or if the.**
fca0: 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 the column inde
fcb0: 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 x is out of rang
fcc0: 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 e, the result is
fcd0: 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
fce0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f * The sqlite3_co
fcf0: 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 lumn_type() rout
fd00: 69 6e 65 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 ine returns .**
fd10: 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 [SQLITE_INTEGER
fd20: 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d | datatype code]
fd30: 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c for the initial
fd40: 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 data type.** of
fd50: 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 the result colu
fd60: 6d 6e 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 mn. The returne
fd70: 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f d value is one o
fd80: 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 f [SQLITE_INTEGE
fd90: 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 R],.** [SQLITE_F
fda0: 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 LOAT], [SQLITE_T
fdb0: 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c EXT], [SQLITE_BL
fdc0: 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f OB], or [SQLITE_
fdd0: 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 NULL]. The valu
fde0: 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 e.** returned by
fdf0: 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
fe00: 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d type() is only m
fe10: 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 eaningful if no
fe20: 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 type.** conversi
fe30: 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 ons have occurre
fe40: 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62 d as described b
fe50: 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 elow. After a t
fe60: 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a ype conversion,.
fe70: 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 ** the value ret
fe80: 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
fe90: 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 _column_type() i
fea0: 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 s undefined. Fu
feb0: 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 ture.** versions
fec0: 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 of SQLite may c
fed0: 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 hange the behavi
fee0: 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f or of sqlite3_co
fef0: 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 lumn_type().** f
ff00: 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 ollowing a type
ff10: 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a conversion..**.*
ff20: 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 * If the result
ff30: 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 is a BLOB or UTF
ff40: 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 -8 string then t
ff50: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d he sqlite3_colum
ff60: 6e 5f 62 79 74 65 73 28 29 20 0a 2a 2a 20 72 6f n_bytes() .** ro
ff70: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 utine returns th
ff80: 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
ff90: 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f s in that BLOB o
ffa0: 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49 66 20 r string..** If
ffb0: 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 the result is a
ffc0: 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 UTF-16 string, t
ffd0: 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 hen sqlite3_colu
ffe0: 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 mn_bytes() conve
fff0: 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e rts.** the strin
10000 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 g to UTF-8 and t
10010 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 hen returns the
10020 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e number of bytes.
10030 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c .** If the resul
10040 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 t is a numeric v
10050 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 alue then sqlite
10060 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
10070 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 uses.** [sqlite
10080 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 3_snprintf()] to
10090 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 convert that va
100a0 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 lue to a UTF-8 s
100b0 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e tring and return
100c0 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 s.** the number
100d0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 of bytes in that
100e0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 string..** The
100f0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 64 value returned d
10100 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 oes not include
10110 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 the zero termina
10120 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a 2a tor at the end.*
10130 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e * of the string.
10140 20 20 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 For clarity: t
10150 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
10160 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 d is the number
10170 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 of.** bytes in t
10180 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 he string, not t
10190 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 he number of cha
101a0 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 racters..**.** T
101b0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d he sqlite3_colum
101c0 6e 5f 62 79 74 65 73 31 36 28 29 20 72 6f 75 74 n_bytes16() rout
101d0 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 ine is similar t
101e0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e o sqlite3_column
101f0 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 _bytes().** but
10200 6c 65 61 76 65 73 20 74 68 65 20 72 65 73 75 6c leaves the resul
10210 74 20 69 6e 20 55 54 46 2d 31 36 20 69 6e 73 74 t in UTF-16 inst
10220 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 20 20 0a ead of UTF-8. .
10230 2a 2a 20 54 68 65 20 7a 65 72 6f 20 74 65 72 6d ** The zero term
10240 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e inator is not in
10250 63 6c 75 64 65 64 20 69 6e 20 74 68 69 73 20 63 cluded in this c
10260 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ount..**.** Thes
10270 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d e routines attem
10280 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 pt to convert th
10290 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 e value where ap
102a0 70 72 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a propriate. For.
102b0 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 ** example, if t
102c0 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 he internal repr
102d0 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c esentation is FL
102e0 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 OAT and a text r
102f0 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 esult.** is requ
10300 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f ested, [sqlite3_
10310 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 snprintf()] is u
10320 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 sed internally t
10330 6f 20 64 6f 20 74 68 65 20 63 6f 6e 76 65 72 73 o do the convers
10340 69 6f 6e 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 ion.** automatic
10350 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c 6f ally. The follo
10360 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 wing table detai
10370 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f ls the conversio
10380 6e 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 61 ns that.** are a
10390 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 pplied:.**.** <b
103a0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 lockquote>.** <t
103b0 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e able border="1">
103c0 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 .** <tr><th> Int
103d0 65 72 6e 61 6c 20 3c 74 68 3e 20 52 65 71 75 65 ernal <th> Reque
103e0 73 74 65 64 20 3c 74 68 3e 20 0a 2a 2a 20 3c 74 sted <th> .** <t
103f0 72 3e 3c 74 68 3e 20 20 54 79 70 65 20 20 20 20 r><th> Type
10400 3c 74 68 3e 20 20 20 20 54 79 70 65 20 20 20 3c <th> Type <
10410 74 68 3e 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a th> Conversion.*
10420 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e *.** <tr><td> N
10430 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 ULL <td> INTE
10440 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c GER <td> Resul
10450 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 t is 0.** <tr><t
10460 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e d> NULL <td>
10470 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 FLOAT <td>
10480 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a Result is 0.0.**
10490 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 <tr><td> NULL
104a0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 <td> TEXT
104b0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 <td> Result is
104c0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a NULL pointer.**
104d0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 <tr><td> NULL
104e0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 <td> BLOB
104f0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 <td> Result is
10500 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a NULL pointer.**
10510 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 <tr><td> INTEGE
10520 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 R <td> FLOAT
10530 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 <td> Convert f
10540 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 rom integer to f
10550 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e loat.** <tr><td>
10560 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 INTEGER <td>
10570 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 TEXT <td> AS
10580 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 CII rendering of
10590 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 the integer.**
105a0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 <tr><td> INTEGER
105b0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 <td> BLOB
105c0 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 66 6f <td> Same as fo
105d0 72 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a r INTEGER->TEXT.
105e0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f ** <tr><td> FLO
105f0 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 AT <td> INTEGE
10600 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 R <td> Convert
10610 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 from float to i
10620 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 nteger.** <tr><t
10630 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e d> FLOAT <td>
10640 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 TEXT <td>
10650 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 ASCII rendering
10660 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 of the float.**
10670 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 <tr><td> FLOAT
10680 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 <td> BLOB
10690 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c <td> Same as FL
106a0 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 OAT->TEXT.** <tr
106b0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c ><td> TEXT <
106c0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 td> INTEGER <t
106d0 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a d> Use atoi().**
106e0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 <tr><td> TEXT
106f0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 <td> FLOAT
10700 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 <td> Use atof(
10710 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 ).** <tr><td> T
10720 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c EXT <td> BL
10730 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 OB <td> No ch
10740 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e ange.** <tr><td>
10750 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 BLOB <td> I
10760 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f NTEGER <td> Co
10770 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 nvert to TEXT th
10780 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a en use atoi().**
10790 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 <tr><td> BLOB
107a0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 <td> FLOAT
107b0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 <td> Convert t
107c0 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 o TEXT then use
107d0 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 atof().** <tr><t
107e0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e d> BLOB <td>
107f0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 TEXT <td>
10800 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 Add a zero termi
10810 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a nator if needed.
10820 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c ** </table>.** <
10830 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
10840 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f ** The table abo
10850 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e ve makes referen
10860 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 ce to standard C
10870 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f library functio
10880 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 ns atoi().** and
10890 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 atof(). SQLite
108a0 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 does not really
108b0 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 use these funct
108c0 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 ions. It has it
108d0 73 0a 2a 2a 20 6f 6e 20 65 71 75 61 76 61 6c 65 s.** on equavale
108e0 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 nt internal rout
108f0 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 ines. The atoi(
10900 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d ) and atof() nam
10910 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 es are.** used i
10920 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 n the table for
10930 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 brevity and beca
10940 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d use they are fam
10950 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a iliar to most.**
10960 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a C programmers..
10970 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 **.** Note that
10980 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 when type conver
10990 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 sions occur, poi
109a0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 nters returned b
109b0 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 y prior.** calls
109c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 to sqlite3_colu
109d0 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 mn_blob(), sqlit
109e0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
109f0 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 , and/or.** sqli
10a00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
10a10 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 6() may be inval
10a20 69 64 61 74 65 64 2e 20 0a 2a 2a 20 54 79 70 65 idated. .** Type
10a30 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 conversions and
10a40 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 pointer invalid
10a50 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 ations might occ
10a60 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c ur.** in the fol
10a70 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a lowing cases:.**
10a80 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
10a90 3c 70 3e 20 20 54 68 65 20 69 6e 69 74 69 61 6c <p> The initial
10aa0 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c content is a BL
10ab0 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 OB and sqlite3_c
10ac0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 0a 2a 2a olumn_text() .**
10ad0 20 20 20 20 20 20 20 20 20 20 6f 72 20 73 71 6c or sql
10ae0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
10af0 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 16() is called.
10b00 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 A zero-terminat
10b10 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 or might.**
10b20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 need to be
10b30 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 added to the str
10b40 69 6e 67 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a ing.</p></li>.**
10b50 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 .** <li><p> The
10b60 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 initial content
10b70 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 is UTF-8 text a
10b80 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nd sqlite3_colum
10b90 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a n_bytes16() or.*
10ba0 2a 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 * sqlit
10bb0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
10bc0 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 () is called. T
10bd0 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 he content must
10be0 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 be converted.**
10bf0 20 20 20 20 20 20 20 20 20 74 6f 20 55 54 46 2d to UTF-
10c00 31 36 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 16.</p></li>.**.
10c10 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 ** <li><p> The
10c20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 initial content
10c30 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 is UTF-16 text a
10c40 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nd sqlite3_colum
10c50 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 n_bytes() or.**
10c60 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 sqlite3
10c70 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 _column_text() i
10c80 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 s called. The c
10c90 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 ontent must be c
10ca0 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 onverted.**
10cb0 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f to UTF-8.</
10cc0 70 3e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e p></li>.** </ul>
10cd0 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f .**.** Conversio
10ce0 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 ns between UTF-1
10cf0 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 6be and UTF-16le
10d00 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 are always done
10d10 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f in place and do
10d20 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 .** not invalida
10d30 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 te a prior point
10d40 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f er, though of co
10d50 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 urse the content
10d60 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a of the buffer.*
10d70 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 * that the prior
10d80 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 pointer points
10d90 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 to will have bee
10da0 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 n modified. Oth
10db0 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 er kinds.** of c
10dc0 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f onversion are do
10dd0 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e ne in place when
10de0 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c it is possible,
10df0 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 20 69 74 but sometime it
10e00 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 is.** not possi
10e10 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 ble and in those
10e20 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 cases prior poi
10e30 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 nters are invali
10e40 64 61 74 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 dated. .**.** T
10e50 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 he safest and ea
10e60 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 siest to remembe
10e70 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 r policy is to i
10e80 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 nvoke these rout
10e90 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f ines.** in one o
10ea0 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 f the following
10eb0 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 20 3c 75 6c ways:.**.** <ul
10ec0 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 >.** <li>sqlite
10ed0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 3_column_text()
10ee0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 followed by sqli
10ef0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
10f00 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e ()</li>.** <li>
10f10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
10f20 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 lob() followed b
10f30 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e y sqlite3_column
10f40 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a _bytes()</li>.**
10f50 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f <li>sqlite3_co
10f60 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f lumn_text16() fo
10f70 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 llowed by sqlite
10f80 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
10f90 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 2f 75 6c ()</li>.** </ul
10fa0 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 >.**.** In other
10fb0 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 words, you shou
10fc0 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f ld call sqlite3_
10fd0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 73 column_text(), s
10fe0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
10ff0 6f 62 28 29 2c 0a 2a 2a 20 6f 72 20 73 71 6c 69 ob(),.** or sqli
11000 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
11010 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 6() first to for
11020 63 65 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e ce the result in
11030 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 0a 2a to the desired.*
11040 2a 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 * format, then i
11050 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f nvoke sqlite3_co
11060 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 20 lumn_bytes() or
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 20 74 6f 0a 2a 2a 20 66 ytes16() to.** f
11090 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 ind the size of
110a0 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 the result. Do
110b0 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 20 74 6f 20 not mix call to
110c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
110d0 65 78 74 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 ext() or.** sqli
110e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
110f0 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 ) with calls to
11100 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
11110 79 74 65 73 31 36 28 29 2e 20 20 41 6e 64 20 64 ytes16(). And d
11120 6f 20 6e 6f 74 0a 2a 2a 20 6d 69 78 20 63 61 6c o not.** mix cal
11130 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ls to sqlite3_co
11140 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 77 69 lumn_text16() wi
11150 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 th calls to sqli
11160 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
11170 28 29 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 ()..*/.const voi
11180 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
11190 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 n_blob(sqlite3_s
111a0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
111b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c .int sqlite3_col
111c0 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 umn_bytes(sqlite
111d0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
111e0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f l);.int sqlite3_
111f0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 column_bytes16(s
11200 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
11210 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 t iCol);.double
11220 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
11230 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 ouble(sqlite3_st
11240 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
11250 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 int sqlite3_colu
11260 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 mn_int(sqlite3_s
11270 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
11280 0a 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 .sqlite_int64 sq
11290 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 lite3_column_int
112a0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 64(sqlite3_stmt*
112b0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e , int iCol);.con
112c0 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 st unsigned char
112d0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
112e0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 _text(sqlite3_st
112f0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
11300 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
11310 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
11320 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
11330 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 int iCol);.int
11340 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
11350 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ype(sqlite3_stmt
11360 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 *, int iCol);.sq
11370 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c lite3_value *sql
11380 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 ite3_column_valu
11390 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
113a0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a int iCol);../*.
113b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 ** CAPI3REF: Des
113c0 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 troy A Prepared
113d0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 Statement Object
113e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
113f0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 e3_finalize() fu
11400 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 nction is called
11410 20 74 6f 20 64 65 6c 65 74 65 20 61 20 0a 2a 2a to delete a .**
11420 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c [sqlite3_stmt |
11430 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 compiled SQL st
11440 61 74 65 6d 65 6e 74 5d 2e 20 49 66 20 74 68 65 atement]. If the
11450 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a statement was.*
11460 2a 20 65 78 65 63 75 74 65 64 20 73 75 63 63 65 * executed succe
11470 73 73 66 75 6c 6c 79 2c 20 6f 72 20 6e 6f 74 20 ssfully, or not
11480 65 78 65 63 75 74 65 64 20 61 74 20 61 6c 6c 2c executed at all,
11490 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 then SQLITE_OK
114a0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 is returned..**
114b0 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 If execution of
114c0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61 the statement fa
114d0 69 6c 65 64 20 74 68 65 6e 20 61 6e 20 0a 2a 2a iled then an .**
114e0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c [SQLITE_ERROR |
114f0 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 error code] or
11500 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 [SQLITE_IOERR_RE
11510 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 65 72 AD | extended er
11520 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 69 73 20 ror code].** is
11530 72 65 74 75 72 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a returned. .**.**
11540 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 This routine ca
11550 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 n be called at a
11560 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 ny point during
11570 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 the execution of
11580 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
11590 5f 73 74 6d 74 20 7c 20 76 69 72 74 75 61 6c 20 _stmt | virtual
115a0 6d 61 63 68 69 6e 65 5d 2e 20 20 49 66 20 74 68 machine]. If th
115b0 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e e virtual machin
115c0 65 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 63 6f e has not .** co
115d0 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f mpleted executio
115e0 6e 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74 n when this rout
115f0 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 ine is called, t
11600 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 hat is like.** e
11610 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 ncountering an e
11620 72 72 6f 72 20 6f 72 20 61 6e 20 69 6e 74 65 72 rror or an inter
11630 72 75 70 74 2e 20 20 28 53 65 65 20 5b 73 71 6c rupt. (See [sql
11640 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
11650 5d 2e 29 20 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 ].) .** Incomple
11660 74 65 20 75 70 64 61 74 65 73 20 6d 61 79 20 62 te updates may b
11670 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e e rolled back an
11680 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 d transactions c
11690 61 6e 63 65 6c 6c 65 64 2c 20 20 0a 2a 2a 20 64 ancelled, .** d
116a0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 epending on the
116b0 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61 circumstances, a
116c0 6e 64 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 nd the .** [SQLI
116d0 54 45 5f 45 52 52 4f 52 20 7c 20 72 65 73 75 6c TE_ERROR | resul
116e0 74 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64 t code] returned
116f0 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 will be [SQLITE
11700 5f 41 42 4f 52 54 5d 2e 0a 2a 2f 0a 69 6e 74 20 _ABORT]..*/.int
11710 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
11720 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 (sqlite3_stmt *p
11730 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Stmt);../*.** CA
11740 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 PI3REF: Reset A
11750 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 Prepared Stateme
11760 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 nt Object.**.**
11770 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 The sqlite3_rese
11780 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 t() function is
11790 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 called to reset
117a0 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 73 74 a .** [sqlite_st
117b0 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51 mt | compiled SQ
117c0 4c 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a L statement] obj
117d0 65 63 74 2e 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 ect..** back to
117e0 69 74 27 73 20 69 6e 69 74 69 61 6c 20 73 74 61 it's initial sta
117f0 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 te, ready to be
11800 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 re-executed..**
11810 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e Any SQL statemen
11820 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 t variables that
11830 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e had values boun
11840 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a d to them using.
11850 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f ** the [sqlite3_
11860 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 bind_blob | sqli
11870 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 te3_bind_*() API
11880 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 ] retain their v
11890 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 alues..** Use [s
118a0 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e qlite3_clear_bin
118b0 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 dings()] to rese
118c0 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a t the bindings..
118d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 */.int sqlite3_r
118e0 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d eset(sqlite3_stm
118f0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
11900 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 * CAPI3REF: Crea
11910 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 te Or Redefine S
11920 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a QL Functions.**.
11930 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 ** The following
11940 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 61 two functions a
11950 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 re used to add S
11960 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 QL functions or
11970 61 67 67 72 65 67 61 74 65 73 0a 2a 2a 20 6f 72 aggregates.** or
11980 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 to redefine the
11990 20 62 65 68 61 76 69 6f 72 20 6f 66 20 65 78 69 behavior of exi
119a0 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 sting SQL functi
119b0 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 ons or aggregate
119c0 73 2e 20 20 54 68 65 0a 2a 2a 20 64 69 66 66 65 s. The.** diffe
119d0 72 65 6e 63 65 20 6f 6e 6c 79 20 62 65 74 77 65 rence only betwe
119e0 65 6e 20 74 68 65 20 74 77 6f 20 69 73 20 74 68 en the two is th
119f0 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 at the second pa
11a00 72 61 6d 65 74 65 72 2c 20 74 68 65 0a 2a 2a 20 rameter, the.**
11a10 6e 61 6d 65 20 6f 66 20 74 68 65 20 28 73 63 61 name of the (sca
11a20 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72 lar) function or
11a30 20 61 67 67 72 65 67 61 74 65 2c 20 69 73 20 65 aggregate, is e
11a40 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 20 ncoded in UTF-8
11a50 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 for.** sqlite3_c
11a60 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
11a70 20 61 6e 64 20 55 54 46 2d 31 36 20 66 6f 72 20 and UTF-16 for
11a80 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
11a90 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a unction16()..**.
11aa0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 ** The first arg
11ab0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 5b 73 71 ument is the [sq
11ac0 6c 69 74 65 33 20 7c 20 64 61 74 61 62 61 73 65 lite3 | database
11ad0 20 68 61 6e 64 6c 65 5d 20 74 68 61 74 20 68 6f handle] that ho
11ae0 6c 64 73 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 lds the.** SQL f
11af0 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 unction or aggre
11b00 67 61 74 65 20 69 73 20 74 6f 20 62 65 20 61 64 gate is to be ad
11b10 64 65 64 20 6f 72 20 72 65 64 65 66 69 6e 65 64 ded or redefined
11b20 2e 20 49 66 20 61 20 73 69 6e 67 6c 65 0a 2a 2a . If a single.**
11b30 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 6d 6f program uses mo
11b40 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 re than one data
11b50 62 61 73 65 20 68 61 6e 64 6c 65 20 69 6e 74 65 base handle inte
11b60 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c rnally, then SQL
11b70 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 .** functions or
11b80 20 61 67 67 72 65 67 61 74 65 73 20 6d 75 73 74 aggregates must
11b90 20 62 65 20 61 64 64 65 64 20 69 6e 64 69 76 69 be added indivi
11ba0 64 75 61 6c 6c 79 20 74 6f 20 65 61 63 68 20 64 dually to each d
11bb0 61 74 61 62 61 73 65 0a 2a 2a 20 68 61 6e 64 6c atabase.** handl
11bc0 65 20 77 69 74 68 20 77 68 69 63 68 20 74 68 65 e with which the
11bd0 79 20 77 69 6c 6c 20 62 65 20 75 73 65 64 2e 0a y will be used..
11be0 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 **.** The second
11bf0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
11c00 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 e name of the SQ
11c10 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 L function to be
11c20 20 63 72 65 61 74 65 64 0a 2a 2a 20 6f 72 20 72 created.** or r
11c30 65 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 edefined..** The
11c40 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e length of the n
11c50 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 ame is limited t
11c60 6f 20 32 35 35 20 62 79 74 65 73 2c 20 65 78 63 o 255 bytes, exc
11c70 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 0a 2a lusive of the .*
11c80 2a 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f * zero-terminato
11c90 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 r. Note that th
11ca0 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69 e name length li
11cb0 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65 73 2c mit is in bytes,
11cc0 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74 65 not.** characte
11cd0 72 73 2e 20 20 41 6e 79 20 61 74 74 65 6d 70 74 rs. Any attempt
11ce0 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e to create a fun
11cf0 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e ction with a lon
11d00 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c ger name.** will
11d10 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 53 51 result in an SQ
11d20 4c 49 54 45 5f 45 52 52 4f 52 20 65 72 72 6f 72 LITE_ERROR error
11d30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 ..**.** The thir
11d40 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 d parameter is t
11d50 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 he number of arg
11d60 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 uments that the
11d70 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a SQL function or.
11d80 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b ** aggregate tak
11d90 65 73 2e 20 49 66 20 74 68 69 73 20 70 61 72 61 es. If this para
11da0 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 meter is negativ
11db0 65 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 e, then the SQL
11dc0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 function or.** a
11dd0 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b ggregate may tak
11de0 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 e any number of
11df0 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a arguments..**.**
11e00 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 The fourth para
11e10 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c meter, eTextRep,
11e20 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 20 specifies what
11e30 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 .** [SQLITE_UTF8
11e40 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 | text encoding
11e50 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 ] this SQL funct
11e60 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a ion prefers for.
11e70 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 ** its parameter
11e80 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e 63 s. Any SQL func
11e90 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 tion implementat
11ea0 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61 62 ion should be ab
11eb0 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f le to work.** wo
11ec0 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 rk with UTF-8, U
11ed0 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d TF-16le, or UTF-
11ee0 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 16be. But some
11ef0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
11f00 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 may be.** more e
11f10 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e fficient with on
11f20 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 e encoding than
11f30 61 6e 6f 74 68 65 72 2e 20 20 49 74 20 69 73 20 another. It is
11f40 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20 69 6e allowed to.** in
11f50 76 6f 6b 65 20 73 71 6c 69 74 65 5f 63 72 65 61 voke sqlite_crea
11f60 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 te_function() or
11f70 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
11f80 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c function16() mul
11f90 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 tiple.** times w
11fa0 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e ith the same fun
11fb0 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64 ction but with d
11fc0 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20 ifferent values
11fd0 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 of eTextRep..**
11fe0 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d When multiple im
11ff0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 plementations of
12000 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 the same functi
12010 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 on are available
12020 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c , SQLite.** will
12030 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 pick the one th
12040 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 at involves the
12050 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 least amount of
12060 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e data conversion.
12070 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 .** If there is
12080 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d only a single im
12090 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 plementation whi
120a0 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 ch does not care
120b0 20 77 68 61 74 0a 2a 2a 20 74 65 78 74 20 65 6e what.** text en
120c0 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 coding is used,
120d0 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 then the fourth
120e0 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 argument should
120f0 62 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 41 4e be.** [SQLITE_AN
12100 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 Y]..**.** The fi
12110 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 fth parameter is
12120 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f an arbitrary po
12130 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c inter. The impl
12140 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 ementation.** of
12150 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 63 61 the function ca
12160 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f n gain access to
12170 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 this pointer us
12180 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 75 ing.** [sqlite_u
12190 73 65 72 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a ser_data()]..**.
121a0 2a 2a 20 54 68 65 20 73 65 76 65 6e 74 68 2c 20 ** The seventh,
121b0 65 69 67 68 74 68 20 61 6e 64 20 6e 69 6e 74 68 eighth and ninth
121c0 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 parameters, xFu
121d0 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 nc, xStep and xF
121e0 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 inal, are.** poi
121f0 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 nters to C-langu
12200 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 age functions th
12210 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 at implement the
12220 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e SQL.** function
12230 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 20 41 or aggregate. A
12240 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 scalar SQL func
12250 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e tion requires an
12260 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
12270 6f 66 0a 2a 2a 20 74 68 65 20 78 46 75 6e 63 20 of.** the xFunc
12280 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e callback only, N
12290 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 73 68 6f ULL pointers sho
122a0 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 61 73 uld be passed as
122b0 20 74 68 65 20 78 53 74 65 70 0a 2a 2a 20 61 6e the xStep.** an
122c0 64 20 78 46 69 6e 61 6c 20 70 61 72 61 6d 65 74 d xFinal paramet
122d0 65 72 73 2e 20 41 6e 20 61 67 67 72 65 67 61 74 ers. An aggregat
122e0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 e SQL function r
122f0 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 equires an imple
12300 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 mentation.** of
12310 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c xStep and xFinal
12320 20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 and NULL should
12330 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 be passed for x
12340 46 75 6e 63 2e 20 54 6f 20 64 65 6c 65 74 65 20 Func. To delete
12350 61 6e 0a 2a 2a 20 65 78 69 73 74 69 6e 67 20 53 an.** existing S
12360 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 QL function or a
12370 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e ggregate, pass N
12380 55 4c 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 ULL for all thre
12390 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 e function.** ca
123a0 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 74 llback..**.** It
123b0 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f is permitted to
123c0 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 register multip
123d0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
123e0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a ns of the same.*
123f0 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 * functions with
12400 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 the same name b
12410 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64 ut with either d
12420 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 iffering numbers
12430 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 of.** arguments
12440 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 65 or differing pe
12450 72 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 rferred text enc
12460 6f 64 69 6e 67 73 2e 20 20 53 51 4c 69 74 65 20 odings. SQLite
12470 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 will use.** the
12480 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d implementation m
12490 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 ost closely matc
124a0 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 hes the way in w
124b0 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 hich the.** SQL
124c0 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 function is used
124d0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
124e0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
124f0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 2c 0a 20 (. sqlite3 *,.
12500 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 const char *zFu
12510 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e nctionName,. in
12520 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 t nArg,. int eT
12530 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 2a 2c extRep,. void*,
12540 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 . void (*xFunc)
12550 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
12560 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
12570 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
12580 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f *xStep)(sqlite3_
12590 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c context*,int,sql
125a0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 ite3_value**),.
125b0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 void (*xFinal)(
125c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
125d0 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 ).);.int sqlite3
125e0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
125f0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 16(. sqlite3*,.
12600 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 const void *zF
12610 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 unctionName,. i
12620 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 nt nArg,. int e
12630 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 2a TextRep,. void*
12640 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 ,. void (*xFunc
12650 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 )(sqlite3_contex
12660 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 t*,int,sqlite3_v
12670 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 alue**),. void
12680 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 (*xStep)(sqlite3
12690 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 _context*,int,sq
126a0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a lite3_value**),.
126b0 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 void (*xFinal)
126c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
126d0 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 *).);../*.** CAP
126e0 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f I3REF: Text Enco
126f0 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 dings.**.** Thes
12700 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e e constant defin
12710 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 e integer codes
12720 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 that represent t
12730 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 he various.** te
12740 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 xt encodings sup
12750 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 ported by SQLite
12760 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
12770 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 ITE_UTF8
12780 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 1.#define SQL
12790 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 ITE_UTF16LE
127a0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 2.#define SQL
127b0 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 ITE_UTF16BE
127c0 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 3.#define SQL
127d0 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 ITE_UTF16
127e0 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 4 /* Use n
127f0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
12800 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
12810 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 TE_ANY
12820 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 5 /* sqlite
12830 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
12840 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e n only */.#defin
12850 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 e SQLITE_UTF16_A
12860 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 LIGNED 8 /*
12870 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
12880 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f ollation only */
12890 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
128a0 3a 20 4f 62 73 6f 6c 65 74 65 20 46 75 6e 63 74 : Obsolete Funct
128b0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ions.**.** These
128c0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 61 functions are a
128d0 6c 6c 20 6e 6f 77 20 6f 62 73 6f 6c 65 74 65 2e ll now obsolete.
128e0 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 In order to ma
128f0 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 intain.** backwa
12900 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 rds compatibilit
12910 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 y with older cod
12920 65 2c 20 77 65 20 63 6f 6e 74 69 6e 75 65 20 74 e, we continue t
12930 6f 20 73 75 70 70 6f 72 74 0a 2a 2a 20 74 68 65 o support.** the
12940 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 48 se functions. H
12950 6f 77 65 76 65 72 2c 20 6e 65 77 20 64 65 76 65 owever, new deve
12960 6c 6f 70 6d 65 6e 74 20 70 72 6f 6a 65 63 74 73 lopment projects
12970 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a should avoid.**
12980 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 the use of thes
12990 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f e functions. To
129a0 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 help encourage
129b0 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a people to avoid.
129c0 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 ** using these f
129d0 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 unctions, we are
129e0 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 not going to te
129f0 6c 6c 20 79 6f 75 20 77 61 6e 74 20 74 68 65 79 ll you want they
12a00 20 64 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 do..*/.int sqli
12a10 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
12a20 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 unt(sqlite3_cont
12a30 65 78 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 ext*);.int sqlit
12a40 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 e3_expired(sqlit
12a50 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 e3_stmt*);.int s
12a60 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f qlite3_transfer_
12a70 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 bindings(sqlite3
12a80 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f _stmt*, sqlite3_
12a90 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 stmt*);.int sqli
12aa0 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 te3_global_recov
12ab0 65 72 28 76 6f 69 64 29 3b 0a 0a 0a 2f 2a 0a 2a er(void);.../*.*
12ac0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 * CAPI3REF: Obta
12ad0 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 ining SQL Functi
12ae0 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c on Parameter Val
12af0 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d ues.**.** The C-
12b00 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 language impleme
12b10 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 ntation of SQL f
12b20 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 unctions and agg
12b30 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 regates uses.**
12b40 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 this set of inte
12b50 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 rface routines t
12b60 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 o access the par
12b70 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e ameter values on
12b80 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e .** the function
12b90 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a or aggregate..*
12ba0 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 *.** The xFunc (
12bb0 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 for scalar funct
12bc0 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 ions) or xStep (
12bd0 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 for aggregates)
12be0 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f parameters.** to
12bf0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
12c00 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 _function()] and
12c10 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
12c20 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a _function16()].*
12c30 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 * define callbac
12c40 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e ks that implemen
12c50 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 t the SQL functi
12c60 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 ons and aggregat
12c70 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 es..** The 4th p
12c80 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 arameter to thes
12c90 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 e callbacks is a
12ca0 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 n array of point
12cb0 65 72 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 ers to.** [sqlit
12cc0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
12cd0 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 s. There is one
12ce0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d [sqlite3_value]
12cf0 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 object for.** e
12d00 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f ach parameter to
12d10 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
12d20 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e n. These routin
12d30 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a es are used to.*
12d40 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 * extract values
12d50 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 from the [sqlit
12d60 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
12d70 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 s..**.** These r
12d80 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 outines work jus
12d90 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 t like the corre
12da0 73 70 6f 6e 64 69 6e 67 20 0a 2a 2a 20 5b 73 71 sponding .** [sq
12db0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
12dc0 62 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 b | sqlite3_colu
12dd0 6d 6e 5f 2a 20 72 6f 75 74 69 6e 65 73 5d 20 65 mn_* routines] e
12de0 78 63 65 70 74 20 74 68 61 74 20 0a 2a 2a 20 74 xcept that .** t
12df0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 hese routines ta
12e00 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 73 71 6c ke a single [sql
12e10 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 6f 69 ite3_value*] poi
12e20 6e 74 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 nter instead.**
12e30 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 73 of an [sqlite3_s
12e40 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e tmt*] pointer an
12e50 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c d an integer col
12e60 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a umn number..**.*
12e70 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 * The sqlite3_va
12e80 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 lue_text16() int
12e90 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 erface extracts
12ea0 61 20 55 54 46 31 36 20 73 74 72 69 6e 67 0a 2a a UTF16 string.*
12eb0 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 * in the native
12ec0 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 byte-order of th
12ed0 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 e host machine.
12ee0 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f The.** sqlite3_
12ef0 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 value_text16be()
12f00 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c and sqlite3_val
12f10 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e ue_text16le() in
12f20 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 terfaces.** extr
12f30 61 63 74 20 55 54 46 31 36 20 73 74 72 69 6e 67 act UTF16 string
12f40 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 s as big-endian
12f50 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 and little-endia
12f60 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a n respectively..
12f70 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
12f80 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 3_value_numeric_
12f90 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 type() interface
12fa0 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 attempts to app
12fb0 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 ly.** numeric af
12fc0 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 finity to the va
12fd0 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 lue. This means
12fe0 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 that an attempt
12ff0 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 is.** made to c
13000 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 onvert the value
13010 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f to an integer o
13020 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 r floating point
13030 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 . If.** such a
13040 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f conversion is po
13050 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c ssible without l
13060 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 oss of informati
13070 6f 6e 20 28 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 on (in order.**
13080 77 6f 72 64 73 20 69 66 20 74 68 65 20 76 61 6c words if the val
13090 75 65 20 69 73 20 6f 72 69 67 69 6e 61 6c 20 61 ue is original a
130a0 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f string that loo
130b0 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 ks like a number
130c0 29 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 ).** then it is
130d0 64 6f 6e 65 2e 20 20 4f 74 68 65 72 77 69 73 65 done. Otherwise
130e0 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f no conversion o
130f0 63 63 75 72 73 2e 20 20 54 68 65 20 0a 2a 2a 20 ccurs. The .**
13100 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 [SQLITE_INTEGER
13110 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 | datatype] afte
13120 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 r conversion is
13130 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
13140 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69 Please pay parti
13150 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 cular attention
13160 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74 to the fact that
13170 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 the pointer tha
13180 74 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 t.** is returned
13190 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 from [sqlite3_v
131a0 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 alue_blob()], [s
131b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
131c0 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c t()], or.** [sql
131d0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
131e0 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6()] can be inva
131f0 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 lidated by a sub
13200 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a sequent call to.
13210 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ** [sqlite3_valu
13220 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c e_bytes()], [sql
13230 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 ite3_value_bytes
13240 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 5f 76 16()], [sqlite_v
13250 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a alue_text()],.**
13260 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c or [sqlite3_val
13270 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 20 20 0a ue_text16()]. .
13280 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 */.const void *s
13290 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f qlite3_value_blo
132a0 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a b(sqlite3_value*
132b0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 );.int sqlite3_v
132c0 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 alue_bytes(sqlit
132d0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 e3_value*);.int
132e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 sqlite3_value_by
132f0 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 tes16(sqlite3_va
13300 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 lue*);.double sq
13310 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 lite3_value_doub
13320 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 le(sqlite3_value
13330 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f *);.int sqlite3_
13340 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 value_int(sqlite
13350 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 3_value*);.sqlit
13360 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f e_int64 sqlite3_
13370 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 value_int64(sqli
13380 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e te3_value*);.con
13390 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 st unsigned char
133a0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f *sqlite3_value_
133b0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c text(sqlite3_val
133c0 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 ue*);.const void
133d0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f *sqlite3_value_
133e0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 text16(sqlite3_v
133f0 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f alue*);.const vo
13400 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 id *sqlite3_valu
13410 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 e_text16le(sqlit
13420 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 e3_value*);.cons
13430 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
13440 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 value_text16be(s
13450 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
13460 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 int sqlite3_valu
13470 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 e_type(sqlite3_v
13480 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 alue*);.int sqli
13490 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 te3_value_numeri
134a0 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 c_type(sqlite3_v
134b0 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 alue*);../*.** C
134c0 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 API3REF: Obtain
134d0 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 Aggregate Functi
134e0 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a on Context.**.**
134f0 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 The implementat
13500 69 6f 6e 20 6f 66 20 61 67 67 72 65 67 61 74 65 ion of aggregate
13510 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 SQL functions u
13520 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 se this routine
13530 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61 to allocate.** a
13540 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 73 structure for s
13550 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 toring their sta
13560 74 65 2e 20 20 54 68 65 20 66 69 72 73 74 20 74 te. The first t
13570 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 ime this routine
13580 0a 2a 2a 20 69 73 20 63 61 6c 6c 65 64 20 66 6f .** is called fo
13590 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 r a particular a
135a0 67 67 72 65 67 61 74 65 2c 20 61 20 6e 65 77 20 ggregate, a new
135b0 73 74 72 75 63 74 75 72 65 20 6f 66 20 73 69 7a structure of siz
135c0 65 20 6e 42 79 74 65 73 0a 2a 2a 20 69 73 20 61 e nBytes.** is a
135d0 6c 6c 6f 63 61 74 65 64 2c 20 7a 65 72 6f 65 64 llocated, zeroed
135e0 2c 20 61 6e 64 20 72 65 74 75 72 6e 65 64 2e 20 , and returned.
135f0 20 4f 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 On subsequent c
13600 61 6c 6c 73 20 28 66 6f 72 20 74 68 65 0a 2a 2a alls (for the.**
13610 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 same aggregate
13620 69 6e 73 74 61 6e 63 65 29 20 74 68 65 20 73 61 instance) the sa
13630 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74 me buffer is ret
13640 75 72 6e 65 64 2e 20 20 54 68 65 20 69 6d 70 6c urned. The impl
13650 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 ementation.** of
13660 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 63 the aggregate c
13670 61 6e 20 75 73 65 20 74 68 65 20 72 65 74 75 72 an use the retur
13680 6e 65 64 20 62 75 66 66 65 72 20 74 6f 20 61 63 ned buffer to ac
13690 63 75 6d 75 6c 61 74 65 20 64 61 74 61 2e 0a 2a cumulate data..*
136a0 2a 0a 2a 2a 20 54 68 65 20 62 75 66 66 65 72 20 *.** The buffer
136b0 61 6c 6c 6f 63 61 74 65 64 20 69 73 20 66 72 65 allocated is fre
136c0 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ed automatically
136d0 20 62 79 20 53 51 4c 69 74 65 20 77 68 61 6e 20 by SQLite whan
136e0 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a the aggregate.**
136f0 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 query concludes
13700 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 ..**.** The firs
13710 74 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 t parameter shou
13720 6c 64 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 ld be a copy of
13730 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the .** [sqlite3
13740 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 _context | SQL f
13750 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d unction context]
13760 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72 that is the fir
13770 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 st.** parameter
13780 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 to the callback
13790 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 routine that imp
137a0 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 lements the aggr
137b0 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f egate.** functio
137c0 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 n..*/.void *sqli
137d0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
137e0 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f ntext(sqlite3_co
137f0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 ntext*, int nByt
13800 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 es);../*.** CAPI
13810 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 3REF: User Data
13820 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a For Functions.**
13830 0a 2a 2a 20 54 68 65 20 70 55 73 65 72 44 61 74 .** The pUserDat
13840 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 a parameter to t
13850 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 he [sqlite3_crea
13860 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a te_function()].*
13870 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 * and [sqlite3_c
13880 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
13890 28 29 5d 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 ()] routines.**
138a0 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 used to register
138b0 20 75 73 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 user functions
138c0 69 73 20 61 76 61 69 6c 61 62 6c 65 20 74 6f 0a is available to.
138d0 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 ** the implement
138e0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 66 75 6e ation of the fun
138f0 63 74 69 6f 6e 20 75 73 69 6e 67 20 74 68 69 73 ction using this
13900 20 63 61 6c 6c 2e 0a 2a 2f 0a 76 6f 69 64 20 2a call..*/.void *
13910 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 sqlite3_user_dat
13920 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 a(sqlite3_contex
13930 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
13940 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 3REF: Function A
13950 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a uxiliary Data.**
13960 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e .** The followin
13970 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 g two functions
13980 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73 may be used by s
13990 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 calar SQL functi
139a0 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 ons to.** associ
139b0 61 74 65 20 6d 65 74 61 2d 64 61 74 61 20 77 69 ate meta-data wi
139c0 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 th argument valu
139d0 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 es. If the same
139e0 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 value is passed
139f0 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 to.** multiple i
13a00 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 nvocations of th
13a10 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 e same SQL funct
13a20 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 ion during query
13a30 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 execution, unde
13a40 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d r.** some circum
13a50 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f stances the asso
13a60 63 69 61 74 65 64 20 6d 65 74 61 2d 64 61 74 61 ciated meta-data
13a70 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 may be preserve
13a80 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 d. This may.** b
13a90 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d e used, for exam
13aa0 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 ple, to add a re
13ab0 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e gular-expression
13ac0 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 matching scalar
13ad0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 .** function. Th
13ae0 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 e compiled versi
13af0 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 on of the regula
13b00 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 r expression is
13b10 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 stored as.** met
13b20 61 2d 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 a-data associate
13b30 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 d with the SQL v
13b40 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 alue passed as t
13b50 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 he regular expre
13b60 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e ssion.** pattern
13b70 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 . The compiled
13b80 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 regular expressi
13b90 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 on can be reused
13ba0 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 on multiple.**
13bb0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 invocations of t
13bc0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e he same function
13bd0 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 so that the ori
13be0 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 ginal pattern st
13bf0 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 ring.** does not
13c00 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f need to be reco
13c10 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 mpiled on each i
13c20 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a nvocation..**.**
13c30 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 The sqlite3_get
13c40 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 _auxdata() inter
13c50 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 face returns a p
13c60 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 ointer to the me
13c70 74 61 2d 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 ta-data.** assoc
13c80 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 4e iated with the N
13c90 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 th argument valu
13ca0 65 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 e to the current
13cb0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a SQL function.**
13cc0 20 63 61 6c 6c 2c 20 77 68 65 72 65 20 4e 20 69 call, where N i
13cd0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 s the second par
13ce0 61 6d 65 74 65 72 2e 20 49 66 20 6e 6f 20 6d 65 ameter. If no me
13cf0 74 61 2d 64 61 74 61 20 68 61 73 20 62 65 65 6e ta-data has been
13d00 20 73 65 74 20 66 6f 72 0a 2a 2a 20 74 68 61 74 set for.** that
13d10 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 20 4e value, then a N
13d20 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 ULL pointer is r
13d30 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 eturned..**.** T
13d40 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 he sqlite3_set_a
13d50 75 78 64 61 74 61 28 29 20 69 73 20 75 73 65 64 uxdata() is used
13d60 20 74 6f 20 61 73 73 6f 63 69 61 74 65 20 6d 65 to associate me
13d70 74 61 2d 64 61 74 61 20 77 69 74 68 20 61 6e 20 ta-data with an
13d80 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 SQL.** function
13d90 61 72 67 75 6d 65 6e 74 2e 20 54 68 65 20 74 68 argument. The th
13da0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ird parameter is
13db0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
13dc0 65 20 6d 65 74 61 2d 64 61 74 61 0a 2a 2a 20 74 e meta-data.** t
13dd0 6f 20 62 65 20 61 73 73 6f 63 69 61 74 65 64 20 o be associated
13de0 77 69 74 68 20 74 68 65 20 4e 74 68 20 75 73 65 with the Nth use
13df0 72 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d r function argum
13e00 65 6e 74 20 76 61 6c 75 65 2e 20 54 68 65 20 66 ent value. The f
13e10 6f 75 72 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 ourth.** paramet
13e20 65 72 20 73 70 65 63 69 66 69 65 73 20 61 20 64 er specifies a d
13e30 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 77 estructor that w
13e40 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e ill be called on
13e50 20 74 68 65 20 6d 65 74 61 2d 0a 2a 2a 20 64 61 the meta-.** da
13e60 74 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 72 65 ta pointer to re
13e70 6c 65 61 73 65 20 69 74 20 77 68 65 6e 20 69 74 lease it when it
13e80 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 is no longer re
13e90 71 75 69 72 65 64 2e 20 49 66 20 74 68 65 20 0a quired. If the .
13ea0 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 ** destructor is
13eb0 20 4e 55 4c 4c 2c 20 69 74 20 69 73 20 6e 6f 74 NULL, it is not
13ec0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 invoked..**.**
13ed0 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 In practice, met
13ee0 61 2d 64 61 74 61 20 69 73 20 70 72 65 73 65 72 a-data is preser
13ef0 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 ved between func
13f00 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a tion calls for.*
13f10 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 * expressions th
13f20 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 at are constant
13f30 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e at compile time.
13f40 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c This includes l
13f50 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 iteral.** values
13f60 20 61 6e 64 20 53 51 4c 20 76 61 72 69 61 62 6c and SQL variabl
13f70 65 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c es..*/.void *sql
13f80 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 ite3_get_auxdata
13f90 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
13fa0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 *, int);.void sq
13fb0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 lite3_set_auxdat
13fc0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 a(sqlite3_contex
13fd0 74 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 2a 2c 20 t*, int, void*,
13fe0 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 void (*)(void*))
13ff0 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 ;.../*.** CAPI3R
14000 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 EF: Constants De
14010 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 fining Special D
14020 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 estructor Behavi
14030 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 or.**.** These a
14040 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 re special value
14050 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 for the destruc
14060 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73 tor that is pass
14070 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 ed in as the.**
14080 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 final argument t
14090 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 o routines like
140a0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
140b0 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20 74 68 65 blob()]. If the
140c0 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 destructor.** a
140d0 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 rgument is SQLIT
140e0 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 E_STATIC, it mea
140f0 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 ns that the cont
14100 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 ent pointer is c
14110 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 onstant.** and w
14120 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 ill never change
14130 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e . It does not n
14140 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f eed to be destro
14150 79 65 64 2e 20 20 54 68 65 20 0a 2a 2a 20 53 51 yed. The .** SQ
14160 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 LITE_TRANSIENT v
14170 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 alue means that
14180 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c the content will
14190 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 likely change i
141a0 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 n.** the near fu
141b0 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 ture and that SQ
141c0 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 Lite should make
141d0 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 its own private
141e0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 copy of.** the
141f0 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 content before r
14200 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 eturning..**.**
14210 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e The typedef is n
14220 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b ecessary to work
14230 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 around problems
14240 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 in certain.** C
14250 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 ++ compilers. S
14260 65 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e ee ticket #2191.
14270 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 .*/.typedef void
14280 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 (*sqlite3_destr
14290 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 uctor_type)(void
142a0 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 *);.#define SQLI
142b0 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 TE_STATIC (
142c0 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 (sqlite3_destruc
142d0 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 tor_type)0).#def
142e0 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 ine SQLITE_TRANS
142f0 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 IENT ((sqlite3
14300 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 _destructor_type
14310 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 )-1)../*.** CAPI
14320 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 3REF: Setting Th
14330 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 e Result Of An S
14340 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a QL Function.**.*
14350 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
14360 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 are used by the
14370 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c xFunc or xFinal
14380 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a callbacks that.
14390 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c ** implement SQL
143a0 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 functions and a
143b0 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a ggregates. See.
143c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 ** [sqlite3_crea
143d0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 te_function()] a
143e0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 nd [sqlite3_crea
143f0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d te_function16()]
14400 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e .** for addition
14410 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a al information..
14420 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 **.** These func
14430 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 tions work very
14440 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 0a 2a much like the .*
14450 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
14460 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 blob | sqlite3_b
14470 69 6e 64 5f 2a 5d 20 66 61 6d 69 6c 79 20 6f 66 ind_*] family of
14480 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 0a functions used.
14490 2a 2a 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 ** to bind value
144a0 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 s to host parame
144b0 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 ters in prepared
144c0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 statements..**
144d0 52 65 66 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 Refer to the.**
144e0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
144f0 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e ob | sqlite3_bin
14500 64 5f 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f d_* documentatio
14510 6e 5d 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 n] for.** additi
14520 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
14530 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The 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 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 () and sqlite3_r
14560 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 esult_error16()
14570 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 functions.** cau
14580 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 se the implement
14590 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 ed SQL function
145a0 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 to throw an exce
145b0 70 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 70 ption. The.** p
145c0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
145d0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
145e0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 () or sqlite3_re
145f0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a sult_error16().*
14600 2a 20 69 73 20 74 68 65 20 74 65 78 74 20 6f 66 * is the text of
14610 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 an error messag
14620 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c e..**.** The sql
14630 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 ite3_result_toob
14640 69 67 28 29 20 63 61 75 73 65 20 74 68 65 20 66 ig() cause the f
14650 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e unction implemen
14660 74 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 72 tation.** to thr
14670 6f 77 20 61 6e 64 20 65 72 72 6f 72 20 69 6e 64 ow and error ind
14680 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 icating that a s
14690 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 tring or BLOB is
146a0 20 74 6f 20 6c 6f 6e 67 0a 2a 2a 20 74 6f 20 72 to long.** to r
146b0 65 70 72 65 73 65 6e 74 2e 0a 2a 2f 0a 76 6f 69 epresent..*/.voi
146c0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
146d0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f _blob(sqlite3_co
146e0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f ntext*, const vo
146f0 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a id*, int, void(*
14700 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 )(void*));.void
14710 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 sqlite3_result_d
14720 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f ouble(sqlite3_co
14730 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b ntext*, double);
14740 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
14750 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 sult_error(sqlit
14760 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e e3_context*, con
14770 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a st char*, int);.
14780 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
14790 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 ult_error16(sqli
147a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f te3_context*, co
147b0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b nst void*, int);
147c0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
147d0 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 sult_error_toobi
147e0 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 g(sqlite3_contex
147f0 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 t*);.void sqlite
14800 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 3_result_int(sql
14810 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 ite3_context*, i
14820 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 nt);.void sqlite
14830 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 3_result_int64(s
14840 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
14850 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 29 3b 0a sqlite_int64);.
14860 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
14870 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 ult_null(sqlite3
14880 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 _context*);.void
14890 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
148a0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e text(sqlite3_con
148b0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 text*, const cha
148c0 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 r*, int, void(*)
148d0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 (void*));.void s
148e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
148f0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e xt16(sqlite3_con
14900 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 text*, const voi
14910 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 d*, int, void(*)
14920 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 (void*));.void s
14930 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
14940 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 xt16le(sqlite3_c
14950 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 ontext*, const v
14960 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a oid*, int,void(*
14970 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 )(void*));.void
14980 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
14990 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f ext16be(sqlite3_
149a0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
149b0 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 void*, int,void(
149c0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 *)(void*));.void
149d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
149e0 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f value(sqlite3_co
149f0 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f ntext*, sqlite3_
14a00 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 value*);.void sq
14a10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 lite3_result_zer
14a20 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f oblob(sqlite3_co
14a30 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a ntext*, int n);.
14a40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
14a50 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c Define New Coll
14a60 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a ating Sequences.
14a70 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 **.** These func
14a80 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 tions are used t
14a90 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 o add new collat
14aa0 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f ion sequences to
14ab0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
14ac0 2a 5d 20 68 61 6e 64 6c 65 20 73 70 65 63 69 66 *] handle specif
14ad0 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 ied as the first
14ae0 20 61 72 67 75 6d 65 6e 74 2e 20 0a 2a 2a 0a 2a argument. .**.*
14af0 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 * The name of th
14b00 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 e new collation
14b10 73 65 71 75 65 6e 63 65 20 69 73 20 73 70 65 63 sequence is spec
14b20 69 66 69 65 64 20 61 73 20 61 20 55 54 46 2d 38 ified as a UTF-8
14b30 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 string.** for s
14b40 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
14b50 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 llation() and sq
14b60 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
14b70 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 lation_v2().** a
14b80 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 nd a UTF-16 stri
14b90 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 ng for sqlite3_c
14ba0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 reate_collation1
14bb0 36 28 29 2e 20 20 49 6e 20 61 6c 6c 20 63 61 73 6(). In all cas
14bc0 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 es.** the name i
14bd0 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 s passed as the
14be0 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 second function
14bf0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 argument..**.**
14c00 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 The third argume
14c10 6e 74 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f nt must be one o
14c20 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 f the constants
14c30 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a [SQLITE_UTF8],.*
14c40 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c * [SQLITE_UTF16L
14c50 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 E] or [SQLITE_UT
14c60 46 31 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 F16BE], indicati
14c70 6e 67 20 74 68 61 74 20 74 68 65 20 75 73 65 72 ng that the user
14c80 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 -supplied.** rou
14c90 74 69 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20 tine expects to
14ca0 62 65 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65 be passed pointe
14cb0 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e rs to strings en
14cc0 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d coded using UTF-
14cd0 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 8,.** UTF-16 lit
14ce0 74 6c 65 2d 65 6e 64 69 61 6e 20 6f 72 20 55 54 tle-endian or UT
14cf0 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 20 F-16 big-endian
14d00 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a respectively..**
14d10 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f .** A pointer to
14d20 20 74 68 65 20 75 73 65 72 20 73 75 70 70 6c 69 the user suppli
14d30 65 64 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 ed routine must
14d40 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 be passed as the
14d50 20 66 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 fifth.** argume
14d60 6e 74 2e 20 49 66 20 69 74 20 69 73 20 4e 55 4c nt. If it is NUL
14d70 4c 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 73 L, this is the s
14d80 61 6d 65 20 61 73 20 64 65 6c 65 74 69 6e 67 20 ame as deleting
14d90 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a the collation.**
14da0 20 73 65 71 75 65 6e 63 65 20 28 73 6f 20 74 68 sequence (so th
14db0 61 74 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 at SQLite cannot
14dc0 20 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 call it anymore
14dd0 29 2e 20 45 61 63 68 20 74 69 6d 65 20 74 68 65 ). Each time the
14de0 20 75 73 65 72 0a 2a 2a 20 73 75 70 70 6c 69 65 user.** supplie
14df0 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e d function is in
14e00 76 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 61 73 voked, it is pas
14e10 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 sed a copy of th
14e20 65 20 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61 e void* passed a
14e30 73 0a 2a 2a 20 74 68 65 20 66 6f 75 72 74 68 20 s.** the fourth
14e40 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
14e50 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
14e60 74 69 6f 6e 28 29 20 6f 72 0a 2a 2a 20 73 71 6c tion() or.** sql
14e70 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
14e80 61 74 69 6f 6e 31 36 28 29 20 61 73 20 69 74 73 ation16() as its
14e90 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
14ea0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d 61 ..**.** The rema
14eb0 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 ining arguments
14ec0 74 6f 20 74 68 65 20 75 73 65 72 2d 73 75 70 70 to the user-supp
14ed0 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 61 72 65 lied routine are
14ee0 20 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a two strings,.**
14ef0 20 65 61 63 68 20 72 65 70 72 65 73 65 6e 74 65 each represente
14f00 64 20 62 79 20 61 20 5b 6c 65 6e 67 74 68 2c 20 d by a [length,
14f10 64 61 74 61 5d 20 70 61 69 72 20 61 6e 64 20 65 data] pair and e
14f20 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 20 65 6e ncoded in the en
14f30 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 coding.** that w
14f40 61 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 as passed as the
14f50 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 third argument
14f60 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 when the collati
14f70 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 61 73 0a on sequence was.
14f80 2a 2a 20 72 65 67 69 73 74 65 72 65 64 2e 20 54 ** registered. T
14f90 68 65 20 75 73 65 72 20 72 6f 75 74 69 6e 65 20 he user routine
14fa0 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 6e 65 should return ne
14fb0 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 gative, zero or
14fc0 70 6f 73 69 74 69 76 65 20 69 66 0a 2a 2a 20 74 positive if.** t
14fd0 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 he first string
14fe0 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 is less than, eq
14ff0 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 ual to, or great
15000 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f er than the seco
15010 6e 64 0a 2a 2a 20 73 74 72 69 6e 67 2e 20 69 2e nd.** string. i.
15020 65 2e 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54 e. (STRING1 - ST
15030 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 RING2)..**.** Th
15040 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 e sqlite3_create
15050 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 _collation_v2()
15060 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 works like sqlit
15070 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
15080 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 61 70 74 20 ion().** excapt
15090 74 68 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e that it takes an
150a0 20 65 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20 extra argument
150b0 77 68 69 63 68 20 69 73 20 61 20 64 65 73 74 72 which is a destr
150c0 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 uctor for.** the
150d0 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65 collation. The
150e0 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 destructor is c
150f0 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 63 alled when the c
15100 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 ollation is.** d
15110 65 73 74 72 6f 79 65 64 20 61 6e 64 20 69 73 20 estroyed and is
15120 70 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66 passed a copy of
15130 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
15140 6d 65 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e meter void* poin
15150 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 ter.** of the sq
15160 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
15170 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 20 20 43 6f lation_v2(). Co
15180 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 64 65 73 llations are des
15190 74 72 6f 79 65 64 20 77 68 65 6e 0a 2a 2a 20 74 troyed when.** t
151a0 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 hey are overridd
151b0 65 6e 20 62 79 20 6c 61 74 65 72 20 63 61 6c 6c en by later call
151c0 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 s to the collati
151d0 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 on creation func
151e0 74 69 6f 6e 73 0a 2a 2a 20 6f 72 20 77 68 65 6e tions.** or when
151f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20 the [sqlite3*]
15200 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 database handle
15210 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 is closed using
15220 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 [sqlite3_close()
15230 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c ]..**.** The sql
15240 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
15250 61 74 69 6f 6e 5f 76 32 28 29 20 69 6e 74 65 72 ation_v2() inter
15260 66 61 63 65 20 69 73 20 65 78 70 65 72 69 6d 65 face is experime
15270 6e 74 61 6c 20 61 6e 64 0a 2a 2a 20 73 75 62 6a ntal and.** subj
15280 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e ect to change in
15290 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
152a0 2e 20 20 54 68 65 20 6f 74 68 65 72 20 63 6f 6c . The other col
152b0 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 0a lation creation.
152c0 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 ** functions are
152d0 20 73 74 61 62 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 stable..*/.int
152e0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
152f0 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 ollation(. sqli
15300 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 te3*, . const c
15310 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 har *zName, . i
15320 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 nt eTextRep, .
15330 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 void*,. int(*xC
15340 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e ompare)(void*,in
15350 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e t,const void*,in
15360 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 t,const void*).)
15370 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 ;.int sqlite3_cr
15380 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 eate_collation_v
15390 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 2(. sqlite3*, .
153a0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e const char *zN
153b0 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 ame, . int eTex
153c0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a tRep, . void*,.
153d0 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 int(*xCompare)
153e0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 (void*,int,const
153f0 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 void*,int,const
15400 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 void*),. void(
15410 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a *xDestroy)(void*
15420 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 ).);.int sqlite3
15430 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
15440 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c n16(. sqlite3*,
15450 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a . const char *
15460 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 zName, . int eT
15470 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a extRep, . void*
15480 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 ,. int(*xCompar
15490 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e e)(void*,int,con
154a0 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e st void*,int,con
154b0 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a st void*).);../*
154c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
154d0 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 llation Needed C
154e0 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 54 allbacks.**.** T
154f0 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 o avoid having t
15500 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 o register all c
15510 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 ollation sequenc
15520 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 es before a data
15530 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 base.** can be u
15540 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 sed, a single ca
15550 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
15560 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 may be registere
15570 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 64 61 d with the.** da
15580 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74 6f tabase handle to
15590 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 be called whene
155a0 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 ver an undefined
155b0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 collation seque
155c0 6e 63 65 20 69 73 0a 2a 2a 20 72 65 71 75 69 72 nce is.** requir
155d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 ed..**.** If the
155e0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 function is reg
155f0 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 istered using th
15600 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 e sqlite3_collat
15610 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 ion_needed() API
15620 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 ,.** then it is
15630 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 passed the names
15640 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f of undefined co
15650 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 llation sequence
15660 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 s as strings.**
15670 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 encoded in UTF-8
15680 2e 20 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c . If sqlite3_col
15690 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 lation_needed16(
156a0 29 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 6e ) is used, the n
156b0 61 6d 65 73 0a 2a 2a 20 61 72 65 20 70 61 73 73 ames.** are pass
156c0 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 ed as UTF-16 in
156d0 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 machine native b
156e0 79 74 65 20 6f 72 64 65 72 2e 20 41 20 63 61 6c yte order. A cal
156f0 6c 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 66 l to either.** f
15700 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 unction replaces
15710 20 61 6e 79 20 65 78 69 73 74 69 6e 67 20 63 61 any existing ca
15720 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 llback..**.** Wh
15730 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 en the callback
15740 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 is invoked, the
15750 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 first argument p
15760 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a assed is a copy.
15770 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 ** of the second
15780 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c argument to sql
15790 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e ite3_collation_n
157a0 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 eeded() or.** sq
157b0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
157c0 6e 65 65 64 65 64 31 36 28 29 2e 20 54 68 65 20 needed16(). The
157d0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
157e0 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a is the database.
157f0 2a 2a 20 68 61 6e 64 6c 65 2e 20 54 68 65 20 74 ** handle. The t
15800 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 hird argument is
15810 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f one of [SQLITE_
15820 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 UTF8], [SQLITE_U
15830 54 46 31 36 42 45 5d 2c 20 6f 72 0a 2a 2a 20 5b TF16BE], or.** [
15840 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c SQLITE_UTF16LE],
15850 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 indicating the
15860 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 most desirable f
15870 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 orm of the colla
15880 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 tion.** sequence
15890 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 function requir
158a0 65 64 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 ed. The fourth p
158b0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 arameter is the
158c0 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 name of the.** r
158d0 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f equired collatio
158e0 6e 20 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a n sequence..**.*
158f0 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 * The callback f
15900 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 unction should r
15910 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69 egister the desi
15920 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 red collation us
15930 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
15940 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
15950 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 ()], [sqlite3_cr
15960 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 eate_collation16
15970 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 ()], or.** [sqli
15980 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
15990 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 tion_v2()]..*/.i
159a0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 nt sqlite3_colla
159b0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 tion_needed(. s
159c0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 qlite3*, . void
159d0 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f *, . void(*)(vo
159e0 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 id*,sqlite3*,int
159f0 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 eTextRep,const
15a00 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 char*).);.int sq
15a10 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
15a20 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 needed16(. sqli
15a30 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a te3*, . void*,.
15a40 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c void(*)(void*,
15a50 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 sqlite3*,int eTe
15a60 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 xtRep,const void
15a70 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 *).);../*.** Spe
15a80 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 cify the key for
15a90 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 an encrypted da
15aa0 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f tabase. This ro
15ab0 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a utine should be.
15ac0 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 ** called right
15ad0 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 after sqlite3_op
15ae0 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 en()..**.** The
15af0 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e code to implemen
15b00 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f t this API is no
15b10 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 t available in t
15b20 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 he public releas
15b30 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a e.** of SQLite..
15b40 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b */.int sqlite3_k
15b50 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 ey(. sqlite3 *d
15b60 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 b,
15b70 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
15b80 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a to be rekeyed *
15b90 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a /. const void *
15ba0 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 pKey, int nKey
15bb0 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f /* The key */
15bc0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 .);../*.** Chang
15bd0 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 e the key on an
15be0 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 open database.
15bf0 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 If the current d
15c00 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a atabase is not.*
15c10 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 * encrypted, thi
15c20 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 s routine will e
15c30 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 ncrypt it. If p
15c40 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d New==0 or nNew==
15c50 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 0, the.** databa
15c60 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64 2e se is decrypted.
15c70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 .**.** The code
15c80 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 to implement thi
15c90 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 s API is not ava
15ca0 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 ilable in the pu
15cb0 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 blic release.**
15cc0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e of SQLite..*/.in
15cd0 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 t sqlite3_rekey(
15ce0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
15cf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
15d00 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f /* Database to
15d10 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 be rekeyed */.
15d20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 const void *pKe
15d30 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 y, int nKey
15d40 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a /* The new key *
15d50 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.);../*.** CAPI
15d60 33 52 45 46 3a 20 20 53 75 73 70 65 6e 64 20 45 3REF: Suspend E
15d70 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 xecution For A S
15d80 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 hort Time.**.**
15d90 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 This function ca
15da0 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 uses the current
15db0 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 thread to suspe
15dc0 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 nd execution.**
15dd0 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c a number of mill
15de0 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 iseconds specifi
15df0 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 ed in its parame
15e00 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ter..**.** If th
15e10 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 e operating syst
15e20 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 em does not supp
15e30 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 ort sleep reques
15e40 74 73 20 77 69 74 68 20 0a 2a 2a 20 6d 69 6c 6c ts with .** mill
15e50 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 isecond time res
15e60 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 olution, then th
15e70 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 e time will be r
15e80 6f 75 6e 64 65 64 20 75 70 20 74 6f 20 0a 2a 2a ounded up to .**
15e90 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 the nearest sec
15ea0 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 ond. The number
15eb0 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 of milliseconds
15ec0 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c of sleep actuall
15ed0 79 20 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 y .** requested
15ee0 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 from the operati
15ef0 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 ng system is ret
15f00 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 urned..*/.int sq
15f10 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 lite3_sleep(int)
15f20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
15f30 46 3a 20 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 F: Name Of The
15f40 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 Folder Holding T
15f50 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a emporary Files.*
15f60 2a 0a 2a 2a 20 49 66 20 74 68 69 73 20 67 6c 6f *.** If this glo
15f70 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 bal variable is
15f80 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f made to point to
15f90 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 a string which
15fa0 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f is.** the name o
15fb0 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 61 f a folder (a.ka
15fc0 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 . directory), th
15fd0 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 en all temporary
15fe0 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 files.** create
15ff0 64 20 62 79 20 53 51 4c 69 74 65 20 77 69 6c 6c d by SQLite will
16000 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 be placed in th
16010 61 74 20 64 69 72 65 63 74 6f 72 79 2e 20 20 49 at directory. I
16020 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a f this variable.
16030 2a 2a 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 ** is NULL point
16040 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 er, then SQLite
16050 64 6f 65 73 20 61 20 73 65 61 72 63 68 20 66 6f does a search fo
16060 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 r an appropriate
16070 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 66 69 temporary.** fi
16080 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a le directory..**
16090 0a 2a 2a 20 4f 6e 63 65 20 5b 73 71 6c 69 74 65 .** Once [sqlite
160a0 33 5f 6f 70 65 6e 28 29 5d 20 68 61 73 20 62 65 3_open()] has be
160b0 65 6e 20 63 61 6c 6c 65 64 2c 20 63 68 61 6e 67 en called, chang
160c0 69 6e 67 20 74 68 69 73 20 76 61 72 69 61 62 6c ing this variabl
160d0 65 20 77 69 6c 6c 0a 2a 2a 20 69 6e 76 61 6c 69 e will.** invali
160e0 64 61 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 date the current
160f0 20 74 65 6d 70 6f 72 61 72 79 20 64 61 74 61 62 temporary datab
16100 61 73 65 2c 20 69 66 20 61 6e 79 2e 20 20 47 65 ase, if any. Ge
16110 6e 65 72 61 6c 6c 79 20 73 70 65 61 6b 69 6e 67 nerally speaking
16120 2c 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 73 ,.** it is not s
16130 61 66 65 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 afe to invoke th
16140 69 73 20 72 6f 75 74 69 6e 65 20 61 66 74 65 72 is routine after
16150 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
16160 5d 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 63 61 ] has.** been ca
16170 6c 6c 65 64 2e 0a 2a 2f 0a 65 78 74 65 72 6e 20 lled..*/.extern
16180 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 char *sqlite3_te
16190 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f mp_directory;../
161a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 *.** CAPI3REF:
161b0 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 Test To See If T
161c0 68 65 20 44 61 74 61 62 73 65 20 49 73 20 49 6e he Databse Is In
161d0 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 Auto-Commit Mod
161e0 65 0a 2a 2a 0a 2a 2a 20 54 65 73 74 20 74 6f 20 e.**.** Test to
161f0 73 65 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e see whether or n
16200 6f 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ot the database
16210 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e connection is in
16220 20 61 75 74 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 6d autocommit.** m
16230 6f 64 65 2e 20 20 52 65 74 75 72 6e 20 54 52 55 ode. Return TRU
16240 45 20 69 66 20 69 74 20 69 73 20 61 6e 64 20 46 E if it is and F
16250 41 4c 53 45 20 69 66 20 6e 6f 74 2e 20 20 41 75 ALSE if not. Au
16260 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 tocommit mode is
16270 20 6f 6e 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c on.** by defaul
16280 74 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 69 t. Autocommit i
16290 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 s disabled by a
162a0 42 45 47 49 4e 20 73 74 61 74 65 6d 65 6e 74 20 BEGIN statement
162b0 61 6e 64 20 72 65 65 6e 61 62 6c 65 64 0a 2a 2a and reenabled.**
162c0 20 62 79 20 74 68 65 20 6e 65 78 74 20 43 4f 4d by the next COM
162d0 4d 49 54 20 6f 72 20 52 4f 4c 4c 42 41 43 4b 2e MIT or ROLLBACK.
162e0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
162f0 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 get_autocommit(s
16300 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
16310 20 43 41 50 49 33 52 45 46 3a 20 20 46 69 6e 64 CAPI3REF: Find
16320 20 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61 The Database Ha
16330 6e 64 6c 65 20 41 73 73 6f 63 69 61 74 65 64 20 ndle Associated
16340 57 69 74 68 20 41 20 50 72 65 70 61 72 65 64 20 With A Prepared
16350 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 Statement.**.**
16360 52 65 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 Return the [sqli
16370 74 65 33 2a 5d 20 64 61 74 61 62 61 73 65 20 68 te3*] database h
16380 61 6e 64 6c 65 20 74 6f 20 77 68 69 63 68 20 61 andle to which a
16390 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d .** [sqlite3_stm
163a0 74 20 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 t | prepared sta
163b0 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e tement] belongs.
163c0 0a 2a 2a 20 54 68 69 73 20 69 73 20 74 68 65 20 .** This is the
163d0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 68 61 same database ha
163e0 6e 64 6c 65 20 74 68 61 74 20 77 61 73 0a 2a 2a ndle that was.**
163f0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
16400 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 ent to the [sqli
16410 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
16420 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 ] or its variant
16430 73 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 75 73 s.** that was us
16440 65 64 20 74 6f 20 63 72 65 61 74 65 20 74 68 65 ed to create the
16450 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 statement in th
16460 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a e first place..*
16470 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 /.sqlite3 *sqlit
16480 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c e3_db_handle(sql
16490 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 0a 2f ite3_stmt*);.../
164a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
164b0 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 ommit And Rollba
164c0 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 ck Notification
164d0 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 Callbacks.**.**
164e0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a These routines.*
164f0 2a 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 * register callb
16500 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f ack functions to
16510 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e be invoked when
16520 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 ever a transacti
16530 6f 6e 0a 2a 2a 20 69 73 20 63 6f 6d 6d 69 74 74 on.** is committ
16540 65 64 20 6f 72 20 72 6f 6c 6c 65 64 20 62 61 63 ed or rolled bac
16550 6b 2e 20 20 54 68 65 20 70 41 72 67 20 61 72 67 k. The pArg arg
16560 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 ument is passed
16570 74 68 72 6f 75 67 68 0a 2a 2a 20 74 6f 20 74 68 through.** to th
16580 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66 20 e callback. If
16590 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 the callback on
165a0 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 a commit hook fu
165b0 6e 63 74 69 6f 6e 20 0a 2a 2a 20 72 65 74 75 72 nction .** retur
165c0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 ns non-zero, the
165d0 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 n the commit is
165e0 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 converted into a
165f0 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a rollback..**.**
16600 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 If another func
16610 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 tion was previou
16620 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 sly registered,
16630 69 74 73 20 70 41 72 67 20 76 61 6c 75 65 20 69 its pArg value i
16640 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f s returned..** O
16650 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 therwise NULL is
16660 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
16670 20 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e Registering a N
16680 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 ULL function dis
16690 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61 ables the callba
166a0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 ck..**.** For th
166b0 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 e purposes of th
166c0 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 is API, a transa
166d0 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f ction is said to
166e0 20 68 61 76 65 20 62 65 65 6e 20 0a 2a 2a 20 72 have been .** r
166f0 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e olled back if an
16700 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 explicit "ROLLB
16710 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69 ACK" statement i
16720 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a s executed, or.*
16730 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f * an error or co
16740 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65 73 20 nstraint causes
16750 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c an implicit roll
16760 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 20 54 back to occur. T
16770 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 he .** callback
16780 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 is not invoked i
16790 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 f a transaction
167a0 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 is automatically
167b0 20 72 6f 6c 6c 65 64 0a 2a 2a 20 62 61 63 6b 20 rolled.** back
167c0 62 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61 because the data
167d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
167e0 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a is closed..**.**
167f0 20 54 68 65 73 65 20 61 72 65 20 65 78 70 65 72 These are exper
16800 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 imental interfac
16810 65 73 20 61 6e 64 20 61 72 65 20 73 75 62 6a 65 es and are subje
16820 63 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f ct to change..*/
16830 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 .void *sqlite3_c
16840 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 ommit_hook(sqlit
16850 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 e3*, int(*)(void
16860 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 *), void*);.void
16870 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 *sqlite3_rollba
16880 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a ck_hook(sqlite3*
16890 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a , void(*)(void *
168a0 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a ), void*);../*.*
168b0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 * CAPI3REF: Data
168c0 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 Change Notifica
168d0 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a tion Callbacks.*
168e0 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 20 61 20 *.** Register a
168f0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
16900 6e 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62 n with the datab
16910 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ase connection i
16920 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 dentified by the
16930 20 0a 2a 2a 20 66 69 72 73 74 20 61 72 67 75 6d .** first argum
16940 65 6e 74 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 ent to be invoke
16950 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 d whenever a row
16960 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 is updated, ins
16970 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 erted or deleted
16980 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 ..** Any callbac
16990 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 k set by a previ
169a0 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 ous call to this
169b0 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 74 68 function for th
169c0 65 20 73 61 6d 65 20 0a 2a 2a 20 64 61 74 61 62 e same .** datab
169d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ase connection i
169e0 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a s overridden..**
169f0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 .** The second a
16a00 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 rgument is a poi
16a10 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 nter to the func
16a20 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 tion to invoke w
16a30 68 65 6e 20 61 20 0a 2a 2a 20 72 6f 77 20 69 73 hen a .** row is
16a40 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 updated, insert
16a50 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 20 54 ed or deleted. T
16a60 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
16a70 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 t to the callbac
16a80 6b 20 69 73 0a 2a 2a 20 61 20 63 6f 70 79 20 6f k is.** a copy o
16a90 66 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 f the third argu
16aa0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f ment to sqlite3_
16ab0 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 20 54 update_hook(). T
16ac0 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 he second callba
16ad0 63 6b 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 ck .** argument
16ae0 69 73 20 6f 6e 65 20 6f 66 20 53 51 4c 49 54 45 is one of SQLITE
16af0 5f 49 4e 53 45 52 54 2c 20 53 51 4c 49 54 45 5f _INSERT, SQLITE_
16b00 44 45 4c 45 54 45 20 6f 72 20 53 51 4c 49 54 45 DELETE or SQLITE
16b10 5f 55 50 44 41 54 45 2c 20 64 65 70 65 6e 64 69 _UPDATE, dependi
16b20 6e 67 0a 2a 2a 20 6f 6e 20 74 68 65 20 6f 70 65 ng.** on the ope
16b30 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 ration that caus
16b40 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 ed the callback
16b50 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 20 54 to be invoked. T
16b60 68 65 20 74 68 69 72 64 20 61 6e 64 20 0a 2a 2a he third and .**
16b70 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 fourth argument
16b80 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 s to the callbac
16b90 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 k contain pointe
16ba0 72 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 rs to the databa
16bb0 73 65 20 61 6e 64 20 0a 2a 2a 20 74 61 62 6c 65 se and .** table
16bc0 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 name containing
16bd0 20 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f the affected ro
16be0 77 2e 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c w. The final cal
16bf0 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 lback parameter
16c00 69 73 20 0a 2a 2a 20 74 68 65 20 72 6f 77 69 64 is .** the rowid
16c10 20 6f 66 20 74 68 65 20 72 6f 77 2e 20 49 6e 20 of the row. In
16c20 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75 the case of an u
16c30 70 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 74 pdate, this is t
16c40 68 65 20 72 6f 77 69 64 20 61 66 74 65 72 20 0a he rowid after .
16c50 2a 2a 20 74 68 65 20 75 70 64 61 74 65 20 74 61 ** the update ta
16c60 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a kes place..**.**
16c70 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b The update hook
16c80 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 is not invoked
16c90 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 when internal sy
16ca0 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a stem tables are.
16cb0 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 ** modified (i.e
16cc0 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 . sqlite_master
16cd0 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 and sqlite_seque
16ce0 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 nce)..**.** If a
16cf0 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 nother function
16d00 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 was previously r
16d10 65 67 69 73 74 65 72 65 64 2c 20 69 74 73 20 70 egistered, its p
16d20 41 72 67 20 76 61 6c 75 65 20 69 73 20 72 65 74 Arg value is ret
16d30 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 urned..** Otherw
16d40 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 ise NULL is retu
16d50 72 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 rned..*/.void *s
16d60 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f qlite3_update_ho
16d70 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 ok(. sqlite3*,
16d80 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 . void(*)(void
16d90 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 *,int ,char cons
16da0 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a t *,char const *
16db0 2c 73 71 6c 69 74 65 5f 69 6e 74 36 34 29 2c 0a ,sqlite_int64),.
16dc0 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a void*.);../*.*
16dd0 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 6e 61 * CAPI3REF: Ena
16de0 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 ble Or Disable S
16df0 68 61 72 65 64 20 50 61 67 65 72 20 43 61 63 68 hared Pager Cach
16e00 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 e.**.** This rou
16e10 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 tine enables or
16e20 64 69 73 61 62 6c 65 73 20 74 68 65 20 73 68 61 disables the sha
16e30 72 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 ring of the data
16e40 62 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e base cache.** an
16e50 64 20 73 63 68 65 6d 61 20 64 61 74 61 20 73 74 d schema data st
16e60 72 75 63 74 75 72 65 73 20 62 65 74 77 65 65 6e ructures between
16e70 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 74 6f 20 connections to
16e80 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
16e90 65 2e 0a 2a 2a 20 53 68 61 72 69 6e 67 20 69 73 e..** Sharing is
16ea0 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 enabled if the
16eb0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 argument is true
16ec0 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66 and disabled if
16ed0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a the argument.**
16ee0 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a is false..**.**
16ef0 20 43 61 63 68 65 20 73 68 61 72 69 6e 67 20 69 Cache sharing i
16f00 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 s enabled and di
16f10 73 61 62 6c 65 64 20 6f 6e 20 61 20 74 68 72 65 sabled on a thre
16f20 61 64 2d 62 79 2d 74 68 72 65 61 64 20 62 61 73 ad-by-thread bas
16f30 69 73 2e 0a 2a 2a 20 45 61 63 68 20 63 61 6c 6c is..** Each call
16f40 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 to this routine
16f50 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 enables or disa
16f60 62 6c 65 73 20 63 61 63 68 65 20 73 68 61 72 69 bles cache shari
16f70 6e 67 20 6f 6e 6c 79 20 66 6f 72 0a 2a 2a 20 63 ng only for.** c
16f80 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 72 65 61 74 onnections creat
16f90 65 64 20 69 6e 20 74 68 65 20 73 61 6d 65 20 74 ed in the same t
16fa0 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 74 hread in which t
16fb0 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63 his routine is c
16fc0 61 6c 6c 65 64 2e 0a 2a 2a 20 54 68 65 72 65 20 alled..** There
16fd0 69 73 20 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20 is no mechanism
16fe0 66 6f 72 20 73 68 61 72 69 6e 67 20 63 61 63 68 for sharing cach
16ff0 65 20 62 65 74 77 65 65 6e 20 64 61 74 61 62 61 e between databa
17000 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a se connections.*
17010 2a 20 72 75 6e 6e 69 6e 67 20 69 6e 20 64 69 66 * running in dif
17020 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 2e 0a ferent threads..
17030 2a 2a 0a 2a 2a 20 53 68 61 72 69 6e 67 20 6d 75 **.** Sharing mu
17040 73 74 20 62 65 20 64 69 73 61 62 6c 65 64 20 70 st be disabled p
17050 72 69 6f 72 20 74 6f 20 73 68 75 74 74 69 6e 67 rior to shutting
17060 20 64 6f 77 6e 20 61 20 74 68 72 65 61 64 20 6f down a thread o
17070 72 20 65 6c 73 65 0a 2a 2a 20 74 68 65 20 74 68 r else.** the th
17080 72 65 61 64 20 77 69 6c 6c 20 6c 65 61 6b 20 6d read will leak m
17090 65 6d 6f 72 79 2e 20 20 43 61 6c 6c 20 74 68 69 emory. Call thi
170a0 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 s routine with a
170b0 6e 20 61 72 67 75 6d 65 6e 74 20 6f 66 0a 2a 2a n argument of.**
170c0 20 30 20 74 6f 20 74 75 72 6e 20 6f 66 66 20 73 0 to turn off s
170d0 68 61 72 69 6e 67 2e 20 20 4f 72 20 75 73 65 20 haring. Or use
170e0 74 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 the sqlite3_thre
170f0 61 64 5f 63 6c 65 61 6e 75 70 28 29 20 41 50 49 ad_cleanup() API
17100 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 ..**.** This rou
17110 74 69 6e 65 20 6d 75 73 74 20 6e 6f 74 20 62 65 tine must not be
17120 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 61 6e 79 called when any
17130 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
17140 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 63 74 tions.** are act
17150 69 76 65 20 69 6e 20 74 68 65 20 63 75 72 72 65 ive in the curre
17160 6e 74 20 74 68 72 65 61 64 2e 20 20 45 6e 61 62 nt thread. Enab
17170 6c 69 6e 67 20 6f 72 20 64 69 73 61 62 6c 69 6e ling or disablin
17180 67 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 g shared.** cach
17190 65 20 77 68 69 6c 65 20 74 68 65 72 65 20 61 72 e while there ar
171a0 65 20 61 63 74 69 76 65 20 64 61 74 61 62 61 73 e active databas
171b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 77 69 e connections wi
171c0 6c 6c 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 ll result.** in
171d0 6d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f memory corruptio
171e0 6e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 n..**.** When th
171f0 65 20 73 68 61 72 65 64 20 63 61 63 68 65 20 69 e shared cache i
17200 73 20 65 6e 61 62 6c 65 64 2c 20 74 68 65 0a 2a s enabled, the.*
17210 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 72 6f 75 74 * following rout
17220 69 6e 65 73 20 6d 75 73 74 20 61 6c 77 61 79 73 ines must always
17230 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 be called from
17240 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 3a the same thread:
17250 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 .** [sqlite3_ope
17260 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 n()], [sqlite3_p
17270 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 repare_v2()], [s
17280 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 0a qlite3_step()],.
17290 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ** [sqlite3_rese
172a0 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 t()], [sqlite3_f
172b0 69 6e 61 6c 69 7a 65 28 29 5d 2c 20 61 6e 64 20 inalize()], and
172c0 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 [sqlite3_close()
172d0 5d 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 75 ]..** This is du
172e0 65 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 e to the fact th
172f0 61 74 20 74 68 65 20 73 68 61 72 65 64 20 63 61 at the shared ca
17300 63 68 65 20 6d 61 6b 65 73 20 75 73 65 20 6f 66 che makes use of
17310 0a 2a 2a 20 74 68 72 65 61 64 2d 73 70 65 63 69 .** thread-speci
17320 66 69 63 20 73 74 6f 72 61 67 65 20 73 6f 20 74 fic storage so t
17330 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 61 hat it will be a
17340 76 61 69 6c 61 62 6c 65 20 66 6f 72 20 73 68 61 vailable for sha
17350 72 69 6e 67 0a 2a 2a 20 77 69 74 68 20 6f 74 68 ring.** with oth
17360 65 72 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a er connections..
17370 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 **.** Virtual ta
17380 62 6c 65 73 20 63 61 6e 6e 6f 74 20 62 65 20 75 bles cannot be u
17390 73 65 64 20 77 69 74 68 20 61 20 73 68 61 72 65 sed with a share
173a0 64 20 63 61 63 68 65 2e 20 20 57 68 65 6e 20 73 d cache. When s
173b0 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 hared.** cache i
173c0 73 20 65 6e 61 62 6c 65 64 2c 20 74 68 65 20 73 s enabled, the s
173d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f qlite3_create_mo
173e0 64 75 6c 65 28 29 20 41 50 49 20 75 73 65 64 20 dule() API used
173f0 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 76 to register.** v
17400 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 77 69 irtual tables wi
17410 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e ll always return
17420 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a an error..**.**
17430 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 This routine re
17440 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b turns [SQLITE_OK
17450 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68 ] if shared cach
17460 65 20 77 61 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 e was.** enabled
17470 20 6f 72 20 64 69 73 61 62 6c 65 64 20 73 75 63 or disabled suc
17480 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b cessfully. An [
17490 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 65 SQLITE_ERROR | e
174a0 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 69 73 rror code].** is
174b0 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 returned otherw
174c0 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65 ise..**.** Share
174d0 64 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62 d cache is disab
174e0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 led by default f
174f0 6f 72 20 62 61 63 6b 77 61 72 64 20 63 6f 6d 70 or backward comp
17500 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e atibility..*/.in
17510 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 t sqlite3_enable
17520 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 69 6e _shared_cache(in
17530 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
17540 52 45 46 3a 20 20 41 74 74 65 6d 70 74 20 54 6f REF: Attempt To
17550 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72 Free Heap Memor
17560 79 0a 2a 2a 0a 2a 2a 20 41 74 74 65 6d 70 74 20 y.**.** Attempt
17570 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73 20 to free N bytes
17580 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 of heap memory b
17590 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e y deallocating n
175a0 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 0a 2a 2a 20 on-essential.**
175b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
175c0 6e 73 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 ns held by the d
175d0 61 74 61 62 61 73 65 20 6c 69 62 72 61 72 79 20 atabase library
175e0 28 65 78 61 6d 70 6c 65 3a 20 6d 65 6d 6f 72 79 (example: memory
175f0 20 0a 2a 2a 20 75 73 65 64 20 74 6f 20 63 61 63 .** used to cac
17600 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 he database page
17610 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 s to improve per
17620 66 6f 72 6d 61 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a formance)..**.**
17630 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 This function i
17640 73 20 6e 6f 74 20 61 20 70 61 72 74 20 6f 66 20 s not a part of
17650 73 74 61 6e 64 61 72 64 20 62 75 69 6c 64 73 2e standard builds.
17660 20 20 49 74 20 69 73 20 6f 6e 6c 79 20 63 72 65 It is only cre
17670 61 74 65 64 0a 2a 2a 20 69 66 20 53 51 4c 69 74 ated.** if SQLit
17680 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
17690 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 45 4e th the SQLITE_EN
176a0 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 ABLE_MEMORY_MANA
176b0 47 45 4d 45 4e 54 20 6d 61 63 72 6f 2e 0a 2a 2f GEMENT macro..*/
176c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c .int sqlite3_rel
176d0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 ease_memory(int)
176e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
176f0 46 3a 20 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d F: Impose A Lim
17700 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 0a it On Heap Size.
17710 2a 2a 0a 2a 2a 20 50 6c 61 63 65 20 61 20 22 73 **.** Place a "s
17720 6f 66 74 22 20 6c 69 6d 69 74 20 6f 6e 20 74 68 oft" limit on th
17730 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 e amount of heap
17740 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 memory that may
17750 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 be allocated by
17760 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 74 68 69 .** SQLite withi
17770 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 n the current th
17780 72 65 61 64 2e 20 49 66 20 61 6e 20 69 6e 74 65 read. If an inte
17790 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 rnal allocation
177a0 69 73 20 72 65 71 75 65 73 74 65 64 20 0a 2a 2a is requested .**
177b0 20 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65 that would exce
177c0 65 64 20 74 68 65 20 73 70 65 63 69 66 69 65 64 ed the specified
177d0 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74 65 33 limit, [sqlite3
177e0 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 _release_memory(
177f0 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a )] is invoked.**
17800 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d one or more tim
17810 65 73 20 74 6f 20 66 72 65 65 20 75 70 20 73 6f es to free up so
17820 6d 65 20 73 70 61 63 65 20 62 65 66 6f 72 65 20 me space before
17830 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 the allocation i
17840 73 20 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 s made..**.** Th
17850 65 20 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 e limit is calle
17860 64 20 22 73 6f 66 74 22 2c 20 62 65 63 61 75 73 d "soft", becaus
17870 65 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 72 65 e if [sqlite3_re
17880 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 lease_memory()]
17890 63 61 6e 6e 6f 74 20 66 72 65 65 0a 2a 2a 20 73 cannot free.** s
178a0 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 ufficient memory
178b0 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 65 20 to prevent the
178c0 6c 69 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 limit from being
178d0 20 65 78 63 65 65 64 65 64 2c 20 74 68 65 20 6d exceeded, the m
178e0 65 6d 6f 72 79 20 69 73 0a 2a 2a 20 61 6c 6c 6f emory is.** allo
178f0 63 61 74 65 64 20 61 6e 79 77 61 79 20 61 6e 64 cated anyway and
17900 20 74 68 65 20 63 75 72 72 65 6e 74 20 6f 70 65 the current ope
17910 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e ration proceeds.
17920 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 .**.** Prior to
17930 73 68 75 74 74 69 6e 67 20 64 6f 77 6e 20 61 20 shutting down a
17940 74 68 72 65 61 64 20 73 71 6c 69 74 65 33 5f 73 thread sqlite3_s
17950 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 oft_heap_limit()
17960 20 6d 75 73 74 20 62 65 20 73 65 74 20 74 6f 20 must be set to
17970 0a 2a 2a 20 7a 65 72 6f 20 28 74 68 65 20 64 65 .** zero (the de
17980 66 61 75 6c 74 29 20 6f 72 20 65 6c 73 65 20 74 fault) or else t
17990 68 65 20 74 68 72 65 61 64 20 77 69 6c 6c 20 6c he thread will l
179a0 65 61 6b 20 6d 65 6d 6f 72 79 2e 20 41 6c 74 65 eak memory. Alte
179b0 72 6e 61 74 69 76 65 6c 79 2c 20 75 73 65 0a 2a rnatively, use.*
179c0 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 * the [sqlite3_t
179d0 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 29 5d hread_cleanup()]
179e0 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e 65 API..**.** A ne
179f0 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f 20 76 gative or zero v
17a00 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65 61 6e 73 alue for N means
17a10 20 74 68 61 74 20 74 68 65 72 65 20 69 73 20 6e that there is n
17a20 6f 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 o soft heap limi
17a30 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 t and.** [sqlite
17a40 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 3_release_memory
17a50 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 ()] will only be
17a60 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d called when mem
17a70 6f 72 79 20 69 73 20 65 78 68 61 75 73 65 64 2e ory is exhaused.
17a80 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 .** The default
17a90 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 73 6f value for the so
17aa0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 ft heap limit is
17ab0 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c zero..**.** SQL
17ac0 69 74 65 20 6d 61 6b 65 73 20 61 20 62 65 73 74 ite makes a best
17ad0 20 65 66 66 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 effort to honor
17ae0 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c the soft heap l
17af0 69 6d 69 74 2e 20 20 42 75 74 20 69 66 20 69 74 imit. But if it
17b00 0a 2a 2a 20 69 73 20 75 6e 61 62 6c 65 20 74 6f .** is unable to
17b10 20 72 65 64 75 63 65 20 6d 65 6d 6f 72 79 20 75 reduce memory u
17b20 73 61 67 65 20 62 65 6c 6f 77 20 74 68 65 20 73 sage below the s
17b30 6f 66 74 20 6c 69 6d 69 74 2c 20 65 78 65 63 75 oft limit, execu
17b40 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e tion will.** con
17b50 74 69 6e 75 65 20 77 69 74 68 6f 75 74 20 65 72 tinue without er
17b60 72 6f 72 20 6f 72 20 6e 6f 74 69 66 69 63 61 74 ror or notificat
17b70 69 6f 6e 2e 20 20 54 68 69 73 20 69 73 20 77 68 ion. This is wh
17b80 79 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 0a y the limit is .
17b90 2a 2a 20 63 61 6c 6c 65 64 20 61 20 22 73 6f 66 ** called a "sof
17ba0 74 22 20 6c 69 6d 69 74 2e 20 20 49 74 20 69 73 t" limit. It is
17bb0 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a advisory only..
17bc0 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 **.** This funct
17bd0 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 ion is only avai
17be0 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 lable if the lib
17bf0 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 rary was compile
17c00 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 d with the .** S
17c10 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d QLITE_ENABLE_MEM
17c20 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 20 6f ORY_MANAGEMENT o
17c30 70 74 69 6f 6e 20 73 65 74 2e 0a 2a 2a 20 6d 65 ption set..** me
17c40 6d 6f 72 79 2d 6d 61 6e 61 67 65 6d 65 6e 74 20 mory-management
17c50 68 61 73 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 has been enabled
17c60 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 ..*/.void sqlite
17c70 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 3_soft_heap_limi
17c80 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 t(int);../*.** C
17c90 41 50 49 33 52 45 46 3a 20 20 43 6c 65 61 6e 20 API3REF: Clean
17ca0 55 70 20 54 68 72 65 61 64 20 4c 6f 63 61 6c 20 Up Thread Local
17cb0 53 74 6f 72 61 67 65 0a 2a 2a 0a 2a 2a 20 54 68 Storage.**.** Th
17cc0 69 73 20 72 6f 75 74 69 6e 65 20 6d 61 6b 65 73 is routine makes
17cd0 20 73 75 72 65 20 74 68 61 74 20 61 6c 6c 20 74 sure that all t
17ce0 68 72 65 61 64 2d 6c 6f 63 61 6c 20 73 74 6f 72 hread-local stor
17cf0 61 67 65 20 68 61 73 20 62 65 65 6e 0a 2a 2a 20 age has been.**
17d00 64 65 61 6c 6c 6f 63 61 74 65 64 20 66 6f 72 20 deallocated for
17d10 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 the current thre
17d20 61 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 ad..**.** This r
17d30 6f 75 74 69 6e 65 20 69 73 20 6e 6f 74 20 74 65 outine is not te
17d40 63 68 6e 69 63 61 6c 6c 79 20 6e 65 63 65 73 73 chnically necess
17d50 61 72 79 2e 20 20 41 6c 6c 20 74 68 72 65 61 64 ary. All thread
17d60 2d 6c 6f 63 61 6c 20 73 74 6f 72 61 67 65 0a 2a -local storage.*
17d70 2a 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 * will be automa
17d80 74 69 63 61 6c 6c 79 20 64 65 61 6c 6c 6f 63 61 tically dealloca
17d90 74 65 64 20 6f 6e 63 65 20 6d 65 6d 6f 72 79 2d ted once memory-
17da0 6d 61 6e 61 67 65 6d 65 6e 74 20 61 6e 64 0a 2a management and.*
17db0 2a 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 61 * shared-cache a
17dc0 72 65 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 re disabled and
17dd0 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 the soft heap li
17de0 6d 69 74 20 68 61 73 20 62 65 65 6e 20 73 65 74 mit has been set
17df0 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2e 20 20 54 68 .** to zero. Th
17e00 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 70 72 is routine is pr
17e10 6f 76 69 64 65 64 20 61 73 20 61 20 63 6f 6e 76 ovided as a conv
17e20 65 6e 69 65 6e 63 65 20 66 6f 72 20 75 73 65 72 enience for user
17e30 73 20 77 68 6f 0a 2a 2a 20 77 61 6e 74 20 74 6f s who.** want to
17e40 20 6d 61 6b 65 20 61 62 73 6f 6c 75 74 65 6c 79 make absolutely
17e50 20 73 75 72 65 20 74 68 65 79 20 68 61 76 65 20 sure they have
17e60 6e 6f 74 20 66 6f 72 67 6f 74 74 65 6e 20 73 6f not forgotten so
17e70 6d 65 74 68 69 6e 67 0a 2a 2a 20 70 72 69 6f 72 mething.** prior
17e80 20 74 6f 20 6b 69 6c 6c 69 6e 67 20 6f 66 66 20 to killing off
17e90 61 20 74 68 72 65 61 64 2e 0a 2a 2f 0a 76 6f 69 a thread..*/.voi
17ea0 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 d sqlite3_thread
17eb0 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a _cleanup(void);.
17ec0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
17ed0 20 20 45 78 74 72 61 63 74 20 4d 65 74 61 64 61 Extract Metada
17ee0 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d ta About A Colum
17ef0 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a 2a 0a n Of A Table.**.
17f00 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 0a ** This routine.
17f10 2a 2a 20 72 65 74 75 72 6e 73 20 6d 65 74 61 2d ** returns meta-
17f20 64 61 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 data about a spe
17f30 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 cific column of
17f40 61 20 73 70 65 63 69 66 69 63 20 64 61 74 61 62 a specific datab
17f50 61 73 65 0a 2a 2a 20 74 61 62 6c 65 20 61 63 63 ase.** table acc
17f60 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 essible using th
17f70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e e connection han
17f80 64 6c 65 20 70 61 73 73 65 64 20 61 73 20 74 68 dle passed as th
17f90 65 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e e first function
17fa0 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 0a 2a .** argument..*
17fb0 2a 0a 2a 2a 20 54 68 65 20 63 6f 6c 75 6d 6e 20 *.** The column
17fc0 69 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 is identified by
17fd0 20 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 the second, thi
17fe0 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 rd and fourth pa
17ff0 72 61 6d 65 74 65 72 73 20 74 6f 20 0a 2a 2a 20 rameters to .**
18000 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54 this function. T
18010 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
18020 74 65 72 20 69 73 20 65 69 74 68 65 72 20 74 68 ter is either th
18030 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 e name of the da
18040 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 tabase.** (i.e.
18050 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 20 6f "main", "temp" o
18060 72 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 r an attached da
18070 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 tabase) containi
18080 6e 67 20 74 68 65 20 73 70 65 63 69 66 69 65 64 ng the specified
18090 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c .** table or NUL
180a0 4c 2e 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c L. If it is NULL
180b0 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 , then all attac
180c0 68 65 64 20 64 61 74 61 62 61 73 65 73 20 61 72 hed databases ar
180d0 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f e searched.** fo
180e0 72 20 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e r the table usin
180f0 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 g the same algor
18100 69 74 68 6d 20 61 73 20 74 68 65 20 64 61 74 61 ithm as the data
18110 62 61 73 65 20 65 6e 67 69 6e 65 20 75 73 65 73 base engine uses
18120 20 74 6f 20 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 to .** resolve
18130 75 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c unqualified tabl
18140 65 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a e references..**
18150 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e .** The third an
18160 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 d fourth paramet
18170 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 ers to this func
18180 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62 tion are the tab
18190 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 0a 2a le and column .*
181a0 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 * name of the de
181b0 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 sired column, re
181c0 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 spectively. Neit
181d0 68 65 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 her of these par
181e0 61 6d 65 74 65 72 73 20 0a 2a 2a 20 6d 61 79 20 ameters .** may
181f0 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d be NULL..**.** M
18200 65 74 61 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 eta information
18210 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 77 is returned by w
18220 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 riting to the me
18230 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 mory locations p
18240 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 assed as.** the
18250 35 74 68 20 61 6e 64 20 73 75 62 73 65 71 75 65 5th and subseque
18260 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f nt parameters to
18270 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 this function.
18280 41 6e 79 20 6f 66 20 74 68 65 73 65 20 0a 2a 2a Any of these .**
18290 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 arguments may b
182a0 65 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 e NULL, in which
182b0 20 63 61 73 65 20 74 68 65 20 63 6f 72 72 65 73 case the corres
182c0 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 ponding element
182d0 6f 66 20 6d 65 74 61 20 0a 2a 2a 20 69 6e 66 6f of meta .** info
182e0 72 6d 61 74 69 6f 6e 20 69 73 20 6f 6d 6d 69 74 rmation is ommit
182f0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e ted..**.** <pre>
18300 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 20 20 20 .** Parameter
18310 20 20 4f 75 74 70 75 74 20 54 79 70 65 20 20 20 Output Type
18320 20 20 20 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a Description.*
18330 2a 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d * --------------
18340 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
18350 2d 2d 2d 2d 2d 0a 2a 2a 0a 2a 2a 20 20 20 35 74 -----.**.** 5t
18360 68 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74 20 h const
18370 63 68 61 72 2a 20 20 20 20 20 20 44 61 74 61 20 char* Data
18380 74 79 70 65 0a 2a 2a 20 20 20 36 74 68 20 20 20 type.** 6th
18390 20 20 20 20 20 20 63 6f 6e 73 74 20 63 68 61 72 const char
183a0 2a 20 20 20 20 20 20 4e 61 6d 65 20 6f 66 20 74 * Name of t
183b0 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 he default colla
183c0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 0a 2a tion sequence .*
183d0 2a 20 20 20 37 74 68 20 20 20 20 20 20 20 20 20 * 7th
183e0 69 6e 74 20 20 20 20 20 20 20 20 20 20 20 20 20 int
183f0 20 54 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c True if the col
18400 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 umn has a NOT NU
18410 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a LL constraint.**
18420 20 20 20 38 74 68 20 20 20 20 20 20 20 20 20 69 8th i
18430 6e 74 20 20 20 20 20 20 20 20 20 20 20 20 20 20 nt
18440 54 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75 True if the colu
18450 6d 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 mn is part of th
18460 65 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a e PRIMARY KEY.**
18470 20 20 20 39 74 68 20 20 20 20 20 20 20 20 20 69 9th i
18480 6e 74 20 20 20 20 20 20 20 20 20 20 20 20 20 20 nt
18490 54 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75 True if the colu
184a0 6d 6e 20 69 73 20 41 55 54 4f 49 4e 43 52 45 4d mn is AUTOINCREM
184b0 45 4e 54 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a ENT.** </pre>.**
184c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 .**.** The memor
184d0 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 y pointed to by
184e0 74 68 65 20 63 68 61 72 61 63 74 65 72 20 70 6f the character po
184f0 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 inters returned
18500 66 6f 72 20 74 68 65 20 0a 2a 2a 20 64 65 63 6c for the .** decl
18510 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 aration type and
18520 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 collation seque
18530 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c nce is valid onl
18540 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 y until the next
18550 20 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79 .** call to any
18560 20 73 71 6c 69 74 65 20 41 50 49 20 66 75 6e 63 sqlite API func
18570 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 tion..**.** If t
18580 68 65 20 73 70 65 63 69 66 69 65 64 20 74 61 62 he specified tab
18590 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79 20 61 le is actually a
185a0 20 76 69 65 77 2c 20 74 68 65 6e 20 61 6e 20 65 view, then an e
185b0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 rror is returned
185c0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 ..**.** If the s
185d0 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 pecified column
185e0 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 is "rowid", "oid
185f0 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 " or "_rowid_" a
18600 6e 64 20 61 6e 20 0a 2a 2a 20 49 4e 54 45 47 45 nd an .** INTEGE
18610 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20 63 6f R PRIMARY KEY co
18620 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 65 78 lumn has been ex
18630 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 plicitly declare
18640 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 d, then the outp
18650 75 74 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ut .** parameter
18660 73 20 61 72 65 20 73 65 74 20 66 6f 72 20 74 68 s are set for th
18670 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 e explicitly dec
18680 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 49 66 lared column. If
18690 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 there is no.**
186a0 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 explicitly decla
186b0 72 65 64 20 49 50 4b 20 63 6f 6c 75 6d 6e 2c 20 red IPK column,
186c0 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 20 then the output
186d0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 parameters are s
186e0 65 74 20 61 73 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 et as .** follow
186f0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a s:.**.** <pre>.*
18700 2a 20 20 20 20 20 64 61 74 61 20 74 79 70 65 3a * data type:
18710 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 "INTEGER".**
18720 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 collation sequ
18730 65 6e 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a ence: "BINARY".*
18740 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 * not null:
18750 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79 0.** primary
18760 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 key: 1.** a
18770 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 uto increment: 0
18780 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a .** </pre>.**.**
18790 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d This function m
187a0 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d ay load one or m
187b0 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f 6d ore schemas from
187c0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e database files.
187d0 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 If an.** error
187e0 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 occurs during th
187f0 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 is process, or i
18800 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 f the requested
18810 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a table or column.
18820 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 ** cannot be fou
18830 6e 64 2c 20 61 6e 20 53 51 4c 49 54 45 20 65 72 nd, an SQLITE er
18840 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 ror code is retu
18850 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 72 72 6f rned and an erro
18860 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 6c 65 66 r message.** lef
18870 74 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 t in the databas
18880 65 20 68 61 6e 64 6c 65 20 28 74 6f 20 62 65 20 e handle (to be
18890 72 65 74 72 69 65 76 65 64 20 75 73 69 6e 67 20 retrieved using
188a0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 sqlite3_errmsg()
188b0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 )..**.** This AP
188c0 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 I is only availa
188d0 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 ble if the libra
188e0 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 ry was compiled
188f0 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 with the.** SQLI
18900 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e TE_ENABLE_COLUMN
18910 5f 4d 45 54 41 44 41 54 41 20 70 72 65 70 72 6f _METADATA prepro
18920 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 cessor symbol de
18930 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 fined..*/.int sq
18940 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 lite3_table_colu
18950 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73 mn_metadata(. s
18960 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
18970 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f /* Co
18980 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 nnection handle
18990 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
189a0 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 *zDbName,
189b0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6e 61 6d /* Database nam
189c0 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 e or NULL */. c
189d0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c onst char *zTabl
189e0 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 eName, /* Ta
189f0 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f ble name */. co
18a00 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d nst char *zColum
18a10 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c nName, /* Col
18a20 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 umn name */. ch
18a30 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 ar const **pzDat
18a40 61 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 aType, /* OUT
18a50 50 55 54 3a 20 44 65 63 6c 61 72 65 64 20 64 61 PUT: Declared da
18a60 74 61 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 ta type */. cha
18a70 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c r const **pzColl
18a80 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 Seq, /* OUTP
18a90 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 UT: Collation se
18aa0 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 quence name */.
18ab0 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 int *pNotNull,
18ac0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
18ad0 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 OUTPUT: True if
18ae0 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 NOT NULL constra
18af0 69 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 int exists */.
18b00 69 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 int *pPrimaryKey
18b10 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f , /* O
18b20 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 UTPUT: True if c
18b30 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b olumn part of PK
18b40 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f */. int *pAuto
18b50 69 6e 63 20 20 20 20 20 20 20 20 20 20 20 20 20 inc
18b60 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 /* OUTPUT: Tru
18b70 65 20 69 66 20 63 6f 6c 75 6d 73 20 69 73 20 61 e if colums is a
18b80 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f uto-increment */
18b90 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
18ba0 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 REF: Load An Ext
18bb0 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 41 74 74 ension.**.** Att
18bc0 65 6d 70 74 20 74 6f 20 6c 6f 61 64 20 61 6e 20 empt to load an
18bd0 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e SQLite extension
18be0 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e library contain
18bf0 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65 0a 2a ed in the file.*
18c00 2a 20 7a 46 69 6c 65 2e 20 20 54 68 65 20 65 6e * zFile. The en
18c10 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 72 try point is zPr
18c20 6f 63 2e 20 20 7a 50 72 6f 63 20 6d 61 79 20 62 oc. zProc may b
18c30 65 20 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 e 0 in which cas
18c40 65 20 74 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 e the.** name of
18c50 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 the entry point
18c60 20 64 65 66 61 75 6c 74 73 20 74 6f 20 22 73 71 defaults to "sq
18c70 6c 69 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f lite3_extension_
18c80 69 6e 69 74 22 2e 0a 2a 2a 0a 2a 2a 20 52 65 74 init"..**.** Ret
18c90 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 urn [SQLITE_OK]
18ca0 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b on success and [
18cb0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 SQLITE_ERROR] if
18cc0 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 something goes
18cd0 77 72 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 wrong..**.** If
18ce0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 an error occurs
18cf0 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20 and pzErrMsg is
18d00 6e 6f 74 20 30 2c 20 74 68 65 6e 20 66 69 6c 6c not 0, then fill
18d10 20 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20 *pzErrMsg with
18d20 0a 2a 2a 20 65 72 72 6f 72 20 6d 65 73 73 61 67 .** error messag
18d30 65 20 74 65 78 74 2e 20 20 54 68 65 20 63 61 6c e text. The cal
18d40 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68 ling function sh
18d50 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d ould free this m
18d60 65 6d 6f 72 79 0a 2a 2a 20 62 79 20 63 61 6c 6c emory.** by call
18d70 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 ing [sqlite3_fre
18d80 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 45 78 74 65 e()]..**.** Exte
18d90 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 nsion loading mu
18da0 73 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73 st be enabled us
18db0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 ing [sqlite3_ena
18dc0 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 ble_load_extensi
18dd0 6f 6e 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 on()].** prior t
18de0 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 o calling this A
18df0 50 49 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 77 PI or an error w
18e00 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e ill be returned.
18e10 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
18e20 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a load_extension(.
18e30 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
18e40 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 /* Load
18e50 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e the extension in
18e60 74 6f 20 74 68 69 73 20 64 61 74 61 62 61 73 65 to this database
18e70 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 connection */.
18e80 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 const char *zFi
18e90 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f le, /* Name o
18ea0 66 20 74 68 65 20 73 68 61 72 65 64 20 6c 69 62 f the shared lib
18eb0 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 rary containing
18ec0 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 extension */. c
18ed0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 onst char *zProc
18ee0 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f , /* Entry po
18ef0 69 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66 72 int. Derived fr
18f00 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f om zFile if 0 */
18f10 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d . char **pzErrM
18f20 73 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20 sg /* Put
18f30 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65 error message he
18f40 72 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 re if not 0 */.)
18f50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
18f60 46 3a 20 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 F: Enable Or Di
18f70 73 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 sable Extension
18f80 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 53 6f Loading.**.** So
18f90 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 as not to open
18fa0 73 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69 security holes i
18fb0 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74 n older applicat
18fc0 69 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a ions that are.**
18fd0 20 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64 unprepared to d
18fe0 65 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69 eal with extensi
18ff0 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 on loading, and
19000 61 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 as a means of di
19010 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e sabling.** exten
19020 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 sion loading whi
19030 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73 le evaluating us
19040 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 er-entered SQL,
19050 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a the following.**
19060 20 41 50 49 20 69 73 20 70 72 6f 76 69 64 65 64 API is provided
19070 20 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71 to turn the [sq
19080 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e lite3_load_exten
19090 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 sion()] mechanis
190a0 6d 20 6f 6e 20 61 6e 64 0a 2a 2a 20 6f 66 66 2e m on and.** off.
190b0 20 20 49 74 20 69 73 20 6f 66 66 20 62 79 20 64 It is off by d
190c0 65 66 61 75 6c 74 2e 20 20 53 65 65 20 74 69 63 efault. See tic
190d0 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 0a 2a 2a ket #1863..**.**
190e0 20 43 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 Call this routi
190f0 6e 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 ne with onoff==1
19100 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69 to turn extensi
19110 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 0a 2a 2a on loading on.**
19120 20 61 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 and call it wit
19130 68 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 h onoff==0 to tu
19140 72 6e 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61 rn it back off a
19150 67 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c gain..*/.int sql
19160 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 ite3_enable_load
19170 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 _extension(sqlit
19180 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 e3 *db, int onof
19190 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 f);../*.** CAPI3
191a0 52 45 46 3a 20 4d 61 6b 65 20 41 72 72 61 6e 67 REF: Make Arrang
191b0 65 6d 65 6e 74 73 20 54 6f 20 41 75 74 6f 6d 61 ements To Automa
191c0 74 69 63 61 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 tically Load An
191d0 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 Extension.**.**
191e0 52 65 67 69 73 74 65 72 20 61 6e 20 65 78 74 65 Register an exte
191f0 6e 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e nsion entry poin
19200 74 20 74 68 61 74 20 69 73 20 61 75 74 6f 6d 61 t that is automa
19210 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 0a tically invoked.
19220 2a 2a 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65 ** whenever a ne
19230 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 w database conne
19240 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 20 ction is opened
19250 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 using.** [sqlite
19260 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 3_open()] or [sq
19270 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e lite3_open16()].
19280 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 .**.** This API
19290 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65 64 20 61 can be invoked a
192a0 74 20 70 72 6f 67 72 61 6d 20 73 74 61 72 74 75 t program startu
192b0 70 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 72 65 p in order to re
192c0 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 gister.** one or
192d0 20 6d 6f 72 65 20 73 74 61 74 69 63 61 6c 6c 79 more statically
192e0 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e 73 69 6f linked extensio
192f0 6e 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 ns that will be
19300 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20 available.** to
19310 61 6c 6c 20 6e 65 77 20 64 61 74 61 62 61 73 65 all new database
19320 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a connections..**
19330 0a 2a 2a 20 44 75 70 6c 69 63 61 74 65 20 65 78 .** Duplicate ex
19340 74 65 6e 73 69 6f 6e 73 20 61 72 65 20 64 65 74 tensions are det
19350 65 63 74 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67 ected so calling
19360 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 this routine mu
19370 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 ltiple.** times
19380 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 65 78 with the same ex
19390 74 65 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c tension is harml
193a0 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ess..**.** This
193b0 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61 routine stores a
193c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
193d0 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 extension in an
193e0 61 72 72 61 79 0a 2a 2a 20 74 68 61 74 20 69 73 array.** that is
193f0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 6d obtained from m
19400 61 6c 6c 6f 63 28 29 2e 20 20 49 66 20 79 6f 75 alloc(). If you
19410 20 72 75 6e 20 61 20 6d 65 6d 6f 72 79 20 6c 65 run a memory le
19420 61 6b 0a 2a 2a 20 63 68 65 63 6b 65 72 20 6f 6e ak.** checker on
19430 20 79 6f 75 72 20 70 72 6f 67 72 61 6d 20 61 6e your program an
19440 64 20 69 74 20 72 65 70 6f 72 74 73 20 61 20 6c d it reports a l
19450 65 61 6b 20 62 65 63 61 75 73 65 20 6f 66 20 74 eak because of t
19460 68 69 73 0a 2a 2a 20 61 72 72 61 79 2c 20 74 68 his.** array, th
19470 65 6e 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 en invoke [sqlit
19480 65 33 5f 61 75 74 6f 6d 61 74 69 63 5f 65 78 74 e3_automatic_ext
19490 65 6e 73 69 6f 6e 5f 72 65 73 65 74 28 29 5d 20 ension_reset()]
194a0 70 72 69 6f 72 0a 2a 2a 20 74 6f 20 73 68 75 74 prior.** to shut
194b0 64 6f 77 6e 20 74 6f 20 66 72 65 65 20 74 68 65 down to free the
194c0 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 memory..**.** A
194d0 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 utomatic extensi
194e0 6f 6e 73 20 61 70 70 6c 79 20 61 63 72 6f 73 73 ons apply across
194f0 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a all threads..**
19500 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 .** This interfa
19510 63 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 ce is experiment
19520 61 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 al and is subjec
19530 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a t to change or.*
19540 2a 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 * removal in fut
19550 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 ure releases of
19560 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 SQLite..*/.int s
19570 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 qlite3_auto_exte
19580 6e 73 69 6f 6e 28 76 6f 69 64 20 2a 78 45 6e 74 nsion(void *xEnt
19590 72 79 50 6f 69 6e 74 29 3b 0a 0a 0a 2f 2a 0a 2a ryPoint);.../*.*
195a0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 * CAPI3REF: Rese
195b0 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78 74 65 t Automatic Exte
195c0 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a nsion Loading.**
195d0 0a 2a 2a 20 44 69 73 61 62 6c 65 20 61 6c 6c 20 .** Disable all
195e0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 previously regis
195f0 74 65 72 65 64 20 61 75 74 6f 6d 61 74 69 63 20 tered automatic
19600 65 78 74 65 6e 73 69 6f 6e 73 2e 20 20 54 68 69 extensions. Thi
19610 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 s.** routine und
19620 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f oes the effect o
19630 66 20 61 6c 6c 20 70 72 69 6f 72 20 5b 73 71 6c f all prior [sql
19640 69 74 65 33 5f 61 75 74 6f 6d 61 74 69 63 5f 65 ite3_automatic_e
19650 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 63 xtension()].** c
19660 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 alls..**.** This
19670 20 63 61 6c 6c 20 64 69 73 61 62 6c 65 64 20 61 call disabled a
19680 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 utomatic extensi
19690 6f 6e 73 20 69 6e 20 61 6c 6c 20 74 68 72 65 61 ons in all threa
196a0 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 ds..**.** This i
196b0 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65 nterface is expe
196c0 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 rimental and is
196d0 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 subject to chang
196e0 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 e or.** removal
196f0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
19700 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f es of SQLite..*/
19710 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
19720 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 set_auto_extensi
19730 6f 6e 28 76 6f 69 64 29 3b 0a 0a 0a 2f 2a 0a 2a on(void);.../*.*
19740 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 ***** EXPERIMENT
19750 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 AL - subject to
19760 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e change without n
19770 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a otice **********
19780 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 ****.**.** The i
19790 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 nterface to the
197a0 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 virtual-table me
197b0 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65 chanism is curre
197c0 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a ntly considered.
197d0 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d ** to be experim
197e0 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 ental. The inte
197f0 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e rface might chan
19800 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 ge in incompatib
19810 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 le ways..** If t
19820 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d his is a problem
19830 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 for you, do not
19840 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 use the interfa
19850 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e ce at this time.
19860 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 .**.** When the
19870 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 virtual-table me
19880 63 68 61 6e 69 73 6d 20 73 74 61 62 6c 69 7a 65 chanism stablize
19890 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 s, we will decla
198a0 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 re the.** interf
198b0 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f ace fixed, suppo
198c0 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 rt it indefinite
198d0 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 ly, and remove t
198e0 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a his comment..*/.
198f0 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 ./*.** Structure
19900 73 20 75 73 65 64 20 62 79 20 74 68 65 20 76 69 s used by the vi
19910 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 rtual table inte
19920 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 rface.*/.typedef
19930 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
19940 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61 vtab sqlite3_vta
19950 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 b;.typedef struc
19960 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f t sqlite3_index_
19970 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 info sqlite3_ind
19980 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 ex_info;.typedef
19990 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
199a0 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 vtab_cursor sqli
199b0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b te3_vtab_cursor;
199c0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
199d0 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 sqlite3_module s
199e0 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a qlite3_module;..
199f0 2f 2a 0a 2a 2a 20 41 20 6d 6f 64 75 6c 65 20 69 /*.** A module i
19a00 73 20 61 20 63 6c 61 73 73 20 6f 66 20 76 69 72 s a class of vir
19a10 74 75 61 6c 20 74 61 62 6c 65 73 2e 20 20 45 61 tual tables. Ea
19a20 63 68 20 6d 6f 64 75 6c 65 20 69 73 20 64 65 66 ch module is def
19a30 69 6e 65 64 0a 2a 2a 20 62 79 20 61 6e 20 69 6e ined.** by an in
19a40 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 66 6f stance of the fo
19a50 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 llowing structur
19a60 65 2e 20 20 54 68 69 73 20 73 74 72 75 63 74 75 e. This structu
19a70 72 65 20 63 6f 6e 73 69 73 74 73 0a 2a 2a 20 6d re consists.** m
19a80 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 ostly of methods
19a90 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e for the module.
19aa0 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 .*/.struct sqlit
19ab0 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e e3_module {. in
19ac0 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e t iVersion;. in
19ad0 74 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c t (*xCreate)(sql
19ae0 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 ite3*, void *pAu
19af0 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 x,.
19b00 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 int argc, cons
19b10 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 t char *const*ar
19b20 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 gv,.
19b30 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 sqlite3_vtab
19b40 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a **ppVTab, char**
19b50 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e );. int (*xConn
19b60 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 ect)(sqlite3*, v
19b70 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 oid *pAux,.
19b80 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 int ar
19b90 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a gc, const char *
19ba0 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 const*argv,.
19bb0 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 sqlit
19bc0 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 e3_vtab **ppVTab
19bd0 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 , char**);. int
19be0 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 (*xBestIndex)(s
19bf0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 qlite3_vtab *pVT
19c00 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 ab, sqlite3_inde
19c10 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 x_info*);. int
19c20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 (*xDisconnect)(s
19c30 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 qlite3_vtab *pVT
19c40 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 ab);. int (*xDe
19c50 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 stroy)(sqlite3_v
19c60 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 tab *pVTab);. i
19c70 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 nt (*xOpen)(sqli
19c80 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c te3_vtab *pVTab,
19c90 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 sqlite3_vtab_cu
19ca0 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 rsor **ppCursor)
19cb0 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 ;. int (*xClose
19cc0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 )(sqlite3_vtab_c
19cd0 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 ursor*);. int (
19ce0 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 *xFilter)(sqlite
19cf0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 3_vtab_cursor*,
19d00 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 int idxNum, cons
19d10 74 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a t char *idxStr,.
19d20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
19d30 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 int argc, sqlite
19d40 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 3_value **argv);
19d50 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 . int (*xNext)(
19d60 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 sqlite3_vtab_cur
19d70 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 sor*);. int (*x
19d80 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61 Eof)(sqlite3_vta
19d90 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e b_cursor*);. in
19da0 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c t (*xColumn)(sql
19db0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 ite3_vtab_cursor
19dc0 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 *, sqlite3_conte
19dd0 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 xt*, int);. int
19de0 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74 (*xRowid)(sqlit
19df0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c e3_vtab_cursor*,
19e00 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 2a 70 sqlite_int64 *p
19e10 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a Rowid);. int (*
19e20 78 55 70 64 61 74 65 29 28 73 71 6c 69 74 65 33 xUpdate)(sqlite3
19e30 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71 _vtab *, int, sq
19e40 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 lite3_value **,
19e50 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 2a 29 3b sqlite_int64 *);
19e60 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29 . int (*xBegin)
19e70 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 (sqlite3_vtab *p
19e80 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 VTab);. int (*x
19e90 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76 74 Sync)(sqlite3_vt
19ea0 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e ab *pVTab);. in
19eb0 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c t (*xCommit)(sql
19ec0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 ite3_vtab *pVTab
19ed0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c );. int (*xRoll
19ee0 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 74 back)(sqlite3_vt
19ef0 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e ab *pVTab);. in
19f00 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f t (*xFindFunctio
19f10 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 n)(sqlite3_vtab
19f20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72 67 *pVtab, int nArg
19f30 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
19f40 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20 20 ame,.
19f50 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 void
19f60 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c 69 (**pxFunc)(sqli
19f70 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 te3_context*,int
19f80 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a ,sqlite3_value**
19f90 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 ),.
19fa0 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 2a void *
19fb0 2a 70 70 41 72 67 29 3b 0a 0a 20 20 69 6e 74 20 *ppArg);.. int
19fc0 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 (*xRename)(sqlit
19fd0 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 e3_vtab *pVtab,
19fe0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 const char *zNew
19ff0 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 );.};../*.** The
1a000 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 sqlite3_index_i
1a010 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20 61 6e nfo structure an
1a020 64 20 69 74 73 20 73 75 62 73 74 72 75 63 74 75 d its substructu
1a030 72 65 73 20 69 73 20 75 73 65 64 20 74 6f 0a 2a res is used to.*
1a040 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d 61 74 69 * pass informati
1a050 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65 63 65 on into and rece
1a060 69 76 65 20 74 68 65 20 72 65 70 6c 79 20 66 72 ive the reply fr
1a070 6f 6d 20 74 68 65 20 78 42 65 73 74 49 6e 64 65 om the xBestInde
1a080 78 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61 x.** method of a
1a090 6e 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 n sqlite3_module
1a0a0 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e . The fields un
1a0b0 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 der **Inputs** a
1a0c0 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 re the.** inputs
1a0d0 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61 to xBestIndex a
1a0e0 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 nd are read-only
1a0f0 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e . xBestIndex in
1a100 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 serts its.** res
1a110 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a ults into the **
1a120 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 Outputs** fields
1a130 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43 6f 6e ..**.** The aCon
1a140 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 straint[] array
1a150 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c records WHERE cl
1a160 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 ause constraints
1a170 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 3a of the.** form:
1a180 0a 2a 2a 0a 2a 2a 20 20 20 20 20 20 20 20 20 63 .**.** c
1a190 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 0a 2a 2a olumn OP expr.**
1a1a0 0a 2a 2a 20 57 68 65 72 65 20 4f 50 20 69 73 20 .** Where OP is
1a1b0 3d 2c 20 3c 2c 20 3c 3d 2c 20 3e 2c 20 6f 72 20 =, <, <=, >, or
1a1c0 3e 3d 2e 20 20 54 68 65 20 70 61 72 74 69 63 75 >=. The particu
1a1d0 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69 73 20 lar operator is
1a1e0 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 43 6f stored.** in aCo
1a1f0 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e 20 20 nstraint[].op.
1a200 54 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 The index of the
1a210 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65 column is store
1a220 64 20 69 6e 20 0a 2a 2a 20 61 43 6f 6e 73 74 72 d in .** aConstr
1a230 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 20 aint[].iColumn.
1a240 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 aConstraint[].u
1a250 73 61 62 6c 65 20 69 73 20 54 52 55 45 20 69 66 sable is TRUE if
1a260 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 the.** expr on
1a270 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 the right-hand s
1a280 69 64 65 20 63 61 6e 20 62 65 20 65 76 61 6c 75 ide can be evalu
1a290 61 74 65 64 20 28 61 6e 64 20 74 68 75 73 20 74 ated (and thus t
1a2a0 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a he constraint.**
1a2b0 20 69 73 20 75 73 61 62 6c 65 29 20 61 6e 64 20 is usable) and
1a2c0 66 61 6c 73 65 20 69 66 20 69 74 20 63 61 6e 6e false if it cann
1a2d0 6f 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 70 ot..**.** The op
1a2e0 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 timizer automati
1a2f0 63 61 6c 6c 79 20 69 6e 76 65 72 74 73 20 74 65 cally inverts te
1a300 72 6d 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 rms of the form
1a310 22 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 "expr OP column"
1a320 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 .** and makes ot
1a330 68 65 72 20 73 69 6d 70 6c 69 66 69 63 61 74 69 her simplificati
1a340 6e 6f 73 20 74 6f 20 74 68 65 20 57 48 45 52 45 nos to the WHERE
1a350 20 63 6c 61 75 73 65 20 69 6e 20 61 6e 20 61 74 clause in an at
1a360 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 tempt to.** get
1a370 61 73 20 6d 61 6e 79 20 57 48 45 52 45 20 63 6c as many WHERE cl
1a380 61 75 73 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 ause terms into
1a390 74 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 the form shown a
1a3a0 62 6f 76 65 20 61 73 20 70 6f 73 73 69 62 6c 65 bove as possible
1a3b0 2e 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74 72 ..** The aConstr
1a3c0 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c aint[] array onl
1a3d0 79 20 72 65 70 6f 72 74 73 20 57 48 45 52 45 20 y reports WHERE
1a3e0 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e 20 clause terms in
1a3f0 74 68 65 20 63 6f 72 72 65 63 74 0a 2a 2a 20 66 the correct.** f
1a400 6f 72 6d 20 74 68 61 74 20 72 65 66 65 72 20 74 orm that refer t
1a410 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 o the particular
1a420 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 62 virtual table b
1a430 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a eing queried..**
1a440 0a 2a 2a 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 .** Information
1a450 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52 20 about the ORDER
1a460 42 59 20 63 6c 61 75 73 65 20 69 73 20 73 74 6f BY clause is sto
1a470 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42 79 5b red in aOrderBy[
1a480 5d 2e 0a 2a 2a 20 45 61 63 68 20 74 65 72 6d 20 ]..** Each term
1a490 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65 63 6f of aOrderBy reco
1a4a0 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 rds a column of
1a4b0 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 the ORDER BY cla
1a4c0 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 use..**.** The x
1a4d0 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64 BestIndex method
1a4e0 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73 must fill aCons
1a4f0 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 77 69 traintUsage[] wi
1a500 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a th information.*
1a510 2a 20 61 62 6f 75 74 20 77 68 61 74 20 70 61 72 * about what par
1a520 61 6d 65 74 65 72 73 20 74 6f 20 70 61 73 73 20 ameters to pass
1a530 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 49 66 20 to xFilter. If
1a540 61 72 67 76 49 6e 64 65 78 3e 30 20 74 68 65 6e argvIndex>0 then
1a550 0a 2a 2a 20 74 68 65 20 72 69 67 68 74 2d 68 61 .** the right-ha
1a560 6e 64 20 73 69 64 65 20 6f 66 20 74 68 65 20 63 nd side of the c
1a570 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f orresponding aCo
1a580 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 65 76 nstraint[] is ev
1a590 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62 aluated.** and b
1a5a0 65 63 6f 6d 65 73 20 74 68 65 20 61 72 67 76 49 ecomes the argvI
1a5b0 6e 64 65 78 2d 74 68 20 65 6e 74 72 79 20 69 6e ndex-th entry in
1a5c0 20 61 72 67 76 2e 20 20 49 66 20 61 43 6f 6e 73 argv. If aCons
1a5d0 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d traintUsage[].om
1a5e0 69 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20 74 it.** is true, t
1a5f0 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 72 61 69 hen the constrai
1a600 6e 74 20 69 73 20 61 73 73 75 6d 65 64 20 74 6f nt is assumed to
1a610 20 62 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65 be fully handle
1a620 64 20 62 79 20 74 68 65 0a 2a 2a 20 76 69 72 74 d by the.** virt
1a630 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 69 73 ual table and is
1a640 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 61 67 61 not checked aga
1a650 69 6e 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a in by SQLite..**
1a660 0a 2a 2a 20 54 68 65 20 69 64 78 4e 75 6d 20 61 .** The idxNum a
1a670 6e 64 20 69 64 78 50 74 72 20 76 61 6c 75 65 73 nd idxPtr values
1a680 20 61 72 65 20 72 65 63 6f 72 64 65 64 20 61 6e are recorded an
1a690 64 20 70 61 73 73 65 64 20 69 6e 74 6f 20 78 46 d passed into xF
1a6a0 69 6c 74 65 72 2e 0a 2a 2a 20 73 71 6c 69 74 65 ilter..** sqlite
1a6b0 33 5f 66 72 65 65 28 29 20 69 73 20 75 73 65 64 3_free() is used
1a6c0 20 74 6f 20 66 72 65 65 20 69 64 78 50 74 72 20 to free idxPtr
1a6d0 69 66 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 if needToFreeIdx
1a6e0 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a Ptr is true..**.
1a6f0 2a 2a 20 54 68 65 20 6f 72 64 65 72 42 79 43 6f ** The orderByCo
1a700 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 nsumed means tha
1a710 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 78 46 t output from xF
1a720 69 6c 74 65 72 20 77 69 6c 6c 20 6f 63 63 75 72 ilter will occur
1a730 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 72 65 in.** the corre
1a740 63 74 20 6f 72 64 65 72 20 74 6f 20 73 61 74 69 ct order to sati
1a750 73 66 79 20 74 68 65 20 4f 52 44 45 52 20 42 59 sfy the ORDER BY
1a760 20 63 6c 61 75 73 65 20 73 6f 20 74 68 61 74 20 clause so that
1a770 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 73 no separate.** s
1a780 6f 72 74 69 6e 67 20 73 74 65 70 20 69 73 20 72 orting step is r
1a790 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 equired..**.** T
1a7a0 68 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 he estimatedCost
1a7b0 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65 73 74 value is an est
1a7c0 69 6d 61 74 65 20 6f 66 20 74 68 65 20 63 6f 73 imate of the cos
1a7d0 74 20 6f 66 20 64 6f 69 6e 67 20 74 68 65 0a 2a t of doing the.*
1a7e0 2a 20 70 61 72 74 69 63 75 6c 61 72 20 6c 6f 6f * particular loo
1a7f0 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20 73 63 61 kup. A full sca
1a800 6e 20 6f 66 20 61 20 74 61 62 6c 65 20 77 69 74 n of a table wit
1a810 68 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 h N entries shou
1a820 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20 63 6f 73 ld have.** a cos
1a830 74 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e 61 72 t of N. A binar
1a840 79 20 73 65 61 72 63 68 20 6f 66 20 61 20 74 61 y search of a ta
1a850 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69 65 73 ble of N entries
1a860 20 73 68 6f 75 6c 64 20 68 61 76 65 20 61 0a 2a should have a.*
1a870 2a 20 63 6f 73 74 20 6f 66 20 61 70 70 72 6f 78 * cost of approx
1a880 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a imately log(N)..
1a890 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 */.struct sqlite
1a8a0 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a 20 3_index_info {.
1a8b0 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20 20 /* Inputs */.
1a8c0 63 6f 6e 73 74 20 69 6e 74 20 6e 43 6f 6e 73 74 const int nConst
1a8d0 72 61 69 6e 74 3b 20 20 20 20 20 2f 2a 20 4e 75 raint; /* Nu
1a8e0 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20 mber of entries
1a8f0 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 20 2a in aConstraint *
1a900 2f 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 /. const struct
1a910 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 sqlite3_index_c
1a920 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20 20 onstraint {.
1a930 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 int iColumn;
1a940 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f /* Co
1a950 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 6e lumn on left-han
1a960 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74 72 d side of constr
1a970 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e 73 aint */. uns
1a980 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20 20 igned char op;
1a990 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74 72 /* Constr
1a9a0 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a 2f aint operator */
1a9b0 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 . unsigned c
1a9c0 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20 20 har usable;
1a9d0 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69 73 20 /* True if this
1a9e0 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75 73 constraint is us
1a9f0 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e 74 able */. int
1aa00 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20 20 iTermOffset;
1aa10 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69 /* Used i
1aa20 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65 73 nternally - xBes
1aa30 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69 67 tIndex should ig
1aa40 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 63 6f 6e nore */. } *con
1aa50 73 74 20 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 st aConstraint;
1aa60 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f 66 /* Table of
1aa70 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f WHERE clause co
1aa80 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20 63 nstraints */. c
1aa90 6f 6e 73 74 20 69 6e 74 20 6e 4f 72 64 65 72 42 onst int nOrderB
1aaa0 79 3b 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d y; /* Num
1aab0 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 ber of terms in
1aac0 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 the ORDER BY cla
1aad0 75 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 use */. const s
1aae0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e truct sqlite3_in
1aaf0 64 65 78 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 dex_orderby {.
1ab00 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 int iColumn;
1ab10 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
1ab20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f Column number */
1ab30 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 . unsigned c
1ab40 68 61 72 20 64 65 73 63 3b 20 20 20 20 20 20 20 har desc;
1ab50 2f 2a 20 54 72 75 65 20 66 6f 72 20 44 45 53 43 /* True for DESC
1ab60 2e 20 20 46 61 6c 73 65 20 66 6f 72 20 41 53 43 . False for ASC
1ab70 2e 20 2a 2f 0a 20 20 7d 20 2a 63 6f 6e 73 74 20 . */. } *const
1ab80 61 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 aOrderBy;
1ab90 20 20 2f 2a 20 54 68 65 20 4f 52 44 45 52 20 42 /* The ORDER B
1aba0 59 20 63 6c 61 75 73 65 20 2a 2f 0a 0a 20 20 2f Y clause */.. /
1abb0 2a 20 4f 75 74 70 75 74 73 20 2a 2f 0a 20 20 73 * Outputs */. s
1abc0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e truct sqlite3_in
1abd0 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 5f 75 dex_constraint_u
1abe0 73 61 67 65 20 7b 0a 20 20 20 20 69 6e 74 20 61 sage {. int a
1abf0 72 67 76 49 6e 64 65 78 3b 20 20 20 20 20 20 20 rgvIndex;
1ac00 20 20 20 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f /* if >0, co
1ac10 6e 73 74 72 61 69 6e 74 20 69 73 20 70 61 72 74 nstraint is part
1ac20 20 6f 66 20 61 72 67 76 20 74 6f 20 78 46 69 6c of argv to xFil
1ac30 74 65 72 20 2a 2f 0a 20 20 20 20 75 6e 73 69 67 ter */. unsig
1ac40 6e 65 64 20 63 68 61 72 20 6f 6d 69 74 3b 20 20 ned char omit;
1ac50 20 20 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f /* Do not co
1ac60 64 65 20 61 20 74 65 73 74 20 66 6f 72 20 74 68 de a test for th
1ac70 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f is constraint */
1ac80 0a 20 20 7d 20 2a 63 6f 6e 73 74 20 61 43 6f 6e . } *const aCon
1ac90 73 74 72 61 69 6e 74 55 73 61 67 65 3b 0a 20 20 straintUsage;.
1aca0 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20 20 20 20 int idxNum;
1acb0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 /* Nu
1acc0 6d 62 65 72 20 75 73 65 64 20 74 6f 20 69 64 65 mber used to ide
1acd0 6e 74 69 66 79 20 74 68 65 20 69 6e 64 65 78 20 ntify the index
1ace0 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64 78 53 74 */. char *idxSt
1acf0 72 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 r;
1ad00 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f 73 73 69 /* String, possi
1ad10 62 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f bly obtained fro
1ad20 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 m sqlite3_malloc
1ad30 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 64 54 6f */. int needTo
1ad40 46 72 65 65 49 64 78 53 74 72 3b 20 20 20 20 20 FreeIdxStr;
1ad50 20 2f 2a 20 46 72 65 65 20 69 64 78 53 74 72 20 /* Free idxStr
1ad60 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 using sqlite3_fr
1ad70 65 65 28 29 20 69 66 20 74 72 75 65 20 2a 2f 0a ee() if true */.
1ad80 20 20 69 6e 74 20 6f 72 64 65 72 42 79 43 6f 6e int orderByCon
1ad90 73 75 6d 65 64 3b 20 20 20 20 20 20 20 2f 2a 20 sumed; /*
1ada0 54 72 75 65 20 69 66 20 6f 75 74 70 75 74 20 69 True if output i
1adb0 73 20 61 6c 72 65 61 64 79 20 6f 72 64 65 72 65 s already ordere
1adc0 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 20 65 73 d */. double es
1add0 74 69 6d 61 74 65 64 43 6f 73 74 3b 20 20 20 20 timatedCost;
1ade0 20 20 2f 2a 20 45 73 74 69 6d 61 74 65 64 20 63 /* Estimated c
1adf0 6f 73 74 20 6f 66 20 75 73 69 6e 67 20 74 68 69 ost of using thi
1ae00 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 23 64 s index */.};.#d
1ae10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 efine SQLITE_IND
1ae20 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 EX_CONSTRAINT_EQ
1ae30 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 2.#define SQ
1ae40 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 LITE_INDEX_CONST
1ae50 52 41 49 4e 54 5f 47 54 20 20 20 20 34 0a 23 64 RAINT_GT 4.#d
1ae60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 efine SQLITE_IND
1ae70 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 EX_CONSTRAINT_LE
1ae80 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 8.#define SQ
1ae90 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 LITE_INDEX_CONST
1aea0 52 41 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23 RAINT_LT 16.#
1aeb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e define SQLITE_IN
1aec0 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 DEX_CONSTRAINT_G
1aed0 45 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20 E 32.#define
1aee0 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e SQLITE_INDEX_CON
1aef0 53 54 52 41 49 4e 54 5f 4d 41 54 43 48 20 36 34 STRAINT_MATCH 64
1af00 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 ../*.** This rou
1af10 74 69 6e 65 20 69 73 20 75 73 65 64 20 74 6f 20 tine is used to
1af20 72 65 67 69 73 74 65 72 20 61 20 6e 65 77 20 6d register a new m
1af30 6f 64 75 6c 65 20 6e 61 6d 65 20 77 69 74 68 20 odule name with
1af40 61 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 6e an SQLite.** con
1af50 6e 65 63 74 69 6f 6e 2e 20 20 4d 6f 64 75 6c 65 nection. Module
1af60 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20 72 names must be r
1af70 65 67 69 73 74 65 72 65 64 20 62 65 66 6f 72 65 egistered before
1af80 20 63 72 65 61 74 69 6e 67 20 6e 65 77 0a 2a 2a creating new.**
1af90 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 virtual tables
1afa0 6f 6e 20 74 68 65 20 6d 6f 64 75 6c 65 2c 20 6f on the module, o
1afb0 72 20 62 65 66 6f 72 65 20 75 73 69 6e 67 20 70 r before using p
1afc0 72 65 65 78 69 73 74 69 6e 67 20 76 69 72 74 75 reexisting virtu
1afd0 61 6c 0a 2a 2a 20 74 61 62 6c 65 73 20 6f 66 20 al.** tables of
1afe0 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a 69 the module..*/.i
1aff0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 nt sqlite3_creat
1b000 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69 e_module(. sqli
1b010 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
1b020 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 /* SQLite
1b030 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 connection to r
1b040 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 egister module w
1b050 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 ith */. const c
1b060 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 har *zName,
1b070 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 /* Name of t
1b080 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 he module */. c
1b090 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 onst sqlite3_mod
1b0a0 75 6c 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 ule *, /* Met
1b0b0 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 hods for the mod
1b0c0 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 20 ule */. void *
1b0d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1b0e0 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 /* Client da
1b0f0 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 ta for xCreate/x
1b100 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a 2f Connect */.);../
1b110 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
1b120 65 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 e is identical t
1b130 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72 o the sqlite3_cr
1b140 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 20 6d 65 eate_module() me
1b150 74 68 6f 64 20 61 62 6f 76 65 2c 0a 2a 2a 20 65 thod above,.** e
1b160 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c xcept that it al
1b170 6c 6f 77 73 20 61 20 64 65 73 74 72 75 63 74 6f lows a destructo
1b180 72 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 r function to be
1b190 20 73 70 65 63 69 66 69 65 64 2e 20 49 74 20 69 specified. It i
1b1a0 73 0a 2a 2a 20 65 76 65 6e 20 6d 6f 72 65 20 65 s.** even more e
1b1b0 78 70 65 72 69 6d 65 6e 74 61 6c 20 74 68 61 6e xperimental than
1b1c0 20 74 68 65 20 72 65 73 74 20 6f 66 20 74 68 65 the rest of the
1b1d0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 virtual tables
1b1e0 41 50 49 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 API..*/.int sqli
1b1f0 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c te3_create_modul
1b200 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 e_v2(. sqlite3
1b210 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
1b220 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e /* SQLite con
1b230 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 nection to regis
1b240 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 ter module with
1b250 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
1b260 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 *zName,
1b270 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d /* Name of the m
1b280 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 odule */. const
1b290 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 sqlite3_module
1b2a0 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 *, /* Methods
1b2b0 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 for the module
1b2c0 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 */. void *,
1b2d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1b2e0 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 /* Client data f
1b2f0 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e or xCreate/xConn
1b300 65 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 ect */. void(*x
1b310 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 20 Destroy)(void*)
1b320 20 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 /* Module de
1b330 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f structor functio
1b340 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 45 n */.);../*.** E
1b350 76 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70 6c very module impl
1b360 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 ementation uses
1b370 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 a subclass of th
1b380 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 e following stru
1b390 63 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73 63 cture.** to desc
1b3a0 72 69 62 65 20 61 20 70 61 72 74 69 63 75 6c 61 ribe a particula
1b3b0 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 r instance of th
1b3c0 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 e module. Each
1b3d0 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a subclass will.**
1b3e0 20 62 65 20 74 61 79 6c 6f 72 65 64 20 74 6f 20 be taylored to
1b3f0 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 the specific nee
1b400 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 ds of the module
1b410 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e implementation.
1b420 20 20 20 54 68 65 0a 2a 2a 20 70 75 72 70 6f 73 The.** purpos
1b430 65 20 6f 66 20 74 68 69 73 20 73 75 70 65 72 63 e of this superc
1b440 6c 61 73 73 20 69 73 20 74 6f 20 64 65 66 69 6e lass is to defin
1b450 65 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64 73 e certain fields
1b460 20 74 68 61 74 20 61 72 65 20 63 6f 6d 6d 6f 6e that are common
1b470 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c .** to all modul
1b480 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
1b490 73 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c s..**.** Virtual
1b4a0 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 73 20 tables methods
1b4b0 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72 6f 72 can set an error
1b4c0 20 6d 65 73 73 61 67 65 20 62 79 20 61 73 73 69 message by assi
1b4d0 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e gning a.** strin
1b4e0 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 g obtained from
1b4f0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 sqlite3_mprintf(
1b500 29 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54 ) to zErrMsg. T
1b510 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 he method should
1b520 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20 74 68 .** take care th
1b530 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73 74 72 at any prior str
1b540 69 6e 67 20 69 73 20 66 72 65 65 64 20 62 79 20 ing is freed by
1b550 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 a call to sqlite
1b560 33 5f 66 72 65 65 28 29 0a 2a 2a 20 70 72 69 6f 3_free().** prio
1b570 72 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 61 r to assigning a
1b580 20 6e 65 77 20 73 74 72 69 6e 67 20 74 6f 20 7a new string to z
1b590 45 72 72 4d 73 67 2e 20 20 41 66 74 65 72 20 74 ErrMsg. After t
1b5a0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 he error message
1b5b0 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 65 64 .** is delivered
1b5c0 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69 65 6e up to the clien
1b5d0 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 t application, t
1b5e0 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 he string will b
1b5f0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a e automatically.
1b600 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71 6c 69 ** freed by sqli
1b610 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64 20 74 te3_free() and t
1b620 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 he zErrMsg field
1b630 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e will be zeroed.
1b640 20 20 4e 6f 74 65 0a 2a 2a 20 74 68 61 74 20 73 Note.** that s
1b650 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 qlite3_mprintf()
1b660 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 66 72 65 and sqlite3_fre
1b670 65 28 29 20 61 72 65 20 75 73 65 64 20 6f 6e 20 e() are used on
1b680 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c the zErrMsg fiel
1b690 64 0a 2a 2a 20 73 69 6e 63 65 20 76 69 72 74 75 d.** since virtu
1b6a0 61 6c 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f al tables are co
1b6b0 6d 6d 6f 6e 6c 79 20 69 6d 70 6c 65 6d 65 6e 74 mmonly implement
1b6c0 65 64 20 69 6e 20 6c 6f 61 64 61 62 6c 65 20 65 ed in loadable e
1b6d0 78 74 65 6e 73 69 6f 6e 73 20 77 68 69 63 68 0a xtensions which.
1b6e0 2a 2a 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 61 ** do not have a
1b6f0 63 63 65 73 73 20 74 6f 20 73 71 6c 69 74 65 33 ccess to sqlite3
1b700 4d 50 72 69 6e 74 66 28 29 20 6f 72 20 73 71 6c MPrintf() or sql
1b710 69 74 65 33 46 72 65 65 28 29 2e 0a 2a 2f 0a 73 ite3Free()..*/.s
1b720 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 truct sqlite3_vt
1b730 61 62 20 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c ab {. const sql
1b740 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f ite3_module *pMo
1b750 64 75 6c 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f dule; /* The mo
1b760 64 75 6c 65 20 66 6f 72 20 74 68 69 73 20 76 69 dule for this vi
1b770 72 74 75 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 rtual table */.
1b780 20 69 6e 74 20 6e 52 65 66 3b 20 20 20 20 20 20 int nRef;
1b790 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1b7a0 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61 /* Used interna
1b7b0 6c 6c 79 20 2a 2f 0a 20 20 63 68 61 72 20 2a 7a lly */. char *z
1b7c0 45 72 72 4d 73 67 3b 20 20 20 20 20 20 20 20 20 ErrMsg;
1b7d0 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f /* Erro
1b7e0 72 20 6d 65 73 73 61 67 65 20 66 72 6f 6d 20 73 r message from s
1b7f0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 qlite3_mprintf()
1b800 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c */. /* Virtual
1b810 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 table implement
1b820 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 ations will typi
1b830 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 cally add additi
1b840 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d onal fields */.}
1b850 3b 0a 0a 2f 2a 20 45 76 65 72 79 20 6d 6f 64 75 ;../* Every modu
1b860 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
1b870 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 n uses a subclas
1b880 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 s of the followi
1b890 6e 67 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 ng structure.**
1b8a0 74 6f 20 64 65 73 63 72 69 62 65 20 63 75 72 73 to describe curs
1b8b0 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74 20 69 ors that point i
1b8c0 6e 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 20 nto the virtual
1b8d0 74 61 62 6c 65 20 61 6e 64 20 61 72 65 20 75 73 table and are us
1b8e0 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74 68 ed.** to loop th
1b8f0 72 6f 75 67 68 20 74 68 65 20 76 69 72 74 75 61 rough the virtua
1b900 6c 20 74 61 62 6c 65 2e 20 20 43 75 72 73 6f 72 l table. Cursor
1b910 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 s are created us
1b920 69 6e 67 20 74 68 65 0a 2a 2a 20 78 4f 70 65 6e ing the.** xOpen
1b930 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 6d method of the m
1b940 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64 odule. Each mod
1b950 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ule implementati
1b960 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a on will define.*
1b970 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 * the content of
1b980 20 61 20 63 75 72 73 6f 72 20 73 74 72 75 63 74 a cursor struct
1b990 75 72 65 20 74 6f 20 73 75 69 74 20 69 74 73 20 ure to suit its
1b9a0 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a own needs..**.**
1b9b0 20 54 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 This superclass
1b9c0 20 65 78 69 73 74 73 20 69 6e 20 6f 72 64 65 72 exists in order
1b9d0 20 74 6f 20 64 65 66 69 6e 65 20 66 69 65 6c 64 to define field
1b9e0 73 20 6f 66 20 74 68 65 20 63 75 72 73 6f 72 20 s of the cursor
1b9f0 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d that.** are comm
1ba00 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d on to all implem
1ba10 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 entations..*/.st
1ba20 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 ruct sqlite3_vta
1ba30 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73 71 6c b_cursor {. sql
1ba40 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 ite3_vtab *pVtab
1ba50 3b 20 20 20 20 20 20 2f 2a 20 56 69 72 74 75 61 ; /* Virtua
1ba60 6c 20 74 61 62 6c 65 20 6f 66 20 74 68 69 73 20 l table of this
1ba70 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 cursor */. /* V
1ba80 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 irtual table imp
1ba90 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c lementations wil
1baa0 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 l typically add
1bab0 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 additional field
1bac0 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 54 s */.};../*.** T
1bad0 68 65 20 78 43 72 65 61 74 65 20 61 6e 64 20 78 he xCreate and x
1bae0 43 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64 73 20 Connect methods
1baf0 6f 66 20 61 20 6d 6f 64 75 6c 65 20 75 73 65 20 of a module use
1bb00 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 the following AP
1bb10 49 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72 65 20 I.** to declare
1bb20 74 68 65 20 66 6f 72 6d 61 74 20 28 74 68 65 20 the format (the
1bb30 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 61 74 79 names and dataty
1bb40 70 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d pes of the colum
1bb50 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20 76 69 ns) of.** the vi
1bb60 72 74 75 61 6c 20 74 61 62 6c 65 73 20 74 68 65 rtual tables the
1bb70 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a y implement..*/.
1bb80 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 65 63 6c int sqlite3_decl
1bb90 61 72 65 5f 76 74 61 62 28 73 71 6c 69 74 65 33 are_vtab(sqlite3
1bba0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
1bbb0 43 72 65 61 74 65 54 61 62 6c 65 29 3b 0a 0a 2f CreateTable);../
1bbc0 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 *.** Virtual tab
1bbd0 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64 65 20 les can provide
1bbe0 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70 6c alternative impl
1bbf0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66 ementations of f
1bc00 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e unctions.** usin
1bc10 67 20 74 68 65 20 78 46 69 6e 64 46 75 6e 63 74 g the xFindFunct
1bc20 69 6f 6e 20 6d 65 74 68 6f 64 2e 20 20 42 75 74 ion method. But
1bc30 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 73 global versions
1bc40 20 6f 66 20 74 68 6f 73 65 20 66 75 6e 63 74 69 of those functi
1bc50 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69 73 ons.** must exis
1bc60 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 62 65 t in order to be
1bc70 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a overloaded..**.
1bc80 2a 2a 20 54 68 69 73 20 41 50 49 20 6d 61 6b 65 ** This API make
1bc90 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61 6c 20 s sure a global
1bca0 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 75 6e version of a fun
1bcb0 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70 61 72 ction with a par
1bcc0 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20 ticular.** name
1bcd0 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 and number of pa
1bce0 72 61 6d 65 74 65 72 73 20 65 78 69 73 74 73 2e rameters exists.
1bcf0 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66 75 6e If no such fun
1bd00 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a 20 ction exists.**
1bd10 62 65 66 6f 72 65 20 74 68 69 73 20 41 50 49 20 before this API
1bd20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65 77 is called, a new
1bd30 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 72 65 function is cre
1bd40 61 74 65 64 2e 20 20 54 68 65 20 69 6d 70 6c 65 ated. The imple
1bd50 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 mentation.** of
1bd60 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e the new function
1bd70 20 61 6c 77 61 79 73 20 63 61 75 73 65 73 20 61 always causes a
1bd80 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f 20 62 n exception to b
1bd90 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a e thrown. So.**
1bda0 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f the new functio
1bdb0 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20 66 6f n is not good fo
1bdc0 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20 69 74 r anything by it
1bdd0 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c 79 0a self. Its only.
1bde0 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20 74 6f ** purpose is to
1bdf0 20 62 65 20 61 20 70 6c 61 63 65 2d 68 6f 6c 64 be a place-hold
1be00 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 er function that
1be10 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61 64 can be overload
1be20 65 64 0a 2a 2a 20 62 79 20 76 69 72 74 75 61 6c ed.** by virtual
1be30 20 74 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 tables..**.** T
1be40 68 69 73 20 41 50 49 20 73 68 6f 75 6c 64 20 62 his API should b
1be50 65 20 63 6f 6e 73 69 64 65 72 65 64 20 70 61 72 e considered par
1be60 74 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c t of the virtual
1be70 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61 63 65 table interface
1be80 2c 0a 2a 2a 20 77 68 69 63 68 20 69 73 20 65 78 ,.** which is ex
1be90 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 73 perimental and s
1bea0 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 ubject to change
1beb0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
1bec0 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 _overload_functi
1bed0 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e on(sqlite3*, con
1bee0 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 st char *zFuncNa
1bef0 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a me, int nArg);..
1bf00 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 /*.** The interf
1bf10 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 ace to the virtu
1bf20 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 al-table mechani
1bf30 73 6d 20 64 65 66 69 6e 65 64 20 61 62 6f 76 65 sm defined above
1bf40 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 (back up.** to
1bf50 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b a comment remark
1bf60 61 62 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 ably similar to
1bf70 74 68 69 73 20 6f 6e 65 29 20 69 73 20 63 75 72 this one) is cur
1bf80 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 rently considere
1bf90 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 d.** to be exper
1bfa0 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e imental. The in
1bfb0 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 terface might ch
1bfc0 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 ange in incompat
1bfd0 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 ible ways..** If
1bfe0 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c this is a probl
1bff0 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e em for you, do n
1c000 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 ot use the inter
1c010 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d face at this tim
1c020 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 e..**.** When th
1c030 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 e virtual-table
1c040 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 6c 69 mechanism stabli
1c050 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 zes, we will dec
1c060 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 lare the.** inte
1c070 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 rface fixed, sup
1c080 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 port it indefini
1c090 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 tely, and remove
1c0a0 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a this comment..*
1c0b0 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d *.****** EXPERIM
1c0c0 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 ENTAL - subject
1c0d0 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 to change withou
1c0e0 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a t notice *******
1c0f0 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a *******.*/../*.*
1c100 2a 20 43 41 50 49 33 52 45 46 3a 20 41 20 48 61 * CAPI3REF: A Ha
1c110 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e 20 ndle To An Open
1c120 42 4c 4f 42 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e BLOB.**.** An in
1c130 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 66 6f stance of the fo
1c140 6c 6c 6f 77 69 6e 67 20 6f 70 61 71 75 65 20 73 llowing opaque s
1c150 74 72 75 63 74 75 72 65 20 69 73 20 75 73 65 64 tructure is used
1c160 20 74 6f 20 0a 2a 2a 20 72 65 70 72 65 73 65 6e to .** represen
1c170 74 20 61 6e 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 t an blob-handle
1c180 2e 20 20 41 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 . A blob-handle
1c190 20 69 73 20 63 72 65 61 74 65 64 20 62 79 0a 2a is created by.*
1c1a0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f * [sqlite3_blob_
1c1b0 6f 70 65 6e 28 29 5d 20 61 6e 64 20 64 65 73 74 open()] and dest
1c1c0 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 royed by [sqlite
1c1d0 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 3_blob_close()].
1c1e0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 .** The [sqlite3
1c1f0 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e _blob_read()] an
1c200 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f d [sqlite3_blob_
1c210 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66 61 write()] interfa
1c220 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 ces.** can be us
1c230 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 ed to read or wr
1c240 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 63 ite small subsec
1c250 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 6c 6f tions of the blo
1c260 62 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 74 69 b..** The [sqlti
1c270 65 33 5f 62 6c 6f 62 5f 73 69 7a 65 28 29 5d 20 e3_blob_size()]
1c280 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
1c290 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 s the size of th
1c2a0 65 0a 2a 2a 20 62 6c 6f 62 20 69 6e 20 62 79 74 e.** blob in byt
1c2b0 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 es..*/.typedef s
1c2c0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62 6c truct sqlite3_bl
1c2d0 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b ob sqlite3_blob;
1c2e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1c2f0 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f : Open A BLOB Fo
1c300 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f r Incremental I/
1c310 4f 0a 2a 2a 0a 2a 2a 20 4f 70 65 6e 20 61 20 68 O.**.** Open a h
1c320 61 6e 64 6c 65 20 74 6f 20 74 68 65 20 62 6c 6f andle to the blo
1c330 62 20 6c 6f 63 61 74 65 64 20 69 6e 20 72 6f 77 b located in row
1c340 20 69 52 6f 77 2c 2c 20 63 6f 6c 75 6d 6e 20 7a iRow,, column z
1c350 43 6f 6c 75 6d 6e 2c 20 0a 2a 2a 20 74 61 62 6c Column, .** tabl
1c360 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61 74 61 e zTable in data
1c370 62 61 73 65 20 7a 44 62 2e 20 69 2e 65 2e 20 74 base zDb. i.e. t
1c380 68 65 20 73 61 6d 65 20 62 6c 6f 62 20 74 68 61 he same blob tha
1c390 74 20 77 6f 75 6c 64 0a 2a 2a 20 62 65 20 73 65 t would.** be se
1c3a0 6c 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a lected by:.**.**
1c3b0 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 <pre>.** SE
1c3c0 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f LECT zColumn FRO
1c3d0 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 M zDb.zTable WHE
1c3e0 52 45 20 72 6f 77 69 64 20 3d 20 69 52 6f 77 3b RE rowid = iRow;
1c3f0 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a .** </pre>.**.**
1c400 20 49 66 20 74 68 65 20 66 6c 61 67 73 20 70 61 If the flags pa
1c410 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a rameter is non-z
1c420 65 72 6f 2c 20 74 68 65 20 62 6c 6f 62 20 69 73 ero, the blob is
1c430 20 6f 70 65 6e 65 64 20 66 6f 72 20 0a 2a 2a 20 opened for .**
1c440 72 65 61 64 20 61 6e 64 20 77 72 69 74 65 20 61 read and write a
1c450 63 63 65 73 73 2e 20 49 66 20 69 74 20 69 73 20 ccess. If it is
1c460 7a 65 72 6f 2c 20 74 68 65 20 62 6c 6f 62 20 69 zero, the blob i
1c470 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 s opened for rea
1c480 64 20 0a 2a 2a 20 61 63 63 65 73 73 2e 0a 2a 2a d .** access..**
1c490 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 .** On success,
1c4a0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 [SQLITE_OK] is r
1c4b0 65 74 75 72 6e 65 64 20 61 6e 64 20 74 68 65 20 eturned and the
1c4c0 6e 65 77 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 new .** [sqlite3
1c4d0 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 20 68 61 6e _blob | blob han
1c4e0 64 6c 65 5d 20 69 73 20 77 72 69 74 74 65 6e 20 dle] is written
1c4f0 74 6f 20 2a 70 70 42 6c 6f 62 2e 0a 2a 2a 20 4f to *ppBlob..** O
1c500 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f therwise an erro
1c510 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e r code is return
1c520 65 64 20 61 6e 64 20 0a 2a 2a 20 61 6e 79 20 76 ed and .** any v
1c530 61 6c 75 65 20 77 72 69 74 74 65 6e 20 74 6f 20 alue written to
1c540 2a 70 70 42 6c 6f 62 20 73 68 6f 75 6c 64 20 6e *ppBlob should n
1c550 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 74 68 ot be used by th
1c560 65 20 63 61 6c 6c 65 72 2e 0a 2a 2a 20 54 68 69 e caller..** Thi
1c570 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 s function sets
1c580 74 68 65 20 64 61 74 61 62 61 73 65 2d 68 61 6e the database-han
1c590 64 6c 65 20 65 72 72 6f 72 20 63 6f 64 65 20 61 dle error code a
1c5a0 6e 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20 61 63 nd message.** ac
1c5b0 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73 71 cessible via [sq
1c5c0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d lite3_errcode()]
1c5d0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 and [sqlite3_er
1c5e0 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 rmsg()]..*/.int
1c5f0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 sqlite3_blob_ope
1c600 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 n(. sqlite3*,.
1c610 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 const char *zDb
1c620 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a ,. const char *
1c630 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 zTable,. const
1c640 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 char *zColumn,.
1c650 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 69 52 sqlite_int64 iR
1c660 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c ow,. int flags,
1c670 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 . sqlite3_blob
1c680 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a **ppBlob.);../*.
1c690 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 43 6c ** CAPI3REF: Cl
1c6a0 6f 73 65 20 41 20 42 4c 4f 42 20 48 61 6e 64 6c ose A BLOB Handl
1c6b0 65 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 65 20 61 6e e.**.** Close an
1c6c0 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 62 open [sqlite3_b
1c6d0 6c 6f 62 20 7c 20 62 6c 6f 62 20 68 61 6e 64 6c lob | blob handl
1c6e0 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 e]..*/.int sqlit
1c6f0 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71 e3_blob_close(sq
1c700 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a lite3_blob *);..
1c710 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1c720 20 52 65 74 75 72 6e 20 54 68 65 20 53 69 7a 65 Return The Size
1c730 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 Of An Open BLOB
1c740 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 .**.** Return th
1c750 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73 20 e size in bytes
1c760 6f 66 20 74 68 65 20 62 6c 6f 62 20 61 63 63 65 of the blob acce
1c770 73 73 69 62 6c 65 20 76 69 61 20 74 68 65 20 6f ssible via the o
1c780 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 pen .** [sqlite3
1c790 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 61 6e _blob | blob-han
1c7a0 64 6c 65 5d 20 70 61 73 73 65 64 20 61 73 20 61 dle] passed as a
1c7b0 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2f 0a 69 n argument..*/.i
1c7c0 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f nt sqlite3_blob_
1c7d0 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 62 6c bytes(sqlite3_bl
1c7e0 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ob *);../*.** CA
1c7f0 50 49 33 52 45 46 3a 20 20 52 65 61 64 20 44 61 PI3REF: Read Da
1c800 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49 ta From A BLOB I
1c810 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a ncrementally.**.
1c820 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e ** This function
1c830 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 61 64 is used to read
1c840 20 64 61 74 61 20 66 72 6f 6d 20 61 6e 20 6f 70 data from an op
1c850 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f en .** [sqlite3_
1c860 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 61 6e 64 blob | blob-hand
1c870 6c 65 5d 20 69 6e 74 6f 20 61 20 63 61 6c 6c 65 le] into a calle
1c880 72 20 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 r supplied buffe
1c890 72 2e 0a 2a 2a 20 6e 20 62 79 74 65 73 20 6f 66 r..** n bytes of
1c8a0 20 64 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 data are copied
1c8b0 20 69 6e 74 6f 20 62 75 66 66 65 72 0a 2a 2a 20 into buffer.**
1c8c0 7a 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 6e 20 z from the open
1c8d0 62 6c 6f 62 2c 20 73 74 61 72 74 69 6e 67 20 61 blob, starting a
1c8e0 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 t offset iOffset
1c8f0 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 ..**.** On succe
1c900 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 ss, SQLITE_OK is
1c910 20 72 65 74 75 72 6e 65 64 2e 20 4f 74 68 65 72 returned. Other
1c920 77 69 73 65 2c 20 61 6e 20 0a 2a 2a 20 5b 53 51 wise, an .** [SQ
1c930 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 53 51 4c LITE_ERROR | SQL
1c940 69 74 65 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 ite error code]
1c950 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 or an.** [SQLITE
1c960 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 _IOERR_READ | ex
1c970 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 tended error cod
1c980 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a e] is returned..
1c990 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 */.int sqlite3_b
1c9a0 6c 6f 62 5f 72 65 61 64 28 73 71 6c 69 74 65 33 lob_read(sqlite3
1c9b0 5f 62 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 2a 7a _blob *, void *z
1c9c0 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 , int n, int iOf
1c9d0 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 fset);../*.** CA
1c9e0 50 49 33 52 45 46 3a 20 20 57 72 69 74 65 20 44 PI3REF: Write D
1c9f0 61 74 61 20 49 6e 74 6f 20 41 20 42 4c 4f 42 20 ata Into A BLOB
1ca00 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a Incrementally.**
1ca10 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f .** This functio
1ca20 6e 20 69 73 20 75 73 65 64 20 74 6f 20 77 72 69 n is used to wri
1ca30 74 65 20 64 61 74 61 20 69 6e 74 6f 20 61 6e 20 te data into an
1ca40 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 open .** [sqlite
1ca50 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 61 3_blob | blob-ha
1ca60 6e 64 6c 65 5d 20 66 72 6f 6d 20 61 20 75 73 65 ndle] from a use
1ca70 72 20 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 r supplied buffe
1ca80 72 2e 0a 2a 2a 20 6e 20 62 79 74 65 73 20 6f 66 r..** n bytes of
1ca90 20 64 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 data are copied
1caa0 20 66 72 6f 6d 20 74 68 65 20 62 75 66 66 65 72 from the buffer
1cab0 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 .** pointed to b
1cac0 79 20 7a 20 69 6e 74 6f 20 74 68 65 20 6f 70 65 y z into the ope
1cad0 6e 20 62 6c 6f 62 2c 20 73 74 61 72 74 69 6e 67 n blob, starting
1cae0 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73 at offset iOffs
1caf0 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 et..**.** If the
1cb00 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c [sqlite3_blob |
1cb10 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 70 61 blob-handle] pa
1cb20 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 ssed as the firs
1cb30 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 61 t argument.** wa
1cb40 73 20 6e 6f 74 20 6f 70 65 6e 65 64 20 66 6f 72 s not opened for
1cb50 20 77 72 69 74 69 6e 67 20 28 74 68 65 20 66 6c writing (the fl
1cb60 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f ags parameter to
1cb70 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f [sqlite3_blob_o
1cb80 70 65 6e 28 29 5d 0a 2a 2a 2a 20 77 61 73 20 7a pen()].*** was z
1cb90 65 72 6f 29 2c 20 74 68 69 73 20 66 75 6e 63 74 ero), this funct
1cba0 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ion returns [SQL
1cbb0 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a ITE_READONLY]..*
1cbc0 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 *.** This functi
1cbd0 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 on may only modi
1cbe0 66 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 fy the contents
1cbf0 6f 66 20 74 68 65 20 62 6c 6f 62 2c 20 69 74 20 of the blob, it
1cc00 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 is.** not possib
1cc10 6c 65 20 74 6f 20 69 6e 63 72 65 61 73 65 20 74 le to increase t
1cc20 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f he size of a blo
1cc30 62 20 75 73 69 6e 67 20 74 68 69 73 20 41 50 49 b using this API
1cc40 2e 20 49 66 0a 2a 2a 20 6f 66 66 73 65 74 20 69 . If.** offset i
1cc50 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 Offset is less t
1cc60 68 61 6e 20 6e 20 62 79 74 65 73 20 66 72 6f 6d han n bytes from
1cc70 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 the end of the
1cc80 62 6c 6f 62 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 blob, .** [SQLIT
1cc90 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 E_ERROR] is retu
1cca0 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 rned and no data
1ccb0 20 69 73 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a is written..**.
1ccc0 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 53 ** On success, S
1ccd0 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 QLITE_OK is retu
1cce0 72 6e 65 64 2e 20 4f 74 68 65 72 77 69 73 65 2c rned. Otherwise,
1ccf0 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f an .** [SQLITE_
1cd00 45 52 52 4f 52 20 7c 20 53 51 4c 69 74 65 20 65 ERROR | SQLite e
1cd10 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e rror code] or an
1cd20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 .** [SQLITE_IOER
1cd30 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 R_READ | extende
1cd40 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 d error code] is
1cd50 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e returned..*/.in
1cd60 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 t sqlite3_blob_w
1cd70 72 69 74 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f rite(sqlite3_blo
1cd80 62 20 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 20 b *, const void
1cd90 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69 *z, int n, int i
1cda0 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 Offset);../*.**
1cdb0 55 6e 64 6f 20 74 68 65 20 68 61 63 6b 20 74 68 Undo the hack th
1cdc0 61 74 20 63 6f 6e 76 65 72 74 73 20 66 6c 6f 61 at converts floa
1cdd0 74 69 6e 67 20 70 6f 69 6e 74 20 74 79 70 65 73 ting point types
1cde0 20 74 6f 20 69 6e 74 65 67 65 72 20 66 6f 72 0a to integer for.
1cdf0 2a 2a 20 62 75 69 6c 64 73 20 6f 6e 20 70 72 6f ** builds on pro
1ce00 63 65 73 73 6f 72 73 20 77 69 74 68 6f 75 74 20 cessors without
1ce10 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 floating point s
1ce20 75 70 70 6f 72 74 2e 0a 2a 2f 0a 23 69 66 64 65 upport..*/.#ifde
1ce30 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c f SQLITE_OMIT_FL
1ce40 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 75 OATING_POINT.# u
1ce50 6e 64 65 66 20 64 6f 75 62 6c 65 0a 23 65 6e 64 ndef double.#end
1ce60 69 66 0a 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c if..#ifdef __cpl
1ce70 75 73 70 6c 75 73 0a 7d 20 20 2f 2a 20 45 6e 64 usplus.} /* End
1ce80 20 6f 66 20 74 68 65 20 27 65 78 74 65 72 6e 20 of the 'extern
1ce90 22 43 22 27 20 62 6c 6f 63 6b 20 2a 2f 0a 23 65 "C"' block */.#e
1cea0 6e 64 69 66 0a 23 65 6e 64 69 66 0a ndif.#endif.