amalgalite 1.7.0-x64-mingw32 → 1.8.0-x64-mingw32

Sign up to get free protection for your applications and to get access to all the features.
@@ -43,7 +43,30 @@ extern "C" {
43
43
 
44
44
 
45
45
  /*
46
- ** Provide the ability to override linkage features of the interface.
46
+ ** Facilitate override of interface linkage and calling conventions.
47
+ ** Be aware that these macros may not be used within this particular
48
+ ** translation of the amalgamation and its associated header file.
49
+ **
50
+ ** The SQLITE_EXTERN and SQLITE_API macros are used to instruct the
51
+ ** compiler that the target identifier should have external linkage.
52
+ **
53
+ ** The SQLITE_CDECL macro is used to set the calling convention for
54
+ ** public functions that accept a variable number of arguments.
55
+ **
56
+ ** The SQLITE_APICALL macro is used to set the calling convention for
57
+ ** public functions that accept a fixed number of arguments.
58
+ **
59
+ ** The SQLITE_STDCALL macro is no longer used and is now deprecated.
60
+ **
61
+ ** The SQLITE_CALLBACK macro is used to set the calling convention for
62
+ ** function pointers.
63
+ **
64
+ ** The SQLITE_SYSAPI macro is used to set the calling convention for
65
+ ** functions provided by the operating system.
66
+ **
67
+ ** Currently, the SQLITE_CDECL, SQLITE_APICALL, SQLITE_CALLBACK, and
68
+ ** SQLITE_SYSAPI macros are used only when building for environments
69
+ ** that require non-default calling conventions.
47
70
  */
48
71
  #ifndef SQLITE_EXTERN
49
72
  # define SQLITE_EXTERN extern
@@ -123,9 +146,9 @@ extern "C" {
123
146
  ** [sqlite3_libversion_number()], [sqlite3_sourceid()],
124
147
  ** [sqlite_version()] and [sqlite_source_id()].
125
148
  */
126
- #define SQLITE_VERSION "3.34.0"
127
- #define SQLITE_VERSION_NUMBER 3034000
128
- #define SQLITE_SOURCE_ID "2020-12-01 16:14:00 a26b6597e3ae272231b96f9982c3bcc17ddec2f2b6eb4df06a224b91089fed5b"
149
+ #define SQLITE_VERSION "3.40.1"
150
+ #define SQLITE_VERSION_NUMBER 3040001
151
+ #define SQLITE_SOURCE_ID "2022-12-28 14:03:47 df5c253c0b3dd24916e4ec7cf77d3db5294cc9fd45ae7b9c5e82ad8197f38a24"
129
152
 
130
153
  /*
131
154
  ** CAPI3REF: Run-Time Library Version Numbers
@@ -537,12 +560,13 @@ SQLITE_API int sqlite3_exec(
537
560
  #define SQLITE_CONSTRAINT_VTAB (SQLITE_CONSTRAINT | (9<<8))
538
561
  #define SQLITE_CONSTRAINT_ROWID (SQLITE_CONSTRAINT |(10<<8))
539
562
  #define SQLITE_CONSTRAINT_PINNED (SQLITE_CONSTRAINT |(11<<8))
563
+ #define SQLITE_CONSTRAINT_DATATYPE (SQLITE_CONSTRAINT |(12<<8))
540
564
  #define SQLITE_NOTICE_RECOVER_WAL (SQLITE_NOTICE | (1<<8))
541
565
  #define SQLITE_NOTICE_RECOVER_ROLLBACK (SQLITE_NOTICE | (2<<8))
542
566
  #define SQLITE_WARNING_AUTOINDEX (SQLITE_WARNING | (1<<8))
543
567
  #define SQLITE_AUTH_USER (SQLITE_AUTH | (1<<8))
544
568
  #define SQLITE_OK_LOAD_PERMANENTLY (SQLITE_OK | (1<<8))
545
- #define SQLITE_OK_SYMLINK (SQLITE_OK | (2<<8))
569
+ #define SQLITE_OK_SYMLINK (SQLITE_OK | (2<<8)) /* internal use only */
546
570
 
547
571
  /*
548
572
  ** CAPI3REF: Flags For File Open Operations
@@ -550,6 +574,19 @@ SQLITE_API int sqlite3_exec(
550
574
  ** These bit values are intended for use in the
551
575
  ** 3rd parameter to the [sqlite3_open_v2()] interface and
552
576
  ** in the 4th parameter to the [sqlite3_vfs.xOpen] method.
577
+ **
578
+ ** Only those flags marked as "Ok for sqlite3_open_v2()" may be
579
+ ** used as the third argument to the [sqlite3_open_v2()] interface.
580
+ ** The other flags have historically been ignored by sqlite3_open_v2(),
581
+ ** though future versions of SQLite might change so that an error is
582
+ ** raised if any of the disallowed bits are passed into sqlite3_open_v2().
583
+ ** Applications should not depend on the historical behavior.
584
+ **
585
+ ** Note in particular that passing the SQLITE_OPEN_EXCLUSIVE flag into
586
+ ** [sqlite3_open_v2()] does *not* cause the underlying database file
587
+ ** to be opened using O_EXCL. Passing SQLITE_OPEN_EXCLUSIVE into
588
+ ** [sqlite3_open_v2()] has historically be a no-op and might become an
589
+ ** error in future versions of SQLite.
553
590
  */
554
591
  #define SQLITE_OPEN_READONLY 0x00000001 /* Ok for sqlite3_open_v2() */
555
592
  #define SQLITE_OPEN_READWRITE 0x00000002 /* Ok for sqlite3_open_v2() */
@@ -572,6 +609,7 @@ SQLITE_API int sqlite3_exec(
572
609
  #define SQLITE_OPEN_PRIVATECACHE 0x00040000 /* Ok for sqlite3_open_v2() */
573
610
  #define SQLITE_OPEN_WAL 0x00080000 /* VFS only */
574
611
  #define SQLITE_OPEN_NOFOLLOW 0x01000000 /* Ok for sqlite3_open_v2() */
612
+ #define SQLITE_OPEN_EXRESCODE 0x02000000 /* Extended result codes */
575
613
 
576
614
  /* Reserved: 0x00F00000 */
577
615
  /* Legacy compatibility: */
@@ -632,13 +670,17 @@ SQLITE_API int sqlite3_exec(
632
670
  **
633
671
  ** SQLite uses one of these integer values as the second
634
672
  ** argument to calls it makes to the xLock() and xUnlock() methods
635
- ** of an [sqlite3_io_methods] object.
673
+ ** of an [sqlite3_io_methods] object. These values are ordered from
674
+ ** lest restrictive to most restrictive.
675
+ **
676
+ ** The argument to xLock() is always SHARED or higher. The argument to
677
+ ** xUnlock is either SHARED or NONE.
636
678
  */
637
- #define SQLITE_LOCK_NONE 0
638
- #define SQLITE_LOCK_SHARED 1
639
- #define SQLITE_LOCK_RESERVED 2
640
- #define SQLITE_LOCK_PENDING 3
641
- #define SQLITE_LOCK_EXCLUSIVE 4
679
+ #define SQLITE_LOCK_NONE 0 /* xUnlock() only */
680
+ #define SQLITE_LOCK_SHARED 1 /* xLock() or xUnlock() */
681
+ #define SQLITE_LOCK_RESERVED 2 /* xLock() only */
682
+ #define SQLITE_LOCK_PENDING 3 /* xLock() only */
683
+ #define SQLITE_LOCK_EXCLUSIVE 4 /* xLock() only */
642
684
 
643
685
  /*
644
686
  ** CAPI3REF: Synchronization Type Flags
@@ -716,7 +758,14 @@ struct sqlite3_file {
716
758
  ** <li> [SQLITE_LOCK_PENDING], or
717
759
  ** <li> [SQLITE_LOCK_EXCLUSIVE].
718
760
  ** </ul>
719
- ** xLock() increases the lock. xUnlock() decreases the lock.
761
+ ** xLock() upgrades the database file lock. In other words, xLock() moves the
762
+ ** database file lock in the direction NONE toward EXCLUSIVE. The argument to
763
+ ** xLock() is always on of SHARED, RESERVED, PENDING, or EXCLUSIVE, never
764
+ ** SQLITE_LOCK_NONE. If the database file lock is already at or above the
765
+ ** requested lock, then the call to xLock() is a no-op.
766
+ ** xUnlock() downgrades the database file lock to either SHARED or NONE.
767
+ * If the lock is already at or below the requested lock state, then the call
768
+ ** to xUnlock() is a no-op.
720
769
  ** The xCheckReservedLock() method checks whether any database connection,
721
770
  ** either in this process or in some other process, is holding a RESERVED,
722
771
  ** PENDING, or EXCLUSIVE lock on the file. It returns true
@@ -821,9 +870,8 @@ struct sqlite3_io_methods {
821
870
  ** opcode causes the xFileControl method to write the current state of
822
871
  ** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],
823
872
  ** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])
824
- ** into an integer that the pArg argument points to. This capability
825
- ** is used during testing and is only available when the SQLITE_TEST
826
- ** compile-time option is used.
873
+ ** into an integer that the pArg argument points to.
874
+ ** This capability is only available if SQLite is compiled with [SQLITE_DEBUG].
827
875
  **
828
876
  ** <li>[[SQLITE_FCNTL_SIZE_HINT]]
829
877
  ** The [SQLITE_FCNTL_SIZE_HINT] opcode is used by SQLite to give the VFS
@@ -1128,6 +1176,29 @@ struct sqlite3_io_methods {
1128
1176
  ** file to the database file, but before the *-shm file is updated to
1129
1177
  ** record the fact that the pages have been checkpointed.
1130
1178
  ** </ul>
1179
+ **
1180
+ ** <li>[[SQLITE_FCNTL_EXTERNAL_READER]]
1181
+ ** The EXPERIMENTAL [SQLITE_FCNTL_EXTERNAL_READER] opcode is used to detect
1182
+ ** whether or not there is a database client in another process with a wal-mode
1183
+ ** transaction open on the database or not. It is only available on unix.The
1184
+ ** (void*) argument passed with this file-control should be a pointer to a
1185
+ ** value of type (int). The integer value is set to 1 if the database is a wal
1186
+ ** mode database and there exists at least one client in another process that
1187
+ ** currently has an SQL transaction open on the database. It is set to 0 if
1188
+ ** the database is not a wal-mode db, or if there is no such connection in any
1189
+ ** other process. This opcode cannot be used to detect transactions opened
1190
+ ** by clients within the current process, only within other processes.
1191
+ ** </ul>
1192
+ **
1193
+ ** <li>[[SQLITE_FCNTL_CKSM_FILE]]
1194
+ ** Used by the cksmvfs VFS module only.
1195
+ **
1196
+ ** <li>[[SQLITE_FCNTL_RESET_CACHE]]
1197
+ ** If there is currently no transaction open on the database, and the
1198
+ ** database is not a temp db, then this file-control purges the contents
1199
+ ** of the in-memory page cache. If there is an open transaction, or if
1200
+ ** the db is a temp-db, it is a no-op, not an error.
1201
+ ** </ul>
1131
1202
  */
1132
1203
  #define SQLITE_FCNTL_LOCKSTATE 1
1133
1204
  #define SQLITE_FCNTL_GET_LOCKPROXYFILE 2
@@ -1167,6 +1238,9 @@ struct sqlite3_io_methods {
1167
1238
  #define SQLITE_FCNTL_CKPT_DONE 37
1168
1239
  #define SQLITE_FCNTL_RESERVE_BYTES 38
1169
1240
  #define SQLITE_FCNTL_CKPT_START 39
1241
+ #define SQLITE_FCNTL_EXTERNAL_READER 40
1242
+ #define SQLITE_FCNTL_CKSM_FILE 41
1243
+ #define SQLITE_FCNTL_RESET_CACHE 42
1170
1244
 
1171
1245
  /* deprecated names */
1172
1246
  #define SQLITE_GET_LOCKPROXYFILE SQLITE_FCNTL_GET_LOCKPROXYFILE
@@ -1196,6 +1270,26 @@ typedef struct sqlite3_mutex sqlite3_mutex;
1196
1270
  */
1197
1271
  typedef struct sqlite3_api_routines sqlite3_api_routines;
1198
1272
 
1273
+ /*
1274
+ ** CAPI3REF: File Name
1275
+ **
1276
+ ** Type [sqlite3_filename] is used by SQLite to pass filenames to the
1277
+ ** xOpen method of a [VFS]. It may be cast to (const char*) and treated
1278
+ ** as a normal, nul-terminated, UTF-8 buffer containing the filename, but
1279
+ ** may also be passed to special APIs such as:
1280
+ **
1281
+ ** <ul>
1282
+ ** <li> sqlite3_filename_database()
1283
+ ** <li> sqlite3_filename_journal()
1284
+ ** <li> sqlite3_filename_wal()
1285
+ ** <li> sqlite3_uri_parameter()
1286
+ ** <li> sqlite3_uri_boolean()
1287
+ ** <li> sqlite3_uri_int64()
1288
+ ** <li> sqlite3_uri_key()
1289
+ ** </ul>
1290
+ */
1291
+ typedef const char *sqlite3_filename;
1292
+
1199
1293
  /*
1200
1294
  ** CAPI3REF: OS Interface Object
1201
1295
  **
@@ -1374,7 +1468,7 @@ struct sqlite3_vfs {
1374
1468
  sqlite3_vfs *pNext; /* Next registered VFS */
1375
1469
  const char *zName; /* Name of this virtual file system */
1376
1470
  void *pAppData; /* Pointer to application-specific data */
1377
- int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,
1471
+ int (*xOpen)(sqlite3_vfs*, sqlite3_filename zName, sqlite3_file*,
1378
1472
  int flags, int *pOutFlags);
1379
1473
  int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
1380
1474
  int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut);
@@ -2115,7 +2209,13 @@ struct sqlite3_mem_methods {
2115
2209
  ** The second parameter is a pointer to an integer into which
2116
2210
  ** is written 0 or 1 to indicate whether triggers are disabled or enabled
2117
2211
  ** following this call. The second parameter may be a NULL pointer, in
2118
- ** which case the trigger setting is not reported back. </dd>
2212
+ ** which case the trigger setting is not reported back.
2213
+ **
2214
+ ** <p>Originally this option disabled all triggers. ^(However, since
2215
+ ** SQLite version 3.35.0, TEMP triggers are still allowed even if
2216
+ ** this option is off. So, in other words, this option now only disables
2217
+ ** triggers in the main database schema or in the schemas of ATTACH-ed
2218
+ ** databases.)^ </dd>
2119
2219
  **
2120
2220
  ** [[SQLITE_DBCONFIG_ENABLE_VIEW]]
2121
2221
  ** <dt>SQLITE_DBCONFIG_ENABLE_VIEW</dt>
@@ -2126,7 +2226,13 @@ struct sqlite3_mem_methods {
2126
2226
  ** The second parameter is a pointer to an integer into which
2127
2227
  ** is written 0 or 1 to indicate whether views are disabled or enabled
2128
2228
  ** following this call. The second parameter may be a NULL pointer, in
2129
- ** which case the view setting is not reported back. </dd>
2229
+ ** which case the view setting is not reported back.
2230
+ **
2231
+ ** <p>Originally this option disabled all views. ^(However, since
2232
+ ** SQLite version 3.35.0, TEMP views are still allowed even if
2233
+ ** this option is off. So, in other words, this option now only disables
2234
+ ** views in the main database schema or in the schemas of ATTACH-ed
2235
+ ** databases.)^ </dd>
2130
2236
  **
2131
2237
  ** [[SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER]]
2132
2238
  ** <dt>SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER</dt>
@@ -2240,6 +2346,7 @@ struct sqlite3_mem_methods {
2240
2346
  ** <ul>
2241
2347
  ** <li> The [PRAGMA writable_schema=ON] statement.
2242
2348
  ** <li> The [PRAGMA journal_mode=OFF] statement.
2349
+ ** <li> The [PRAGMA schema_version=N] statement.
2243
2350
  ** <li> Writes to the [sqlite_dbpage] virtual table.
2244
2351
  ** <li> Direct writes to [shadow tables].
2245
2352
  ** </ul>
@@ -2433,11 +2540,14 @@ SQLITE_API void sqlite3_set_last_insert_rowid(sqlite3*,sqlite3_int64);
2433
2540
  ** CAPI3REF: Count The Number Of Rows Modified
2434
2541
  ** METHOD: sqlite3
2435
2542
  **
2436
- ** ^This function returns the number of rows modified, inserted or
2543
+ ** ^These functions return the number of rows modified, inserted or
2437
2544
  ** deleted by the most recently completed INSERT, UPDATE or DELETE
2438
2545
  ** statement on the database connection specified by the only parameter.
2439
- ** ^Executing any other type of SQL statement does not modify the value
2440
- ** returned by this function.
2546
+ ** The two functions are identical except for the type of the return value
2547
+ ** and that if the number of rows modified by the most recent INSERT, UPDATE
2548
+ ** or DELETE is greater than the maximum value supported by type "int", then
2549
+ ** the return value of sqlite3_changes() is undefined. ^Executing any other
2550
+ ** type of SQL statement does not modify the value returned by these functions.
2441
2551
  **
2442
2552
  ** ^Only changes made directly by the INSERT, UPDATE or DELETE statement are
2443
2553
  ** considered - auxiliary changes caused by [CREATE TRIGGER | triggers],
@@ -2486,16 +2596,21 @@ SQLITE_API void sqlite3_set_last_insert_rowid(sqlite3*,sqlite3_int64);
2486
2596
  ** </ul>
2487
2597
  */
2488
2598
  SQLITE_API int sqlite3_changes(sqlite3*);
2599
+ SQLITE_API sqlite3_int64 sqlite3_changes64(sqlite3*);
2489
2600
 
2490
2601
  /*
2491
2602
  ** CAPI3REF: Total Number Of Rows Modified
2492
2603
  ** METHOD: sqlite3
2493
2604
  **
2494
- ** ^This function returns the total number of rows inserted, modified or
2605
+ ** ^These functions return the total number of rows inserted, modified or
2495
2606
  ** deleted by all [INSERT], [UPDATE] or [DELETE] statements completed
2496
2607
  ** since the database connection was opened, including those executed as
2497
- ** part of trigger programs. ^Executing any other type of SQL statement
2498
- ** does not affect the value returned by sqlite3_total_changes().
2608
+ ** part of trigger programs. The two functions are identical except for the
2609
+ ** type of the return value and that if the number of rows modified by the
2610
+ ** connection exceeds the maximum value supported by type "int", then
2611
+ ** the return value of sqlite3_total_changes() is undefined. ^Executing
2612
+ ** any other type of SQL statement does not affect the value returned by
2613
+ ** sqlite3_total_changes().
2499
2614
  **
2500
2615
  ** ^Changes made as part of [foreign key actions] are included in the
2501
2616
  ** count, but those made as part of REPLACE constraint resolution are
@@ -2523,6 +2638,7 @@ SQLITE_API int sqlite3_changes(sqlite3*);
2523
2638
  ** </ul>
2524
2639
  */
2525
2640
  SQLITE_API int sqlite3_total_changes(sqlite3*);
2641
+ SQLITE_API sqlite3_int64 sqlite3_total_changes64(sqlite3*);
2526
2642
 
2527
2643
  /*
2528
2644
  ** CAPI3REF: Interrupt A Long-Running Query
@@ -3346,20 +3462,39 @@ SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
3346
3462
  ** <dd>The database is opened [shared cache] enabled, overriding
3347
3463
  ** the default shared cache setting provided by
3348
3464
  ** [sqlite3_enable_shared_cache()].)^
3465
+ ** The [use of shared cache mode is discouraged] and hence shared cache
3466
+ ** capabilities may be omitted from many builds of SQLite. In such cases,
3467
+ ** this option is a no-op.
3349
3468
  **
3350
3469
  ** ^(<dt>[SQLITE_OPEN_PRIVATECACHE]</dt>
3351
3470
  ** <dd>The database is opened [shared cache] disabled, overriding
3352
3471
  ** the default shared cache setting provided by
3353
3472
  ** [sqlite3_enable_shared_cache()].)^
3354
3473
  **
3474
+ ** [[OPEN_EXRESCODE]] ^(<dt>[SQLITE_OPEN_EXRESCODE]</dt>
3475
+ ** <dd>The database connection comes up in "extended result code mode".
3476
+ ** In other words, the database behaves has if
3477
+ ** [sqlite3_extended_result_codes(db,1)] where called on the database
3478
+ ** connection as soon as the connection is created. In addition to setting
3479
+ ** the extended result code mode, this flag also causes [sqlite3_open_v2()]
3480
+ ** to return an extended result code.</dd>
3481
+ **
3355
3482
  ** [[OPEN_NOFOLLOW]] ^(<dt>[SQLITE_OPEN_NOFOLLOW]</dt>
3356
- ** <dd>The database filename is not allowed to be a symbolic link</dd>
3483
+ ** <dd>The database filename is not allowed to contain a symbolic link</dd>
3357
3484
  ** </dl>)^
3358
3485
  **
3359
3486
  ** If the 3rd parameter to sqlite3_open_v2() is not one of the
3360
3487
  ** required combinations shown above optionally combined with other
3361
3488
  ** [SQLITE_OPEN_READONLY | SQLITE_OPEN_* bits]
3362
- ** then the behavior is undefined.
3489
+ ** then the behavior is undefined. Historic versions of SQLite
3490
+ ** have silently ignored surplus bits in the flags parameter to
3491
+ ** sqlite3_open_v2(), however that behavior might not be carried through
3492
+ ** into future versions of SQLite and so applications should not rely
3493
+ ** upon it. Note in particular that the SQLITE_OPEN_EXCLUSIVE flag is a no-op
3494
+ ** for sqlite3_open_v2(). The SQLITE_OPEN_EXCLUSIVE does *not* cause
3495
+ ** the open to fail if the database already exists. The SQLITE_OPEN_EXCLUSIVE
3496
+ ** flag is intended for use by the [sqlite3_vfs|VFS interface] only, and not
3497
+ ** by sqlite3_open_v2().
3363
3498
  **
3364
3499
  ** ^The fourth parameter to sqlite3_open_v2() is the name of the
3365
3500
  ** [sqlite3_vfs] object that defines the operating system interface that
@@ -3499,6 +3634,7 @@ SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
3499
3634
  ** that uses dot-files in place of posix advisory locking.
3500
3635
  ** <tr><td> file:data.db?mode=readonly <td>
3501
3636
  ** An error. "readonly" is not a valid option for the "mode" parameter.
3637
+ ** Use "ro" instead: "file:data.db?mode=ro".
3502
3638
  ** </table>
3503
3639
  **
3504
3640
  ** ^URI hexadecimal escape sequences (%HH) are supported within the path and
@@ -3603,10 +3739,10 @@ SQLITE_API int sqlite3_open_v2(
3603
3739
  **
3604
3740
  ** See the [URI filename] documentation for additional information.
3605
3741
  */
3606
- SQLITE_API const char *sqlite3_uri_parameter(const char *zFilename, const char *zParam);
3607
- SQLITE_API int sqlite3_uri_boolean(const char *zFile, const char *zParam, int bDefault);
3608
- SQLITE_API sqlite3_int64 sqlite3_uri_int64(const char*, const char*, sqlite3_int64);
3609
- SQLITE_API const char *sqlite3_uri_key(const char *zFilename, int N);
3742
+ SQLITE_API const char *sqlite3_uri_parameter(sqlite3_filename z, const char *zParam);
3743
+ SQLITE_API int sqlite3_uri_boolean(sqlite3_filename z, const char *zParam, int bDefault);
3744
+ SQLITE_API sqlite3_int64 sqlite3_uri_int64(sqlite3_filename, const char*, sqlite3_int64);
3745
+ SQLITE_API const char *sqlite3_uri_key(sqlite3_filename z, int N);
3610
3746
 
3611
3747
  /*
3612
3748
  ** CAPI3REF: Translate filenames
@@ -3635,9 +3771,9 @@ SQLITE_API const char *sqlite3_uri_key(const char *zFilename, int N);
3635
3771
  ** return value from [sqlite3_db_filename()], then the result is
3636
3772
  ** undefined and is likely a memory access violation.
3637
3773
  */
3638
- SQLITE_API const char *sqlite3_filename_database(const char*);
3639
- SQLITE_API const char *sqlite3_filename_journal(const char*);
3640
- SQLITE_API const char *sqlite3_filename_wal(const char*);
3774
+ SQLITE_API const char *sqlite3_filename_database(sqlite3_filename);
3775
+ SQLITE_API const char *sqlite3_filename_journal(sqlite3_filename);
3776
+ SQLITE_API const char *sqlite3_filename_wal(sqlite3_filename);
3641
3777
 
3642
3778
  /*
3643
3779
  ** CAPI3REF: Database File Corresponding To A Journal
@@ -3697,20 +3833,20 @@ SQLITE_API sqlite3_file *sqlite3_database_file_object(const char*);
3697
3833
  ** If the Y parameter to sqlite3_free_filename(Y) is anything other
3698
3834
  ** than a NULL pointer or a pointer previously acquired from
3699
3835
  ** sqlite3_create_filename(), then bad things such as heap
3700
- ** corruption or segfaults may occur. The value Y should be
3836
+ ** corruption or segfaults may occur. The value Y should not be
3701
3837
  ** used again after sqlite3_free_filename(Y) has been called. This means
3702
3838
  ** that if the [sqlite3_vfs.xOpen()] method of a VFS has been called using Y,
3703
3839
  ** then the corresponding [sqlite3_module.xClose() method should also be
3704
3840
  ** invoked prior to calling sqlite3_free_filename(Y).
3705
3841
  */
3706
- SQLITE_API char *sqlite3_create_filename(
3842
+ SQLITE_API sqlite3_filename sqlite3_create_filename(
3707
3843
  const char *zDatabase,
3708
3844
  const char *zJournal,
3709
3845
  const char *zWal,
3710
3846
  int nParam,
3711
3847
  const char **azParam
3712
3848
  );
3713
- SQLITE_API void sqlite3_free_filename(char*);
3849
+ SQLITE_API void sqlite3_free_filename(sqlite3_filename);
3714
3850
 
3715
3851
  /*
3716
3852
  ** CAPI3REF: Error Codes And Messages
@@ -3729,13 +3865,14 @@ SQLITE_API void sqlite3_free_filename(char*);
3729
3865
  ** sqlite3_extended_errcode() might change with each API call.
3730
3866
  ** Except, there are some interfaces that are guaranteed to never
3731
3867
  ** change the value of the error code. The error-code preserving
3732
- ** interfaces are:
3868
+ ** interfaces include the following:
3733
3869
  **
3734
3870
  ** <ul>
3735
3871
  ** <li> sqlite3_errcode()
3736
3872
  ** <li> sqlite3_extended_errcode()
3737
3873
  ** <li> sqlite3_errmsg()
3738
3874
  ** <li> sqlite3_errmsg16()
3875
+ ** <li> sqlite3_error_offset()
3739
3876
  ** </ul>
3740
3877
  **
3741
3878
  ** ^The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
@@ -3750,6 +3887,13 @@ SQLITE_API void sqlite3_free_filename(char*);
3750
3887
  ** ^(Memory to hold the error message string is managed internally
3751
3888
  ** and must not be freed by the application)^.
3752
3889
  **
3890
+ ** ^If the most recent error references a specific token in the input
3891
+ ** SQL, the sqlite3_error_offset() interface returns the byte offset
3892
+ ** of the start of that token. ^The byte offset returned by
3893
+ ** sqlite3_error_offset() assumes that the input SQL is UTF8.
3894
+ ** ^If the most recent error does not reference a specific token in the input
3895
+ ** SQL, then the sqlite3_error_offset() function returns -1.
3896
+ **
3753
3897
  ** When the serialized [threading mode] is in use, it might be the
3754
3898
  ** case that a second error occurs on a separate thread in between
3755
3899
  ** the time of the first error and the call to these interfaces.
@@ -3769,6 +3913,7 @@ SQLITE_API int sqlite3_extended_errcode(sqlite3 *db);
3769
3913
  SQLITE_API const char *sqlite3_errmsg(sqlite3*);
3770
3914
  SQLITE_API const void *sqlite3_errmsg16(sqlite3*);
3771
3915
  SQLITE_API const char *sqlite3_errstr(int);
3916
+ SQLITE_API int sqlite3_error_offset(sqlite3 *db);
3772
3917
 
3773
3918
  /*
3774
3919
  ** CAPI3REF: Prepared Statement Object
@@ -4126,12 +4271,17 @@ SQLITE_API int sqlite3_prepare16_v3(
4126
4271
  ** are managed by SQLite and are automatically freed when the prepared
4127
4272
  ** statement is finalized.
4128
4273
  ** ^The string returned by sqlite3_expanded_sql(P), on the other hand,
4129
- ** is obtained from [sqlite3_malloc()] and must be free by the application
4274
+ ** is obtained from [sqlite3_malloc()] and must be freed by the application
4130
4275
  ** by passing it to [sqlite3_free()].
4276
+ **
4277
+ ** ^The sqlite3_normalized_sql() interface is only available if
4278
+ ** the [SQLITE_ENABLE_NORMALIZE] compile-time option is defined.
4131
4279
  */
4132
4280
  SQLITE_API const char *sqlite3_sql(sqlite3_stmt *pStmt);
4133
4281
  SQLITE_API char *sqlite3_expanded_sql(sqlite3_stmt *pStmt);
4282
+ #ifdef SQLITE_ENABLE_NORMALIZE
4134
4283
  SQLITE_API const char *sqlite3_normalized_sql(sqlite3_stmt *pStmt);
4284
+ #endif
4135
4285
 
4136
4286
  /*
4137
4287
  ** CAPI3REF: Determine If An SQL Statement Writes The Database
@@ -4166,6 +4316,19 @@ SQLITE_API const char *sqlite3_normalized_sql(sqlite3_stmt *pStmt);
4166
4316
  ** [BEGIN] merely sets internal flags, but the [BEGIN|BEGIN IMMEDIATE] and
4167
4317
  ** [BEGIN|BEGIN EXCLUSIVE] commands do touch the database and so
4168
4318
  ** sqlite3_stmt_readonly() returns false for those commands.
4319
+ **
4320
+ ** ^This routine returns false if there is any possibility that the
4321
+ ** statement might change the database file. ^A false return does
4322
+ ** not guarantee that the statement will change the database file.
4323
+ ** ^For example, an UPDATE statement might have a WHERE clause that
4324
+ ** makes it a no-op, but the sqlite3_stmt_readonly() result would still
4325
+ ** be false. ^Similarly, a CREATE TABLE IF NOT EXISTS statement is a
4326
+ ** read-only no-op if the table already exists, but
4327
+ ** sqlite3_stmt_readonly() still returns false for such a statement.
4328
+ **
4329
+ ** ^If prepared statement X is an [EXPLAIN] or [EXPLAIN QUERY PLAN]
4330
+ ** statement, then sqlite3_stmt_readonly(X) returns the same value as
4331
+ ** if the EXPLAIN or EXPLAIN QUERY PLAN prefix were omitted.
4169
4332
  */
4170
4333
  SQLITE_API int sqlite3_stmt_readonly(sqlite3_stmt *pStmt);
4171
4334
 
@@ -4234,6 +4397,8 @@ SQLITE_API int sqlite3_stmt_busy(sqlite3_stmt*);
4234
4397
  **
4235
4398
  ** ^The sqlite3_value objects that are passed as parameters into the
4236
4399
  ** implementation of [application-defined SQL functions] are protected.
4400
+ ** ^The sqlite3_value objects returned by [sqlite3_vtab_rhs_value()]
4401
+ ** are protected.
4237
4402
  ** ^The sqlite3_value object returned by
4238
4403
  ** [sqlite3_column_value()] is unprotected.
4239
4404
  ** Unprotected sqlite3_value objects may only be used as arguments
@@ -4335,18 +4500,22 @@ typedef struct sqlite3_context sqlite3_context;
4335
4500
  ** contain embedded NULs. The result of expressions involving strings
4336
4501
  ** with embedded NULs is undefined.
4337
4502
  **
4338
- ** ^The fifth argument to the BLOB and string binding interfaces
4339
- ** is a destructor used to dispose of the BLOB or
4340
- ** string after SQLite has finished with it. ^The destructor is called
4341
- ** to dispose of the BLOB or string even if the call to the bind API fails,
4342
- ** except the destructor is not called if the third parameter is a NULL
4343
- ** pointer or the fourth parameter is negative.
4344
- ** ^If the fifth argument is
4345
- ** the special value [SQLITE_STATIC], then SQLite assumes that the
4346
- ** information is in static, unmanaged space and does not need to be freed.
4347
- ** ^If the fifth argument has the value [SQLITE_TRANSIENT], then
4348
- ** SQLite makes its own private copy of the data immediately, before
4349
- ** the sqlite3_bind_*() routine returns.
4503
+ ** ^The fifth argument to the BLOB and string binding interfaces controls
4504
+ ** or indicates the lifetime of the object referenced by the third parameter.
4505
+ ** These three options exist:
4506
+ ** ^ (1) A destructor to dispose of the BLOB or string after SQLite has finished
4507
+ ** with it may be passed. ^It is called to dispose of the BLOB or string even
4508
+ ** if the call to the bind API fails, except the destructor is not called if
4509
+ ** the third parameter is a NULL pointer or the fourth parameter is negative.
4510
+ ** ^ (2) The special constant, [SQLITE_STATIC], may be passsed to indicate that
4511
+ ** the application remains responsible for disposing of the object. ^In this
4512
+ ** case, the object and the provided pointer to it must remain valid until
4513
+ ** either the prepared statement is finalized or the same SQL parameter is
4514
+ ** bound to something else, whichever occurs sooner.
4515
+ ** ^ (3) The constant, [SQLITE_TRANSIENT], may be passed to indicate that the
4516
+ ** object is to be copied prior to the return from sqlite3_bind_*(). ^The
4517
+ ** object and pointer to it must remain valid until then. ^SQLite will then
4518
+ ** manage the lifetime of its private copy.
4350
4519
  **
4351
4520
  ** ^The sixth argument to sqlite3_bind_text64() must be one of
4352
4521
  ** [SQLITE_UTF8], [SQLITE_UTF16], [SQLITE_UTF16BE], or [SQLITE_UTF16LE]
@@ -4851,6 +5020,10 @@ SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
4851
5020
  ** even empty strings, are always zero-terminated. ^The return
4852
5021
  ** value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer.
4853
5022
  **
5023
+ ** ^Strings returned by sqlite3_column_text16() always have the endianness
5024
+ ** which is native to the platform, regardless of the text encoding set
5025
+ ** for the database.
5026
+ **
4854
5027
  ** <b>Warning:</b> ^The object returned by [sqlite3_column_value()] is an
4855
5028
  ** [unprotected sqlite3_value] object. In a multithreaded environment,
4856
5029
  ** an unprotected sqlite3_value object may only be used safely with
@@ -4864,7 +5037,7 @@ SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
4864
5037
  ** [application-defined SQL functions] or [virtual tables], not within
4865
5038
  ** top-level application code.
4866
5039
  **
4867
- ** The these routines may attempt to convert the datatype of the result.
5040
+ ** These routines may attempt to convert the datatype of the result.
4868
5041
  ** ^For example, if the internal representation is FLOAT and a text result
4869
5042
  ** is requested, [sqlite3_snprintf()] is used internally to perform the
4870
5043
  ** conversion automatically. ^(The following table details the conversions
@@ -4889,7 +5062,7 @@ SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
4889
5062
  ** <tr><td> TEXT <td> BLOB <td> No change
4890
5063
  ** <tr><td> BLOB <td> INTEGER <td> [CAST] to INTEGER
4891
5064
  ** <tr><td> BLOB <td> FLOAT <td> [CAST] to REAL
4892
- ** <tr><td> BLOB <td> TEXT <td> Add a zero terminator if needed
5065
+ ** <tr><td> BLOB <td> TEXT <td> [CAST] to TEXT, ensure zero terminator
4893
5066
  ** </table>
4894
5067
  ** </blockquote>)^
4895
5068
  **
@@ -5088,7 +5261,6 @@ SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt);
5088
5261
  ** within VIEWs, TRIGGERs, CHECK constraints, generated column expressions,
5089
5262
  ** index expressions, or the WHERE clause of partial indexes.
5090
5263
  **
5091
- ** <span style="background-color:#ffff90;">
5092
5264
  ** For best security, the [SQLITE_DIRECTONLY] flag is recommended for
5093
5265
  ** all application-defined SQL functions that do not need to be
5094
5266
  ** used inside of triggers, view, CHECK constraints, or other elements of
@@ -5098,7 +5270,6 @@ SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt);
5098
5270
  ** a database file to include invocations of the function with parameters
5099
5271
  ** chosen by the attacker, which the application will then execute when
5100
5272
  ** the database file is opened and read.
5101
- ** </span>
5102
5273
  **
5103
5274
  ** ^(The fifth parameter is an arbitrary pointer. The implementation of the
5104
5275
  ** function can gain access to this pointer using [sqlite3_user_data()].)^
@@ -5378,6 +5549,16 @@ SQLITE_API SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int6
5378
5549
  ** then the conversion is performed. Otherwise no conversion occurs.
5379
5550
  ** The [SQLITE_INTEGER | datatype] after conversion is returned.)^
5380
5551
  **
5552
+ ** ^(The sqlite3_value_encoding(X) interface returns one of [SQLITE_UTF8],
5553
+ ** [SQLITE_UTF16BE], or [SQLITE_UTF16LE] according to the current encoding
5554
+ ** of the value X, assuming that X has type TEXT.)^ If sqlite3_value_type(X)
5555
+ ** returns something other than SQLITE_TEXT, then the return value from
5556
+ ** sqlite3_value_encoding(X) is meaningless. ^Calls to
5557
+ ** sqlite3_value_text(X), sqlite3_value_text16(X), sqlite3_value_text16be(X),
5558
+ ** sqlite3_value_text16le(X), sqlite3_value_bytes(X), or
5559
+ ** sqlite3_value_bytes16(X) might change the encoding of the value X and
5560
+ ** thus change the return from subsequent calls to sqlite3_value_encoding(X).
5561
+ **
5381
5562
  ** ^Within the [xUpdate] method of a [virtual table], the
5382
5563
  ** sqlite3_value_nochange(X) interface returns true if and only if
5383
5564
  ** the column corresponding to X is unchanged by the UPDATE operation
@@ -5442,6 +5623,7 @@ SQLITE_API int sqlite3_value_type(sqlite3_value*);
5442
5623
  SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*);
5443
5624
  SQLITE_API int sqlite3_value_nochange(sqlite3_value*);
5444
5625
  SQLITE_API int sqlite3_value_frombind(sqlite3_value*);
5626
+ SQLITE_API int sqlite3_value_encoding(sqlite3_value*);
5445
5627
 
5446
5628
  /*
5447
5629
  ** CAPI3REF: Finding The Subtype Of SQL Values
@@ -5463,7 +5645,8 @@ SQLITE_API unsigned int sqlite3_value_subtype(sqlite3_value*);
5463
5645
  ** object D and returns a pointer to that copy. ^The [sqlite3_value] returned
5464
5646
  ** is a [protected sqlite3_value] object even if the input is not.
5465
5647
  ** ^The sqlite3_value_dup(V) interface returns NULL if V is NULL or if a
5466
- ** memory allocation fails.
5648
+ ** memory allocation fails. ^If V is a [pointer value], then the result
5649
+ ** of sqlite3_value_dup(V) is a NULL value.
5467
5650
  **
5468
5651
  ** ^The sqlite3_value_free(V) interface frees an [sqlite3_value] object
5469
5652
  ** previously obtained from [sqlite3_value_dup()]. ^If V is a NULL pointer
@@ -5494,7 +5677,7 @@ SQLITE_API void sqlite3_value_free(sqlite3_value*);
5494
5677
  **
5495
5678
  ** ^The sqlite3_aggregate_context(C,N) routine returns a NULL pointer
5496
5679
  ** when first called if N is less than or equal to zero or if a memory
5497
- ** allocate error occurs.
5680
+ ** allocation error occurs.
5498
5681
  **
5499
5682
  ** ^(The amount of space allocated by sqlite3_aggregate_context(C,N) is
5500
5683
  ** determined by the N parameter on first successful call. Changing the
@@ -5699,9 +5882,10 @@ typedef void (*sqlite3_destructor_type)(void*);
5699
5882
  ** of [SQLITE_UTF8], [SQLITE_UTF16], [SQLITE_UTF16BE], or [SQLITE_UTF16LE].
5700
5883
  ** ^SQLite takes the text result from the application from
5701
5884
  ** the 2nd parameter of the sqlite3_result_text* interfaces.
5702
- ** ^If the 3rd parameter to the sqlite3_result_text* interfaces
5703
- ** is negative, then SQLite takes result text from the 2nd parameter
5704
- ** through the first zero character.
5885
+ ** ^If the 3rd parameter to any of the sqlite3_result_text* interfaces
5886
+ ** other than sqlite3_result_text64() is negative, then SQLite computes
5887
+ ** the string length itself by searching the 2nd parameter for the first
5888
+ ** zero character.
5705
5889
  ** ^If the 3rd parameter to the sqlite3_result_text* interfaces
5706
5890
  ** is non-negative, then as many bytes (not characters) of the text
5707
5891
  ** pointed to by the 2nd parameter are taken as the application-defined
@@ -6145,6 +6329,28 @@ SQLITE_API int sqlite3_get_autocommit(sqlite3*);
6145
6329
  */
6146
6330
  SQLITE_API sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
6147
6331
 
6332
+ /*
6333
+ ** CAPI3REF: Return The Schema Name For A Database Connection
6334
+ ** METHOD: sqlite3
6335
+ **
6336
+ ** ^The sqlite3_db_name(D,N) interface returns a pointer to the schema name
6337
+ ** for the N-th database on database connection D, or a NULL pointer of N is
6338
+ ** out of range. An N value of 0 means the main database file. An N of 1 is
6339
+ ** the "temp" schema. Larger values of N correspond to various ATTACH-ed
6340
+ ** databases.
6341
+ **
6342
+ ** Space to hold the string that is returned by sqlite3_db_name() is managed
6343
+ ** by SQLite itself. The string might be deallocated by any operation that
6344
+ ** changes the schema, including [ATTACH] or [DETACH] or calls to
6345
+ ** [sqlite3_serialize()] or [sqlite3_deserialize()], even operations that
6346
+ ** occur on a different thread. Applications that need to
6347
+ ** remember the string long-term should make their own copy. Applications that
6348
+ ** are accessing the same database connection simultaneously on multiple
6349
+ ** threads should mutex-protect calls to this API and should make their own
6350
+ ** private copy of the result prior to releasing the mutex.
6351
+ */
6352
+ SQLITE_API const char *sqlite3_db_name(sqlite3 *db, int N);
6353
+
6148
6354
  /*
6149
6355
  ** CAPI3REF: Return The Filename For A Database Connection
6150
6356
  ** METHOD: sqlite3
@@ -6175,7 +6381,7 @@ SQLITE_API sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
6175
6381
  ** <li> [sqlite3_filename_wal()]
6176
6382
  ** </ul>
6177
6383
  */
6178
- SQLITE_API const char *sqlite3_db_filename(sqlite3 *db, const char *zDbName);
6384
+ SQLITE_API sqlite3_filename sqlite3_db_filename(sqlite3 *db, const char *zDbName);
6179
6385
 
6180
6386
  /*
6181
6387
  ** CAPI3REF: Determine if a database is read-only
@@ -6304,6 +6510,72 @@ SQLITE_API sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt);
6304
6510
  SQLITE_API void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
6305
6511
  SQLITE_API void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
6306
6512
 
6513
+ /*
6514
+ ** CAPI3REF: Autovacuum Compaction Amount Callback
6515
+ ** METHOD: sqlite3
6516
+ **
6517
+ ** ^The sqlite3_autovacuum_pages(D,C,P,X) interface registers a callback
6518
+ ** function C that is invoked prior to each autovacuum of the database
6519
+ ** file. ^The callback is passed a copy of the generic data pointer (P),
6520
+ ** the schema-name of the attached database that is being autovacuumed,
6521
+ ** the size of the database file in pages, the number of free pages,
6522
+ ** and the number of bytes per page, respectively. The callback should
6523
+ ** return the number of free pages that should be removed by the
6524
+ ** autovacuum. ^If the callback returns zero, then no autovacuum happens.
6525
+ ** ^If the value returned is greater than or equal to the number of
6526
+ ** free pages, then a complete autovacuum happens.
6527
+ **
6528
+ ** <p>^If there are multiple ATTACH-ed database files that are being
6529
+ ** modified as part of a transaction commit, then the autovacuum pages
6530
+ ** callback is invoked separately for each file.
6531
+ **
6532
+ ** <p><b>The callback is not reentrant.</b> The callback function should
6533
+ ** not attempt to invoke any other SQLite interface. If it does, bad
6534
+ ** things may happen, including segmentation faults and corrupt database
6535
+ ** files. The callback function should be a simple function that
6536
+ ** does some arithmetic on its input parameters and returns a result.
6537
+ **
6538
+ ** ^The X parameter to sqlite3_autovacuum_pages(D,C,P,X) is an optional
6539
+ ** destructor for the P parameter. ^If X is not NULL, then X(P) is
6540
+ ** invoked whenever the database connection closes or when the callback
6541
+ ** is overwritten by another invocation of sqlite3_autovacuum_pages().
6542
+ **
6543
+ ** <p>^There is only one autovacuum pages callback per database connection.
6544
+ ** ^Each call to the sqlite3_autovacuum_pages() interface overrides all
6545
+ ** previous invocations for that database connection. ^If the callback
6546
+ ** argument (C) to sqlite3_autovacuum_pages(D,C,P,X) is a NULL pointer,
6547
+ ** then the autovacuum steps callback is cancelled. The return value
6548
+ ** from sqlite3_autovacuum_pages() is normally SQLITE_OK, but might
6549
+ ** be some other error code if something goes wrong. The current
6550
+ ** implementation will only return SQLITE_OK or SQLITE_MISUSE, but other
6551
+ ** return codes might be added in future releases.
6552
+ **
6553
+ ** <p>If no autovacuum pages callback is specified (the usual case) or
6554
+ ** a NULL pointer is provided for the callback,
6555
+ ** then the default behavior is to vacuum all free pages. So, in other
6556
+ ** words, the default behavior is the same as if the callback function
6557
+ ** were something like this:
6558
+ **
6559
+ ** <blockquote><pre>
6560
+ ** &nbsp; unsigned int demonstration_autovac_pages_callback(
6561
+ ** &nbsp; void *pClientData,
6562
+ ** &nbsp; const char *zSchema,
6563
+ ** &nbsp; unsigned int nDbPage,
6564
+ ** &nbsp; unsigned int nFreePage,
6565
+ ** &nbsp; unsigned int nBytePerPage
6566
+ ** &nbsp; ){
6567
+ ** &nbsp; return nFreePage;
6568
+ ** &nbsp; }
6569
+ ** </pre></blockquote>
6570
+ */
6571
+ SQLITE_API int sqlite3_autovacuum_pages(
6572
+ sqlite3 *db,
6573
+ unsigned int(*)(void*,const char*,unsigned int,unsigned int,unsigned int),
6574
+ void*,
6575
+ void(*)(void*)
6576
+ );
6577
+
6578
+
6307
6579
  /*
6308
6580
  ** CAPI3REF: Data Change Notification Callbacks
6309
6581
  ** METHOD: sqlite3
@@ -6367,6 +6639,11 @@ SQLITE_API void *sqlite3_update_hook(
6367
6639
  ** to the same database. Sharing is enabled if the argument is true
6368
6640
  ** and disabled if the argument is false.)^
6369
6641
  **
6642
+ ** This interface is omitted if SQLite is compiled with
6643
+ ** [-DSQLITE_OMIT_SHARED_CACHE]. The [-DSQLITE_OMIT_SHARED_CACHE]
6644
+ ** compile-time option is recommended because the
6645
+ ** [use of shared cache mode is discouraged].
6646
+ **
6370
6647
  ** ^Cache sharing is enabled and disabled for an entire process.
6371
6648
  ** This is a change as of SQLite [version 3.5.0] ([dateof:3.5.0]).
6372
6649
  ** In prior versions of SQLite,
@@ -6465,7 +6742,7 @@ SQLITE_API int sqlite3_db_release_memory(sqlite3*);
6465
6742
  ** ^The soft heap limit may not be greater than the hard heap limit.
6466
6743
  ** ^If the hard heap limit is enabled and if sqlite3_soft_heap_limit(N)
6467
6744
  ** is invoked with a value of N that is greater than the hard heap limit,
6468
- ** the the soft heap limit is set to the value of the hard heap limit.
6745
+ ** the soft heap limit is set to the value of the hard heap limit.
6469
6746
  ** ^The soft heap limit is automatically enabled whenever the hard heap
6470
6747
  ** limit is enabled. ^When sqlite3_hard_heap_limit64(N) is invoked and
6471
6748
  ** the soft heap limit is outside the range of 1..N, then the soft heap
@@ -6945,24 +7222,56 @@ struct sqlite3_index_info {
6945
7222
  **
6946
7223
  ** These macros define the allowed values for the
6947
7224
  ** [sqlite3_index_info].aConstraint[].op field. Each value represents
6948
- ** an operator that is part of a constraint term in the wHERE clause of
7225
+ ** an operator that is part of a constraint term in the WHERE clause of
6949
7226
  ** a query that uses a [virtual table].
6950
- */
6951
- #define SQLITE_INDEX_CONSTRAINT_EQ 2
6952
- #define SQLITE_INDEX_CONSTRAINT_GT 4
6953
- #define SQLITE_INDEX_CONSTRAINT_LE 8
6954
- #define SQLITE_INDEX_CONSTRAINT_LT 16
6955
- #define SQLITE_INDEX_CONSTRAINT_GE 32
6956
- #define SQLITE_INDEX_CONSTRAINT_MATCH 64
6957
- #define SQLITE_INDEX_CONSTRAINT_LIKE 65
6958
- #define SQLITE_INDEX_CONSTRAINT_GLOB 66
6959
- #define SQLITE_INDEX_CONSTRAINT_REGEXP 67
6960
- #define SQLITE_INDEX_CONSTRAINT_NE 68
6961
- #define SQLITE_INDEX_CONSTRAINT_ISNOT 69
6962
- #define SQLITE_INDEX_CONSTRAINT_ISNOTNULL 70
6963
- #define SQLITE_INDEX_CONSTRAINT_ISNULL 71
6964
- #define SQLITE_INDEX_CONSTRAINT_IS 72
6965
- #define SQLITE_INDEX_CONSTRAINT_FUNCTION 150
7227
+ **
7228
+ ** ^The left-hand operand of the operator is given by the corresponding
7229
+ ** aConstraint[].iColumn field. ^An iColumn of -1 indicates the left-hand
7230
+ ** operand is the rowid.
7231
+ ** The SQLITE_INDEX_CONSTRAINT_LIMIT and SQLITE_INDEX_CONSTRAINT_OFFSET
7232
+ ** operators have no left-hand operand, and so for those operators the
7233
+ ** corresponding aConstraint[].iColumn is meaningless and should not be
7234
+ ** used.
7235
+ **
7236
+ ** All operator values from SQLITE_INDEX_CONSTRAINT_FUNCTION through
7237
+ ** value 255 are reserved to represent functions that are overloaded
7238
+ ** by the [xFindFunction|xFindFunction method] of the virtual table
7239
+ ** implementation.
7240
+ **
7241
+ ** The right-hand operands for each constraint might be accessible using
7242
+ ** the [sqlite3_vtab_rhs_value()] interface. Usually the right-hand
7243
+ ** operand is only available if it appears as a single constant literal
7244
+ ** in the input SQL. If the right-hand operand is another column or an
7245
+ ** expression (even a constant expression) or a parameter, then the
7246
+ ** sqlite3_vtab_rhs_value() probably will not be able to extract it.
7247
+ ** ^The SQLITE_INDEX_CONSTRAINT_ISNULL and
7248
+ ** SQLITE_INDEX_CONSTRAINT_ISNOTNULL operators have no right-hand operand
7249
+ ** and hence calls to sqlite3_vtab_rhs_value() for those operators will
7250
+ ** always return SQLITE_NOTFOUND.
7251
+ **
7252
+ ** The collating sequence to be used for comparison can be found using
7253
+ ** the [sqlite3_vtab_collation()] interface. For most real-world virtual
7254
+ ** tables, the collating sequence of constraints does not matter (for example
7255
+ ** because the constraints are numeric) and so the sqlite3_vtab_collation()
7256
+ ** interface is no commonly needed.
7257
+ */
7258
+ #define SQLITE_INDEX_CONSTRAINT_EQ 2
7259
+ #define SQLITE_INDEX_CONSTRAINT_GT 4
7260
+ #define SQLITE_INDEX_CONSTRAINT_LE 8
7261
+ #define SQLITE_INDEX_CONSTRAINT_LT 16
7262
+ #define SQLITE_INDEX_CONSTRAINT_GE 32
7263
+ #define SQLITE_INDEX_CONSTRAINT_MATCH 64
7264
+ #define SQLITE_INDEX_CONSTRAINT_LIKE 65
7265
+ #define SQLITE_INDEX_CONSTRAINT_GLOB 66
7266
+ #define SQLITE_INDEX_CONSTRAINT_REGEXP 67
7267
+ #define SQLITE_INDEX_CONSTRAINT_NE 68
7268
+ #define SQLITE_INDEX_CONSTRAINT_ISNOT 69
7269
+ #define SQLITE_INDEX_CONSTRAINT_ISNOTNULL 70
7270
+ #define SQLITE_INDEX_CONSTRAINT_ISNULL 71
7271
+ #define SQLITE_INDEX_CONSTRAINT_IS 72
7272
+ #define SQLITE_INDEX_CONSTRAINT_LIMIT 73
7273
+ #define SQLITE_INDEX_CONSTRAINT_OFFSET 74
7274
+ #define SQLITE_INDEX_CONSTRAINT_FUNCTION 150
6966
7275
 
6967
7276
  /*
6968
7277
  ** CAPI3REF: Register A Virtual Table Implementation
@@ -6991,7 +7300,7 @@ struct sqlite3_index_info {
6991
7300
  ** destructor.
6992
7301
  **
6993
7302
  ** ^If the third parameter (the pointer to the sqlite3_module object) is
6994
- ** NULL then no new module is create and any existing modules with the
7303
+ ** NULL then no new module is created and any existing modules with the
6995
7304
  ** same name are dropped.
6996
7305
  **
6997
7306
  ** See also: [sqlite3_drop_modules()]
@@ -7765,7 +8074,10 @@ SQLITE_API int sqlite3_test_control(int op, ...);
7765
8074
  #define SQLITE_TESTCTRL_PRNG_SEED 28
7766
8075
  #define SQLITE_TESTCTRL_EXTRA_SCHEMA_CHECKS 29
7767
8076
  #define SQLITE_TESTCTRL_SEEK_COUNT 30
7768
- #define SQLITE_TESTCTRL_LAST 30 /* Largest TESTCTRL */
8077
+ #define SQLITE_TESTCTRL_TRACEFLAGS 31
8078
+ #define SQLITE_TESTCTRL_TUNE 32
8079
+ #define SQLITE_TESTCTRL_LOGEST 33
8080
+ #define SQLITE_TESTCTRL_LAST 33 /* Largest TESTCTRL */
7769
8081
 
7770
8082
  /*
7771
8083
  ** CAPI3REF: SQL Keyword Checking
@@ -8288,6 +8600,16 @@ SQLITE_API int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg);
8288
8600
  ** The counter is incremented on the first [sqlite3_step()] call of each
8289
8601
  ** cycle.
8290
8602
  **
8603
+ ** [[SQLITE_STMTSTATUS_FILTER_MISS]]
8604
+ ** [[SQLITE_STMTSTATUS_FILTER HIT]]
8605
+ ** <dt>SQLITE_STMTSTATUS_FILTER_HIT<br>
8606
+ ** SQLITE_STMTSTATUS_FILTER_MISS</dt>
8607
+ ** <dd>^SQLITE_STMTSTATUS_FILTER_HIT is the number of times that a join
8608
+ ** step was bypassed because a Bloom filter returned not-found. The
8609
+ ** corresponding SQLITE_STMTSTATUS_FILTER_MISS value is the number of
8610
+ ** times that the Bloom filter returned a find, and thus the join step
8611
+ ** had to be processed as normal.
8612
+ **
8291
8613
  ** [[SQLITE_STMTSTATUS_MEMUSED]] <dt>SQLITE_STMTSTATUS_MEMUSED</dt>
8292
8614
  ** <dd>^This is the approximate number of bytes of heap memory
8293
8615
  ** used to store the prepared statement. ^This value is not actually
@@ -8302,6 +8624,8 @@ SQLITE_API int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg);
8302
8624
  #define SQLITE_STMTSTATUS_VM_STEP 4
8303
8625
  #define SQLITE_STMTSTATUS_REPREPARE 5
8304
8626
  #define SQLITE_STMTSTATUS_RUN 6
8627
+ #define SQLITE_STMTSTATUS_FILTER_MISS 7
8628
+ #define SQLITE_STMTSTATUS_FILTER_HIT 8
8305
8629
  #define SQLITE_STMTSTATUS_MEMUSED 99
8306
8630
 
8307
8631
  /*
@@ -8713,7 +9037,7 @@ typedef struct sqlite3_backup sqlite3_backup;
8713
9037
  ** if the application incorrectly accesses the destination [database connection]
8714
9038
  ** and so no error code is reported, but the operations may malfunction
8715
9039
  ** nevertheless. Use of the destination database connection while a
8716
- ** backup is in progress might also also cause a mutex deadlock.
9040
+ ** backup is in progress might also cause a mutex deadlock.
8717
9041
  **
8718
9042
  ** If running in [shared cache mode], the application must
8719
9043
  ** guarantee that the shared cache used by the destination database
@@ -8965,8 +9289,9 @@ SQLITE_API void sqlite3_log(int iErrCode, const char *zFormat, ...);
8965
9289
  **
8966
9290
  ** A single database handle may have at most a single write-ahead log callback
8967
9291
  ** registered at one time. ^Calling [sqlite3_wal_hook()] replaces any
8968
- ** previously registered write-ahead log callback. ^Note that the
8969
- ** [sqlite3_wal_autocheckpoint()] interface and the
9292
+ ** previously registered write-ahead log callback. ^The return value is
9293
+ ** a copy of the third parameter from the previous call, if any, or 0.
9294
+ ** ^Note that the [sqlite3_wal_autocheckpoint()] interface and the
8970
9295
  ** [wal_autocheckpoint pragma] both invoke [sqlite3_wal_hook()] and will
8971
9296
  ** overwrite any prior [sqlite3_wal_hook()] settings.
8972
9297
  */
@@ -9140,7 +9465,7 @@ SQLITE_API int sqlite3_wal_checkpoint_v2(
9140
9465
  */
9141
9466
  #define SQLITE_CHECKPOINT_PASSIVE 0 /* Do as much as possible w/o blocking */
9142
9467
  #define SQLITE_CHECKPOINT_FULL 1 /* Wait for writers, then checkpoint */
9143
- #define SQLITE_CHECKPOINT_RESTART 2 /* Like FULL but wait for for readers */
9468
+ #define SQLITE_CHECKPOINT_RESTART 2 /* Like FULL but wait for readers */
9144
9469
  #define SQLITE_CHECKPOINT_TRUNCATE 3 /* Like RESTART but also truncate WAL */
9145
9470
 
9146
9471
  /*
@@ -9269,19 +9594,276 @@ SQLITE_API int sqlite3_vtab_nochange(sqlite3_context*);
9269
9594
 
9270
9595
  /*
9271
9596
  ** CAPI3REF: Determine The Collation For a Virtual Table Constraint
9597
+ ** METHOD: sqlite3_index_info
9272
9598
  **
9273
9599
  ** This function may only be called from within a call to the [xBestIndex]
9274
- ** method of a [virtual table].
9600
+ ** method of a [virtual table]. This function returns a pointer to a string
9601
+ ** that is the name of the appropriate collation sequence to use for text
9602
+ ** comparisons on the constraint identified by its arguments.
9603
+ **
9604
+ ** The first argument must be the pointer to the [sqlite3_index_info] object
9605
+ ** that is the first parameter to the xBestIndex() method. The second argument
9606
+ ** must be an index into the aConstraint[] array belonging to the
9607
+ ** sqlite3_index_info structure passed to xBestIndex.
9275
9608
  **
9276
- ** The first argument must be the sqlite3_index_info object that is the
9277
- ** first parameter to the xBestIndex() method. The second argument must be
9278
- ** an index into the aConstraint[] array belonging to the sqlite3_index_info
9279
- ** structure passed to xBestIndex. This function returns a pointer to a buffer
9280
- ** containing the name of the collation sequence for the corresponding
9281
- ** constraint.
9609
+ ** Important:
9610
+ ** The first parameter must be the same pointer that is passed into the
9611
+ ** xBestMethod() method. The first parameter may not be a pointer to a
9612
+ ** different [sqlite3_index_info] object, even an exact copy.
9613
+ **
9614
+ ** The return value is computed as follows:
9615
+ **
9616
+ ** <ol>
9617
+ ** <li><p> If the constraint comes from a WHERE clause expression that contains
9618
+ ** a [COLLATE operator], then the name of the collation specified by
9619
+ ** that COLLATE operator is returned.
9620
+ ** <li><p> If there is no COLLATE operator, but the column that is the subject
9621
+ ** of the constraint specifies an alternative collating sequence via
9622
+ ** a [COLLATE clause] on the column definition within the CREATE TABLE
9623
+ ** statement that was passed into [sqlite3_declare_vtab()], then the
9624
+ ** name of that alternative collating sequence is returned.
9625
+ ** <li><p> Otherwise, "BINARY" is returned.
9626
+ ** </ol>
9282
9627
  */
9283
9628
  SQLITE_API SQLITE_EXPERIMENTAL const char *sqlite3_vtab_collation(sqlite3_index_info*,int);
9284
9629
 
9630
+ /*
9631
+ ** CAPI3REF: Determine if a virtual table query is DISTINCT
9632
+ ** METHOD: sqlite3_index_info
9633
+ **
9634
+ ** This API may only be used from within an [xBestIndex|xBestIndex method]
9635
+ ** of a [virtual table] implementation. The result of calling this
9636
+ ** interface from outside of xBestIndex() is undefined and probably harmful.
9637
+ **
9638
+ ** ^The sqlite3_vtab_distinct() interface returns an integer between 0 and
9639
+ ** 3. The integer returned by sqlite3_vtab_distinct()
9640
+ ** gives the virtual table additional information about how the query
9641
+ ** planner wants the output to be ordered. As long as the virtual table
9642
+ ** can meet the ordering requirements of the query planner, it may set
9643
+ ** the "orderByConsumed" flag.
9644
+ **
9645
+ ** <ol><li value="0"><p>
9646
+ ** ^If the sqlite3_vtab_distinct() interface returns 0, that means
9647
+ ** that the query planner needs the virtual table to return all rows in the
9648
+ ** sort order defined by the "nOrderBy" and "aOrderBy" fields of the
9649
+ ** [sqlite3_index_info] object. This is the default expectation. If the
9650
+ ** virtual table outputs all rows in sorted order, then it is always safe for
9651
+ ** the xBestIndex method to set the "orderByConsumed" flag, regardless of
9652
+ ** the return value from sqlite3_vtab_distinct().
9653
+ ** <li value="1"><p>
9654
+ ** ^(If the sqlite3_vtab_distinct() interface returns 1, that means
9655
+ ** that the query planner does not need the rows to be returned in sorted order
9656
+ ** as long as all rows with the same values in all columns identified by the
9657
+ ** "aOrderBy" field are adjacent.)^ This mode is used when the query planner
9658
+ ** is doing a GROUP BY.
9659
+ ** <li value="2"><p>
9660
+ ** ^(If the sqlite3_vtab_distinct() interface returns 2, that means
9661
+ ** that the query planner does not need the rows returned in any particular
9662
+ ** order, as long as rows with the same values in all "aOrderBy" columns
9663
+ ** are adjacent.)^ ^(Furthermore, only a single row for each particular
9664
+ ** combination of values in the columns identified by the "aOrderBy" field
9665
+ ** needs to be returned.)^ ^It is always ok for two or more rows with the same
9666
+ ** values in all "aOrderBy" columns to be returned, as long as all such rows
9667
+ ** are adjacent. ^The virtual table may, if it chooses, omit extra rows
9668
+ ** that have the same value for all columns identified by "aOrderBy".
9669
+ ** ^However omitting the extra rows is optional.
9670
+ ** This mode is used for a DISTINCT query.
9671
+ ** <li value="3"><p>
9672
+ ** ^(If the sqlite3_vtab_distinct() interface returns 3, that means
9673
+ ** that the query planner needs only distinct rows but it does need the
9674
+ ** rows to be sorted.)^ ^The virtual table implementation is free to omit
9675
+ ** rows that are identical in all aOrderBy columns, if it wants to, but
9676
+ ** it is not required to omit any rows. This mode is used for queries
9677
+ ** that have both DISTINCT and ORDER BY clauses.
9678
+ ** </ol>
9679
+ **
9680
+ ** ^For the purposes of comparing virtual table output values to see if the
9681
+ ** values are same value for sorting purposes, two NULL values are considered
9682
+ ** to be the same. In other words, the comparison operator is "IS"
9683
+ ** (or "IS NOT DISTINCT FROM") and not "==".
9684
+ **
9685
+ ** If a virtual table implementation is unable to meet the requirements
9686
+ ** specified above, then it must not set the "orderByConsumed" flag in the
9687
+ ** [sqlite3_index_info] object or an incorrect answer may result.
9688
+ **
9689
+ ** ^A virtual table implementation is always free to return rows in any order
9690
+ ** it wants, as long as the "orderByConsumed" flag is not set. ^When the
9691
+ ** the "orderByConsumed" flag is unset, the query planner will add extra
9692
+ ** [bytecode] to ensure that the final results returned by the SQL query are
9693
+ ** ordered correctly. The use of the "orderByConsumed" flag and the
9694
+ ** sqlite3_vtab_distinct() interface is merely an optimization. ^Careful
9695
+ ** use of the sqlite3_vtab_distinct() interface and the "orderByConsumed"
9696
+ ** flag might help queries against a virtual table to run faster. Being
9697
+ ** overly aggressive and setting the "orderByConsumed" flag when it is not
9698
+ ** valid to do so, on the other hand, might cause SQLite to return incorrect
9699
+ ** results.
9700
+ */
9701
+ SQLITE_API int sqlite3_vtab_distinct(sqlite3_index_info*);
9702
+
9703
+ /*
9704
+ ** CAPI3REF: Identify and handle IN constraints in xBestIndex
9705
+ **
9706
+ ** This interface may only be used from within an
9707
+ ** [xBestIndex|xBestIndex() method] of a [virtual table] implementation.
9708
+ ** The result of invoking this interface from any other context is
9709
+ ** undefined and probably harmful.
9710
+ **
9711
+ ** ^(A constraint on a virtual table of the form
9712
+ ** "[IN operator|column IN (...)]" is
9713
+ ** communicated to the xBestIndex method as a
9714
+ ** [SQLITE_INDEX_CONSTRAINT_EQ] constraint.)^ If xBestIndex wants to use
9715
+ ** this constraint, it must set the corresponding
9716
+ ** aConstraintUsage[].argvIndex to a postive integer. ^(Then, under
9717
+ ** the usual mode of handling IN operators, SQLite generates [bytecode]
9718
+ ** that invokes the [xFilter|xFilter() method] once for each value
9719
+ ** on the right-hand side of the IN operator.)^ Thus the virtual table
9720
+ ** only sees a single value from the right-hand side of the IN operator
9721
+ ** at a time.
9722
+ **
9723
+ ** In some cases, however, it would be advantageous for the virtual
9724
+ ** table to see all values on the right-hand of the IN operator all at
9725
+ ** once. The sqlite3_vtab_in() interfaces facilitates this in two ways:
9726
+ **
9727
+ ** <ol>
9728
+ ** <li><p>
9729
+ ** ^A call to sqlite3_vtab_in(P,N,-1) will return true (non-zero)
9730
+ ** if and only if the [sqlite3_index_info|P->aConstraint][N] constraint
9731
+ ** is an [IN operator] that can be processed all at once. ^In other words,
9732
+ ** sqlite3_vtab_in() with -1 in the third argument is a mechanism
9733
+ ** by which the virtual table can ask SQLite if all-at-once processing
9734
+ ** of the IN operator is even possible.
9735
+ **
9736
+ ** <li><p>
9737
+ ** ^A call to sqlite3_vtab_in(P,N,F) with F==1 or F==0 indicates
9738
+ ** to SQLite that the virtual table does or does not want to process
9739
+ ** the IN operator all-at-once, respectively. ^Thus when the third
9740
+ ** parameter (F) is non-negative, this interface is the mechanism by
9741
+ ** which the virtual table tells SQLite how it wants to process the
9742
+ ** IN operator.
9743
+ ** </ol>
9744
+ **
9745
+ ** ^The sqlite3_vtab_in(P,N,F) interface can be invoked multiple times
9746
+ ** within the same xBestIndex method call. ^For any given P,N pair,
9747
+ ** the return value from sqlite3_vtab_in(P,N,F) will always be the same
9748
+ ** within the same xBestIndex call. ^If the interface returns true
9749
+ ** (non-zero), that means that the constraint is an IN operator
9750
+ ** that can be processed all-at-once. ^If the constraint is not an IN
9751
+ ** operator or cannot be processed all-at-once, then the interface returns
9752
+ ** false.
9753
+ **
9754
+ ** ^(All-at-once processing of the IN operator is selected if both of the
9755
+ ** following conditions are met:
9756
+ **
9757
+ ** <ol>
9758
+ ** <li><p> The P->aConstraintUsage[N].argvIndex value is set to a positive
9759
+ ** integer. This is how the virtual table tells SQLite that it wants to
9760
+ ** use the N-th constraint.
9761
+ **
9762
+ ** <li><p> The last call to sqlite3_vtab_in(P,N,F) for which F was
9763
+ ** non-negative had F>=1.
9764
+ ** </ol>)^
9765
+ **
9766
+ ** ^If either or both of the conditions above are false, then SQLite uses
9767
+ ** the traditional one-at-a-time processing strategy for the IN constraint.
9768
+ ** ^If both conditions are true, then the argvIndex-th parameter to the
9769
+ ** xFilter method will be an [sqlite3_value] that appears to be NULL,
9770
+ ** but which can be passed to [sqlite3_vtab_in_first()] and
9771
+ ** [sqlite3_vtab_in_next()] to find all values on the right-hand side
9772
+ ** of the IN constraint.
9773
+ */
9774
+ SQLITE_API int sqlite3_vtab_in(sqlite3_index_info*, int iCons, int bHandle);
9775
+
9776
+ /*
9777
+ ** CAPI3REF: Find all elements on the right-hand side of an IN constraint.
9778
+ **
9779
+ ** These interfaces are only useful from within the
9780
+ ** [xFilter|xFilter() method] of a [virtual table] implementation.
9781
+ ** The result of invoking these interfaces from any other context
9782
+ ** is undefined and probably harmful.
9783
+ **
9784
+ ** The X parameter in a call to sqlite3_vtab_in_first(X,P) or
9785
+ ** sqlite3_vtab_in_next(X,P) must be one of the parameters to the
9786
+ ** xFilter method which invokes these routines, and specifically
9787
+ ** a parameter that was previously selected for all-at-once IN constraint
9788
+ ** processing use the [sqlite3_vtab_in()] interface in the
9789
+ ** [xBestIndex|xBestIndex method]. ^(If the X parameter is not
9790
+ ** an xFilter argument that was selected for all-at-once IN constraint
9791
+ ** processing, then these routines return [SQLITE_MISUSE])^ or perhaps
9792
+ ** exhibit some other undefined or harmful behavior.
9793
+ **
9794
+ ** ^(Use these routines to access all values on the right-hand side
9795
+ ** of the IN constraint using code like the following:
9796
+ **
9797
+ ** <blockquote><pre>
9798
+ ** &nbsp; for(rc=sqlite3_vtab_in_first(pList, &pVal);
9799
+ ** &nbsp; rc==SQLITE_OK && pVal
9800
+ ** &nbsp; rc=sqlite3_vtab_in_next(pList, &pVal)
9801
+ ** &nbsp; ){
9802
+ ** &nbsp; // do something with pVal
9803
+ ** &nbsp; }
9804
+ ** &nbsp; if( rc!=SQLITE_OK ){
9805
+ ** &nbsp; // an error has occurred
9806
+ ** &nbsp; }
9807
+ ** </pre></blockquote>)^
9808
+ **
9809
+ ** ^On success, the sqlite3_vtab_in_first(X,P) and sqlite3_vtab_in_next(X,P)
9810
+ ** routines return SQLITE_OK and set *P to point to the first or next value
9811
+ ** on the RHS of the IN constraint. ^If there are no more values on the
9812
+ ** right hand side of the IN constraint, then *P is set to NULL and these
9813
+ ** routines return [SQLITE_DONE]. ^The return value might be
9814
+ ** some other value, such as SQLITE_NOMEM, in the event of a malfunction.
9815
+ **
9816
+ ** The *ppOut values returned by these routines are only valid until the
9817
+ ** next call to either of these routines or until the end of the xFilter
9818
+ ** method from which these routines were called. If the virtual table
9819
+ ** implementation needs to retain the *ppOut values for longer, it must make
9820
+ ** copies. The *ppOut values are [protected sqlite3_value|protected].
9821
+ */
9822
+ SQLITE_API int sqlite3_vtab_in_first(sqlite3_value *pVal, sqlite3_value **ppOut);
9823
+ SQLITE_API int sqlite3_vtab_in_next(sqlite3_value *pVal, sqlite3_value **ppOut);
9824
+
9825
+ /*
9826
+ ** CAPI3REF: Constraint values in xBestIndex()
9827
+ ** METHOD: sqlite3_index_info
9828
+ **
9829
+ ** This API may only be used from within the [xBestIndex|xBestIndex method]
9830
+ ** of a [virtual table] implementation. The result of calling this interface
9831
+ ** from outside of an xBestIndex method are undefined and probably harmful.
9832
+ **
9833
+ ** ^When the sqlite3_vtab_rhs_value(P,J,V) interface is invoked from within
9834
+ ** the [xBestIndex] method of a [virtual table] implementation, with P being
9835
+ ** a copy of the [sqlite3_index_info] object pointer passed into xBestIndex and
9836
+ ** J being a 0-based index into P->aConstraint[], then this routine
9837
+ ** attempts to set *V to the value of the right-hand operand of
9838
+ ** that constraint if the right-hand operand is known. ^If the
9839
+ ** right-hand operand is not known, then *V is set to a NULL pointer.
9840
+ ** ^The sqlite3_vtab_rhs_value(P,J,V) interface returns SQLITE_OK if
9841
+ ** and only if *V is set to a value. ^The sqlite3_vtab_rhs_value(P,J,V)
9842
+ ** inteface returns SQLITE_NOTFOUND if the right-hand side of the J-th
9843
+ ** constraint is not available. ^The sqlite3_vtab_rhs_value() interface
9844
+ ** can return an result code other than SQLITE_OK or SQLITE_NOTFOUND if
9845
+ ** something goes wrong.
9846
+ **
9847
+ ** The sqlite3_vtab_rhs_value() interface is usually only successful if
9848
+ ** the right-hand operand of a constraint is a literal value in the original
9849
+ ** SQL statement. If the right-hand operand is an expression or a reference
9850
+ ** to some other column or a [host parameter], then sqlite3_vtab_rhs_value()
9851
+ ** will probably return [SQLITE_NOTFOUND].
9852
+ **
9853
+ ** ^(Some constraints, such as [SQLITE_INDEX_CONSTRAINT_ISNULL] and
9854
+ ** [SQLITE_INDEX_CONSTRAINT_ISNOTNULL], have no right-hand operand. For such
9855
+ ** constraints, sqlite3_vtab_rhs_value() always returns SQLITE_NOTFOUND.)^
9856
+ **
9857
+ ** ^The [sqlite3_value] object returned in *V is a protected sqlite3_value
9858
+ ** and remains valid for the duration of the xBestIndex method call.
9859
+ ** ^When xBestIndex returns, the sqlite3_value object returned by
9860
+ ** sqlite3_vtab_rhs_value() is automatically deallocated.
9861
+ **
9862
+ ** The "_rhs_" in the name of this routine is an abbreviation for
9863
+ ** "Right-Hand Side".
9864
+ */
9865
+ SQLITE_API int sqlite3_vtab_rhs_value(sqlite3_index_info*, int, sqlite3_value **ppVal);
9866
+
9285
9867
  /*
9286
9868
  ** CAPI3REF: Conflict resolution modes
9287
9869
  ** KEYWORDS: {conflict resolution mode}
@@ -9517,6 +10099,15 @@ SQLITE_API int sqlite3_db_cacheflush(sqlite3*);
9517
10099
  ** triggers; or 2 for changes resulting from triggers called by top-level
9518
10100
  ** triggers; and so forth.
9519
10101
  **
10102
+ ** When the [sqlite3_blob_write()] API is used to update a blob column,
10103
+ ** the pre-update hook is invoked with SQLITE_DELETE. This is because the
10104
+ ** in this case the new values are not available. In this case, when a
10105
+ ** callback made with op==SQLITE_DELETE is actuall a write using the
10106
+ ** sqlite3_blob_write() API, the [sqlite3_preupdate_blobwrite()] returns
10107
+ ** the index of the column being written. In other cases, where the
10108
+ ** pre-update hook is being invoked for some other reason, including a
10109
+ ** regular DELETE, sqlite3_preupdate_blobwrite() returns -1.
10110
+ **
9520
10111
  ** See also: [sqlite3_update_hook()]
9521
10112
  */
9522
10113
  #if defined(SQLITE_ENABLE_PREUPDATE_HOOK)
@@ -9537,6 +10128,7 @@ SQLITE_API int sqlite3_preupdate_old(sqlite3 *, int, sqlite3_value **);
9537
10128
  SQLITE_API int sqlite3_preupdate_count(sqlite3 *);
9538
10129
  SQLITE_API int sqlite3_preupdate_depth(sqlite3 *);
9539
10130
  SQLITE_API int sqlite3_preupdate_new(sqlite3 *, int, sqlite3_value **);
10131
+ SQLITE_API int sqlite3_preupdate_blobwrite(sqlite3 *);
9540
10132
  #endif
9541
10133
 
9542
10134
  /*
@@ -9775,8 +10367,8 @@ SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_recover(sqlite3 *db, const c
9775
10367
  ** SQLITE_SERIALIZE_NOCOPY bit is omitted from argument F if a memory
9776
10368
  ** allocation error occurs.
9777
10369
  **
9778
- ** This interface is only available if SQLite is compiled with the
9779
- ** [SQLITE_ENABLE_DESERIALIZE] option.
10370
+ ** This interface is omitted if SQLite is compiled with the
10371
+ ** [SQLITE_OMIT_DESERIALIZE] option.
9780
10372
  */
9781
10373
  SQLITE_API unsigned char *sqlite3_serialize(
9782
10374
  sqlite3 *db, /* The database connection */
@@ -9823,12 +10415,16 @@ SQLITE_API unsigned char *sqlite3_serialize(
9823
10415
  ** database is currently in a read transaction or is involved in a backup
9824
10416
  ** operation.
9825
10417
  **
10418
+ ** It is not possible to deserialized into the TEMP database. If the
10419
+ ** S argument to sqlite3_deserialize(D,S,P,N,M,F) is "temp" then the
10420
+ ** function returns SQLITE_ERROR.
10421
+ **
9826
10422
  ** If sqlite3_deserialize(D,S,P,N,M,F) fails for any reason and if the
9827
10423
  ** SQLITE_DESERIALIZE_FREEONCLOSE bit is set in argument F, then
9828
10424
  ** [sqlite3_free()] is invoked on argument P prior to returning.
9829
10425
  **
9830
- ** This interface is only available if SQLite is compiled with the
9831
- ** [SQLITE_ENABLE_DESERIALIZE] option.
10426
+ ** This interface is omitted if SQLite is compiled with the
10427
+ ** [SQLITE_OMIT_DESERIALIZE] option.
9832
10428
  */
9833
10429
  SQLITE_API int sqlite3_deserialize(
9834
10430
  sqlite3 *db, /* The database connection */
@@ -10077,6 +10673,38 @@ SQLITE_API int sqlite3session_create(
10077
10673
  */
10078
10674
  SQLITE_API void sqlite3session_delete(sqlite3_session *pSession);
10079
10675
 
10676
+ /*
10677
+ ** CAPIREF: Conigure a Session Object
10678
+ ** METHOD: sqlite3_session
10679
+ **
10680
+ ** This method is used to configure a session object after it has been
10681
+ ** created. At present the only valid value for the second parameter is
10682
+ ** [SQLITE_SESSION_OBJCONFIG_SIZE].
10683
+ **
10684
+ ** Arguments for sqlite3session_object_config()
10685
+ **
10686
+ ** The following values may passed as the the 4th parameter to
10687
+ ** sqlite3session_object_config().
10688
+ **
10689
+ ** <dt>SQLITE_SESSION_OBJCONFIG_SIZE <dd>
10690
+ ** This option is used to set, clear or query the flag that enables
10691
+ ** the [sqlite3session_changeset_size()] API. Because it imposes some
10692
+ ** computational overhead, this API is disabled by default. Argument
10693
+ ** pArg must point to a value of type (int). If the value is initially
10694
+ ** 0, then the sqlite3session_changeset_size() API is disabled. If it
10695
+ ** is greater than 0, then the same API is enabled. Or, if the initial
10696
+ ** value is less than zero, no change is made. In all cases the (int)
10697
+ ** variable is set to 1 if the sqlite3session_changeset_size() API is
10698
+ ** enabled following the current call, or 0 otherwise.
10699
+ **
10700
+ ** It is an error (SQLITE_MISUSE) to attempt to modify this setting after
10701
+ ** the first table has been attached to the session object.
10702
+ */
10703
+ SQLITE_API int sqlite3session_object_config(sqlite3_session*, int op, void *pArg);
10704
+
10705
+ /*
10706
+ */
10707
+ #define SQLITE_SESSION_OBJCONFIG_SIZE 1
10080
10708
 
10081
10709
  /*
10082
10710
  ** CAPI3REF: Enable Or Disable A Session Object
@@ -10321,6 +10949,22 @@ SQLITE_API int sqlite3session_changeset(
10321
10949
  void **ppChangeset /* OUT: Buffer containing changeset */
10322
10950
  );
10323
10951
 
10952
+ /*
10953
+ ** CAPI3REF: Return An Upper-limit For The Size Of The Changeset
10954
+ ** METHOD: sqlite3_session
10955
+ **
10956
+ ** By default, this function always returns 0. For it to return
10957
+ ** a useful result, the sqlite3_session object must have been configured
10958
+ ** to enable this API using sqlite3session_object_config() with the
10959
+ ** SQLITE_SESSION_OBJCONFIG_SIZE verb.
10960
+ **
10961
+ ** When enabled, this function returns an upper limit, in bytes, for the size
10962
+ ** of the changeset that might be produced if sqlite3session_changeset() were
10963
+ ** called. The final changeset size might be equal to or smaller than the
10964
+ ** size in bytes returned by this function.
10965
+ */
10966
+ SQLITE_API sqlite3_int64 sqlite3session_changeset_size(sqlite3_session *pSession);
10967
+
10324
10968
  /*
10325
10969
  ** CAPI3REF: Load The Difference Between Tables Into A Session
10326
10970
  ** METHOD: sqlite3_session
@@ -10438,6 +11082,14 @@ SQLITE_API int sqlite3session_patchset(
10438
11082
  */
10439
11083
  SQLITE_API int sqlite3session_isempty(sqlite3_session *pSession);
10440
11084
 
11085
+ /*
11086
+ ** CAPI3REF: Query for the amount of heap memory used by a session object.
11087
+ **
11088
+ ** This API returns the total amount of heap memory in bytes currently
11089
+ ** used by the session object passed as the only argument.
11090
+ */
11091
+ SQLITE_API sqlite3_int64 sqlite3session_memory_used(sqlite3_session *pSession);
11092
+
10441
11093
  /*
10442
11094
  ** CAPI3REF: Create An Iterator To Traverse A Changeset
10443
11095
  ** CONSTRUCTOR: sqlite3_changeset_iter
@@ -10540,18 +11192,23 @@ SQLITE_API int sqlite3changeset_next(sqlite3_changeset_iter *pIter);
10540
11192
  ** call to [sqlite3changeset_next()] must have returned [SQLITE_ROW]. If this
10541
11193
  ** is not the case, this function returns [SQLITE_MISUSE].
10542
11194
  **
10543
- ** If argument pzTab is not NULL, then *pzTab is set to point to a
10544
- ** nul-terminated utf-8 encoded string containing the name of the table
10545
- ** affected by the current change. The buffer remains valid until either
10546
- ** sqlite3changeset_next() is called on the iterator or until the
10547
- ** conflict-handler function returns. If pnCol is not NULL, then *pnCol is
10548
- ** set to the number of columns in the table affected by the change. If
10549
- ** pbIndirect is not NULL, then *pbIndirect is set to true (1) if the change
11195
+ ** Arguments pOp, pnCol and pzTab may not be NULL. Upon return, three
11196
+ ** outputs are set through these pointers:
11197
+ **
11198
+ ** *pOp is set to one of [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE],
11199
+ ** depending on the type of change that the iterator currently points to;
11200
+ **
11201
+ ** *pnCol is set to the number of columns in the table affected by the change; and
11202
+ **
11203
+ ** *pzTab is set to point to a nul-terminated utf-8 encoded string containing
11204
+ ** the name of the table affected by the current change. The buffer remains
11205
+ ** valid until either sqlite3changeset_next() is called on the iterator
11206
+ ** or until the conflict-handler function returns.
11207
+ **
11208
+ ** If pbIndirect is not NULL, then *pbIndirect is set to true (1) if the change
10550
11209
  ** is an indirect change, or false (0) otherwise. See the documentation for
10551
11210
  ** [sqlite3session_indirect()] for a description of direct and indirect
10552
- ** changes. Finally, if pOp is not NULL, then *pOp is set to one of
10553
- ** [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE], depending on the
10554
- ** type of change that the iterator currently points to.
11211
+ ** changes.
10555
11212
  **
10556
11213
  ** If no error occurs, SQLITE_OK is returned. If an error does occur, an
10557
11214
  ** SQLite error code is returned. The values of the output variables may not