amalgalite 1.5.0-x86-mingw32 → 1.6.0-x86-mingw32
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/HISTORY.md +13 -0
- data/LICENSE +2 -0
- data/README.md +1 -1
- data/Rakefile +5 -5
- data/ext/amalgalite/c/amalgalite.c +26 -0
- data/ext/amalgalite/c/amalgalite_constants.c +887 -39
- data/ext/amalgalite/c/extconf.rb +5 -1
- data/ext/amalgalite/c/gen_constants.rb +290 -153
- data/ext/amalgalite/c/sqlite3.c +39928 -18827
- data/ext/amalgalite/c/sqlite3.h +2739 -455
- data/ext/amalgalite/c/sqlite3ext.h +54 -10
- data/lib/amalgalite/2.0/amalgalite.so +0 -0
- data/lib/amalgalite/2.1/amalgalite.so +0 -0
- data/lib/amalgalite/2.2/amalgalite.so +0 -0
- data/lib/amalgalite/2.3/amalgalite.so +0 -0
- data/lib/amalgalite/2.4/amalgalite.so +0 -0
- data/lib/amalgalite/type_maps/default_map.rb +1 -1
- data/lib/amalgalite/type_maps/storage_map.rb +1 -1
- data/lib/amalgalite/version.rb +1 -1
- data/spec/default_map_spec.rb +1 -1
- data/spec/integeration_spec.rb +2 -2
- data/spec/sqlite3/version_spec.rb +15 -9
- data/spec/storage_map_spec.rb +1 -1
- data/tasks/default.rake +3 -10
- data/tasks/extension.rake +4 -4
- data/tasks/this.rb +3 -1
- metadata +19 -16
- data/lib/amalgalite/1.8/amalgalite.so +0 -0
- data/lib/amalgalite/1.9/amalgalite.so +0 -0
data/ext/amalgalite/c/sqlite3.h
CHANGED
@@ -1,5 +1,5 @@
|
|
1
1
|
/*
|
2
|
-
** 2001
|
2
|
+
** 2001-09-15
|
3
3
|
**
|
4
4
|
** The author disclaims copyright to this source code. In place of
|
5
5
|
** a legal notice, here is a blessing:
|
@@ -30,8 +30,8 @@
|
|
30
30
|
** the version number) and changes its name to "sqlite3.h" as
|
31
31
|
** part of the build process.
|
32
32
|
*/
|
33
|
-
#ifndef
|
34
|
-
#define
|
33
|
+
#ifndef SQLITE3_H
|
34
|
+
#define SQLITE3_H
|
35
35
|
#include <stdarg.h> /* Needed for the definition of va_list */
|
36
36
|
|
37
37
|
/*
|
@@ -54,8 +54,17 @@ extern "C" {
|
|
54
54
|
#ifndef SQLITE_CDECL
|
55
55
|
# define SQLITE_CDECL
|
56
56
|
#endif
|
57
|
+
#ifndef SQLITE_APICALL
|
58
|
+
# define SQLITE_APICALL
|
59
|
+
#endif
|
57
60
|
#ifndef SQLITE_STDCALL
|
58
|
-
# define SQLITE_STDCALL
|
61
|
+
# define SQLITE_STDCALL SQLITE_APICALL
|
62
|
+
#endif
|
63
|
+
#ifndef SQLITE_CALLBACK
|
64
|
+
# define SQLITE_CALLBACK
|
65
|
+
#endif
|
66
|
+
#ifndef SQLITE_SYSAPI
|
67
|
+
# define SQLITE_SYSAPI
|
59
68
|
#endif
|
60
69
|
|
61
70
|
/*
|
@@ -99,25 +108,28 @@ extern "C" {
|
|
99
108
|
** be held constant and Z will be incremented or else Y will be incremented
|
100
109
|
** and Z will be reset to zero.
|
101
110
|
**
|
102
|
-
** Since version 3.6.18,
|
111
|
+
** Since [version 3.6.18] ([dateof:3.6.18]),
|
112
|
+
** SQLite source code has been stored in the
|
103
113
|
** <a href="http://www.fossil-scm.org/">Fossil configuration management
|
104
114
|
** system</a>. ^The SQLITE_SOURCE_ID macro evaluates to
|
105
115
|
** a string which identifies a particular check-in of SQLite
|
106
116
|
** within its configuration management system. ^The SQLITE_SOURCE_ID
|
107
|
-
** string contains the date and time of the check-in (UTC) and
|
108
|
-
** hash of the entire source tree.
|
117
|
+
** string contains the date and time of the check-in (UTC) and a SHA1
|
118
|
+
** or SHA3-256 hash of the entire source tree. If the source code has
|
119
|
+
** been edited in any way since it was last checked in, then the last
|
120
|
+
** four hexadecimal digits of the hash may be modified.
|
109
121
|
**
|
110
122
|
** See also: [sqlite3_libversion()],
|
111
123
|
** [sqlite3_libversion_number()], [sqlite3_sourceid()],
|
112
124
|
** [sqlite_version()] and [sqlite_source_id()].
|
113
125
|
*/
|
114
|
-
#define SQLITE_VERSION "3.
|
115
|
-
#define SQLITE_VERSION_NUMBER
|
116
|
-
#define SQLITE_SOURCE_ID "
|
126
|
+
#define SQLITE_VERSION "3.21.0"
|
127
|
+
#define SQLITE_VERSION_NUMBER 3021000
|
128
|
+
#define SQLITE_SOURCE_ID "2017-10-24 18:55:49 1a584e499906b5c87ec7d43d4abce641fdf017c42125b083109bc77c4de48827"
|
117
129
|
|
118
130
|
/*
|
119
131
|
** CAPI3REF: Run-Time Library Version Numbers
|
120
|
-
** KEYWORDS: sqlite3_version
|
132
|
+
** KEYWORDS: sqlite3_version sqlite3_sourceid
|
121
133
|
**
|
122
134
|
** These interfaces provide the same information as the [SQLITE_VERSION],
|
123
135
|
** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] C preprocessor macros
|
@@ -129,7 +141,7 @@ extern "C" {
|
|
129
141
|
**
|
130
142
|
** <blockquote><pre>
|
131
143
|
** assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER );
|
132
|
-
** assert(
|
144
|
+
** assert( strncmp(sqlite3_sourceid(),SQLITE_SOURCE_ID,80)==0 );
|
133
145
|
** assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 );
|
134
146
|
** </pre></blockquote>)^
|
135
147
|
**
|
@@ -139,16 +151,18 @@ extern "C" {
|
|
139
151
|
** function is provided for use in DLLs since DLL users usually do not have
|
140
152
|
** direct access to string constants within the DLL. ^The
|
141
153
|
** sqlite3_libversion_number() function returns an integer equal to
|
142
|
-
** [SQLITE_VERSION_NUMBER]. ^The sqlite3_sourceid() function returns
|
154
|
+
** [SQLITE_VERSION_NUMBER]. ^(The sqlite3_sourceid() function returns
|
143
155
|
** a pointer to a string constant whose value is the same as the
|
144
|
-
** [SQLITE_SOURCE_ID] C preprocessor macro.
|
156
|
+
** [SQLITE_SOURCE_ID] C preprocessor macro. Except if SQLite is built
|
157
|
+
** using an edited copy of [the amalgamation], then the last four characters
|
158
|
+
** of the hash might be different from [SQLITE_SOURCE_ID].)^
|
145
159
|
**
|
146
160
|
** See also: [sqlite_version()] and [sqlite_source_id()].
|
147
161
|
*/
|
148
162
|
SQLITE_API SQLITE_EXTERN const char sqlite3_version[];
|
149
|
-
SQLITE_API const char *
|
150
|
-
SQLITE_API const char *
|
151
|
-
SQLITE_API int
|
163
|
+
SQLITE_API const char *sqlite3_libversion(void);
|
164
|
+
SQLITE_API const char *sqlite3_sourceid(void);
|
165
|
+
SQLITE_API int sqlite3_libversion_number(void);
|
152
166
|
|
153
167
|
/*
|
154
168
|
** CAPI3REF: Run-Time Library Compilation Options Diagnostics
|
@@ -173,8 +187,8 @@ SQLITE_API int SQLITE_STDCALL sqlite3_libversion_number(void);
|
|
173
187
|
** [sqlite_compileoption_get()] and the [compile_options pragma].
|
174
188
|
*/
|
175
189
|
#ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS
|
176
|
-
SQLITE_API int
|
177
|
-
SQLITE_API const char *
|
190
|
+
SQLITE_API int sqlite3_compileoption_used(const char *zOptName);
|
191
|
+
SQLITE_API const char *sqlite3_compileoption_get(int N);
|
178
192
|
#endif
|
179
193
|
|
180
194
|
/*
|
@@ -213,7 +227,7 @@ SQLITE_API const char *SQLITE_STDCALL sqlite3_compileoption_get(int N);
|
|
213
227
|
**
|
214
228
|
** See the [threading mode] documentation for additional information.
|
215
229
|
*/
|
216
|
-
SQLITE_API int
|
230
|
+
SQLITE_API int sqlite3_threadsafe(void);
|
217
231
|
|
218
232
|
/*
|
219
233
|
** CAPI3REF: Database Connection Handle
|
@@ -249,7 +263,11 @@ typedef struct sqlite3 sqlite3;
|
|
249
263
|
*/
|
250
264
|
#ifdef SQLITE_INT64_TYPE
|
251
265
|
typedef SQLITE_INT64_TYPE sqlite_int64;
|
252
|
-
|
266
|
+
# ifdef SQLITE_UINT64_TYPE
|
267
|
+
typedef SQLITE_UINT64_TYPE sqlite_uint64;
|
268
|
+
# else
|
269
|
+
typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;
|
270
|
+
# endif
|
253
271
|
#elif defined(_MSC_VER) || defined(__BORLANDC__)
|
254
272
|
typedef __int64 sqlite_int64;
|
255
273
|
typedef unsigned __int64 sqlite_uint64;
|
@@ -310,8 +328,8 @@ typedef sqlite_uint64 sqlite3_uint64;
|
|
310
328
|
** ^Calling sqlite3_close() or sqlite3_close_v2() with a NULL pointer
|
311
329
|
** argument is a harmless no-op.
|
312
330
|
*/
|
313
|
-
SQLITE_API int
|
314
|
-
SQLITE_API int
|
331
|
+
SQLITE_API int sqlite3_close(sqlite3*);
|
332
|
+
SQLITE_API int sqlite3_close_v2(sqlite3*);
|
315
333
|
|
316
334
|
/*
|
317
335
|
** The type for a callback function.
|
@@ -347,7 +365,7 @@ typedef int (*sqlite3_callback)(void*,int,char**, char**);
|
|
347
365
|
** from [sqlite3_malloc()] and passed back through the 5th parameter.
|
348
366
|
** To avoid memory leaks, the application should invoke [sqlite3_free()]
|
349
367
|
** on error message strings returned through the 5th parameter of
|
350
|
-
**
|
368
|
+
** sqlite3_exec() after the error message string is no longer needed.
|
351
369
|
** ^If the 5th parameter to sqlite3_exec() is not NULL and no errors
|
352
370
|
** occur, then sqlite3_exec() sets the pointer in its 5th parameter to
|
353
371
|
** NULL before returning.
|
@@ -382,7 +400,7 @@ typedef int (*sqlite3_callback)(void*,int,char**, char**);
|
|
382
400
|
** the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running.
|
383
401
|
** </ul>
|
384
402
|
*/
|
385
|
-
SQLITE_API int
|
403
|
+
SQLITE_API int sqlite3_exec(
|
386
404
|
sqlite3*, /* An open database */
|
387
405
|
const char *sql, /* SQL to be evaluated */
|
388
406
|
int (*callback)(void*,int,char**,char**), /* Callback function */
|
@@ -403,7 +421,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_exec(
|
|
403
421
|
*/
|
404
422
|
#define SQLITE_OK 0 /* Successful result */
|
405
423
|
/* beginning-of-error-codes */
|
406
|
-
#define SQLITE_ERROR 1 /*
|
424
|
+
#define SQLITE_ERROR 1 /* Generic error */
|
407
425
|
#define SQLITE_INTERNAL 2 /* Internal logic error in SQLite */
|
408
426
|
#define SQLITE_PERM 3 /* Access permission denied */
|
409
427
|
#define SQLITE_ABORT 4 /* Callback routine requested an abort */
|
@@ -418,7 +436,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_exec(
|
|
418
436
|
#define SQLITE_FULL 13 /* Insertion failed because database is full */
|
419
437
|
#define SQLITE_CANTOPEN 14 /* Unable to open the database file */
|
420
438
|
#define SQLITE_PROTOCOL 15 /* Database lock protocol error */
|
421
|
-
#define SQLITE_EMPTY 16 /*
|
439
|
+
#define SQLITE_EMPTY 16 /* Internal use only */
|
422
440
|
#define SQLITE_SCHEMA 17 /* The database schema changed */
|
423
441
|
#define SQLITE_TOOBIG 18 /* String or BLOB exceeds size limit */
|
424
442
|
#define SQLITE_CONSTRAINT 19 /* Abort due to constraint violation */
|
@@ -426,7 +444,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_exec(
|
|
426
444
|
#define SQLITE_MISUSE 21 /* Library used incorrectly */
|
427
445
|
#define SQLITE_NOLFS 22 /* Uses OS features not supported on host */
|
428
446
|
#define SQLITE_AUTH 23 /* Authorization denied */
|
429
|
-
#define SQLITE_FORMAT 24 /*
|
447
|
+
#define SQLITE_FORMAT 24 /* Not used */
|
430
448
|
#define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */
|
431
449
|
#define SQLITE_NOTADB 26 /* File opened that is not a database file */
|
432
450
|
#define SQLITE_NOTICE 27 /* Notifications from sqlite3_log() */
|
@@ -443,7 +461,8 @@ SQLITE_API int SQLITE_STDCALL sqlite3_exec(
|
|
443
461
|
** [result codes]. However, experience has shown that many of
|
444
462
|
** these result codes are too coarse-grained. They do not provide as
|
445
463
|
** much information about problems as programmers might like. In an effort to
|
446
|
-
** address this, newer versions of SQLite (version 3.3.8
|
464
|
+
** address this, newer versions of SQLite (version 3.3.8 [dateof:3.3.8]
|
465
|
+
** and later) include
|
447
466
|
** support for additional result codes that provide more detailed information
|
448
467
|
** about errors. These [extended result codes] are enabled or disabled
|
449
468
|
** on a per database connection basis using the
|
@@ -478,6 +497,10 @@ SQLITE_API int SQLITE_STDCALL sqlite3_exec(
|
|
478
497
|
#define SQLITE_IOERR_GETTEMPPATH (SQLITE_IOERR | (25<<8))
|
479
498
|
#define SQLITE_IOERR_CONVPATH (SQLITE_IOERR | (26<<8))
|
480
499
|
#define SQLITE_IOERR_VNODE (SQLITE_IOERR | (27<<8))
|
500
|
+
#define SQLITE_IOERR_AUTH (SQLITE_IOERR | (28<<8))
|
501
|
+
#define SQLITE_IOERR_BEGIN_ATOMIC (SQLITE_IOERR | (29<<8))
|
502
|
+
#define SQLITE_IOERR_COMMIT_ATOMIC (SQLITE_IOERR | (30<<8))
|
503
|
+
#define SQLITE_IOERR_ROLLBACK_ATOMIC (SQLITE_IOERR | (31<<8))
|
481
504
|
#define SQLITE_LOCKED_SHAREDCACHE (SQLITE_LOCKED | (1<<8))
|
482
505
|
#define SQLITE_BUSY_RECOVERY (SQLITE_BUSY | (1<<8))
|
483
506
|
#define SQLITE_BUSY_SNAPSHOT (SQLITE_BUSY | (2<<8))
|
@@ -505,6 +528,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_exec(
|
|
505
528
|
#define SQLITE_NOTICE_RECOVER_ROLLBACK (SQLITE_NOTICE | (2<<8))
|
506
529
|
#define SQLITE_WARNING_AUTOINDEX (SQLITE_WARNING | (1<<8))
|
507
530
|
#define SQLITE_AUTH_USER (SQLITE_AUTH | (1<<8))
|
531
|
+
#define SQLITE_OK_LOAD_PERMANENTLY (SQLITE_OK | (1<<8))
|
508
532
|
|
509
533
|
/*
|
510
534
|
** CAPI3REF: Flags For File Open Operations
|
@@ -559,10 +583,15 @@ SQLITE_API int SQLITE_STDCALL sqlite3_exec(
|
|
559
583
|
** file that were written at the application level might have changed
|
560
584
|
** and that adjacent bytes, even bytes within the same sector are
|
561
585
|
** guaranteed to be unchanged. The SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN
|
562
|
-
** flag
|
586
|
+
** flag indicates that a file cannot be deleted when open. The
|
563
587
|
** SQLITE_IOCAP_IMMUTABLE flag indicates that the file is on
|
564
588
|
** read-only media and cannot be changed even by processes with
|
565
589
|
** elevated privileges.
|
590
|
+
**
|
591
|
+
** The SQLITE_IOCAP_BATCH_ATOMIC property means that the underlying
|
592
|
+
** filesystem supports doing multiple write operations atomically when those
|
593
|
+
** write operations are bracketed by [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] and
|
594
|
+
** [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE].
|
566
595
|
*/
|
567
596
|
#define SQLITE_IOCAP_ATOMIC 0x00000001
|
568
597
|
#define SQLITE_IOCAP_ATOMIC512 0x00000002
|
@@ -578,6 +607,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_exec(
|
|
578
607
|
#define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN 0x00000800
|
579
608
|
#define SQLITE_IOCAP_POWERSAFE_OVERWRITE 0x00001000
|
580
609
|
#define SQLITE_IOCAP_IMMUTABLE 0x00002000
|
610
|
+
#define SQLITE_IOCAP_BATCH_ATOMIC 0x00004000
|
581
611
|
|
582
612
|
/*
|
583
613
|
** CAPI3REF: File Locking Levels
|
@@ -709,6 +739,10 @@ struct sqlite3_file {
|
|
709
739
|
** <li> [SQLITE_IOCAP_ATOMIC64K]
|
710
740
|
** <li> [SQLITE_IOCAP_SAFE_APPEND]
|
711
741
|
** <li> [SQLITE_IOCAP_SEQUENTIAL]
|
742
|
+
** <li> [SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN]
|
743
|
+
** <li> [SQLITE_IOCAP_POWERSAFE_OVERWRITE]
|
744
|
+
** <li> [SQLITE_IOCAP_IMMUTABLE]
|
745
|
+
** <li> [SQLITE_IOCAP_BATCH_ATOMIC]
|
712
746
|
** </ul>
|
713
747
|
**
|
714
748
|
** The SQLITE_IOCAP_ATOMIC property means that all writes of
|
@@ -793,8 +827,13 @@ struct sqlite3_io_methods {
|
|
793
827
|
** <li>[[SQLITE_FCNTL_FILE_POINTER]]
|
794
828
|
** The [SQLITE_FCNTL_FILE_POINTER] opcode is used to obtain a pointer
|
795
829
|
** to the [sqlite3_file] object associated with a particular database
|
796
|
-
** connection. See
|
797
|
-
**
|
830
|
+
** connection. See also [SQLITE_FCNTL_JOURNAL_POINTER].
|
831
|
+
**
|
832
|
+
** <li>[[SQLITE_FCNTL_JOURNAL_POINTER]]
|
833
|
+
** The [SQLITE_FCNTL_JOURNAL_POINTER] opcode is used to obtain a pointer
|
834
|
+
** to the [sqlite3_file] object associated with the journal file (either
|
835
|
+
** the [rollback journal] or the [write-ahead log]) for a particular database
|
836
|
+
** connection. See also [SQLITE_FCNTL_FILE_POINTER].
|
798
837
|
**
|
799
838
|
** <li>[[SQLITE_FCNTL_SYNC_OMITTED]]
|
800
839
|
** No longer in use.
|
@@ -832,7 +871,7 @@ struct sqlite3_io_methods {
|
|
832
871
|
** opcode allows these two values (10 retries and 25 milliseconds of delay)
|
833
872
|
** to be adjusted. The values are changed for all database connections
|
834
873
|
** within the same process. The argument is a pointer to an array of two
|
835
|
-
** integers where the first integer
|
874
|
+
** integers where the first integer is the new retry count and the second
|
836
875
|
** integer is the delay. If either integer is negative, then the setting
|
837
876
|
** is not changed but instead the prior value of that setting is written
|
838
877
|
** into the array entry, allowing the current retry settings to be
|
@@ -881,6 +920,15 @@ struct sqlite3_io_methods {
|
|
881
920
|
** pointer in case this file-control is not implemented. This file-control
|
882
921
|
** is intended for diagnostic use only.
|
883
922
|
**
|
923
|
+
** <li>[[SQLITE_FCNTL_VFS_POINTER]]
|
924
|
+
** ^The [SQLITE_FCNTL_VFS_POINTER] opcode finds a pointer to the top-level
|
925
|
+
** [VFSes] currently in use. ^(The argument X in
|
926
|
+
** sqlite3_file_control(db,SQLITE_FCNTL_VFS_POINTER,X) must be
|
927
|
+
** of type "[sqlite3_vfs] **". This opcodes will set *X
|
928
|
+
** to a pointer to the top-level VFS.)^
|
929
|
+
** ^When there are multiple VFS shims in the stack, this opcode finds the
|
930
|
+
** upper-most shim only.
|
931
|
+
**
|
884
932
|
** <li>[[SQLITE_FCNTL_PRAGMA]]
|
885
933
|
** ^Whenever a [PRAGMA] statement is parsed, an [SQLITE_FCNTL_PRAGMA]
|
886
934
|
** file control is sent to the open [sqlite3_file] object corresponding
|
@@ -951,6 +999,12 @@ struct sqlite3_io_methods {
|
|
951
999
|
** on whether or not the file has been renamed, moved, or deleted since it
|
952
1000
|
** was first opened.
|
953
1001
|
**
|
1002
|
+
** <li>[[SQLITE_FCNTL_WIN32_GET_HANDLE]]
|
1003
|
+
** The [SQLITE_FCNTL_WIN32_GET_HANDLE] opcode can be used to obtain the
|
1004
|
+
** underlying native file handle associated with a file handle. This file
|
1005
|
+
** control interprets its argument as a pointer to a native file handle and
|
1006
|
+
** writes the resulting value there.
|
1007
|
+
**
|
954
1008
|
** <li>[[SQLITE_FCNTL_WIN32_SET_HANDLE]]
|
955
1009
|
** The [SQLITE_FCNTL_WIN32_SET_HANDLE] opcode is used for debugging. This
|
956
1010
|
** opcode causes the xFileControl method to swap the file handle with the one
|
@@ -972,6 +1026,40 @@ struct sqlite3_io_methods {
|
|
972
1026
|
** The [SQLITE_FCNTL_RBU] opcode is implemented by the special VFS used by
|
973
1027
|
** the RBU extension only. All other VFS should return SQLITE_NOTFOUND for
|
974
1028
|
** this opcode.
|
1029
|
+
**
|
1030
|
+
** <li>[[SQLITE_FCNTL_BEGIN_ATOMIC_WRITE]]
|
1031
|
+
** If the [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] opcode returns SQLITE_OK, then
|
1032
|
+
** the file descriptor is placed in "batch write mode", which
|
1033
|
+
** means all subsequent write operations will be deferred and done
|
1034
|
+
** atomically at the next [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE]. Systems
|
1035
|
+
** that do not support batch atomic writes will return SQLITE_NOTFOUND.
|
1036
|
+
** ^Following a successful SQLITE_FCNTL_BEGIN_ATOMIC_WRITE and prior to
|
1037
|
+
** the closing [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE] or
|
1038
|
+
** [SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE], SQLite will make
|
1039
|
+
** no VFS interface calls on the same [sqlite3_file] file descriptor
|
1040
|
+
** except for calls to the xWrite method and the xFileControl method
|
1041
|
+
** with [SQLITE_FCNTL_SIZE_HINT].
|
1042
|
+
**
|
1043
|
+
** <li>[[SQLITE_FCNTL_COMMIT_ATOMIC_WRITE]]
|
1044
|
+
** The [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE] opcode causes all write
|
1045
|
+
** operations since the previous successful call to
|
1046
|
+
** [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] to be performed atomically.
|
1047
|
+
** This file control returns [SQLITE_OK] if and only if the writes were
|
1048
|
+
** all performed successfully and have been committed to persistent storage.
|
1049
|
+
** ^Regardless of whether or not it is successful, this file control takes
|
1050
|
+
** the file descriptor out of batch write mode so that all subsequent
|
1051
|
+
** write operations are independent.
|
1052
|
+
** ^SQLite will never invoke SQLITE_FCNTL_COMMIT_ATOMIC_WRITE without
|
1053
|
+
** a prior successful call to [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE].
|
1054
|
+
**
|
1055
|
+
** <li>[[SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE]]
|
1056
|
+
** The [SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE] opcode causes all write
|
1057
|
+
** operations since the previous successful call to
|
1058
|
+
** [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] to be rolled back.
|
1059
|
+
** ^This file control takes the file descriptor out of batch write mode
|
1060
|
+
** so that all subsequent write operations are independent.
|
1061
|
+
** ^SQLite will never invoke SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE without
|
1062
|
+
** a prior successful call to [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE].
|
975
1063
|
** </ul>
|
976
1064
|
*/
|
977
1065
|
#define SQLITE_FCNTL_LOCKSTATE 1
|
@@ -999,6 +1087,13 @@ struct sqlite3_io_methods {
|
|
999
1087
|
#define SQLITE_FCNTL_WAL_BLOCK 24
|
1000
1088
|
#define SQLITE_FCNTL_ZIPVFS 25
|
1001
1089
|
#define SQLITE_FCNTL_RBU 26
|
1090
|
+
#define SQLITE_FCNTL_VFS_POINTER 27
|
1091
|
+
#define SQLITE_FCNTL_JOURNAL_POINTER 28
|
1092
|
+
#define SQLITE_FCNTL_WIN32_GET_HANDLE 29
|
1093
|
+
#define SQLITE_FCNTL_PDB 30
|
1094
|
+
#define SQLITE_FCNTL_BEGIN_ATOMIC_WRITE 31
|
1095
|
+
#define SQLITE_FCNTL_COMMIT_ATOMIC_WRITE 32
|
1096
|
+
#define SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE 33
|
1002
1097
|
|
1003
1098
|
/* deprecated names */
|
1004
1099
|
#define SQLITE_GET_LOCKPROXYFILE SQLITE_FCNTL_GET_LOCKPROXYFILE
|
@@ -1018,6 +1113,16 @@ struct sqlite3_io_methods {
|
|
1018
1113
|
*/
|
1019
1114
|
typedef struct sqlite3_mutex sqlite3_mutex;
|
1020
1115
|
|
1116
|
+
/*
|
1117
|
+
** CAPI3REF: Loadable Extension Thunk
|
1118
|
+
**
|
1119
|
+
** A pointer to the opaque sqlite3_api_routines structure is passed as
|
1120
|
+
** the third parameter to entry points of [loadable extensions]. This
|
1121
|
+
** structure must be typedefed in order to work around compiler warnings
|
1122
|
+
** on some platforms.
|
1123
|
+
*/
|
1124
|
+
typedef struct sqlite3_api_routines sqlite3_api_routines;
|
1125
|
+
|
1021
1126
|
/*
|
1022
1127
|
** CAPI3REF: OS Interface Object
|
1023
1128
|
**
|
@@ -1211,7 +1316,7 @@ struct sqlite3_vfs {
|
|
1211
1316
|
const char *(*xNextSystemCall)(sqlite3_vfs*, const char *zName);
|
1212
1317
|
/*
|
1213
1318
|
** The methods above are in versions 1 through 3 of the sqlite_vfs object.
|
1214
|
-
** New fields may be appended in
|
1319
|
+
** New fields may be appended in future versions. The iVersion
|
1215
1320
|
** value will increment whenever this happens.
|
1216
1321
|
*/
|
1217
1322
|
};
|
@@ -1353,10 +1458,10 @@ struct sqlite3_vfs {
|
|
1353
1458
|
** must return [SQLITE_OK] on success and some other [error code] upon
|
1354
1459
|
** failure.
|
1355
1460
|
*/
|
1356
|
-
SQLITE_API int
|
1357
|
-
SQLITE_API int
|
1358
|
-
SQLITE_API int
|
1359
|
-
SQLITE_API int
|
1461
|
+
SQLITE_API int sqlite3_initialize(void);
|
1462
|
+
SQLITE_API int sqlite3_shutdown(void);
|
1463
|
+
SQLITE_API int sqlite3_os_init(void);
|
1464
|
+
SQLITE_API int sqlite3_os_end(void);
|
1360
1465
|
|
1361
1466
|
/*
|
1362
1467
|
** CAPI3REF: Configuring The SQLite Library
|
@@ -1389,7 +1494,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_os_end(void);
|
|
1389
1494
|
** ^If the option is unknown or SQLite is unable to set the option
|
1390
1495
|
** then this routine returns a non-zero [error code].
|
1391
1496
|
*/
|
1392
|
-
SQLITE_API int
|
1497
|
+
SQLITE_API int sqlite3_config(int, ...);
|
1393
1498
|
|
1394
1499
|
/*
|
1395
1500
|
** CAPI3REF: Configure database connections
|
@@ -1408,7 +1513,7 @@ SQLITE_API int SQLITE_CDECL sqlite3_config(int, ...);
|
|
1408
1513
|
** ^Calls to sqlite3_db_config() return SQLITE_OK if and only if
|
1409
1514
|
** the call is considered successful.
|
1410
1515
|
*/
|
1411
|
-
SQLITE_API int
|
1516
|
+
SQLITE_API int sqlite3_db_config(sqlite3*, int op, ...);
|
1412
1517
|
|
1413
1518
|
/*
|
1414
1519
|
** CAPI3REF: Memory Allocation Routines
|
@@ -1559,6 +1664,16 @@ struct sqlite3_mem_methods {
|
|
1559
1664
|
** routines with a wrapper that simulations memory allocation failure or
|
1560
1665
|
** tracks memory usage, for example. </dd>
|
1561
1666
|
**
|
1667
|
+
** [[SQLITE_CONFIG_SMALL_MALLOC]] <dt>SQLITE_CONFIG_SMALL_MALLOC</dt>
|
1668
|
+
** <dd> ^The SQLITE_CONFIG_SMALL_MALLOC option takes single argument of
|
1669
|
+
** type int, interpreted as a boolean, which if true provides a hint to
|
1670
|
+
** SQLite that it should avoid large memory allocations if possible.
|
1671
|
+
** SQLite will run faster if it is free to make large memory allocations,
|
1672
|
+
** but some application might prefer to run slower in exchange for
|
1673
|
+
** guarantees about memory fragmentation that are possible if large
|
1674
|
+
** allocations are avoided. This hint is normally off.
|
1675
|
+
** </dd>
|
1676
|
+
**
|
1562
1677
|
** [[SQLITE_CONFIG_MEMSTATUS]] <dt>SQLITE_CONFIG_MEMSTATUS</dt>
|
1563
1678
|
** <dd> ^The SQLITE_CONFIG_MEMSTATUS option takes single argument of type int,
|
1564
1679
|
** interpreted as a boolean, which enables or disables the collection of
|
@@ -1576,57 +1691,43 @@ struct sqlite3_mem_methods {
|
|
1576
1691
|
** </dd>
|
1577
1692
|
**
|
1578
1693
|
** [[SQLITE_CONFIG_SCRATCH]] <dt>SQLITE_CONFIG_SCRATCH</dt>
|
1579
|
-
** <dd>
|
1580
|
-
** that SQLite can use for scratch memory. ^(There are three arguments
|
1581
|
-
** to SQLITE_CONFIG_SCRATCH: A pointer an 8-byte
|
1582
|
-
** aligned memory buffer from which the scratch allocations will be
|
1583
|
-
** drawn, the size of each scratch allocation (sz),
|
1584
|
-
** and the maximum number of scratch allocations (N).)^
|
1585
|
-
** The first argument must be a pointer to an 8-byte aligned buffer
|
1586
|
-
** of at least sz*N bytes of memory.
|
1587
|
-
** ^SQLite will not use more than one scratch buffers per thread.
|
1588
|
-
** ^SQLite will never request a scratch buffer that is more than 6
|
1589
|
-
** times the database page size.
|
1590
|
-
** ^If SQLite needs needs additional
|
1591
|
-
** scratch memory beyond what is provided by this configuration option, then
|
1592
|
-
** [sqlite3_malloc()] will be used to obtain the memory needed.<p>
|
1593
|
-
** ^When the application provides any amount of scratch memory using
|
1594
|
-
** SQLITE_CONFIG_SCRATCH, SQLite avoids unnecessary large
|
1595
|
-
** [sqlite3_malloc|heap allocations].
|
1596
|
-
** This can help [Robson proof|prevent memory allocation failures] due to heap
|
1597
|
-
** fragmentation in low-memory embedded systems.
|
1694
|
+
** <dd> The SQLITE_CONFIG_SCRATCH option is no longer used.
|
1598
1695
|
** </dd>
|
1599
1696
|
**
|
1600
1697
|
** [[SQLITE_CONFIG_PAGECACHE]] <dt>SQLITE_CONFIG_PAGECACHE</dt>
|
1601
|
-
** <dd> ^The SQLITE_CONFIG_PAGECACHE option specifies a
|
1698
|
+
** <dd> ^The SQLITE_CONFIG_PAGECACHE option specifies a memory pool
|
1602
1699
|
** that SQLite can use for the database page cache with the default page
|
1603
1700
|
** cache implementation.
|
1604
|
-
** This configuration
|
1605
|
-
** cache implementation is loaded using the [SQLITE_CONFIG_PCACHE2]
|
1606
|
-
** configuration option.
|
1701
|
+
** This configuration option is a no-op if an application-define page
|
1702
|
+
** cache implementation is loaded using the [SQLITE_CONFIG_PCACHE2].
|
1607
1703
|
** ^There are three arguments to SQLITE_CONFIG_PAGECACHE: A pointer to
|
1608
|
-
** 8-byte aligned
|
1609
|
-
**
|
1704
|
+
** 8-byte aligned memory (pMem), the size of each page cache line (sz),
|
1705
|
+
** and the number of cache lines (N).
|
1610
1706
|
** The sz argument should be the size of the largest database page
|
1611
1707
|
** (a power of two between 512 and 65536) plus some extra bytes for each
|
1612
1708
|
** page header. ^The number of extra bytes needed by the page header
|
1613
|
-
** can be determined using
|
1614
|
-
** to [sqlite3_config()].
|
1709
|
+
** can be determined using [SQLITE_CONFIG_PCACHE_HDRSZ].
|
1615
1710
|
** ^It is harmless, apart from the wasted memory,
|
1616
|
-
** for the sz parameter to be larger than necessary. The
|
1617
|
-
** argument
|
1618
|
-
**
|
1619
|
-
** undefined.
|
1620
|
-
** ^
|
1621
|
-
**
|
1622
|
-
** page cache
|
1623
|
-
**
|
1711
|
+
** for the sz parameter to be larger than necessary. The pMem
|
1712
|
+
** argument must be either a NULL pointer or a pointer to an 8-byte
|
1713
|
+
** aligned block of memory of at least sz*N bytes, otherwise
|
1714
|
+
** subsequent behavior is undefined.
|
1715
|
+
** ^When pMem is not NULL, SQLite will strive to use the memory provided
|
1716
|
+
** to satisfy page cache needs, falling back to [sqlite3_malloc()] if
|
1717
|
+
** a page cache line is larger than sz bytes or if all of the pMem buffer
|
1718
|
+
** is exhausted.
|
1719
|
+
** ^If pMem is NULL and N is non-zero, then each database connection
|
1720
|
+
** does an initial bulk allocation for page cache memory
|
1721
|
+
** from [sqlite3_malloc()] sufficient for N cache lines if N is positive or
|
1722
|
+
** of -1024*N bytes if N is negative, . ^If additional
|
1723
|
+
** page cache memory is needed beyond what is provided by the initial
|
1724
|
+
** allocation, then SQLite goes to [sqlite3_malloc()] separately for each
|
1725
|
+
** additional cache line. </dd>
|
1624
1726
|
**
|
1625
1727
|
** [[SQLITE_CONFIG_HEAP]] <dt>SQLITE_CONFIG_HEAP</dt>
|
1626
1728
|
** <dd> ^The SQLITE_CONFIG_HEAP option specifies a static memory buffer
|
1627
1729
|
** that SQLite will use for all of its dynamic memory allocation needs
|
1628
|
-
** beyond those provided for by [
|
1629
|
-
** [SQLITE_CONFIG_PAGECACHE].
|
1730
|
+
** beyond those provided for by [SQLITE_CONFIG_PAGECACHE].
|
1630
1731
|
** ^The SQLITE_CONFIG_HEAP option is only available if SQLite is compiled
|
1631
1732
|
** with either [SQLITE_ENABLE_MEMSYS3] or [SQLITE_ENABLE_MEMSYS5] and returns
|
1632
1733
|
** [SQLITE_ERROR] if invoked otherwise.
|
@@ -1798,6 +1899,20 @@ struct sqlite3_mem_methods {
|
|
1798
1899
|
** is enabled (using the [PRAGMA threads] command) and the amount of content
|
1799
1900
|
** to be sorted exceeds the page size times the minimum of the
|
1800
1901
|
** [PRAGMA cache_size] setting and this value.
|
1902
|
+
**
|
1903
|
+
** [[SQLITE_CONFIG_STMTJRNL_SPILL]]
|
1904
|
+
** <dt>SQLITE_CONFIG_STMTJRNL_SPILL
|
1905
|
+
** <dd>^The SQLITE_CONFIG_STMTJRNL_SPILL option takes a single parameter which
|
1906
|
+
** becomes the [statement journal] spill-to-disk threshold.
|
1907
|
+
** [Statement journals] are held in memory until their size (in bytes)
|
1908
|
+
** exceeds this threshold, at which point they are written to disk.
|
1909
|
+
** Or if the threshold is -1, statement journals are always held
|
1910
|
+
** exclusively in memory.
|
1911
|
+
** Since many statement journals never become large, setting the spill
|
1912
|
+
** threshold to a value such as 64KiB can greatly reduce the amount of
|
1913
|
+
** I/O required to support statement rollback.
|
1914
|
+
** The default value for this setting is controlled by the
|
1915
|
+
** [SQLITE_STMTJRNL_SPILL] compile-time option.
|
1801
1916
|
** </dl>
|
1802
1917
|
*/
|
1803
1918
|
#define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */
|
@@ -1805,7 +1920,7 @@ struct sqlite3_mem_methods {
|
|
1805
1920
|
#define SQLITE_CONFIG_SERIALIZED 3 /* nil */
|
1806
1921
|
#define SQLITE_CONFIG_MALLOC 4 /* sqlite3_mem_methods* */
|
1807
1922
|
#define SQLITE_CONFIG_GETMALLOC 5 /* sqlite3_mem_methods* */
|
1808
|
-
#define SQLITE_CONFIG_SCRATCH 6 /*
|
1923
|
+
#define SQLITE_CONFIG_SCRATCH 6 /* No longer used */
|
1809
1924
|
#define SQLITE_CONFIG_PAGECACHE 7 /* void*, int sz, int N */
|
1810
1925
|
#define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */
|
1811
1926
|
#define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */
|
@@ -1825,6 +1940,8 @@ struct sqlite3_mem_methods {
|
|
1825
1940
|
#define SQLITE_CONFIG_WIN32_HEAPSIZE 23 /* int nByte */
|
1826
1941
|
#define SQLITE_CONFIG_PCACHE_HDRSZ 24 /* int *psz */
|
1827
1942
|
#define SQLITE_CONFIG_PMASZ 25 /* unsigned int szPma */
|
1943
|
+
#define SQLITE_CONFIG_STMTJRNL_SPILL 26 /* int nByte */
|
1944
|
+
#define SQLITE_CONFIG_SMALL_MALLOC 27 /* boolean */
|
1828
1945
|
|
1829
1946
|
/*
|
1830
1947
|
** CAPI3REF: Database Connection Configuration Options
|
@@ -1882,11 +1999,78 @@ struct sqlite3_mem_methods {
|
|
1882
1999
|
** following this call. The second parameter may be a NULL pointer, in
|
1883
2000
|
** which case the trigger setting is not reported back. </dd>
|
1884
2001
|
**
|
2002
|
+
** <dt>SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER</dt>
|
2003
|
+
** <dd> ^This option is used to enable or disable the two-argument
|
2004
|
+
** version of the [fts3_tokenizer()] function which is part of the
|
2005
|
+
** [FTS3] full-text search engine extension.
|
2006
|
+
** There should be two additional arguments.
|
2007
|
+
** The first argument is an integer which is 0 to disable fts3_tokenizer() or
|
2008
|
+
** positive to enable fts3_tokenizer() or negative to leave the setting
|
2009
|
+
** unchanged.
|
2010
|
+
** The second parameter is a pointer to an integer into which
|
2011
|
+
** is written 0 or 1 to indicate whether fts3_tokenizer is disabled or enabled
|
2012
|
+
** following this call. The second parameter may be a NULL pointer, in
|
2013
|
+
** which case the new setting is not reported back. </dd>
|
2014
|
+
**
|
2015
|
+
** <dt>SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION</dt>
|
2016
|
+
** <dd> ^This option is used to enable or disable the [sqlite3_load_extension()]
|
2017
|
+
** interface independently of the [load_extension()] SQL function.
|
2018
|
+
** The [sqlite3_enable_load_extension()] API enables or disables both the
|
2019
|
+
** C-API [sqlite3_load_extension()] and the SQL function [load_extension()].
|
2020
|
+
** There should be two additional arguments.
|
2021
|
+
** When the first argument to this interface is 1, then only the C-API is
|
2022
|
+
** enabled and the SQL function remains disabled. If the first argument to
|
2023
|
+
** this interface is 0, then both the C-API and the SQL function are disabled.
|
2024
|
+
** If the first argument is -1, then no changes are made to state of either the
|
2025
|
+
** C-API or the SQL function.
|
2026
|
+
** The second parameter is a pointer to an integer into which
|
2027
|
+
** is written 0 or 1 to indicate whether [sqlite3_load_extension()] interface
|
2028
|
+
** is disabled or enabled following this call. The second parameter may
|
2029
|
+
** be a NULL pointer, in which case the new setting is not reported back.
|
2030
|
+
** </dd>
|
2031
|
+
**
|
2032
|
+
** <dt>SQLITE_DBCONFIG_MAINDBNAME</dt>
|
2033
|
+
** <dd> ^This option is used to change the name of the "main" database
|
2034
|
+
** schema. ^The sole argument is a pointer to a constant UTF8 string
|
2035
|
+
** which will become the new schema name in place of "main". ^SQLite
|
2036
|
+
** does not make a copy of the new main schema name string, so the application
|
2037
|
+
** must ensure that the argument passed into this DBCONFIG option is unchanged
|
2038
|
+
** until after the database connection closes.
|
2039
|
+
** </dd>
|
2040
|
+
**
|
2041
|
+
** <dt>SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE</dt>
|
2042
|
+
** <dd> Usually, when a database in wal mode is closed or detached from a
|
2043
|
+
** database handle, SQLite checks if this will mean that there are now no
|
2044
|
+
** connections at all to the database. If so, it performs a checkpoint
|
2045
|
+
** operation before closing the connection. This option may be used to
|
2046
|
+
** override this behaviour. The first parameter passed to this operation
|
2047
|
+
** is an integer - non-zero to disable checkpoints-on-close, or zero (the
|
2048
|
+
** default) to enable them. The second parameter is a pointer to an integer
|
2049
|
+
** into which is written 0 or 1 to indicate whether checkpoints-on-close
|
2050
|
+
** have been disabled - 0 if they are not disabled, 1 if they are.
|
2051
|
+
** </dd>
|
2052
|
+
**
|
2053
|
+
** <dt>SQLITE_DBCONFIG_ENABLE_QPSG</dt>
|
2054
|
+
** <dd>^(The SQLITE_DBCONFIG_ENABLE_QPSG option activates or deactivates
|
2055
|
+
** the [query planner stability guarantee] (QPSG). When the QPSG is active,
|
2056
|
+
** a single SQL query statement will always use the same algorithm regardless
|
2057
|
+
** of values of [bound parameters].)^ The QPSG disables some query optimizations
|
2058
|
+
** that look at the values of bound parameters, which can make some queries
|
2059
|
+
** slower. But the QPSG has the advantage of more predictable behavior. With
|
2060
|
+
** the QPSG active, SQLite will always use the same query plan in the field as
|
2061
|
+
** was used during testing in the lab.
|
2062
|
+
** </dd>
|
2063
|
+
**
|
1885
2064
|
** </dl>
|
1886
2065
|
*/
|
1887
|
-
#define
|
1888
|
-
#define
|
1889
|
-
#define
|
2066
|
+
#define SQLITE_DBCONFIG_MAINDBNAME 1000 /* const char* */
|
2067
|
+
#define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */
|
2068
|
+
#define SQLITE_DBCONFIG_ENABLE_FKEY 1002 /* int int* */
|
2069
|
+
#define SQLITE_DBCONFIG_ENABLE_TRIGGER 1003 /* int int* */
|
2070
|
+
#define SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER 1004 /* int int* */
|
2071
|
+
#define SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION 1005 /* int int* */
|
2072
|
+
#define SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE 1006 /* int int* */
|
2073
|
+
#define SQLITE_DBCONFIG_ENABLE_QPSG 1007 /* int int* */
|
1890
2074
|
|
1891
2075
|
|
1892
2076
|
/*
|
@@ -1897,7 +2081,7 @@ struct sqlite3_mem_methods {
|
|
1897
2081
|
** [extended result codes] feature of SQLite. ^The extended result
|
1898
2082
|
** codes are disabled by default for historical compatibility.
|
1899
2083
|
*/
|
1900
|
-
SQLITE_API int
|
2084
|
+
SQLITE_API int sqlite3_extended_result_codes(sqlite3*, int onoff);
|
1901
2085
|
|
1902
2086
|
/*
|
1903
2087
|
** CAPI3REF: Last Insert Rowid
|
@@ -1911,20 +2095,30 @@ SQLITE_API int SQLITE_STDCALL sqlite3_extended_result_codes(sqlite3*, int onoff)
|
|
1911
2095
|
** the table has a column of type [INTEGER PRIMARY KEY] then that column
|
1912
2096
|
** is another alias for the rowid.
|
1913
2097
|
**
|
1914
|
-
** ^The sqlite3_last_insert_rowid(D) interface returns the [rowid] of
|
1915
|
-
** most recent successful [INSERT] into a rowid table or [virtual table]
|
1916
|
-
** on database connection D.
|
1917
|
-
** ^
|
1918
|
-
**
|
1919
|
-
**
|
1920
|
-
**
|
1921
|
-
**
|
1922
|
-
**
|
1923
|
-
**
|
1924
|
-
**
|
1925
|
-
**
|
1926
|
-
**
|
1927
|
-
**
|
2098
|
+
** ^The sqlite3_last_insert_rowid(D) interface usually returns the [rowid] of
|
2099
|
+
** the most recent successful [INSERT] into a rowid table or [virtual table]
|
2100
|
+
** on database connection D. ^Inserts into [WITHOUT ROWID] tables are not
|
2101
|
+
** recorded. ^If no successful [INSERT]s into rowid tables have ever occurred
|
2102
|
+
** on the database connection D, then sqlite3_last_insert_rowid(D) returns
|
2103
|
+
** zero.
|
2104
|
+
**
|
2105
|
+
** As well as being set automatically as rows are inserted into database
|
2106
|
+
** tables, the value returned by this function may be set explicitly by
|
2107
|
+
** [sqlite3_set_last_insert_rowid()]
|
2108
|
+
**
|
2109
|
+
** Some virtual table implementations may INSERT rows into rowid tables as
|
2110
|
+
** part of committing a transaction (e.g. to flush data accumulated in memory
|
2111
|
+
** to disk). In this case subsequent calls to this function return the rowid
|
2112
|
+
** associated with these internal INSERT operations, which leads to
|
2113
|
+
** unintuitive results. Virtual table implementations that do write to rowid
|
2114
|
+
** tables in this way can avoid this problem by restoring the original
|
2115
|
+
** rowid value using [sqlite3_set_last_insert_rowid()] before returning
|
2116
|
+
** control to the user.
|
2117
|
+
**
|
2118
|
+
** ^(If an [INSERT] occurs within a trigger then this routine will
|
2119
|
+
** return the [rowid] of the inserted row as long as the trigger is
|
2120
|
+
** running. Once the trigger program ends, the value returned
|
2121
|
+
** by this routine reverts to what it was before the trigger was fired.)^
|
1928
2122
|
**
|
1929
2123
|
** ^An [INSERT] that fails due to a constraint violation is not a
|
1930
2124
|
** successful [INSERT] and does not change the value returned by this
|
@@ -1949,7 +2143,17 @@ SQLITE_API int SQLITE_STDCALL sqlite3_extended_result_codes(sqlite3*, int onoff)
|
|
1949
2143
|
** unpredictable and might not equal either the old or the new
|
1950
2144
|
** last insert [rowid].
|
1951
2145
|
*/
|
1952
|
-
SQLITE_API sqlite3_int64
|
2146
|
+
SQLITE_API sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
|
2147
|
+
|
2148
|
+
/*
|
2149
|
+
** CAPI3REF: Set the Last Insert Rowid value.
|
2150
|
+
** METHOD: sqlite3
|
2151
|
+
**
|
2152
|
+
** The sqlite3_set_last_insert_rowid(D, R) method allows the application to
|
2153
|
+
** set the value returned by calling sqlite3_last_insert_rowid(D) to R
|
2154
|
+
** without inserting a row into the database.
|
2155
|
+
*/
|
2156
|
+
SQLITE_API void sqlite3_set_last_insert_rowid(sqlite3*,sqlite3_int64);
|
1953
2157
|
|
1954
2158
|
/*
|
1955
2159
|
** CAPI3REF: Count The Number Of Rows Modified
|
@@ -2002,7 +2206,7 @@ SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_last_insert_rowid(sqlite3*);
|
|
2002
2206
|
** while [sqlite3_changes()] is running then the value returned
|
2003
2207
|
** is unpredictable and not meaningful.
|
2004
2208
|
*/
|
2005
|
-
SQLITE_API int
|
2209
|
+
SQLITE_API int sqlite3_changes(sqlite3*);
|
2006
2210
|
|
2007
2211
|
/*
|
2008
2212
|
** CAPI3REF: Total Number Of Rows Modified
|
@@ -2026,7 +2230,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_changes(sqlite3*);
|
|
2026
2230
|
** while [sqlite3_total_changes()] is running then the value
|
2027
2231
|
** returned is unpredictable and not meaningful.
|
2028
2232
|
*/
|
2029
|
-
SQLITE_API int
|
2233
|
+
SQLITE_API int sqlite3_total_changes(sqlite3*);
|
2030
2234
|
|
2031
2235
|
/*
|
2032
2236
|
** CAPI3REF: Interrupt A Long-Running Query
|
@@ -2062,11 +2266,8 @@ SQLITE_API int SQLITE_STDCALL sqlite3_total_changes(sqlite3*);
|
|
2062
2266
|
** ^A call to sqlite3_interrupt(D) that occurs when there are no running
|
2063
2267
|
** SQL statements is a no-op and has no effect on SQL statements
|
2064
2268
|
** that are started after the sqlite3_interrupt() call returns.
|
2065
|
-
**
|
2066
|
-
** If the database connection closes while [sqlite3_interrupt()]
|
2067
|
-
** is running then bad things will likely happen.
|
2068
2269
|
*/
|
2069
|
-
SQLITE_API void
|
2270
|
+
SQLITE_API void sqlite3_interrupt(sqlite3*);
|
2070
2271
|
|
2071
2272
|
/*
|
2072
2273
|
** CAPI3REF: Determine If An SQL Statement Is Complete
|
@@ -2101,8 +2302,8 @@ SQLITE_API void SQLITE_STDCALL sqlite3_interrupt(sqlite3*);
|
|
2101
2302
|
** The input to [sqlite3_complete16()] must be a zero-terminated
|
2102
2303
|
** UTF-16 string in native byte order.
|
2103
2304
|
*/
|
2104
|
-
SQLITE_API int
|
2105
|
-
SQLITE_API int
|
2305
|
+
SQLITE_API int sqlite3_complete(const char *sql);
|
2306
|
+
SQLITE_API int sqlite3_complete16(const void *sql);
|
2106
2307
|
|
2107
2308
|
/*
|
2108
2309
|
** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors
|
@@ -2163,7 +2364,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_complete16(const void *sql);
|
|
2163
2364
|
** A busy handler must not close the database connection
|
2164
2365
|
** or [prepared statement] that invoked the busy handler.
|
2165
2366
|
*/
|
2166
|
-
SQLITE_API int
|
2367
|
+
SQLITE_API int sqlite3_busy_handler(sqlite3*,int(*)(void*,int),void*);
|
2167
2368
|
|
2168
2369
|
/*
|
2169
2370
|
** CAPI3REF: Set A Busy Timeout
|
@@ -2186,7 +2387,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_busy_handler(sqlite3*, int(*)(void*,int),
|
|
2186
2387
|
**
|
2187
2388
|
** See also: [PRAGMA busy_timeout]
|
2188
2389
|
*/
|
2189
|
-
SQLITE_API int
|
2390
|
+
SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms);
|
2190
2391
|
|
2191
2392
|
/*
|
2192
2393
|
** CAPI3REF: Convenience Routines For Running Queries
|
@@ -2261,7 +2462,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_busy_timeout(sqlite3*, int ms);
|
|
2261
2462
|
** reflected in subsequent calls to [sqlite3_errcode()] or
|
2262
2463
|
** [sqlite3_errmsg()].
|
2263
2464
|
*/
|
2264
|
-
SQLITE_API int
|
2465
|
+
SQLITE_API int sqlite3_get_table(
|
2265
2466
|
sqlite3 *db, /* An open database */
|
2266
2467
|
const char *zSql, /* SQL to be evaluated */
|
2267
2468
|
char ***pazResult, /* Results of the query */
|
@@ -2269,7 +2470,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_get_table(
|
|
2269
2470
|
int *pnColumn, /* Number of result columns written here */
|
2270
2471
|
char **pzErrmsg /* Error msg written here */
|
2271
2472
|
);
|
2272
|
-
SQLITE_API void
|
2473
|
+
SQLITE_API void sqlite3_free_table(char **result);
|
2273
2474
|
|
2274
2475
|
/*
|
2275
2476
|
** CAPI3REF: Formatted String Printing Functions
|
@@ -2375,10 +2576,10 @@ SQLITE_API void SQLITE_STDCALL sqlite3_free_table(char **result);
|
|
2375
2576
|
** addition that after the string has been read and copied into
|
2376
2577
|
** the result, [sqlite3_free()] is called on the input string.)^
|
2377
2578
|
*/
|
2378
|
-
SQLITE_API char *
|
2379
|
-
SQLITE_API char *
|
2380
|
-
SQLITE_API char *
|
2381
|
-
SQLITE_API char *
|
2579
|
+
SQLITE_API char *sqlite3_mprintf(const char*,...);
|
2580
|
+
SQLITE_API char *sqlite3_vmprintf(const char*, va_list);
|
2581
|
+
SQLITE_API char *sqlite3_snprintf(int,char*,const char*, ...);
|
2582
|
+
SQLITE_API char *sqlite3_vsnprintf(int,char*,const char*, va_list);
|
2382
2583
|
|
2383
2584
|
/*
|
2384
2585
|
** CAPI3REF: Memory Allocation Subsystem
|
@@ -2468,12 +2669,12 @@ SQLITE_API char *SQLITE_STDCALL sqlite3_vsnprintf(int,char*,const char*, va_list
|
|
2468
2669
|
** a block of memory after it has been released using
|
2469
2670
|
** [sqlite3_free()] or [sqlite3_realloc()].
|
2470
2671
|
*/
|
2471
|
-
SQLITE_API void *
|
2472
|
-
SQLITE_API void *
|
2473
|
-
SQLITE_API void *
|
2474
|
-
SQLITE_API void *
|
2475
|
-
SQLITE_API void
|
2476
|
-
SQLITE_API sqlite3_uint64
|
2672
|
+
SQLITE_API void *sqlite3_malloc(int);
|
2673
|
+
SQLITE_API void *sqlite3_malloc64(sqlite3_uint64);
|
2674
|
+
SQLITE_API void *sqlite3_realloc(void*, int);
|
2675
|
+
SQLITE_API void *sqlite3_realloc64(void*, sqlite3_uint64);
|
2676
|
+
SQLITE_API void sqlite3_free(void*);
|
2677
|
+
SQLITE_API sqlite3_uint64 sqlite3_msize(void*);
|
2477
2678
|
|
2478
2679
|
/*
|
2479
2680
|
** CAPI3REF: Memory Allocator Statistics
|
@@ -2498,8 +2699,8 @@ SQLITE_API sqlite3_uint64 SQLITE_STDCALL sqlite3_msize(void*);
|
|
2498
2699
|
** by [sqlite3_memory_highwater(1)] is the high-water mark
|
2499
2700
|
** prior to the reset.
|
2500
2701
|
*/
|
2501
|
-
SQLITE_API sqlite3_int64
|
2502
|
-
SQLITE_API sqlite3_int64
|
2702
|
+
SQLITE_API sqlite3_int64 sqlite3_memory_used(void);
|
2703
|
+
SQLITE_API sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
|
2503
2704
|
|
2504
2705
|
/*
|
2505
2706
|
** CAPI3REF: Pseudo-Random Number Generator
|
@@ -2522,17 +2723,19 @@ SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_memory_highwater(int resetFlag);
|
|
2522
2723
|
** internally and without recourse to the [sqlite3_vfs] xRandomness
|
2523
2724
|
** method.
|
2524
2725
|
*/
|
2525
|
-
SQLITE_API void
|
2726
|
+
SQLITE_API void sqlite3_randomness(int N, void *P);
|
2526
2727
|
|
2527
2728
|
/*
|
2528
2729
|
** CAPI3REF: Compile-Time Authorization Callbacks
|
2529
2730
|
** METHOD: sqlite3
|
2731
|
+
** KEYWORDS: {authorizer callback}
|
2530
2732
|
**
|
2531
2733
|
** ^This routine registers an authorizer callback with a particular
|
2532
2734
|
** [database connection], supplied in the first argument.
|
2533
2735
|
** ^The authorizer callback is invoked as SQL statements are being compiled
|
2534
2736
|
** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()],
|
2535
|
-
** [sqlite3_prepare16()]
|
2737
|
+
** [sqlite3_prepare_v3()], [sqlite3_prepare16()], [sqlite3_prepare16_v2()],
|
2738
|
+
** and [sqlite3_prepare16_v3()]. ^At various
|
2536
2739
|
** points during the compilation process, as logic is being created
|
2537
2740
|
** to perform various actions, the authorizer callback is invoked to
|
2538
2741
|
** see if those actions are allowed. ^The authorizer callback should
|
@@ -2554,8 +2757,10 @@ SQLITE_API void SQLITE_STDCALL sqlite3_randomness(int N, void *P);
|
|
2554
2757
|
** parameter to the sqlite3_set_authorizer() interface. ^The second parameter
|
2555
2758
|
** to the callback is an integer [SQLITE_COPY | action code] that specifies
|
2556
2759
|
** the particular action to be authorized. ^The third through sixth parameters
|
2557
|
-
** to the callback are zero-terminated strings
|
2558
|
-
** details about the action to be authorized.
|
2760
|
+
** to the callback are either NULL pointers or zero-terminated strings
|
2761
|
+
** that contain additional details about the action to be authorized.
|
2762
|
+
** Applications must always be prepared to encounter a NULL pointer in any
|
2763
|
+
** of the third through the sixth parameters of the authorization callback.
|
2559
2764
|
**
|
2560
2765
|
** ^If the action code is [SQLITE_READ]
|
2561
2766
|
** and the callback returns [SQLITE_IGNORE] then the
|
@@ -2564,6 +2769,10 @@ SQLITE_API void SQLITE_STDCALL sqlite3_randomness(int N, void *P);
|
|
2564
2769
|
** been read if [SQLITE_OK] had been returned. The [SQLITE_IGNORE]
|
2565
2770
|
** return can be used to deny an untrusted user access to individual
|
2566
2771
|
** columns of a table.
|
2772
|
+
** ^When a table is referenced by a [SELECT] but no column values are
|
2773
|
+
** extracted from that table (for example in a query like
|
2774
|
+
** "SELECT count(*) FROM tab") then the [SQLITE_READ] authorizer callback
|
2775
|
+
** is invoked once for that table with a column name that is an empty string.
|
2567
2776
|
** ^If the action code is [SQLITE_DELETE] and the callback returns
|
2568
2777
|
** [SQLITE_IGNORE] then the [DELETE] operation proceeds but the
|
2569
2778
|
** [truncate optimization] is disabled and all rows are deleted individually.
|
@@ -2605,7 +2814,7 @@ SQLITE_API void SQLITE_STDCALL sqlite3_randomness(int N, void *P);
|
|
2605
2814
|
** as stated in the previous paragraph, sqlite3_step() invokes
|
2606
2815
|
** sqlite3_prepare_v2() to reprepare a statement after a schema change.
|
2607
2816
|
*/
|
2608
|
-
SQLITE_API int
|
2817
|
+
SQLITE_API int sqlite3_set_authorizer(
|
2609
2818
|
sqlite3*,
|
2610
2819
|
int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
|
2611
2820
|
void *pUserData
|
@@ -2685,6 +2894,9 @@ SQLITE_API int SQLITE_STDCALL sqlite3_set_authorizer(
|
|
2685
2894
|
** CAPI3REF: Tracing And Profiling Functions
|
2686
2895
|
** METHOD: sqlite3
|
2687
2896
|
**
|
2897
|
+
** These routines are deprecated. Use the [sqlite3_trace_v2()] interface
|
2898
|
+
** instead of the routines described here.
|
2899
|
+
**
|
2688
2900
|
** These routines register callback functions that can be used for
|
2689
2901
|
** tracing and profiling the execution of SQL statements.
|
2690
2902
|
**
|
@@ -2710,10 +2922,104 @@ SQLITE_API int SQLITE_STDCALL sqlite3_set_authorizer(
|
|
2710
2922
|
** sqlite3_profile() function is considered experimental and is
|
2711
2923
|
** subject to change in future versions of SQLite.
|
2712
2924
|
*/
|
2713
|
-
SQLITE_API void *
|
2714
|
-
|
2925
|
+
SQLITE_API SQLITE_DEPRECATED void *sqlite3_trace(sqlite3*,
|
2926
|
+
void(*xTrace)(void*,const char*), void*);
|
2927
|
+
SQLITE_API SQLITE_DEPRECATED void *sqlite3_profile(sqlite3*,
|
2715
2928
|
void(*xProfile)(void*,const char*,sqlite3_uint64), void*);
|
2716
2929
|
|
2930
|
+
/*
|
2931
|
+
** CAPI3REF: SQL Trace Event Codes
|
2932
|
+
** KEYWORDS: SQLITE_TRACE
|
2933
|
+
**
|
2934
|
+
** These constants identify classes of events that can be monitored
|
2935
|
+
** using the [sqlite3_trace_v2()] tracing logic. The third argument
|
2936
|
+
** to [sqlite3_trace_v2()] is an OR-ed combination of one or more of
|
2937
|
+
** the following constants. ^The first argument to the trace callback
|
2938
|
+
** is one of the following constants.
|
2939
|
+
**
|
2940
|
+
** New tracing constants may be added in future releases.
|
2941
|
+
**
|
2942
|
+
** ^A trace callback has four arguments: xCallback(T,C,P,X).
|
2943
|
+
** ^The T argument is one of the integer type codes above.
|
2944
|
+
** ^The C argument is a copy of the context pointer passed in as the
|
2945
|
+
** fourth argument to [sqlite3_trace_v2()].
|
2946
|
+
** The P and X arguments are pointers whose meanings depend on T.
|
2947
|
+
**
|
2948
|
+
** <dl>
|
2949
|
+
** [[SQLITE_TRACE_STMT]] <dt>SQLITE_TRACE_STMT</dt>
|
2950
|
+
** <dd>^An SQLITE_TRACE_STMT callback is invoked when a prepared statement
|
2951
|
+
** first begins running and possibly at other times during the
|
2952
|
+
** execution of the prepared statement, such as at the start of each
|
2953
|
+
** trigger subprogram. ^The P argument is a pointer to the
|
2954
|
+
** [prepared statement]. ^The X argument is a pointer to a string which
|
2955
|
+
** is the unexpanded SQL text of the prepared statement or an SQL comment
|
2956
|
+
** that indicates the invocation of a trigger. ^The callback can compute
|
2957
|
+
** the same text that would have been returned by the legacy [sqlite3_trace()]
|
2958
|
+
** interface by using the X argument when X begins with "--" and invoking
|
2959
|
+
** [sqlite3_expanded_sql(P)] otherwise.
|
2960
|
+
**
|
2961
|
+
** [[SQLITE_TRACE_PROFILE]] <dt>SQLITE_TRACE_PROFILE</dt>
|
2962
|
+
** <dd>^An SQLITE_TRACE_PROFILE callback provides approximately the same
|
2963
|
+
** information as is provided by the [sqlite3_profile()] callback.
|
2964
|
+
** ^The P argument is a pointer to the [prepared statement] and the
|
2965
|
+
** X argument points to a 64-bit integer which is the estimated of
|
2966
|
+
** the number of nanosecond that the prepared statement took to run.
|
2967
|
+
** ^The SQLITE_TRACE_PROFILE callback is invoked when the statement finishes.
|
2968
|
+
**
|
2969
|
+
** [[SQLITE_TRACE_ROW]] <dt>SQLITE_TRACE_ROW</dt>
|
2970
|
+
** <dd>^An SQLITE_TRACE_ROW callback is invoked whenever a prepared
|
2971
|
+
** statement generates a single row of result.
|
2972
|
+
** ^The P argument is a pointer to the [prepared statement] and the
|
2973
|
+
** X argument is unused.
|
2974
|
+
**
|
2975
|
+
** [[SQLITE_TRACE_CLOSE]] <dt>SQLITE_TRACE_CLOSE</dt>
|
2976
|
+
** <dd>^An SQLITE_TRACE_CLOSE callback is invoked when a database
|
2977
|
+
** connection closes.
|
2978
|
+
** ^The P argument is a pointer to the [database connection] object
|
2979
|
+
** and the X argument is unused.
|
2980
|
+
** </dl>
|
2981
|
+
*/
|
2982
|
+
#define SQLITE_TRACE_STMT 0x01
|
2983
|
+
#define SQLITE_TRACE_PROFILE 0x02
|
2984
|
+
#define SQLITE_TRACE_ROW 0x04
|
2985
|
+
#define SQLITE_TRACE_CLOSE 0x08
|
2986
|
+
|
2987
|
+
/*
|
2988
|
+
** CAPI3REF: SQL Trace Hook
|
2989
|
+
** METHOD: sqlite3
|
2990
|
+
**
|
2991
|
+
** ^The sqlite3_trace_v2(D,M,X,P) interface registers a trace callback
|
2992
|
+
** function X against [database connection] D, using property mask M
|
2993
|
+
** and context pointer P. ^If the X callback is
|
2994
|
+
** NULL or if the M mask is zero, then tracing is disabled. The
|
2995
|
+
** M argument should be the bitwise OR-ed combination of
|
2996
|
+
** zero or more [SQLITE_TRACE] constants.
|
2997
|
+
**
|
2998
|
+
** ^Each call to either sqlite3_trace() or sqlite3_trace_v2() overrides
|
2999
|
+
** (cancels) any prior calls to sqlite3_trace() or sqlite3_trace_v2().
|
3000
|
+
**
|
3001
|
+
** ^The X callback is invoked whenever any of the events identified by
|
3002
|
+
** mask M occur. ^The integer return value from the callback is currently
|
3003
|
+
** ignored, though this may change in future releases. Callback
|
3004
|
+
** implementations should return zero to ensure future compatibility.
|
3005
|
+
**
|
3006
|
+
** ^A trace callback is invoked with four arguments: callback(T,C,P,X).
|
3007
|
+
** ^The T argument is one of the [SQLITE_TRACE]
|
3008
|
+
** constants to indicate why the callback was invoked.
|
3009
|
+
** ^The C argument is a copy of the context pointer.
|
3010
|
+
** The P and X arguments are pointers whose meanings depend on T.
|
3011
|
+
**
|
3012
|
+
** The sqlite3_trace_v2() interface is intended to replace the legacy
|
3013
|
+
** interfaces [sqlite3_trace()] and [sqlite3_profile()], both of which
|
3014
|
+
** are deprecated.
|
3015
|
+
*/
|
3016
|
+
SQLITE_API int sqlite3_trace_v2(
|
3017
|
+
sqlite3*,
|
3018
|
+
unsigned uMask,
|
3019
|
+
int(*xCallback)(unsigned,void*,void*,void*),
|
3020
|
+
void *pCtx
|
3021
|
+
);
|
3022
|
+
|
2717
3023
|
/*
|
2718
3024
|
** CAPI3REF: Query Progress Callbacks
|
2719
3025
|
** METHOD: sqlite3
|
@@ -2746,7 +3052,7 @@ SQLITE_API SQLITE_EXPERIMENTAL void *SQLITE_STDCALL sqlite3_profile(sqlite3*,
|
|
2746
3052
|
** database connections for the meaning of "modify" in this paragraph.
|
2747
3053
|
**
|
2748
3054
|
*/
|
2749
|
-
SQLITE_API void
|
3055
|
+
SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
|
2750
3056
|
|
2751
3057
|
/*
|
2752
3058
|
** CAPI3REF: Opening A New Database Connection
|
@@ -2836,10 +3142,10 @@ SQLITE_API void SQLITE_STDCALL sqlite3_progress_handler(sqlite3*, int, int(*)(vo
|
|
2836
3142
|
** ^If [URI filename] interpretation is enabled, and the filename argument
|
2837
3143
|
** begins with "file:", then the filename is interpreted as a URI. ^URI
|
2838
3144
|
** filename interpretation is enabled if the [SQLITE_OPEN_URI] flag is
|
2839
|
-
** set in the
|
3145
|
+
** set in the third argument to sqlite3_open_v2(), or if it has
|
2840
3146
|
** been enabled globally using the [SQLITE_CONFIG_URI] option with the
|
2841
3147
|
** [sqlite3_config()] method or by the [SQLITE_USE_URI] compile-time option.
|
2842
|
-
**
|
3148
|
+
** URI filename interpretation is turned off
|
2843
3149
|
** by default, but future releases of SQLite might enable URI filename
|
2844
3150
|
** interpretation by default. See "[URI filenames]" for additional
|
2845
3151
|
** information.
|
@@ -2975,15 +3281,15 @@ SQLITE_API void SQLITE_STDCALL sqlite3_progress_handler(sqlite3*, int, int(*)(vo
|
|
2975
3281
|
**
|
2976
3282
|
** See also: [sqlite3_temp_directory]
|
2977
3283
|
*/
|
2978
|
-
SQLITE_API int
|
3284
|
+
SQLITE_API int sqlite3_open(
|
2979
3285
|
const char *filename, /* Database filename (UTF-8) */
|
2980
3286
|
sqlite3 **ppDb /* OUT: SQLite db handle */
|
2981
3287
|
);
|
2982
|
-
SQLITE_API int
|
3288
|
+
SQLITE_API int sqlite3_open16(
|
2983
3289
|
const void *filename, /* Database filename (UTF-16) */
|
2984
3290
|
sqlite3 **ppDb /* OUT: SQLite db handle */
|
2985
3291
|
);
|
2986
|
-
SQLITE_API int
|
3292
|
+
SQLITE_API int sqlite3_open_v2(
|
2987
3293
|
const char *filename, /* Database filename (UTF-8) */
|
2988
3294
|
sqlite3 **ppDb, /* OUT: SQLite db handle */
|
2989
3295
|
int flags, /* Flags */
|
@@ -3029,9 +3335,9 @@ SQLITE_API int SQLITE_STDCALL sqlite3_open_v2(
|
|
3029
3335
|
** VFS method, then the behavior of this routine is undefined and probably
|
3030
3336
|
** undesirable.
|
3031
3337
|
*/
|
3032
|
-
SQLITE_API const char *
|
3033
|
-
SQLITE_API int
|
3034
|
-
SQLITE_API sqlite3_int64
|
3338
|
+
SQLITE_API const char *sqlite3_uri_parameter(const char *zFilename, const char *zParam);
|
3339
|
+
SQLITE_API int sqlite3_uri_boolean(const char *zFile, const char *zParam, int bDefault);
|
3340
|
+
SQLITE_API sqlite3_int64 sqlite3_uri_int64(const char*, const char*, sqlite3_int64);
|
3035
3341
|
|
3036
3342
|
|
3037
3343
|
/*
|
@@ -3075,11 +3381,11 @@ SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_uri_int64(const char*, const cha
|
|
3075
3381
|
** was invoked incorrectly by the application. In that case, the
|
3076
3382
|
** error code and message may or may not be set.
|
3077
3383
|
*/
|
3078
|
-
SQLITE_API int
|
3079
|
-
SQLITE_API int
|
3080
|
-
SQLITE_API const char *
|
3081
|
-
SQLITE_API const void *
|
3082
|
-
SQLITE_API const char *
|
3384
|
+
SQLITE_API int sqlite3_errcode(sqlite3 *db);
|
3385
|
+
SQLITE_API int sqlite3_extended_errcode(sqlite3 *db);
|
3386
|
+
SQLITE_API const char *sqlite3_errmsg(sqlite3*);
|
3387
|
+
SQLITE_API const void *sqlite3_errmsg16(sqlite3*);
|
3388
|
+
SQLITE_API const char *sqlite3_errstr(int);
|
3083
3389
|
|
3084
3390
|
/*
|
3085
3391
|
** CAPI3REF: Prepared Statement Object
|
@@ -3147,7 +3453,7 @@ typedef struct sqlite3_stmt sqlite3_stmt;
|
|
3147
3453
|
**
|
3148
3454
|
** New run-time limit categories may be added in future releases.
|
3149
3455
|
*/
|
3150
|
-
SQLITE_API int
|
3456
|
+
SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal);
|
3151
3457
|
|
3152
3458
|
/*
|
3153
3459
|
** CAPI3REF: Run-Time Limit Categories
|
@@ -3178,9 +3484,9 @@ SQLITE_API int SQLITE_STDCALL sqlite3_limit(sqlite3*, int id, int newVal);
|
|
3178
3484
|
**
|
3179
3485
|
** [[SQLITE_LIMIT_VDBE_OP]] ^(<dt>SQLITE_LIMIT_VDBE_OP</dt>
|
3180
3486
|
** <dd>The maximum number of instructions in a virtual machine program
|
3181
|
-
** used to implement an SQL statement.
|
3182
|
-
**
|
3183
|
-
**
|
3487
|
+
** used to implement an SQL statement. If [sqlite3_prepare_v2()] or
|
3488
|
+
** the equivalent tries to allocate space for more than this many opcodes
|
3489
|
+
** in a single prepared statement, an SQLITE_NOMEM error is returned.</dd>)^
|
3184
3490
|
**
|
3185
3491
|
** [[SQLITE_LIMIT_FUNCTION_ARG]] ^(<dt>SQLITE_LIMIT_FUNCTION_ARG</dt>
|
3186
3492
|
** <dd>The maximum number of arguments on a function.</dd>)^
|
@@ -3218,23 +3524,59 @@ SQLITE_API int SQLITE_STDCALL sqlite3_limit(sqlite3*, int id, int newVal);
|
|
3218
3524
|
#define SQLITE_LIMIT_TRIGGER_DEPTH 10
|
3219
3525
|
#define SQLITE_LIMIT_WORKER_THREADS 11
|
3220
3526
|
|
3527
|
+
/*
|
3528
|
+
** CAPI3REF: Prepare Flags
|
3529
|
+
**
|
3530
|
+
** These constants define various flags that can be passed into
|
3531
|
+
** "prepFlags" parameter of the [sqlite3_prepare_v3()] and
|
3532
|
+
** [sqlite3_prepare16_v3()] interfaces.
|
3533
|
+
**
|
3534
|
+
** New flags may be added in future releases of SQLite.
|
3535
|
+
**
|
3536
|
+
** <dl>
|
3537
|
+
** [[SQLITE_PREPARE_PERSISTENT]] ^(<dt>SQLITE_PREPARE_PERSISTENT</dt>
|
3538
|
+
** <dd>The SQLITE_PREPARE_PERSISTENT flag is a hint to the query planner
|
3539
|
+
** that the prepared statement will be retained for a long time and
|
3540
|
+
** probably reused many times.)^ ^Without this flag, [sqlite3_prepare_v3()]
|
3541
|
+
** and [sqlite3_prepare16_v3()] assume that the prepared statement will
|
3542
|
+
** be used just once or at most a few times and then destroyed using
|
3543
|
+
** [sqlite3_finalize()] relatively soon. The current implementation acts
|
3544
|
+
** on this hint by avoiding the use of [lookaside memory] so as not to
|
3545
|
+
** deplete the limited store of lookaside memory. Future versions of
|
3546
|
+
** SQLite may act on this hint differently.
|
3547
|
+
** </dl>
|
3548
|
+
*/
|
3549
|
+
#define SQLITE_PREPARE_PERSISTENT 0x01
|
3550
|
+
|
3221
3551
|
/*
|
3222
3552
|
** CAPI3REF: Compiling An SQL Statement
|
3223
3553
|
** KEYWORDS: {SQL statement compiler}
|
3224
3554
|
** METHOD: sqlite3
|
3225
3555
|
** CONSTRUCTOR: sqlite3_stmt
|
3226
3556
|
**
|
3227
|
-
** To execute an SQL
|
3228
|
-
** program using one of these routines.
|
3557
|
+
** To execute an SQL statement, it must first be compiled into a byte-code
|
3558
|
+
** program using one of these routines. Or, in other words, these routines
|
3559
|
+
** are constructors for the [prepared statement] object.
|
3560
|
+
**
|
3561
|
+
** The preferred routine to use is [sqlite3_prepare_v2()]. The
|
3562
|
+
** [sqlite3_prepare()] interface is legacy and should be avoided.
|
3563
|
+
** [sqlite3_prepare_v3()] has an extra "prepFlags" option that is used
|
3564
|
+
** for special purposes.
|
3565
|
+
**
|
3566
|
+
** The use of the UTF-8 interfaces is preferred, as SQLite currently
|
3567
|
+
** does all parsing using UTF-8. The UTF-16 interfaces are provided
|
3568
|
+
** as a convenience. The UTF-16 interfaces work by converting the
|
3569
|
+
** input text into UTF-8, then invoking the corresponding UTF-8 interface.
|
3229
3570
|
**
|
3230
3571
|
** The first argument, "db", is a [database connection] obtained from a
|
3231
3572
|
** prior successful call to [sqlite3_open()], [sqlite3_open_v2()] or
|
3232
3573
|
** [sqlite3_open16()]. The database connection must not have been closed.
|
3233
3574
|
**
|
3234
3575
|
** The second argument, "zSql", is the statement to be compiled, encoded
|
3235
|
-
** as either UTF-8 or UTF-16. The sqlite3_prepare()
|
3236
|
-
**
|
3237
|
-
** use UTF-
|
3576
|
+
** as either UTF-8 or UTF-16. The sqlite3_prepare(), sqlite3_prepare_v2(),
|
3577
|
+
** and sqlite3_prepare_v3()
|
3578
|
+
** interfaces use UTF-8, and sqlite3_prepare16(), sqlite3_prepare16_v2(),
|
3579
|
+
** and sqlite3_prepare16_v3() use UTF-16.
|
3238
3580
|
**
|
3239
3581
|
** ^If the nByte argument is negative, then zSql is read up to the
|
3240
3582
|
** first zero terminator. ^If nByte is positive, then it is the
|
@@ -3261,10 +3603,11 @@ SQLITE_API int SQLITE_STDCALL sqlite3_limit(sqlite3*, int id, int newVal);
|
|
3261
3603
|
** ^On success, the sqlite3_prepare() family of routines return [SQLITE_OK];
|
3262
3604
|
** otherwise an [error code] is returned.
|
3263
3605
|
**
|
3264
|
-
** The sqlite3_prepare_v2()
|
3265
|
-
** recommended for all new programs.
|
3266
|
-
**
|
3267
|
-
**
|
3606
|
+
** The sqlite3_prepare_v2(), sqlite3_prepare_v3(), sqlite3_prepare16_v2(),
|
3607
|
+
** and sqlite3_prepare16_v3() interfaces are recommended for all new programs.
|
3608
|
+
** The older interfaces (sqlite3_prepare() and sqlite3_prepare16())
|
3609
|
+
** are retained for backwards compatibility, but their use is discouraged.
|
3610
|
+
** ^In the "vX" interfaces, the prepared statement
|
3268
3611
|
** that is returned (the [sqlite3_stmt] object) contains a copy of the
|
3269
3612
|
** original SQL text. This causes the [sqlite3_step()] interface to
|
3270
3613
|
** behave differently in three ways:
|
@@ -3297,46 +3640,93 @@ SQLITE_API int SQLITE_STDCALL sqlite3_limit(sqlite3*, int id, int newVal);
|
|
3297
3640
|
** or [GLOB] operator or if the parameter is compared to an indexed column
|
3298
3641
|
** and the [SQLITE_ENABLE_STAT3] compile-time option is enabled.
|
3299
3642
|
** </li>
|
3643
|
+
**
|
3644
|
+
** <p>^sqlite3_prepare_v3() differs from sqlite3_prepare_v2() only in having
|
3645
|
+
** the extra prepFlags parameter, which is a bit array consisting of zero or
|
3646
|
+
** more of the [SQLITE_PREPARE_PERSISTENT|SQLITE_PREPARE_*] flags. ^The
|
3647
|
+
** sqlite3_prepare_v2() interface works exactly the same as
|
3648
|
+
** sqlite3_prepare_v3() with a zero prepFlags parameter.
|
3300
3649
|
** </ol>
|
3301
3650
|
*/
|
3302
|
-
SQLITE_API int
|
3651
|
+
SQLITE_API int sqlite3_prepare(
|
3303
3652
|
sqlite3 *db, /* Database handle */
|
3304
3653
|
const char *zSql, /* SQL statement, UTF-8 encoded */
|
3305
3654
|
int nByte, /* Maximum length of zSql in bytes. */
|
3306
3655
|
sqlite3_stmt **ppStmt, /* OUT: Statement handle */
|
3307
3656
|
const char **pzTail /* OUT: Pointer to unused portion of zSql */
|
3308
3657
|
);
|
3309
|
-
SQLITE_API int
|
3658
|
+
SQLITE_API int sqlite3_prepare_v2(
|
3310
3659
|
sqlite3 *db, /* Database handle */
|
3311
3660
|
const char *zSql, /* SQL statement, UTF-8 encoded */
|
3312
3661
|
int nByte, /* Maximum length of zSql in bytes. */
|
3313
3662
|
sqlite3_stmt **ppStmt, /* OUT: Statement handle */
|
3314
3663
|
const char **pzTail /* OUT: Pointer to unused portion of zSql */
|
3315
3664
|
);
|
3316
|
-
SQLITE_API int
|
3665
|
+
SQLITE_API int sqlite3_prepare_v3(
|
3666
|
+
sqlite3 *db, /* Database handle */
|
3667
|
+
const char *zSql, /* SQL statement, UTF-8 encoded */
|
3668
|
+
int nByte, /* Maximum length of zSql in bytes. */
|
3669
|
+
unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */
|
3670
|
+
sqlite3_stmt **ppStmt, /* OUT: Statement handle */
|
3671
|
+
const char **pzTail /* OUT: Pointer to unused portion of zSql */
|
3672
|
+
);
|
3673
|
+
SQLITE_API int sqlite3_prepare16(
|
3317
3674
|
sqlite3 *db, /* Database handle */
|
3318
3675
|
const void *zSql, /* SQL statement, UTF-16 encoded */
|
3319
3676
|
int nByte, /* Maximum length of zSql in bytes. */
|
3320
3677
|
sqlite3_stmt **ppStmt, /* OUT: Statement handle */
|
3321
3678
|
const void **pzTail /* OUT: Pointer to unused portion of zSql */
|
3322
3679
|
);
|
3323
|
-
SQLITE_API int
|
3680
|
+
SQLITE_API int sqlite3_prepare16_v2(
|
3324
3681
|
sqlite3 *db, /* Database handle */
|
3325
3682
|
const void *zSql, /* SQL statement, UTF-16 encoded */
|
3326
3683
|
int nByte, /* Maximum length of zSql in bytes. */
|
3327
3684
|
sqlite3_stmt **ppStmt, /* OUT: Statement handle */
|
3328
3685
|
const void **pzTail /* OUT: Pointer to unused portion of zSql */
|
3329
3686
|
);
|
3687
|
+
SQLITE_API int sqlite3_prepare16_v3(
|
3688
|
+
sqlite3 *db, /* Database handle */
|
3689
|
+
const void *zSql, /* SQL statement, UTF-16 encoded */
|
3690
|
+
int nByte, /* Maximum length of zSql in bytes. */
|
3691
|
+
unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */
|
3692
|
+
sqlite3_stmt **ppStmt, /* OUT: Statement handle */
|
3693
|
+
const void **pzTail /* OUT: Pointer to unused portion of zSql */
|
3694
|
+
);
|
3330
3695
|
|
3331
3696
|
/*
|
3332
3697
|
** CAPI3REF: Retrieving Statement SQL
|
3333
3698
|
** METHOD: sqlite3_stmt
|
3334
3699
|
**
|
3335
|
-
** ^
|
3336
|
-
** SQL text used to create
|
3337
|
-
**
|
3700
|
+
** ^The sqlite3_sql(P) interface returns a pointer to a copy of the UTF-8
|
3701
|
+
** SQL text used to create [prepared statement] P if P was
|
3702
|
+
** created by [sqlite3_prepare_v2()], [sqlite3_prepare_v3()],
|
3703
|
+
** [sqlite3_prepare16_v2()], or [sqlite3_prepare16_v3()].
|
3704
|
+
** ^The sqlite3_expanded_sql(P) interface returns a pointer to a UTF-8
|
3705
|
+
** string containing the SQL text of prepared statement P with
|
3706
|
+
** [bound parameters] expanded.
|
3707
|
+
**
|
3708
|
+
** ^(For example, if a prepared statement is created using the SQL
|
3709
|
+
** text "SELECT $abc,:xyz" and if parameter $abc is bound to integer 2345
|
3710
|
+
** and parameter :xyz is unbound, then sqlite3_sql() will return
|
3711
|
+
** the original string, "SELECT $abc,:xyz" but sqlite3_expanded_sql()
|
3712
|
+
** will return "SELECT 2345,NULL".)^
|
3713
|
+
**
|
3714
|
+
** ^The sqlite3_expanded_sql() interface returns NULL if insufficient memory
|
3715
|
+
** is available to hold the result, or if the result would exceed the
|
3716
|
+
** the maximum string length determined by the [SQLITE_LIMIT_LENGTH].
|
3717
|
+
**
|
3718
|
+
** ^The [SQLITE_TRACE_SIZE_LIMIT] compile-time option limits the size of
|
3719
|
+
** bound parameter expansions. ^The [SQLITE_OMIT_TRACE] compile-time
|
3720
|
+
** option causes sqlite3_expanded_sql() to always return NULL.
|
3721
|
+
**
|
3722
|
+
** ^The string returned by sqlite3_sql(P) is managed by SQLite and is
|
3723
|
+
** automatically freed when the prepared statement is finalized.
|
3724
|
+
** ^The string returned by sqlite3_expanded_sql(P), on the other hand,
|
3725
|
+
** is obtained from [sqlite3_malloc()] and must be free by the application
|
3726
|
+
** by passing it to [sqlite3_free()].
|
3338
3727
|
*/
|
3339
|
-
SQLITE_API const char *
|
3728
|
+
SQLITE_API const char *sqlite3_sql(sqlite3_stmt *pStmt);
|
3729
|
+
SQLITE_API char *sqlite3_expanded_sql(sqlite3_stmt *pStmt);
|
3340
3730
|
|
3341
3731
|
/*
|
3342
3732
|
** CAPI3REF: Determine If An SQL Statement Writes The Database
|
@@ -3367,8 +3757,12 @@ SQLITE_API const char *SQLITE_STDCALL sqlite3_sql(sqlite3_stmt *pStmt);
|
|
3367
3757
|
** sqlite3_stmt_readonly() to return true since, while those statements
|
3368
3758
|
** change the configuration of a database connection, they do not make
|
3369
3759
|
** changes to the content of the database files on disk.
|
3760
|
+
** ^The sqlite3_stmt_readonly() interface returns true for [BEGIN] since
|
3761
|
+
** [BEGIN] merely sets internal flags, but the [BEGIN|BEGIN IMMEDIATE] and
|
3762
|
+
** [BEGIN|BEGIN EXCLUSIVE] commands do touch the database and so
|
3763
|
+
** sqlite3_stmt_readonly() returns false for those commands.
|
3370
3764
|
*/
|
3371
|
-
SQLITE_API int
|
3765
|
+
SQLITE_API int sqlite3_stmt_readonly(sqlite3_stmt *pStmt);
|
3372
3766
|
|
3373
3767
|
/*
|
3374
3768
|
** CAPI3REF: Determine If A Prepared Statement Has Been Reset
|
@@ -3389,7 +3783,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_stmt_readonly(sqlite3_stmt *pStmt);
|
|
3389
3783
|
** for example, in diagnostic routines to search for prepared
|
3390
3784
|
** statements that are holding a transaction open.
|
3391
3785
|
*/
|
3392
|
-
SQLITE_API int
|
3786
|
+
SQLITE_API int sqlite3_stmt_busy(sqlite3_stmt*);
|
3393
3787
|
|
3394
3788
|
/*
|
3395
3789
|
** CAPI3REF: Dynamically Typed Value Object
|
@@ -3425,12 +3819,13 @@ SQLITE_API int SQLITE_STDCALL sqlite3_stmt_busy(sqlite3_stmt*);
|
|
3425
3819
|
** implementation of [application-defined SQL functions] are protected.
|
3426
3820
|
** ^The sqlite3_value object returned by
|
3427
3821
|
** [sqlite3_column_value()] is unprotected.
|
3428
|
-
** Unprotected sqlite3_value objects may only be used
|
3429
|
-
** [sqlite3_result_value()]
|
3822
|
+
** Unprotected sqlite3_value objects may only be used as arguments
|
3823
|
+
** to [sqlite3_result_value()], [sqlite3_bind_value()], and
|
3824
|
+
** [sqlite3_value_dup()].
|
3430
3825
|
** The [sqlite3_value_blob | sqlite3_value_type()] family of
|
3431
3826
|
** interfaces require protected sqlite3_value objects.
|
3432
3827
|
*/
|
3433
|
-
typedef struct
|
3828
|
+
typedef struct sqlite3_value sqlite3_value;
|
3434
3829
|
|
3435
3830
|
/*
|
3436
3831
|
** CAPI3REF: SQL Function Context Object
|
@@ -3532,6 +3927,15 @@ typedef struct sqlite3_context sqlite3_context;
|
|
3532
3927
|
** [sqlite3_blob_open | incremental BLOB I/O] routines.
|
3533
3928
|
** ^A negative value for the zeroblob results in a zero-length BLOB.
|
3534
3929
|
**
|
3930
|
+
** ^The sqlite3_bind_pointer(S,I,P,T,D) routine causes the I-th parameter in
|
3931
|
+
** [prepared statement] S to have an SQL value of NULL, but to also be
|
3932
|
+
** associated with the pointer P of type T. ^D is either a NULL pointer or
|
3933
|
+
** a pointer to a destructor function for P. ^SQLite will invoke the
|
3934
|
+
** destructor D with a single argument of P when it is finished using
|
3935
|
+
** P. The T parameter should be a static string, preferably a string
|
3936
|
+
** literal. The sqlite3_bind_pointer() routine is part of the
|
3937
|
+
** [pointer passing interface] added for SQLite 3.20.0.
|
3938
|
+
**
|
3535
3939
|
** ^If any of the sqlite3_bind_*() routines are called with a NULL pointer
|
3536
3940
|
** for the [prepared statement] or with a prepared statement for which
|
3537
3941
|
** [sqlite3_step()] has been called more recently than [sqlite3_reset()],
|
@@ -3553,20 +3957,21 @@ typedef struct sqlite3_context sqlite3_context;
|
|
3553
3957
|
** See also: [sqlite3_bind_parameter_count()],
|
3554
3958
|
** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()].
|
3555
3959
|
*/
|
3556
|
-
SQLITE_API int
|
3557
|
-
SQLITE_API int
|
3960
|
+
SQLITE_API int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
|
3961
|
+
SQLITE_API int sqlite3_bind_blob64(sqlite3_stmt*, int, const void*, sqlite3_uint64,
|
3558
3962
|
void(*)(void*));
|
3559
|
-
SQLITE_API int
|
3560
|
-
SQLITE_API int
|
3561
|
-
SQLITE_API int
|
3562
|
-
SQLITE_API int
|
3563
|
-
SQLITE_API int
|
3564
|
-
SQLITE_API int
|
3565
|
-
SQLITE_API int
|
3963
|
+
SQLITE_API int sqlite3_bind_double(sqlite3_stmt*, int, double);
|
3964
|
+
SQLITE_API int sqlite3_bind_int(sqlite3_stmt*, int, int);
|
3965
|
+
SQLITE_API int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
|
3966
|
+
SQLITE_API int sqlite3_bind_null(sqlite3_stmt*, int);
|
3967
|
+
SQLITE_API int sqlite3_bind_text(sqlite3_stmt*,int,const char*,int,void(*)(void*));
|
3968
|
+
SQLITE_API int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
|
3969
|
+
SQLITE_API int sqlite3_bind_text64(sqlite3_stmt*, int, const char*, sqlite3_uint64,
|
3566
3970
|
void(*)(void*), unsigned char encoding);
|
3567
|
-
SQLITE_API int
|
3568
|
-
SQLITE_API int
|
3569
|
-
SQLITE_API int
|
3971
|
+
SQLITE_API int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
|
3972
|
+
SQLITE_API int sqlite3_bind_pointer(sqlite3_stmt*, int, void*, const char*,void(*)(void*));
|
3973
|
+
SQLITE_API int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
|
3974
|
+
SQLITE_API int sqlite3_bind_zeroblob64(sqlite3_stmt*, int, sqlite3_uint64);
|
3570
3975
|
|
3571
3976
|
/*
|
3572
3977
|
** CAPI3REF: Number Of SQL Parameters
|
@@ -3587,7 +3992,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_bind_zeroblob64(sqlite3_stmt*, int, sqlite
|
|
3587
3992
|
** [sqlite3_bind_parameter_name()], and
|
3588
3993
|
** [sqlite3_bind_parameter_index()].
|
3589
3994
|
*/
|
3590
|
-
SQLITE_API int
|
3995
|
+
SQLITE_API int sqlite3_bind_parameter_count(sqlite3_stmt*);
|
3591
3996
|
|
3592
3997
|
/*
|
3593
3998
|
** CAPI3REF: Name Of A Host Parameter
|
@@ -3608,14 +4013,14 @@ SQLITE_API int SQLITE_STDCALL sqlite3_bind_parameter_count(sqlite3_stmt*);
|
|
3608
4013
|
** ^If the value N is out of range or if the N-th parameter is
|
3609
4014
|
** nameless, then NULL is returned. ^The returned string is
|
3610
4015
|
** always in UTF-8 encoding even if the named parameter was
|
3611
|
-
** originally specified as UTF-16 in [sqlite3_prepare16()]
|
3612
|
-
** [sqlite3_prepare16_v2()].
|
4016
|
+
** originally specified as UTF-16 in [sqlite3_prepare16()],
|
4017
|
+
** [sqlite3_prepare16_v2()], or [sqlite3_prepare16_v3()].
|
3613
4018
|
**
|
3614
4019
|
** See also: [sqlite3_bind_blob|sqlite3_bind()],
|
3615
4020
|
** [sqlite3_bind_parameter_count()], and
|
3616
4021
|
** [sqlite3_bind_parameter_index()].
|
3617
4022
|
*/
|
3618
|
-
SQLITE_API const char *
|
4023
|
+
SQLITE_API const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
|
3619
4024
|
|
3620
4025
|
/*
|
3621
4026
|
** CAPI3REF: Index Of A Parameter With A Given Name
|
@@ -3626,13 +4031,14 @@ SQLITE_API const char *SQLITE_STDCALL sqlite3_bind_parameter_name(sqlite3_stmt*,
|
|
3626
4031
|
** parameter to [sqlite3_bind_blob|sqlite3_bind()]. ^A zero
|
3627
4032
|
** is returned if no matching parameter is found. ^The parameter
|
3628
4033
|
** name must be given in UTF-8 even if the original statement
|
3629
|
-
** was prepared from UTF-16 text using [sqlite3_prepare16_v2()]
|
4034
|
+
** was prepared from UTF-16 text using [sqlite3_prepare16_v2()] or
|
4035
|
+
** [sqlite3_prepare16_v3()].
|
3630
4036
|
**
|
3631
4037
|
** See also: [sqlite3_bind_blob|sqlite3_bind()],
|
3632
4038
|
** [sqlite3_bind_parameter_count()], and
|
3633
4039
|
** [sqlite3_bind_parameter_name()].
|
3634
4040
|
*/
|
3635
|
-
SQLITE_API int
|
4041
|
+
SQLITE_API int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
|
3636
4042
|
|
3637
4043
|
/*
|
3638
4044
|
** CAPI3REF: Reset All Bindings On A Prepared Statement
|
@@ -3642,19 +4048,23 @@ SQLITE_API int SQLITE_STDCALL sqlite3_bind_parameter_index(sqlite3_stmt*, const
|
|
3642
4048
|
** the [sqlite3_bind_blob | bindings] on a [prepared statement].
|
3643
4049
|
** ^Use this routine to reset all host parameters to NULL.
|
3644
4050
|
*/
|
3645
|
-
SQLITE_API int
|
4051
|
+
SQLITE_API int sqlite3_clear_bindings(sqlite3_stmt*);
|
3646
4052
|
|
3647
4053
|
/*
|
3648
4054
|
** CAPI3REF: Number Of Columns In A Result Set
|
3649
4055
|
** METHOD: sqlite3_stmt
|
3650
4056
|
**
|
3651
4057
|
** ^Return the number of columns in the result set returned by the
|
3652
|
-
** [prepared statement]. ^
|
3653
|
-
** statement
|
4058
|
+
** [prepared statement]. ^If this routine returns 0, that means the
|
4059
|
+
** [prepared statement] returns no data (for example an [UPDATE]).
|
4060
|
+
** ^However, just because this routine returns a positive number does not
|
4061
|
+
** mean that one or more rows of data will be returned. ^A SELECT statement
|
4062
|
+
** will always have a positive sqlite3_column_count() but depending on the
|
4063
|
+
** WHERE clause constraints and the table content, it might return no rows.
|
3654
4064
|
**
|
3655
4065
|
** See also: [sqlite3_data_count()]
|
3656
4066
|
*/
|
3657
|
-
SQLITE_API int
|
4067
|
+
SQLITE_API int sqlite3_column_count(sqlite3_stmt *pStmt);
|
3658
4068
|
|
3659
4069
|
/*
|
3660
4070
|
** CAPI3REF: Column Names In A Result Set
|
@@ -3683,8 +4093,8 @@ SQLITE_API int SQLITE_STDCALL sqlite3_column_count(sqlite3_stmt *pStmt);
|
|
3683
4093
|
** then the name of the column is unspecified and may change from
|
3684
4094
|
** one release of SQLite to the next.
|
3685
4095
|
*/
|
3686
|
-
SQLITE_API const char *
|
3687
|
-
SQLITE_API const void *
|
4096
|
+
SQLITE_API const char *sqlite3_column_name(sqlite3_stmt*, int N);
|
4097
|
+
SQLITE_API const void *sqlite3_column_name16(sqlite3_stmt*, int N);
|
3688
4098
|
|
3689
4099
|
/*
|
3690
4100
|
** CAPI3REF: Source Of Data In A Query Result
|
@@ -3732,12 +4142,12 @@ SQLITE_API const void *SQLITE_STDCALL sqlite3_column_name16(sqlite3_stmt*, int N
|
|
3732
4142
|
** for the same [prepared statement] and result column
|
3733
4143
|
** at the same time then the results are undefined.
|
3734
4144
|
*/
|
3735
|
-
SQLITE_API const char *
|
3736
|
-
SQLITE_API const void *
|
3737
|
-
SQLITE_API const char *
|
3738
|
-
SQLITE_API const void *
|
3739
|
-
SQLITE_API const char *
|
3740
|
-
SQLITE_API const void *
|
4145
|
+
SQLITE_API const char *sqlite3_column_database_name(sqlite3_stmt*,int);
|
4146
|
+
SQLITE_API const void *sqlite3_column_database_name16(sqlite3_stmt*,int);
|
4147
|
+
SQLITE_API const char *sqlite3_column_table_name(sqlite3_stmt*,int);
|
4148
|
+
SQLITE_API const void *sqlite3_column_table_name16(sqlite3_stmt*,int);
|
4149
|
+
SQLITE_API const char *sqlite3_column_origin_name(sqlite3_stmt*,int);
|
4150
|
+
SQLITE_API const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);
|
3741
4151
|
|
3742
4152
|
/*
|
3743
4153
|
** CAPI3REF: Declared Datatype Of A Query Result
|
@@ -3769,23 +4179,25 @@ SQLITE_API const void *SQLITE_STDCALL sqlite3_column_origin_name16(sqlite3_stmt*
|
|
3769
4179
|
** is associated with individual values, not with the containers
|
3770
4180
|
** used to hold those values.
|
3771
4181
|
*/
|
3772
|
-
SQLITE_API const char *
|
3773
|
-
SQLITE_API const void *
|
4182
|
+
SQLITE_API const char *sqlite3_column_decltype(sqlite3_stmt*,int);
|
4183
|
+
SQLITE_API const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
|
3774
4184
|
|
3775
4185
|
/*
|
3776
4186
|
** CAPI3REF: Evaluate An SQL Statement
|
3777
4187
|
** METHOD: sqlite3_stmt
|
3778
4188
|
**
|
3779
|
-
** After a [prepared statement] has been prepared using
|
3780
|
-
** [sqlite3_prepare_v2()]
|
4189
|
+
** After a [prepared statement] has been prepared using any of
|
4190
|
+
** [sqlite3_prepare_v2()], [sqlite3_prepare_v3()], [sqlite3_prepare16_v2()],
|
4191
|
+
** or [sqlite3_prepare16_v3()] or one of the legacy
|
3781
4192
|
** interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], this function
|
3782
4193
|
** must be called one or more times to evaluate the statement.
|
3783
4194
|
**
|
3784
4195
|
** The details of the behavior of the sqlite3_step() interface depend
|
3785
|
-
** on whether the statement was prepared using the newer "
|
3786
|
-
** [sqlite3_prepare_v2()]
|
3787
|
-
**
|
3788
|
-
**
|
4196
|
+
** on whether the statement was prepared using the newer "vX" interfaces
|
4197
|
+
** [sqlite3_prepare_v3()], [sqlite3_prepare_v2()], [sqlite3_prepare16_v3()],
|
4198
|
+
** [sqlite3_prepare16_v2()] or the older legacy
|
4199
|
+
** interfaces [sqlite3_prepare()] and [sqlite3_prepare16()]. The use of the
|
4200
|
+
** new "vX" interface is recommended for new applications but the legacy
|
3789
4201
|
** interface will continue to be supported.
|
3790
4202
|
**
|
3791
4203
|
** ^In the legacy interface, the return value will be either [SQLITE_BUSY],
|
@@ -3831,7 +4243,8 @@ SQLITE_API const void *SQLITE_STDCALL sqlite3_column_decltype16(sqlite3_stmt*,in
|
|
3831
4243
|
** other than [SQLITE_ROW] before any subsequent invocation of
|
3832
4244
|
** sqlite3_step(). Failure to reset the prepared statement using
|
3833
4245
|
** [sqlite3_reset()] would result in an [SQLITE_MISUSE] return from
|
3834
|
-
** sqlite3_step(). But after version 3.6.23.1
|
4246
|
+
** sqlite3_step(). But after [version 3.6.23.1] ([dateof:3.6.23.1],
|
4247
|
+
** sqlite3_step() began
|
3835
4248
|
** calling [sqlite3_reset()] automatically in this circumstance rather
|
3836
4249
|
** than returning [SQLITE_MISUSE]. This is not considered a compatibility
|
3837
4250
|
** break because any application that ever receives an SQLITE_MISUSE error
|
@@ -3845,12 +4258,13 @@ SQLITE_API const void *SQLITE_STDCALL sqlite3_column_decltype16(sqlite3_stmt*,in
|
|
3845
4258
|
** specific [error codes] that better describes the error.
|
3846
4259
|
** We admit that this is a goofy design. The problem has been fixed
|
3847
4260
|
** with the "v2" interface. If you prepare all of your SQL statements
|
3848
|
-
** using
|
4261
|
+
** using [sqlite3_prepare_v3()] or [sqlite3_prepare_v2()]
|
4262
|
+
** or [sqlite3_prepare16_v2()] or [sqlite3_prepare16_v3()] instead
|
3849
4263
|
** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()] interfaces,
|
3850
4264
|
** then the more specific [error codes] are returned directly
|
3851
|
-
** by sqlite3_step(). The use of the "
|
4265
|
+
** by sqlite3_step(). The use of the "vX" interfaces is recommended.
|
3852
4266
|
*/
|
3853
|
-
SQLITE_API int
|
4267
|
+
SQLITE_API int sqlite3_step(sqlite3_stmt*);
|
3854
4268
|
|
3855
4269
|
/*
|
3856
4270
|
** CAPI3REF: Number of columns in a result set
|
@@ -3871,7 +4285,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_step(sqlite3_stmt*);
|
|
3871
4285
|
**
|
3872
4286
|
** See also: [sqlite3_column_count()]
|
3873
4287
|
*/
|
3874
|
-
SQLITE_API int
|
4288
|
+
SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
|
3875
4289
|
|
3876
4290
|
/*
|
3877
4291
|
** CAPI3REF: Fundamental Datatypes
|
@@ -3910,6 +4324,28 @@ SQLITE_API int SQLITE_STDCALL sqlite3_data_count(sqlite3_stmt *pStmt);
|
|
3910
4324
|
** KEYWORDS: {column access functions}
|
3911
4325
|
** METHOD: sqlite3_stmt
|
3912
4326
|
**
|
4327
|
+
** <b>Summary:</b>
|
4328
|
+
** <blockquote><table border=0 cellpadding=0 cellspacing=0>
|
4329
|
+
** <tr><td><b>sqlite3_column_blob</b><td>→<td>BLOB result
|
4330
|
+
** <tr><td><b>sqlite3_column_double</b><td>→<td>REAL result
|
4331
|
+
** <tr><td><b>sqlite3_column_int</b><td>→<td>32-bit INTEGER result
|
4332
|
+
** <tr><td><b>sqlite3_column_int64</b><td>→<td>64-bit INTEGER result
|
4333
|
+
** <tr><td><b>sqlite3_column_text</b><td>→<td>UTF-8 TEXT result
|
4334
|
+
** <tr><td><b>sqlite3_column_text16</b><td>→<td>UTF-16 TEXT result
|
4335
|
+
** <tr><td><b>sqlite3_column_value</b><td>→<td>The result as an
|
4336
|
+
** [sqlite3_value|unprotected sqlite3_value] object.
|
4337
|
+
** <tr><td> <td> <td>
|
4338
|
+
** <tr><td><b>sqlite3_column_bytes</b><td>→<td>Size of a BLOB
|
4339
|
+
** or a UTF-8 TEXT result in bytes
|
4340
|
+
** <tr><td><b>sqlite3_column_bytes16 </b>
|
4341
|
+
** <td>→ <td>Size of UTF-16
|
4342
|
+
** TEXT in bytes
|
4343
|
+
** <tr><td><b>sqlite3_column_type</b><td>→<td>Default
|
4344
|
+
** datatype of the result
|
4345
|
+
** </table></blockquote>
|
4346
|
+
**
|
4347
|
+
** <b>Details:</b>
|
4348
|
+
**
|
3913
4349
|
** ^These routines return information about a single column of the current
|
3914
4350
|
** result row of a query. ^In every case the first argument is a pointer
|
3915
4351
|
** to the [prepared statement] that is being evaluated (the [sqlite3_stmt*]
|
@@ -3931,16 +4367,29 @@ SQLITE_API int SQLITE_STDCALL sqlite3_data_count(sqlite3_stmt *pStmt);
|
|
3931
4367
|
** are called from a different thread while any of these routines
|
3932
4368
|
** are pending, then the results are undefined.
|
3933
4369
|
**
|
4370
|
+
** The first six interfaces (_blob, _double, _int, _int64, _text, and _text16)
|
4371
|
+
** each return the value of a result column in a specific data format. If
|
4372
|
+
** the result column is not initially in the requested format (for example,
|
4373
|
+
** if the query returns an integer but the sqlite3_column_text() interface
|
4374
|
+
** is used to extract the value) then an automatic type conversion is performed.
|
4375
|
+
**
|
3934
4376
|
** ^The sqlite3_column_type() routine returns the
|
3935
4377
|
** [SQLITE_INTEGER | datatype code] for the initial data type
|
3936
4378
|
** of the result column. ^The returned value is one of [SQLITE_INTEGER],
|
3937
|
-
** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL].
|
3938
|
-
**
|
3939
|
-
**
|
3940
|
-
**
|
4379
|
+
** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL].
|
4380
|
+
** The return value of sqlite3_column_type() can be used to decide which
|
4381
|
+
** of the first six interface should be used to extract the column value.
|
4382
|
+
** The value returned by sqlite3_column_type() is only meaningful if no
|
4383
|
+
** automatic type conversions have occurred for the value in question.
|
4384
|
+
** After a type conversion, the result of calling sqlite3_column_type()
|
4385
|
+
** is undefined, though harmless. Future
|
3941
4386
|
** versions of SQLite may change the behavior of sqlite3_column_type()
|
3942
4387
|
** following a type conversion.
|
3943
4388
|
**
|
4389
|
+
** If the result is a BLOB or a TEXT string, then the sqlite3_column_bytes()
|
4390
|
+
** or sqlite3_column_bytes16() interfaces can be used to determine the size
|
4391
|
+
** of that BLOB or string.
|
4392
|
+
**
|
3944
4393
|
** ^If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
|
3945
4394
|
** routine returns the number of bytes in that BLOB or string.
|
3946
4395
|
** ^If the result is a UTF-16 string, then sqlite3_column_bytes() converts
|
@@ -3977,9 +4426,13 @@ SQLITE_API int SQLITE_STDCALL sqlite3_data_count(sqlite3_stmt *pStmt);
|
|
3977
4426
|
** [sqlite3_column_value()] is used in any other way, including calls
|
3978
4427
|
** to routines like [sqlite3_value_int()], [sqlite3_value_text()],
|
3979
4428
|
** or [sqlite3_value_bytes()], the behavior is not threadsafe.
|
4429
|
+
** Hence, the sqlite3_column_value() interface
|
4430
|
+
** is normally only useful within the implementation of
|
4431
|
+
** [application-defined SQL functions] or [virtual tables], not within
|
4432
|
+
** top-level application code.
|
3980
4433
|
**
|
3981
|
-
**
|
3982
|
-
** example, if the internal representation is FLOAT and a text result
|
4434
|
+
** The these routines may attempt to convert the datatype of the result.
|
4435
|
+
** ^For example, if the internal representation is FLOAT and a text result
|
3983
4436
|
** is requested, [sqlite3_snprintf()] is used internally to perform the
|
3984
4437
|
** conversion automatically. ^(The following table details the conversions
|
3985
4438
|
** that are applied:
|
@@ -4051,7 +4504,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_data_count(sqlite3_stmt *pStmt);
|
|
4051
4504
|
** ^The pointers returned are valid until a type conversion occurs as
|
4052
4505
|
** described above, or until [sqlite3_step()] or [sqlite3_reset()] or
|
4053
4506
|
** [sqlite3_finalize()] is called. ^The memory space used to hold strings
|
4054
|
-
** and BLOBs is freed automatically. Do
|
4507
|
+
** and BLOBs is freed automatically. Do not pass the pointers returned
|
4055
4508
|
** from [sqlite3_column_blob()], [sqlite3_column_text()], etc. into
|
4056
4509
|
** [sqlite3_free()].
|
4057
4510
|
**
|
@@ -4061,16 +4514,16 @@ SQLITE_API int SQLITE_STDCALL sqlite3_data_count(sqlite3_stmt *pStmt);
|
|
4061
4514
|
** pointer. Subsequent calls to [sqlite3_errcode()] will return
|
4062
4515
|
** [SQLITE_NOMEM].)^
|
4063
4516
|
*/
|
4064
|
-
SQLITE_API const void *
|
4065
|
-
SQLITE_API
|
4066
|
-
SQLITE_API int
|
4067
|
-
SQLITE_API
|
4068
|
-
SQLITE_API
|
4069
|
-
SQLITE_API
|
4070
|
-
SQLITE_API
|
4071
|
-
SQLITE_API
|
4072
|
-
SQLITE_API int
|
4073
|
-
SQLITE_API
|
4517
|
+
SQLITE_API const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
|
4518
|
+
SQLITE_API double sqlite3_column_double(sqlite3_stmt*, int iCol);
|
4519
|
+
SQLITE_API int sqlite3_column_int(sqlite3_stmt*, int iCol);
|
4520
|
+
SQLITE_API sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
|
4521
|
+
SQLITE_API const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
|
4522
|
+
SQLITE_API const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
|
4523
|
+
SQLITE_API sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
|
4524
|
+
SQLITE_API int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
|
4525
|
+
SQLITE_API int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
|
4526
|
+
SQLITE_API int sqlite3_column_type(sqlite3_stmt*, int iCol);
|
4074
4527
|
|
4075
4528
|
/*
|
4076
4529
|
** CAPI3REF: Destroy A Prepared Statement Object
|
@@ -4098,7 +4551,7 @@ SQLITE_API sqlite3_value *SQLITE_STDCALL sqlite3_column_value(sqlite3_stmt*, int
|
|
4098
4551
|
** statement after it has been finalized can result in undefined and
|
4099
4552
|
** undesirable behavior such as segfaults and heap corruption.
|
4100
4553
|
*/
|
4101
|
-
SQLITE_API int
|
4554
|
+
SQLITE_API int sqlite3_finalize(sqlite3_stmt *pStmt);
|
4102
4555
|
|
4103
4556
|
/*
|
4104
4557
|
** CAPI3REF: Reset A Prepared Statement Object
|
@@ -4125,7 +4578,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_finalize(sqlite3_stmt *pStmt);
|
|
4125
4578
|
** ^The [sqlite3_reset(S)] interface does not change the values
|
4126
4579
|
** of any [sqlite3_bind_blob|bindings] on the [prepared statement] S.
|
4127
4580
|
*/
|
4128
|
-
SQLITE_API int
|
4581
|
+
SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt);
|
4129
4582
|
|
4130
4583
|
/*
|
4131
4584
|
** CAPI3REF: Create Or Redefine SQL Functions
|
@@ -4225,7 +4678,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_reset(sqlite3_stmt *pStmt);
|
|
4225
4678
|
** close the database connection nor finalize or reset the prepared
|
4226
4679
|
** statement in which the function is running.
|
4227
4680
|
*/
|
4228
|
-
SQLITE_API int
|
4681
|
+
SQLITE_API int sqlite3_create_function(
|
4229
4682
|
sqlite3 *db,
|
4230
4683
|
const char *zFunctionName,
|
4231
4684
|
int nArg,
|
@@ -4235,7 +4688,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_create_function(
|
|
4235
4688
|
void (*xStep)(sqlite3_context*,int,sqlite3_value**),
|
4236
4689
|
void (*xFinal)(sqlite3_context*)
|
4237
4690
|
);
|
4238
|
-
SQLITE_API int
|
4691
|
+
SQLITE_API int sqlite3_create_function16(
|
4239
4692
|
sqlite3 *db,
|
4240
4693
|
const void *zFunctionName,
|
4241
4694
|
int nArg,
|
@@ -4245,7 +4698,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_create_function16(
|
|
4245
4698
|
void (*xStep)(sqlite3_context*,int,sqlite3_value**),
|
4246
4699
|
void (*xFinal)(sqlite3_context*)
|
4247
4700
|
);
|
4248
|
-
SQLITE_API int
|
4701
|
+
SQLITE_API int sqlite3_create_function_v2(
|
4249
4702
|
sqlite3 *db,
|
4250
4703
|
const char *zFunctionName,
|
4251
4704
|
int nArg,
|
@@ -4291,12 +4744,12 @@ SQLITE_API int SQLITE_STDCALL sqlite3_create_function_v2(
|
|
4291
4744
|
** these functions, we will not explain what they do.
|
4292
4745
|
*/
|
4293
4746
|
#ifndef SQLITE_OMIT_DEPRECATED
|
4294
|
-
SQLITE_API SQLITE_DEPRECATED int
|
4295
|
-
SQLITE_API SQLITE_DEPRECATED int
|
4296
|
-
SQLITE_API SQLITE_DEPRECATED int
|
4297
|
-
SQLITE_API SQLITE_DEPRECATED int
|
4298
|
-
SQLITE_API SQLITE_DEPRECATED void
|
4299
|
-
SQLITE_API SQLITE_DEPRECATED int
|
4747
|
+
SQLITE_API SQLITE_DEPRECATED int sqlite3_aggregate_count(sqlite3_context*);
|
4748
|
+
SQLITE_API SQLITE_DEPRECATED int sqlite3_expired(sqlite3_stmt*);
|
4749
|
+
SQLITE_API SQLITE_DEPRECATED int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
|
4750
|
+
SQLITE_API SQLITE_DEPRECATED int sqlite3_global_recover(void);
|
4751
|
+
SQLITE_API SQLITE_DEPRECATED void sqlite3_thread_cleanup(void);
|
4752
|
+
SQLITE_API SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),
|
4300
4753
|
void*,sqlite3_int64);
|
4301
4754
|
#endif
|
4302
4755
|
|
@@ -4304,21 +4757,40 @@ SQLITE_API SQLITE_DEPRECATED int SQLITE_STDCALL sqlite3_memory_alarm(void(*)(voi
|
|
4304
4757
|
** CAPI3REF: Obtaining SQL Values
|
4305
4758
|
** METHOD: sqlite3_value
|
4306
4759
|
**
|
4307
|
-
**
|
4308
|
-
**
|
4309
|
-
**
|
4310
|
-
**
|
4311
|
-
**
|
4312
|
-
**
|
4313
|
-
**
|
4314
|
-
**
|
4315
|
-
**
|
4316
|
-
**
|
4317
|
-
**
|
4760
|
+
** <b>Summary:</b>
|
4761
|
+
** <blockquote><table border=0 cellpadding=0 cellspacing=0>
|
4762
|
+
** <tr><td><b>sqlite3_value_blob</b><td>→<td>BLOB value
|
4763
|
+
** <tr><td><b>sqlite3_value_double</b><td>→<td>REAL value
|
4764
|
+
** <tr><td><b>sqlite3_value_int</b><td>→<td>32-bit INTEGER value
|
4765
|
+
** <tr><td><b>sqlite3_value_int64</b><td>→<td>64-bit INTEGER value
|
4766
|
+
** <tr><td><b>sqlite3_value_pointer</b><td>→<td>Pointer value
|
4767
|
+
** <tr><td><b>sqlite3_value_text</b><td>→<td>UTF-8 TEXT value
|
4768
|
+
** <tr><td><b>sqlite3_value_text16</b><td>→<td>UTF-16 TEXT value in
|
4769
|
+
** the native byteorder
|
4770
|
+
** <tr><td><b>sqlite3_value_text16be</b><td>→<td>UTF-16be TEXT value
|
4771
|
+
** <tr><td><b>sqlite3_value_text16le</b><td>→<td>UTF-16le TEXT value
|
4772
|
+
** <tr><td> <td> <td>
|
4773
|
+
** <tr><td><b>sqlite3_value_bytes</b><td>→<td>Size of a BLOB
|
4774
|
+
** or a UTF-8 TEXT in bytes
|
4775
|
+
** <tr><td><b>sqlite3_value_bytes16 </b>
|
4776
|
+
** <td>→ <td>Size of UTF-16
|
4777
|
+
** TEXT in bytes
|
4778
|
+
** <tr><td><b>sqlite3_value_type</b><td>→<td>Default
|
4779
|
+
** datatype of the value
|
4780
|
+
** <tr><td><b>sqlite3_value_numeric_type </b>
|
4781
|
+
** <td>→ <td>Best numeric datatype of the value
|
4782
|
+
** </table></blockquote>
|
4783
|
+
**
|
4784
|
+
** <b>Details:</b>
|
4785
|
+
**
|
4786
|
+
** These routines extract type, size, and content information from
|
4787
|
+
** [protected sqlite3_value] objects. Protected sqlite3_value objects
|
4788
|
+
** are used to pass parameter information into implementation of
|
4789
|
+
** [application-defined SQL functions] and [virtual tables].
|
4318
4790
|
**
|
4319
4791
|
** These routines work only with [protected sqlite3_value] objects.
|
4320
4792
|
** Any attempt to use these routines on an [unprotected sqlite3_value]
|
4321
|
-
**
|
4793
|
+
** is not threadsafe.
|
4322
4794
|
**
|
4323
4795
|
** ^These routines work just like the corresponding [column access functions]
|
4324
4796
|
** except that these routines take a single [protected sqlite3_value] object
|
@@ -4329,6 +4801,24 @@ SQLITE_API SQLITE_DEPRECATED int SQLITE_STDCALL sqlite3_memory_alarm(void(*)(voi
|
|
4329
4801
|
** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces
|
4330
4802
|
** extract UTF-16 strings as big-endian and little-endian respectively.
|
4331
4803
|
**
|
4804
|
+
** ^If [sqlite3_value] object V was initialized
|
4805
|
+
** using [sqlite3_bind_pointer(S,I,P,X,D)] or [sqlite3_result_pointer(C,P,X,D)]
|
4806
|
+
** and if X and Y are strings that compare equal according to strcmp(X,Y),
|
4807
|
+
** then sqlite3_value_pointer(V,Y) will return the pointer P. ^Otherwise,
|
4808
|
+
** sqlite3_value_pointer(V,Y) returns a NULL. The sqlite3_bind_pointer()
|
4809
|
+
** routine is part of the [pointer passing interface] added for SQLite 3.20.0.
|
4810
|
+
**
|
4811
|
+
** ^(The sqlite3_value_type(V) interface returns the
|
4812
|
+
** [SQLITE_INTEGER | datatype code] for the initial datatype of the
|
4813
|
+
** [sqlite3_value] object V. The returned value is one of [SQLITE_INTEGER],
|
4814
|
+
** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL].)^
|
4815
|
+
** Other interfaces might change the datatype for an sqlite3_value object.
|
4816
|
+
** For example, if the datatype is initially SQLITE_INTEGER and
|
4817
|
+
** sqlite3_value_text(V) is called to extract a text value for that
|
4818
|
+
** integer, then subsequent calls to sqlite3_value_type(V) might return
|
4819
|
+
** SQLITE_TEXT. Whether or not a persistent internal datatype conversion
|
4820
|
+
** occurs is undefined and may change from one release of SQLite to the next.
|
4821
|
+
**
|
4332
4822
|
** ^(The sqlite3_value_numeric_type() interface attempts to apply
|
4333
4823
|
** numeric affinity to the value. This means that an attempt is
|
4334
4824
|
** made to convert the value to an integer or floating point. If
|
@@ -4346,18 +4836,19 @@ SQLITE_API SQLITE_DEPRECATED int SQLITE_STDCALL sqlite3_memory_alarm(void(*)(voi
|
|
4346
4836
|
** These routines must be called from the same thread as
|
4347
4837
|
** the SQL function that supplied the [sqlite3_value*] parameters.
|
4348
4838
|
*/
|
4349
|
-
SQLITE_API const void *
|
4350
|
-
SQLITE_API
|
4351
|
-
SQLITE_API int
|
4352
|
-
SQLITE_API
|
4353
|
-
SQLITE_API
|
4354
|
-
SQLITE_API
|
4355
|
-
SQLITE_API const
|
4356
|
-
SQLITE_API const void *
|
4357
|
-
SQLITE_API const void *
|
4358
|
-
SQLITE_API
|
4359
|
-
SQLITE_API int
|
4360
|
-
SQLITE_API int
|
4839
|
+
SQLITE_API const void *sqlite3_value_blob(sqlite3_value*);
|
4840
|
+
SQLITE_API double sqlite3_value_double(sqlite3_value*);
|
4841
|
+
SQLITE_API int sqlite3_value_int(sqlite3_value*);
|
4842
|
+
SQLITE_API sqlite3_int64 sqlite3_value_int64(sqlite3_value*);
|
4843
|
+
SQLITE_API void *sqlite3_value_pointer(sqlite3_value*, const char*);
|
4844
|
+
SQLITE_API const unsigned char *sqlite3_value_text(sqlite3_value*);
|
4845
|
+
SQLITE_API const void *sqlite3_value_text16(sqlite3_value*);
|
4846
|
+
SQLITE_API const void *sqlite3_value_text16le(sqlite3_value*);
|
4847
|
+
SQLITE_API const void *sqlite3_value_text16be(sqlite3_value*);
|
4848
|
+
SQLITE_API int sqlite3_value_bytes(sqlite3_value*);
|
4849
|
+
SQLITE_API int sqlite3_value_bytes16(sqlite3_value*);
|
4850
|
+
SQLITE_API int sqlite3_value_type(sqlite3_value*);
|
4851
|
+
SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*);
|
4361
4852
|
|
4362
4853
|
/*
|
4363
4854
|
** CAPI3REF: Finding The Subtype Of SQL Values
|
@@ -4368,12 +4859,8 @@ SQLITE_API int SQLITE_STDCALL sqlite3_value_numeric_type(sqlite3_value*);
|
|
4368
4859
|
** information can be used to pass a limited amount of context from
|
4369
4860
|
** one SQL function to another. Use the [sqlite3_result_subtype()]
|
4370
4861
|
** routine to set the subtype for the return value of an SQL function.
|
4371
|
-
**
|
4372
|
-
** SQLite makes no use of subtype itself. It merely passes the subtype
|
4373
|
-
** from the result of one [application-defined SQL function] into the
|
4374
|
-
** input of another.
|
4375
4862
|
*/
|
4376
|
-
SQLITE_API unsigned int
|
4863
|
+
SQLITE_API unsigned int sqlite3_value_subtype(sqlite3_value*);
|
4377
4864
|
|
4378
4865
|
/*
|
4379
4866
|
** CAPI3REF: Copy And Free SQL Values
|
@@ -4389,8 +4876,8 @@ SQLITE_API unsigned int SQLITE_STDCALL sqlite3_value_subtype(sqlite3_value*);
|
|
4389
4876
|
** previously obtained from [sqlite3_value_dup()]. ^If V is a NULL pointer
|
4390
4877
|
** then sqlite3_value_free(V) is a harmless no-op.
|
4391
4878
|
*/
|
4392
|
-
SQLITE_API
|
4393
|
-
SQLITE_API
|
4879
|
+
SQLITE_API sqlite3_value *sqlite3_value_dup(const sqlite3_value*);
|
4880
|
+
SQLITE_API void sqlite3_value_free(sqlite3_value*);
|
4394
4881
|
|
4395
4882
|
/*
|
4396
4883
|
** CAPI3REF: Obtain Aggregate Function Context
|
@@ -4435,7 +4922,7 @@ SQLITE_API SQLITE_EXPERIMENTAL void SQLITE_STDCALL sqlite3_value_free(sqlite3_va
|
|
4435
4922
|
** This routine must be called from the same thread in which
|
4436
4923
|
** the aggregate SQL function is running.
|
4437
4924
|
*/
|
4438
|
-
SQLITE_API void *
|
4925
|
+
SQLITE_API void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
|
4439
4926
|
|
4440
4927
|
/*
|
4441
4928
|
** CAPI3REF: User Data For Functions
|
@@ -4450,7 +4937,7 @@ SQLITE_API void *SQLITE_STDCALL sqlite3_aggregate_context(sqlite3_context*, int
|
|
4450
4937
|
** This routine must be called from the same thread in which
|
4451
4938
|
** the application-defined function is running.
|
4452
4939
|
*/
|
4453
|
-
SQLITE_API void *
|
4940
|
+
SQLITE_API void *sqlite3_user_data(sqlite3_context*);
|
4454
4941
|
|
4455
4942
|
/*
|
4456
4943
|
** CAPI3REF: Database Connection For Functions
|
@@ -4462,7 +4949,7 @@ SQLITE_API void *SQLITE_STDCALL sqlite3_user_data(sqlite3_context*);
|
|
4462
4949
|
** and [sqlite3_create_function16()] routines that originally
|
4463
4950
|
** registered the application defined function.
|
4464
4951
|
*/
|
4465
|
-
SQLITE_API sqlite3 *
|
4952
|
+
SQLITE_API sqlite3 *sqlite3_context_db_handle(sqlite3_context*);
|
4466
4953
|
|
4467
4954
|
/*
|
4468
4955
|
** CAPI3REF: Function Auxiliary Data
|
@@ -4479,10 +4966,11 @@ SQLITE_API sqlite3 *SQLITE_STDCALL sqlite3_context_db_handle(sqlite3_context*);
|
|
4479
4966
|
** the compiled regular expression can be reused on multiple
|
4480
4967
|
** invocations of the same function.
|
4481
4968
|
**
|
4482
|
-
** ^The sqlite3_get_auxdata() interface returns a pointer to the metadata
|
4483
|
-
** associated by the sqlite3_set_auxdata() function with the Nth argument
|
4484
|
-
** value to the application-defined function.
|
4485
|
-
**
|
4969
|
+
** ^The sqlite3_get_auxdata(C,N) interface returns a pointer to the metadata
|
4970
|
+
** associated by the sqlite3_set_auxdata(C,N,P,X) function with the Nth argument
|
4971
|
+
** value to the application-defined function. ^N is zero for the left-most
|
4972
|
+
** function argument. ^If there is no metadata
|
4973
|
+
** associated with the function argument, the sqlite3_get_auxdata(C,N) interface
|
4486
4974
|
** returns a NULL pointer.
|
4487
4975
|
**
|
4488
4976
|
** ^The sqlite3_set_auxdata(C,N,P,X) interface saves P as metadata for the N-th
|
@@ -4494,12 +4982,13 @@ SQLITE_API sqlite3 *SQLITE_STDCALL sqlite3_context_db_handle(sqlite3_context*);
|
|
4494
4982
|
** SQLite will invoke the destructor function X with parameter P exactly
|
4495
4983
|
** once, when the metadata is discarded.
|
4496
4984
|
** SQLite is free to discard the metadata at any time, including: <ul>
|
4497
|
-
** <li> when the corresponding function parameter changes
|
4498
|
-
** <li> when [sqlite3_reset()] or [sqlite3_finalize()] is called for the
|
4499
|
-
** SQL statement
|
4500
|
-
** <li> when sqlite3_set_auxdata() is invoked again on the same
|
4501
|
-
**
|
4502
|
-
**
|
4985
|
+
** <li> ^(when the corresponding function parameter changes)^, or
|
4986
|
+
** <li> ^(when [sqlite3_reset()] or [sqlite3_finalize()] is called for the
|
4987
|
+
** SQL statement)^, or
|
4988
|
+
** <li> ^(when sqlite3_set_auxdata() is invoked again on the same
|
4989
|
+
** parameter)^, or
|
4990
|
+
** <li> ^(during the original sqlite3_set_auxdata() call when a memory
|
4991
|
+
** allocation error occurs.)^ </ul>
|
4503
4992
|
**
|
4504
4993
|
** Note the last bullet in particular. The destructor X in
|
4505
4994
|
** sqlite3_set_auxdata(C,N,P,X) might be called immediately, before the
|
@@ -4512,11 +5001,15 @@ SQLITE_API sqlite3 *SQLITE_STDCALL sqlite3_context_db_handle(sqlite3_context*);
|
|
4512
5001
|
** function parameters that are compile-time constants, including literal
|
4513
5002
|
** values and [parameters] and expressions composed from the same.)^
|
4514
5003
|
**
|
5004
|
+
** The value of the N parameter to these interfaces should be non-negative.
|
5005
|
+
** Future enhancements may make use of negative N values to define new
|
5006
|
+
** kinds of function caching behavior.
|
5007
|
+
**
|
4515
5008
|
** These routines must be called from the same thread in which
|
4516
5009
|
** the SQL function is running.
|
4517
5010
|
*/
|
4518
|
-
SQLITE_API void *
|
4519
|
-
SQLITE_API void
|
5011
|
+
SQLITE_API void *sqlite3_get_auxdata(sqlite3_context*, int N);
|
5012
|
+
SQLITE_API void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));
|
4520
5013
|
|
4521
5014
|
|
4522
5015
|
/*
|
@@ -4635,7 +5128,7 @@ typedef void (*sqlite3_destructor_type)(void*);
|
|
4635
5128
|
** when it has finished using that result.
|
4636
5129
|
** ^If the 4th parameter to the sqlite3_result_text* interfaces
|
4637
5130
|
** or sqlite3_result_blob is the special constant SQLITE_TRANSIENT
|
4638
|
-
** then SQLite makes a copy of the result into space obtained
|
5131
|
+
** then SQLite makes a copy of the result into space obtained
|
4639
5132
|
** from [sqlite3_malloc()] before it returns.
|
4640
5133
|
**
|
4641
5134
|
** ^The sqlite3_result_value() interface sets the result of
|
@@ -4648,31 +5141,43 @@ typedef void (*sqlite3_destructor_type)(void*);
|
|
4648
5141
|
** [unprotected sqlite3_value] object is required, so either
|
4649
5142
|
** kind of [sqlite3_value] object can be used with this interface.
|
4650
5143
|
**
|
5144
|
+
** ^The sqlite3_result_pointer(C,P,T,D) interface sets the result to an
|
5145
|
+
** SQL NULL value, just like [sqlite3_result_null(C)], except that it
|
5146
|
+
** also associates the host-language pointer P or type T with that
|
5147
|
+
** NULL value such that the pointer can be retrieved within an
|
5148
|
+
** [application-defined SQL function] using [sqlite3_value_pointer()].
|
5149
|
+
** ^If the D parameter is not NULL, then it is a pointer to a destructor
|
5150
|
+
** for the P parameter. ^SQLite invokes D with P as its only argument
|
5151
|
+
** when SQLite is finished with P. The T parameter should be a static
|
5152
|
+
** string and preferably a string literal. The sqlite3_result_pointer()
|
5153
|
+
** routine is part of the [pointer passing interface] added for SQLite 3.20.0.
|
5154
|
+
**
|
4651
5155
|
** If these routines are called from within the different thread
|
4652
5156
|
** than the one containing the application-defined function that received
|
4653
5157
|
** the [sqlite3_context] pointer, the results are undefined.
|
4654
5158
|
*/
|
4655
|
-
SQLITE_API void
|
4656
|
-
SQLITE_API void
|
5159
|
+
SQLITE_API void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
|
5160
|
+
SQLITE_API void sqlite3_result_blob64(sqlite3_context*,const void*,
|
4657
5161
|
sqlite3_uint64,void(*)(void*));
|
4658
|
-
SQLITE_API void
|
4659
|
-
SQLITE_API void
|
4660
|
-
SQLITE_API void
|
4661
|
-
SQLITE_API void
|
4662
|
-
SQLITE_API void
|
4663
|
-
SQLITE_API void
|
4664
|
-
SQLITE_API void
|
4665
|
-
SQLITE_API void
|
4666
|
-
SQLITE_API void
|
4667
|
-
SQLITE_API void
|
4668
|
-
SQLITE_API void
|
5162
|
+
SQLITE_API void sqlite3_result_double(sqlite3_context*, double);
|
5163
|
+
SQLITE_API void sqlite3_result_error(sqlite3_context*, const char*, int);
|
5164
|
+
SQLITE_API void sqlite3_result_error16(sqlite3_context*, const void*, int);
|
5165
|
+
SQLITE_API void sqlite3_result_error_toobig(sqlite3_context*);
|
5166
|
+
SQLITE_API void sqlite3_result_error_nomem(sqlite3_context*);
|
5167
|
+
SQLITE_API void sqlite3_result_error_code(sqlite3_context*, int);
|
5168
|
+
SQLITE_API void sqlite3_result_int(sqlite3_context*, int);
|
5169
|
+
SQLITE_API void sqlite3_result_int64(sqlite3_context*, sqlite3_int64);
|
5170
|
+
SQLITE_API void sqlite3_result_null(sqlite3_context*);
|
5171
|
+
SQLITE_API void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
|
5172
|
+
SQLITE_API void sqlite3_result_text64(sqlite3_context*, const char*,sqlite3_uint64,
|
4669
5173
|
void(*)(void*), unsigned char encoding);
|
4670
|
-
SQLITE_API void
|
4671
|
-
SQLITE_API void
|
4672
|
-
SQLITE_API void
|
4673
|
-
SQLITE_API void
|
4674
|
-
SQLITE_API void
|
4675
|
-
SQLITE_API
|
5174
|
+
SQLITE_API void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
|
5175
|
+
SQLITE_API void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
|
5176
|
+
SQLITE_API void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
|
5177
|
+
SQLITE_API void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
|
5178
|
+
SQLITE_API void sqlite3_result_pointer(sqlite3_context*, void*,const char*,void(*)(void*));
|
5179
|
+
SQLITE_API void sqlite3_result_zeroblob(sqlite3_context*, int n);
|
5180
|
+
SQLITE_API int sqlite3_result_zeroblob64(sqlite3_context*, sqlite3_uint64 n);
|
4676
5181
|
|
4677
5182
|
|
4678
5183
|
/*
|
@@ -4687,7 +5192,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_result_zeroblob64(sqlite3_context*, sqlite
|
|
4687
5192
|
** The number of subtype bytes preserved by SQLite might increase
|
4688
5193
|
** in future releases of SQLite.
|
4689
5194
|
*/
|
4690
|
-
SQLITE_API void
|
5195
|
+
SQLITE_API void sqlite3_result_subtype(sqlite3_context*,unsigned int);
|
4691
5196
|
|
4692
5197
|
/*
|
4693
5198
|
** CAPI3REF: Define New Collating Sequences
|
@@ -4769,14 +5274,14 @@ SQLITE_API void SQLITE_STDCALL sqlite3_result_subtype(sqlite3_context*,unsigned
|
|
4769
5274
|
**
|
4770
5275
|
** See also: [sqlite3_collation_needed()] and [sqlite3_collation_needed16()].
|
4771
5276
|
*/
|
4772
|
-
SQLITE_API int
|
5277
|
+
SQLITE_API int sqlite3_create_collation(
|
4773
5278
|
sqlite3*,
|
4774
5279
|
const char *zName,
|
4775
5280
|
int eTextRep,
|
4776
5281
|
void *pArg,
|
4777
5282
|
int(*xCompare)(void*,int,const void*,int,const void*)
|
4778
5283
|
);
|
4779
|
-
SQLITE_API int
|
5284
|
+
SQLITE_API int sqlite3_create_collation_v2(
|
4780
5285
|
sqlite3*,
|
4781
5286
|
const char *zName,
|
4782
5287
|
int eTextRep,
|
@@ -4784,7 +5289,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_create_collation_v2(
|
|
4784
5289
|
int(*xCompare)(void*,int,const void*,int,const void*),
|
4785
5290
|
void(*xDestroy)(void*)
|
4786
5291
|
);
|
4787
|
-
SQLITE_API int
|
5292
|
+
SQLITE_API int sqlite3_create_collation16(
|
4788
5293
|
sqlite3*,
|
4789
5294
|
const void *zName,
|
4790
5295
|
int eTextRep,
|
@@ -4819,12 +5324,12 @@ SQLITE_API int SQLITE_STDCALL sqlite3_create_collation16(
|
|
4819
5324
|
** [sqlite3_create_collation()], [sqlite3_create_collation16()], or
|
4820
5325
|
** [sqlite3_create_collation_v2()].
|
4821
5326
|
*/
|
4822
|
-
SQLITE_API int
|
5327
|
+
SQLITE_API int sqlite3_collation_needed(
|
4823
5328
|
sqlite3*,
|
4824
5329
|
void*,
|
4825
5330
|
void(*)(void*,sqlite3*,int eTextRep,const char*)
|
4826
5331
|
);
|
4827
|
-
SQLITE_API int
|
5332
|
+
SQLITE_API int sqlite3_collation_needed16(
|
4828
5333
|
sqlite3*,
|
4829
5334
|
void*,
|
4830
5335
|
void(*)(void*,sqlite3*,int eTextRep,const void*)
|
@@ -4838,11 +5343,11 @@ SQLITE_API int SQLITE_STDCALL sqlite3_collation_needed16(
|
|
4838
5343
|
** The code to implement this API is not available in the public release
|
4839
5344
|
** of SQLite.
|
4840
5345
|
*/
|
4841
|
-
SQLITE_API int
|
5346
|
+
SQLITE_API int sqlite3_key(
|
4842
5347
|
sqlite3 *db, /* Database to be rekeyed */
|
4843
5348
|
const void *pKey, int nKey /* The key */
|
4844
5349
|
);
|
4845
|
-
SQLITE_API int
|
5350
|
+
SQLITE_API int sqlite3_key_v2(
|
4846
5351
|
sqlite3 *db, /* Database to be rekeyed */
|
4847
5352
|
const char *zDbName, /* Name of the database */
|
4848
5353
|
const void *pKey, int nKey /* The key */
|
@@ -4856,11 +5361,11 @@ SQLITE_API int SQLITE_STDCALL sqlite3_key_v2(
|
|
4856
5361
|
** The code to implement this API is not available in the public release
|
4857
5362
|
** of SQLite.
|
4858
5363
|
*/
|
4859
|
-
SQLITE_API int
|
5364
|
+
SQLITE_API int sqlite3_rekey(
|
4860
5365
|
sqlite3 *db, /* Database to be rekeyed */
|
4861
5366
|
const void *pKey, int nKey /* The new key */
|
4862
5367
|
);
|
4863
|
-
SQLITE_API int
|
5368
|
+
SQLITE_API int sqlite3_rekey_v2(
|
4864
5369
|
sqlite3 *db, /* Database to be rekeyed */
|
4865
5370
|
const char *zDbName, /* Name of the database */
|
4866
5371
|
const void *pKey, int nKey /* The new key */
|
@@ -4870,7 +5375,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_rekey_v2(
|
|
4870
5375
|
** Specify the activation key for a SEE database. Unless
|
4871
5376
|
** activated, none of the SEE routines will work.
|
4872
5377
|
*/
|
4873
|
-
SQLITE_API void
|
5378
|
+
SQLITE_API void sqlite3_activate_see(
|
4874
5379
|
const char *zPassPhrase /* Activation phrase */
|
4875
5380
|
);
|
4876
5381
|
#endif
|
@@ -4880,7 +5385,7 @@ SQLITE_API void SQLITE_STDCALL sqlite3_activate_see(
|
|
4880
5385
|
** Specify the activation key for a CEROD database. Unless
|
4881
5386
|
** activated, none of the CEROD routines will work.
|
4882
5387
|
*/
|
4883
|
-
SQLITE_API void
|
5388
|
+
SQLITE_API void sqlite3_activate_cerod(
|
4884
5389
|
const char *zPassPhrase /* Activation phrase */
|
4885
5390
|
);
|
4886
5391
|
#endif
|
@@ -4902,7 +5407,7 @@ SQLITE_API void SQLITE_STDCALL sqlite3_activate_cerod(
|
|
4902
5407
|
** all, then the behavior of sqlite3_sleep() may deviate from the description
|
4903
5408
|
** in the previous paragraphs.
|
4904
5409
|
*/
|
4905
|
-
SQLITE_API int
|
5410
|
+
SQLITE_API int sqlite3_sleep(int);
|
4906
5411
|
|
4907
5412
|
/*
|
4908
5413
|
** CAPI3REF: Name Of The Folder Holding Temporary Files
|
@@ -5021,7 +5526,7 @@ SQLITE_API SQLITE_EXTERN char *sqlite3_data_directory;
|
|
5021
5526
|
** connection while this routine is running, then the return value
|
5022
5527
|
** is undefined.
|
5023
5528
|
*/
|
5024
|
-
SQLITE_API int
|
5529
|
+
SQLITE_API int sqlite3_get_autocommit(sqlite3*);
|
5025
5530
|
|
5026
5531
|
/*
|
5027
5532
|
** CAPI3REF: Find The Database Handle Of A Prepared Statement
|
@@ -5034,7 +5539,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_get_autocommit(sqlite3*);
|
|
5034
5539
|
** to the [sqlite3_prepare_v2()] call (or its variants) that was used to
|
5035
5540
|
** create the statement in the first place.
|
5036
5541
|
*/
|
5037
|
-
SQLITE_API sqlite3 *
|
5542
|
+
SQLITE_API sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
|
5038
5543
|
|
5039
5544
|
/*
|
5040
5545
|
** CAPI3REF: Return The Filename For A Database Connection
|
@@ -5051,7 +5556,7 @@ SQLITE_API sqlite3 *SQLITE_STDCALL sqlite3_db_handle(sqlite3_stmt*);
|
|
5051
5556
|
** will be an absolute pathname, even if the filename used
|
5052
5557
|
** to open the database originally was a URI or relative pathname.
|
5053
5558
|
*/
|
5054
|
-
SQLITE_API const char *
|
5559
|
+
SQLITE_API const char *sqlite3_db_filename(sqlite3 *db, const char *zDbName);
|
5055
5560
|
|
5056
5561
|
/*
|
5057
5562
|
** CAPI3REF: Determine if a database is read-only
|
@@ -5061,7 +5566,7 @@ SQLITE_API const char *SQLITE_STDCALL sqlite3_db_filename(sqlite3 *db, const cha
|
|
5061
5566
|
** of connection D is read-only, 0 if it is read/write, or -1 if N is not
|
5062
5567
|
** the name of a database on connection D.
|
5063
5568
|
*/
|
5064
|
-
SQLITE_API int
|
5569
|
+
SQLITE_API int sqlite3_db_readonly(sqlite3 *db, const char *zDbName);
|
5065
5570
|
|
5066
5571
|
/*
|
5067
5572
|
** CAPI3REF: Find the next prepared statement
|
@@ -5077,7 +5582,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_db_readonly(sqlite3 *db, const char *zDbNa
|
|
5077
5582
|
** [sqlite3_next_stmt(D,S)] must refer to an open database
|
5078
5583
|
** connection and in particular must not be a NULL pointer.
|
5079
5584
|
*/
|
5080
|
-
SQLITE_API sqlite3_stmt *
|
5585
|
+
SQLITE_API sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt);
|
5081
5586
|
|
5082
5587
|
/*
|
5083
5588
|
** CAPI3REF: Commit And Rollback Notification Callbacks
|
@@ -5126,8 +5631,8 @@ SQLITE_API sqlite3_stmt *SQLITE_STDCALL sqlite3_next_stmt(sqlite3 *pDb, sqlite3_
|
|
5126
5631
|
**
|
5127
5632
|
** See also the [sqlite3_update_hook()] interface.
|
5128
5633
|
*/
|
5129
|
-
SQLITE_API void *
|
5130
|
-
SQLITE_API void *
|
5634
|
+
SQLITE_API void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
|
5635
|
+
SQLITE_API void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
|
5131
5636
|
|
5132
5637
|
/*
|
5133
5638
|
** CAPI3REF: Data Change Notification Callbacks
|
@@ -5136,7 +5641,7 @@ SQLITE_API void *SQLITE_STDCALL sqlite3_rollback_hook(sqlite3*, void(*)(void *),
|
|
5136
5641
|
** ^The sqlite3_update_hook() interface registers a callback function
|
5137
5642
|
** with the [database connection] identified by the first argument
|
5138
5643
|
** to be invoked whenever a row is updated, inserted or deleted in
|
5139
|
-
** a rowid table.
|
5644
|
+
** a [rowid table].
|
5140
5645
|
** ^Any callback set by a previous call to this function
|
5141
5646
|
** for the same database connection is overridden.
|
5142
5647
|
**
|
@@ -5157,7 +5662,7 @@ SQLITE_API void *SQLITE_STDCALL sqlite3_rollback_hook(sqlite3*, void(*)(void *),
|
|
5157
5662
|
** ^The update hook is not invoked when [WITHOUT ROWID] tables are modified.
|
5158
5663
|
**
|
5159
5664
|
** ^In the current implementation, the update hook
|
5160
|
-
** is not invoked when
|
5665
|
+
** is not invoked when conflicting rows are deleted because of an
|
5161
5666
|
** [ON CONFLICT | ON CONFLICT REPLACE] clause. ^Nor is the update hook
|
5162
5667
|
** invoked when rows are deleted using the [truncate optimization].
|
5163
5668
|
** The exceptions defined in this paragraph might change in a future
|
@@ -5175,10 +5680,10 @@ SQLITE_API void *SQLITE_STDCALL sqlite3_rollback_hook(sqlite3*, void(*)(void *),
|
|
5175
5680
|
** on the same [database connection] D, or NULL for
|
5176
5681
|
** the first call on D.
|
5177
5682
|
**
|
5178
|
-
** See also the [sqlite3_commit_hook()]
|
5179
|
-
** interfaces.
|
5683
|
+
** See also the [sqlite3_commit_hook()], [sqlite3_rollback_hook()],
|
5684
|
+
** and [sqlite3_preupdate_hook()] interfaces.
|
5180
5685
|
*/
|
5181
|
-
SQLITE_API void *
|
5686
|
+
SQLITE_API void *sqlite3_update_hook(
|
5182
5687
|
sqlite3*,
|
5183
5688
|
void(*)(void *,int ,char const *,char const *,sqlite3_int64),
|
5184
5689
|
void*
|
@@ -5193,7 +5698,8 @@ SQLITE_API void *SQLITE_STDCALL sqlite3_update_hook(
|
|
5193
5698
|
** and disabled if the argument is false.)^
|
5194
5699
|
**
|
5195
5700
|
** ^Cache sharing is enabled and disabled for an entire process.
|
5196
|
-
** This is a change as of SQLite version 3.5.0.
|
5701
|
+
** This is a change as of SQLite [version 3.5.0] ([dateof:3.5.0]).
|
5702
|
+
** In prior versions of SQLite,
|
5197
5703
|
** sharing was enabled or disabled for each thread separately.
|
5198
5704
|
**
|
5199
5705
|
** ^(The cache sharing mode set by this interface effects all subsequent
|
@@ -5218,7 +5724,7 @@ SQLITE_API void *SQLITE_STDCALL sqlite3_update_hook(
|
|
5218
5724
|
**
|
5219
5725
|
** See Also: [SQLite Shared-Cache Mode]
|
5220
5726
|
*/
|
5221
|
-
SQLITE_API int
|
5727
|
+
SQLITE_API int sqlite3_enable_shared_cache(int);
|
5222
5728
|
|
5223
5729
|
/*
|
5224
5730
|
** CAPI3REF: Attempt To Free Heap Memory
|
@@ -5234,7 +5740,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_enable_shared_cache(int);
|
|
5234
5740
|
**
|
5235
5741
|
** See also: [sqlite3_db_release_memory()]
|
5236
5742
|
*/
|
5237
|
-
SQLITE_API int
|
5743
|
+
SQLITE_API int sqlite3_release_memory(int);
|
5238
5744
|
|
5239
5745
|
/*
|
5240
5746
|
** CAPI3REF: Free Memory Used By A Database Connection
|
@@ -5248,7 +5754,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_release_memory(int);
|
|
5248
5754
|
**
|
5249
5755
|
** See also: [sqlite3_release_memory()]
|
5250
5756
|
*/
|
5251
|
-
SQLITE_API int
|
5757
|
+
SQLITE_API int sqlite3_db_release_memory(sqlite3*);
|
5252
5758
|
|
5253
5759
|
/*
|
5254
5760
|
** CAPI3REF: Impose A Limit On Heap Size
|
@@ -5287,7 +5793,8 @@ SQLITE_API int SQLITE_STDCALL sqlite3_db_release_memory(sqlite3*);
|
|
5287
5793
|
** from the heap.
|
5288
5794
|
** </ul>)^
|
5289
5795
|
**
|
5290
|
-
** Beginning with SQLite version 3.7.3,
|
5796
|
+
** Beginning with SQLite [version 3.7.3] ([dateof:3.7.3]),
|
5797
|
+
** the soft heap limit is enforced
|
5291
5798
|
** regardless of whether or not the [SQLITE_ENABLE_MEMORY_MANAGEMENT]
|
5292
5799
|
** compile-time option is invoked. With [SQLITE_ENABLE_MEMORY_MANAGEMENT],
|
5293
5800
|
** the soft heap limit is enforced on every memory allocation. Without
|
@@ -5300,7 +5807,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_db_release_memory(sqlite3*);
|
|
5300
5807
|
** The circumstances under which SQLite will enforce the soft heap limit may
|
5301
5808
|
** changes in future releases of SQLite.
|
5302
5809
|
*/
|
5303
|
-
SQLITE_API sqlite3_int64
|
5810
|
+
SQLITE_API sqlite3_int64 sqlite3_soft_heap_limit64(sqlite3_int64 N);
|
5304
5811
|
|
5305
5812
|
/*
|
5306
5813
|
** CAPI3REF: Deprecated Soft Heap Limit Interface
|
@@ -5311,7 +5818,7 @@ SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_soft_heap_limit64(sqlite3_int64
|
|
5311
5818
|
** only. All new applications should use the
|
5312
5819
|
** [sqlite3_soft_heap_limit64()] interface rather than this one.
|
5313
5820
|
*/
|
5314
|
-
SQLITE_API SQLITE_DEPRECATED void
|
5821
|
+
SQLITE_API SQLITE_DEPRECATED void sqlite3_soft_heap_limit(int N);
|
5315
5822
|
|
5316
5823
|
|
5317
5824
|
/*
|
@@ -5326,9 +5833,11 @@ SQLITE_API SQLITE_DEPRECATED void SQLITE_STDCALL sqlite3_soft_heap_limit(int N);
|
|
5326
5833
|
** column exists. ^The sqlite3_table_column_metadata() interface returns
|
5327
5834
|
** SQLITE_ERROR and if the specified column does not exist.
|
5328
5835
|
** ^If the column-name parameter to sqlite3_table_column_metadata() is a
|
5329
|
-
** NULL pointer, then this routine simply checks for the
|
5836
|
+
** NULL pointer, then this routine simply checks for the existence of the
|
5330
5837
|
** table and returns SQLITE_OK if the table exists and SQLITE_ERROR if it
|
5331
|
-
** does not.
|
5838
|
+
** does not. If the table name parameter T in a call to
|
5839
|
+
** sqlite3_table_column_metadata(X,D,T,C,...) is NULL then the result is
|
5840
|
+
** undefined behavior.
|
5332
5841
|
**
|
5333
5842
|
** ^The column is identified by the second, third and fourth parameters to
|
5334
5843
|
** this function. ^(The second parameter is either the name of the database
|
@@ -5381,7 +5890,7 @@ SQLITE_API SQLITE_DEPRECATED void SQLITE_STDCALL sqlite3_soft_heap_limit(int N);
|
|
5381
5890
|
** parsed, if that has not already been done, and returns an error if
|
5382
5891
|
** any errors are encountered while loading the schema.
|
5383
5892
|
*/
|
5384
|
-
SQLITE_API int
|
5893
|
+
SQLITE_API int sqlite3_table_column_metadata(
|
5385
5894
|
sqlite3 *db, /* Connection handle */
|
5386
5895
|
const char *zDbName, /* Database name or NULL */
|
5387
5896
|
const char *zTableName, /* Table name */
|
@@ -5423,12 +5932,21 @@ SQLITE_API int SQLITE_STDCALL sqlite3_table_column_metadata(
|
|
5423
5932
|
** should free this memory by calling [sqlite3_free()].
|
5424
5933
|
**
|
5425
5934
|
** ^Extension loading must be enabled using
|
5426
|
-
** [sqlite3_enable_load_extension()]
|
5935
|
+
** [sqlite3_enable_load_extension()] or
|
5936
|
+
** [sqlite3_db_config](db,[SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION],1,NULL)
|
5937
|
+
** prior to calling this API,
|
5427
5938
|
** otherwise an error will be returned.
|
5428
5939
|
**
|
5940
|
+
** <b>Security warning:</b> It is recommended that the
|
5941
|
+
** [SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION] method be used to enable only this
|
5942
|
+
** interface. The use of the [sqlite3_enable_load_extension()] interface
|
5943
|
+
** should be avoided. This will keep the SQL function [load_extension()]
|
5944
|
+
** disabled and prevent SQL injections from giving attackers
|
5945
|
+
** access to extension loading capabilities.
|
5946
|
+
**
|
5429
5947
|
** See also the [load_extension() SQL function].
|
5430
5948
|
*/
|
5431
|
-
SQLITE_API int
|
5949
|
+
SQLITE_API int sqlite3_load_extension(
|
5432
5950
|
sqlite3 *db, /* Load the extension into this database connection */
|
5433
5951
|
const char *zFile, /* Name of the shared library containing extension */
|
5434
5952
|
const char *zProc, /* Entry point. Derived from zFile if 0 */
|
@@ -5448,8 +5966,19 @@ SQLITE_API int SQLITE_STDCALL sqlite3_load_extension(
|
|
5448
5966
|
** ^Call the sqlite3_enable_load_extension() routine with onoff==1
|
5449
5967
|
** to turn extension loading on and call it with onoff==0 to turn
|
5450
5968
|
** it back off again.
|
5969
|
+
**
|
5970
|
+
** ^This interface enables or disables both the C-API
|
5971
|
+
** [sqlite3_load_extension()] and the SQL function [load_extension()].
|
5972
|
+
** ^(Use [sqlite3_db_config](db,[SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION],..)
|
5973
|
+
** to enable or disable only the C-API.)^
|
5974
|
+
**
|
5975
|
+
** <b>Security warning:</b> It is recommended that extension loading
|
5976
|
+
** be disabled using the [SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION] method
|
5977
|
+
** rather than this interface, so the [load_extension()] SQL function
|
5978
|
+
** remains disabled. This will prevent SQL injections from giving attackers
|
5979
|
+
** access to extension loading capabilities.
|
5451
5980
|
*/
|
5452
|
-
SQLITE_API int
|
5981
|
+
SQLITE_API int sqlite3_enable_load_extension(sqlite3 *db, int onoff);
|
5453
5982
|
|
5454
5983
|
/*
|
5455
5984
|
** CAPI3REF: Automatically Load Statically Linked Extensions
|
@@ -5461,7 +5990,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_enable_load_extension(sqlite3 *db, int ono
|
|
5461
5990
|
**
|
5462
5991
|
** ^(Even though the function prototype shows that xEntryPoint() takes
|
5463
5992
|
** no arguments and returns void, SQLite invokes xEntryPoint() with three
|
5464
|
-
** arguments and expects
|
5993
|
+
** arguments and expects an integer result as if the signature of the
|
5465
5994
|
** entry point where as follows:
|
5466
5995
|
**
|
5467
5996
|
** <blockquote><pre>
|
@@ -5487,7 +6016,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_enable_load_extension(sqlite3 *db, int ono
|
|
5487
6016
|
** See also: [sqlite3_reset_auto_extension()]
|
5488
6017
|
** and [sqlite3_cancel_auto_extension()]
|
5489
6018
|
*/
|
5490
|
-
SQLITE_API int
|
6019
|
+
SQLITE_API int sqlite3_auto_extension(void(*xEntryPoint)(void));
|
5491
6020
|
|
5492
6021
|
/*
|
5493
6022
|
** CAPI3REF: Cancel Automatic Extension Loading
|
@@ -5499,7 +6028,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_auto_extension(void (*xEntryPoint)(void));
|
|
5499
6028
|
** unregistered and it returns 0 if X was not on the list of initialization
|
5500
6029
|
** routines.
|
5501
6030
|
*/
|
5502
|
-
SQLITE_API int
|
6031
|
+
SQLITE_API int sqlite3_cancel_auto_extension(void(*xEntryPoint)(void));
|
5503
6032
|
|
5504
6033
|
/*
|
5505
6034
|
** CAPI3REF: Reset Automatic Extension Loading
|
@@ -5507,7 +6036,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_cancel_auto_extension(void (*xEntryPoint)(
|
|
5507
6036
|
** ^This interface disables all automatic extensions previously
|
5508
6037
|
** registered using [sqlite3_auto_extension()].
|
5509
6038
|
*/
|
5510
|
-
SQLITE_API void
|
6039
|
+
SQLITE_API void sqlite3_reset_auto_extension(void);
|
5511
6040
|
|
5512
6041
|
/*
|
5513
6042
|
** The interface to the virtual-table mechanism is currently considered
|
@@ -5609,6 +6138,17 @@ struct sqlite3_module {
|
|
5609
6138
|
** ^Information about the ORDER BY clause is stored in aOrderBy[].
|
5610
6139
|
** ^Each term of aOrderBy records a column of the ORDER BY clause.
|
5611
6140
|
**
|
6141
|
+
** The colUsed field indicates which columns of the virtual table may be
|
6142
|
+
** required by the current scan. Virtual table columns are numbered from
|
6143
|
+
** zero in the order in which they appear within the CREATE TABLE statement
|
6144
|
+
** passed to sqlite3_declare_vtab(). For the first 63 columns (columns 0-62),
|
6145
|
+
** the corresponding bit is set within the colUsed mask if the column may be
|
6146
|
+
** required by SQLite. If the table has at least 64 columns and any column
|
6147
|
+
** to the right of the first 63 is required, then bit 63 of colUsed is also
|
6148
|
+
** set. In other words, column iCol may be required if the expression
|
6149
|
+
** (colUsed & ((sqlite3_uint64)1 << (iCol>=63 ? 63 : iCol))) evaluates to
|
6150
|
+
** non-zero.
|
6151
|
+
**
|
5612
6152
|
** The [xBestIndex] method must fill aConstraintUsage[] with information
|
5613
6153
|
** about what parameters to pass to xFilter. ^If argvIndex>0 then
|
5614
6154
|
** the right-hand side of the corresponding aConstraint[] is evaluated
|
@@ -5650,13 +6190,15 @@ struct sqlite3_module {
|
|
5650
6190
|
** the xUpdate method are automatically rolled back by SQLite.
|
5651
6191
|
**
|
5652
6192
|
** IMPORTANT: The estimatedRows field was added to the sqlite3_index_info
|
5653
|
-
** structure for SQLite version 3.8.2.
|
6193
|
+
** structure for SQLite [version 3.8.2] ([dateof:3.8.2]).
|
6194
|
+
** If a virtual table extension is
|
5654
6195
|
** used with an SQLite version earlier than 3.8.2, the results of attempting
|
5655
6196
|
** to read or write the estimatedRows field are undefined (but are likely
|
5656
6197
|
** to included crashing the application). The estimatedRows field should
|
5657
6198
|
** therefore only be used if [sqlite3_libversion_number()] returns a
|
5658
6199
|
** value greater than or equal to 3008002. Similarly, the idxFlags field
|
5659
|
-
** was added for version 3.9.0.
|
6200
|
+
** was added for [version 3.9.0] ([dateof:3.9.0]).
|
6201
|
+
** It may therefore only be used if
|
5660
6202
|
** sqlite3_libversion_number() returns a value greater than or equal to
|
5661
6203
|
** 3009000.
|
5662
6204
|
*/
|
@@ -5664,7 +6206,7 @@ struct sqlite3_index_info {
|
|
5664
6206
|
/* Inputs */
|
5665
6207
|
int nConstraint; /* Number of entries in aConstraint */
|
5666
6208
|
struct sqlite3_index_constraint {
|
5667
|
-
int iColumn; /* Column
|
6209
|
+
int iColumn; /* Column constrained. -1 for ROWID */
|
5668
6210
|
unsigned char op; /* Constraint operator */
|
5669
6211
|
unsigned char usable; /* True if this constraint is usable */
|
5670
6212
|
int iTermOffset; /* Used internally - xBestIndex should ignore */
|
@@ -5688,6 +6230,8 @@ struct sqlite3_index_info {
|
|
5688
6230
|
sqlite3_int64 estimatedRows; /* Estimated number of rows returned */
|
5689
6231
|
/* Fields below are only available in SQLite 3.9.0 and later */
|
5690
6232
|
int idxFlags; /* Mask of SQLITE_INDEX_SCAN_* flags */
|
6233
|
+
/* Fields below are only available in SQLite 3.10.0 and later */
|
6234
|
+
sqlite3_uint64 colUsed; /* Input: Mask of columns used by statement */
|
5691
6235
|
};
|
5692
6236
|
|
5693
6237
|
/*
|
@@ -5703,12 +6247,20 @@ struct sqlite3_index_info {
|
|
5703
6247
|
** an operator that is part of a constraint term in the wHERE clause of
|
5704
6248
|
** a query that uses a [virtual table].
|
5705
6249
|
*/
|
5706
|
-
#define SQLITE_INDEX_CONSTRAINT_EQ
|
5707
|
-
#define SQLITE_INDEX_CONSTRAINT_GT
|
5708
|
-
#define SQLITE_INDEX_CONSTRAINT_LE
|
5709
|
-
#define SQLITE_INDEX_CONSTRAINT_LT
|
5710
|
-
#define SQLITE_INDEX_CONSTRAINT_GE
|
5711
|
-
#define SQLITE_INDEX_CONSTRAINT_MATCH
|
6250
|
+
#define SQLITE_INDEX_CONSTRAINT_EQ 2
|
6251
|
+
#define SQLITE_INDEX_CONSTRAINT_GT 4
|
6252
|
+
#define SQLITE_INDEX_CONSTRAINT_LE 8
|
6253
|
+
#define SQLITE_INDEX_CONSTRAINT_LT 16
|
6254
|
+
#define SQLITE_INDEX_CONSTRAINT_GE 32
|
6255
|
+
#define SQLITE_INDEX_CONSTRAINT_MATCH 64
|
6256
|
+
#define SQLITE_INDEX_CONSTRAINT_LIKE 65
|
6257
|
+
#define SQLITE_INDEX_CONSTRAINT_GLOB 66
|
6258
|
+
#define SQLITE_INDEX_CONSTRAINT_REGEXP 67
|
6259
|
+
#define SQLITE_INDEX_CONSTRAINT_NE 68
|
6260
|
+
#define SQLITE_INDEX_CONSTRAINT_ISNOT 69
|
6261
|
+
#define SQLITE_INDEX_CONSTRAINT_ISNOTNULL 70
|
6262
|
+
#define SQLITE_INDEX_CONSTRAINT_ISNULL 71
|
6263
|
+
#define SQLITE_INDEX_CONSTRAINT_IS 72
|
5712
6264
|
|
5713
6265
|
/*
|
5714
6266
|
** CAPI3REF: Register A Virtual Table Implementation
|
@@ -5736,13 +6288,13 @@ struct sqlite3_index_info {
|
|
5736
6288
|
** interface is equivalent to sqlite3_create_module_v2() with a NULL
|
5737
6289
|
** destructor.
|
5738
6290
|
*/
|
5739
|
-
SQLITE_API int
|
6291
|
+
SQLITE_API int sqlite3_create_module(
|
5740
6292
|
sqlite3 *db, /* SQLite connection to register module with */
|
5741
6293
|
const char *zName, /* Name of the module */
|
5742
6294
|
const sqlite3_module *p, /* Methods for the module */
|
5743
6295
|
void *pClientData /* Client data for xCreate/xConnect */
|
5744
6296
|
);
|
5745
|
-
SQLITE_API int
|
6297
|
+
SQLITE_API int sqlite3_create_module_v2(
|
5746
6298
|
sqlite3 *db, /* SQLite connection to register module with */
|
5747
6299
|
const char *zName, /* Name of the module */
|
5748
6300
|
const sqlite3_module *p, /* Methods for the module */
|
@@ -5805,7 +6357,7 @@ struct sqlite3_vtab_cursor {
|
|
5805
6357
|
** to declare the format (the names and datatypes of the columns) of
|
5806
6358
|
** the virtual tables they implement.
|
5807
6359
|
*/
|
5808
|
-
SQLITE_API int
|
6360
|
+
SQLITE_API int sqlite3_declare_vtab(sqlite3*, const char *zSQL);
|
5809
6361
|
|
5810
6362
|
/*
|
5811
6363
|
** CAPI3REF: Overload A Function For A Virtual Table
|
@@ -5824,7 +6376,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_declare_vtab(sqlite3*, const char *zSQL);
|
|
5824
6376
|
** purpose is to be a placeholder function that can be overloaded
|
5825
6377
|
** by a [virtual table].
|
5826
6378
|
*/
|
5827
|
-
SQLITE_API int
|
6379
|
+
SQLITE_API int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg);
|
5828
6380
|
|
5829
6381
|
/*
|
5830
6382
|
** The interface to the virtual-table mechanism defined above (back up
|
@@ -5899,6 +6451,12 @@ typedef struct sqlite3_blob sqlite3_blob;
|
|
5899
6451
|
** [database connection] error code and message accessible via
|
5900
6452
|
** [sqlite3_errcode()] and [sqlite3_errmsg()] and related functions.
|
5901
6453
|
**
|
6454
|
+
** A BLOB referenced by sqlite3_blob_open() may be read using the
|
6455
|
+
** [sqlite3_blob_read()] interface and modified by using
|
6456
|
+
** [sqlite3_blob_write()]. The [BLOB handle] can be moved to a
|
6457
|
+
** different row of the same table using the [sqlite3_blob_reopen()]
|
6458
|
+
** interface. However, the column, table, or database of a [BLOB handle]
|
6459
|
+
** cannot be changed after the [BLOB handle] is opened.
|
5902
6460
|
**
|
5903
6461
|
** ^(If the row that a BLOB handle points to is modified by an
|
5904
6462
|
** [UPDATE], [DELETE], or by [ON CONFLICT] side-effects
|
@@ -5922,8 +6480,12 @@ typedef struct sqlite3_blob sqlite3_blob;
|
|
5922
6480
|
**
|
5923
6481
|
** To avoid a resource leak, every open [BLOB handle] should eventually
|
5924
6482
|
** be released by a call to [sqlite3_blob_close()].
|
6483
|
+
**
|
6484
|
+
** See also: [sqlite3_blob_close()],
|
6485
|
+
** [sqlite3_blob_reopen()], [sqlite3_blob_read()],
|
6486
|
+
** [sqlite3_blob_bytes()], [sqlite3_blob_write()].
|
5925
6487
|
*/
|
5926
|
-
SQLITE_API int
|
6488
|
+
SQLITE_API int sqlite3_blob_open(
|
5927
6489
|
sqlite3*,
|
5928
6490
|
const char *zDb,
|
5929
6491
|
const char *zTable,
|
@@ -5937,11 +6499,11 @@ SQLITE_API int SQLITE_STDCALL sqlite3_blob_open(
|
|
5937
6499
|
** CAPI3REF: Move a BLOB Handle to a New Row
|
5938
6500
|
** METHOD: sqlite3_blob
|
5939
6501
|
**
|
5940
|
-
** ^This function is used to move an existing
|
6502
|
+
** ^This function is used to move an existing [BLOB handle] so that it points
|
5941
6503
|
** to a different row of the same database table. ^The new row is identified
|
5942
6504
|
** by the rowid value passed as the second argument. Only the row can be
|
5943
6505
|
** changed. ^The database, table and column on which the blob handle is open
|
5944
|
-
** remain the same. Moving an existing
|
6506
|
+
** remain the same. Moving an existing [BLOB handle] to a new row is
|
5945
6507
|
** faster than closing the existing handle and opening a new one.
|
5946
6508
|
**
|
5947
6509
|
** ^(The new row must meet the same criteria as for [sqlite3_blob_open()] -
|
@@ -5956,7 +6518,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_blob_open(
|
|
5956
6518
|
**
|
5957
6519
|
** ^This function sets the database handle error code and message.
|
5958
6520
|
*/
|
5959
|
-
SQLITE_API int
|
6521
|
+
SQLITE_API int sqlite3_blob_reopen(sqlite3_blob *, sqlite3_int64);
|
5960
6522
|
|
5961
6523
|
/*
|
5962
6524
|
** CAPI3REF: Close A BLOB Handle
|
@@ -5979,7 +6541,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_blob_reopen(sqlite3_blob *, sqlite3_int64)
|
|
5979
6541
|
** is passed a valid open blob handle, the values returned by the
|
5980
6542
|
** sqlite3_errcode() and sqlite3_errmsg() functions are set before returning.
|
5981
6543
|
*/
|
5982
|
-
SQLITE_API int
|
6544
|
+
SQLITE_API int sqlite3_blob_close(sqlite3_blob *);
|
5983
6545
|
|
5984
6546
|
/*
|
5985
6547
|
** CAPI3REF: Return The Size Of An Open BLOB
|
@@ -5995,7 +6557,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_blob_close(sqlite3_blob *);
|
|
5995
6557
|
** been closed by [sqlite3_blob_close()]. Passing any other pointer in
|
5996
6558
|
** to this routine results in undefined and probably undesirable behavior.
|
5997
6559
|
*/
|
5998
|
-
SQLITE_API int
|
6560
|
+
SQLITE_API int sqlite3_blob_bytes(sqlite3_blob *);
|
5999
6561
|
|
6000
6562
|
/*
|
6001
6563
|
** CAPI3REF: Read Data From A BLOB Incrementally
|
@@ -6024,7 +6586,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_blob_bytes(sqlite3_blob *);
|
|
6024
6586
|
**
|
6025
6587
|
** See also: [sqlite3_blob_write()].
|
6026
6588
|
*/
|
6027
|
-
SQLITE_API int
|
6589
|
+
SQLITE_API int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);
|
6028
6590
|
|
6029
6591
|
/*
|
6030
6592
|
** CAPI3REF: Write Data Into A BLOB Incrementally
|
@@ -6066,7 +6628,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_blob_read(sqlite3_blob *, void *Z, int N,
|
|
6066
6628
|
**
|
6067
6629
|
** See also: [sqlite3_blob_read()].
|
6068
6630
|
*/
|
6069
|
-
SQLITE_API int
|
6631
|
+
SQLITE_API int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);
|
6070
6632
|
|
6071
6633
|
/*
|
6072
6634
|
** CAPI3REF: Virtual File System Objects
|
@@ -6097,9 +6659,9 @@ SQLITE_API int SQLITE_STDCALL sqlite3_blob_write(sqlite3_blob *, const void *z,
|
|
6097
6659
|
** ^(If the default VFS is unregistered, another VFS is chosen as
|
6098
6660
|
** the default. The choice for the new VFS is arbitrary.)^
|
6099
6661
|
*/
|
6100
|
-
SQLITE_API sqlite3_vfs *
|
6101
|
-
SQLITE_API int
|
6102
|
-
SQLITE_API int
|
6662
|
+
SQLITE_API sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName);
|
6663
|
+
SQLITE_API int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);
|
6664
|
+
SQLITE_API int sqlite3_vfs_unregister(sqlite3_vfs*);
|
6103
6665
|
|
6104
6666
|
/*
|
6105
6667
|
** CAPI3REF: Mutexes
|
@@ -6215,11 +6777,11 @@ SQLITE_API int SQLITE_STDCALL sqlite3_vfs_unregister(sqlite3_vfs*);
|
|
6215
6777
|
**
|
6216
6778
|
** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()].
|
6217
6779
|
*/
|
6218
|
-
SQLITE_API sqlite3_mutex *
|
6219
|
-
SQLITE_API void
|
6220
|
-
SQLITE_API void
|
6221
|
-
SQLITE_API int
|
6222
|
-
SQLITE_API void
|
6780
|
+
SQLITE_API sqlite3_mutex *sqlite3_mutex_alloc(int);
|
6781
|
+
SQLITE_API void sqlite3_mutex_free(sqlite3_mutex*);
|
6782
|
+
SQLITE_API void sqlite3_mutex_enter(sqlite3_mutex*);
|
6783
|
+
SQLITE_API int sqlite3_mutex_try(sqlite3_mutex*);
|
6784
|
+
SQLITE_API void sqlite3_mutex_leave(sqlite3_mutex*);
|
6223
6785
|
|
6224
6786
|
/*
|
6225
6787
|
** CAPI3REF: Mutex Methods Object
|
@@ -6329,8 +6891,8 @@ struct sqlite3_mutex_methods {
|
|
6329
6891
|
** interface should also return 1 when given a NULL pointer.
|
6330
6892
|
*/
|
6331
6893
|
#ifndef NDEBUG
|
6332
|
-
SQLITE_API int
|
6333
|
-
SQLITE_API int
|
6894
|
+
SQLITE_API int sqlite3_mutex_held(sqlite3_mutex*);
|
6895
|
+
SQLITE_API int sqlite3_mutex_notheld(sqlite3_mutex*);
|
6334
6896
|
#endif
|
6335
6897
|
|
6336
6898
|
/*
|
@@ -6349,7 +6911,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_mutex_notheld(sqlite3_mutex*);
|
|
6349
6911
|
#define SQLITE_MUTEX_STATIC_MEM 3 /* sqlite3_malloc() */
|
6350
6912
|
#define SQLITE_MUTEX_STATIC_MEM2 4 /* NOT USED */
|
6351
6913
|
#define SQLITE_MUTEX_STATIC_OPEN 4 /* sqlite3BtreeOpen() */
|
6352
|
-
#define SQLITE_MUTEX_STATIC_PRNG 5 /*
|
6914
|
+
#define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_randomness() */
|
6353
6915
|
#define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */
|
6354
6916
|
#define SQLITE_MUTEX_STATIC_LRU2 7 /* NOT USED */
|
6355
6917
|
#define SQLITE_MUTEX_STATIC_PMEM 7 /* sqlite3PageMalloc() */
|
@@ -6370,7 +6932,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_mutex_notheld(sqlite3_mutex*);
|
|
6370
6932
|
** ^If the [threading mode] is Single-thread or Multi-thread then this
|
6371
6933
|
** routine returns a NULL pointer.
|
6372
6934
|
*/
|
6373
|
-
SQLITE_API sqlite3_mutex *
|
6935
|
+
SQLITE_API sqlite3_mutex *sqlite3_db_mutex(sqlite3*);
|
6374
6936
|
|
6375
6937
|
/*
|
6376
6938
|
** CAPI3REF: Low-Level Control Of Database Files
|
@@ -6405,7 +6967,7 @@ SQLITE_API sqlite3_mutex *SQLITE_STDCALL sqlite3_db_mutex(sqlite3*);
|
|
6405
6967
|
**
|
6406
6968
|
** See also: [SQLITE_FCNTL_LOCKSTATE]
|
6407
6969
|
*/
|
6408
|
-
SQLITE_API int
|
6970
|
+
SQLITE_API int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*);
|
6409
6971
|
|
6410
6972
|
/*
|
6411
6973
|
** CAPI3REF: Testing Interface
|
@@ -6424,7 +6986,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_file_control(sqlite3*, const char *zDbName
|
|
6424
6986
|
** Unlike most of the SQLite API, this function is not guaranteed to
|
6425
6987
|
** operate consistently from one release to the next.
|
6426
6988
|
*/
|
6427
|
-
SQLITE_API int
|
6989
|
+
SQLITE_API int sqlite3_test_control(int op, ...);
|
6428
6990
|
|
6429
6991
|
/*
|
6430
6992
|
** CAPI3REF: Testing Interface Operation Codes
|
@@ -6450,9 +7012,10 @@ SQLITE_API int SQLITE_CDECL sqlite3_test_control(int op, ...);
|
|
6450
7012
|
#define SQLITE_TESTCTRL_RESERVE 14
|
6451
7013
|
#define SQLITE_TESTCTRL_OPTIMIZATIONS 15
|
6452
7014
|
#define SQLITE_TESTCTRL_ISKEYWORD 16
|
6453
|
-
#define SQLITE_TESTCTRL_SCRATCHMALLOC 17
|
7015
|
+
#define SQLITE_TESTCTRL_SCRATCHMALLOC 17 /* NOT USED */
|
6454
7016
|
#define SQLITE_TESTCTRL_LOCALTIME_FAULT 18
|
6455
7017
|
#define SQLITE_TESTCTRL_EXPLAIN_STMT 19 /* NOT USED */
|
7018
|
+
#define SQLITE_TESTCTRL_ONCE_RESET_THRESHOLD 19
|
6456
7019
|
#define SQLITE_TESTCTRL_NEVER_CORRUPT 20
|
6457
7020
|
#define SQLITE_TESTCTRL_VDBE_COVERAGE 21
|
6458
7021
|
#define SQLITE_TESTCTRL_BYTEORDER 22
|
@@ -6487,8 +7050,8 @@ SQLITE_API int SQLITE_CDECL sqlite3_test_control(int op, ...);
|
|
6487
7050
|
**
|
6488
7051
|
** See also: [sqlite3_db_status()]
|
6489
7052
|
*/
|
6490
|
-
SQLITE_API int
|
6491
|
-
SQLITE_API int
|
7053
|
+
SQLITE_API int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag);
|
7054
|
+
SQLITE_API int sqlite3_status64(
|
6492
7055
|
int op,
|
6493
7056
|
sqlite3_int64 *pCurrent,
|
6494
7057
|
sqlite3_int64 *pHighwater,
|
@@ -6508,8 +7071,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_status64(
|
|
6508
7071
|
** <dd>This parameter is the current amount of memory checked out
|
6509
7072
|
** using [sqlite3_malloc()], either directly or indirectly. The
|
6510
7073
|
** figure includes calls made to [sqlite3_malloc()] by the application
|
6511
|
-
** and internal memory usage by the SQLite library.
|
6512
|
-
** controlled by [SQLITE_CONFIG_SCRATCH] and auxiliary page-cache
|
7074
|
+
** and internal memory usage by the SQLite library. Auxiliary page-cache
|
6513
7075
|
** memory controlled by [SQLITE_CONFIG_PAGECACHE] is not included in
|
6514
7076
|
** this parameter. The amount returned is the sum of the allocation
|
6515
7077
|
** sizes as reported by the xSize method in [sqlite3_mem_methods].</dd>)^
|
@@ -6544,35 +7106,21 @@ SQLITE_API int SQLITE_STDCALL sqlite3_status64(
|
|
6544
7106
|
** [[SQLITE_STATUS_PAGECACHE_SIZE]] ^(<dt>SQLITE_STATUS_PAGECACHE_SIZE</dt>
|
6545
7107
|
** <dd>This parameter records the largest memory allocation request
|
6546
7108
|
** handed to [pagecache memory allocator]. Only the value returned in the
|
6547
|
-
** *pHighwater parameter to [sqlite3_status()] is of interest.
|
7109
|
+
** *pHighwater parameter to [sqlite3_status()] is of interest.
|
6548
7110
|
** The value written into the *pCurrent parameter is undefined.</dd>)^
|
6549
7111
|
**
|
6550
|
-
** [[SQLITE_STATUS_SCRATCH_USED]]
|
6551
|
-
** <dd>
|
6552
|
-
** [scratch memory allocator] configured using
|
6553
|
-
** [SQLITE_CONFIG_SCRATCH]. The value returned is in allocations, not
|
6554
|
-
** in bytes. Since a single thread may only have one scratch allocation
|
6555
|
-
** outstanding at time, this parameter also reports the number of threads
|
6556
|
-
** using scratch memory at the same time.</dd>)^
|
7112
|
+
** [[SQLITE_STATUS_SCRATCH_USED]] <dt>SQLITE_STATUS_SCRATCH_USED</dt>
|
7113
|
+
** <dd>No longer used.</dd>
|
6557
7114
|
**
|
6558
7115
|
** [[SQLITE_STATUS_SCRATCH_OVERFLOW]] ^(<dt>SQLITE_STATUS_SCRATCH_OVERFLOW</dt>
|
6559
|
-
** <dd>
|
6560
|
-
**
|
6561
|
-
**
|
6562
|
-
**
|
6563
|
-
** larger (that is, because the requested allocation was larger than the
|
6564
|
-
** "sz" parameter to [SQLITE_CONFIG_SCRATCH]) and because no scratch buffer
|
6565
|
-
** slots were available.
|
6566
|
-
** </dd>)^
|
6567
|
-
**
|
6568
|
-
** [[SQLITE_STATUS_SCRATCH_SIZE]] ^(<dt>SQLITE_STATUS_SCRATCH_SIZE</dt>
|
6569
|
-
** <dd>This parameter records the largest memory allocation request
|
6570
|
-
** handed to [scratch memory allocator]. Only the value returned in the
|
6571
|
-
** *pHighwater parameter to [sqlite3_status()] is of interest.
|
6572
|
-
** The value written into the *pCurrent parameter is undefined.</dd>)^
|
7116
|
+
** <dd>No longer used.</dd>
|
7117
|
+
**
|
7118
|
+
** [[SQLITE_STATUS_SCRATCH_SIZE]] <dt>SQLITE_STATUS_SCRATCH_SIZE</dt>
|
7119
|
+
** <dd>No longer used.</dd>
|
6573
7120
|
**
|
6574
7121
|
** [[SQLITE_STATUS_PARSER_STACK]] ^(<dt>SQLITE_STATUS_PARSER_STACK</dt>
|
6575
|
-
** <dd>
|
7122
|
+
** <dd>The *pHighwater parameter records the deepest parser stack.
|
7123
|
+
** The *pCurrent value is undefined. The *pHighwater value is only
|
6576
7124
|
** meaningful if SQLite is compiled with [YYTRACKMAXSTACKDEPTH].</dd>)^
|
6577
7125
|
** </dl>
|
6578
7126
|
**
|
@@ -6581,12 +7129,12 @@ SQLITE_API int SQLITE_STDCALL sqlite3_status64(
|
|
6581
7129
|
#define SQLITE_STATUS_MEMORY_USED 0
|
6582
7130
|
#define SQLITE_STATUS_PAGECACHE_USED 1
|
6583
7131
|
#define SQLITE_STATUS_PAGECACHE_OVERFLOW 2
|
6584
|
-
#define SQLITE_STATUS_SCRATCH_USED 3
|
6585
|
-
#define SQLITE_STATUS_SCRATCH_OVERFLOW 4
|
7132
|
+
#define SQLITE_STATUS_SCRATCH_USED 3 /* NOT USED */
|
7133
|
+
#define SQLITE_STATUS_SCRATCH_OVERFLOW 4 /* NOT USED */
|
6586
7134
|
#define SQLITE_STATUS_MALLOC_SIZE 5
|
6587
7135
|
#define SQLITE_STATUS_PARSER_STACK 6
|
6588
7136
|
#define SQLITE_STATUS_PAGECACHE_SIZE 7
|
6589
|
-
#define SQLITE_STATUS_SCRATCH_SIZE 8
|
7137
|
+
#define SQLITE_STATUS_SCRATCH_SIZE 8 /* NOT USED */
|
6590
7138
|
#define SQLITE_STATUS_MALLOC_COUNT 9
|
6591
7139
|
|
6592
7140
|
/*
|
@@ -6612,7 +7160,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_status64(
|
|
6612
7160
|
**
|
6613
7161
|
** See also: [sqlite3_status()] and [sqlite3_stmt_status()].
|
6614
7162
|
*/
|
6615
|
-
SQLITE_API int
|
7163
|
+
SQLITE_API int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg);
|
6616
7164
|
|
6617
7165
|
/*
|
6618
7166
|
** CAPI3REF: Status Parameters for database connections
|
@@ -6658,6 +7206,18 @@ SQLITE_API int SQLITE_STDCALL sqlite3_db_status(sqlite3*, int op, int *pCur, int
|
|
6658
7206
|
** memory used by all pager caches associated with the database connection.)^
|
6659
7207
|
** ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_USED is always 0.
|
6660
7208
|
**
|
7209
|
+
** [[SQLITE_DBSTATUS_CACHE_USED_SHARED]]
|
7210
|
+
** ^(<dt>SQLITE_DBSTATUS_CACHE_USED_SHARED</dt>
|
7211
|
+
** <dd>This parameter is similar to DBSTATUS_CACHE_USED, except that if a
|
7212
|
+
** pager cache is shared between two or more connections the bytes of heap
|
7213
|
+
** memory used by that pager cache is divided evenly between the attached
|
7214
|
+
** connections.)^ In other words, if none of the pager caches associated
|
7215
|
+
** with the database connection are shared, this request returns the same
|
7216
|
+
** value as DBSTATUS_CACHE_USED. Or, if one or more or the pager caches are
|
7217
|
+
** shared, the value returned by this call will be smaller than that returned
|
7218
|
+
** by DBSTATUS_CACHE_USED. ^The highwater mark associated with
|
7219
|
+
** SQLITE_DBSTATUS_CACHE_USED_SHARED is always 0.
|
7220
|
+
**
|
6661
7221
|
** [[SQLITE_DBSTATUS_SCHEMA_USED]] ^(<dt>SQLITE_DBSTATUS_SCHEMA_USED</dt>
|
6662
7222
|
** <dd>This parameter returns the approximate number of bytes of heap
|
6663
7223
|
** memory used to store the schema for all databases associated
|
@@ -6715,7 +7275,8 @@ SQLITE_API int SQLITE_STDCALL sqlite3_db_status(sqlite3*, int op, int *pCur, int
|
|
6715
7275
|
#define SQLITE_DBSTATUS_CACHE_MISS 8
|
6716
7276
|
#define SQLITE_DBSTATUS_CACHE_WRITE 9
|
6717
7277
|
#define SQLITE_DBSTATUS_DEFERRED_FKS 10
|
6718
|
-
#define
|
7278
|
+
#define SQLITE_DBSTATUS_CACHE_USED_SHARED 11
|
7279
|
+
#define SQLITE_DBSTATUS_MAX 11 /* Largest defined DBSTATUS */
|
6719
7280
|
|
6720
7281
|
|
6721
7282
|
/*
|
@@ -6742,7 +7303,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_db_status(sqlite3*, int op, int *pCur, int
|
|
6742
7303
|
**
|
6743
7304
|
** See also: [sqlite3_status()] and [sqlite3_db_status()].
|
6744
7305
|
*/
|
6745
|
-
SQLITE_API int
|
7306
|
+
SQLITE_API int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg);
|
6746
7307
|
|
6747
7308
|
/*
|
6748
7309
|
** CAPI3REF: Status Parameters for prepared statements
|
@@ -6778,6 +7339,24 @@ SQLITE_API int SQLITE_STDCALL sqlite3_stmt_status(sqlite3_stmt*, int op,int rese
|
|
6778
7339
|
** used as a proxy for the total work done by the prepared statement.
|
6779
7340
|
** If the number of virtual machine operations exceeds 2147483647
|
6780
7341
|
** then the value returned by this statement status code is undefined.
|
7342
|
+
**
|
7343
|
+
** [[SQLITE_STMTSTATUS_REPREPARE]] <dt>SQLITE_STMTSTATUS_REPREPARE</dt>
|
7344
|
+
** <dd>^This is the number of times that the prepare statement has been
|
7345
|
+
** automatically regenerated due to schema changes or change to
|
7346
|
+
** [bound parameters] that might affect the query plan.
|
7347
|
+
**
|
7348
|
+
** [[SQLITE_STMTSTATUS_RUN]] <dt>SQLITE_STMTSTATUS_RUN</dt>
|
7349
|
+
** <dd>^This is the number of times that the prepared statement has
|
7350
|
+
** been run. A single "run" for the purposes of this counter is one
|
7351
|
+
** or more calls to [sqlite3_step()] followed by a call to [sqlite3_reset()].
|
7352
|
+
** The counter is incremented on the first [sqlite3_step()] call of each
|
7353
|
+
** cycle.
|
7354
|
+
**
|
7355
|
+
** [[SQLITE_STMTSTATUS_MEMUSED]] <dt>SQLITE_STMTSTATUS_MEMUSED</dt>
|
7356
|
+
** <dd>^This is the approximate number of bytes of heap memory
|
7357
|
+
** used to store the prepared statement. ^This value is not actually
|
7358
|
+
** a counter, and so the resetFlg parameter to sqlite3_stmt_status()
|
7359
|
+
** is ignored when the opcode is SQLITE_STMTSTATUS_MEMUSED.
|
6781
7360
|
** </dd>
|
6782
7361
|
** </dl>
|
6783
7362
|
*/
|
@@ -6785,6 +7364,9 @@ SQLITE_API int SQLITE_STDCALL sqlite3_stmt_status(sqlite3_stmt*, int op,int rese
|
|
6785
7364
|
#define SQLITE_STMTSTATUS_SORT 2
|
6786
7365
|
#define SQLITE_STMTSTATUS_AUTOINDEX 3
|
6787
7366
|
#define SQLITE_STMTSTATUS_VM_STEP 4
|
7367
|
+
#define SQLITE_STMTSTATUS_REPREPARE 5
|
7368
|
+
#define SQLITE_STMTSTATUS_RUN 6
|
7369
|
+
#define SQLITE_STMTSTATUS_MEMUSED 99
|
6788
7370
|
|
6789
7371
|
/*
|
6790
7372
|
** CAPI3REF: Custom Page Cache Object
|
@@ -7069,7 +7651,7 @@ typedef struct sqlite3_backup sqlite3_backup;
|
|
7069
7651
|
** must be different or else sqlite3_backup_init(D,N,S,M) will fail with
|
7070
7652
|
** an error.
|
7071
7653
|
**
|
7072
|
-
** ^A call to sqlite3_backup_init() will fail, returning
|
7654
|
+
** ^A call to sqlite3_backup_init() will fail, returning NULL, if
|
7073
7655
|
** there is already a read or read-write transaction open on the
|
7074
7656
|
** destination database.
|
7075
7657
|
**
|
@@ -7211,16 +7793,16 @@ typedef struct sqlite3_backup sqlite3_backup;
|
|
7211
7793
|
** same time as another thread is invoking sqlite3_backup_step() it is
|
7212
7794
|
** possible that they return invalid values.
|
7213
7795
|
*/
|
7214
|
-
SQLITE_API sqlite3_backup *
|
7796
|
+
SQLITE_API sqlite3_backup *sqlite3_backup_init(
|
7215
7797
|
sqlite3 *pDest, /* Destination database handle */
|
7216
7798
|
const char *zDestName, /* Destination database name */
|
7217
7799
|
sqlite3 *pSource, /* Source database handle */
|
7218
7800
|
const char *zSourceName /* Source database name */
|
7219
7801
|
);
|
7220
|
-
SQLITE_API int
|
7221
|
-
SQLITE_API int
|
7222
|
-
SQLITE_API int
|
7223
|
-
SQLITE_API int
|
7802
|
+
SQLITE_API int sqlite3_backup_step(sqlite3_backup *p, int nPage);
|
7803
|
+
SQLITE_API int sqlite3_backup_finish(sqlite3_backup *p);
|
7804
|
+
SQLITE_API int sqlite3_backup_remaining(sqlite3_backup *p);
|
7805
|
+
SQLITE_API int sqlite3_backup_pagecount(sqlite3_backup *p);
|
7224
7806
|
|
7225
7807
|
/*
|
7226
7808
|
** CAPI3REF: Unlock Notification
|
@@ -7337,7 +7919,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_backup_pagecount(sqlite3_backup *p);
|
|
7337
7919
|
** the special "DROP TABLE/INDEX" case, the extended error code is just
|
7338
7920
|
** SQLITE_LOCKED.)^
|
7339
7921
|
*/
|
7340
|
-
SQLITE_API int
|
7922
|
+
SQLITE_API int sqlite3_unlock_notify(
|
7341
7923
|
sqlite3 *pBlocked, /* Waiting connection */
|
7342
7924
|
void (*xNotify)(void **apArg, int nArg), /* Callback function to invoke */
|
7343
7925
|
void *pNotifyArg /* Argument to pass to xNotify */
|
@@ -7352,23 +7934,48 @@ SQLITE_API int SQLITE_STDCALL sqlite3_unlock_notify(
|
|
7352
7934
|
** strings in a case-independent fashion, using the same definition of "case
|
7353
7935
|
** independence" that SQLite uses internally when comparing identifiers.
|
7354
7936
|
*/
|
7355
|
-
SQLITE_API int
|
7356
|
-
SQLITE_API int
|
7937
|
+
SQLITE_API int sqlite3_stricmp(const char *, const char *);
|
7938
|
+
SQLITE_API int sqlite3_strnicmp(const char *, const char *, int);
|
7357
7939
|
|
7358
7940
|
/*
|
7359
7941
|
** CAPI3REF: String Globbing
|
7360
7942
|
*
|
7361
|
-
** ^The [sqlite3_strglob(P,X)] interface returns zero if
|
7362
|
-
** the
|
7363
|
-
**
|
7943
|
+
** ^The [sqlite3_strglob(P,X)] interface returns zero if and only if
|
7944
|
+
** string X matches the [GLOB] pattern P.
|
7945
|
+
** ^The definition of [GLOB] pattern matching used in
|
7364
7946
|
** [sqlite3_strglob(P,X)] is the same as for the "X GLOB P" operator in the
|
7365
|
-
** SQL dialect
|
7366
|
-
** sensitive.
|
7947
|
+
** SQL dialect understood by SQLite. ^The [sqlite3_strglob(P,X)] function
|
7948
|
+
** is case sensitive.
|
7367
7949
|
**
|
7368
7950
|
** Note that this routine returns zero on a match and non-zero if the strings
|
7369
7951
|
** do not match, the same as [sqlite3_stricmp()] and [sqlite3_strnicmp()].
|
7952
|
+
**
|
7953
|
+
** See also: [sqlite3_strlike()].
|
7370
7954
|
*/
|
7371
|
-
SQLITE_API int
|
7955
|
+
SQLITE_API int sqlite3_strglob(const char *zGlob, const char *zStr);
|
7956
|
+
|
7957
|
+
/*
|
7958
|
+
** CAPI3REF: String LIKE Matching
|
7959
|
+
*
|
7960
|
+
** ^The [sqlite3_strlike(P,X,E)] interface returns zero if and only if
|
7961
|
+
** string X matches the [LIKE] pattern P with escape character E.
|
7962
|
+
** ^The definition of [LIKE] pattern matching used in
|
7963
|
+
** [sqlite3_strlike(P,X,E)] is the same as for the "X LIKE P ESCAPE E"
|
7964
|
+
** operator in the SQL dialect understood by SQLite. ^For "X LIKE P" without
|
7965
|
+
** the ESCAPE clause, set the E parameter of [sqlite3_strlike(P,X,E)] to 0.
|
7966
|
+
** ^As with the LIKE operator, the [sqlite3_strlike(P,X,E)] function is case
|
7967
|
+
** insensitive - equivalent upper and lower case ASCII characters match
|
7968
|
+
** one another.
|
7969
|
+
**
|
7970
|
+
** ^The [sqlite3_strlike(P,X,E)] function matches Unicode characters, though
|
7971
|
+
** only ASCII characters are case folded.
|
7972
|
+
**
|
7973
|
+
** Note that this routine returns zero on a match and non-zero if the strings
|
7974
|
+
** do not match, the same as [sqlite3_stricmp()] and [sqlite3_strnicmp()].
|
7975
|
+
**
|
7976
|
+
** See also: [sqlite3_strglob()].
|
7977
|
+
*/
|
7978
|
+
SQLITE_API int sqlite3_strlike(const char *zGlob, const char *zStr, unsigned int cEsc);
|
7372
7979
|
|
7373
7980
|
/*
|
7374
7981
|
** CAPI3REF: Error Logging Interface
|
@@ -7391,7 +7998,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_strglob(const char *zGlob, const char *zSt
|
|
7391
7998
|
** a few hundred characters, it will be truncated to the length of the
|
7392
7999
|
** buffer.
|
7393
8000
|
*/
|
7394
|
-
SQLITE_API void
|
8001
|
+
SQLITE_API void sqlite3_log(int iErrCode, const char *zFormat, ...);
|
7395
8002
|
|
7396
8003
|
/*
|
7397
8004
|
** CAPI3REF: Write-Ahead Log Commit Hook
|
@@ -7425,9 +8032,9 @@ SQLITE_API void SQLITE_CDECL sqlite3_log(int iErrCode, const char *zFormat, ...)
|
|
7425
8032
|
** previously registered write-ahead log callback. ^Note that the
|
7426
8033
|
** [sqlite3_wal_autocheckpoint()] interface and the
|
7427
8034
|
** [wal_autocheckpoint pragma] both invoke [sqlite3_wal_hook()] and will
|
7428
|
-
**
|
8035
|
+
** overwrite any prior [sqlite3_wal_hook()] settings.
|
7429
8036
|
*/
|
7430
|
-
SQLITE_API void *
|
8037
|
+
SQLITE_API void *sqlite3_wal_hook(
|
7431
8038
|
sqlite3*,
|
7432
8039
|
int(*)(void *,sqlite3*,const char*,int),
|
7433
8040
|
void*
|
@@ -7462,7 +8069,7 @@ SQLITE_API void *SQLITE_STDCALL sqlite3_wal_hook(
|
|
7462
8069
|
** is only necessary if the default setting is found to be suboptimal
|
7463
8070
|
** for a particular application.
|
7464
8071
|
*/
|
7465
|
-
SQLITE_API int
|
8072
|
+
SQLITE_API int sqlite3_wal_autocheckpoint(sqlite3 *db, int N);
|
7466
8073
|
|
7467
8074
|
/*
|
7468
8075
|
** CAPI3REF: Checkpoint a database
|
@@ -7484,7 +8091,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_wal_autocheckpoint(sqlite3 *db, int N);
|
|
7484
8091
|
** start a callback but which do not need the full power (and corresponding
|
7485
8092
|
** complication) of [sqlite3_wal_checkpoint_v2()].
|
7486
8093
|
*/
|
7487
|
-
SQLITE_API int
|
8094
|
+
SQLITE_API int sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb);
|
7488
8095
|
|
7489
8096
|
/*
|
7490
8097
|
** CAPI3REF: Checkpoint a database
|
@@ -7578,7 +8185,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_wal_checkpoint(sqlite3 *db, const char *zD
|
|
7578
8185
|
** ^The [PRAGMA wal_checkpoint] command can be used to invoke this interface
|
7579
8186
|
** from SQL.
|
7580
8187
|
*/
|
7581
|
-
SQLITE_API int
|
8188
|
+
SQLITE_API int sqlite3_wal_checkpoint_v2(
|
7582
8189
|
sqlite3 *db, /* Database handle */
|
7583
8190
|
const char *zDb, /* Name of attached database (or NULL) */
|
7584
8191
|
int eMode, /* SQLITE_CHECKPOINT_* value */
|
@@ -7614,7 +8221,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_wal_checkpoint_v2(
|
|
7614
8221
|
** this function. (See [SQLITE_VTAB_CONSTRAINT_SUPPORT].) Further options
|
7615
8222
|
** may be added in the future.
|
7616
8223
|
*/
|
7617
|
-
SQLITE_API int
|
8224
|
+
SQLITE_API int sqlite3_vtab_config(sqlite3*, int op, ...);
|
7618
8225
|
|
7619
8226
|
/*
|
7620
8227
|
** CAPI3REF: Virtual Table Configuration Options
|
@@ -7667,7 +8274,7 @@ SQLITE_API int SQLITE_CDECL sqlite3_vtab_config(sqlite3*, int op, ...);
|
|
7667
8274
|
** of the SQL statement that triggered the call to the [xUpdate] method of the
|
7668
8275
|
** [virtual table].
|
7669
8276
|
*/
|
7670
|
-
SQLITE_API int
|
8277
|
+
SQLITE_API int sqlite3_vtab_on_conflict(sqlite3 *);
|
7671
8278
|
|
7672
8279
|
/*
|
7673
8280
|
** CAPI3REF: Conflict resolution modes
|
@@ -7772,7 +8379,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_vtab_on_conflict(sqlite3 *);
|
|
7772
8379
|
**
|
7773
8380
|
** See also: [sqlite3_stmt_scanstatus_reset()]
|
7774
8381
|
*/
|
7775
|
-
SQLITE_API int
|
8382
|
+
SQLITE_API int sqlite3_stmt_scanstatus(
|
7776
8383
|
sqlite3_stmt *pStmt, /* Prepared statement for which info desired */
|
7777
8384
|
int idx, /* Index of loop to report on */
|
7778
8385
|
int iScanStatusOp, /* Information desired. SQLITE_SCANSTAT_* */
|
@@ -7788,8 +8395,332 @@ SQLITE_API int SQLITE_STDCALL sqlite3_stmt_scanstatus(
|
|
7788
8395
|
** This API is only available if the library is built with pre-processor
|
7789
8396
|
** symbol [SQLITE_ENABLE_STMT_SCANSTATUS] defined.
|
7790
8397
|
*/
|
7791
|
-
SQLITE_API void
|
8398
|
+
SQLITE_API void sqlite3_stmt_scanstatus_reset(sqlite3_stmt*);
|
8399
|
+
|
8400
|
+
/*
|
8401
|
+
** CAPI3REF: Flush caches to disk mid-transaction
|
8402
|
+
**
|
8403
|
+
** ^If a write-transaction is open on [database connection] D when the
|
8404
|
+
** [sqlite3_db_cacheflush(D)] interface invoked, any dirty
|
8405
|
+
** pages in the pager-cache that are not currently in use are written out
|
8406
|
+
** to disk. A dirty page may be in use if a database cursor created by an
|
8407
|
+
** active SQL statement is reading from it, or if it is page 1 of a database
|
8408
|
+
** file (page 1 is always "in use"). ^The [sqlite3_db_cacheflush(D)]
|
8409
|
+
** interface flushes caches for all schemas - "main", "temp", and
|
8410
|
+
** any [attached] databases.
|
8411
|
+
**
|
8412
|
+
** ^If this function needs to obtain extra database locks before dirty pages
|
8413
|
+
** can be flushed to disk, it does so. ^If those locks cannot be obtained
|
8414
|
+
** immediately and there is a busy-handler callback configured, it is invoked
|
8415
|
+
** in the usual manner. ^If the required lock still cannot be obtained, then
|
8416
|
+
** the database is skipped and an attempt made to flush any dirty pages
|
8417
|
+
** belonging to the next (if any) database. ^If any databases are skipped
|
8418
|
+
** because locks cannot be obtained, but no other error occurs, this
|
8419
|
+
** function returns SQLITE_BUSY.
|
8420
|
+
**
|
8421
|
+
** ^If any other error occurs while flushing dirty pages to disk (for
|
8422
|
+
** example an IO error or out-of-memory condition), then processing is
|
8423
|
+
** abandoned and an SQLite [error code] is returned to the caller immediately.
|
8424
|
+
**
|
8425
|
+
** ^Otherwise, if no error occurs, [sqlite3_db_cacheflush()] returns SQLITE_OK.
|
8426
|
+
**
|
8427
|
+
** ^This function does not set the database handle error code or message
|
8428
|
+
** returned by the [sqlite3_errcode()] and [sqlite3_errmsg()] functions.
|
8429
|
+
*/
|
8430
|
+
SQLITE_API int sqlite3_db_cacheflush(sqlite3*);
|
8431
|
+
|
8432
|
+
/*
|
8433
|
+
** CAPI3REF: The pre-update hook.
|
8434
|
+
**
|
8435
|
+
** ^These interfaces are only available if SQLite is compiled using the
|
8436
|
+
** [SQLITE_ENABLE_PREUPDATE_HOOK] compile-time option.
|
8437
|
+
**
|
8438
|
+
** ^The [sqlite3_preupdate_hook()] interface registers a callback function
|
8439
|
+
** that is invoked prior to each [INSERT], [UPDATE], and [DELETE] operation
|
8440
|
+
** on a database table.
|
8441
|
+
** ^At most one preupdate hook may be registered at a time on a single
|
8442
|
+
** [database connection]; each call to [sqlite3_preupdate_hook()] overrides
|
8443
|
+
** the previous setting.
|
8444
|
+
** ^The preupdate hook is disabled by invoking [sqlite3_preupdate_hook()]
|
8445
|
+
** with a NULL pointer as the second parameter.
|
8446
|
+
** ^The third parameter to [sqlite3_preupdate_hook()] is passed through as
|
8447
|
+
** the first parameter to callbacks.
|
8448
|
+
**
|
8449
|
+
** ^The preupdate hook only fires for changes to real database tables; the
|
8450
|
+
** preupdate hook is not invoked for changes to [virtual tables] or to
|
8451
|
+
** system tables like sqlite_master or sqlite_stat1.
|
8452
|
+
**
|
8453
|
+
** ^The second parameter to the preupdate callback is a pointer to
|
8454
|
+
** the [database connection] that registered the preupdate hook.
|
8455
|
+
** ^The third parameter to the preupdate callback is one of the constants
|
8456
|
+
** [SQLITE_INSERT], [SQLITE_DELETE], or [SQLITE_UPDATE] to identify the
|
8457
|
+
** kind of update operation that is about to occur.
|
8458
|
+
** ^(The fourth parameter to the preupdate callback is the name of the
|
8459
|
+
** database within the database connection that is being modified. This
|
8460
|
+
** will be "main" for the main database or "temp" for TEMP tables or
|
8461
|
+
** the name given after the AS keyword in the [ATTACH] statement for attached
|
8462
|
+
** databases.)^
|
8463
|
+
** ^The fifth parameter to the preupdate callback is the name of the
|
8464
|
+
** table that is being modified.
|
8465
|
+
**
|
8466
|
+
** For an UPDATE or DELETE operation on a [rowid table], the sixth
|
8467
|
+
** parameter passed to the preupdate callback is the initial [rowid] of the
|
8468
|
+
** row being modified or deleted. For an INSERT operation on a rowid table,
|
8469
|
+
** or any operation on a WITHOUT ROWID table, the value of the sixth
|
8470
|
+
** parameter is undefined. For an INSERT or UPDATE on a rowid table the
|
8471
|
+
** seventh parameter is the final rowid value of the row being inserted
|
8472
|
+
** or updated. The value of the seventh parameter passed to the callback
|
8473
|
+
** function is not defined for operations on WITHOUT ROWID tables, or for
|
8474
|
+
** INSERT operations on rowid tables.
|
8475
|
+
**
|
8476
|
+
** The [sqlite3_preupdate_old()], [sqlite3_preupdate_new()],
|
8477
|
+
** [sqlite3_preupdate_count()], and [sqlite3_preupdate_depth()] interfaces
|
8478
|
+
** provide additional information about a preupdate event. These routines
|
8479
|
+
** may only be called from within a preupdate callback. Invoking any of
|
8480
|
+
** these routines from outside of a preupdate callback or with a
|
8481
|
+
** [database connection] pointer that is different from the one supplied
|
8482
|
+
** to the preupdate callback results in undefined and probably undesirable
|
8483
|
+
** behavior.
|
8484
|
+
**
|
8485
|
+
** ^The [sqlite3_preupdate_count(D)] interface returns the number of columns
|
8486
|
+
** in the row that is being inserted, updated, or deleted.
|
8487
|
+
**
|
8488
|
+
** ^The [sqlite3_preupdate_old(D,N,P)] interface writes into P a pointer to
|
8489
|
+
** a [protected sqlite3_value] that contains the value of the Nth column of
|
8490
|
+
** the table row before it is updated. The N parameter must be between 0
|
8491
|
+
** and one less than the number of columns or the behavior will be
|
8492
|
+
** undefined. This must only be used within SQLITE_UPDATE and SQLITE_DELETE
|
8493
|
+
** preupdate callbacks; if it is used by an SQLITE_INSERT callback then the
|
8494
|
+
** behavior is undefined. The [sqlite3_value] that P points to
|
8495
|
+
** will be destroyed when the preupdate callback returns.
|
8496
|
+
**
|
8497
|
+
** ^The [sqlite3_preupdate_new(D,N,P)] interface writes into P a pointer to
|
8498
|
+
** a [protected sqlite3_value] that contains the value of the Nth column of
|
8499
|
+
** the table row after it is updated. The N parameter must be between 0
|
8500
|
+
** and one less than the number of columns or the behavior will be
|
8501
|
+
** undefined. This must only be used within SQLITE_INSERT and SQLITE_UPDATE
|
8502
|
+
** preupdate callbacks; if it is used by an SQLITE_DELETE callback then the
|
8503
|
+
** behavior is undefined. The [sqlite3_value] that P points to
|
8504
|
+
** will be destroyed when the preupdate callback returns.
|
8505
|
+
**
|
8506
|
+
** ^The [sqlite3_preupdate_depth(D)] interface returns 0 if the preupdate
|
8507
|
+
** callback was invoked as a result of a direct insert, update, or delete
|
8508
|
+
** operation; or 1 for inserts, updates, or deletes invoked by top-level
|
8509
|
+
** triggers; or 2 for changes resulting from triggers called by top-level
|
8510
|
+
** triggers; and so forth.
|
8511
|
+
**
|
8512
|
+
** See also: [sqlite3_update_hook()]
|
8513
|
+
*/
|
8514
|
+
#if defined(SQLITE_ENABLE_PREUPDATE_HOOK)
|
8515
|
+
SQLITE_API void *sqlite3_preupdate_hook(
|
8516
|
+
sqlite3 *db,
|
8517
|
+
void(*xPreUpdate)(
|
8518
|
+
void *pCtx, /* Copy of third arg to preupdate_hook() */
|
8519
|
+
sqlite3 *db, /* Database handle */
|
8520
|
+
int op, /* SQLITE_UPDATE, DELETE or INSERT */
|
8521
|
+
char const *zDb, /* Database name */
|
8522
|
+
char const *zName, /* Table name */
|
8523
|
+
sqlite3_int64 iKey1, /* Rowid of row about to be deleted/updated */
|
8524
|
+
sqlite3_int64 iKey2 /* New rowid value (for a rowid UPDATE) */
|
8525
|
+
),
|
8526
|
+
void*
|
8527
|
+
);
|
8528
|
+
SQLITE_API int sqlite3_preupdate_old(sqlite3 *, int, sqlite3_value **);
|
8529
|
+
SQLITE_API int sqlite3_preupdate_count(sqlite3 *);
|
8530
|
+
SQLITE_API int sqlite3_preupdate_depth(sqlite3 *);
|
8531
|
+
SQLITE_API int sqlite3_preupdate_new(sqlite3 *, int, sqlite3_value **);
|
8532
|
+
#endif
|
8533
|
+
|
8534
|
+
/*
|
8535
|
+
** CAPI3REF: Low-level system error code
|
8536
|
+
**
|
8537
|
+
** ^Attempt to return the underlying operating system error code or error
|
8538
|
+
** number that caused the most recent I/O error or failure to open a file.
|
8539
|
+
** The return value is OS-dependent. For example, on unix systems, after
|
8540
|
+
** [sqlite3_open_v2()] returns [SQLITE_CANTOPEN], this interface could be
|
8541
|
+
** called to get back the underlying "errno" that caused the problem, such
|
8542
|
+
** as ENOSPC, EAUTH, EISDIR, and so forth.
|
8543
|
+
*/
|
8544
|
+
SQLITE_API int sqlite3_system_errno(sqlite3*);
|
8545
|
+
|
8546
|
+
/*
|
8547
|
+
** CAPI3REF: Database Snapshot
|
8548
|
+
** KEYWORDS: {snapshot} {sqlite3_snapshot}
|
8549
|
+
** EXPERIMENTAL
|
8550
|
+
**
|
8551
|
+
** An instance of the snapshot object records the state of a [WAL mode]
|
8552
|
+
** database for some specific point in history.
|
8553
|
+
**
|
8554
|
+
** In [WAL mode], multiple [database connections] that are open on the
|
8555
|
+
** same database file can each be reading a different historical version
|
8556
|
+
** of the database file. When a [database connection] begins a read
|
8557
|
+
** transaction, that connection sees an unchanging copy of the database
|
8558
|
+
** as it existed for the point in time when the transaction first started.
|
8559
|
+
** Subsequent changes to the database from other connections are not seen
|
8560
|
+
** by the reader until a new read transaction is started.
|
8561
|
+
**
|
8562
|
+
** The sqlite3_snapshot object records state information about an historical
|
8563
|
+
** version of the database file so that it is possible to later open a new read
|
8564
|
+
** transaction that sees that historical version of the database rather than
|
8565
|
+
** the most recent version.
|
8566
|
+
**
|
8567
|
+
** The constructor for this object is [sqlite3_snapshot_get()]. The
|
8568
|
+
** [sqlite3_snapshot_open()] method causes a fresh read transaction to refer
|
8569
|
+
** to an historical snapshot (if possible). The destructor for
|
8570
|
+
** sqlite3_snapshot objects is [sqlite3_snapshot_free()].
|
8571
|
+
*/
|
8572
|
+
typedef struct sqlite3_snapshot {
|
8573
|
+
unsigned char hidden[48];
|
8574
|
+
} sqlite3_snapshot;
|
8575
|
+
|
8576
|
+
/*
|
8577
|
+
** CAPI3REF: Record A Database Snapshot
|
8578
|
+
** EXPERIMENTAL
|
8579
|
+
**
|
8580
|
+
** ^The [sqlite3_snapshot_get(D,S,P)] interface attempts to make a
|
8581
|
+
** new [sqlite3_snapshot] object that records the current state of
|
8582
|
+
** schema S in database connection D. ^On success, the
|
8583
|
+
** [sqlite3_snapshot_get(D,S,P)] interface writes a pointer to the newly
|
8584
|
+
** created [sqlite3_snapshot] object into *P and returns SQLITE_OK.
|
8585
|
+
** If there is not already a read-transaction open on schema S when
|
8586
|
+
** this function is called, one is opened automatically.
|
8587
|
+
**
|
8588
|
+
** The following must be true for this function to succeed. If any of
|
8589
|
+
** the following statements are false when sqlite3_snapshot_get() is
|
8590
|
+
** called, SQLITE_ERROR is returned. The final value of *P is undefined
|
8591
|
+
** in this case.
|
8592
|
+
**
|
8593
|
+
** <ul>
|
8594
|
+
** <li> The database handle must be in [autocommit mode].
|
8595
|
+
**
|
8596
|
+
** <li> Schema S of [database connection] D must be a [WAL mode] database.
|
8597
|
+
**
|
8598
|
+
** <li> There must not be a write transaction open on schema S of database
|
8599
|
+
** connection D.
|
8600
|
+
**
|
8601
|
+
** <li> One or more transactions must have been written to the current wal
|
8602
|
+
** file since it was created on disk (by any connection). This means
|
8603
|
+
** that a snapshot cannot be taken on a wal mode database with no wal
|
8604
|
+
** file immediately after it is first opened. At least one transaction
|
8605
|
+
** must be written to it first.
|
8606
|
+
** </ul>
|
8607
|
+
**
|
8608
|
+
** This function may also return SQLITE_NOMEM. If it is called with the
|
8609
|
+
** database handle in autocommit mode but fails for some other reason,
|
8610
|
+
** whether or not a read transaction is opened on schema S is undefined.
|
8611
|
+
**
|
8612
|
+
** The [sqlite3_snapshot] object returned from a successful call to
|
8613
|
+
** [sqlite3_snapshot_get()] must be freed using [sqlite3_snapshot_free()]
|
8614
|
+
** to avoid a memory leak.
|
8615
|
+
**
|
8616
|
+
** The [sqlite3_snapshot_get()] interface is only available when the
|
8617
|
+
** SQLITE_ENABLE_SNAPSHOT compile-time option is used.
|
8618
|
+
*/
|
8619
|
+
SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_get(
|
8620
|
+
sqlite3 *db,
|
8621
|
+
const char *zSchema,
|
8622
|
+
sqlite3_snapshot **ppSnapshot
|
8623
|
+
);
|
8624
|
+
|
8625
|
+
/*
|
8626
|
+
** CAPI3REF: Start a read transaction on an historical snapshot
|
8627
|
+
** EXPERIMENTAL
|
8628
|
+
**
|
8629
|
+
** ^The [sqlite3_snapshot_open(D,S,P)] interface starts a
|
8630
|
+
** read transaction for schema S of
|
8631
|
+
** [database connection] D such that the read transaction
|
8632
|
+
** refers to historical [snapshot] P, rather than the most
|
8633
|
+
** recent change to the database.
|
8634
|
+
** ^The [sqlite3_snapshot_open()] interface returns SQLITE_OK on success
|
8635
|
+
** or an appropriate [error code] if it fails.
|
8636
|
+
**
|
8637
|
+
** ^In order to succeed, a call to [sqlite3_snapshot_open(D,S,P)] must be
|
8638
|
+
** the first operation following the [BEGIN] that takes the schema S
|
8639
|
+
** out of [autocommit mode].
|
8640
|
+
** ^In other words, schema S must not currently be in
|
8641
|
+
** a transaction for [sqlite3_snapshot_open(D,S,P)] to work, but the
|
8642
|
+
** database connection D must be out of [autocommit mode].
|
8643
|
+
** ^A [snapshot] will fail to open if it has been overwritten by a
|
8644
|
+
** [checkpoint].
|
8645
|
+
** ^(A call to [sqlite3_snapshot_open(D,S,P)] will fail if the
|
8646
|
+
** database connection D does not know that the database file for
|
8647
|
+
** schema S is in [WAL mode]. A database connection might not know
|
8648
|
+
** that the database file is in [WAL mode] if there has been no prior
|
8649
|
+
** I/O on that database connection, or if the database entered [WAL mode]
|
8650
|
+
** after the most recent I/O on the database connection.)^
|
8651
|
+
** (Hint: Run "[PRAGMA application_id]" against a newly opened
|
8652
|
+
** database connection in order to make it ready to use snapshots.)
|
8653
|
+
**
|
8654
|
+
** The [sqlite3_snapshot_open()] interface is only available when the
|
8655
|
+
** SQLITE_ENABLE_SNAPSHOT compile-time option is used.
|
8656
|
+
*/
|
8657
|
+
SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_open(
|
8658
|
+
sqlite3 *db,
|
8659
|
+
const char *zSchema,
|
8660
|
+
sqlite3_snapshot *pSnapshot
|
8661
|
+
);
|
8662
|
+
|
8663
|
+
/*
|
8664
|
+
** CAPI3REF: Destroy a snapshot
|
8665
|
+
** EXPERIMENTAL
|
8666
|
+
**
|
8667
|
+
** ^The [sqlite3_snapshot_free(P)] interface destroys [sqlite3_snapshot] P.
|
8668
|
+
** The application must eventually free every [sqlite3_snapshot] object
|
8669
|
+
** using this routine to avoid a memory leak.
|
8670
|
+
**
|
8671
|
+
** The [sqlite3_snapshot_free()] interface is only available when the
|
8672
|
+
** SQLITE_ENABLE_SNAPSHOT compile-time option is used.
|
8673
|
+
*/
|
8674
|
+
SQLITE_API SQLITE_EXPERIMENTAL void sqlite3_snapshot_free(sqlite3_snapshot*);
|
8675
|
+
|
8676
|
+
/*
|
8677
|
+
** CAPI3REF: Compare the ages of two snapshot handles.
|
8678
|
+
** EXPERIMENTAL
|
8679
|
+
**
|
8680
|
+
** The sqlite3_snapshot_cmp(P1, P2) interface is used to compare the ages
|
8681
|
+
** of two valid snapshot handles.
|
8682
|
+
**
|
8683
|
+
** If the two snapshot handles are not associated with the same database
|
8684
|
+
** file, the result of the comparison is undefined.
|
8685
|
+
**
|
8686
|
+
** Additionally, the result of the comparison is only valid if both of the
|
8687
|
+
** snapshot handles were obtained by calling sqlite3_snapshot_get() since the
|
8688
|
+
** last time the wal file was deleted. The wal file is deleted when the
|
8689
|
+
** database is changed back to rollback mode or when the number of database
|
8690
|
+
** clients drops to zero. If either snapshot handle was obtained before the
|
8691
|
+
** wal file was last deleted, the value returned by this function
|
8692
|
+
** is undefined.
|
8693
|
+
**
|
8694
|
+
** Otherwise, this API returns a negative value if P1 refers to an older
|
8695
|
+
** snapshot than P2, zero if the two handles refer to the same database
|
8696
|
+
** snapshot, and a positive value if P1 is a newer snapshot than P2.
|
8697
|
+
*/
|
8698
|
+
SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_cmp(
|
8699
|
+
sqlite3_snapshot *p1,
|
8700
|
+
sqlite3_snapshot *p2
|
8701
|
+
);
|
7792
8702
|
|
8703
|
+
/*
|
8704
|
+
** CAPI3REF: Recover snapshots from a wal file
|
8705
|
+
** EXPERIMENTAL
|
8706
|
+
**
|
8707
|
+
** If all connections disconnect from a database file but do not perform
|
8708
|
+
** a checkpoint, the existing wal file is opened along with the database
|
8709
|
+
** file the next time the database is opened. At this point it is only
|
8710
|
+
** possible to successfully call sqlite3_snapshot_open() to open the most
|
8711
|
+
** recent snapshot of the database (the one at the head of the wal file),
|
8712
|
+
** even though the wal file may contain other valid snapshots for which
|
8713
|
+
** clients have sqlite3_snapshot handles.
|
8714
|
+
**
|
8715
|
+
** This function attempts to scan the wal file associated with database zDb
|
8716
|
+
** of database handle db and make all valid snapshots available to
|
8717
|
+
** sqlite3_snapshot_open(). It is an error if there is already a read
|
8718
|
+
** transaction open on the database, or if the database is not a wal mode
|
8719
|
+
** database.
|
8720
|
+
**
|
8721
|
+
** SQLITE_OK is returned if successful, or an SQLite error code otherwise.
|
8722
|
+
*/
|
8723
|
+
SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_recover(sqlite3 *db, const char *zDb);
|
7793
8724
|
|
7794
8725
|
/*
|
7795
8726
|
** Undo the hack that converts floating point types to integer for
|
@@ -7802,8 +8733,9 @@ SQLITE_API void SQLITE_STDCALL sqlite3_stmt_scanstatus_reset(sqlite3_stmt*);
|
|
7802
8733
|
#ifdef __cplusplus
|
7803
8734
|
} /* End of the 'extern "C"' block */
|
7804
8735
|
#endif
|
7805
|
-
#endif /*
|
8736
|
+
#endif /* SQLITE3_H */
|
7806
8737
|
|
8738
|
+
/******** Begin file sqlite3rtree.h *********/
|
7807
8739
|
/*
|
7808
8740
|
** 2010 August 30
|
7809
8741
|
**
|
@@ -7843,7 +8775,7 @@ typedef struct sqlite3_rtree_query_info sqlite3_rtree_query_info;
|
|
7843
8775
|
**
|
7844
8776
|
** SELECT ... FROM <rtree> WHERE <rtree col> MATCH $zGeom(... params ...)
|
7845
8777
|
*/
|
7846
|
-
SQLITE_API int
|
8778
|
+
SQLITE_API int sqlite3_rtree_geometry_callback(
|
7847
8779
|
sqlite3 *db,
|
7848
8780
|
const char *zGeom,
|
7849
8781
|
int (*xGeom)(sqlite3_rtree_geometry*, int, sqlite3_rtree_dbl*,int*),
|
@@ -7869,7 +8801,7 @@ struct sqlite3_rtree_geometry {
|
|
7869
8801
|
**
|
7870
8802
|
** SELECT ... FROM <rtree> WHERE <rtree col> MATCH $zQueryFunc(... params ...)
|
7871
8803
|
*/
|
7872
|
-
SQLITE_API int
|
8804
|
+
SQLITE_API int sqlite3_rtree_query_callback(
|
7873
8805
|
sqlite3 *db,
|
7874
8806
|
const char *zQueryFunc,
|
7875
8807
|
int (*xQueryFunc)(sqlite3_rtree_query_info*),
|
@@ -7921,6 +8853,1298 @@ struct sqlite3_rtree_query_info {
|
|
7921
8853
|
|
7922
8854
|
#endif /* ifndef _SQLITE3RTREE_H_ */
|
7923
8855
|
|
8856
|
+
/******** End of sqlite3rtree.h *********/
|
8857
|
+
/******** Begin file sqlite3session.h *********/
|
8858
|
+
|
8859
|
+
#if !defined(__SQLITESESSION_H_) && defined(SQLITE_ENABLE_SESSION)
|
8860
|
+
#define __SQLITESESSION_H_ 1
|
8861
|
+
|
8862
|
+
/*
|
8863
|
+
** Make sure we can call this stuff from C++.
|
8864
|
+
*/
|
8865
|
+
#ifdef __cplusplus
|
8866
|
+
extern "C" {
|
8867
|
+
#endif
|
8868
|
+
|
8869
|
+
|
8870
|
+
/*
|
8871
|
+
** CAPI3REF: Session Object Handle
|
8872
|
+
*/
|
8873
|
+
typedef struct sqlite3_session sqlite3_session;
|
8874
|
+
|
8875
|
+
/*
|
8876
|
+
** CAPI3REF: Changeset Iterator Handle
|
8877
|
+
*/
|
8878
|
+
typedef struct sqlite3_changeset_iter sqlite3_changeset_iter;
|
8879
|
+
|
8880
|
+
/*
|
8881
|
+
** CAPI3REF: Create A New Session Object
|
8882
|
+
**
|
8883
|
+
** Create a new session object attached to database handle db. If successful,
|
8884
|
+
** a pointer to the new object is written to *ppSession and SQLITE_OK is
|
8885
|
+
** returned. If an error occurs, *ppSession is set to NULL and an SQLite
|
8886
|
+
** error code (e.g. SQLITE_NOMEM) is returned.
|
8887
|
+
**
|
8888
|
+
** It is possible to create multiple session objects attached to a single
|
8889
|
+
** database handle.
|
8890
|
+
**
|
8891
|
+
** Session objects created using this function should be deleted using the
|
8892
|
+
** [sqlite3session_delete()] function before the database handle that they
|
8893
|
+
** are attached to is itself closed. If the database handle is closed before
|
8894
|
+
** the session object is deleted, then the results of calling any session
|
8895
|
+
** module function, including [sqlite3session_delete()] on the session object
|
8896
|
+
** are undefined.
|
8897
|
+
**
|
8898
|
+
** Because the session module uses the [sqlite3_preupdate_hook()] API, it
|
8899
|
+
** is not possible for an application to register a pre-update hook on a
|
8900
|
+
** database handle that has one or more session objects attached. Nor is
|
8901
|
+
** it possible to create a session object attached to a database handle for
|
8902
|
+
** which a pre-update hook is already defined. The results of attempting
|
8903
|
+
** either of these things are undefined.
|
8904
|
+
**
|
8905
|
+
** The session object will be used to create changesets for tables in
|
8906
|
+
** database zDb, where zDb is either "main", or "temp", or the name of an
|
8907
|
+
** attached database. It is not an error if database zDb is not attached
|
8908
|
+
** to the database when the session object is created.
|
8909
|
+
*/
|
8910
|
+
SQLITE_API int sqlite3session_create(
|
8911
|
+
sqlite3 *db, /* Database handle */
|
8912
|
+
const char *zDb, /* Name of db (e.g. "main") */
|
8913
|
+
sqlite3_session **ppSession /* OUT: New session object */
|
8914
|
+
);
|
8915
|
+
|
8916
|
+
/*
|
8917
|
+
** CAPI3REF: Delete A Session Object
|
8918
|
+
**
|
8919
|
+
** Delete a session object previously allocated using
|
8920
|
+
** [sqlite3session_create()]. Once a session object has been deleted, the
|
8921
|
+
** results of attempting to use pSession with any other session module
|
8922
|
+
** function are undefined.
|
8923
|
+
**
|
8924
|
+
** Session objects must be deleted before the database handle to which they
|
8925
|
+
** are attached is closed. Refer to the documentation for
|
8926
|
+
** [sqlite3session_create()] for details.
|
8927
|
+
*/
|
8928
|
+
SQLITE_API void sqlite3session_delete(sqlite3_session *pSession);
|
8929
|
+
|
8930
|
+
|
8931
|
+
/*
|
8932
|
+
** CAPI3REF: Enable Or Disable A Session Object
|
8933
|
+
**
|
8934
|
+
** Enable or disable the recording of changes by a session object. When
|
8935
|
+
** enabled, a session object records changes made to the database. When
|
8936
|
+
** disabled - it does not. A newly created session object is enabled.
|
8937
|
+
** Refer to the documentation for [sqlite3session_changeset()] for further
|
8938
|
+
** details regarding how enabling and disabling a session object affects
|
8939
|
+
** the eventual changesets.
|
8940
|
+
**
|
8941
|
+
** Passing zero to this function disables the session. Passing a value
|
8942
|
+
** greater than zero enables it. Passing a value less than zero is a
|
8943
|
+
** no-op, and may be used to query the current state of the session.
|
8944
|
+
**
|
8945
|
+
** The return value indicates the final state of the session object: 0 if
|
8946
|
+
** the session is disabled, or 1 if it is enabled.
|
8947
|
+
*/
|
8948
|
+
SQLITE_API int sqlite3session_enable(sqlite3_session *pSession, int bEnable);
|
8949
|
+
|
8950
|
+
/*
|
8951
|
+
** CAPI3REF: Set Or Clear the Indirect Change Flag
|
8952
|
+
**
|
8953
|
+
** Each change recorded by a session object is marked as either direct or
|
8954
|
+
** indirect. A change is marked as indirect if either:
|
8955
|
+
**
|
8956
|
+
** <ul>
|
8957
|
+
** <li> The session object "indirect" flag is set when the change is
|
8958
|
+
** made, or
|
8959
|
+
** <li> The change is made by an SQL trigger or foreign key action
|
8960
|
+
** instead of directly as a result of a users SQL statement.
|
8961
|
+
** </ul>
|
8962
|
+
**
|
8963
|
+
** If a single row is affected by more than one operation within a session,
|
8964
|
+
** then the change is considered indirect if all operations meet the criteria
|
8965
|
+
** for an indirect change above, or direct otherwise.
|
8966
|
+
**
|
8967
|
+
** This function is used to set, clear or query the session object indirect
|
8968
|
+
** flag. If the second argument passed to this function is zero, then the
|
8969
|
+
** indirect flag is cleared. If it is greater than zero, the indirect flag
|
8970
|
+
** is set. Passing a value less than zero does not modify the current value
|
8971
|
+
** of the indirect flag, and may be used to query the current state of the
|
8972
|
+
** indirect flag for the specified session object.
|
8973
|
+
**
|
8974
|
+
** The return value indicates the final state of the indirect flag: 0 if
|
8975
|
+
** it is clear, or 1 if it is set.
|
8976
|
+
*/
|
8977
|
+
SQLITE_API int sqlite3session_indirect(sqlite3_session *pSession, int bIndirect);
|
8978
|
+
|
8979
|
+
/*
|
8980
|
+
** CAPI3REF: Attach A Table To A Session Object
|
8981
|
+
**
|
8982
|
+
** If argument zTab is not NULL, then it is the name of a table to attach
|
8983
|
+
** to the session object passed as the first argument. All subsequent changes
|
8984
|
+
** made to the table while the session object is enabled will be recorded. See
|
8985
|
+
** documentation for [sqlite3session_changeset()] for further details.
|
8986
|
+
**
|
8987
|
+
** Or, if argument zTab is NULL, then changes are recorded for all tables
|
8988
|
+
** in the database. If additional tables are added to the database (by
|
8989
|
+
** executing "CREATE TABLE" statements) after this call is made, changes for
|
8990
|
+
** the new tables are also recorded.
|
8991
|
+
**
|
8992
|
+
** Changes can only be recorded for tables that have a PRIMARY KEY explicitly
|
8993
|
+
** defined as part of their CREATE TABLE statement. It does not matter if the
|
8994
|
+
** PRIMARY KEY is an "INTEGER PRIMARY KEY" (rowid alias) or not. The PRIMARY
|
8995
|
+
** KEY may consist of a single column, or may be a composite key.
|
8996
|
+
**
|
8997
|
+
** It is not an error if the named table does not exist in the database. Nor
|
8998
|
+
** is it an error if the named table does not have a PRIMARY KEY. However,
|
8999
|
+
** no changes will be recorded in either of these scenarios.
|
9000
|
+
**
|
9001
|
+
** Changes are not recorded for individual rows that have NULL values stored
|
9002
|
+
** in one or more of their PRIMARY KEY columns.
|
9003
|
+
**
|
9004
|
+
** SQLITE_OK is returned if the call completes without error. Or, if an error
|
9005
|
+
** occurs, an SQLite error code (e.g. SQLITE_NOMEM) is returned.
|
9006
|
+
*/
|
9007
|
+
SQLITE_API int sqlite3session_attach(
|
9008
|
+
sqlite3_session *pSession, /* Session object */
|
9009
|
+
const char *zTab /* Table name */
|
9010
|
+
);
|
9011
|
+
|
9012
|
+
/*
|
9013
|
+
** CAPI3REF: Set a table filter on a Session Object.
|
9014
|
+
**
|
9015
|
+
** The second argument (xFilter) is the "filter callback". For changes to rows
|
9016
|
+
** in tables that are not attached to the Session object, the filter is called
|
9017
|
+
** to determine whether changes to the table's rows should be tracked or not.
|
9018
|
+
** If xFilter returns 0, changes is not tracked. Note that once a table is
|
9019
|
+
** attached, xFilter will not be called again.
|
9020
|
+
*/
|
9021
|
+
SQLITE_API void sqlite3session_table_filter(
|
9022
|
+
sqlite3_session *pSession, /* Session object */
|
9023
|
+
int(*xFilter)(
|
9024
|
+
void *pCtx, /* Copy of third arg to _filter_table() */
|
9025
|
+
const char *zTab /* Table name */
|
9026
|
+
),
|
9027
|
+
void *pCtx /* First argument passed to xFilter */
|
9028
|
+
);
|
9029
|
+
|
9030
|
+
/*
|
9031
|
+
** CAPI3REF: Generate A Changeset From A Session Object
|
9032
|
+
**
|
9033
|
+
** Obtain a changeset containing changes to the tables attached to the
|
9034
|
+
** session object passed as the first argument. If successful,
|
9035
|
+
** set *ppChangeset to point to a buffer containing the changeset
|
9036
|
+
** and *pnChangeset to the size of the changeset in bytes before returning
|
9037
|
+
** SQLITE_OK. If an error occurs, set both *ppChangeset and *pnChangeset to
|
9038
|
+
** zero and return an SQLite error code.
|
9039
|
+
**
|
9040
|
+
** A changeset consists of zero or more INSERT, UPDATE and/or DELETE changes,
|
9041
|
+
** each representing a change to a single row of an attached table. An INSERT
|
9042
|
+
** change contains the values of each field of a new database row. A DELETE
|
9043
|
+
** contains the original values of each field of a deleted database row. An
|
9044
|
+
** UPDATE change contains the original values of each field of an updated
|
9045
|
+
** database row along with the updated values for each updated non-primary-key
|
9046
|
+
** column. It is not possible for an UPDATE change to represent a change that
|
9047
|
+
** modifies the values of primary key columns. If such a change is made, it
|
9048
|
+
** is represented in a changeset as a DELETE followed by an INSERT.
|
9049
|
+
**
|
9050
|
+
** Changes are not recorded for rows that have NULL values stored in one or
|
9051
|
+
** more of their PRIMARY KEY columns. If such a row is inserted or deleted,
|
9052
|
+
** no corresponding change is present in the changesets returned by this
|
9053
|
+
** function. If an existing row with one or more NULL values stored in
|
9054
|
+
** PRIMARY KEY columns is updated so that all PRIMARY KEY columns are non-NULL,
|
9055
|
+
** only an INSERT is appears in the changeset. Similarly, if an existing row
|
9056
|
+
** with non-NULL PRIMARY KEY values is updated so that one or more of its
|
9057
|
+
** PRIMARY KEY columns are set to NULL, the resulting changeset contains a
|
9058
|
+
** DELETE change only.
|
9059
|
+
**
|
9060
|
+
** The contents of a changeset may be traversed using an iterator created
|
9061
|
+
** using the [sqlite3changeset_start()] API. A changeset may be applied to
|
9062
|
+
** a database with a compatible schema using the [sqlite3changeset_apply()]
|
9063
|
+
** API.
|
9064
|
+
**
|
9065
|
+
** Within a changeset generated by this function, all changes related to a
|
9066
|
+
** single table are grouped together. In other words, when iterating through
|
9067
|
+
** a changeset or when applying a changeset to a database, all changes related
|
9068
|
+
** to a single table are processed before moving on to the next table. Tables
|
9069
|
+
** are sorted in the same order in which they were attached (or auto-attached)
|
9070
|
+
** to the sqlite3_session object. The order in which the changes related to
|
9071
|
+
** a single table are stored is undefined.
|
9072
|
+
**
|
9073
|
+
** Following a successful call to this function, it is the responsibility of
|
9074
|
+
** the caller to eventually free the buffer that *ppChangeset points to using
|
9075
|
+
** [sqlite3_free()].
|
9076
|
+
**
|
9077
|
+
** <h3>Changeset Generation</h3>
|
9078
|
+
**
|
9079
|
+
** Once a table has been attached to a session object, the session object
|
9080
|
+
** records the primary key values of all new rows inserted into the table.
|
9081
|
+
** It also records the original primary key and other column values of any
|
9082
|
+
** deleted or updated rows. For each unique primary key value, data is only
|
9083
|
+
** recorded once - the first time a row with said primary key is inserted,
|
9084
|
+
** updated or deleted in the lifetime of the session.
|
9085
|
+
**
|
9086
|
+
** There is one exception to the previous paragraph: when a row is inserted,
|
9087
|
+
** updated or deleted, if one or more of its primary key columns contain a
|
9088
|
+
** NULL value, no record of the change is made.
|
9089
|
+
**
|
9090
|
+
** The session object therefore accumulates two types of records - those
|
9091
|
+
** that consist of primary key values only (created when the user inserts
|
9092
|
+
** a new record) and those that consist of the primary key values and the
|
9093
|
+
** original values of other table columns (created when the users deletes
|
9094
|
+
** or updates a record).
|
9095
|
+
**
|
9096
|
+
** When this function is called, the requested changeset is created using
|
9097
|
+
** both the accumulated records and the current contents of the database
|
9098
|
+
** file. Specifically:
|
9099
|
+
**
|
9100
|
+
** <ul>
|
9101
|
+
** <li> For each record generated by an insert, the database is queried
|
9102
|
+
** for a row with a matching primary key. If one is found, an INSERT
|
9103
|
+
** change is added to the changeset. If no such row is found, no change
|
9104
|
+
** is added to the changeset.
|
9105
|
+
**
|
9106
|
+
** <li> For each record generated by an update or delete, the database is
|
9107
|
+
** queried for a row with a matching primary key. If such a row is
|
9108
|
+
** found and one or more of the non-primary key fields have been
|
9109
|
+
** modified from their original values, an UPDATE change is added to
|
9110
|
+
** the changeset. Or, if no such row is found in the table, a DELETE
|
9111
|
+
** change is added to the changeset. If there is a row with a matching
|
9112
|
+
** primary key in the database, but all fields contain their original
|
9113
|
+
** values, no change is added to the changeset.
|
9114
|
+
** </ul>
|
9115
|
+
**
|
9116
|
+
** This means, amongst other things, that if a row is inserted and then later
|
9117
|
+
** deleted while a session object is active, neither the insert nor the delete
|
9118
|
+
** will be present in the changeset. Or if a row is deleted and then later a
|
9119
|
+
** row with the same primary key values inserted while a session object is
|
9120
|
+
** active, the resulting changeset will contain an UPDATE change instead of
|
9121
|
+
** a DELETE and an INSERT.
|
9122
|
+
**
|
9123
|
+
** When a session object is disabled (see the [sqlite3session_enable()] API),
|
9124
|
+
** it does not accumulate records when rows are inserted, updated or deleted.
|
9125
|
+
** This may appear to have some counter-intuitive effects if a single row
|
9126
|
+
** is written to more than once during a session. For example, if a row
|
9127
|
+
** is inserted while a session object is enabled, then later deleted while
|
9128
|
+
** the same session object is disabled, no INSERT record will appear in the
|
9129
|
+
** changeset, even though the delete took place while the session was disabled.
|
9130
|
+
** Or, if one field of a row is updated while a session is disabled, and
|
9131
|
+
** another field of the same row is updated while the session is enabled, the
|
9132
|
+
** resulting changeset will contain an UPDATE change that updates both fields.
|
9133
|
+
*/
|
9134
|
+
SQLITE_API int sqlite3session_changeset(
|
9135
|
+
sqlite3_session *pSession, /* Session object */
|
9136
|
+
int *pnChangeset, /* OUT: Size of buffer at *ppChangeset */
|
9137
|
+
void **ppChangeset /* OUT: Buffer containing changeset */
|
9138
|
+
);
|
9139
|
+
|
9140
|
+
/*
|
9141
|
+
** CAPI3REF: Load The Difference Between Tables Into A Session
|
9142
|
+
**
|
9143
|
+
** If it is not already attached to the session object passed as the first
|
9144
|
+
** argument, this function attaches table zTbl in the same manner as the
|
9145
|
+
** [sqlite3session_attach()] function. If zTbl does not exist, or if it
|
9146
|
+
** does not have a primary key, this function is a no-op (but does not return
|
9147
|
+
** an error).
|
9148
|
+
**
|
9149
|
+
** Argument zFromDb must be the name of a database ("main", "temp" etc.)
|
9150
|
+
** attached to the same database handle as the session object that contains
|
9151
|
+
** a table compatible with the table attached to the session by this function.
|
9152
|
+
** A table is considered compatible if it:
|
9153
|
+
**
|
9154
|
+
** <ul>
|
9155
|
+
** <li> Has the same name,
|
9156
|
+
** <li> Has the same set of columns declared in the same order, and
|
9157
|
+
** <li> Has the same PRIMARY KEY definition.
|
9158
|
+
** </ul>
|
9159
|
+
**
|
9160
|
+
** If the tables are not compatible, SQLITE_SCHEMA is returned. If the tables
|
9161
|
+
** are compatible but do not have any PRIMARY KEY columns, it is not an error
|
9162
|
+
** but no changes are added to the session object. As with other session
|
9163
|
+
** APIs, tables without PRIMARY KEYs are simply ignored.
|
9164
|
+
**
|
9165
|
+
** This function adds a set of changes to the session object that could be
|
9166
|
+
** used to update the table in database zFrom (call this the "from-table")
|
9167
|
+
** so that its content is the same as the table attached to the session
|
9168
|
+
** object (call this the "to-table"). Specifically:
|
9169
|
+
**
|
9170
|
+
** <ul>
|
9171
|
+
** <li> For each row (primary key) that exists in the to-table but not in
|
9172
|
+
** the from-table, an INSERT record is added to the session object.
|
9173
|
+
**
|
9174
|
+
** <li> For each row (primary key) that exists in the to-table but not in
|
9175
|
+
** the from-table, a DELETE record is added to the session object.
|
9176
|
+
**
|
9177
|
+
** <li> For each row (primary key) that exists in both tables, but features
|
9178
|
+
** different non-PK values in each, an UPDATE record is added to the
|
9179
|
+
** session.
|
9180
|
+
** </ul>
|
9181
|
+
**
|
9182
|
+
** To clarify, if this function is called and then a changeset constructed
|
9183
|
+
** using [sqlite3session_changeset()], then after applying that changeset to
|
9184
|
+
** database zFrom the contents of the two compatible tables would be
|
9185
|
+
** identical.
|
9186
|
+
**
|
9187
|
+
** It an error if database zFrom does not exist or does not contain the
|
9188
|
+
** required compatible table.
|
9189
|
+
**
|
9190
|
+
** If the operation successful, SQLITE_OK is returned. Otherwise, an SQLite
|
9191
|
+
** error code. In this case, if argument pzErrMsg is not NULL, *pzErrMsg
|
9192
|
+
** may be set to point to a buffer containing an English language error
|
9193
|
+
** message. It is the responsibility of the caller to free this buffer using
|
9194
|
+
** sqlite3_free().
|
9195
|
+
*/
|
9196
|
+
SQLITE_API int sqlite3session_diff(
|
9197
|
+
sqlite3_session *pSession,
|
9198
|
+
const char *zFromDb,
|
9199
|
+
const char *zTbl,
|
9200
|
+
char **pzErrMsg
|
9201
|
+
);
|
9202
|
+
|
9203
|
+
|
9204
|
+
/*
|
9205
|
+
** CAPI3REF: Generate A Patchset From A Session Object
|
9206
|
+
**
|
9207
|
+
** The differences between a patchset and a changeset are that:
|
9208
|
+
**
|
9209
|
+
** <ul>
|
9210
|
+
** <li> DELETE records consist of the primary key fields only. The
|
9211
|
+
** original values of other fields are omitted.
|
9212
|
+
** <li> The original values of any modified fields are omitted from
|
9213
|
+
** UPDATE records.
|
9214
|
+
** </ul>
|
9215
|
+
**
|
9216
|
+
** A patchset blob may be used with up to date versions of all
|
9217
|
+
** sqlite3changeset_xxx API functions except for sqlite3changeset_invert(),
|
9218
|
+
** which returns SQLITE_CORRUPT if it is passed a patchset. Similarly,
|
9219
|
+
** attempting to use a patchset blob with old versions of the
|
9220
|
+
** sqlite3changeset_xxx APIs also provokes an SQLITE_CORRUPT error.
|
9221
|
+
**
|
9222
|
+
** Because the non-primary key "old.*" fields are omitted, no
|
9223
|
+
** SQLITE_CHANGESET_DATA conflicts can be detected or reported if a patchset
|
9224
|
+
** is passed to the sqlite3changeset_apply() API. Other conflict types work
|
9225
|
+
** in the same way as for changesets.
|
9226
|
+
**
|
9227
|
+
** Changes within a patchset are ordered in the same way as for changesets
|
9228
|
+
** generated by the sqlite3session_changeset() function (i.e. all changes for
|
9229
|
+
** a single table are grouped together, tables appear in the order in which
|
9230
|
+
** they were attached to the session object).
|
9231
|
+
*/
|
9232
|
+
SQLITE_API int sqlite3session_patchset(
|
9233
|
+
sqlite3_session *pSession, /* Session object */
|
9234
|
+
int *pnPatchset, /* OUT: Size of buffer at *ppPatchset */
|
9235
|
+
void **ppPatchset /* OUT: Buffer containing patchset */
|
9236
|
+
);
|
9237
|
+
|
9238
|
+
/*
|
9239
|
+
** CAPI3REF: Test if a changeset has recorded any changes.
|
9240
|
+
**
|
9241
|
+
** Return non-zero if no changes to attached tables have been recorded by
|
9242
|
+
** the session object passed as the first argument. Otherwise, if one or
|
9243
|
+
** more changes have been recorded, return zero.
|
9244
|
+
**
|
9245
|
+
** Even if this function returns zero, it is possible that calling
|
9246
|
+
** [sqlite3session_changeset()] on the session handle may still return a
|
9247
|
+
** changeset that contains no changes. This can happen when a row in
|
9248
|
+
** an attached table is modified and then later on the original values
|
9249
|
+
** are restored. However, if this function returns non-zero, then it is
|
9250
|
+
** guaranteed that a call to sqlite3session_changeset() will return a
|
9251
|
+
** changeset containing zero changes.
|
9252
|
+
*/
|
9253
|
+
SQLITE_API int sqlite3session_isempty(sqlite3_session *pSession);
|
9254
|
+
|
9255
|
+
/*
|
9256
|
+
** CAPI3REF: Create An Iterator To Traverse A Changeset
|
9257
|
+
**
|
9258
|
+
** Create an iterator used to iterate through the contents of a changeset.
|
9259
|
+
** If successful, *pp is set to point to the iterator handle and SQLITE_OK
|
9260
|
+
** is returned. Otherwise, if an error occurs, *pp is set to zero and an
|
9261
|
+
** SQLite error code is returned.
|
9262
|
+
**
|
9263
|
+
** The following functions can be used to advance and query a changeset
|
9264
|
+
** iterator created by this function:
|
9265
|
+
**
|
9266
|
+
** <ul>
|
9267
|
+
** <li> [sqlite3changeset_next()]
|
9268
|
+
** <li> [sqlite3changeset_op()]
|
9269
|
+
** <li> [sqlite3changeset_new()]
|
9270
|
+
** <li> [sqlite3changeset_old()]
|
9271
|
+
** </ul>
|
9272
|
+
**
|
9273
|
+
** It is the responsibility of the caller to eventually destroy the iterator
|
9274
|
+
** by passing it to [sqlite3changeset_finalize()]. The buffer containing the
|
9275
|
+
** changeset (pChangeset) must remain valid until after the iterator is
|
9276
|
+
** destroyed.
|
9277
|
+
**
|
9278
|
+
** Assuming the changeset blob was created by one of the
|
9279
|
+
** [sqlite3session_changeset()], [sqlite3changeset_concat()] or
|
9280
|
+
** [sqlite3changeset_invert()] functions, all changes within the changeset
|
9281
|
+
** that apply to a single table are grouped together. This means that when
|
9282
|
+
** an application iterates through a changeset using an iterator created by
|
9283
|
+
** this function, all changes that relate to a single table are visited
|
9284
|
+
** consecutively. There is no chance that the iterator will visit a change
|
9285
|
+
** the applies to table X, then one for table Y, and then later on visit
|
9286
|
+
** another change for table X.
|
9287
|
+
*/
|
9288
|
+
SQLITE_API int sqlite3changeset_start(
|
9289
|
+
sqlite3_changeset_iter **pp, /* OUT: New changeset iterator handle */
|
9290
|
+
int nChangeset, /* Size of changeset blob in bytes */
|
9291
|
+
void *pChangeset /* Pointer to blob containing changeset */
|
9292
|
+
);
|
9293
|
+
|
9294
|
+
|
9295
|
+
/*
|
9296
|
+
** CAPI3REF: Advance A Changeset Iterator
|
9297
|
+
**
|
9298
|
+
** This function may only be used with iterators created by function
|
9299
|
+
** [sqlite3changeset_start()]. If it is called on an iterator passed to
|
9300
|
+
** a conflict-handler callback by [sqlite3changeset_apply()], SQLITE_MISUSE
|
9301
|
+
** is returned and the call has no effect.
|
9302
|
+
**
|
9303
|
+
** Immediately after an iterator is created by sqlite3changeset_start(), it
|
9304
|
+
** does not point to any change in the changeset. Assuming the changeset
|
9305
|
+
** is not empty, the first call to this function advances the iterator to
|
9306
|
+
** point to the first change in the changeset. Each subsequent call advances
|
9307
|
+
** the iterator to point to the next change in the changeset (if any). If
|
9308
|
+
** no error occurs and the iterator points to a valid change after a call
|
9309
|
+
** to sqlite3changeset_next() has advanced it, SQLITE_ROW is returned.
|
9310
|
+
** Otherwise, if all changes in the changeset have already been visited,
|
9311
|
+
** SQLITE_DONE is returned.
|
9312
|
+
**
|
9313
|
+
** If an error occurs, an SQLite error code is returned. Possible error
|
9314
|
+
** codes include SQLITE_CORRUPT (if the changeset buffer is corrupt) or
|
9315
|
+
** SQLITE_NOMEM.
|
9316
|
+
*/
|
9317
|
+
SQLITE_API int sqlite3changeset_next(sqlite3_changeset_iter *pIter);
|
9318
|
+
|
9319
|
+
/*
|
9320
|
+
** CAPI3REF: Obtain The Current Operation From A Changeset Iterator
|
9321
|
+
**
|
9322
|
+
** The pIter argument passed to this function may either be an iterator
|
9323
|
+
** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
|
9324
|
+
** created by [sqlite3changeset_start()]. In the latter case, the most recent
|
9325
|
+
** call to [sqlite3changeset_next()] must have returned [SQLITE_ROW]. If this
|
9326
|
+
** is not the case, this function returns [SQLITE_MISUSE].
|
9327
|
+
**
|
9328
|
+
** If argument pzTab is not NULL, then *pzTab is set to point to a
|
9329
|
+
** nul-terminated utf-8 encoded string containing the name of the table
|
9330
|
+
** affected by the current change. The buffer remains valid until either
|
9331
|
+
** sqlite3changeset_next() is called on the iterator or until the
|
9332
|
+
** conflict-handler function returns. If pnCol is not NULL, then *pnCol is
|
9333
|
+
** set to the number of columns in the table affected by the change. If
|
9334
|
+
** pbIncorrect is not NULL, then *pbIndirect is set to true (1) if the change
|
9335
|
+
** is an indirect change, or false (0) otherwise. See the documentation for
|
9336
|
+
** [sqlite3session_indirect()] for a description of direct and indirect
|
9337
|
+
** changes. Finally, if pOp is not NULL, then *pOp is set to one of
|
9338
|
+
** [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE], depending on the
|
9339
|
+
** type of change that the iterator currently points to.
|
9340
|
+
**
|
9341
|
+
** If no error occurs, SQLITE_OK is returned. If an error does occur, an
|
9342
|
+
** SQLite error code is returned. The values of the output variables may not
|
9343
|
+
** be trusted in this case.
|
9344
|
+
*/
|
9345
|
+
SQLITE_API int sqlite3changeset_op(
|
9346
|
+
sqlite3_changeset_iter *pIter, /* Iterator object */
|
9347
|
+
const char **pzTab, /* OUT: Pointer to table name */
|
9348
|
+
int *pnCol, /* OUT: Number of columns in table */
|
9349
|
+
int *pOp, /* OUT: SQLITE_INSERT, DELETE or UPDATE */
|
9350
|
+
int *pbIndirect /* OUT: True for an 'indirect' change */
|
9351
|
+
);
|
9352
|
+
|
9353
|
+
/*
|
9354
|
+
** CAPI3REF: Obtain The Primary Key Definition Of A Table
|
9355
|
+
**
|
9356
|
+
** For each modified table, a changeset includes the following:
|
9357
|
+
**
|
9358
|
+
** <ul>
|
9359
|
+
** <li> The number of columns in the table, and
|
9360
|
+
** <li> Which of those columns make up the tables PRIMARY KEY.
|
9361
|
+
** </ul>
|
9362
|
+
**
|
9363
|
+
** This function is used to find which columns comprise the PRIMARY KEY of
|
9364
|
+
** the table modified by the change that iterator pIter currently points to.
|
9365
|
+
** If successful, *pabPK is set to point to an array of nCol entries, where
|
9366
|
+
** nCol is the number of columns in the table. Elements of *pabPK are set to
|
9367
|
+
** 0x01 if the corresponding column is part of the tables primary key, or
|
9368
|
+
** 0x00 if it is not.
|
9369
|
+
**
|
9370
|
+
** If argument pnCol is not NULL, then *pnCol is set to the number of columns
|
9371
|
+
** in the table.
|
9372
|
+
**
|
9373
|
+
** If this function is called when the iterator does not point to a valid
|
9374
|
+
** entry, SQLITE_MISUSE is returned and the output variables zeroed. Otherwise,
|
9375
|
+
** SQLITE_OK is returned and the output variables populated as described
|
9376
|
+
** above.
|
9377
|
+
*/
|
9378
|
+
SQLITE_API int sqlite3changeset_pk(
|
9379
|
+
sqlite3_changeset_iter *pIter, /* Iterator object */
|
9380
|
+
unsigned char **pabPK, /* OUT: Array of boolean - true for PK cols */
|
9381
|
+
int *pnCol /* OUT: Number of entries in output array */
|
9382
|
+
);
|
9383
|
+
|
9384
|
+
/*
|
9385
|
+
** CAPI3REF: Obtain old.* Values From A Changeset Iterator
|
9386
|
+
**
|
9387
|
+
** The pIter argument passed to this function may either be an iterator
|
9388
|
+
** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
|
9389
|
+
** created by [sqlite3changeset_start()]. In the latter case, the most recent
|
9390
|
+
** call to [sqlite3changeset_next()] must have returned SQLITE_ROW.
|
9391
|
+
** Furthermore, it may only be called if the type of change that the iterator
|
9392
|
+
** currently points to is either [SQLITE_DELETE] or [SQLITE_UPDATE]. Otherwise,
|
9393
|
+
** this function returns [SQLITE_MISUSE] and sets *ppValue to NULL.
|
9394
|
+
**
|
9395
|
+
** Argument iVal must be greater than or equal to 0, and less than the number
|
9396
|
+
** of columns in the table affected by the current change. Otherwise,
|
9397
|
+
** [SQLITE_RANGE] is returned and *ppValue is set to NULL.
|
9398
|
+
**
|
9399
|
+
** If successful, this function sets *ppValue to point to a protected
|
9400
|
+
** sqlite3_value object containing the iVal'th value from the vector of
|
9401
|
+
** original row values stored as part of the UPDATE or DELETE change and
|
9402
|
+
** returns SQLITE_OK. The name of the function comes from the fact that this
|
9403
|
+
** is similar to the "old.*" columns available to update or delete triggers.
|
9404
|
+
**
|
9405
|
+
** If some other error occurs (e.g. an OOM condition), an SQLite error code
|
9406
|
+
** is returned and *ppValue is set to NULL.
|
9407
|
+
*/
|
9408
|
+
SQLITE_API int sqlite3changeset_old(
|
9409
|
+
sqlite3_changeset_iter *pIter, /* Changeset iterator */
|
9410
|
+
int iVal, /* Column number */
|
9411
|
+
sqlite3_value **ppValue /* OUT: Old value (or NULL pointer) */
|
9412
|
+
);
|
9413
|
+
|
9414
|
+
/*
|
9415
|
+
** CAPI3REF: Obtain new.* Values From A Changeset Iterator
|
9416
|
+
**
|
9417
|
+
** The pIter argument passed to this function may either be an iterator
|
9418
|
+
** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
|
9419
|
+
** created by [sqlite3changeset_start()]. In the latter case, the most recent
|
9420
|
+
** call to [sqlite3changeset_next()] must have returned SQLITE_ROW.
|
9421
|
+
** Furthermore, it may only be called if the type of change that the iterator
|
9422
|
+
** currently points to is either [SQLITE_UPDATE] or [SQLITE_INSERT]. Otherwise,
|
9423
|
+
** this function returns [SQLITE_MISUSE] and sets *ppValue to NULL.
|
9424
|
+
**
|
9425
|
+
** Argument iVal must be greater than or equal to 0, and less than the number
|
9426
|
+
** of columns in the table affected by the current change. Otherwise,
|
9427
|
+
** [SQLITE_RANGE] is returned and *ppValue is set to NULL.
|
9428
|
+
**
|
9429
|
+
** If successful, this function sets *ppValue to point to a protected
|
9430
|
+
** sqlite3_value object containing the iVal'th value from the vector of
|
9431
|
+
** new row values stored as part of the UPDATE or INSERT change and
|
9432
|
+
** returns SQLITE_OK. If the change is an UPDATE and does not include
|
9433
|
+
** a new value for the requested column, *ppValue is set to NULL and
|
9434
|
+
** SQLITE_OK returned. The name of the function comes from the fact that
|
9435
|
+
** this is similar to the "new.*" columns available to update or delete
|
9436
|
+
** triggers.
|
9437
|
+
**
|
9438
|
+
** If some other error occurs (e.g. an OOM condition), an SQLite error code
|
9439
|
+
** is returned and *ppValue is set to NULL.
|
9440
|
+
*/
|
9441
|
+
SQLITE_API int sqlite3changeset_new(
|
9442
|
+
sqlite3_changeset_iter *pIter, /* Changeset iterator */
|
9443
|
+
int iVal, /* Column number */
|
9444
|
+
sqlite3_value **ppValue /* OUT: New value (or NULL pointer) */
|
9445
|
+
);
|
9446
|
+
|
9447
|
+
/*
|
9448
|
+
** CAPI3REF: Obtain Conflicting Row Values From A Changeset Iterator
|
9449
|
+
**
|
9450
|
+
** This function should only be used with iterator objects passed to a
|
9451
|
+
** conflict-handler callback by [sqlite3changeset_apply()] with either
|
9452
|
+
** [SQLITE_CHANGESET_DATA] or [SQLITE_CHANGESET_CONFLICT]. If this function
|
9453
|
+
** is called on any other iterator, [SQLITE_MISUSE] is returned and *ppValue
|
9454
|
+
** is set to NULL.
|
9455
|
+
**
|
9456
|
+
** Argument iVal must be greater than or equal to 0, and less than the number
|
9457
|
+
** of columns in the table affected by the current change. Otherwise,
|
9458
|
+
** [SQLITE_RANGE] is returned and *ppValue is set to NULL.
|
9459
|
+
**
|
9460
|
+
** If successful, this function sets *ppValue to point to a protected
|
9461
|
+
** sqlite3_value object containing the iVal'th value from the
|
9462
|
+
** "conflicting row" associated with the current conflict-handler callback
|
9463
|
+
** and returns SQLITE_OK.
|
9464
|
+
**
|
9465
|
+
** If some other error occurs (e.g. an OOM condition), an SQLite error code
|
9466
|
+
** is returned and *ppValue is set to NULL.
|
9467
|
+
*/
|
9468
|
+
SQLITE_API int sqlite3changeset_conflict(
|
9469
|
+
sqlite3_changeset_iter *pIter, /* Changeset iterator */
|
9470
|
+
int iVal, /* Column number */
|
9471
|
+
sqlite3_value **ppValue /* OUT: Value from conflicting row */
|
9472
|
+
);
|
9473
|
+
|
9474
|
+
/*
|
9475
|
+
** CAPI3REF: Determine The Number Of Foreign Key Constraint Violations
|
9476
|
+
**
|
9477
|
+
** This function may only be called with an iterator passed to an
|
9478
|
+
** SQLITE_CHANGESET_FOREIGN_KEY conflict handler callback. In this case
|
9479
|
+
** it sets the output variable to the total number of known foreign key
|
9480
|
+
** violations in the destination database and returns SQLITE_OK.
|
9481
|
+
**
|
9482
|
+
** In all other cases this function returns SQLITE_MISUSE.
|
9483
|
+
*/
|
9484
|
+
SQLITE_API int sqlite3changeset_fk_conflicts(
|
9485
|
+
sqlite3_changeset_iter *pIter, /* Changeset iterator */
|
9486
|
+
int *pnOut /* OUT: Number of FK violations */
|
9487
|
+
);
|
9488
|
+
|
9489
|
+
|
9490
|
+
/*
|
9491
|
+
** CAPI3REF: Finalize A Changeset Iterator
|
9492
|
+
**
|
9493
|
+
** This function is used to finalize an iterator allocated with
|
9494
|
+
** [sqlite3changeset_start()].
|
9495
|
+
**
|
9496
|
+
** This function should only be called on iterators created using the
|
9497
|
+
** [sqlite3changeset_start()] function. If an application calls this
|
9498
|
+
** function with an iterator passed to a conflict-handler by
|
9499
|
+
** [sqlite3changeset_apply()], [SQLITE_MISUSE] is immediately returned and the
|
9500
|
+
** call has no effect.
|
9501
|
+
**
|
9502
|
+
** If an error was encountered within a call to an sqlite3changeset_xxx()
|
9503
|
+
** function (for example an [SQLITE_CORRUPT] in [sqlite3changeset_next()] or an
|
9504
|
+
** [SQLITE_NOMEM] in [sqlite3changeset_new()]) then an error code corresponding
|
9505
|
+
** to that error is returned by this function. Otherwise, SQLITE_OK is
|
9506
|
+
** returned. This is to allow the following pattern (pseudo-code):
|
9507
|
+
**
|
9508
|
+
** sqlite3changeset_start();
|
9509
|
+
** while( SQLITE_ROW==sqlite3changeset_next() ){
|
9510
|
+
** // Do something with change.
|
9511
|
+
** }
|
9512
|
+
** rc = sqlite3changeset_finalize();
|
9513
|
+
** if( rc!=SQLITE_OK ){
|
9514
|
+
** // An error has occurred
|
9515
|
+
** }
|
9516
|
+
*/
|
9517
|
+
SQLITE_API int sqlite3changeset_finalize(sqlite3_changeset_iter *pIter);
|
9518
|
+
|
9519
|
+
/*
|
9520
|
+
** CAPI3REF: Invert A Changeset
|
9521
|
+
**
|
9522
|
+
** This function is used to "invert" a changeset object. Applying an inverted
|
9523
|
+
** changeset to a database reverses the effects of applying the uninverted
|
9524
|
+
** changeset. Specifically:
|
9525
|
+
**
|
9526
|
+
** <ul>
|
9527
|
+
** <li> Each DELETE change is changed to an INSERT, and
|
9528
|
+
** <li> Each INSERT change is changed to a DELETE, and
|
9529
|
+
** <li> For each UPDATE change, the old.* and new.* values are exchanged.
|
9530
|
+
** </ul>
|
9531
|
+
**
|
9532
|
+
** This function does not change the order in which changes appear within
|
9533
|
+
** the changeset. It merely reverses the sense of each individual change.
|
9534
|
+
**
|
9535
|
+
** If successful, a pointer to a buffer containing the inverted changeset
|
9536
|
+
** is stored in *ppOut, the size of the same buffer is stored in *pnOut, and
|
9537
|
+
** SQLITE_OK is returned. If an error occurs, both *pnOut and *ppOut are
|
9538
|
+
** zeroed and an SQLite error code returned.
|
9539
|
+
**
|
9540
|
+
** It is the responsibility of the caller to eventually call sqlite3_free()
|
9541
|
+
** on the *ppOut pointer to free the buffer allocation following a successful
|
9542
|
+
** call to this function.
|
9543
|
+
**
|
9544
|
+
** WARNING/TODO: This function currently assumes that the input is a valid
|
9545
|
+
** changeset. If it is not, the results are undefined.
|
9546
|
+
*/
|
9547
|
+
SQLITE_API int sqlite3changeset_invert(
|
9548
|
+
int nIn, const void *pIn, /* Input changeset */
|
9549
|
+
int *pnOut, void **ppOut /* OUT: Inverse of input */
|
9550
|
+
);
|
9551
|
+
|
9552
|
+
/*
|
9553
|
+
** CAPI3REF: Concatenate Two Changeset Objects
|
9554
|
+
**
|
9555
|
+
** This function is used to concatenate two changesets, A and B, into a
|
9556
|
+
** single changeset. The result is a changeset equivalent to applying
|
9557
|
+
** changeset A followed by changeset B.
|
9558
|
+
**
|
9559
|
+
** This function combines the two input changesets using an
|
9560
|
+
** sqlite3_changegroup object. Calling it produces similar results as the
|
9561
|
+
** following code fragment:
|
9562
|
+
**
|
9563
|
+
** sqlite3_changegroup *pGrp;
|
9564
|
+
** rc = sqlite3_changegroup_new(&pGrp);
|
9565
|
+
** if( rc==SQLITE_OK ) rc = sqlite3changegroup_add(pGrp, nA, pA);
|
9566
|
+
** if( rc==SQLITE_OK ) rc = sqlite3changegroup_add(pGrp, nB, pB);
|
9567
|
+
** if( rc==SQLITE_OK ){
|
9568
|
+
** rc = sqlite3changegroup_output(pGrp, pnOut, ppOut);
|
9569
|
+
** }else{
|
9570
|
+
** *ppOut = 0;
|
9571
|
+
** *pnOut = 0;
|
9572
|
+
** }
|
9573
|
+
**
|
9574
|
+
** Refer to the sqlite3_changegroup documentation below for details.
|
9575
|
+
*/
|
9576
|
+
SQLITE_API int sqlite3changeset_concat(
|
9577
|
+
int nA, /* Number of bytes in buffer pA */
|
9578
|
+
void *pA, /* Pointer to buffer containing changeset A */
|
9579
|
+
int nB, /* Number of bytes in buffer pB */
|
9580
|
+
void *pB, /* Pointer to buffer containing changeset B */
|
9581
|
+
int *pnOut, /* OUT: Number of bytes in output changeset */
|
9582
|
+
void **ppOut /* OUT: Buffer containing output changeset */
|
9583
|
+
);
|
9584
|
+
|
9585
|
+
|
9586
|
+
/*
|
9587
|
+
** CAPI3REF: Changegroup Handle
|
9588
|
+
*/
|
9589
|
+
typedef struct sqlite3_changegroup sqlite3_changegroup;
|
9590
|
+
|
9591
|
+
/*
|
9592
|
+
** CAPI3REF: Create A New Changegroup Object
|
9593
|
+
**
|
9594
|
+
** An sqlite3_changegroup object is used to combine two or more changesets
|
9595
|
+
** (or patchsets) into a single changeset (or patchset). A single changegroup
|
9596
|
+
** object may combine changesets or patchsets, but not both. The output is
|
9597
|
+
** always in the same format as the input.
|
9598
|
+
**
|
9599
|
+
** If successful, this function returns SQLITE_OK and populates (*pp) with
|
9600
|
+
** a pointer to a new sqlite3_changegroup object before returning. The caller
|
9601
|
+
** should eventually free the returned object using a call to
|
9602
|
+
** sqlite3changegroup_delete(). If an error occurs, an SQLite error code
|
9603
|
+
** (i.e. SQLITE_NOMEM) is returned and *pp is set to NULL.
|
9604
|
+
**
|
9605
|
+
** The usual usage pattern for an sqlite3_changegroup object is as follows:
|
9606
|
+
**
|
9607
|
+
** <ul>
|
9608
|
+
** <li> It is created using a call to sqlite3changegroup_new().
|
9609
|
+
**
|
9610
|
+
** <li> Zero or more changesets (or patchsets) are added to the object
|
9611
|
+
** by calling sqlite3changegroup_add().
|
9612
|
+
**
|
9613
|
+
** <li> The result of combining all input changesets together is obtained
|
9614
|
+
** by the application via a call to sqlite3changegroup_output().
|
9615
|
+
**
|
9616
|
+
** <li> The object is deleted using a call to sqlite3changegroup_delete().
|
9617
|
+
** </ul>
|
9618
|
+
**
|
9619
|
+
** Any number of calls to add() and output() may be made between the calls to
|
9620
|
+
** new() and delete(), and in any order.
|
9621
|
+
**
|
9622
|
+
** As well as the regular sqlite3changegroup_add() and
|
9623
|
+
** sqlite3changegroup_output() functions, also available are the streaming
|
9624
|
+
** versions sqlite3changegroup_add_strm() and sqlite3changegroup_output_strm().
|
9625
|
+
*/
|
9626
|
+
SQLITE_API int sqlite3changegroup_new(sqlite3_changegroup **pp);
|
9627
|
+
|
9628
|
+
/*
|
9629
|
+
** CAPI3REF: Add A Changeset To A Changegroup
|
9630
|
+
**
|
9631
|
+
** Add all changes within the changeset (or patchset) in buffer pData (size
|
9632
|
+
** nData bytes) to the changegroup.
|
9633
|
+
**
|
9634
|
+
** If the buffer contains a patchset, then all prior calls to this function
|
9635
|
+
** on the same changegroup object must also have specified patchsets. Or, if
|
9636
|
+
** the buffer contains a changeset, so must have the earlier calls to this
|
9637
|
+
** function. Otherwise, SQLITE_ERROR is returned and no changes are added
|
9638
|
+
** to the changegroup.
|
9639
|
+
**
|
9640
|
+
** Rows within the changeset and changegroup are identified by the values in
|
9641
|
+
** their PRIMARY KEY columns. A change in the changeset is considered to
|
9642
|
+
** apply to the same row as a change already present in the changegroup if
|
9643
|
+
** the two rows have the same primary key.
|
9644
|
+
**
|
9645
|
+
** Changes to rows that do not already appear in the changegroup are
|
9646
|
+
** simply copied into it. Or, if both the new changeset and the changegroup
|
9647
|
+
** contain changes that apply to a single row, the final contents of the
|
9648
|
+
** changegroup depends on the type of each change, as follows:
|
9649
|
+
**
|
9650
|
+
** <table border=1 style="margin-left:8ex;margin-right:8ex">
|
9651
|
+
** <tr><th style="white-space:pre">Existing Change </th>
|
9652
|
+
** <th style="white-space:pre">New Change </th>
|
9653
|
+
** <th>Output Change
|
9654
|
+
** <tr><td>INSERT <td>INSERT <td>
|
9655
|
+
** The new change is ignored. This case does not occur if the new
|
9656
|
+
** changeset was recorded immediately after the changesets already
|
9657
|
+
** added to the changegroup.
|
9658
|
+
** <tr><td>INSERT <td>UPDATE <td>
|
9659
|
+
** The INSERT change remains in the changegroup. The values in the
|
9660
|
+
** INSERT change are modified as if the row was inserted by the
|
9661
|
+
** existing change and then updated according to the new change.
|
9662
|
+
** <tr><td>INSERT <td>DELETE <td>
|
9663
|
+
** The existing INSERT is removed from the changegroup. The DELETE is
|
9664
|
+
** not added.
|
9665
|
+
** <tr><td>UPDATE <td>INSERT <td>
|
9666
|
+
** The new change is ignored. This case does not occur if the new
|
9667
|
+
** changeset was recorded immediately after the changesets already
|
9668
|
+
** added to the changegroup.
|
9669
|
+
** <tr><td>UPDATE <td>UPDATE <td>
|
9670
|
+
** The existing UPDATE remains within the changegroup. It is amended
|
9671
|
+
** so that the accompanying values are as if the row was updated once
|
9672
|
+
** by the existing change and then again by the new change.
|
9673
|
+
** <tr><td>UPDATE <td>DELETE <td>
|
9674
|
+
** The existing UPDATE is replaced by the new DELETE within the
|
9675
|
+
** changegroup.
|
9676
|
+
** <tr><td>DELETE <td>INSERT <td>
|
9677
|
+
** If one or more of the column values in the row inserted by the
|
9678
|
+
** new change differ from those in the row deleted by the existing
|
9679
|
+
** change, the existing DELETE is replaced by an UPDATE within the
|
9680
|
+
** changegroup. Otherwise, if the inserted row is exactly the same
|
9681
|
+
** as the deleted row, the existing DELETE is simply discarded.
|
9682
|
+
** <tr><td>DELETE <td>UPDATE <td>
|
9683
|
+
** The new change is ignored. This case does not occur if the new
|
9684
|
+
** changeset was recorded immediately after the changesets already
|
9685
|
+
** added to the changegroup.
|
9686
|
+
** <tr><td>DELETE <td>DELETE <td>
|
9687
|
+
** The new change is ignored. This case does not occur if the new
|
9688
|
+
** changeset was recorded immediately after the changesets already
|
9689
|
+
** added to the changegroup.
|
9690
|
+
** </table>
|
9691
|
+
**
|
9692
|
+
** If the new changeset contains changes to a table that is already present
|
9693
|
+
** in the changegroup, then the number of columns and the position of the
|
9694
|
+
** primary key columns for the table must be consistent. If this is not the
|
9695
|
+
** case, this function fails with SQLITE_SCHEMA. If the input changeset
|
9696
|
+
** appears to be corrupt and the corruption is detected, SQLITE_CORRUPT is
|
9697
|
+
** returned. Or, if an out-of-memory condition occurs during processing, this
|
9698
|
+
** function returns SQLITE_NOMEM. In all cases, if an error occurs the
|
9699
|
+
** final contents of the changegroup is undefined.
|
9700
|
+
**
|
9701
|
+
** If no error occurs, SQLITE_OK is returned.
|
9702
|
+
*/
|
9703
|
+
SQLITE_API int sqlite3changegroup_add(sqlite3_changegroup*, int nData, void *pData);
|
9704
|
+
|
9705
|
+
/*
|
9706
|
+
** CAPI3REF: Obtain A Composite Changeset From A Changegroup
|
9707
|
+
**
|
9708
|
+
** Obtain a buffer containing a changeset (or patchset) representing the
|
9709
|
+
** current contents of the changegroup. If the inputs to the changegroup
|
9710
|
+
** were themselves changesets, the output is a changeset. Or, if the
|
9711
|
+
** inputs were patchsets, the output is also a patchset.
|
9712
|
+
**
|
9713
|
+
** As with the output of the sqlite3session_changeset() and
|
9714
|
+
** sqlite3session_patchset() functions, all changes related to a single
|
9715
|
+
** table are grouped together in the output of this function. Tables appear
|
9716
|
+
** in the same order as for the very first changeset added to the changegroup.
|
9717
|
+
** If the second or subsequent changesets added to the changegroup contain
|
9718
|
+
** changes for tables that do not appear in the first changeset, they are
|
9719
|
+
** appended onto the end of the output changeset, again in the order in
|
9720
|
+
** which they are first encountered.
|
9721
|
+
**
|
9722
|
+
** If an error occurs, an SQLite error code is returned and the output
|
9723
|
+
** variables (*pnData) and (*ppData) are set to 0. Otherwise, SQLITE_OK
|
9724
|
+
** is returned and the output variables are set to the size of and a
|
9725
|
+
** pointer to the output buffer, respectively. In this case it is the
|
9726
|
+
** responsibility of the caller to eventually free the buffer using a
|
9727
|
+
** call to sqlite3_free().
|
9728
|
+
*/
|
9729
|
+
SQLITE_API int sqlite3changegroup_output(
|
9730
|
+
sqlite3_changegroup*,
|
9731
|
+
int *pnData, /* OUT: Size of output buffer in bytes */
|
9732
|
+
void **ppData /* OUT: Pointer to output buffer */
|
9733
|
+
);
|
9734
|
+
|
9735
|
+
/*
|
9736
|
+
** CAPI3REF: Delete A Changegroup Object
|
9737
|
+
*/
|
9738
|
+
SQLITE_API void sqlite3changegroup_delete(sqlite3_changegroup*);
|
9739
|
+
|
9740
|
+
/*
|
9741
|
+
** CAPI3REF: Apply A Changeset To A Database
|
9742
|
+
**
|
9743
|
+
** Apply a changeset to a database. This function attempts to update the
|
9744
|
+
** "main" database attached to handle db with the changes found in the
|
9745
|
+
** changeset passed via the second and third arguments.
|
9746
|
+
**
|
9747
|
+
** The fourth argument (xFilter) passed to this function is the "filter
|
9748
|
+
** callback". If it is not NULL, then for each table affected by at least one
|
9749
|
+
** change in the changeset, the filter callback is invoked with
|
9750
|
+
** the table name as the second argument, and a copy of the context pointer
|
9751
|
+
** passed as the sixth argument to this function as the first. If the "filter
|
9752
|
+
** callback" returns zero, then no attempt is made to apply any changes to
|
9753
|
+
** the table. Otherwise, if the return value is non-zero or the xFilter
|
9754
|
+
** argument to this function is NULL, all changes related to the table are
|
9755
|
+
** attempted.
|
9756
|
+
**
|
9757
|
+
** For each table that is not excluded by the filter callback, this function
|
9758
|
+
** tests that the target database contains a compatible table. A table is
|
9759
|
+
** considered compatible if all of the following are true:
|
9760
|
+
**
|
9761
|
+
** <ul>
|
9762
|
+
** <li> The table has the same name as the name recorded in the
|
9763
|
+
** changeset, and
|
9764
|
+
** <li> The table has at least as many columns as recorded in the
|
9765
|
+
** changeset, and
|
9766
|
+
** <li> The table has primary key columns in the same position as
|
9767
|
+
** recorded in the changeset.
|
9768
|
+
** </ul>
|
9769
|
+
**
|
9770
|
+
** If there is no compatible table, it is not an error, but none of the
|
9771
|
+
** changes associated with the table are applied. A warning message is issued
|
9772
|
+
** via the sqlite3_log() mechanism with the error code SQLITE_SCHEMA. At most
|
9773
|
+
** one such warning is issued for each table in the changeset.
|
9774
|
+
**
|
9775
|
+
** For each change for which there is a compatible table, an attempt is made
|
9776
|
+
** to modify the table contents according to the UPDATE, INSERT or DELETE
|
9777
|
+
** change. If a change cannot be applied cleanly, the conflict handler
|
9778
|
+
** function passed as the fifth argument to sqlite3changeset_apply() may be
|
9779
|
+
** invoked. A description of exactly when the conflict handler is invoked for
|
9780
|
+
** each type of change is below.
|
9781
|
+
**
|
9782
|
+
** Unlike the xFilter argument, xConflict may not be passed NULL. The results
|
9783
|
+
** of passing anything other than a valid function pointer as the xConflict
|
9784
|
+
** argument are undefined.
|
9785
|
+
**
|
9786
|
+
** Each time the conflict handler function is invoked, it must return one
|
9787
|
+
** of [SQLITE_CHANGESET_OMIT], [SQLITE_CHANGESET_ABORT] or
|
9788
|
+
** [SQLITE_CHANGESET_REPLACE]. SQLITE_CHANGESET_REPLACE may only be returned
|
9789
|
+
** if the second argument passed to the conflict handler is either
|
9790
|
+
** SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If the conflict-handler
|
9791
|
+
** returns an illegal value, any changes already made are rolled back and
|
9792
|
+
** the call to sqlite3changeset_apply() returns SQLITE_MISUSE. Different
|
9793
|
+
** actions are taken by sqlite3changeset_apply() depending on the value
|
9794
|
+
** returned by each invocation of the conflict-handler function. Refer to
|
9795
|
+
** the documentation for the three
|
9796
|
+
** [SQLITE_CHANGESET_OMIT|available return values] for details.
|
9797
|
+
**
|
9798
|
+
** <dl>
|
9799
|
+
** <dt>DELETE Changes<dd>
|
9800
|
+
** For each DELETE change, this function checks if the target database
|
9801
|
+
** contains a row with the same primary key value (or values) as the
|
9802
|
+
** original row values stored in the changeset. If it does, and the values
|
9803
|
+
** stored in all non-primary key columns also match the values stored in
|
9804
|
+
** the changeset the row is deleted from the target database.
|
9805
|
+
**
|
9806
|
+
** If a row with matching primary key values is found, but one or more of
|
9807
|
+
** the non-primary key fields contains a value different from the original
|
9808
|
+
** row value stored in the changeset, the conflict-handler function is
|
9809
|
+
** invoked with [SQLITE_CHANGESET_DATA] as the second argument. If the
|
9810
|
+
** database table has more columns than are recorded in the changeset,
|
9811
|
+
** only the values of those non-primary key fields are compared against
|
9812
|
+
** the current database contents - any trailing database table columns
|
9813
|
+
** are ignored.
|
9814
|
+
**
|
9815
|
+
** If no row with matching primary key values is found in the database,
|
9816
|
+
** the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND]
|
9817
|
+
** passed as the second argument.
|
9818
|
+
**
|
9819
|
+
** If the DELETE operation is attempted, but SQLite returns SQLITE_CONSTRAINT
|
9820
|
+
** (which can only happen if a foreign key constraint is violated), the
|
9821
|
+
** conflict-handler function is invoked with [SQLITE_CHANGESET_CONSTRAINT]
|
9822
|
+
** passed as the second argument. This includes the case where the DELETE
|
9823
|
+
** operation is attempted because an earlier call to the conflict handler
|
9824
|
+
** function returned [SQLITE_CHANGESET_REPLACE].
|
9825
|
+
**
|
9826
|
+
** <dt>INSERT Changes<dd>
|
9827
|
+
** For each INSERT change, an attempt is made to insert the new row into
|
9828
|
+
** the database. If the changeset row contains fewer fields than the
|
9829
|
+
** database table, the trailing fields are populated with their default
|
9830
|
+
** values.
|
9831
|
+
**
|
9832
|
+
** If the attempt to insert the row fails because the database already
|
9833
|
+
** contains a row with the same primary key values, the conflict handler
|
9834
|
+
** function is invoked with the second argument set to
|
9835
|
+
** [SQLITE_CHANGESET_CONFLICT].
|
9836
|
+
**
|
9837
|
+
** If the attempt to insert the row fails because of some other constraint
|
9838
|
+
** violation (e.g. NOT NULL or UNIQUE), the conflict handler function is
|
9839
|
+
** invoked with the second argument set to [SQLITE_CHANGESET_CONSTRAINT].
|
9840
|
+
** This includes the case where the INSERT operation is re-attempted because
|
9841
|
+
** an earlier call to the conflict handler function returned
|
9842
|
+
** [SQLITE_CHANGESET_REPLACE].
|
9843
|
+
**
|
9844
|
+
** <dt>UPDATE Changes<dd>
|
9845
|
+
** For each UPDATE change, this function checks if the target database
|
9846
|
+
** contains a row with the same primary key value (or values) as the
|
9847
|
+
** original row values stored in the changeset. If it does, and the values
|
9848
|
+
** stored in all modified non-primary key columns also match the values
|
9849
|
+
** stored in the changeset the row is updated within the target database.
|
9850
|
+
**
|
9851
|
+
** If a row with matching primary key values is found, but one or more of
|
9852
|
+
** the modified non-primary key fields contains a value different from an
|
9853
|
+
** original row value stored in the changeset, the conflict-handler function
|
9854
|
+
** is invoked with [SQLITE_CHANGESET_DATA] as the second argument. Since
|
9855
|
+
** UPDATE changes only contain values for non-primary key fields that are
|
9856
|
+
** to be modified, only those fields need to match the original values to
|
9857
|
+
** avoid the SQLITE_CHANGESET_DATA conflict-handler callback.
|
9858
|
+
**
|
9859
|
+
** If no row with matching primary key values is found in the database,
|
9860
|
+
** the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND]
|
9861
|
+
** passed as the second argument.
|
9862
|
+
**
|
9863
|
+
** If the UPDATE operation is attempted, but SQLite returns
|
9864
|
+
** SQLITE_CONSTRAINT, the conflict-handler function is invoked with
|
9865
|
+
** [SQLITE_CHANGESET_CONSTRAINT] passed as the second argument.
|
9866
|
+
** This includes the case where the UPDATE operation is attempted after
|
9867
|
+
** an earlier call to the conflict handler function returned
|
9868
|
+
** [SQLITE_CHANGESET_REPLACE].
|
9869
|
+
** </dl>
|
9870
|
+
**
|
9871
|
+
** It is safe to execute SQL statements, including those that write to the
|
9872
|
+
** table that the callback related to, from within the xConflict callback.
|
9873
|
+
** This can be used to further customize the applications conflict
|
9874
|
+
** resolution strategy.
|
9875
|
+
**
|
9876
|
+
** All changes made by this function are enclosed in a savepoint transaction.
|
9877
|
+
** If any other error (aside from a constraint failure when attempting to
|
9878
|
+
** write to the target database) occurs, then the savepoint transaction is
|
9879
|
+
** rolled back, restoring the target database to its original state, and an
|
9880
|
+
** SQLite error code returned.
|
9881
|
+
*/
|
9882
|
+
SQLITE_API int sqlite3changeset_apply(
|
9883
|
+
sqlite3 *db, /* Apply change to "main" db of this handle */
|
9884
|
+
int nChangeset, /* Size of changeset in bytes */
|
9885
|
+
void *pChangeset, /* Changeset blob */
|
9886
|
+
int(*xFilter)(
|
9887
|
+
void *pCtx, /* Copy of sixth arg to _apply() */
|
9888
|
+
const char *zTab /* Table name */
|
9889
|
+
),
|
9890
|
+
int(*xConflict)(
|
9891
|
+
void *pCtx, /* Copy of sixth arg to _apply() */
|
9892
|
+
int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
|
9893
|
+
sqlite3_changeset_iter *p /* Handle describing change and conflict */
|
9894
|
+
),
|
9895
|
+
void *pCtx /* First argument passed to xConflict */
|
9896
|
+
);
|
9897
|
+
|
9898
|
+
/*
|
9899
|
+
** CAPI3REF: Constants Passed To The Conflict Handler
|
9900
|
+
**
|
9901
|
+
** Values that may be passed as the second argument to a conflict-handler.
|
9902
|
+
**
|
9903
|
+
** <dl>
|
9904
|
+
** <dt>SQLITE_CHANGESET_DATA<dd>
|
9905
|
+
** The conflict handler is invoked with CHANGESET_DATA as the second argument
|
9906
|
+
** when processing a DELETE or UPDATE change if a row with the required
|
9907
|
+
** PRIMARY KEY fields is present in the database, but one or more other
|
9908
|
+
** (non primary-key) fields modified by the update do not contain the
|
9909
|
+
** expected "before" values.
|
9910
|
+
**
|
9911
|
+
** The conflicting row, in this case, is the database row with the matching
|
9912
|
+
** primary key.
|
9913
|
+
**
|
9914
|
+
** <dt>SQLITE_CHANGESET_NOTFOUND<dd>
|
9915
|
+
** The conflict handler is invoked with CHANGESET_NOTFOUND as the second
|
9916
|
+
** argument when processing a DELETE or UPDATE change if a row with the
|
9917
|
+
** required PRIMARY KEY fields is not present in the database.
|
9918
|
+
**
|
9919
|
+
** There is no conflicting row in this case. The results of invoking the
|
9920
|
+
** sqlite3changeset_conflict() API are undefined.
|
9921
|
+
**
|
9922
|
+
** <dt>SQLITE_CHANGESET_CONFLICT<dd>
|
9923
|
+
** CHANGESET_CONFLICT is passed as the second argument to the conflict
|
9924
|
+
** handler while processing an INSERT change if the operation would result
|
9925
|
+
** in duplicate primary key values.
|
9926
|
+
**
|
9927
|
+
** The conflicting row in this case is the database row with the matching
|
9928
|
+
** primary key.
|
9929
|
+
**
|
9930
|
+
** <dt>SQLITE_CHANGESET_FOREIGN_KEY<dd>
|
9931
|
+
** If foreign key handling is enabled, and applying a changeset leaves the
|
9932
|
+
** database in a state containing foreign key violations, the conflict
|
9933
|
+
** handler is invoked with CHANGESET_FOREIGN_KEY as the second argument
|
9934
|
+
** exactly once before the changeset is committed. If the conflict handler
|
9935
|
+
** returns CHANGESET_OMIT, the changes, including those that caused the
|
9936
|
+
** foreign key constraint violation, are committed. Or, if it returns
|
9937
|
+
** CHANGESET_ABORT, the changeset is rolled back.
|
9938
|
+
**
|
9939
|
+
** No current or conflicting row information is provided. The only function
|
9940
|
+
** it is possible to call on the supplied sqlite3_changeset_iter handle
|
9941
|
+
** is sqlite3changeset_fk_conflicts().
|
9942
|
+
**
|
9943
|
+
** <dt>SQLITE_CHANGESET_CONSTRAINT<dd>
|
9944
|
+
** If any other constraint violation occurs while applying a change (i.e.
|
9945
|
+
** a UNIQUE, CHECK or NOT NULL constraint), the conflict handler is
|
9946
|
+
** invoked with CHANGESET_CONSTRAINT as the second argument.
|
9947
|
+
**
|
9948
|
+
** There is no conflicting row in this case. The results of invoking the
|
9949
|
+
** sqlite3changeset_conflict() API are undefined.
|
9950
|
+
**
|
9951
|
+
** </dl>
|
9952
|
+
*/
|
9953
|
+
#define SQLITE_CHANGESET_DATA 1
|
9954
|
+
#define SQLITE_CHANGESET_NOTFOUND 2
|
9955
|
+
#define SQLITE_CHANGESET_CONFLICT 3
|
9956
|
+
#define SQLITE_CHANGESET_CONSTRAINT 4
|
9957
|
+
#define SQLITE_CHANGESET_FOREIGN_KEY 5
|
9958
|
+
|
9959
|
+
/*
|
9960
|
+
** CAPI3REF: Constants Returned By The Conflict Handler
|
9961
|
+
**
|
9962
|
+
** A conflict handler callback must return one of the following three values.
|
9963
|
+
**
|
9964
|
+
** <dl>
|
9965
|
+
** <dt>SQLITE_CHANGESET_OMIT<dd>
|
9966
|
+
** If a conflict handler returns this value no special action is taken. The
|
9967
|
+
** change that caused the conflict is not applied. The session module
|
9968
|
+
** continues to the next change in the changeset.
|
9969
|
+
**
|
9970
|
+
** <dt>SQLITE_CHANGESET_REPLACE<dd>
|
9971
|
+
** This value may only be returned if the second argument to the conflict
|
9972
|
+
** handler was SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If this
|
9973
|
+
** is not the case, any changes applied so far are rolled back and the
|
9974
|
+
** call to sqlite3changeset_apply() returns SQLITE_MISUSE.
|
9975
|
+
**
|
9976
|
+
** If CHANGESET_REPLACE is returned by an SQLITE_CHANGESET_DATA conflict
|
9977
|
+
** handler, then the conflicting row is either updated or deleted, depending
|
9978
|
+
** on the type of change.
|
9979
|
+
**
|
9980
|
+
** If CHANGESET_REPLACE is returned by an SQLITE_CHANGESET_CONFLICT conflict
|
9981
|
+
** handler, then the conflicting row is removed from the database and a
|
9982
|
+
** second attempt to apply the change is made. If this second attempt fails,
|
9983
|
+
** the original row is restored to the database before continuing.
|
9984
|
+
**
|
9985
|
+
** <dt>SQLITE_CHANGESET_ABORT<dd>
|
9986
|
+
** If this value is returned, any changes applied so far are rolled back
|
9987
|
+
** and the call to sqlite3changeset_apply() returns SQLITE_ABORT.
|
9988
|
+
** </dl>
|
9989
|
+
*/
|
9990
|
+
#define SQLITE_CHANGESET_OMIT 0
|
9991
|
+
#define SQLITE_CHANGESET_REPLACE 1
|
9992
|
+
#define SQLITE_CHANGESET_ABORT 2
|
9993
|
+
|
9994
|
+
/*
|
9995
|
+
** CAPI3REF: Streaming Versions of API functions.
|
9996
|
+
**
|
9997
|
+
** The six streaming API xxx_strm() functions serve similar purposes to the
|
9998
|
+
** corresponding non-streaming API functions:
|
9999
|
+
**
|
10000
|
+
** <table border=1 style="margin-left:8ex;margin-right:8ex">
|
10001
|
+
** <tr><th>Streaming function<th>Non-streaming equivalent</th>
|
10002
|
+
** <tr><td>sqlite3changeset_apply_strm<td>[sqlite3changeset_apply]
|
10003
|
+
** <tr><td>sqlite3changeset_concat_strm<td>[sqlite3changeset_concat]
|
10004
|
+
** <tr><td>sqlite3changeset_invert_strm<td>[sqlite3changeset_invert]
|
10005
|
+
** <tr><td>sqlite3changeset_start_strm<td>[sqlite3changeset_start]
|
10006
|
+
** <tr><td>sqlite3session_changeset_strm<td>[sqlite3session_changeset]
|
10007
|
+
** <tr><td>sqlite3session_patchset_strm<td>[sqlite3session_patchset]
|
10008
|
+
** </table>
|
10009
|
+
**
|
10010
|
+
** Non-streaming functions that accept changesets (or patchsets) as input
|
10011
|
+
** require that the entire changeset be stored in a single buffer in memory.
|
10012
|
+
** Similarly, those that return a changeset or patchset do so by returning
|
10013
|
+
** a pointer to a single large buffer allocated using sqlite3_malloc().
|
10014
|
+
** Normally this is convenient. However, if an application running in a
|
10015
|
+
** low-memory environment is required to handle very large changesets, the
|
10016
|
+
** large contiguous memory allocations required can become onerous.
|
10017
|
+
**
|
10018
|
+
** In order to avoid this problem, instead of a single large buffer, input
|
10019
|
+
** is passed to a streaming API functions by way of a callback function that
|
10020
|
+
** the sessions module invokes to incrementally request input data as it is
|
10021
|
+
** required. In all cases, a pair of API function parameters such as
|
10022
|
+
**
|
10023
|
+
** <pre>
|
10024
|
+
** int nChangeset,
|
10025
|
+
** void *pChangeset,
|
10026
|
+
** </pre>
|
10027
|
+
**
|
10028
|
+
** Is replaced by:
|
10029
|
+
**
|
10030
|
+
** <pre>
|
10031
|
+
** int (*xInput)(void *pIn, void *pData, int *pnData),
|
10032
|
+
** void *pIn,
|
10033
|
+
** </pre>
|
10034
|
+
**
|
10035
|
+
** Each time the xInput callback is invoked by the sessions module, the first
|
10036
|
+
** argument passed is a copy of the supplied pIn context pointer. The second
|
10037
|
+
** argument, pData, points to a buffer (*pnData) bytes in size. Assuming no
|
10038
|
+
** error occurs the xInput method should copy up to (*pnData) bytes of data
|
10039
|
+
** into the buffer and set (*pnData) to the actual number of bytes copied
|
10040
|
+
** before returning SQLITE_OK. If the input is completely exhausted, (*pnData)
|
10041
|
+
** should be set to zero to indicate this. Or, if an error occurs, an SQLite
|
10042
|
+
** error code should be returned. In all cases, if an xInput callback returns
|
10043
|
+
** an error, all processing is abandoned and the streaming API function
|
10044
|
+
** returns a copy of the error code to the caller.
|
10045
|
+
**
|
10046
|
+
** In the case of sqlite3changeset_start_strm(), the xInput callback may be
|
10047
|
+
** invoked by the sessions module at any point during the lifetime of the
|
10048
|
+
** iterator. If such an xInput callback returns an error, the iterator enters
|
10049
|
+
** an error state, whereby all subsequent calls to iterator functions
|
10050
|
+
** immediately fail with the same error code as returned by xInput.
|
10051
|
+
**
|
10052
|
+
** Similarly, streaming API functions that return changesets (or patchsets)
|
10053
|
+
** return them in chunks by way of a callback function instead of via a
|
10054
|
+
** pointer to a single large buffer. In this case, a pair of parameters such
|
10055
|
+
** as:
|
10056
|
+
**
|
10057
|
+
** <pre>
|
10058
|
+
** int *pnChangeset,
|
10059
|
+
** void **ppChangeset,
|
10060
|
+
** </pre>
|
10061
|
+
**
|
10062
|
+
** Is replaced by:
|
10063
|
+
**
|
10064
|
+
** <pre>
|
10065
|
+
** int (*xOutput)(void *pOut, const void *pData, int nData),
|
10066
|
+
** void *pOut
|
10067
|
+
** </pre>
|
10068
|
+
**
|
10069
|
+
** The xOutput callback is invoked zero or more times to return data to
|
10070
|
+
** the application. The first parameter passed to each call is a copy of the
|
10071
|
+
** pOut pointer supplied by the application. The second parameter, pData,
|
10072
|
+
** points to a buffer nData bytes in size containing the chunk of output
|
10073
|
+
** data being returned. If the xOutput callback successfully processes the
|
10074
|
+
** supplied data, it should return SQLITE_OK to indicate success. Otherwise,
|
10075
|
+
** it should return some other SQLite error code. In this case processing
|
10076
|
+
** is immediately abandoned and the streaming API function returns a copy
|
10077
|
+
** of the xOutput error code to the application.
|
10078
|
+
**
|
10079
|
+
** The sessions module never invokes an xOutput callback with the third
|
10080
|
+
** parameter set to a value less than or equal to zero. Other than this,
|
10081
|
+
** no guarantees are made as to the size of the chunks of data returned.
|
10082
|
+
*/
|
10083
|
+
SQLITE_API int sqlite3changeset_apply_strm(
|
10084
|
+
sqlite3 *db, /* Apply change to "main" db of this handle */
|
10085
|
+
int (*xInput)(void *pIn, void *pData, int *pnData), /* Input function */
|
10086
|
+
void *pIn, /* First arg for xInput */
|
10087
|
+
int(*xFilter)(
|
10088
|
+
void *pCtx, /* Copy of sixth arg to _apply() */
|
10089
|
+
const char *zTab /* Table name */
|
10090
|
+
),
|
10091
|
+
int(*xConflict)(
|
10092
|
+
void *pCtx, /* Copy of sixth arg to _apply() */
|
10093
|
+
int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
|
10094
|
+
sqlite3_changeset_iter *p /* Handle describing change and conflict */
|
10095
|
+
),
|
10096
|
+
void *pCtx /* First argument passed to xConflict */
|
10097
|
+
);
|
10098
|
+
SQLITE_API int sqlite3changeset_concat_strm(
|
10099
|
+
int (*xInputA)(void *pIn, void *pData, int *pnData),
|
10100
|
+
void *pInA,
|
10101
|
+
int (*xInputB)(void *pIn, void *pData, int *pnData),
|
10102
|
+
void *pInB,
|
10103
|
+
int (*xOutput)(void *pOut, const void *pData, int nData),
|
10104
|
+
void *pOut
|
10105
|
+
);
|
10106
|
+
SQLITE_API int sqlite3changeset_invert_strm(
|
10107
|
+
int (*xInput)(void *pIn, void *pData, int *pnData),
|
10108
|
+
void *pIn,
|
10109
|
+
int (*xOutput)(void *pOut, const void *pData, int nData),
|
10110
|
+
void *pOut
|
10111
|
+
);
|
10112
|
+
SQLITE_API int sqlite3changeset_start_strm(
|
10113
|
+
sqlite3_changeset_iter **pp,
|
10114
|
+
int (*xInput)(void *pIn, void *pData, int *pnData),
|
10115
|
+
void *pIn
|
10116
|
+
);
|
10117
|
+
SQLITE_API int sqlite3session_changeset_strm(
|
10118
|
+
sqlite3_session *pSession,
|
10119
|
+
int (*xOutput)(void *pOut, const void *pData, int nData),
|
10120
|
+
void *pOut
|
10121
|
+
);
|
10122
|
+
SQLITE_API int sqlite3session_patchset_strm(
|
10123
|
+
sqlite3_session *pSession,
|
10124
|
+
int (*xOutput)(void *pOut, const void *pData, int nData),
|
10125
|
+
void *pOut
|
10126
|
+
);
|
10127
|
+
SQLITE_API int sqlite3changegroup_add_strm(sqlite3_changegroup*,
|
10128
|
+
int (*xInput)(void *pIn, void *pData, int *pnData),
|
10129
|
+
void *pIn
|
10130
|
+
);
|
10131
|
+
SQLITE_API int sqlite3changegroup_output_strm(sqlite3_changegroup*,
|
10132
|
+
int (*xOutput)(void *pOut, const void *pData, int nData),
|
10133
|
+
void *pOut
|
10134
|
+
);
|
10135
|
+
|
10136
|
+
|
10137
|
+
/*
|
10138
|
+
** Make sure we can call this stuff from C++.
|
10139
|
+
*/
|
10140
|
+
#ifdef __cplusplus
|
10141
|
+
}
|
10142
|
+
#endif
|
10143
|
+
|
10144
|
+
#endif /* !defined(__SQLITESESSION_H_) && defined(SQLITE_ENABLE_SESSION) */
|
10145
|
+
|
10146
|
+
/******** End of sqlite3session.h *********/
|
10147
|
+
/******** Begin file fts5.h *********/
|
7924
10148
|
/*
|
7925
10149
|
** 2014 May 31
|
7926
10150
|
**
|
@@ -8006,6 +10230,9 @@ struct Fts5PhraseIter {
|
|
8006
10230
|
** an OOM condition or IO error), an appropriate SQLite error code is
|
8007
10231
|
** returned.
|
8008
10232
|
**
|
10233
|
+
** This function may be quite inefficient if used with an FTS5 table
|
10234
|
+
** created with the "columnsize=0" option.
|
10235
|
+
**
|
8009
10236
|
** xColumnText:
|
8010
10237
|
** This function attempts to retrieve the text of column iCol of the
|
8011
10238
|
** current document. If successful, (*pz) is set to point to a buffer
|
@@ -8026,15 +10253,29 @@ struct Fts5PhraseIter {
|
|
8026
10253
|
** the query within the current row. Return SQLITE_OK if successful, or
|
8027
10254
|
** an error code (i.e. SQLITE_NOMEM) if an error occurs.
|
8028
10255
|
**
|
10256
|
+
** This API can be quite slow if used with an FTS5 table created with the
|
10257
|
+
** "detail=none" or "detail=column" option. If the FTS5 table is created
|
10258
|
+
** with either "detail=none" or "detail=column" and "content=" option
|
10259
|
+
** (i.e. if it is a contentless table), then this API always returns 0.
|
10260
|
+
**
|
8029
10261
|
** xInst:
|
8030
10262
|
** Query for the details of phrase match iIdx within the current row.
|
8031
10263
|
** Phrase matches are numbered starting from zero, so the iIdx argument
|
8032
10264
|
** should be greater than or equal to zero and smaller than the value
|
8033
10265
|
** output by xInstCount().
|
8034
10266
|
**
|
10267
|
+
** Usually, output parameter *piPhrase is set to the phrase number, *piCol
|
10268
|
+
** to the column in which it occurs and *piOff the token offset of the
|
10269
|
+
** first token of the phrase. The exception is if the table was created
|
10270
|
+
** with the offsets=0 option specified. In this case *piOff is always
|
10271
|
+
** set to -1.
|
10272
|
+
**
|
8035
10273
|
** Returns SQLITE_OK if successful, or an error code (i.e. SQLITE_NOMEM)
|
8036
10274
|
** if an error occurs.
|
8037
10275
|
**
|
10276
|
+
** This API can be quite slow if used with an FTS5 table created with the
|
10277
|
+
** "detail=none" or "detail=column" option.
|
10278
|
+
**
|
8038
10279
|
** xRowid:
|
8039
10280
|
** Returns the rowid of the current row.
|
8040
10281
|
**
|
@@ -8048,11 +10289,13 @@ struct Fts5PhraseIter {
|
|
8048
10289
|
** ... FROM ftstable WHERE ftstable MATCH $p ORDER BY rowid
|
8049
10290
|
**
|
8050
10291
|
** with $p set to a phrase equivalent to the phrase iPhrase of the
|
8051
|
-
** current query is executed.
|
8052
|
-
**
|
8053
|
-
**
|
8054
|
-
**
|
8055
|
-
**
|
10292
|
+
** current query is executed. Any column filter that applies to
|
10293
|
+
** phrase iPhrase of the current query is included in $p. For each
|
10294
|
+
** row visited, the callback function passed as the fourth argument
|
10295
|
+
** is invoked. The context and API objects passed to the callback
|
10296
|
+
** function may be used to access the properties of each matched row.
|
10297
|
+
** Invoking Api.xUserData() returns a copy of the pointer passed as
|
10298
|
+
** the third argument to pUserData.
|
8056
10299
|
**
|
8057
10300
|
** If the callback function returns any value other than SQLITE_OK, the
|
8058
10301
|
** query is abandoned and the xQueryPhrase function returns immediately.
|
@@ -8118,7 +10361,7 @@ struct Fts5PhraseIter {
|
|
8118
10361
|
** Fts5PhraseIter iter;
|
8119
10362
|
** int iCol, iOff;
|
8120
10363
|
** for(pApi->xPhraseFirst(pFts, iPhrase, &iter, &iCol, &iOff);
|
8121
|
-
**
|
10364
|
+
** iCol>=0;
|
8122
10365
|
** pApi->xPhraseNext(pFts, &iter, &iCol, &iOff)
|
8123
10366
|
** ){
|
8124
10367
|
** // An instance of phrase iPhrase at offset iOff of column iCol
|
@@ -8126,13 +10369,51 @@ struct Fts5PhraseIter {
|
|
8126
10369
|
**
|
8127
10370
|
** The Fts5PhraseIter structure is defined above. Applications should not
|
8128
10371
|
** modify this structure directly - it should only be used as shown above
|
8129
|
-
** with the xPhraseFirst() and xPhraseNext() API methods
|
10372
|
+
** with the xPhraseFirst() and xPhraseNext() API methods (and by
|
10373
|
+
** xPhraseFirstColumn() and xPhraseNextColumn() as illustrated below).
|
10374
|
+
**
|
10375
|
+
** This API can be quite slow if used with an FTS5 table created with the
|
10376
|
+
** "detail=none" or "detail=column" option. If the FTS5 table is created
|
10377
|
+
** with either "detail=none" or "detail=column" and "content=" option
|
10378
|
+
** (i.e. if it is a contentless table), then this API always iterates
|
10379
|
+
** through an empty set (all calls to xPhraseFirst() set iCol to -1).
|
8130
10380
|
**
|
8131
10381
|
** xPhraseNext()
|
8132
10382
|
** See xPhraseFirst above.
|
10383
|
+
**
|
10384
|
+
** xPhraseFirstColumn()
|
10385
|
+
** This function and xPhraseNextColumn() are similar to the xPhraseFirst()
|
10386
|
+
** and xPhraseNext() APIs described above. The difference is that instead
|
10387
|
+
** of iterating through all instances of a phrase in the current row, these
|
10388
|
+
** APIs are used to iterate through the set of columns in the current row
|
10389
|
+
** that contain one or more instances of a specified phrase. For example:
|
10390
|
+
**
|
10391
|
+
** Fts5PhraseIter iter;
|
10392
|
+
** int iCol;
|
10393
|
+
** for(pApi->xPhraseFirstColumn(pFts, iPhrase, &iter, &iCol);
|
10394
|
+
** iCol>=0;
|
10395
|
+
** pApi->xPhraseNextColumn(pFts, &iter, &iCol)
|
10396
|
+
** ){
|
10397
|
+
** // Column iCol contains at least one instance of phrase iPhrase
|
10398
|
+
** }
|
10399
|
+
**
|
10400
|
+
** This API can be quite slow if used with an FTS5 table created with the
|
10401
|
+
** "detail=none" option. If the FTS5 table is created with either
|
10402
|
+
** "detail=none" "content=" option (i.e. if it is a contentless table),
|
10403
|
+
** then this API always iterates through an empty set (all calls to
|
10404
|
+
** xPhraseFirstColumn() set iCol to -1).
|
10405
|
+
**
|
10406
|
+
** The information accessed using this API and its companion
|
10407
|
+
** xPhraseFirstColumn() may also be obtained using xPhraseFirst/xPhraseNext
|
10408
|
+
** (or xInst/xInstCount). The chief advantage of this API is that it is
|
10409
|
+
** significantly more efficient than those alternatives when used with
|
10410
|
+
** "detail=column" tables.
|
10411
|
+
**
|
10412
|
+
** xPhraseNextColumn()
|
10413
|
+
** See xPhraseFirstColumn above.
|
8133
10414
|
*/
|
8134
10415
|
struct Fts5ExtensionApi {
|
8135
|
-
int iVersion; /* Currently always set to
|
10416
|
+
int iVersion; /* Currently always set to 3 */
|
8136
10417
|
|
8137
10418
|
void *(*xUserData)(Fts5Context*);
|
8138
10419
|
|
@@ -8162,8 +10443,11 @@ struct Fts5ExtensionApi {
|
|
8162
10443
|
int (*xSetAuxdata)(Fts5Context*, void *pAux, void(*xDelete)(void*));
|
8163
10444
|
void *(*xGetAuxdata)(Fts5Context*, int bClear);
|
8164
10445
|
|
8165
|
-
|
10446
|
+
int (*xPhraseFirst)(Fts5Context*, int iPhrase, Fts5PhraseIter*, int*, int*);
|
8166
10447
|
void (*xPhraseNext)(Fts5Context*, Fts5PhraseIter*, int *piCol, int *piOff);
|
10448
|
+
|
10449
|
+
int (*xPhraseFirstColumn)(Fts5Context*, int iPhrase, Fts5PhraseIter*, int*);
|
10450
|
+
void (*xPhraseNextColumn)(Fts5Context*, Fts5PhraseIter*, int *piCol);
|
8167
10451
|
};
|
8168
10452
|
|
8169
10453
|
/*
|
@@ -8180,7 +10464,7 @@ struct Fts5ExtensionApi {
|
|
8180
10464
|
** behaviour. The structure methods are expected to function as follows:
|
8181
10465
|
**
|
8182
10466
|
** xCreate:
|
8183
|
-
** This function is used to allocate and
|
10467
|
+
** This function is used to allocate and initialize a tokenizer instance.
|
8184
10468
|
** A tokenizer instance is required to actually tokenize text.
|
8185
10469
|
**
|
8186
10470
|
** The first argument passed to this function is a copy of the (void*)
|
@@ -8440,4 +10724,4 @@ struct fts5_api {
|
|
8440
10724
|
|
8441
10725
|
#endif /* _FTS5_H */
|
8442
10726
|
|
8443
|
-
|
10727
|
+
/******** End of fts5.h *********/
|