amalgalite 1.5.0 → 1.6.0

Sign up to get free protection for your applications and to get access to all the features.
@@ -1,5 +1,5 @@
1
1
  /*
2
- ** 2001 September 15
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 _SQLITE3_H_
34
- #define _SQLITE3_H_
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, SQLite source code has been stored in the
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 an SHA1
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.9.2"
115
- #define SQLITE_VERSION_NUMBER 3009002
116
- #define SQLITE_SOURCE_ID "2015-11-02 18:31:45 bda77dda9697c463c3d0704014d51627fceee328"
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, sqlite3_sourceid
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( strcmp(sqlite3_sourceid(),SQLITE_SOURCE_ID)==0 );
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 *SQLITE_STDCALL sqlite3_libversion(void);
150
- SQLITE_API const char *SQLITE_STDCALL sqlite3_sourceid(void);
151
- SQLITE_API int SQLITE_STDCALL sqlite3_libversion_number(void);
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 SQLITE_STDCALL sqlite3_compileoption_used(const char *zOptName);
177
- SQLITE_API const char *SQLITE_STDCALL sqlite3_compileoption_get(int N);
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 SQLITE_STDCALL sqlite3_threadsafe(void);
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
- typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;
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 SQLITE_STDCALL sqlite3_close(sqlite3*);
314
- SQLITE_API int SQLITE_STDCALL sqlite3_close_v2(sqlite3*);
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
- ** of sqlite3_exec() after the error message string is no longer needed.
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 SQLITE_STDCALL sqlite3_exec(
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 /* SQL error or missing database */
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 /* Database is empty */
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 /* Auxiliary database format error */
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 and later) include
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 indicate that a file cannot be deleted when open. The
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 the [sqlite3_file_control()] documentation for
797
- ** additional information.
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 i the new retry count and the second
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 figure versions. The iVersion
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 SQLITE_STDCALL sqlite3_initialize(void);
1357
- SQLITE_API int SQLITE_STDCALL sqlite3_shutdown(void);
1358
- SQLITE_API int SQLITE_STDCALL sqlite3_os_init(void);
1359
- SQLITE_API int SQLITE_STDCALL sqlite3_os_end(void);
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 SQLITE_CDECL sqlite3_config(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 SQLITE_CDECL sqlite3_db_config(sqlite3*, int op, ...);
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> ^The SQLITE_CONFIG_SCRATCH option specifies a static memory buffer
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 static memory buffer
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 should not be used if an application-define page
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
- ** memory, the size of each page buffer (sz), and the number of pages (N).
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 the [SQLITE_CONFIG_PCACHE_HDRSZ] option
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 first
1617
- ** argument should pointer to an 8-byte aligned block of memory that
1618
- ** is at least sz*N bytes of memory, otherwise subsequent behavior is
1619
- ** undefined.
1620
- ** ^SQLite will use the memory provided by the first argument to satisfy its
1621
- ** memory needs for the first N pages that it adds to cache. ^If additional
1622
- ** page cache memory is needed beyond what is provided by this option, then
1623
- ** SQLite goes to [sqlite3_malloc()] for the additional storage space.</dd>
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 [SQLITE_CONFIG_SCRATCH] and
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 /* void*, int sz, int N */
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 SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */
1888
- #define SQLITE_DBCONFIG_ENABLE_FKEY 1002 /* int int* */
1889
- #define SQLITE_DBCONFIG_ENABLE_TRIGGER 1003 /* int int* */
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 SQLITE_STDCALL sqlite3_extended_result_codes(sqlite3*, int onoff);
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 the
1915
- ** most recent successful [INSERT] into a rowid table or [virtual table]
1916
- ** on database connection D.
1917
- ** ^Inserts into [WITHOUT ROWID] tables are not recorded.
1918
- ** ^If no successful [INSERT]s into rowid tables
1919
- ** have ever occurred on the database connection D,
1920
- ** then sqlite3_last_insert_rowid(D) returns zero.
1921
- **
1922
- ** ^(If an [INSERT] occurs within a trigger or within a [virtual table]
1923
- ** method, then this routine will return the [rowid] of the inserted
1924
- ** row as long as the trigger or virtual table method is running.
1925
- ** But once the trigger or virtual table method ends, the value returned
1926
- ** by this routine reverts to what it was before the trigger or virtual
1927
- ** table method began.)^
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 SQLITE_STDCALL sqlite3_last_insert_rowid(sqlite3*);
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 SQLITE_STDCALL sqlite3_changes(sqlite3*);
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 SQLITE_STDCALL sqlite3_total_changes(sqlite3*);
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 SQLITE_STDCALL sqlite3_interrupt(sqlite3*);
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 SQLITE_STDCALL sqlite3_complete(const char *sql);
2105
- SQLITE_API int SQLITE_STDCALL sqlite3_complete16(const void *sql);
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 SQLITE_STDCALL sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
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 SQLITE_STDCALL sqlite3_busy_timeout(sqlite3*, int ms);
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 SQLITE_STDCALL sqlite3_get_table(
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 SQLITE_STDCALL sqlite3_free_table(char **result);
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 *SQLITE_CDECL sqlite3_mprintf(const char*,...);
2379
- SQLITE_API char *SQLITE_STDCALL sqlite3_vmprintf(const char*, va_list);
2380
- SQLITE_API char *SQLITE_CDECL sqlite3_snprintf(int,char*,const char*, ...);
2381
- SQLITE_API char *SQLITE_STDCALL sqlite3_vsnprintf(int,char*,const char*, va_list);
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 *SQLITE_STDCALL sqlite3_malloc(int);
2472
- SQLITE_API void *SQLITE_STDCALL sqlite3_malloc64(sqlite3_uint64);
2473
- SQLITE_API void *SQLITE_STDCALL sqlite3_realloc(void*, int);
2474
- SQLITE_API void *SQLITE_STDCALL sqlite3_realloc64(void*, sqlite3_uint64);
2475
- SQLITE_API void SQLITE_STDCALL sqlite3_free(void*);
2476
- SQLITE_API sqlite3_uint64 SQLITE_STDCALL sqlite3_msize(void*);
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 SQLITE_STDCALL sqlite3_memory_used(void);
2502
- SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_memory_highwater(int resetFlag);
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 SQLITE_STDCALL sqlite3_randomness(int N, void *P);
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()] and [sqlite3_prepare16_v2()]. ^At various
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 that contain additional
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 SQLITE_STDCALL sqlite3_set_authorizer(
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 *SQLITE_STDCALL sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
2714
- SQLITE_API SQLITE_EXPERIMENTAL void *SQLITE_STDCALL sqlite3_profile(sqlite3*,
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 SQLITE_STDCALL sqlite3_progress_handler(sqlite3*, int, int(*)(void*), 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 fourth argument to sqlite3_open_v2(), or if it has
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
- ** As of SQLite version 3.7.7, URI filename interpretation is turned off
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 SQLITE_STDCALL sqlite3_open(
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 SQLITE_STDCALL sqlite3_open16(
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 SQLITE_STDCALL sqlite3_open_v2(
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 *SQLITE_STDCALL sqlite3_uri_parameter(const char *zFilename, const char *zParam);
3033
- SQLITE_API int SQLITE_STDCALL sqlite3_uri_boolean(const char *zFile, const char *zParam, int bDefault);
3034
- SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_uri_int64(const char*, const char*, 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 SQLITE_STDCALL sqlite3_errcode(sqlite3 *db);
3079
- SQLITE_API int SQLITE_STDCALL sqlite3_extended_errcode(sqlite3 *db);
3080
- SQLITE_API const char *SQLITE_STDCALL sqlite3_errmsg(sqlite3*);
3081
- SQLITE_API const void *SQLITE_STDCALL sqlite3_errmsg16(sqlite3*);
3082
- SQLITE_API const char *SQLITE_STDCALL sqlite3_errstr(int);
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 SQLITE_STDCALL sqlite3_limit(sqlite3*, int id, int newVal);
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. This limit is not currently
3182
- ** enforced, though that might be added in some future release of
3183
- ** SQLite.</dd>)^
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 query, it must first be compiled into a byte-code
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() and sqlite3_prepare_v2()
3236
- ** interfaces use UTF-8, and sqlite3_prepare16() and sqlite3_prepare16_v2()
3237
- ** use UTF-16.
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() and sqlite3_prepare16_v2() interfaces are
3265
- ** recommended for all new programs. The two older interfaces are retained
3266
- ** for backwards compatibility, but their use is discouraged.
3267
- ** ^In the "v2" interfaces, the prepared statement
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 SQLITE_STDCALL sqlite3_prepare(
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 SQLITE_STDCALL sqlite3_prepare_v2(
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 SQLITE_STDCALL sqlite3_prepare16(
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 SQLITE_STDCALL sqlite3_prepare16_v2(
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
- ** ^This interface can be used to retrieve a saved copy of the original
3336
- ** SQL text used to create a [prepared statement] if that statement was
3337
- ** compiled using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()].
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 *SQLITE_STDCALL sqlite3_sql(sqlite3_stmt *pStmt);
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 SQLITE_STDCALL sqlite3_stmt_readonly(sqlite3_stmt *pStmt);
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 SQLITE_STDCALL sqlite3_stmt_busy(sqlite3_stmt*);
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 with
3429
- ** [sqlite3_result_value()] and [sqlite3_bind_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 Mem sqlite3_value;
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 SQLITE_STDCALL sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
3557
- SQLITE_API int SQLITE_STDCALL sqlite3_bind_blob64(sqlite3_stmt*, int, const void*, sqlite3_uint64,
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 SQLITE_STDCALL sqlite3_bind_double(sqlite3_stmt*, int, double);
3560
- SQLITE_API int SQLITE_STDCALL sqlite3_bind_int(sqlite3_stmt*, int, int);
3561
- SQLITE_API int SQLITE_STDCALL sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
3562
- SQLITE_API int SQLITE_STDCALL sqlite3_bind_null(sqlite3_stmt*, int);
3563
- SQLITE_API int SQLITE_STDCALL sqlite3_bind_text(sqlite3_stmt*,int,const char*,int,void(*)(void*));
3564
- SQLITE_API int SQLITE_STDCALL sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
3565
- SQLITE_API int SQLITE_STDCALL sqlite3_bind_text64(sqlite3_stmt*, int, const char*, sqlite3_uint64,
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 SQLITE_STDCALL sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
3568
- SQLITE_API int SQLITE_STDCALL sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
3569
- SQLITE_API int SQLITE_STDCALL sqlite3_bind_zeroblob64(sqlite3_stmt*, int, sqlite3_uint64);
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 SQLITE_STDCALL sqlite3_bind_parameter_count(sqlite3_stmt*);
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()] or
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 *SQLITE_STDCALL sqlite3_bind_parameter_name(sqlite3_stmt*, int);
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 SQLITE_STDCALL sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
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 SQLITE_STDCALL sqlite3_clear_bindings(sqlite3_stmt*);
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]. ^This routine returns 0 if pStmt is an SQL
3653
- ** statement that does not return data (for example an [UPDATE]).
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 SQLITE_STDCALL sqlite3_column_count(sqlite3_stmt *pStmt);
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 *SQLITE_STDCALL sqlite3_column_name(sqlite3_stmt*, int N);
3687
- SQLITE_API const void *SQLITE_STDCALL sqlite3_column_name16(sqlite3_stmt*, int N);
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 *SQLITE_STDCALL sqlite3_column_database_name(sqlite3_stmt*,int);
3736
- SQLITE_API const void *SQLITE_STDCALL sqlite3_column_database_name16(sqlite3_stmt*,int);
3737
- SQLITE_API const char *SQLITE_STDCALL sqlite3_column_table_name(sqlite3_stmt*,int);
3738
- SQLITE_API const void *SQLITE_STDCALL sqlite3_column_table_name16(sqlite3_stmt*,int);
3739
- SQLITE_API const char *SQLITE_STDCALL sqlite3_column_origin_name(sqlite3_stmt*,int);
3740
- SQLITE_API const void *SQLITE_STDCALL sqlite3_column_origin_name16(sqlite3_stmt*,int);
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 *SQLITE_STDCALL sqlite3_column_decltype(sqlite3_stmt*,int);
3773
- SQLITE_API const void *SQLITE_STDCALL sqlite3_column_decltype16(sqlite3_stmt*,int);
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 either
3780
- ** [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or one of the legacy
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 "v2" interface
3786
- ** [sqlite3_prepare_v2()] and [sqlite3_prepare16_v2()] or the older legacy
3787
- ** interface [sqlite3_prepare()] and [sqlite3_prepare16()]. The use of the
3788
- ** new "v2" interface is recommended for new applications but the legacy
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, sqlite3_step() began
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 either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead
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 "v2" interface is recommended.
4265
+ ** by sqlite3_step(). The use of the "vX" interfaces is recommended.
3852
4266
  */
3853
- SQLITE_API int SQLITE_STDCALL sqlite3_step(sqlite3_stmt*);
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 SQLITE_STDCALL sqlite3_data_count(sqlite3_stmt *pStmt);
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>&rarr;<td>BLOB result
4330
+ ** <tr><td><b>sqlite3_column_double</b><td>&rarr;<td>REAL result
4331
+ ** <tr><td><b>sqlite3_column_int</b><td>&rarr;<td>32-bit INTEGER result
4332
+ ** <tr><td><b>sqlite3_column_int64</b><td>&rarr;<td>64-bit INTEGER result
4333
+ ** <tr><td><b>sqlite3_column_text</b><td>&rarr;<td>UTF-8 TEXT result
4334
+ ** <tr><td><b>sqlite3_column_text16</b><td>&rarr;<td>UTF-16 TEXT result
4335
+ ** <tr><td><b>sqlite3_column_value</b><td>&rarr;<td>The result as an
4336
+ ** [sqlite3_value|unprotected sqlite3_value] object.
4337
+ ** <tr><td>&nbsp;<td>&nbsp;<td>&nbsp;
4338
+ ** <tr><td><b>sqlite3_column_bytes</b><td>&rarr;<td>Size of a BLOB
4339
+ ** or a UTF-8 TEXT result in bytes
4340
+ ** <tr><td><b>sqlite3_column_bytes16&nbsp;&nbsp;</b>
4341
+ ** <td>&rarr;&nbsp;&nbsp;<td>Size of UTF-16
4342
+ ** TEXT in bytes
4343
+ ** <tr><td><b>sqlite3_column_type</b><td>&rarr;<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]. The value
3938
- ** returned by sqlite3_column_type() is only meaningful if no type
3939
- ** conversions have occurred as described below. After a type conversion,
3940
- ** the value returned by sqlite3_column_type() is undefined. Future
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
- ** These routines attempt to convert the value where appropriate. ^For
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 <em>not</em> pass the pointers returned
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 *SQLITE_STDCALL sqlite3_column_blob(sqlite3_stmt*, int iCol);
4065
- SQLITE_API int SQLITE_STDCALL sqlite3_column_bytes(sqlite3_stmt*, int iCol);
4066
- SQLITE_API int SQLITE_STDCALL sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
4067
- SQLITE_API double SQLITE_STDCALL sqlite3_column_double(sqlite3_stmt*, int iCol);
4068
- SQLITE_API int SQLITE_STDCALL sqlite3_column_int(sqlite3_stmt*, int iCol);
4069
- SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_column_int64(sqlite3_stmt*, int iCol);
4070
- SQLITE_API const unsigned char *SQLITE_STDCALL sqlite3_column_text(sqlite3_stmt*, int iCol);
4071
- SQLITE_API const void *SQLITE_STDCALL sqlite3_column_text16(sqlite3_stmt*, int iCol);
4072
- SQLITE_API int SQLITE_STDCALL sqlite3_column_type(sqlite3_stmt*, int iCol);
4073
- SQLITE_API sqlite3_value *SQLITE_STDCALL sqlite3_column_value(sqlite3_stmt*, int iCol);
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 SQLITE_STDCALL sqlite3_finalize(sqlite3_stmt *pStmt);
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 SQLITE_STDCALL sqlite3_reset(sqlite3_stmt *pStmt);
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 SQLITE_STDCALL sqlite3_create_function(
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 SQLITE_STDCALL sqlite3_create_function16(
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 SQLITE_STDCALL sqlite3_create_function_v2(
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 SQLITE_STDCALL sqlite3_aggregate_count(sqlite3_context*);
4295
- SQLITE_API SQLITE_DEPRECATED int SQLITE_STDCALL sqlite3_expired(sqlite3_stmt*);
4296
- SQLITE_API SQLITE_DEPRECATED int SQLITE_STDCALL sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
4297
- SQLITE_API SQLITE_DEPRECATED int SQLITE_STDCALL sqlite3_global_recover(void);
4298
- SQLITE_API SQLITE_DEPRECATED void SQLITE_STDCALL sqlite3_thread_cleanup(void);
4299
- SQLITE_API SQLITE_DEPRECATED int SQLITE_STDCALL sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,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
- ** The C-language implementation of SQL functions and aggregates uses
4308
- ** this set of interface routines to access the parameter values on
4309
- ** the function or aggregate.
4310
- **
4311
- ** The xFunc (for scalar functions) or xStep (for aggregates) parameters
4312
- ** to [sqlite3_create_function()] and [sqlite3_create_function16()]
4313
- ** define callbacks that implement the SQL functions and aggregates.
4314
- ** The 3rd parameter to these callbacks is an array of pointers to
4315
- ** [protected sqlite3_value] objects. There is one [sqlite3_value] object for
4316
- ** each parameter to the SQL function. These routines are used to
4317
- ** extract values from the [sqlite3_value] objects.
4760
+ ** <b>Summary:</b>
4761
+ ** <blockquote><table border=0 cellpadding=0 cellspacing=0>
4762
+ ** <tr><td><b>sqlite3_value_blob</b><td>&rarr;<td>BLOB value
4763
+ ** <tr><td><b>sqlite3_value_double</b><td>&rarr;<td>REAL value
4764
+ ** <tr><td><b>sqlite3_value_int</b><td>&rarr;<td>32-bit INTEGER value
4765
+ ** <tr><td><b>sqlite3_value_int64</b><td>&rarr;<td>64-bit INTEGER value
4766
+ ** <tr><td><b>sqlite3_value_pointer</b><td>&rarr;<td>Pointer value
4767
+ ** <tr><td><b>sqlite3_value_text</b><td>&rarr;<td>UTF-8 TEXT value
4768
+ ** <tr><td><b>sqlite3_value_text16</b><td>&rarr;<td>UTF-16 TEXT value in
4769
+ ** the native byteorder
4770
+ ** <tr><td><b>sqlite3_value_text16be</b><td>&rarr;<td>UTF-16be TEXT value
4771
+ ** <tr><td><b>sqlite3_value_text16le</b><td>&rarr;<td>UTF-16le TEXT value
4772
+ ** <tr><td>&nbsp;<td>&nbsp;<td>&nbsp;
4773
+ ** <tr><td><b>sqlite3_value_bytes</b><td>&rarr;<td>Size of a BLOB
4774
+ ** or a UTF-8 TEXT in bytes
4775
+ ** <tr><td><b>sqlite3_value_bytes16&nbsp;&nbsp;</b>
4776
+ ** <td>&rarr;&nbsp;&nbsp;<td>Size of UTF-16
4777
+ ** TEXT in bytes
4778
+ ** <tr><td><b>sqlite3_value_type</b><td>&rarr;<td>Default
4779
+ ** datatype of the value
4780
+ ** <tr><td><b>sqlite3_value_numeric_type&nbsp;&nbsp;</b>
4781
+ ** <td>&rarr;&nbsp;&nbsp;<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
- ** object results in undefined behavior.
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 *SQLITE_STDCALL sqlite3_value_blob(sqlite3_value*);
4350
- SQLITE_API int SQLITE_STDCALL sqlite3_value_bytes(sqlite3_value*);
4351
- SQLITE_API int SQLITE_STDCALL sqlite3_value_bytes16(sqlite3_value*);
4352
- SQLITE_API double SQLITE_STDCALL sqlite3_value_double(sqlite3_value*);
4353
- SQLITE_API int SQLITE_STDCALL sqlite3_value_int(sqlite3_value*);
4354
- SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_value_int64(sqlite3_value*);
4355
- SQLITE_API const unsigned char *SQLITE_STDCALL sqlite3_value_text(sqlite3_value*);
4356
- SQLITE_API const void *SQLITE_STDCALL sqlite3_value_text16(sqlite3_value*);
4357
- SQLITE_API const void *SQLITE_STDCALL sqlite3_value_text16le(sqlite3_value*);
4358
- SQLITE_API const void *SQLITE_STDCALL sqlite3_value_text16be(sqlite3_value*);
4359
- SQLITE_API int SQLITE_STDCALL sqlite3_value_type(sqlite3_value*);
4360
- SQLITE_API int SQLITE_STDCALL sqlite3_value_numeric_type(sqlite3_value*);
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 SQLITE_STDCALL sqlite3_value_subtype(sqlite3_value*);
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 SQLITE_EXPERIMENTAL sqlite3_value *SQLITE_STDCALL sqlite3_value_dup(const sqlite3_value*);
4393
- SQLITE_API SQLITE_EXPERIMENTAL void SQLITE_STDCALL sqlite3_value_free(sqlite3_value*);
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 *SQLITE_STDCALL sqlite3_aggregate_context(sqlite3_context*, int nBytes);
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 *SQLITE_STDCALL sqlite3_user_data(sqlite3_context*);
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 *SQLITE_STDCALL sqlite3_context_db_handle(sqlite3_context*);
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. ^If there is no metadata
4485
- ** associated with the function argument, this sqlite3_get_auxdata() interface
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, or
4498
- ** <li> when [sqlite3_reset()] or [sqlite3_finalize()] is called for the
4499
- ** SQL statement, or
4500
- ** <li> when sqlite3_set_auxdata() is invoked again on the same parameter, or
4501
- ** <li> during the original sqlite3_set_auxdata() call when a memory
4502
- ** allocation error occurs. </ul>)^
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 *SQLITE_STDCALL sqlite3_get_auxdata(sqlite3_context*, int N);
4519
- SQLITE_API void SQLITE_STDCALL sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(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 from
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 SQLITE_STDCALL sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
4656
- SQLITE_API void SQLITE_STDCALL sqlite3_result_blob64(sqlite3_context*,const 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 SQLITE_STDCALL sqlite3_result_double(sqlite3_context*, double);
4659
- SQLITE_API void SQLITE_STDCALL sqlite3_result_error(sqlite3_context*, const char*, int);
4660
- SQLITE_API void SQLITE_STDCALL sqlite3_result_error16(sqlite3_context*, const void*, int);
4661
- SQLITE_API void SQLITE_STDCALL sqlite3_result_error_toobig(sqlite3_context*);
4662
- SQLITE_API void SQLITE_STDCALL sqlite3_result_error_nomem(sqlite3_context*);
4663
- SQLITE_API void SQLITE_STDCALL sqlite3_result_error_code(sqlite3_context*, int);
4664
- SQLITE_API void SQLITE_STDCALL sqlite3_result_int(sqlite3_context*, int);
4665
- SQLITE_API void SQLITE_STDCALL sqlite3_result_int64(sqlite3_context*, sqlite3_int64);
4666
- SQLITE_API void SQLITE_STDCALL sqlite3_result_null(sqlite3_context*);
4667
- SQLITE_API void SQLITE_STDCALL sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
4668
- SQLITE_API void SQLITE_STDCALL sqlite3_result_text64(sqlite3_context*, const char*,sqlite3_uint64,
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 SQLITE_STDCALL sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
4671
- SQLITE_API void SQLITE_STDCALL sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
4672
- SQLITE_API void SQLITE_STDCALL sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
4673
- SQLITE_API void SQLITE_STDCALL sqlite3_result_value(sqlite3_context*, sqlite3_value*);
4674
- SQLITE_API void SQLITE_STDCALL sqlite3_result_zeroblob(sqlite3_context*, int n);
4675
- SQLITE_API int SQLITE_STDCALL sqlite3_result_zeroblob64(sqlite3_context*, sqlite3_uint64 n);
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 SQLITE_STDCALL sqlite3_result_subtype(sqlite3_context*,unsigned int);
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 SQLITE_STDCALL sqlite3_create_collation(
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 SQLITE_STDCALL sqlite3_create_collation_v2(
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 SQLITE_STDCALL sqlite3_create_collation16(
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 SQLITE_STDCALL sqlite3_collation_needed(
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 SQLITE_STDCALL sqlite3_collation_needed16(
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 SQLITE_STDCALL sqlite3_key(
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 SQLITE_STDCALL sqlite3_key_v2(
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 SQLITE_STDCALL sqlite3_rekey(
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 SQLITE_STDCALL sqlite3_rekey_v2(
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 SQLITE_STDCALL sqlite3_activate_see(
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 SQLITE_STDCALL sqlite3_activate_cerod(
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 SQLITE_STDCALL sqlite3_sleep(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 SQLITE_STDCALL sqlite3_get_autocommit(sqlite3*);
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 *SQLITE_STDCALL sqlite3_db_handle(sqlite3_stmt*);
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 *SQLITE_STDCALL sqlite3_db_filename(sqlite3 *db, const char *zDbName);
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 SQLITE_STDCALL sqlite3_db_readonly(sqlite3 *db, const char *zDbName);
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 *SQLITE_STDCALL sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt);
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 *SQLITE_STDCALL sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
5130
- SQLITE_API void *SQLITE_STDCALL sqlite3_rollback_hook(sqlite3*, void(*)(void *), 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 duplication rows are deleted because of an
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()] and [sqlite3_rollback_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 *SQLITE_STDCALL sqlite3_update_hook(
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. In prior versions of SQLite,
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 SQLITE_STDCALL sqlite3_enable_shared_cache(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 SQLITE_STDCALL sqlite3_release_memory(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 SQLITE_STDCALL sqlite3_db_release_memory(sqlite3*);
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, the soft heap limit is enforced
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 SQLITE_STDCALL sqlite3_soft_heap_limit64(sqlite3_int64 N);
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 SQLITE_STDCALL sqlite3_soft_heap_limit(int N);
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 existance of 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 SQLITE_STDCALL sqlite3_table_column_metadata(
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()] prior to calling this API,
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 SQLITE_STDCALL sqlite3_load_extension(
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 SQLITE_STDCALL sqlite3_enable_load_extension(sqlite3 *db, int onoff);
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 and integer result as if the signature of the
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 SQLITE_STDCALL sqlite3_auto_extension(void (*xEntryPoint)(void));
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 SQLITE_STDCALL sqlite3_cancel_auto_extension(void (*xEntryPoint)(void));
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 SQLITE_STDCALL sqlite3_reset_auto_extension(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. If a virtual table extension is
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. It may therefore only be used if
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 on left-hand side of constraint */
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 2
5707
- #define SQLITE_INDEX_CONSTRAINT_GT 4
5708
- #define SQLITE_INDEX_CONSTRAINT_LE 8
5709
- #define SQLITE_INDEX_CONSTRAINT_LT 16
5710
- #define SQLITE_INDEX_CONSTRAINT_GE 32
5711
- #define SQLITE_INDEX_CONSTRAINT_MATCH 64
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 SQLITE_STDCALL sqlite3_create_module(
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 SQLITE_STDCALL sqlite3_create_module_v2(
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 SQLITE_STDCALL sqlite3_declare_vtab(sqlite3*, const char *zSQL);
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 SQLITE_STDCALL sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg);
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 SQLITE_STDCALL sqlite3_blob_open(
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 blob handle so that it points
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 blob handle to a new row can be
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 SQLITE_STDCALL sqlite3_blob_reopen(sqlite3_blob *, sqlite3_int64);
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 SQLITE_STDCALL sqlite3_blob_close(sqlite3_blob *);
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 SQLITE_STDCALL sqlite3_blob_bytes(sqlite3_blob *);
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 SQLITE_STDCALL sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);
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 SQLITE_STDCALL sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);
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 *SQLITE_STDCALL sqlite3_vfs_find(const char *zVfsName);
6101
- SQLITE_API int SQLITE_STDCALL sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);
6102
- SQLITE_API int SQLITE_STDCALL sqlite3_vfs_unregister(sqlite3_vfs*);
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 *SQLITE_STDCALL sqlite3_mutex_alloc(int);
6219
- SQLITE_API void SQLITE_STDCALL sqlite3_mutex_free(sqlite3_mutex*);
6220
- SQLITE_API void SQLITE_STDCALL sqlite3_mutex_enter(sqlite3_mutex*);
6221
- SQLITE_API int SQLITE_STDCALL sqlite3_mutex_try(sqlite3_mutex*);
6222
- SQLITE_API void SQLITE_STDCALL sqlite3_mutex_leave(sqlite3_mutex*);
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 SQLITE_STDCALL sqlite3_mutex_held(sqlite3_mutex*);
6333
- SQLITE_API int SQLITE_STDCALL sqlite3_mutex_notheld(sqlite3_mutex*);
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 /* sqlite3_random() */
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 *SQLITE_STDCALL sqlite3_db_mutex(sqlite3*);
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 SQLITE_STDCALL sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*);
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 SQLITE_CDECL sqlite3_test_control(int op, ...);
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 SQLITE_STDCALL sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag);
6491
- SQLITE_API int SQLITE_STDCALL sqlite3_status64(
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. Scratch memory
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]] ^(<dt>SQLITE_STATUS_SCRATCH_USED</dt>
6551
- ** <dd>This parameter returns the number of allocations used out of the
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>This parameter returns the number of bytes of scratch memory
6560
- ** allocation which could not be satisfied by the [SQLITE_CONFIG_SCRATCH]
6561
- ** buffer and where forced to overflow to [sqlite3_malloc()]. The values
6562
- ** returned include overflows because the requested allocation was too
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>This parameter records the deepest parser stack. It is only
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 SQLITE_STDCALL sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg);
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 SQLITE_DBSTATUS_MAX 10 /* Largest defined DBSTATUS */
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 SQLITE_STDCALL sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg);
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 SQLITE_ERROR, if
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 *SQLITE_STDCALL sqlite3_backup_init(
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 SQLITE_STDCALL sqlite3_backup_step(sqlite3_backup *p, int nPage);
7221
- SQLITE_API int SQLITE_STDCALL sqlite3_backup_finish(sqlite3_backup *p);
7222
- SQLITE_API int SQLITE_STDCALL sqlite3_backup_remaining(sqlite3_backup *p);
7223
- SQLITE_API int SQLITE_STDCALL sqlite3_backup_pagecount(sqlite3_backup *p);
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 SQLITE_STDCALL sqlite3_unlock_notify(
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 SQLITE_STDCALL sqlite3_stricmp(const char *, const char *);
7356
- SQLITE_API int SQLITE_STDCALL sqlite3_strnicmp(const char *, const char *, 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 string X matches
7362
- ** the glob pattern P, and it returns non-zero if string X does not match
7363
- ** the glob pattern P. ^The definition of glob pattern matching used in
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 used by SQLite. ^The sqlite3_strglob(P,X) function is case
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 SQLITE_STDCALL sqlite3_strglob(const char *zGlob, const char *zStr);
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 SQLITE_CDECL sqlite3_log(int iErrCode, const char *zFormat, ...);
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
- ** those overwrite any prior [sqlite3_wal_hook()] settings.
8035
+ ** overwrite any prior [sqlite3_wal_hook()] settings.
7429
8036
  */
7430
- SQLITE_API void *SQLITE_STDCALL sqlite3_wal_hook(
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 SQLITE_STDCALL sqlite3_wal_autocheckpoint(sqlite3 *db, int N);
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 SQLITE_STDCALL sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb);
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 SQLITE_STDCALL sqlite3_wal_checkpoint_v2(
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 SQLITE_CDECL sqlite3_vtab_config(sqlite3*, int op, ...);
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 SQLITE_STDCALL sqlite3_vtab_on_conflict(sqlite3 *);
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 SQLITE_STDCALL sqlite3_stmt_scanstatus(
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 SQLITE_STDCALL sqlite3_stmt_scanstatus_reset(sqlite3_stmt*);
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 /* _SQLITE3_H_ */
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 SQLITE_STDCALL sqlite3_rtree_geometry_callback(
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 SQLITE_STDCALL sqlite3_rtree_query_callback(
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
+ ** &nbsp; int nChangeset,
10025
+ ** &nbsp; void *pChangeset,
10026
+ ** </pre>
10027
+ **
10028
+ ** Is replaced by:
10029
+ **
10030
+ ** <pre>
10031
+ ** &nbsp; int (*xInput)(void *pIn, void *pData, int *pnData),
10032
+ ** &nbsp; 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
+ ** &nbsp; int *pnChangeset,
10059
+ ** &nbsp; void **ppChangeset,
10060
+ ** </pre>
10061
+ **
10062
+ ** Is replaced by:
10063
+ **
10064
+ ** <pre>
10065
+ ** &nbsp; int (*xOutput)(void *pOut, const void *pData, int nData),
10066
+ ** &nbsp; 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. For each row visited, the callback function
8052
- ** passed as the fourth argument is invoked. The context and API objects
8053
- ** passed to the callback function may be used to access the properties of
8054
- ** each matched row. Invoking Api.xUserData() returns a copy of the pointer
8055
- ** passed as the third argument to pUserData.
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
- ** iOff>=0;
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 1 */
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
- void (*xPhraseFirst)(Fts5Context*, int iPhrase, Fts5PhraseIter*, int*, int*);
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 inititalize a tokenizer instance.
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 *********/