OLD | NEW |
1 /* | 1 /* |
2 ** 2001 September 15 | 2 ** 2001 September 15 |
3 ** | 3 ** |
4 ** The author disclaims copyright to this source code. In place of | 4 ** The author disclaims copyright to this source code. In place of |
5 ** a legal notice, here is a blessing: | 5 ** a legal notice, here is a blessing: |
6 ** | 6 ** |
7 ** May you do good and not evil. | 7 ** May you do good and not evil. |
8 ** May you find forgiveness for yourself and forgive others. | 8 ** May you find forgiveness for yourself and forgive others. |
9 ** May you share freely, never taking more than you give. | 9 ** May you share freely, never taking more than you give. |
10 ** | 10 ** |
(...skipping 12 matching lines...) Expand all Loading... |
23 ** | 23 ** |
24 ** The official C-language API documentation for SQLite is derived | 24 ** The official C-language API documentation for SQLite is derived |
25 ** from comments in this file. This file is the authoritative source | 25 ** from comments in this file. This file is the authoritative source |
26 ** on how SQLite interfaces are supposed to operate. | 26 ** on how SQLite interfaces are supposed to operate. |
27 ** | 27 ** |
28 ** The name of this file under configuration management is "sqlite.h.in". | 28 ** The name of this file under configuration management is "sqlite.h.in". |
29 ** The makefile makes some minor changes to this file (such as inserting | 29 ** The makefile makes some minor changes to this file (such as inserting |
30 ** the version number) and changes its name to "sqlite3.h" as | 30 ** the version number) and changes its name to "sqlite3.h" as |
31 ** part of the build process. | 31 ** part of the build process. |
32 */ | 32 */ |
33 #ifndef _SQLITE3_H_ | 33 #ifndef SQLITE3_H |
34 #define _SQLITE3_H_ | 34 #define SQLITE3_H |
35 #include <stdarg.h> /* Needed for the definition of va_list */ | 35 #include <stdarg.h> /* Needed for the definition of va_list */ |
36 | 36 |
37 /* | 37 /* |
38 ** Make sure we can call this stuff from C++. | 38 ** Make sure we can call this stuff from C++. |
39 */ | 39 */ |
40 #ifdef __cplusplus | 40 #ifdef __cplusplus |
41 extern "C" { | 41 extern "C" { |
42 #endif | 42 #endif |
43 | 43 |
44 | 44 |
45 /* | 45 /* |
46 ** Provide the ability to override linkage features of the interface. | 46 ** Provide the ability to override linkage features of the interface. |
47 */ | 47 */ |
48 #ifndef SQLITE_EXTERN | 48 #ifndef SQLITE_EXTERN |
49 # define SQLITE_EXTERN extern | 49 # define SQLITE_EXTERN extern |
50 #endif | 50 #endif |
51 #ifndef SQLITE_API | 51 #ifndef SQLITE_API |
52 # define SQLITE_API | 52 # define SQLITE_API |
53 #endif | 53 #endif |
54 #ifndef SQLITE_CDECL | 54 #ifndef SQLITE_CDECL |
55 # define SQLITE_CDECL | 55 # define SQLITE_CDECL |
56 #endif | 56 #endif |
| 57 #ifndef SQLITE_APICALL |
| 58 # define SQLITE_APICALL |
| 59 #endif |
57 #ifndef SQLITE_STDCALL | 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 #endif | 68 #endif |
60 | 69 |
61 /* | 70 /* |
62 ** These no-op macros are used in front of interfaces to mark those | 71 ** These no-op macros are used in front of interfaces to mark those |
63 ** interfaces as either deprecated or experimental. New applications | 72 ** interfaces as either deprecated or experimental. New applications |
64 ** should not use deprecated interfaces - they are supported for backwards | 73 ** should not use deprecated interfaces - they are supported for backwards |
65 ** compatibility only. Application writers should be aware that | 74 ** compatibility only. Application writers should be aware that |
66 ** experimental interfaces are subject to change in point releases. | 75 ** experimental interfaces are subject to change in point releases. |
67 ** | 76 ** |
68 ** These macros used to resolve to various kinds of compiler magic that | 77 ** These macros used to resolve to various kinds of compiler magic that |
(...skipping 23 matching lines...) Expand all Loading... |
92 ** format "X.Y.Z" where X is the major version number (always 3 for | 101 ** format "X.Y.Z" where X is the major version number (always 3 for |
93 ** SQLite3) and Y is the minor version number and Z is the release number.)^ | 102 ** SQLite3) and Y is the minor version number and Z is the release number.)^ |
94 ** ^(The [SQLITE_VERSION_NUMBER] C preprocessor macro resolves to an integer | 103 ** ^(The [SQLITE_VERSION_NUMBER] C preprocessor macro resolves to an integer |
95 ** with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z are the same | 104 ** with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z are the same |
96 ** numbers used in [SQLITE_VERSION].)^ | 105 ** numbers used in [SQLITE_VERSION].)^ |
97 ** The SQLITE_VERSION_NUMBER for any given release of SQLite will also | 106 ** The SQLITE_VERSION_NUMBER for any given release of SQLite will also |
98 ** be larger than the release from which it is derived. Either Y will | 107 ** be larger than the release from which it is derived. Either Y will |
99 ** be held constant and Z will be incremented or else Y will be incremented | 108 ** be held constant and Z will be incremented or else Y will be incremented |
100 ** and Z will be reset to zero. | 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 ** <a href="http://www.fossil-scm.org/">Fossil configuration management | 113 ** <a href="http://www.fossil-scm.org/">Fossil configuration management |
104 ** system</a>. ^The SQLITE_SOURCE_ID macro evaluates to | 114 ** system</a>. ^The SQLITE_SOURCE_ID macro evaluates to |
105 ** a string which identifies a particular check-in of SQLite | 115 ** a string which identifies a particular check-in of SQLite |
106 ** within its configuration management system. ^The SQLITE_SOURCE_ID | 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 | 117 ** string contains the date and time of the check-in (UTC) and an SHA1 |
108 ** hash of the entire source tree. | 118 ** hash of the entire source tree. |
109 ** | 119 ** |
110 ** See also: [sqlite3_libversion()], | 120 ** See also: [sqlite3_libversion()], |
111 ** [sqlite3_libversion_number()], [sqlite3_sourceid()], | 121 ** [sqlite3_libversion_number()], [sqlite3_sourceid()], |
112 ** [sqlite_version()] and [sqlite_source_id()]. | 122 ** [sqlite_version()] and [sqlite_source_id()]. |
113 */ | 123 */ |
114 #define SQLITE_VERSION "3.10.2" | 124 #define SQLITE_VERSION "3.17.0" |
115 #define SQLITE_VERSION_NUMBER 3010002 | 125 #define SQLITE_VERSION_NUMBER 3017000 |
116 #define SQLITE_SOURCE_ID "2016-01-20 15:27:19 17efb4209f97fb4971656086b1385
99a91a75ff9" | 126 #define SQLITE_SOURCE_ID "2017-02-13 16:02:40 ada05cfa86ad7f5645450ac7a2a21
c9aa6e57d2c" |
117 | 127 |
118 /* | 128 /* |
119 ** CAPI3REF: Run-Time Library Version Numbers | 129 ** CAPI3REF: Run-Time Library Version Numbers |
120 ** KEYWORDS: sqlite3_version, sqlite3_sourceid | 130 ** KEYWORDS: sqlite3_version sqlite3_sourceid |
121 ** | 131 ** |
122 ** These interfaces provide the same information as the [SQLITE_VERSION], | 132 ** These interfaces provide the same information as the [SQLITE_VERSION], |
123 ** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] C preprocessor macros | 133 ** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] C preprocessor macros |
124 ** but are associated with the library instead of the header file. ^(Cautious | 134 ** but are associated with the library instead of the header file. ^(Cautious |
125 ** programmers might include assert() statements in their application to | 135 ** programmers might include assert() statements in their application to |
126 ** verify that values returned by these interfaces match the macros in | 136 ** verify that values returned by these interfaces match the macros in |
127 ** the header, and thus ensure that the application is | 137 ** the header, and thus ensure that the application is |
128 ** compiled with matching library and header files. | 138 ** compiled with matching library and header files. |
129 ** | 139 ** |
130 ** <blockquote><pre> | 140 ** <blockquote><pre> |
131 ** assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER ); | 141 ** assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER ); |
132 ** assert( strcmp(sqlite3_sourceid(),SQLITE_SOURCE_ID)==0 ); | 142 ** assert( strcmp(sqlite3_sourceid(),SQLITE_SOURCE_ID)==0 ); |
133 ** assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 ); | 143 ** assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 ); |
134 ** </pre></blockquote>)^ | 144 ** </pre></blockquote>)^ |
135 ** | 145 ** |
136 ** ^The sqlite3_version[] string constant contains the text of [SQLITE_VERSION] | 146 ** ^The sqlite3_version[] string constant contains the text of [SQLITE_VERSION] |
137 ** macro. ^The sqlite3_libversion() function returns a pointer to the | 147 ** macro. ^The sqlite3_libversion() function returns a pointer to the |
138 ** to the sqlite3_version[] string constant. The sqlite3_libversion() | 148 ** to the sqlite3_version[] string constant. The sqlite3_libversion() |
139 ** function is provided for use in DLLs since DLL users usually do not have | 149 ** function is provided for use in DLLs since DLL users usually do not have |
140 ** direct access to string constants within the DLL. ^The | 150 ** direct access to string constants within the DLL. ^The |
141 ** sqlite3_libversion_number() function returns an integer equal to | 151 ** sqlite3_libversion_number() function returns an integer equal to |
142 ** [SQLITE_VERSION_NUMBER]. ^The sqlite3_sourceid() function returns | 152 ** [SQLITE_VERSION_NUMBER]. ^The sqlite3_sourceid() function returns |
143 ** a pointer to a string constant whose value is the same as the | 153 ** a pointer to a string constant whose value is the same as the |
144 ** [SQLITE_SOURCE_ID] C preprocessor macro. | 154 ** [SQLITE_SOURCE_ID] C preprocessor macro. |
145 ** | 155 ** |
146 ** See also: [sqlite_version()] and [sqlite_source_id()]. | 156 ** See also: [sqlite_version()] and [sqlite_source_id()]. |
147 */ | 157 */ |
148 SQLITE_API SQLITE_EXTERN const char sqlite3_version[]; | 158 SQLITE_API SQLITE_EXTERN const char sqlite3_version[]; |
149 SQLITE_API const char *SQLITE_STDCALL sqlite3_libversion(void); | 159 SQLITE_API const char *sqlite3_libversion(void); |
150 SQLITE_API const char *SQLITE_STDCALL sqlite3_sourceid(void); | 160 SQLITE_API const char *sqlite3_sourceid(void); |
151 SQLITE_API int SQLITE_STDCALL sqlite3_libversion_number(void); | 161 SQLITE_API int sqlite3_libversion_number(void); |
152 | 162 |
153 /* | 163 /* |
154 ** CAPI3REF: Run-Time Library Compilation Options Diagnostics | 164 ** CAPI3REF: Run-Time Library Compilation Options Diagnostics |
155 ** | 165 ** |
156 ** ^The sqlite3_compileoption_used() function returns 0 or 1 | 166 ** ^The sqlite3_compileoption_used() function returns 0 or 1 |
157 ** indicating whether the specified option was defined at | 167 ** indicating whether the specified option was defined at |
158 ** compile time. ^The SQLITE_ prefix may be omitted from the | 168 ** compile time. ^The SQLITE_ prefix may be omitted from the |
159 ** option name passed to sqlite3_compileoption_used(). | 169 ** option name passed to sqlite3_compileoption_used(). |
160 ** | 170 ** |
161 ** ^The sqlite3_compileoption_get() function allows iterating | 171 ** ^The sqlite3_compileoption_get() function allows iterating |
162 ** over the list of options that were defined at compile time by | 172 ** over the list of options that were defined at compile time by |
163 ** returning the N-th compile time option string. ^If N is out of range, | 173 ** returning the N-th compile time option string. ^If N is out of range, |
164 ** sqlite3_compileoption_get() returns a NULL pointer. ^The SQLITE_ | 174 ** sqlite3_compileoption_get() returns a NULL pointer. ^The SQLITE_ |
165 ** prefix is omitted from any strings returned by | 175 ** prefix is omitted from any strings returned by |
166 ** sqlite3_compileoption_get(). | 176 ** sqlite3_compileoption_get(). |
167 ** | 177 ** |
168 ** ^Support for the diagnostic functions sqlite3_compileoption_used() | 178 ** ^Support for the diagnostic functions sqlite3_compileoption_used() |
169 ** and sqlite3_compileoption_get() may be omitted by specifying the | 179 ** and sqlite3_compileoption_get() may be omitted by specifying the |
170 ** [SQLITE_OMIT_COMPILEOPTION_DIAGS] option at compile time. | 180 ** [SQLITE_OMIT_COMPILEOPTION_DIAGS] option at compile time. |
171 ** | 181 ** |
172 ** See also: SQL functions [sqlite_compileoption_used()] and | 182 ** See also: SQL functions [sqlite_compileoption_used()] and |
173 ** [sqlite_compileoption_get()] and the [compile_options pragma]. | 183 ** [sqlite_compileoption_get()] and the [compile_options pragma]. |
174 */ | 184 */ |
175 #ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS | 185 #ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS |
176 SQLITE_API int SQLITE_STDCALL sqlite3_compileoption_used(const char *zOptName); | 186 SQLITE_API int sqlite3_compileoption_used(const char *zOptName); |
177 SQLITE_API const char *SQLITE_STDCALL sqlite3_compileoption_get(int N); | 187 SQLITE_API const char *sqlite3_compileoption_get(int N); |
178 #endif | 188 #endif |
179 | 189 |
180 /* | 190 /* |
181 ** CAPI3REF: Test To See If The Library Is Threadsafe | 191 ** CAPI3REF: Test To See If The Library Is Threadsafe |
182 ** | 192 ** |
183 ** ^The sqlite3_threadsafe() function returns zero if and only if | 193 ** ^The sqlite3_threadsafe() function returns zero if and only if |
184 ** SQLite was compiled with mutexing code omitted due to the | 194 ** SQLite was compiled with mutexing code omitted due to the |
185 ** [SQLITE_THREADSAFE] compile-time option being set to 0. | 195 ** [SQLITE_THREADSAFE] compile-time option being set to 0. |
186 ** | 196 ** |
187 ** SQLite can be compiled with or without mutexes. When | 197 ** SQLite can be compiled with or without mutexes. When |
(...skipping 18 matching lines...) Expand all Loading... |
206 ** can be fully or partially disabled using a call to [sqlite3_config()] | 216 ** can be fully or partially disabled using a call to [sqlite3_config()] |
207 ** with the verbs [SQLITE_CONFIG_SINGLETHREAD], [SQLITE_CONFIG_MULTITHREAD], | 217 ** with the verbs [SQLITE_CONFIG_SINGLETHREAD], [SQLITE_CONFIG_MULTITHREAD], |
208 ** or [SQLITE_CONFIG_SERIALIZED]. ^(The return value of the | 218 ** or [SQLITE_CONFIG_SERIALIZED]. ^(The return value of the |
209 ** sqlite3_threadsafe() function shows only the compile-time setting of | 219 ** sqlite3_threadsafe() function shows only the compile-time setting of |
210 ** thread safety, not any run-time changes to that setting made by | 220 ** thread safety, not any run-time changes to that setting made by |
211 ** sqlite3_config(). In other words, the return value from sqlite3_threadsafe() | 221 ** sqlite3_config(). In other words, the return value from sqlite3_threadsafe() |
212 ** is unchanged by calls to sqlite3_config().)^ | 222 ** is unchanged by calls to sqlite3_config().)^ |
213 ** | 223 ** |
214 ** See the [threading mode] documentation for additional information. | 224 ** See the [threading mode] documentation for additional information. |
215 */ | 225 */ |
216 SQLITE_API int SQLITE_STDCALL sqlite3_threadsafe(void); | 226 SQLITE_API int sqlite3_threadsafe(void); |
217 | 227 |
218 /* | 228 /* |
219 ** CAPI3REF: Database Connection Handle | 229 ** CAPI3REF: Database Connection Handle |
220 ** KEYWORDS: {database connection} {database connections} | 230 ** KEYWORDS: {database connection} {database connections} |
221 ** | 231 ** |
222 ** Each open SQLite database is represented by a pointer to an instance of | 232 ** Each open SQLite database is represented by a pointer to an instance of |
223 ** the opaque structure named "sqlite3". It is useful to think of an sqlite3 | 233 ** the opaque structure named "sqlite3". It is useful to think of an sqlite3 |
224 ** pointer as an object. The [sqlite3_open()], [sqlite3_open16()], and | 234 ** pointer as an object. The [sqlite3_open()], [sqlite3_open16()], and |
225 ** [sqlite3_open_v2()] interfaces are its constructors, and [sqlite3_close()] | 235 ** [sqlite3_open_v2()] interfaces are its constructors, and [sqlite3_close()] |
226 ** and [sqlite3_close_v2()] are its destructors. There are many other | 236 ** and [sqlite3_close_v2()] are its destructors. There are many other |
(...skipping 15 matching lines...) Expand all Loading... |
242 ** The sqlite_int64 and sqlite_uint64 types are supported for backwards | 252 ** The sqlite_int64 and sqlite_uint64 types are supported for backwards |
243 ** compatibility only. | 253 ** compatibility only. |
244 ** | 254 ** |
245 ** ^The sqlite3_int64 and sqlite_int64 types can store integer values | 255 ** ^The sqlite3_int64 and sqlite_int64 types can store integer values |
246 ** between -9223372036854775808 and +9223372036854775807 inclusive. ^The | 256 ** between -9223372036854775808 and +9223372036854775807 inclusive. ^The |
247 ** sqlite3_uint64 and sqlite_uint64 types can store integer values | 257 ** sqlite3_uint64 and sqlite_uint64 types can store integer values |
248 ** between 0 and +18446744073709551615 inclusive. | 258 ** between 0 and +18446744073709551615 inclusive. |
249 */ | 259 */ |
250 #ifdef SQLITE_INT64_TYPE | 260 #ifdef SQLITE_INT64_TYPE |
251 typedef SQLITE_INT64_TYPE sqlite_int64; | 261 typedef SQLITE_INT64_TYPE sqlite_int64; |
252 typedef unsigned SQLITE_INT64_TYPE sqlite_uint64; | 262 # ifdef SQLITE_UINT64_TYPE |
| 263 typedef SQLITE_UINT64_TYPE sqlite_uint64; |
| 264 # else |
| 265 typedef unsigned SQLITE_INT64_TYPE sqlite_uint64; |
| 266 # endif |
253 #elif defined(_MSC_VER) || defined(__BORLANDC__) | 267 #elif defined(_MSC_VER) || defined(__BORLANDC__) |
254 typedef __int64 sqlite_int64; | 268 typedef __int64 sqlite_int64; |
255 typedef unsigned __int64 sqlite_uint64; | 269 typedef unsigned __int64 sqlite_uint64; |
256 #else | 270 #else |
257 typedef long long int sqlite_int64; | 271 typedef long long int sqlite_int64; |
258 typedef unsigned long long int sqlite_uint64; | 272 typedef unsigned long long int sqlite_uint64; |
259 #endif | 273 #endif |
260 typedef sqlite_int64 sqlite3_int64; | 274 typedef sqlite_int64 sqlite3_int64; |
261 typedef sqlite_uint64 sqlite3_uint64; | 275 typedef sqlite_uint64 sqlite3_uint64; |
262 | 276 |
(...skipping 40 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
303 ** the transaction is automatically rolled back. | 317 ** the transaction is automatically rolled back. |
304 ** | 318 ** |
305 ** The C parameter to [sqlite3_close(C)] and [sqlite3_close_v2(C)] | 319 ** The C parameter to [sqlite3_close(C)] and [sqlite3_close_v2(C)] |
306 ** must be either a NULL | 320 ** must be either a NULL |
307 ** pointer or an [sqlite3] object pointer obtained | 321 ** pointer or an [sqlite3] object pointer obtained |
308 ** from [sqlite3_open()], [sqlite3_open16()], or | 322 ** from [sqlite3_open()], [sqlite3_open16()], or |
309 ** [sqlite3_open_v2()], and not previously closed. | 323 ** [sqlite3_open_v2()], and not previously closed. |
310 ** ^Calling sqlite3_close() or sqlite3_close_v2() with a NULL pointer | 324 ** ^Calling sqlite3_close() or sqlite3_close_v2() with a NULL pointer |
311 ** argument is a harmless no-op. | 325 ** argument is a harmless no-op. |
312 */ | 326 */ |
313 SQLITE_API int SQLITE_STDCALL sqlite3_close(sqlite3*); | 327 SQLITE_API int sqlite3_close(sqlite3*); |
314 SQLITE_API int SQLITE_STDCALL sqlite3_close_v2(sqlite3*); | 328 SQLITE_API int sqlite3_close_v2(sqlite3*); |
315 | 329 |
316 /* | 330 /* |
317 ** The type for a callback function. | 331 ** The type for a callback function. |
318 ** This is legacy and deprecated. It is included for historical | 332 ** This is legacy and deprecated. It is included for historical |
319 ** compatibility and is not documented. | 333 ** compatibility and is not documented. |
320 */ | 334 */ |
321 typedef int (*sqlite3_callback)(void*,int,char**, char**); | 335 typedef int (*sqlite3_callback)(void*,int,char**, char**); |
322 | 336 |
323 /* | 337 /* |
324 ** CAPI3REF: One-Step Query Execution Interface | 338 ** CAPI3REF: One-Step Query Execution Interface |
(...skipping 15 matching lines...) Expand all Loading... |
340 ** is NULL, then no callback is ever invoked and result rows are | 354 ** is NULL, then no callback is ever invoked and result rows are |
341 ** ignored. | 355 ** ignored. |
342 ** | 356 ** |
343 ** ^If an error occurs while evaluating the SQL statements passed into | 357 ** ^If an error occurs while evaluating the SQL statements passed into |
344 ** sqlite3_exec(), then execution of the current statement stops and | 358 ** sqlite3_exec(), then execution of the current statement stops and |
345 ** subsequent statements are skipped. ^If the 5th parameter to sqlite3_exec() | 359 ** subsequent statements are skipped. ^If the 5th parameter to sqlite3_exec() |
346 ** is not NULL then any error message is written into memory obtained | 360 ** is not NULL then any error message is written into memory obtained |
347 ** from [sqlite3_malloc()] and passed back through the 5th parameter. | 361 ** from [sqlite3_malloc()] and passed back through the 5th parameter. |
348 ** To avoid memory leaks, the application should invoke [sqlite3_free()] | 362 ** To avoid memory leaks, the application should invoke [sqlite3_free()] |
349 ** on error message strings returned through the 5th parameter of | 363 ** on error message strings returned through the 5th parameter of |
350 ** of sqlite3_exec() after the error message string is no longer needed. | 364 ** sqlite3_exec() after the error message string is no longer needed. |
351 ** ^If the 5th parameter to sqlite3_exec() is not NULL and no errors | 365 ** ^If the 5th parameter to sqlite3_exec() is not NULL and no errors |
352 ** occur, then sqlite3_exec() sets the pointer in its 5th parameter to | 366 ** occur, then sqlite3_exec() sets the pointer in its 5th parameter to |
353 ** NULL before returning. | 367 ** NULL before returning. |
354 ** | 368 ** |
355 ** ^If an sqlite3_exec() callback returns non-zero, the sqlite3_exec() | 369 ** ^If an sqlite3_exec() callback returns non-zero, the sqlite3_exec() |
356 ** routine returns SQLITE_ABORT without invoking the callback again and | 370 ** routine returns SQLITE_ABORT without invoking the callback again and |
357 ** without running any subsequent SQL statements. | 371 ** without running any subsequent SQL statements. |
358 ** | 372 ** |
359 ** ^The 2nd argument to the sqlite3_exec() callback function is the | 373 ** ^The 2nd argument to the sqlite3_exec() callback function is the |
360 ** number of columns in the result. ^The 3rd argument to the sqlite3_exec() | 374 ** number of columns in the result. ^The 3rd argument to the sqlite3_exec() |
(...skipping 14 matching lines...) Expand all Loading... |
375 ** | 389 ** |
376 ** <ul> | 390 ** <ul> |
377 ** <li> The application must ensure that the 1st parameter to sqlite3_exec() | 391 ** <li> The application must ensure that the 1st parameter to sqlite3_exec() |
378 ** is a valid and open [database connection]. | 392 ** is a valid and open [database connection]. |
379 ** <li> The application must not close the [database connection] specified by | 393 ** <li> The application must not close the [database connection] specified by |
380 ** the 1st parameter to sqlite3_exec() while sqlite3_exec() is running. | 394 ** the 1st parameter to sqlite3_exec() while sqlite3_exec() is running. |
381 ** <li> The application must not modify the SQL statement text passed into | 395 ** <li> The application must not modify the SQL statement text passed into |
382 ** the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running. | 396 ** the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running. |
383 ** </ul> | 397 ** </ul> |
384 */ | 398 */ |
385 SQLITE_API int SQLITE_STDCALL sqlite3_exec( | 399 SQLITE_API int sqlite3_exec( |
386 sqlite3*, /* An open database */ | 400 sqlite3*, /* An open database */ |
387 const char *sql, /* SQL to be evaluated */ | 401 const char *sql, /* SQL to be evaluated */ |
388 int (*callback)(void*,int,char**,char**), /* Callback function */ | 402 int (*callback)(void*,int,char**,char**), /* Callback function */ |
389 void *, /* 1st argument to callback */ | 403 void *, /* 1st argument to callback */ |
390 char **errmsg /* Error msg written here */ | 404 char **errmsg /* Error msg written here */ |
391 ); | 405 ); |
392 | 406 |
393 /* | 407 /* |
394 ** CAPI3REF: Result Codes | 408 ** CAPI3REF: Result Codes |
395 ** KEYWORDS: {result code definitions} | 409 ** KEYWORDS: {result code definitions} |
(...skipping 40 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
436 /* end-of-error-codes */ | 450 /* end-of-error-codes */ |
437 | 451 |
438 /* | 452 /* |
439 ** CAPI3REF: Extended Result Codes | 453 ** CAPI3REF: Extended Result Codes |
440 ** KEYWORDS: {extended result code definitions} | 454 ** KEYWORDS: {extended result code definitions} |
441 ** | 455 ** |
442 ** In its default configuration, SQLite API routines return one of 30 integer | 456 ** In its default configuration, SQLite API routines return one of 30 integer |
443 ** [result codes]. However, experience has shown that many of | 457 ** [result codes]. However, experience has shown that many of |
444 ** these result codes are too coarse-grained. They do not provide as | 458 ** these result codes are too coarse-grained. They do not provide as |
445 ** much information about problems as programmers might like. In an effort to | 459 ** 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 | 460 ** address this, newer versions of SQLite (version 3.3.8 [dateof:3.3.8] |
| 461 ** and later) include |
447 ** support for additional result codes that provide more detailed information | 462 ** support for additional result codes that provide more detailed information |
448 ** about errors. These [extended result codes] are enabled or disabled | 463 ** about errors. These [extended result codes] are enabled or disabled |
449 ** on a per database connection basis using the | 464 ** on a per database connection basis using the |
450 ** [sqlite3_extended_result_codes()] API. Or, the extended code for | 465 ** [sqlite3_extended_result_codes()] API. Or, the extended code for |
451 ** the most recent error can be obtained using | 466 ** the most recent error can be obtained using |
452 ** [sqlite3_extended_errcode()]. | 467 ** [sqlite3_extended_errcode()]. |
453 */ | 468 */ |
454 #define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8)) | 469 #define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8)) |
455 #define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8)) | 470 #define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8)) |
456 #define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8)) | 471 #define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8)) |
(...skipping 42 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
499 #define SQLITE_CONSTRAINT_NOTNULL (SQLITE_CONSTRAINT | (5<<8)) | 514 #define SQLITE_CONSTRAINT_NOTNULL (SQLITE_CONSTRAINT | (5<<8)) |
500 #define SQLITE_CONSTRAINT_PRIMARYKEY (SQLITE_CONSTRAINT | (6<<8)) | 515 #define SQLITE_CONSTRAINT_PRIMARYKEY (SQLITE_CONSTRAINT | (6<<8)) |
501 #define SQLITE_CONSTRAINT_TRIGGER (SQLITE_CONSTRAINT | (7<<8)) | 516 #define SQLITE_CONSTRAINT_TRIGGER (SQLITE_CONSTRAINT | (7<<8)) |
502 #define SQLITE_CONSTRAINT_UNIQUE (SQLITE_CONSTRAINT | (8<<8)) | 517 #define SQLITE_CONSTRAINT_UNIQUE (SQLITE_CONSTRAINT | (8<<8)) |
503 #define SQLITE_CONSTRAINT_VTAB (SQLITE_CONSTRAINT | (9<<8)) | 518 #define SQLITE_CONSTRAINT_VTAB (SQLITE_CONSTRAINT | (9<<8)) |
504 #define SQLITE_CONSTRAINT_ROWID (SQLITE_CONSTRAINT |(10<<8)) | 519 #define SQLITE_CONSTRAINT_ROWID (SQLITE_CONSTRAINT |(10<<8)) |
505 #define SQLITE_NOTICE_RECOVER_WAL (SQLITE_NOTICE | (1<<8)) | 520 #define SQLITE_NOTICE_RECOVER_WAL (SQLITE_NOTICE | (1<<8)) |
506 #define SQLITE_NOTICE_RECOVER_ROLLBACK (SQLITE_NOTICE | (2<<8)) | 521 #define SQLITE_NOTICE_RECOVER_ROLLBACK (SQLITE_NOTICE | (2<<8)) |
507 #define SQLITE_WARNING_AUTOINDEX (SQLITE_WARNING | (1<<8)) | 522 #define SQLITE_WARNING_AUTOINDEX (SQLITE_WARNING | (1<<8)) |
508 #define SQLITE_AUTH_USER (SQLITE_AUTH | (1<<8)) | 523 #define SQLITE_AUTH_USER (SQLITE_AUTH | (1<<8)) |
| 524 #define SQLITE_OK_LOAD_PERMANENTLY (SQLITE_OK | (1<<8)) |
509 | 525 |
510 /* | 526 /* |
511 ** CAPI3REF: Flags For File Open Operations | 527 ** CAPI3REF: Flags For File Open Operations |
512 ** | 528 ** |
513 ** These bit values are intended for use in the | 529 ** These bit values are intended for use in the |
514 ** 3rd parameter to the [sqlite3_open_v2()] interface and | 530 ** 3rd parameter to the [sqlite3_open_v2()] interface and |
515 ** in the 4th parameter to the [sqlite3_vfs.xOpen] method. | 531 ** in the 4th parameter to the [sqlite3_vfs.xOpen] method. |
516 */ | 532 */ |
517 #define SQLITE_OPEN_READONLY 0x00000001 /* Ok for sqlite3_open_v2() */ | 533 #define SQLITE_OPEN_READONLY 0x00000001 /* Ok for sqlite3_open_v2() */ |
518 #define SQLITE_OPEN_READWRITE 0x00000002 /* Ok for sqlite3_open_v2() */ | 534 #define SQLITE_OPEN_READWRITE 0x00000002 /* Ok for sqlite3_open_v2() */ |
(...skipping 34 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
553 ** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means | 569 ** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means |
554 ** that when data is appended to a file, the data is appended | 570 ** that when data is appended to a file, the data is appended |
555 ** first then the size of the file is extended, never the other | 571 ** first then the size of the file is extended, never the other |
556 ** way around. The SQLITE_IOCAP_SEQUENTIAL property means that | 572 ** way around. The SQLITE_IOCAP_SEQUENTIAL property means that |
557 ** information is written to disk in the same order as calls | 573 ** information is written to disk in the same order as calls |
558 ** to xWrite(). The SQLITE_IOCAP_POWERSAFE_OVERWRITE property means that | 574 ** to xWrite(). The SQLITE_IOCAP_POWERSAFE_OVERWRITE property means that |
559 ** after reboot following a crash or power loss, the only bytes in a | 575 ** after reboot following a crash or power loss, the only bytes in a |
560 ** file that were written at the application level might have changed | 576 ** file that were written at the application level might have changed |
561 ** and that adjacent bytes, even bytes within the same sector are | 577 ** and that adjacent bytes, even bytes within the same sector are |
562 ** guaranteed to be unchanged. The SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN | 578 ** guaranteed to be unchanged. The SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN |
563 ** flag indicate that a file cannot be deleted when open. The | 579 ** flag indicates that a file cannot be deleted when open. The |
564 ** SQLITE_IOCAP_IMMUTABLE flag indicates that the file is on | 580 ** SQLITE_IOCAP_IMMUTABLE flag indicates that the file is on |
565 ** read-only media and cannot be changed even by processes with | 581 ** read-only media and cannot be changed even by processes with |
566 ** elevated privileges. | 582 ** elevated privileges. |
567 */ | 583 */ |
568 #define SQLITE_IOCAP_ATOMIC 0x00000001 | 584 #define SQLITE_IOCAP_ATOMIC 0x00000001 |
569 #define SQLITE_IOCAP_ATOMIC512 0x00000002 | 585 #define SQLITE_IOCAP_ATOMIC512 0x00000002 |
570 #define SQLITE_IOCAP_ATOMIC1K 0x00000004 | 586 #define SQLITE_IOCAP_ATOMIC1K 0x00000004 |
571 #define SQLITE_IOCAP_ATOMIC2K 0x00000008 | 587 #define SQLITE_IOCAP_ATOMIC2K 0x00000008 |
572 #define SQLITE_IOCAP_ATOMIC4K 0x00000010 | 588 #define SQLITE_IOCAP_ATOMIC4K 0x00000010 |
573 #define SQLITE_IOCAP_ATOMIC8K 0x00000020 | 589 #define SQLITE_IOCAP_ATOMIC8K 0x00000020 |
(...skipping 129 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
703 ** <li> [SQLITE_IOCAP_ATOMIC512] | 719 ** <li> [SQLITE_IOCAP_ATOMIC512] |
704 ** <li> [SQLITE_IOCAP_ATOMIC1K] | 720 ** <li> [SQLITE_IOCAP_ATOMIC1K] |
705 ** <li> [SQLITE_IOCAP_ATOMIC2K] | 721 ** <li> [SQLITE_IOCAP_ATOMIC2K] |
706 ** <li> [SQLITE_IOCAP_ATOMIC4K] | 722 ** <li> [SQLITE_IOCAP_ATOMIC4K] |
707 ** <li> [SQLITE_IOCAP_ATOMIC8K] | 723 ** <li> [SQLITE_IOCAP_ATOMIC8K] |
708 ** <li> [SQLITE_IOCAP_ATOMIC16K] | 724 ** <li> [SQLITE_IOCAP_ATOMIC16K] |
709 ** <li> [SQLITE_IOCAP_ATOMIC32K] | 725 ** <li> [SQLITE_IOCAP_ATOMIC32K] |
710 ** <li> [SQLITE_IOCAP_ATOMIC64K] | 726 ** <li> [SQLITE_IOCAP_ATOMIC64K] |
711 ** <li> [SQLITE_IOCAP_SAFE_APPEND] | 727 ** <li> [SQLITE_IOCAP_SAFE_APPEND] |
712 ** <li> [SQLITE_IOCAP_SEQUENTIAL] | 728 ** <li> [SQLITE_IOCAP_SEQUENTIAL] |
| 729 ** <li> [SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN] |
| 730 ** <li> [SQLITE_IOCAP_POWERSAFE_OVERWRITE] |
| 731 ** <li> [SQLITE_IOCAP_IMMUTABLE] |
713 ** </ul> | 732 ** </ul> |
714 ** | 733 ** |
715 ** The SQLITE_IOCAP_ATOMIC property means that all writes of | 734 ** The SQLITE_IOCAP_ATOMIC property means that all writes of |
716 ** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values | 735 ** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values |
717 ** mean that writes of blocks that are nnn bytes in size and | 736 ** mean that writes of blocks that are nnn bytes in size and |
718 ** are aligned to an address which is an integer multiple of | 737 ** are aligned to an address which is an integer multiple of |
719 ** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means | 738 ** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means |
720 ** that when data is appended to a file, the data is appended | 739 ** that when data is appended to a file, the data is appended |
721 ** first then the size of the file is extended, never the other | 740 ** first then the size of the file is extended, never the other |
722 ** way around. The SQLITE_IOCAP_SEQUENTIAL property means that | 741 ** way around. The SQLITE_IOCAP_SEQUENTIAL property means that |
(...skipping 236 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
959 ** The argument is a zero-terminated string. Higher layers in the | 978 ** The argument is a zero-terminated string. Higher layers in the |
960 ** SQLite stack may generate instances of this file control if | 979 ** SQLite stack may generate instances of this file control if |
961 ** the [SQLITE_USE_FCNTL_TRACE] compile-time option is enabled. | 980 ** the [SQLITE_USE_FCNTL_TRACE] compile-time option is enabled. |
962 ** | 981 ** |
963 ** <li>[[SQLITE_FCNTL_HAS_MOVED]] | 982 ** <li>[[SQLITE_FCNTL_HAS_MOVED]] |
964 ** The [SQLITE_FCNTL_HAS_MOVED] file control interprets its argument as a | 983 ** The [SQLITE_FCNTL_HAS_MOVED] file control interprets its argument as a |
965 ** pointer to an integer and it writes a boolean into that integer depending | 984 ** pointer to an integer and it writes a boolean into that integer depending |
966 ** on whether or not the file has been renamed, moved, or deleted since it | 985 ** on whether or not the file has been renamed, moved, or deleted since it |
967 ** was first opened. | 986 ** was first opened. |
968 ** | 987 ** |
| 988 ** <li>[[SQLITE_FCNTL_WIN32_GET_HANDLE]] |
| 989 ** The [SQLITE_FCNTL_WIN32_GET_HANDLE] opcode can be used to obtain the |
| 990 ** underlying native file handle associated with a file handle. This file |
| 991 ** control interprets its argument as a pointer to a native file handle and |
| 992 ** writes the resulting value there. |
| 993 ** |
969 ** <li>[[SQLITE_FCNTL_WIN32_SET_HANDLE]] | 994 ** <li>[[SQLITE_FCNTL_WIN32_SET_HANDLE]] |
970 ** The [SQLITE_FCNTL_WIN32_SET_HANDLE] opcode is used for debugging. This | 995 ** The [SQLITE_FCNTL_WIN32_SET_HANDLE] opcode is used for debugging. This |
971 ** opcode causes the xFileControl method to swap the file handle with the one | 996 ** opcode causes the xFileControl method to swap the file handle with the one |
972 ** pointed to by the pArg argument. This capability is used during testing | 997 ** pointed to by the pArg argument. This capability is used during testing |
973 ** and only needs to be supported when SQLITE_TEST is defined. | 998 ** and only needs to be supported when SQLITE_TEST is defined. |
974 ** | 999 ** |
975 ** <li>[[SQLITE_FCNTL_WAL_BLOCK]] | 1000 ** <li>[[SQLITE_FCNTL_WAL_BLOCK]] |
976 ** The [SQLITE_FCNTL_WAL_BLOCK] is a signal to the VFS layer that it might | 1001 ** The [SQLITE_FCNTL_WAL_BLOCK] is a signal to the VFS layer that it might |
977 ** be advantageous to block on the next WAL lock if the lock is not immediately | 1002 ** be advantageous to block on the next WAL lock if the lock is not immediately |
978 ** available. The WAL subsystem issues this signal during rare | 1003 ** available. The WAL subsystem issues this signal during rare |
(...skipping 30 matching lines...) Expand all Loading... |
1009 #define SQLITE_FCNTL_TRACE 19 | 1034 #define SQLITE_FCNTL_TRACE 19 |
1010 #define SQLITE_FCNTL_HAS_MOVED 20 | 1035 #define SQLITE_FCNTL_HAS_MOVED 20 |
1011 #define SQLITE_FCNTL_SYNC 21 | 1036 #define SQLITE_FCNTL_SYNC 21 |
1012 #define SQLITE_FCNTL_COMMIT_PHASETWO 22 | 1037 #define SQLITE_FCNTL_COMMIT_PHASETWO 22 |
1013 #define SQLITE_FCNTL_WIN32_SET_HANDLE 23 | 1038 #define SQLITE_FCNTL_WIN32_SET_HANDLE 23 |
1014 #define SQLITE_FCNTL_WAL_BLOCK 24 | 1039 #define SQLITE_FCNTL_WAL_BLOCK 24 |
1015 #define SQLITE_FCNTL_ZIPVFS 25 | 1040 #define SQLITE_FCNTL_ZIPVFS 25 |
1016 #define SQLITE_FCNTL_RBU 26 | 1041 #define SQLITE_FCNTL_RBU 26 |
1017 #define SQLITE_FCNTL_VFS_POINTER 27 | 1042 #define SQLITE_FCNTL_VFS_POINTER 27 |
1018 #define SQLITE_FCNTL_JOURNAL_POINTER 28 | 1043 #define SQLITE_FCNTL_JOURNAL_POINTER 28 |
| 1044 #define SQLITE_FCNTL_WIN32_GET_HANDLE 29 |
| 1045 #define SQLITE_FCNTL_PDB 30 |
1019 | 1046 |
1020 /* deprecated names */ | 1047 /* deprecated names */ |
1021 #define SQLITE_GET_LOCKPROXYFILE SQLITE_FCNTL_GET_LOCKPROXYFILE | 1048 #define SQLITE_GET_LOCKPROXYFILE SQLITE_FCNTL_GET_LOCKPROXYFILE |
1022 #define SQLITE_SET_LOCKPROXYFILE SQLITE_FCNTL_SET_LOCKPROXYFILE | 1049 #define SQLITE_SET_LOCKPROXYFILE SQLITE_FCNTL_SET_LOCKPROXYFILE |
1023 #define SQLITE_LAST_ERRNO SQLITE_FCNTL_LAST_ERRNO | 1050 #define SQLITE_LAST_ERRNO SQLITE_FCNTL_LAST_ERRNO |
1024 | 1051 |
1025 | 1052 |
1026 /* | 1053 /* |
1027 ** CAPI3REF: Mutex Handle | 1054 ** CAPI3REF: Mutex Handle |
1028 ** | 1055 ** |
1029 ** The mutex module within SQLite defines [sqlite3_mutex] to be an | 1056 ** The mutex module within SQLite defines [sqlite3_mutex] to be an |
1030 ** abstract type for a mutex object. The SQLite core never looks | 1057 ** abstract type for a mutex object. The SQLite core never looks |
1031 ** at the internal representation of an [sqlite3_mutex]. It only | 1058 ** at the internal representation of an [sqlite3_mutex]. It only |
1032 ** deals with pointers to the [sqlite3_mutex] object. | 1059 ** deals with pointers to the [sqlite3_mutex] object. |
1033 ** | 1060 ** |
1034 ** Mutexes are created using [sqlite3_mutex_alloc()]. | 1061 ** Mutexes are created using [sqlite3_mutex_alloc()]. |
1035 */ | 1062 */ |
1036 typedef struct sqlite3_mutex sqlite3_mutex; | 1063 typedef struct sqlite3_mutex sqlite3_mutex; |
1037 | 1064 |
1038 /* | 1065 /* |
| 1066 ** CAPI3REF: Loadable Extension Thunk |
| 1067 ** |
| 1068 ** A pointer to the opaque sqlite3_api_routines structure is passed as |
| 1069 ** the third parameter to entry points of [loadable extensions]. This |
| 1070 ** structure must be typedefed in order to work around compiler warnings |
| 1071 ** on some platforms. |
| 1072 */ |
| 1073 typedef struct sqlite3_api_routines sqlite3_api_routines; |
| 1074 |
| 1075 /* |
1039 ** CAPI3REF: OS Interface Object | 1076 ** CAPI3REF: OS Interface Object |
1040 ** | 1077 ** |
1041 ** An instance of the sqlite3_vfs object defines the interface between | 1078 ** An instance of the sqlite3_vfs object defines the interface between |
1042 ** the SQLite core and the underlying operating system. The "vfs" | 1079 ** the SQLite core and the underlying operating system. The "vfs" |
1043 ** in the name of the object stands for "virtual file system". See | 1080 ** in the name of the object stands for "virtual file system". See |
1044 ** the [VFS | VFS documentation] for further information. | 1081 ** the [VFS | VFS documentation] for further information. |
1045 ** | 1082 ** |
1046 ** The value of the iVersion field is initially 1 but may be larger in | 1083 ** The value of the iVersion field is initially 1 but may be larger in |
1047 ** future versions of SQLite. Additional fields may be appended to this | 1084 ** future versions of SQLite. Additional fields may be appended to this |
1048 ** object when the iVersion value is increased. Note that the structure | 1085 ** object when the iVersion value is increased. Note that the structure |
(...skipping 172 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1221 int (*xCurrentTimeInt64)(sqlite3_vfs*, sqlite3_int64*); | 1258 int (*xCurrentTimeInt64)(sqlite3_vfs*, sqlite3_int64*); |
1222 /* | 1259 /* |
1223 ** The methods above are in versions 1 and 2 of the sqlite_vfs object. | 1260 ** The methods above are in versions 1 and 2 of the sqlite_vfs object. |
1224 ** Those below are for version 3 and greater. | 1261 ** Those below are for version 3 and greater. |
1225 */ | 1262 */ |
1226 int (*xSetSystemCall)(sqlite3_vfs*, const char *zName, sqlite3_syscall_ptr); | 1263 int (*xSetSystemCall)(sqlite3_vfs*, const char *zName, sqlite3_syscall_ptr); |
1227 sqlite3_syscall_ptr (*xGetSystemCall)(sqlite3_vfs*, const char *zName); | 1264 sqlite3_syscall_ptr (*xGetSystemCall)(sqlite3_vfs*, const char *zName); |
1228 const char *(*xNextSystemCall)(sqlite3_vfs*, const char *zName); | 1265 const char *(*xNextSystemCall)(sqlite3_vfs*, const char *zName); |
1229 /* | 1266 /* |
1230 ** The methods above are in versions 1 through 3 of the sqlite_vfs object. | 1267 ** The methods above are in versions 1 through 3 of the sqlite_vfs object. |
1231 ** New fields may be appended in figure versions. The iVersion | 1268 ** New fields may be appended in future versions. The iVersion |
1232 ** value will increment whenever this happens. | 1269 ** value will increment whenever this happens. |
1233 */ | 1270 */ |
1234 }; | 1271 }; |
1235 | 1272 |
1236 /* | 1273 /* |
1237 ** CAPI3REF: Flags for the xAccess VFS method | 1274 ** CAPI3REF: Flags for the xAccess VFS method |
1238 ** | 1275 ** |
1239 ** These integer constants can be used as the third parameter to | 1276 ** These integer constants can be used as the third parameter to |
1240 ** the xAccess method of an [sqlite3_vfs] object. They determine | 1277 ** the xAccess method of an [sqlite3_vfs] object. They determine |
1241 ** what kind of permissions the xAccess method is looking for. | 1278 ** what kind of permissions the xAccess method is looking for. |
(...skipping 121 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1363 ** implementations for sqlite3_os_init() and sqlite3_os_end() | 1400 ** implementations for sqlite3_os_init() and sqlite3_os_end() |
1364 ** are built into SQLite when it is compiled for Unix, Windows, or OS/2. | 1401 ** are built into SQLite when it is compiled for Unix, Windows, or OS/2. |
1365 ** When [custom builds | built for other platforms] | 1402 ** When [custom builds | built for other platforms] |
1366 ** (using the [SQLITE_OS_OTHER=1] compile-time | 1403 ** (using the [SQLITE_OS_OTHER=1] compile-time |
1367 ** option) the application must supply a suitable implementation for | 1404 ** option) the application must supply a suitable implementation for |
1368 ** sqlite3_os_init() and sqlite3_os_end(). An application-supplied | 1405 ** sqlite3_os_init() and sqlite3_os_end(). An application-supplied |
1369 ** implementation of sqlite3_os_init() or sqlite3_os_end() | 1406 ** implementation of sqlite3_os_init() or sqlite3_os_end() |
1370 ** must return [SQLITE_OK] on success and some other [error code] upon | 1407 ** must return [SQLITE_OK] on success and some other [error code] upon |
1371 ** failure. | 1408 ** failure. |
1372 */ | 1409 */ |
1373 SQLITE_API int SQLITE_STDCALL sqlite3_initialize(void); | 1410 SQLITE_API int sqlite3_initialize(void); |
1374 SQLITE_API int SQLITE_STDCALL sqlite3_shutdown(void); | 1411 SQLITE_API int sqlite3_shutdown(void); |
1375 SQLITE_API int SQLITE_STDCALL sqlite3_os_init(void); | 1412 SQLITE_API int sqlite3_os_init(void); |
1376 SQLITE_API int SQLITE_STDCALL sqlite3_os_end(void); | 1413 SQLITE_API int sqlite3_os_end(void); |
1377 | 1414 |
1378 /* | 1415 /* |
1379 ** CAPI3REF: Configuring The SQLite Library | 1416 ** CAPI3REF: Configuring The SQLite Library |
1380 ** | 1417 ** |
1381 ** The sqlite3_config() interface is used to make global configuration | 1418 ** The sqlite3_config() interface is used to make global configuration |
1382 ** changes to SQLite in order to tune SQLite to the specific needs of | 1419 ** changes to SQLite in order to tune SQLite to the specific needs of |
1383 ** the application. The default configuration is recommended for most | 1420 ** the application. The default configuration is recommended for most |
1384 ** applications and so this routine is usually not necessary. It is | 1421 ** applications and so this routine is usually not necessary. It is |
1385 ** provided to support rare applications with unusual needs. | 1422 ** provided to support rare applications with unusual needs. |
1386 ** | 1423 ** |
(...skipping 12 matching lines...) Expand all Loading... |
1399 ** The first argument to sqlite3_config() is an integer | 1436 ** The first argument to sqlite3_config() is an integer |
1400 ** [configuration option] that determines | 1437 ** [configuration option] that determines |
1401 ** what property of SQLite is to be configured. Subsequent arguments | 1438 ** what property of SQLite is to be configured. Subsequent arguments |
1402 ** vary depending on the [configuration option] | 1439 ** vary depending on the [configuration option] |
1403 ** in the first argument. | 1440 ** in the first argument. |
1404 ** | 1441 ** |
1405 ** ^When a configuration option is set, sqlite3_config() returns [SQLITE_OK]. | 1442 ** ^When a configuration option is set, sqlite3_config() returns [SQLITE_OK]. |
1406 ** ^If the option is unknown or SQLite is unable to set the option | 1443 ** ^If the option is unknown or SQLite is unable to set the option |
1407 ** then this routine returns a non-zero [error code]. | 1444 ** then this routine returns a non-zero [error code]. |
1408 */ | 1445 */ |
1409 SQLITE_API int SQLITE_CDECL sqlite3_config(int, ...); | 1446 SQLITE_API int sqlite3_config(int, ...); |
1410 | 1447 |
1411 /* | 1448 /* |
1412 ** CAPI3REF: Configure database connections | 1449 ** CAPI3REF: Configure database connections |
1413 ** METHOD: sqlite3 | 1450 ** METHOD: sqlite3 |
1414 ** | 1451 ** |
1415 ** The sqlite3_db_config() interface is used to make configuration | 1452 ** The sqlite3_db_config() interface is used to make configuration |
1416 ** changes to a [database connection]. The interface is similar to | 1453 ** changes to a [database connection]. The interface is similar to |
1417 ** [sqlite3_config()] except that the changes apply to a single | 1454 ** [sqlite3_config()] except that the changes apply to a single |
1418 ** [database connection] (specified in the first argument). | 1455 ** [database connection] (specified in the first argument). |
1419 ** | 1456 ** |
1420 ** The second argument to sqlite3_db_config(D,V,...) is the | 1457 ** The second argument to sqlite3_db_config(D,V,...) is the |
1421 ** [SQLITE_DBCONFIG_LOOKASIDE | configuration verb] - an integer code | 1458 ** [SQLITE_DBCONFIG_LOOKASIDE | configuration verb] - an integer code |
1422 ** that indicates what aspect of the [database connection] is being configured. | 1459 ** that indicates what aspect of the [database connection] is being configured. |
1423 ** Subsequent arguments vary depending on the configuration verb. | 1460 ** Subsequent arguments vary depending on the configuration verb. |
1424 ** | 1461 ** |
1425 ** ^Calls to sqlite3_db_config() return SQLITE_OK if and only if | 1462 ** ^Calls to sqlite3_db_config() return SQLITE_OK if and only if |
1426 ** the call is considered successful. | 1463 ** the call is considered successful. |
1427 */ | 1464 */ |
1428 SQLITE_API int SQLITE_CDECL sqlite3_db_config(sqlite3*, int op, ...); | 1465 SQLITE_API int sqlite3_db_config(sqlite3*, int op, ...); |
1429 | 1466 |
1430 /* | 1467 /* |
1431 ** CAPI3REF: Memory Allocation Routines | 1468 ** CAPI3REF: Memory Allocation Routines |
1432 ** | 1469 ** |
1433 ** An instance of this object defines the interface between SQLite | 1470 ** An instance of this object defines the interface between SQLite |
1434 ** and low-level memory allocation routines. | 1471 ** and low-level memory allocation routines. |
1435 ** | 1472 ** |
1436 ** This object is used in only one place in the SQLite interface. | 1473 ** This object is used in only one place in the SQLite interface. |
1437 ** A pointer to an instance of this object is the argument to | 1474 ** A pointer to an instance of this object is the argument to |
1438 ** [sqlite3_config()] when the configuration option is | 1475 ** [sqlite3_config()] when the configuration option is |
(...skipping 374 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1813 ** [[SQLITE_CONFIG_PMASZ]] | 1850 ** [[SQLITE_CONFIG_PMASZ]] |
1814 ** <dt>SQLITE_CONFIG_PMASZ | 1851 ** <dt>SQLITE_CONFIG_PMASZ |
1815 ** <dd>^The SQLITE_CONFIG_PMASZ option takes a single parameter which | 1852 ** <dd>^The SQLITE_CONFIG_PMASZ option takes a single parameter which |
1816 ** is an unsigned integer and sets the "Minimum PMA Size" for the multithreaded | 1853 ** is an unsigned integer and sets the "Minimum PMA Size" for the multithreaded |
1817 ** sorter to that integer. The default minimum PMA Size is set by the | 1854 ** sorter to that integer. The default minimum PMA Size is set by the |
1818 ** [SQLITE_SORTER_PMASZ] compile-time option. New threads are launched | 1855 ** [SQLITE_SORTER_PMASZ] compile-time option. New threads are launched |
1819 ** to help with sort operations when multithreaded sorting | 1856 ** to help with sort operations when multithreaded sorting |
1820 ** is enabled (using the [PRAGMA threads] command) and the amount of content | 1857 ** is enabled (using the [PRAGMA threads] command) and the amount of content |
1821 ** to be sorted exceeds the page size times the minimum of the | 1858 ** to be sorted exceeds the page size times the minimum of the |
1822 ** [PRAGMA cache_size] setting and this value. | 1859 ** [PRAGMA cache_size] setting and this value. |
| 1860 ** |
| 1861 ** [[SQLITE_CONFIG_STMTJRNL_SPILL]] |
| 1862 ** <dt>SQLITE_CONFIG_STMTJRNL_SPILL |
| 1863 ** <dd>^The SQLITE_CONFIG_STMTJRNL_SPILL option takes a single parameter which |
| 1864 ** becomes the [statement journal] spill-to-disk threshold. |
| 1865 ** [Statement journals] are held in memory until their size (in bytes) |
| 1866 ** exceeds this threshold, at which point they are written to disk. |
| 1867 ** Or if the threshold is -1, statement journals are always held |
| 1868 ** exclusively in memory. |
| 1869 ** Since many statement journals never become large, setting the spill |
| 1870 ** threshold to a value such as 64KiB can greatly reduce the amount of |
| 1871 ** I/O required to support statement rollback. |
| 1872 ** The default value for this setting is controlled by the |
| 1873 ** [SQLITE_STMTJRNL_SPILL] compile-time option. |
1823 ** </dl> | 1874 ** </dl> |
1824 */ | 1875 */ |
1825 #define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */ | 1876 #define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */ |
1826 #define SQLITE_CONFIG_MULTITHREAD 2 /* nil */ | 1877 #define SQLITE_CONFIG_MULTITHREAD 2 /* nil */ |
1827 #define SQLITE_CONFIG_SERIALIZED 3 /* nil */ | 1878 #define SQLITE_CONFIG_SERIALIZED 3 /* nil */ |
1828 #define SQLITE_CONFIG_MALLOC 4 /* sqlite3_mem_methods* */ | 1879 #define SQLITE_CONFIG_MALLOC 4 /* sqlite3_mem_methods* */ |
1829 #define SQLITE_CONFIG_GETMALLOC 5 /* sqlite3_mem_methods* */ | 1880 #define SQLITE_CONFIG_GETMALLOC 5 /* sqlite3_mem_methods* */ |
1830 #define SQLITE_CONFIG_SCRATCH 6 /* void*, int sz, int N */ | 1881 #define SQLITE_CONFIG_SCRATCH 6 /* void*, int sz, int N */ |
1831 #define SQLITE_CONFIG_PAGECACHE 7 /* void*, int sz, int N */ | 1882 #define SQLITE_CONFIG_PAGECACHE 7 /* void*, int sz, int N */ |
1832 #define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */ | 1883 #define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */ |
1833 #define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */ | 1884 #define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */ |
1834 #define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */ | 1885 #define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */ |
1835 #define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */ | 1886 #define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */ |
1836 /* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */ | 1887 /* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */ |
1837 #define SQLITE_CONFIG_LOOKASIDE 13 /* int int */ | 1888 #define SQLITE_CONFIG_LOOKASIDE 13 /* int int */ |
1838 #define SQLITE_CONFIG_PCACHE 14 /* no-op */ | 1889 #define SQLITE_CONFIG_PCACHE 14 /* no-op */ |
1839 #define SQLITE_CONFIG_GETPCACHE 15 /* no-op */ | 1890 #define SQLITE_CONFIG_GETPCACHE 15 /* no-op */ |
1840 #define SQLITE_CONFIG_LOG 16 /* xFunc, void* */ | 1891 #define SQLITE_CONFIG_LOG 16 /* xFunc, void* */ |
1841 #define SQLITE_CONFIG_URI 17 /* int */ | 1892 #define SQLITE_CONFIG_URI 17 /* int */ |
1842 #define SQLITE_CONFIG_PCACHE2 18 /* sqlite3_pcache_methods2* */ | 1893 #define SQLITE_CONFIG_PCACHE2 18 /* sqlite3_pcache_methods2* */ |
1843 #define SQLITE_CONFIG_GETPCACHE2 19 /* sqlite3_pcache_methods2* */ | 1894 #define SQLITE_CONFIG_GETPCACHE2 19 /* sqlite3_pcache_methods2* */ |
1844 #define SQLITE_CONFIG_COVERING_INDEX_SCAN 20 /* int */ | 1895 #define SQLITE_CONFIG_COVERING_INDEX_SCAN 20 /* int */ |
1845 #define SQLITE_CONFIG_SQLLOG 21 /* xSqllog, void* */ | 1896 #define SQLITE_CONFIG_SQLLOG 21 /* xSqllog, void* */ |
1846 #define SQLITE_CONFIG_MMAP_SIZE 22 /* sqlite3_int64, sqlite3_int64 */ | 1897 #define SQLITE_CONFIG_MMAP_SIZE 22 /* sqlite3_int64, sqlite3_int64 */ |
1847 #define SQLITE_CONFIG_WIN32_HEAPSIZE 23 /* int nByte */ | 1898 #define SQLITE_CONFIG_WIN32_HEAPSIZE 23 /* int nByte */ |
1848 #define SQLITE_CONFIG_PCACHE_HDRSZ 24 /* int *psz */ | 1899 #define SQLITE_CONFIG_PCACHE_HDRSZ 24 /* int *psz */ |
1849 #define SQLITE_CONFIG_PMASZ 25 /* unsigned int szPma */ | 1900 #define SQLITE_CONFIG_PMASZ 25 /* unsigned int szPma */ |
| 1901 #define SQLITE_CONFIG_STMTJRNL_SPILL 26 /* int nByte */ |
1850 | 1902 |
1851 /* | 1903 /* |
1852 ** CAPI3REF: Database Connection Configuration Options | 1904 ** CAPI3REF: Database Connection Configuration Options |
1853 ** | 1905 ** |
1854 ** These constants are the available integer configuration options that | 1906 ** These constants are the available integer configuration options that |
1855 ** can be passed as the second argument to the [sqlite3_db_config()] interface. | 1907 ** can be passed as the second argument to the [sqlite3_db_config()] interface. |
1856 ** | 1908 ** |
1857 ** New configuration options may be added in future releases of SQLite. | 1909 ** New configuration options may be added in future releases of SQLite. |
1858 ** Existing configuration options might be discontinued. Applications | 1910 ** Existing configuration options might be discontinued. Applications |
1859 ** should check the return code from [sqlite3_db_config()] to make sure that | 1911 ** should check the return code from [sqlite3_db_config()] to make sure that |
(...skipping 37 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1897 ** <dt>SQLITE_DBCONFIG_ENABLE_TRIGGER</dt> | 1949 ** <dt>SQLITE_DBCONFIG_ENABLE_TRIGGER</dt> |
1898 ** <dd> ^This option is used to enable or disable [CREATE TRIGGER | triggers]. | 1950 ** <dd> ^This option is used to enable or disable [CREATE TRIGGER | triggers]. |
1899 ** There should be two additional arguments. | 1951 ** There should be two additional arguments. |
1900 ** The first argument is an integer which is 0 to disable triggers, | 1952 ** The first argument is an integer which is 0 to disable triggers, |
1901 ** positive to enable triggers or negative to leave the setting unchanged. | 1953 ** positive to enable triggers or negative to leave the setting unchanged. |
1902 ** The second parameter is a pointer to an integer into which | 1954 ** The second parameter is a pointer to an integer into which |
1903 ** is written 0 or 1 to indicate whether triggers are disabled or enabled | 1955 ** is written 0 or 1 to indicate whether triggers are disabled or enabled |
1904 ** following this call. The second parameter may be a NULL pointer, in | 1956 ** following this call. The second parameter may be a NULL pointer, in |
1905 ** which case the trigger setting is not reported back. </dd> | 1957 ** which case the trigger setting is not reported back. </dd> |
1906 ** | 1958 ** |
| 1959 ** <dt>SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER</dt> |
| 1960 ** <dd> ^This option is used to enable or disable the two-argument |
| 1961 ** version of the [fts3_tokenizer()] function which is part of the |
| 1962 ** [FTS3] full-text search engine extension. |
| 1963 ** There should be two additional arguments. |
| 1964 ** The first argument is an integer which is 0 to disable fts3_tokenizer() or |
| 1965 ** positive to enable fts3_tokenizer() or negative to leave the setting |
| 1966 ** unchanged. |
| 1967 ** The second parameter is a pointer to an integer into which |
| 1968 ** is written 0 or 1 to indicate whether fts3_tokenizer is disabled or enabled |
| 1969 ** following this call. The second parameter may be a NULL pointer, in |
| 1970 ** which case the new setting is not reported back. </dd> |
| 1971 ** |
| 1972 ** <dt>SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION</dt> |
| 1973 ** <dd> ^This option is used to enable or disable the [sqlite3_load_extension()] |
| 1974 ** interface independently of the [load_extension()] SQL function. |
| 1975 ** The [sqlite3_enable_load_extension()] API enables or disables both the |
| 1976 ** C-API [sqlite3_load_extension()] and the SQL function [load_extension()]. |
| 1977 ** There should be two additional arguments. |
| 1978 ** When the first argument to this interface is 1, then only the C-API is |
| 1979 ** enabled and the SQL function remains disabled. If the first argument to |
| 1980 ** this interface is 0, then both the C-API and the SQL function are disabled. |
| 1981 ** If the first argument is -1, then no changes are made to state of either the |
| 1982 ** C-API or the SQL function. |
| 1983 ** The second parameter is a pointer to an integer into which |
| 1984 ** is written 0 or 1 to indicate whether [sqlite3_load_extension()] interface |
| 1985 ** is disabled or enabled following this call. The second parameter may |
| 1986 ** be a NULL pointer, in which case the new setting is not reported back. |
| 1987 ** </dd> |
| 1988 ** |
| 1989 ** <dt>SQLITE_DBCONFIG_MAINDBNAME</dt> |
| 1990 ** <dd> ^This option is used to change the name of the "main" database |
| 1991 ** schema. ^The sole argument is a pointer to a constant UTF8 string |
| 1992 ** which will become the new schema name in place of "main". ^SQLite |
| 1993 ** does not make a copy of the new main schema name string, so the application |
| 1994 ** must ensure that the argument passed into this DBCONFIG option is unchanged |
| 1995 ** until after the database connection closes. |
| 1996 ** </dd> |
| 1997 ** |
| 1998 ** <dt>SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE</dt> |
| 1999 ** <dd> Usually, when a database in wal mode is closed or detached from a |
| 2000 ** database handle, SQLite checks if this will mean that there are now no |
| 2001 ** connections at all to the database. If so, it performs a checkpoint |
| 2002 ** operation before closing the connection. This option may be used to |
| 2003 ** override this behaviour. The first parameter passed to this operation |
| 2004 ** is an integer - non-zero to disable checkpoints-on-close, or zero (the |
| 2005 ** default) to enable them. The second parameter is a pointer to an integer |
| 2006 ** into which is written 0 or 1 to indicate whether checkpoints-on-close |
| 2007 ** have been disabled - 0 if they are not disabled, 1 if they are. |
| 2008 ** </dd> |
| 2009 ** |
1907 ** </dl> | 2010 ** </dl> |
1908 */ | 2011 */ |
1909 #define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */ | 2012 #define SQLITE_DBCONFIG_MAINDBNAME 1000 /* const char* */ |
1910 #define SQLITE_DBCONFIG_ENABLE_FKEY 1002 /* int int* */ | 2013 #define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */ |
1911 #define SQLITE_DBCONFIG_ENABLE_TRIGGER 1003 /* int int* */ | 2014 #define SQLITE_DBCONFIG_ENABLE_FKEY 1002 /* int int* */ |
| 2015 #define SQLITE_DBCONFIG_ENABLE_TRIGGER 1003 /* int int* */ |
| 2016 #define SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER 1004 /* int int* */ |
| 2017 #define SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION 1005 /* int int* */ |
| 2018 #define SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE 1006 /* int int* */ |
1912 | 2019 |
1913 | 2020 |
1914 /* | 2021 /* |
1915 ** CAPI3REF: Enable Or Disable Extended Result Codes | 2022 ** CAPI3REF: Enable Or Disable Extended Result Codes |
1916 ** METHOD: sqlite3 | 2023 ** METHOD: sqlite3 |
1917 ** | 2024 ** |
1918 ** ^The sqlite3_extended_result_codes() routine enables or disables the | 2025 ** ^The sqlite3_extended_result_codes() routine enables or disables the |
1919 ** [extended result codes] feature of SQLite. ^The extended result | 2026 ** [extended result codes] feature of SQLite. ^The extended result |
1920 ** codes are disabled by default for historical compatibility. | 2027 ** codes are disabled by default for historical compatibility. |
1921 */ | 2028 */ |
1922 SQLITE_API int SQLITE_STDCALL sqlite3_extended_result_codes(sqlite3*, int onoff)
; | 2029 SQLITE_API int sqlite3_extended_result_codes(sqlite3*, int onoff); |
1923 | 2030 |
1924 /* | 2031 /* |
1925 ** CAPI3REF: Last Insert Rowid | 2032 ** CAPI3REF: Last Insert Rowid |
1926 ** METHOD: sqlite3 | 2033 ** METHOD: sqlite3 |
1927 ** | 2034 ** |
1928 ** ^Each entry in most SQLite tables (except for [WITHOUT ROWID] tables) | 2035 ** ^Each entry in most SQLite tables (except for [WITHOUT ROWID] tables) |
1929 ** has a unique 64-bit signed | 2036 ** has a unique 64-bit signed |
1930 ** integer key called the [ROWID | "rowid"]. ^The rowid is always available | 2037 ** integer key called the [ROWID | "rowid"]. ^The rowid is always available |
1931 ** as an undeclared column named ROWID, OID, or _ROWID_ as long as those | 2038 ** as an undeclared column named ROWID, OID, or _ROWID_ as long as those |
1932 ** names are not also used by explicitly declared columns. ^If | 2039 ** names are not also used by explicitly declared columns. ^If |
(...skipping 31 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1964 ** This function is accessible to SQL statements via the | 2071 ** This function is accessible to SQL statements via the |
1965 ** [last_insert_rowid() SQL function]. | 2072 ** [last_insert_rowid() SQL function]. |
1966 ** | 2073 ** |
1967 ** If a separate thread performs a new [INSERT] on the same | 2074 ** If a separate thread performs a new [INSERT] on the same |
1968 ** database connection while the [sqlite3_last_insert_rowid()] | 2075 ** database connection while the [sqlite3_last_insert_rowid()] |
1969 ** function is running and thus changes the last insert [rowid], | 2076 ** function is running and thus changes the last insert [rowid], |
1970 ** then the value returned by [sqlite3_last_insert_rowid()] is | 2077 ** then the value returned by [sqlite3_last_insert_rowid()] is |
1971 ** unpredictable and might not equal either the old or the new | 2078 ** unpredictable and might not equal either the old or the new |
1972 ** last insert [rowid]. | 2079 ** last insert [rowid]. |
1973 */ | 2080 */ |
1974 SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_last_insert_rowid(sqlite3*); | 2081 SQLITE_API sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*); |
1975 | 2082 |
1976 /* | 2083 /* |
1977 ** CAPI3REF: Count The Number Of Rows Modified | 2084 ** CAPI3REF: Count The Number Of Rows Modified |
1978 ** METHOD: sqlite3 | 2085 ** METHOD: sqlite3 |
1979 ** | 2086 ** |
1980 ** ^This function returns the number of rows modified, inserted or | 2087 ** ^This function returns the number of rows modified, inserted or |
1981 ** deleted by the most recently completed INSERT, UPDATE or DELETE | 2088 ** deleted by the most recently completed INSERT, UPDATE or DELETE |
1982 ** statement on the database connection specified by the only parameter. | 2089 ** statement on the database connection specified by the only parameter. |
1983 ** ^Executing any other type of SQL statement does not modify the value | 2090 ** ^Executing any other type of SQL statement does not modify the value |
1984 ** returned by this function. | 2091 ** returned by this function. |
(...skipping 32 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
2017 ** program, the value returned reflects the number of rows modified by the | 2124 ** program, the value returned reflects the number of rows modified by the |
2018 ** previous INSERT, UPDATE or DELETE statement within the same trigger. | 2125 ** previous INSERT, UPDATE or DELETE statement within the same trigger. |
2019 ** | 2126 ** |
2020 ** See also the [sqlite3_total_changes()] interface, the | 2127 ** See also the [sqlite3_total_changes()] interface, the |
2021 ** [count_changes pragma], and the [changes() SQL function]. | 2128 ** [count_changes pragma], and the [changes() SQL function]. |
2022 ** | 2129 ** |
2023 ** If a separate thread makes changes on the same database connection | 2130 ** If a separate thread makes changes on the same database connection |
2024 ** while [sqlite3_changes()] is running then the value returned | 2131 ** while [sqlite3_changes()] is running then the value returned |
2025 ** is unpredictable and not meaningful. | 2132 ** is unpredictable and not meaningful. |
2026 */ | 2133 */ |
2027 SQLITE_API int SQLITE_STDCALL sqlite3_changes(sqlite3*); | 2134 SQLITE_API int sqlite3_changes(sqlite3*); |
2028 | 2135 |
2029 /* | 2136 /* |
2030 ** CAPI3REF: Total Number Of Rows Modified | 2137 ** CAPI3REF: Total Number Of Rows Modified |
2031 ** METHOD: sqlite3 | 2138 ** METHOD: sqlite3 |
2032 ** | 2139 ** |
2033 ** ^This function returns the total number of rows inserted, modified or | 2140 ** ^This function returns the total number of rows inserted, modified or |
2034 ** deleted by all [INSERT], [UPDATE] or [DELETE] statements completed | 2141 ** deleted by all [INSERT], [UPDATE] or [DELETE] statements completed |
2035 ** since the database connection was opened, including those executed as | 2142 ** since the database connection was opened, including those executed as |
2036 ** part of trigger programs. ^Executing any other type of SQL statement | 2143 ** part of trigger programs. ^Executing any other type of SQL statement |
2037 ** does not affect the value returned by sqlite3_total_changes(). | 2144 ** does not affect the value returned by sqlite3_total_changes(). |
2038 ** | 2145 ** |
2039 ** ^Changes made as part of [foreign key actions] are included in the | 2146 ** ^Changes made as part of [foreign key actions] are included in the |
2040 ** count, but those made as part of REPLACE constraint resolution are | 2147 ** count, but those made as part of REPLACE constraint resolution are |
2041 ** not. ^Changes to a view that are intercepted by INSTEAD OF triggers | 2148 ** not. ^Changes to a view that are intercepted by INSTEAD OF triggers |
2042 ** are not counted. | 2149 ** are not counted. |
2043 ** | 2150 ** |
2044 ** See also the [sqlite3_changes()] interface, the | 2151 ** See also the [sqlite3_changes()] interface, the |
2045 ** [count_changes pragma], and the [total_changes() SQL function]. | 2152 ** [count_changes pragma], and the [total_changes() SQL function]. |
2046 ** | 2153 ** |
2047 ** If a separate thread makes changes on the same database connection | 2154 ** If a separate thread makes changes on the same database connection |
2048 ** while [sqlite3_total_changes()] is running then the value | 2155 ** while [sqlite3_total_changes()] is running then the value |
2049 ** returned is unpredictable and not meaningful. | 2156 ** returned is unpredictable and not meaningful. |
2050 */ | 2157 */ |
2051 SQLITE_API int SQLITE_STDCALL sqlite3_total_changes(sqlite3*); | 2158 SQLITE_API int sqlite3_total_changes(sqlite3*); |
2052 | 2159 |
2053 /* | 2160 /* |
2054 ** CAPI3REF: Interrupt A Long-Running Query | 2161 ** CAPI3REF: Interrupt A Long-Running Query |
2055 ** METHOD: sqlite3 | 2162 ** METHOD: sqlite3 |
2056 ** | 2163 ** |
2057 ** ^This function causes any pending database operation to abort and | 2164 ** ^This function causes any pending database operation to abort and |
2058 ** return at its earliest opportunity. This routine is typically | 2165 ** return at its earliest opportunity. This routine is typically |
2059 ** called in response to a user action such as pressing "Cancel" | 2166 ** called in response to a user action such as pressing "Cancel" |
2060 ** or Ctrl-C where the user wants a long query operation to halt | 2167 ** or Ctrl-C where the user wants a long query operation to halt |
2061 ** immediately. | 2168 ** immediately. |
(...skipping 19 matching lines...) Expand all Loading... |
2081 ** running prior to the sqlite3_interrupt() call. ^New SQL statements | 2188 ** running prior to the sqlite3_interrupt() call. ^New SQL statements |
2082 ** that are started after the running statement count reaches zero are | 2189 ** that are started after the running statement count reaches zero are |
2083 ** not effected by the sqlite3_interrupt(). | 2190 ** not effected by the sqlite3_interrupt(). |
2084 ** ^A call to sqlite3_interrupt(D) that occurs when there are no running | 2191 ** ^A call to sqlite3_interrupt(D) that occurs when there are no running |
2085 ** SQL statements is a no-op and has no effect on SQL statements | 2192 ** SQL statements is a no-op and has no effect on SQL statements |
2086 ** that are started after the sqlite3_interrupt() call returns. | 2193 ** that are started after the sqlite3_interrupt() call returns. |
2087 ** | 2194 ** |
2088 ** If the database connection closes while [sqlite3_interrupt()] | 2195 ** If the database connection closes while [sqlite3_interrupt()] |
2089 ** is running then bad things will likely happen. | 2196 ** is running then bad things will likely happen. |
2090 */ | 2197 */ |
2091 SQLITE_API void SQLITE_STDCALL sqlite3_interrupt(sqlite3*); | 2198 SQLITE_API void sqlite3_interrupt(sqlite3*); |
2092 | 2199 |
2093 /* | 2200 /* |
2094 ** CAPI3REF: Determine If An SQL Statement Is Complete | 2201 ** CAPI3REF: Determine If An SQL Statement Is Complete |
2095 ** | 2202 ** |
2096 ** These routines are useful during command-line input to determine if the | 2203 ** These routines are useful during command-line input to determine if the |
2097 ** currently entered text seems to form a complete SQL statement or | 2204 ** currently entered text seems to form a complete SQL statement or |
2098 ** if additional input is needed before sending the text into | 2205 ** if additional input is needed before sending the text into |
2099 ** SQLite for parsing. ^These routines return 1 if the input string | 2206 ** SQLite for parsing. ^These routines return 1 if the input string |
2100 ** appears to be a complete SQL statement. ^A statement is judged to be | 2207 ** appears to be a complete SQL statement. ^A statement is judged to be |
2101 ** complete if it ends with a semicolon token and is not a prefix of a | 2208 ** complete if it ends with a semicolon token and is not a prefix of a |
(...skipping 14 matching lines...) Expand all Loading... |
2116 ** automatically by sqlite3_complete16(). If that initialization fails, | 2223 ** automatically by sqlite3_complete16(). If that initialization fails, |
2117 ** then the return value from sqlite3_complete16() will be non-zero | 2224 ** then the return value from sqlite3_complete16() will be non-zero |
2118 ** regardless of whether or not the input SQL is complete.)^ | 2225 ** regardless of whether or not the input SQL is complete.)^ |
2119 ** | 2226 ** |
2120 ** The input to [sqlite3_complete()] must be a zero-terminated | 2227 ** The input to [sqlite3_complete()] must be a zero-terminated |
2121 ** UTF-8 string. | 2228 ** UTF-8 string. |
2122 ** | 2229 ** |
2123 ** The input to [sqlite3_complete16()] must be a zero-terminated | 2230 ** The input to [sqlite3_complete16()] must be a zero-terminated |
2124 ** UTF-16 string in native byte order. | 2231 ** UTF-16 string in native byte order. |
2125 */ | 2232 */ |
2126 SQLITE_API int SQLITE_STDCALL sqlite3_complete(const char *sql); | 2233 SQLITE_API int sqlite3_complete(const char *sql); |
2127 SQLITE_API int SQLITE_STDCALL sqlite3_complete16(const void *sql); | 2234 SQLITE_API int sqlite3_complete16(const void *sql); |
2128 | 2235 |
2129 /* | 2236 /* |
2130 ** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors | 2237 ** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors |
2131 ** KEYWORDS: {busy-handler callback} {busy handler} | 2238 ** KEYWORDS: {busy-handler callback} {busy handler} |
2132 ** METHOD: sqlite3 | 2239 ** METHOD: sqlite3 |
2133 ** | 2240 ** |
2134 ** ^The sqlite3_busy_handler(D,X,P) routine sets a callback function X | 2241 ** ^The sqlite3_busy_handler(D,X,P) routine sets a callback function X |
2135 ** that might be invoked with argument P whenever | 2242 ** that might be invoked with argument P whenever |
2136 ** an attempt is made to access a database table associated with | 2243 ** an attempt is made to access a database table associated with |
2137 ** [database connection] D when another thread | 2244 ** [database connection] D when another thread |
(...skipping 40 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
2178 ** busy handler and thus clear any previously set busy handler. | 2285 ** busy handler and thus clear any previously set busy handler. |
2179 ** | 2286 ** |
2180 ** The busy callback should not take any actions which modify the | 2287 ** The busy callback should not take any actions which modify the |
2181 ** database connection that invoked the busy handler. In other words, | 2288 ** database connection that invoked the busy handler. In other words, |
2182 ** the busy handler is not reentrant. Any such actions | 2289 ** the busy handler is not reentrant. Any such actions |
2183 ** result in undefined behavior. | 2290 ** result in undefined behavior. |
2184 ** | 2291 ** |
2185 ** A busy handler must not close the database connection | 2292 ** A busy handler must not close the database connection |
2186 ** or [prepared statement] that invoked the busy handler. | 2293 ** or [prepared statement] that invoked the busy handler. |
2187 */ | 2294 */ |
2188 SQLITE_API int SQLITE_STDCALL sqlite3_busy_handler(sqlite3*, int(*)(void*,int),
void*); | 2295 SQLITE_API int sqlite3_busy_handler(sqlite3*,int(*)(void*,int),void*); |
2189 | 2296 |
2190 /* | 2297 /* |
2191 ** CAPI3REF: Set A Busy Timeout | 2298 ** CAPI3REF: Set A Busy Timeout |
2192 ** METHOD: sqlite3 | 2299 ** METHOD: sqlite3 |
2193 ** | 2300 ** |
2194 ** ^This routine sets a [sqlite3_busy_handler | busy handler] that sleeps | 2301 ** ^This routine sets a [sqlite3_busy_handler | busy handler] that sleeps |
2195 ** for a specified amount of time when a table is locked. ^The handler | 2302 ** for a specified amount of time when a table is locked. ^The handler |
2196 ** will sleep multiple times until at least "ms" milliseconds of sleeping | 2303 ** will sleep multiple times until at least "ms" milliseconds of sleeping |
2197 ** have accumulated. ^After at least "ms" milliseconds of sleeping, | 2304 ** have accumulated. ^After at least "ms" milliseconds of sleeping, |
2198 ** the handler returns 0 which causes [sqlite3_step()] to return | 2305 ** the handler returns 0 which causes [sqlite3_step()] to return |
2199 ** [SQLITE_BUSY]. | 2306 ** [SQLITE_BUSY]. |
2200 ** | 2307 ** |
2201 ** ^Calling this routine with an argument less than or equal to zero | 2308 ** ^Calling this routine with an argument less than or equal to zero |
2202 ** turns off all busy handlers. | 2309 ** turns off all busy handlers. |
2203 ** | 2310 ** |
2204 ** ^(There can only be a single busy handler for a particular | 2311 ** ^(There can only be a single busy handler for a particular |
2205 ** [database connection] at any given moment. If another busy handler | 2312 ** [database connection] at any given moment. If another busy handler |
2206 ** was defined (using [sqlite3_busy_handler()]) prior to calling | 2313 ** was defined (using [sqlite3_busy_handler()]) prior to calling |
2207 ** this routine, that other busy handler is cleared.)^ | 2314 ** this routine, that other busy handler is cleared.)^ |
2208 ** | 2315 ** |
2209 ** See also: [PRAGMA busy_timeout] | 2316 ** See also: [PRAGMA busy_timeout] |
2210 */ | 2317 */ |
2211 SQLITE_API int SQLITE_STDCALL sqlite3_busy_timeout(sqlite3*, int ms); | 2318 SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms); |
2212 | 2319 |
2213 /* | 2320 /* |
2214 ** CAPI3REF: Convenience Routines For Running Queries | 2321 ** CAPI3REF: Convenience Routines For Running Queries |
2215 ** METHOD: sqlite3 | 2322 ** METHOD: sqlite3 |
2216 ** | 2323 ** |
2217 ** This is a legacy interface that is preserved for backwards compatibility. | 2324 ** This is a legacy interface that is preserved for backwards compatibility. |
2218 ** Use of this interface is not recommended. | 2325 ** Use of this interface is not recommended. |
2219 ** | 2326 ** |
2220 ** Definition: A <b>result table</b> is memory data structure created by the | 2327 ** Definition: A <b>result table</b> is memory data structure created by the |
2221 ** [sqlite3_get_table()] interface. A result table records the | 2328 ** [sqlite3_get_table()] interface. A result table records the |
(...skipping 54 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
2276 ** [sqlite3_free_table()] is able to release the memory properly and safely. | 2383 ** [sqlite3_free_table()] is able to release the memory properly and safely. |
2277 ** | 2384 ** |
2278 ** The sqlite3_get_table() interface is implemented as a wrapper around | 2385 ** The sqlite3_get_table() interface is implemented as a wrapper around |
2279 ** [sqlite3_exec()]. The sqlite3_get_table() routine does not have access | 2386 ** [sqlite3_exec()]. The sqlite3_get_table() routine does not have access |
2280 ** to any internal data structures of SQLite. It uses only the public | 2387 ** to any internal data structures of SQLite. It uses only the public |
2281 ** interface defined here. As a consequence, errors that occur in the | 2388 ** interface defined here. As a consequence, errors that occur in the |
2282 ** wrapper layer outside of the internal [sqlite3_exec()] call are not | 2389 ** wrapper layer outside of the internal [sqlite3_exec()] call are not |
2283 ** reflected in subsequent calls to [sqlite3_errcode()] or | 2390 ** reflected in subsequent calls to [sqlite3_errcode()] or |
2284 ** [sqlite3_errmsg()]. | 2391 ** [sqlite3_errmsg()]. |
2285 */ | 2392 */ |
2286 SQLITE_API int SQLITE_STDCALL sqlite3_get_table( | 2393 SQLITE_API int sqlite3_get_table( |
2287 sqlite3 *db, /* An open database */ | 2394 sqlite3 *db, /* An open database */ |
2288 const char *zSql, /* SQL to be evaluated */ | 2395 const char *zSql, /* SQL to be evaluated */ |
2289 char ***pazResult, /* Results of the query */ | 2396 char ***pazResult, /* Results of the query */ |
2290 int *pnRow, /* Number of result rows written here */ | 2397 int *pnRow, /* Number of result rows written here */ |
2291 int *pnColumn, /* Number of result columns written here */ | 2398 int *pnColumn, /* Number of result columns written here */ |
2292 char **pzErrmsg /* Error msg written here */ | 2399 char **pzErrmsg /* Error msg written here */ |
2293 ); | 2400 ); |
2294 SQLITE_API void SQLITE_STDCALL sqlite3_free_table(char **result); | 2401 SQLITE_API void sqlite3_free_table(char **result); |
2295 | 2402 |
2296 /* | 2403 /* |
2297 ** CAPI3REF: Formatted String Printing Functions | 2404 ** CAPI3REF: Formatted String Printing Functions |
2298 ** | 2405 ** |
2299 ** These routines are work-alikes of the "printf()" family of functions | 2406 ** These routines are work-alikes of the "printf()" family of functions |
2300 ** from the standard C library. | 2407 ** from the standard C library. |
2301 ** These routines understand most of the common K&R formatting options, | 2408 ** These routines understand most of the common K&R formatting options, |
2302 ** plus some additional non-standard formats, detailed below. | 2409 ** plus some additional non-standard formats, detailed below. |
2303 ** Note that some of the more obscure formatting options from recent | 2410 ** Note that some of the more obscure formatting options from recent |
2304 ** C-library standards are omitted from this implementation. | 2411 ** C-library standards are omitted from this implementation. |
(...skipping 85 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
2390 ** ^(The "%w" formatting option is like "%q" except that it expects to | 2497 ** ^(The "%w" formatting option is like "%q" except that it expects to |
2391 ** be contained within double-quotes instead of single quotes, and it | 2498 ** be contained within double-quotes instead of single quotes, and it |
2392 ** escapes the double-quote character instead of the single-quote | 2499 ** escapes the double-quote character instead of the single-quote |
2393 ** character.)^ The "%w" formatting option is intended for safely inserting | 2500 ** character.)^ The "%w" formatting option is intended for safely inserting |
2394 ** table and column names into a constructed SQL statement. | 2501 ** table and column names into a constructed SQL statement. |
2395 ** | 2502 ** |
2396 ** ^(The "%z" formatting option works like "%s" but with the | 2503 ** ^(The "%z" formatting option works like "%s" but with the |
2397 ** addition that after the string has been read and copied into | 2504 ** addition that after the string has been read and copied into |
2398 ** the result, [sqlite3_free()] is called on the input string.)^ | 2505 ** the result, [sqlite3_free()] is called on the input string.)^ |
2399 */ | 2506 */ |
2400 SQLITE_API char *SQLITE_CDECL sqlite3_mprintf(const char*,...); | 2507 SQLITE_API char *sqlite3_mprintf(const char*,...); |
2401 SQLITE_API char *SQLITE_STDCALL sqlite3_vmprintf(const char*, va_list); | 2508 SQLITE_API char *sqlite3_vmprintf(const char*, va_list); |
2402 SQLITE_API char *SQLITE_CDECL sqlite3_snprintf(int,char*,const char*, ...); | 2509 SQLITE_API char *sqlite3_snprintf(int,char*,const char*, ...); |
2403 SQLITE_API char *SQLITE_STDCALL sqlite3_vsnprintf(int,char*,const char*, va_list
); | 2510 SQLITE_API char *sqlite3_vsnprintf(int,char*,const char*, va_list); |
2404 | 2511 |
2405 /* | 2512 /* |
2406 ** CAPI3REF: Memory Allocation Subsystem | 2513 ** CAPI3REF: Memory Allocation Subsystem |
2407 ** | 2514 ** |
2408 ** The SQLite core uses these three routines for all of its own | 2515 ** The SQLite core uses these three routines for all of its own |
2409 ** internal memory allocation needs. "Core" in the previous sentence | 2516 ** internal memory allocation needs. "Core" in the previous sentence |
2410 ** does not include operating-system specific VFS implementation. The | 2517 ** does not include operating-system specific VFS implementation. The |
2411 ** Windows VFS uses native malloc() and free() for some operations. | 2518 ** Windows VFS uses native malloc() and free() for some operations. |
2412 ** | 2519 ** |
2413 ** ^The sqlite3_malloc() routine returns a pointer to a block | 2520 ** ^The sqlite3_malloc() routine returns a pointer to a block |
(...skipping 69 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
2483 ** | 2590 ** |
2484 ** The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()] | 2591 ** The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()] |
2485 ** must be either NULL or else pointers obtained from a prior | 2592 ** must be either NULL or else pointers obtained from a prior |
2486 ** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that have | 2593 ** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that have |
2487 ** not yet been released. | 2594 ** not yet been released. |
2488 ** | 2595 ** |
2489 ** The application must not read or write any part of | 2596 ** The application must not read or write any part of |
2490 ** a block of memory after it has been released using | 2597 ** a block of memory after it has been released using |
2491 ** [sqlite3_free()] or [sqlite3_realloc()]. | 2598 ** [sqlite3_free()] or [sqlite3_realloc()]. |
2492 */ | 2599 */ |
2493 SQLITE_API void *SQLITE_STDCALL sqlite3_malloc(int); | 2600 SQLITE_API void *sqlite3_malloc(int); |
2494 SQLITE_API void *SQLITE_STDCALL sqlite3_malloc64(sqlite3_uint64); | 2601 SQLITE_API void *sqlite3_malloc64(sqlite3_uint64); |
2495 SQLITE_API void *SQLITE_STDCALL sqlite3_realloc(void*, int); | 2602 SQLITE_API void *sqlite3_realloc(void*, int); |
2496 SQLITE_API void *SQLITE_STDCALL sqlite3_realloc64(void*, sqlite3_uint64); | 2603 SQLITE_API void *sqlite3_realloc64(void*, sqlite3_uint64); |
2497 SQLITE_API void SQLITE_STDCALL sqlite3_free(void*); | 2604 SQLITE_API void sqlite3_free(void*); |
2498 SQLITE_API sqlite3_uint64 SQLITE_STDCALL sqlite3_msize(void*); | 2605 SQLITE_API sqlite3_uint64 sqlite3_msize(void*); |
2499 | 2606 |
2500 /* | 2607 /* |
2501 ** CAPI3REF: Memory Allocator Statistics | 2608 ** CAPI3REF: Memory Allocator Statistics |
2502 ** | 2609 ** |
2503 ** SQLite provides these two interfaces for reporting on the status | 2610 ** SQLite provides these two interfaces for reporting on the status |
2504 ** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()] | 2611 ** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()] |
2505 ** routines, which form the built-in memory allocation subsystem. | 2612 ** routines, which form the built-in memory allocation subsystem. |
2506 ** | 2613 ** |
2507 ** ^The [sqlite3_memory_used()] routine returns the number of bytes | 2614 ** ^The [sqlite3_memory_used()] routine returns the number of bytes |
2508 ** of memory currently outstanding (malloced but not freed). | 2615 ** of memory currently outstanding (malloced but not freed). |
2509 ** ^The [sqlite3_memory_highwater()] routine returns the maximum | 2616 ** ^The [sqlite3_memory_highwater()] routine returns the maximum |
2510 ** value of [sqlite3_memory_used()] since the high-water mark | 2617 ** value of [sqlite3_memory_used()] since the high-water mark |
2511 ** was last reset. ^The values returned by [sqlite3_memory_used()] and | 2618 ** was last reset. ^The values returned by [sqlite3_memory_used()] and |
2512 ** [sqlite3_memory_highwater()] include any overhead | 2619 ** [sqlite3_memory_highwater()] include any overhead |
2513 ** added by SQLite in its implementation of [sqlite3_malloc()], | 2620 ** added by SQLite in its implementation of [sqlite3_malloc()], |
2514 ** but not overhead added by the any underlying system library | 2621 ** but not overhead added by the any underlying system library |
2515 ** routines that [sqlite3_malloc()] may call. | 2622 ** routines that [sqlite3_malloc()] may call. |
2516 ** | 2623 ** |
2517 ** ^The memory high-water mark is reset to the current value of | 2624 ** ^The memory high-water mark is reset to the current value of |
2518 ** [sqlite3_memory_used()] if and only if the parameter to | 2625 ** [sqlite3_memory_used()] if and only if the parameter to |
2519 ** [sqlite3_memory_highwater()] is true. ^The value returned | 2626 ** [sqlite3_memory_highwater()] is true. ^The value returned |
2520 ** by [sqlite3_memory_highwater(1)] is the high-water mark | 2627 ** by [sqlite3_memory_highwater(1)] is the high-water mark |
2521 ** prior to the reset. | 2628 ** prior to the reset. |
2522 */ | 2629 */ |
2523 SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_memory_used(void); | 2630 SQLITE_API sqlite3_int64 sqlite3_memory_used(void); |
2524 SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_memory_highwater(int resetFlag); | 2631 SQLITE_API sqlite3_int64 sqlite3_memory_highwater(int resetFlag); |
2525 | 2632 |
2526 /* | 2633 /* |
2527 ** CAPI3REF: Pseudo-Random Number Generator | 2634 ** CAPI3REF: Pseudo-Random Number Generator |
2528 ** | 2635 ** |
2529 ** SQLite contains a high-quality pseudo-random number generator (PRNG) used to | 2636 ** SQLite contains a high-quality pseudo-random number generator (PRNG) used to |
2530 ** select random [ROWID | ROWIDs] when inserting new records into a table that | 2637 ** select random [ROWID | ROWIDs] when inserting new records into a table that |
2531 ** already uses the largest possible [ROWID]. The PRNG is also used for | 2638 ** already uses the largest possible [ROWID]. The PRNG is also used for |
2532 ** the build-in random() and randomblob() SQL functions. This interface allows | 2639 ** the build-in random() and randomblob() SQL functions. This interface allows |
2533 ** applications to access the same PRNG for other purposes. | 2640 ** applications to access the same PRNG for other purposes. |
2534 ** | 2641 ** |
2535 ** ^A call to this routine stores N bytes of randomness into buffer P. | 2642 ** ^A call to this routine stores N bytes of randomness into buffer P. |
2536 ** ^The P parameter can be a NULL pointer. | 2643 ** ^The P parameter can be a NULL pointer. |
2537 ** | 2644 ** |
2538 ** ^If this routine has not been previously called or if the previous | 2645 ** ^If this routine has not been previously called or if the previous |
2539 ** call had N less than one or a NULL pointer for P, then the PRNG is | 2646 ** call had N less than one or a NULL pointer for P, then the PRNG is |
2540 ** seeded using randomness obtained from the xRandomness method of | 2647 ** seeded using randomness obtained from the xRandomness method of |
2541 ** the default [sqlite3_vfs] object. | 2648 ** the default [sqlite3_vfs] object. |
2542 ** ^If the previous call to this routine had an N of 1 or more and a | 2649 ** ^If the previous call to this routine had an N of 1 or more and a |
2543 ** non-NULL P then the pseudo-randomness is generated | 2650 ** non-NULL P then the pseudo-randomness is generated |
2544 ** internally and without recourse to the [sqlite3_vfs] xRandomness | 2651 ** internally and without recourse to the [sqlite3_vfs] xRandomness |
2545 ** method. | 2652 ** method. |
2546 */ | 2653 */ |
2547 SQLITE_API void SQLITE_STDCALL sqlite3_randomness(int N, void *P); | 2654 SQLITE_API void sqlite3_randomness(int N, void *P); |
2548 | 2655 |
2549 /* | 2656 /* |
2550 ** CAPI3REF: Compile-Time Authorization Callbacks | 2657 ** CAPI3REF: Compile-Time Authorization Callbacks |
2551 ** METHOD: sqlite3 | 2658 ** METHOD: sqlite3 |
2552 ** | 2659 ** |
2553 ** ^This routine registers an authorizer callback with a particular | 2660 ** ^This routine registers an authorizer callback with a particular |
2554 ** [database connection], supplied in the first argument. | 2661 ** [database connection], supplied in the first argument. |
2555 ** ^The authorizer callback is invoked as SQL statements are being compiled | 2662 ** ^The authorizer callback is invoked as SQL statements are being compiled |
2556 ** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()], | 2663 ** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()], |
2557 ** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()]. ^At various | 2664 ** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()]. ^At various |
(...skipping 62 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
2620 ** statement might be re-prepared during [sqlite3_step()] due to a | 2727 ** statement might be re-prepared during [sqlite3_step()] due to a |
2621 ** schema change. Hence, the application should ensure that the | 2728 ** schema change. Hence, the application should ensure that the |
2622 ** correct authorizer callback remains in place during the [sqlite3_step()]. | 2729 ** correct authorizer callback remains in place during the [sqlite3_step()]. |
2623 ** | 2730 ** |
2624 ** ^Note that the authorizer callback is invoked only during | 2731 ** ^Note that the authorizer callback is invoked only during |
2625 ** [sqlite3_prepare()] or its variants. Authorization is not | 2732 ** [sqlite3_prepare()] or its variants. Authorization is not |
2626 ** performed during statement evaluation in [sqlite3_step()], unless | 2733 ** performed during statement evaluation in [sqlite3_step()], unless |
2627 ** as stated in the previous paragraph, sqlite3_step() invokes | 2734 ** as stated in the previous paragraph, sqlite3_step() invokes |
2628 ** sqlite3_prepare_v2() to reprepare a statement after a schema change. | 2735 ** sqlite3_prepare_v2() to reprepare a statement after a schema change. |
2629 */ | 2736 */ |
2630 SQLITE_API int SQLITE_STDCALL sqlite3_set_authorizer( | 2737 SQLITE_API int sqlite3_set_authorizer( |
2631 sqlite3*, | 2738 sqlite3*, |
2632 int (*xAuth)(void*,int,const char*,const char*,const char*,const char*), | 2739 int (*xAuth)(void*,int,const char*,const char*,const char*,const char*), |
2633 void *pUserData | 2740 void *pUserData |
2634 ); | 2741 ); |
2635 | 2742 |
2636 /* | 2743 /* |
2637 ** CAPI3REF: Authorizer Return Codes | 2744 ** CAPI3REF: Authorizer Return Codes |
2638 ** | 2745 ** |
2639 ** The [sqlite3_set_authorizer | authorizer callback function] must | 2746 ** The [sqlite3_set_authorizer | authorizer callback function] must |
2640 ** return either [SQLITE_OK] or one of these two constants in order | 2747 ** return either [SQLITE_OK] or one of these two constants in order |
(...skipping 59 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
2700 #define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */ | 2807 #define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */ |
2701 #define SQLITE_FUNCTION 31 /* NULL Function Name */ | 2808 #define SQLITE_FUNCTION 31 /* NULL Function Name */ |
2702 #define SQLITE_SAVEPOINT 32 /* Operation Savepoint Name */ | 2809 #define SQLITE_SAVEPOINT 32 /* Operation Savepoint Name */ |
2703 #define SQLITE_COPY 0 /* No longer used */ | 2810 #define SQLITE_COPY 0 /* No longer used */ |
2704 #define SQLITE_RECURSIVE 33 /* NULL NULL */ | 2811 #define SQLITE_RECURSIVE 33 /* NULL NULL */ |
2705 | 2812 |
2706 /* | 2813 /* |
2707 ** CAPI3REF: Tracing And Profiling Functions | 2814 ** CAPI3REF: Tracing And Profiling Functions |
2708 ** METHOD: sqlite3 | 2815 ** METHOD: sqlite3 |
2709 ** | 2816 ** |
| 2817 ** These routines are deprecated. Use the [sqlite3_trace_v2()] interface |
| 2818 ** instead of the routines described here. |
| 2819 ** |
2710 ** These routines register callback functions that can be used for | 2820 ** These routines register callback functions that can be used for |
2711 ** tracing and profiling the execution of SQL statements. | 2821 ** tracing and profiling the execution of SQL statements. |
2712 ** | 2822 ** |
2713 ** ^The callback function registered by sqlite3_trace() is invoked at | 2823 ** ^The callback function registered by sqlite3_trace() is invoked at |
2714 ** various times when an SQL statement is being run by [sqlite3_step()]. | 2824 ** various times when an SQL statement is being run by [sqlite3_step()]. |
2715 ** ^The sqlite3_trace() callback is invoked with a UTF-8 rendering of the | 2825 ** ^The sqlite3_trace() callback is invoked with a UTF-8 rendering of the |
2716 ** SQL statement text as the statement first begins executing. | 2826 ** SQL statement text as the statement first begins executing. |
2717 ** ^(Additional sqlite3_trace() callbacks might occur | 2827 ** ^(Additional sqlite3_trace() callbacks might occur |
2718 ** as each triggered subprogram is entered. The callbacks for triggers | 2828 ** as each triggered subprogram is entered. The callbacks for triggers |
2719 ** contain a UTF-8 SQL comment that identifies the trigger.)^ | 2829 ** contain a UTF-8 SQL comment that identifies the trigger.)^ |
2720 ** | 2830 ** |
2721 ** The [SQLITE_TRACE_SIZE_LIMIT] compile-time option can be used to limit | 2831 ** The [SQLITE_TRACE_SIZE_LIMIT] compile-time option can be used to limit |
2722 ** the length of [bound parameter] expansion in the output of sqlite3_trace(). | 2832 ** the length of [bound parameter] expansion in the output of sqlite3_trace(). |
2723 ** | 2833 ** |
2724 ** ^The callback function registered by sqlite3_profile() is invoked | 2834 ** ^The callback function registered by sqlite3_profile() is invoked |
2725 ** as each SQL statement finishes. ^The profile callback contains | 2835 ** as each SQL statement finishes. ^The profile callback contains |
2726 ** the original statement text and an estimate of wall-clock time | 2836 ** the original statement text and an estimate of wall-clock time |
2727 ** of how long that statement took to run. ^The profile callback | 2837 ** of how long that statement took to run. ^The profile callback |
2728 ** time is in units of nanoseconds, however the current implementation | 2838 ** time is in units of nanoseconds, however the current implementation |
2729 ** is only capable of millisecond resolution so the six least significant | 2839 ** is only capable of millisecond resolution so the six least significant |
2730 ** digits in the time are meaningless. Future versions of SQLite | 2840 ** digits in the time are meaningless. Future versions of SQLite |
2731 ** might provide greater resolution on the profiler callback. The | 2841 ** might provide greater resolution on the profiler callback. The |
2732 ** sqlite3_profile() function is considered experimental and is | 2842 ** sqlite3_profile() function is considered experimental and is |
2733 ** subject to change in future versions of SQLite. | 2843 ** subject to change in future versions of SQLite. |
2734 */ | 2844 */ |
2735 SQLITE_API void *SQLITE_STDCALL sqlite3_trace(sqlite3*, void(*xTrace)(void*,cons
t char*), void*); | 2845 SQLITE_API SQLITE_DEPRECATED void *sqlite3_trace(sqlite3*, |
2736 SQLITE_API SQLITE_EXPERIMENTAL void *SQLITE_STDCALL sqlite3_profile(sqlite3*, | 2846 void(*xTrace)(void*,const char*), void*); |
| 2847 SQLITE_API SQLITE_DEPRECATED void *sqlite3_profile(sqlite3*, |
2737 void(*xProfile)(void*,const char*,sqlite3_uint64), void*); | 2848 void(*xProfile)(void*,const char*,sqlite3_uint64), void*); |
2738 | 2849 |
2739 /* | 2850 /* |
| 2851 ** CAPI3REF: SQL Trace Event Codes |
| 2852 ** KEYWORDS: SQLITE_TRACE |
| 2853 ** |
| 2854 ** These constants identify classes of events that can be monitored |
| 2855 ** using the [sqlite3_trace_v2()] tracing logic. The third argument |
| 2856 ** to [sqlite3_trace_v2()] is an OR-ed combination of one or more of |
| 2857 ** the following constants. ^The first argument to the trace callback |
| 2858 ** is one of the following constants. |
| 2859 ** |
| 2860 ** New tracing constants may be added in future releases. |
| 2861 ** |
| 2862 ** ^A trace callback has four arguments: xCallback(T,C,P,X). |
| 2863 ** ^The T argument is one of the integer type codes above. |
| 2864 ** ^The C argument is a copy of the context pointer passed in as the |
| 2865 ** fourth argument to [sqlite3_trace_v2()]. |
| 2866 ** The P and X arguments are pointers whose meanings depend on T. |
| 2867 ** |
| 2868 ** <dl> |
| 2869 ** [[SQLITE_TRACE_STMT]] <dt>SQLITE_TRACE_STMT</dt> |
| 2870 ** <dd>^An SQLITE_TRACE_STMT callback is invoked when a prepared statement |
| 2871 ** first begins running and possibly at other times during the |
| 2872 ** execution of the prepared statement, such as at the start of each |
| 2873 ** trigger subprogram. ^The P argument is a pointer to the |
| 2874 ** [prepared statement]. ^The X argument is a pointer to a string which |
| 2875 ** is the unexpanded SQL text of the prepared statement or an SQL comment |
| 2876 ** that indicates the invocation of a trigger. ^The callback can compute |
| 2877 ** the same text that would have been returned by the legacy [sqlite3_trace()] |
| 2878 ** interface by using the X argument when X begins with "--" and invoking |
| 2879 ** [sqlite3_expanded_sql(P)] otherwise. |
| 2880 ** |
| 2881 ** [[SQLITE_TRACE_PROFILE]] <dt>SQLITE_TRACE_PROFILE</dt> |
| 2882 ** <dd>^An SQLITE_TRACE_PROFILE callback provides approximately the same |
| 2883 ** information as is provided by the [sqlite3_profile()] callback. |
| 2884 ** ^The P argument is a pointer to the [prepared statement] and the |
| 2885 ** X argument points to a 64-bit integer which is the estimated of |
| 2886 ** the number of nanosecond that the prepared statement took to run. |
| 2887 ** ^The SQLITE_TRACE_PROFILE callback is invoked when the statement finishes. |
| 2888 ** |
| 2889 ** [[SQLITE_TRACE_ROW]] <dt>SQLITE_TRACE_ROW</dt> |
| 2890 ** <dd>^An SQLITE_TRACE_ROW callback is invoked whenever a prepared |
| 2891 ** statement generates a single row of result. |
| 2892 ** ^The P argument is a pointer to the [prepared statement] and the |
| 2893 ** X argument is unused. |
| 2894 ** |
| 2895 ** [[SQLITE_TRACE_CLOSE]] <dt>SQLITE_TRACE_CLOSE</dt> |
| 2896 ** <dd>^An SQLITE_TRACE_CLOSE callback is invoked when a database |
| 2897 ** connection closes. |
| 2898 ** ^The P argument is a pointer to the [database connection] object |
| 2899 ** and the X argument is unused. |
| 2900 ** </dl> |
| 2901 */ |
| 2902 #define SQLITE_TRACE_STMT 0x01 |
| 2903 #define SQLITE_TRACE_PROFILE 0x02 |
| 2904 #define SQLITE_TRACE_ROW 0x04 |
| 2905 #define SQLITE_TRACE_CLOSE 0x08 |
| 2906 |
| 2907 /* |
| 2908 ** CAPI3REF: SQL Trace Hook |
| 2909 ** METHOD: sqlite3 |
| 2910 ** |
| 2911 ** ^The sqlite3_trace_v2(D,M,X,P) interface registers a trace callback |
| 2912 ** function X against [database connection] D, using property mask M |
| 2913 ** and context pointer P. ^If the X callback is |
| 2914 ** NULL or if the M mask is zero, then tracing is disabled. The |
| 2915 ** M argument should be the bitwise OR-ed combination of |
| 2916 ** zero or more [SQLITE_TRACE] constants. |
| 2917 ** |
| 2918 ** ^Each call to either sqlite3_trace() or sqlite3_trace_v2() overrides |
| 2919 ** (cancels) any prior calls to sqlite3_trace() or sqlite3_trace_v2(). |
| 2920 ** |
| 2921 ** ^The X callback is invoked whenever any of the events identified by |
| 2922 ** mask M occur. ^The integer return value from the callback is currently |
| 2923 ** ignored, though this may change in future releases. Callback |
| 2924 ** implementations should return zero to ensure future compatibility. |
| 2925 ** |
| 2926 ** ^A trace callback is invoked with four arguments: callback(T,C,P,X). |
| 2927 ** ^The T argument is one of the [SQLITE_TRACE] |
| 2928 ** constants to indicate why the callback was invoked. |
| 2929 ** ^The C argument is a copy of the context pointer. |
| 2930 ** The P and X arguments are pointers whose meanings depend on T. |
| 2931 ** |
| 2932 ** The sqlite3_trace_v2() interface is intended to replace the legacy |
| 2933 ** interfaces [sqlite3_trace()] and [sqlite3_profile()], both of which |
| 2934 ** are deprecated. |
| 2935 */ |
| 2936 SQLITE_API int sqlite3_trace_v2( |
| 2937 sqlite3*, |
| 2938 unsigned uMask, |
| 2939 int(*xCallback)(unsigned,void*,void*,void*), |
| 2940 void *pCtx |
| 2941 ); |
| 2942 |
| 2943 /* |
2740 ** CAPI3REF: Query Progress Callbacks | 2944 ** CAPI3REF: Query Progress Callbacks |
2741 ** METHOD: sqlite3 | 2945 ** METHOD: sqlite3 |
2742 ** | 2946 ** |
2743 ** ^The sqlite3_progress_handler(D,N,X,P) interface causes the callback | 2947 ** ^The sqlite3_progress_handler(D,N,X,P) interface causes the callback |
2744 ** function X to be invoked periodically during long running calls to | 2948 ** function X to be invoked periodically during long running calls to |
2745 ** [sqlite3_exec()], [sqlite3_step()] and [sqlite3_get_table()] for | 2949 ** [sqlite3_exec()], [sqlite3_step()] and [sqlite3_get_table()] for |
2746 ** database connection D. An example use for this | 2950 ** database connection D. An example use for this |
2747 ** interface is to keep a GUI updated during a large query. | 2951 ** interface is to keep a GUI updated during a large query. |
2748 ** | 2952 ** |
2749 ** ^The parameter P is passed through as the only parameter to the | 2953 ** ^The parameter P is passed through as the only parameter to the |
(...skipping 11 matching lines...) Expand all Loading... |
2761 ** ^If the progress callback returns non-zero, the operation is | 2965 ** ^If the progress callback returns non-zero, the operation is |
2762 ** interrupted. This feature can be used to implement a | 2966 ** interrupted. This feature can be used to implement a |
2763 ** "Cancel" button on a GUI progress dialog box. | 2967 ** "Cancel" button on a GUI progress dialog box. |
2764 ** | 2968 ** |
2765 ** The progress handler callback must not do anything that will modify | 2969 ** The progress handler callback must not do anything that will modify |
2766 ** the database connection that invoked the progress handler. | 2970 ** the database connection that invoked the progress handler. |
2767 ** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their | 2971 ** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their |
2768 ** database connections for the meaning of "modify" in this paragraph. | 2972 ** database connections for the meaning of "modify" in this paragraph. |
2769 ** | 2973 ** |
2770 */ | 2974 */ |
2771 SQLITE_API void SQLITE_STDCALL sqlite3_progress_handler(sqlite3*, int, int(*)(vo
id*), void*); | 2975 SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*); |
2772 | 2976 |
2773 /* | 2977 /* |
2774 ** CAPI3REF: Opening A New Database Connection | 2978 ** CAPI3REF: Opening A New Database Connection |
2775 ** CONSTRUCTOR: sqlite3 | 2979 ** CONSTRUCTOR: sqlite3 |
2776 ** | 2980 ** |
2777 ** ^These routines open an SQLite database file as specified by the | 2981 ** ^These routines open an SQLite database file as specified by the |
2778 ** filename argument. ^The filename argument is interpreted as UTF-8 for | 2982 ** filename argument. ^The filename argument is interpreted as UTF-8 for |
2779 ** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte | 2983 ** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte |
2780 ** order for sqlite3_open16(). ^(A [database connection] handle is usually | 2984 ** order for sqlite3_open16(). ^(A [database connection] handle is usually |
2781 ** returned in *ppDb, even if an error occurs. The only exception is that | 2985 ** returned in *ppDb, even if an error occurs. The only exception is that |
(...skipping 208 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
2990 ** codepage is currently defined. Filenames containing international | 3194 ** codepage is currently defined. Filenames containing international |
2991 ** characters must be converted to UTF-8 prior to passing them into | 3195 ** characters must be converted to UTF-8 prior to passing them into |
2992 ** sqlite3_open() or sqlite3_open_v2(). | 3196 ** sqlite3_open() or sqlite3_open_v2(). |
2993 ** | 3197 ** |
2994 ** <b>Note to Windows Runtime users:</b> The temporary directory must be set | 3198 ** <b>Note to Windows Runtime users:</b> The temporary directory must be set |
2995 ** prior to calling sqlite3_open() or sqlite3_open_v2(). Otherwise, various | 3199 ** prior to calling sqlite3_open() or sqlite3_open_v2(). Otherwise, various |
2996 ** features that require the use of temporary files may fail. | 3200 ** features that require the use of temporary files may fail. |
2997 ** | 3201 ** |
2998 ** See also: [sqlite3_temp_directory] | 3202 ** See also: [sqlite3_temp_directory] |
2999 */ | 3203 */ |
3000 SQLITE_API int SQLITE_STDCALL sqlite3_open( | 3204 SQLITE_API int sqlite3_open( |
3001 const char *filename, /* Database filename (UTF-8) */ | 3205 const char *filename, /* Database filename (UTF-8) */ |
3002 sqlite3 **ppDb /* OUT: SQLite db handle */ | 3206 sqlite3 **ppDb /* OUT: SQLite db handle */ |
3003 ); | 3207 ); |
3004 SQLITE_API int SQLITE_STDCALL sqlite3_open16( | 3208 SQLITE_API int sqlite3_open16( |
3005 const void *filename, /* Database filename (UTF-16) */ | 3209 const void *filename, /* Database filename (UTF-16) */ |
3006 sqlite3 **ppDb /* OUT: SQLite db handle */ | 3210 sqlite3 **ppDb /* OUT: SQLite db handle */ |
3007 ); | 3211 ); |
3008 SQLITE_API int SQLITE_STDCALL sqlite3_open_v2( | 3212 SQLITE_API int sqlite3_open_v2( |
3009 const char *filename, /* Database filename (UTF-8) */ | 3213 const char *filename, /* Database filename (UTF-8) */ |
3010 sqlite3 **ppDb, /* OUT: SQLite db handle */ | 3214 sqlite3 **ppDb, /* OUT: SQLite db handle */ |
3011 int flags, /* Flags */ | 3215 int flags, /* Flags */ |
3012 const char *zVfs /* Name of VFS module to use */ | 3216 const char *zVfs /* Name of VFS module to use */ |
3013 ); | 3217 ); |
3014 | 3218 |
3015 /* | 3219 /* |
3016 ** CAPI3REF: Obtain Values For URI Parameters | 3220 ** CAPI3REF: Obtain Values For URI Parameters |
3017 ** | 3221 ** |
3018 ** These are utility routines, useful to VFS implementations, that check | 3222 ** These are utility routines, useful to VFS implementations, that check |
(...skipping 25 matching lines...) Expand all Loading... |
3044 ** 64-bit signed integer and returns that integer, or D if P does not | 3248 ** 64-bit signed integer and returns that integer, or D if P does not |
3045 ** exist. If the value of P is something other than an integer, then | 3249 ** exist. If the value of P is something other than an integer, then |
3046 ** zero is returned. | 3250 ** zero is returned. |
3047 ** | 3251 ** |
3048 ** If F is a NULL pointer, then sqlite3_uri_parameter(F,P) returns NULL and | 3252 ** If F is a NULL pointer, then sqlite3_uri_parameter(F,P) returns NULL and |
3049 ** sqlite3_uri_boolean(F,P,B) returns B. If F is not a NULL pointer and | 3253 ** sqlite3_uri_boolean(F,P,B) returns B. If F is not a NULL pointer and |
3050 ** is not a database file pathname pointer that SQLite passed into the xOpen | 3254 ** is not a database file pathname pointer that SQLite passed into the xOpen |
3051 ** VFS method, then the behavior of this routine is undefined and probably | 3255 ** VFS method, then the behavior of this routine is undefined and probably |
3052 ** undesirable. | 3256 ** undesirable. |
3053 */ | 3257 */ |
3054 SQLITE_API const char *SQLITE_STDCALL sqlite3_uri_parameter(const char *zFilenam
e, const char *zParam); | 3258 SQLITE_API const char *sqlite3_uri_parameter(const char *zFilename, const char *
zParam); |
3055 SQLITE_API int SQLITE_STDCALL sqlite3_uri_boolean(const char *zFile, const char
*zParam, int bDefault); | 3259 SQLITE_API int sqlite3_uri_boolean(const char *zFile, const char *zParam, int bD
efault); |
3056 SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_uri_int64(const char*, const cha
r*, sqlite3_int64); | 3260 SQLITE_API sqlite3_int64 sqlite3_uri_int64(const char*, const char*, sqlite3_int
64); |
3057 | 3261 |
3058 | 3262 |
3059 /* | 3263 /* |
3060 ** CAPI3REF: Error Codes And Messages | 3264 ** CAPI3REF: Error Codes And Messages |
3061 ** METHOD: sqlite3 | 3265 ** METHOD: sqlite3 |
3062 ** | 3266 ** |
3063 ** ^If the most recent sqlite3_* API call associated with | 3267 ** ^If the most recent sqlite3_* API call associated with |
3064 ** [database connection] D failed, then the sqlite3_errcode(D) interface | 3268 ** [database connection] D failed, then the sqlite3_errcode(D) interface |
3065 ** returns the numeric [result code] or [extended result code] for that | 3269 ** returns the numeric [result code] or [extended result code] for that |
3066 ** API call. | 3270 ** API call. |
(...skipping 23 matching lines...) Expand all Loading... |
3090 ** interfaces always report the most recent result. To avoid | 3294 ** interfaces always report the most recent result. To avoid |
3091 ** this, each thread can obtain exclusive use of the [database connection] D | 3295 ** this, each thread can obtain exclusive use of the [database connection] D |
3092 ** by invoking [sqlite3_mutex_enter]([sqlite3_db_mutex](D)) before beginning | 3296 ** by invoking [sqlite3_mutex_enter]([sqlite3_db_mutex](D)) before beginning |
3093 ** to use D and invoking [sqlite3_mutex_leave]([sqlite3_db_mutex](D)) after | 3297 ** to use D and invoking [sqlite3_mutex_leave]([sqlite3_db_mutex](D)) after |
3094 ** all calls to the interfaces listed here are completed. | 3298 ** all calls to the interfaces listed here are completed. |
3095 ** | 3299 ** |
3096 ** If an interface fails with SQLITE_MISUSE, that means the interface | 3300 ** If an interface fails with SQLITE_MISUSE, that means the interface |
3097 ** was invoked incorrectly by the application. In that case, the | 3301 ** was invoked incorrectly by the application. In that case, the |
3098 ** error code and message may or may not be set. | 3302 ** error code and message may or may not be set. |
3099 */ | 3303 */ |
3100 SQLITE_API int SQLITE_STDCALL sqlite3_errcode(sqlite3 *db); | 3304 SQLITE_API int sqlite3_errcode(sqlite3 *db); |
3101 SQLITE_API int SQLITE_STDCALL sqlite3_extended_errcode(sqlite3 *db); | 3305 SQLITE_API int sqlite3_extended_errcode(sqlite3 *db); |
3102 SQLITE_API const char *SQLITE_STDCALL sqlite3_errmsg(sqlite3*); | 3306 SQLITE_API const char *sqlite3_errmsg(sqlite3*); |
3103 SQLITE_API const void *SQLITE_STDCALL sqlite3_errmsg16(sqlite3*); | 3307 SQLITE_API const void *sqlite3_errmsg16(sqlite3*); |
3104 SQLITE_API const char *SQLITE_STDCALL sqlite3_errstr(int); | 3308 SQLITE_API const char *sqlite3_errstr(int); |
3105 | 3309 |
3106 /* | 3310 /* |
3107 ** CAPI3REF: Prepared Statement Object | 3311 ** CAPI3REF: Prepared Statement Object |
3108 ** KEYWORDS: {prepared statement} {prepared statements} | 3312 ** KEYWORDS: {prepared statement} {prepared statements} |
3109 ** | 3313 ** |
3110 ** An instance of this object represents a single SQL statement that | 3314 ** An instance of this object represents a single SQL statement that |
3111 ** has been compiled into binary form and is ready to be evaluated. | 3315 ** has been compiled into binary form and is ready to be evaluated. |
3112 ** | 3316 ** |
3113 ** Think of each SQL statement as a separate computer program. The | 3317 ** Think of each SQL statement as a separate computer program. The |
3114 ** original SQL text is source code. A prepared statement object | 3318 ** original SQL text is source code. A prepared statement object |
(...skipping 47 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
3162 ** off the Internet. The internal databases can be given the | 3366 ** off the Internet. The internal databases can be given the |
3163 ** large, default limits. Databases managed by external sources can | 3367 ** large, default limits. Databases managed by external sources can |
3164 ** be given much smaller limits designed to prevent a denial of service | 3368 ** be given much smaller limits designed to prevent a denial of service |
3165 ** attack. Developers might also want to use the [sqlite3_set_authorizer()] | 3369 ** attack. Developers might also want to use the [sqlite3_set_authorizer()] |
3166 ** interface to further control untrusted SQL. The size of the database | 3370 ** interface to further control untrusted SQL. The size of the database |
3167 ** created by an untrusted script can be contained using the | 3371 ** created by an untrusted script can be contained using the |
3168 ** [max_page_count] [PRAGMA]. | 3372 ** [max_page_count] [PRAGMA]. |
3169 ** | 3373 ** |
3170 ** New run-time limit categories may be added in future releases. | 3374 ** New run-time limit categories may be added in future releases. |
3171 */ | 3375 */ |
3172 SQLITE_API int SQLITE_STDCALL sqlite3_limit(sqlite3*, int id, int newVal); | 3376 SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal); |
3173 | 3377 |
3174 /* | 3378 /* |
3175 ** CAPI3REF: Run-Time Limit Categories | 3379 ** CAPI3REF: Run-Time Limit Categories |
3176 ** KEYWORDS: {limit category} {*limit categories} | 3380 ** KEYWORDS: {limit category} {*limit categories} |
3177 ** | 3381 ** |
3178 ** These constants define various performance limits | 3382 ** These constants define various performance limits |
3179 ** that can be lowered at run-time using [sqlite3_limit()]. | 3383 ** that can be lowered at run-time using [sqlite3_limit()]. |
3180 ** The synopsis of the meanings of the various limits is shown below. | 3384 ** The synopsis of the meanings of the various limits is shown below. |
3181 ** Additional information is available at [limits | Limits in SQLite]. | 3385 ** Additional information is available at [limits | Limits in SQLite]. |
3182 ** | 3386 ** |
(...skipping 131 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
3314 ** then the statement will be automatically recompiled, as if there had been | 3518 ** then the statement will be automatically recompiled, as if there had been |
3315 ** a schema change, on the first [sqlite3_step()] call following any change | 3519 ** a schema change, on the first [sqlite3_step()] call following any change |
3316 ** to the [sqlite3_bind_text | bindings] of that [parameter]. | 3520 ** to the [sqlite3_bind_text | bindings] of that [parameter]. |
3317 ** ^The specific value of WHERE-clause [parameter] might influence the | 3521 ** ^The specific value of WHERE-clause [parameter] might influence the |
3318 ** choice of query plan if the parameter is the left-hand side of a [LIKE] | 3522 ** choice of query plan if the parameter is the left-hand side of a [LIKE] |
3319 ** or [GLOB] operator or if the parameter is compared to an indexed column | 3523 ** or [GLOB] operator or if the parameter is compared to an indexed column |
3320 ** and the [SQLITE_ENABLE_STAT3] compile-time option is enabled. | 3524 ** and the [SQLITE_ENABLE_STAT3] compile-time option is enabled. |
3321 ** </li> | 3525 ** </li> |
3322 ** </ol> | 3526 ** </ol> |
3323 */ | 3527 */ |
3324 SQLITE_API int SQLITE_STDCALL sqlite3_prepare( | 3528 SQLITE_API int sqlite3_prepare( |
3325 sqlite3 *db, /* Database handle */ | 3529 sqlite3 *db, /* Database handle */ |
3326 const char *zSql, /* SQL statement, UTF-8 encoded */ | 3530 const char *zSql, /* SQL statement, UTF-8 encoded */ |
3327 int nByte, /* Maximum length of zSql in bytes. */ | 3531 int nByte, /* Maximum length of zSql in bytes. */ |
3328 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ | 3532 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ |
3329 const char **pzTail /* OUT: Pointer to unused portion of zSql */ | 3533 const char **pzTail /* OUT: Pointer to unused portion of zSql */ |
3330 ); | 3534 ); |
3331 SQLITE_API int SQLITE_STDCALL sqlite3_prepare_v2( | 3535 SQLITE_API int sqlite3_prepare_v2( |
3332 sqlite3 *db, /* Database handle */ | 3536 sqlite3 *db, /* Database handle */ |
3333 const char *zSql, /* SQL statement, UTF-8 encoded */ | 3537 const char *zSql, /* SQL statement, UTF-8 encoded */ |
3334 int nByte, /* Maximum length of zSql in bytes. */ | 3538 int nByte, /* Maximum length of zSql in bytes. */ |
3335 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ | 3539 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ |
3336 const char **pzTail /* OUT: Pointer to unused portion of zSql */ | 3540 const char **pzTail /* OUT: Pointer to unused portion of zSql */ |
3337 ); | 3541 ); |
3338 SQLITE_API int SQLITE_STDCALL sqlite3_prepare16( | 3542 SQLITE_API int sqlite3_prepare16( |
3339 sqlite3 *db, /* Database handle */ | 3543 sqlite3 *db, /* Database handle */ |
3340 const void *zSql, /* SQL statement, UTF-16 encoded */ | 3544 const void *zSql, /* SQL statement, UTF-16 encoded */ |
3341 int nByte, /* Maximum length of zSql in bytes. */ | 3545 int nByte, /* Maximum length of zSql in bytes. */ |
3342 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ | 3546 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ |
3343 const void **pzTail /* OUT: Pointer to unused portion of zSql */ | 3547 const void **pzTail /* OUT: Pointer to unused portion of zSql */ |
3344 ); | 3548 ); |
3345 SQLITE_API int SQLITE_STDCALL sqlite3_prepare16_v2( | 3549 SQLITE_API int sqlite3_prepare16_v2( |
3346 sqlite3 *db, /* Database handle */ | 3550 sqlite3 *db, /* Database handle */ |
3347 const void *zSql, /* SQL statement, UTF-16 encoded */ | 3551 const void *zSql, /* SQL statement, UTF-16 encoded */ |
3348 int nByte, /* Maximum length of zSql in bytes. */ | 3552 int nByte, /* Maximum length of zSql in bytes. */ |
3349 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ | 3553 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ |
3350 const void **pzTail /* OUT: Pointer to unused portion of zSql */ | 3554 const void **pzTail /* OUT: Pointer to unused portion of zSql */ |
3351 ); | 3555 ); |
3352 | 3556 |
3353 /* | 3557 /* |
3354 ** CAPI3REF: Retrieving Statement SQL | 3558 ** CAPI3REF: Retrieving Statement SQL |
3355 ** METHOD: sqlite3_stmt | 3559 ** METHOD: sqlite3_stmt |
3356 ** | 3560 ** |
3357 ** ^This interface can be used to retrieve a saved copy of the original | 3561 ** ^The sqlite3_sql(P) interface returns a pointer to a copy of the UTF-8 |
3358 ** SQL text used to create a [prepared statement] if that statement was | 3562 ** SQL text used to create [prepared statement] P if P was |
3359 ** compiled using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()]. | 3563 ** created by either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()]. |
| 3564 ** ^The sqlite3_expanded_sql(P) interface returns a pointer to a UTF-8 |
| 3565 ** string containing the SQL text of prepared statement P with |
| 3566 ** [bound parameters] expanded. |
| 3567 ** |
| 3568 ** ^(For example, if a prepared statement is created using the SQL |
| 3569 ** text "SELECT $abc,:xyz" and if parameter $abc is bound to integer 2345 |
| 3570 ** and parameter :xyz is unbound, then sqlite3_sql() will return |
| 3571 ** the original string, "SELECT $abc,:xyz" but sqlite3_expanded_sql() |
| 3572 ** will return "SELECT 2345,NULL".)^ |
| 3573 ** |
| 3574 ** ^The sqlite3_expanded_sql() interface returns NULL if insufficient memory |
| 3575 ** is available to hold the result, or if the result would exceed the |
| 3576 ** the maximum string length determined by the [SQLITE_LIMIT_LENGTH]. |
| 3577 ** |
| 3578 ** ^The [SQLITE_TRACE_SIZE_LIMIT] compile-time option limits the size of |
| 3579 ** bound parameter expansions. ^The [SQLITE_OMIT_TRACE] compile-time |
| 3580 ** option causes sqlite3_expanded_sql() to always return NULL. |
| 3581 ** |
| 3582 ** ^The string returned by sqlite3_sql(P) is managed by SQLite and is |
| 3583 ** automatically freed when the prepared statement is finalized. |
| 3584 ** ^The string returned by sqlite3_expanded_sql(P), on the other hand, |
| 3585 ** is obtained from [sqlite3_malloc()] and must be free by the application |
| 3586 ** by passing it to [sqlite3_free()]. |
3360 */ | 3587 */ |
3361 SQLITE_API const char *SQLITE_STDCALL sqlite3_sql(sqlite3_stmt *pStmt); | 3588 SQLITE_API const char *sqlite3_sql(sqlite3_stmt *pStmt); |
| 3589 SQLITE_API char *sqlite3_expanded_sql(sqlite3_stmt *pStmt); |
3362 | 3590 |
3363 /* | 3591 /* |
3364 ** CAPI3REF: Determine If An SQL Statement Writes The Database | 3592 ** CAPI3REF: Determine If An SQL Statement Writes The Database |
3365 ** METHOD: sqlite3_stmt | 3593 ** METHOD: sqlite3_stmt |
3366 ** | 3594 ** |
3367 ** ^The sqlite3_stmt_readonly(X) interface returns true (non-zero) if | 3595 ** ^The sqlite3_stmt_readonly(X) interface returns true (non-zero) if |
3368 ** and only if the [prepared statement] X makes no direct changes to | 3596 ** and only if the [prepared statement] X makes no direct changes to |
3369 ** the content of the database file. | 3597 ** the content of the database file. |
3370 ** | 3598 ** |
3371 ** Note that [application-defined SQL functions] or | 3599 ** Note that [application-defined SQL functions] or |
(...skipping 10 matching lines...) Expand all Loading... |
3382 ** directly, sqlite3_stmt_readonly() would still return true.)^ | 3610 ** directly, sqlite3_stmt_readonly() would still return true.)^ |
3383 ** | 3611 ** |
3384 ** ^Transaction control statements such as [BEGIN], [COMMIT], [ROLLBACK], | 3612 ** ^Transaction control statements such as [BEGIN], [COMMIT], [ROLLBACK], |
3385 ** [SAVEPOINT], and [RELEASE] cause sqlite3_stmt_readonly() to return true, | 3613 ** [SAVEPOINT], and [RELEASE] cause sqlite3_stmt_readonly() to return true, |
3386 ** since the statements themselves do not actually modify the database but | 3614 ** since the statements themselves do not actually modify the database but |
3387 ** rather they control the timing of when other statements modify the | 3615 ** rather they control the timing of when other statements modify the |
3388 ** database. ^The [ATTACH] and [DETACH] statements also cause | 3616 ** database. ^The [ATTACH] and [DETACH] statements also cause |
3389 ** sqlite3_stmt_readonly() to return true since, while those statements | 3617 ** sqlite3_stmt_readonly() to return true since, while those statements |
3390 ** change the configuration of a database connection, they do not make | 3618 ** change the configuration of a database connection, they do not make |
3391 ** changes to the content of the database files on disk. | 3619 ** changes to the content of the database files on disk. |
| 3620 ** ^The sqlite3_stmt_readonly() interface returns true for [BEGIN] since |
| 3621 ** [BEGIN] merely sets internal flags, but the [BEGIN|BEGIN IMMEDIATE] and |
| 3622 ** [BEGIN|BEGIN EXCLUSIVE] commands do touch the database and so |
| 3623 ** sqlite3_stmt_readonly() returns false for those commands. |
3392 */ | 3624 */ |
3393 SQLITE_API int SQLITE_STDCALL sqlite3_stmt_readonly(sqlite3_stmt *pStmt); | 3625 SQLITE_API int sqlite3_stmt_readonly(sqlite3_stmt *pStmt); |
3394 | 3626 |
3395 /* | 3627 /* |
3396 ** CAPI3REF: Determine If A Prepared Statement Has Been Reset | 3628 ** CAPI3REF: Determine If A Prepared Statement Has Been Reset |
3397 ** METHOD: sqlite3_stmt | 3629 ** METHOD: sqlite3_stmt |
3398 ** | 3630 ** |
3399 ** ^The sqlite3_stmt_busy(S) interface returns true (non-zero) if the | 3631 ** ^The sqlite3_stmt_busy(S) interface returns true (non-zero) if the |
3400 ** [prepared statement] S has been stepped at least once using | 3632 ** [prepared statement] S has been stepped at least once using |
3401 ** [sqlite3_step(S)] but has neither run to completion (returned | 3633 ** [sqlite3_step(S)] but has neither run to completion (returned |
3402 ** [SQLITE_DONE] from [sqlite3_step(S)]) nor | 3634 ** [SQLITE_DONE] from [sqlite3_step(S)]) nor |
3403 ** been reset using [sqlite3_reset(S)]. ^The sqlite3_stmt_busy(S) | 3635 ** been reset using [sqlite3_reset(S)]. ^The sqlite3_stmt_busy(S) |
3404 ** interface returns false if S is a NULL pointer. If S is not a | 3636 ** interface returns false if S is a NULL pointer. If S is not a |
3405 ** NULL pointer and is not a pointer to a valid [prepared statement] | 3637 ** NULL pointer and is not a pointer to a valid [prepared statement] |
3406 ** object, then the behavior is undefined and probably undesirable. | 3638 ** object, then the behavior is undefined and probably undesirable. |
3407 ** | 3639 ** |
3408 ** This interface can be used in combination [sqlite3_next_stmt()] | 3640 ** This interface can be used in combination [sqlite3_next_stmt()] |
3409 ** to locate all prepared statements associated with a database | 3641 ** to locate all prepared statements associated with a database |
3410 ** connection that are in need of being reset. This can be used, | 3642 ** connection that are in need of being reset. This can be used, |
3411 ** for example, in diagnostic routines to search for prepared | 3643 ** for example, in diagnostic routines to search for prepared |
3412 ** statements that are holding a transaction open. | 3644 ** statements that are holding a transaction open. |
3413 */ | 3645 */ |
3414 SQLITE_API int SQLITE_STDCALL sqlite3_stmt_busy(sqlite3_stmt*); | 3646 SQLITE_API int sqlite3_stmt_busy(sqlite3_stmt*); |
3415 | 3647 |
3416 /* | 3648 /* |
3417 ** CAPI3REF: Dynamically Typed Value Object | 3649 ** CAPI3REF: Dynamically Typed Value Object |
3418 ** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value} | 3650 ** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value} |
3419 ** | 3651 ** |
3420 ** SQLite uses the sqlite3_value object to represent all values | 3652 ** SQLite uses the sqlite3_value object to represent all values |
3421 ** that can be stored in a database table. SQLite uses dynamic typing | 3653 ** that can be stored in a database table. SQLite uses dynamic typing |
3422 ** for the values it stores. ^Values stored in sqlite3_value objects | 3654 ** for the values it stores. ^Values stored in sqlite3_value objects |
3423 ** can be integers, floating point values, strings, BLOBs, or NULL. | 3655 ** can be integers, floating point values, strings, BLOBs, or NULL. |
3424 ** | 3656 ** |
(...skipping 143 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
3568 ** [error code] if anything goes wrong. | 3800 ** [error code] if anything goes wrong. |
3569 ** ^[SQLITE_TOOBIG] might be returned if the size of a string or BLOB | 3801 ** ^[SQLITE_TOOBIG] might be returned if the size of a string or BLOB |
3570 ** exceeds limits imposed by [sqlite3_limit]([SQLITE_LIMIT_LENGTH]) or | 3802 ** exceeds limits imposed by [sqlite3_limit]([SQLITE_LIMIT_LENGTH]) or |
3571 ** [SQLITE_MAX_LENGTH]. | 3803 ** [SQLITE_MAX_LENGTH]. |
3572 ** ^[SQLITE_RANGE] is returned if the parameter | 3804 ** ^[SQLITE_RANGE] is returned if the parameter |
3573 ** index is out of range. ^[SQLITE_NOMEM] is returned if malloc() fails. | 3805 ** index is out of range. ^[SQLITE_NOMEM] is returned if malloc() fails. |
3574 ** | 3806 ** |
3575 ** See also: [sqlite3_bind_parameter_count()], | 3807 ** See also: [sqlite3_bind_parameter_count()], |
3576 ** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()]. | 3808 ** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()]. |
3577 */ | 3809 */ |
3578 SQLITE_API int SQLITE_STDCALL sqlite3_bind_blob(sqlite3_stmt*, int, const void*,
int n, void(*)(void*)); | 3810 SQLITE_API int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)
(void*)); |
3579 SQLITE_API int SQLITE_STDCALL sqlite3_bind_blob64(sqlite3_stmt*, int, const void
*, sqlite3_uint64, | 3811 SQLITE_API int sqlite3_bind_blob64(sqlite3_stmt*, int, const void*, sqlite3_uint
64, |
3580 void(*)(void*)); | 3812 void(*)(void*)); |
3581 SQLITE_API int SQLITE_STDCALL sqlite3_bind_double(sqlite3_stmt*, int, double); | 3813 SQLITE_API int sqlite3_bind_double(sqlite3_stmt*, int, double); |
3582 SQLITE_API int SQLITE_STDCALL sqlite3_bind_int(sqlite3_stmt*, int, int); | 3814 SQLITE_API int sqlite3_bind_int(sqlite3_stmt*, int, int); |
3583 SQLITE_API int SQLITE_STDCALL sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int
64); | 3815 SQLITE_API int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64); |
3584 SQLITE_API int SQLITE_STDCALL sqlite3_bind_null(sqlite3_stmt*, int); | 3816 SQLITE_API int sqlite3_bind_null(sqlite3_stmt*, int); |
3585 SQLITE_API int SQLITE_STDCALL sqlite3_bind_text(sqlite3_stmt*,int,const char*,in
t,void(*)(void*)); | 3817 SQLITE_API int sqlite3_bind_text(sqlite3_stmt*,int,const char*,int,void(*)(void*
)); |
3586 SQLITE_API int SQLITE_STDCALL sqlite3_bind_text16(sqlite3_stmt*, int, const void
*, int, void(*)(void*)); | 3818 SQLITE_API int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)
(void*)); |
3587 SQLITE_API int SQLITE_STDCALL sqlite3_bind_text64(sqlite3_stmt*, int, const char
*, sqlite3_uint64, | 3819 SQLITE_API int sqlite3_bind_text64(sqlite3_stmt*, int, const char*, sqlite3_uint
64, |
3588 void(*)(void*), unsigned char encoding); | 3820 void(*)(void*), unsigned char encoding); |
3589 SQLITE_API int SQLITE_STDCALL sqlite3_bind_value(sqlite3_stmt*, int, const sqlit
e3_value*); | 3821 SQLITE_API int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*); |
3590 SQLITE_API int SQLITE_STDCALL sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n); | 3822 SQLITE_API int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n); |
3591 SQLITE_API int SQLITE_STDCALL sqlite3_bind_zeroblob64(sqlite3_stmt*, int, sqlite
3_uint64); | 3823 SQLITE_API int sqlite3_bind_zeroblob64(sqlite3_stmt*, int, sqlite3_uint64); |
3592 | 3824 |
3593 /* | 3825 /* |
3594 ** CAPI3REF: Number Of SQL Parameters | 3826 ** CAPI3REF: Number Of SQL Parameters |
3595 ** METHOD: sqlite3_stmt | 3827 ** METHOD: sqlite3_stmt |
3596 ** | 3828 ** |
3597 ** ^This routine can be used to find the number of [SQL parameters] | 3829 ** ^This routine can be used to find the number of [SQL parameters] |
3598 ** in a [prepared statement]. SQL parameters are tokens of the | 3830 ** in a [prepared statement]. SQL parameters are tokens of the |
3599 ** form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as | 3831 ** form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as |
3600 ** placeholders for values that are [sqlite3_bind_blob | bound] | 3832 ** placeholders for values that are [sqlite3_bind_blob | bound] |
3601 ** to the parameters at a later time. | 3833 ** to the parameters at a later time. |
3602 ** | 3834 ** |
3603 ** ^(This routine actually returns the index of the largest (rightmost) | 3835 ** ^(This routine actually returns the index of the largest (rightmost) |
3604 ** parameter. For all forms except ?NNN, this will correspond to the | 3836 ** parameter. For all forms except ?NNN, this will correspond to the |
3605 ** number of unique parameters. If parameters of the ?NNN form are used, | 3837 ** number of unique parameters. If parameters of the ?NNN form are used, |
3606 ** there may be gaps in the list.)^ | 3838 ** there may be gaps in the list.)^ |
3607 ** | 3839 ** |
3608 ** See also: [sqlite3_bind_blob|sqlite3_bind()], | 3840 ** See also: [sqlite3_bind_blob|sqlite3_bind()], |
3609 ** [sqlite3_bind_parameter_name()], and | 3841 ** [sqlite3_bind_parameter_name()], and |
3610 ** [sqlite3_bind_parameter_index()]. | 3842 ** [sqlite3_bind_parameter_index()]. |
3611 */ | 3843 */ |
3612 SQLITE_API int SQLITE_STDCALL sqlite3_bind_parameter_count(sqlite3_stmt*); | 3844 SQLITE_API int sqlite3_bind_parameter_count(sqlite3_stmt*); |
3613 | 3845 |
3614 /* | 3846 /* |
3615 ** CAPI3REF: Name Of A Host Parameter | 3847 ** CAPI3REF: Name Of A Host Parameter |
3616 ** METHOD: sqlite3_stmt | 3848 ** METHOD: sqlite3_stmt |
3617 ** | 3849 ** |
3618 ** ^The sqlite3_bind_parameter_name(P,N) interface returns | 3850 ** ^The sqlite3_bind_parameter_name(P,N) interface returns |
3619 ** the name of the N-th [SQL parameter] in the [prepared statement] P. | 3851 ** the name of the N-th [SQL parameter] in the [prepared statement] P. |
3620 ** ^(SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA" | 3852 ** ^(SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA" |
3621 ** have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA" | 3853 ** have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA" |
3622 ** respectively. | 3854 ** respectively. |
3623 ** In other words, the initial ":" or "$" or "@" or "?" | 3855 ** In other words, the initial ":" or "$" or "@" or "?" |
3624 ** is included as part of the name.)^ | 3856 ** is included as part of the name.)^ |
3625 ** ^Parameters of the form "?" without a following integer have no name | 3857 ** ^Parameters of the form "?" without a following integer have no name |
3626 ** and are referred to as "nameless" or "anonymous parameters". | 3858 ** and are referred to as "nameless" or "anonymous parameters". |
3627 ** | 3859 ** |
3628 ** ^The first host parameter has an index of 1, not 0. | 3860 ** ^The first host parameter has an index of 1, not 0. |
3629 ** | 3861 ** |
3630 ** ^If the value N is out of range or if the N-th parameter is | 3862 ** ^If the value N is out of range or if the N-th parameter is |
3631 ** nameless, then NULL is returned. ^The returned string is | 3863 ** nameless, then NULL is returned. ^The returned string is |
3632 ** always in UTF-8 encoding even if the named parameter was | 3864 ** always in UTF-8 encoding even if the named parameter was |
3633 ** originally specified as UTF-16 in [sqlite3_prepare16()] or | 3865 ** originally specified as UTF-16 in [sqlite3_prepare16()] or |
3634 ** [sqlite3_prepare16_v2()]. | 3866 ** [sqlite3_prepare16_v2()]. |
3635 ** | 3867 ** |
3636 ** See also: [sqlite3_bind_blob|sqlite3_bind()], | 3868 ** See also: [sqlite3_bind_blob|sqlite3_bind()], |
3637 ** [sqlite3_bind_parameter_count()], and | 3869 ** [sqlite3_bind_parameter_count()], and |
3638 ** [sqlite3_bind_parameter_index()]. | 3870 ** [sqlite3_bind_parameter_index()]. |
3639 */ | 3871 */ |
3640 SQLITE_API const char *SQLITE_STDCALL sqlite3_bind_parameter_name(sqlite3_stmt*,
int); | 3872 SQLITE_API const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int); |
3641 | 3873 |
3642 /* | 3874 /* |
3643 ** CAPI3REF: Index Of A Parameter With A Given Name | 3875 ** CAPI3REF: Index Of A Parameter With A Given Name |
3644 ** METHOD: sqlite3_stmt | 3876 ** METHOD: sqlite3_stmt |
3645 ** | 3877 ** |
3646 ** ^Return the index of an SQL parameter given its name. ^The | 3878 ** ^Return the index of an SQL parameter given its name. ^The |
3647 ** index value returned is suitable for use as the second | 3879 ** index value returned is suitable for use as the second |
3648 ** parameter to [sqlite3_bind_blob|sqlite3_bind()]. ^A zero | 3880 ** parameter to [sqlite3_bind_blob|sqlite3_bind()]. ^A zero |
3649 ** is returned if no matching parameter is found. ^The parameter | 3881 ** is returned if no matching parameter is found. ^The parameter |
3650 ** name must be given in UTF-8 even if the original statement | 3882 ** name must be given in UTF-8 even if the original statement |
3651 ** was prepared from UTF-16 text using [sqlite3_prepare16_v2()]. | 3883 ** was prepared from UTF-16 text using [sqlite3_prepare16_v2()]. |
3652 ** | 3884 ** |
3653 ** See also: [sqlite3_bind_blob|sqlite3_bind()], | 3885 ** See also: [sqlite3_bind_blob|sqlite3_bind()], |
3654 ** [sqlite3_bind_parameter_count()], and | 3886 ** [sqlite3_bind_parameter_count()], and |
3655 ** [sqlite3_bind_parameter_name()]. | 3887 ** [sqlite3_bind_parameter_name()]. |
3656 */ | 3888 */ |
3657 SQLITE_API int SQLITE_STDCALL sqlite3_bind_parameter_index(sqlite3_stmt*, const
char *zName); | 3889 SQLITE_API int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName); |
3658 | 3890 |
3659 /* | 3891 /* |
3660 ** CAPI3REF: Reset All Bindings On A Prepared Statement | 3892 ** CAPI3REF: Reset All Bindings On A Prepared Statement |
3661 ** METHOD: sqlite3_stmt | 3893 ** METHOD: sqlite3_stmt |
3662 ** | 3894 ** |
3663 ** ^Contrary to the intuition of many, [sqlite3_reset()] does not reset | 3895 ** ^Contrary to the intuition of many, [sqlite3_reset()] does not reset |
3664 ** the [sqlite3_bind_blob | bindings] on a [prepared statement]. | 3896 ** the [sqlite3_bind_blob | bindings] on a [prepared statement]. |
3665 ** ^Use this routine to reset all host parameters to NULL. | 3897 ** ^Use this routine to reset all host parameters to NULL. |
3666 */ | 3898 */ |
3667 SQLITE_API int SQLITE_STDCALL sqlite3_clear_bindings(sqlite3_stmt*); | 3899 SQLITE_API int sqlite3_clear_bindings(sqlite3_stmt*); |
3668 | 3900 |
3669 /* | 3901 /* |
3670 ** CAPI3REF: Number Of Columns In A Result Set | 3902 ** CAPI3REF: Number Of Columns In A Result Set |
3671 ** METHOD: sqlite3_stmt | 3903 ** METHOD: sqlite3_stmt |
3672 ** | 3904 ** |
3673 ** ^Return the number of columns in the result set returned by the | 3905 ** ^Return the number of columns in the result set returned by the |
3674 ** [prepared statement]. ^This routine returns 0 if pStmt is an SQL | 3906 ** [prepared statement]. ^If this routine returns 0, that means the |
3675 ** statement that does not return data (for example an [UPDATE]). | 3907 ** [prepared statement] returns no data (for example an [UPDATE]). |
| 3908 ** ^However, just because this routine returns a positive number does not |
| 3909 ** mean that one or more rows of data will be returned. ^A SELECT statement |
| 3910 ** will always have a positive sqlite3_column_count() but depending on the |
| 3911 ** WHERE clause constraints and the table content, it might return no rows. |
3676 ** | 3912 ** |
3677 ** See also: [sqlite3_data_count()] | 3913 ** See also: [sqlite3_data_count()] |
3678 */ | 3914 */ |
3679 SQLITE_API int SQLITE_STDCALL sqlite3_column_count(sqlite3_stmt *pStmt); | 3915 SQLITE_API int sqlite3_column_count(sqlite3_stmt *pStmt); |
3680 | 3916 |
3681 /* | 3917 /* |
3682 ** CAPI3REF: Column Names In A Result Set | 3918 ** CAPI3REF: Column Names In A Result Set |
3683 ** METHOD: sqlite3_stmt | 3919 ** METHOD: sqlite3_stmt |
3684 ** | 3920 ** |
3685 ** ^These routines return the name assigned to a particular column | 3921 ** ^These routines return the name assigned to a particular column |
3686 ** in the result set of a [SELECT] statement. ^The sqlite3_column_name() | 3922 ** in the result set of a [SELECT] statement. ^The sqlite3_column_name() |
3687 ** interface returns a pointer to a zero-terminated UTF-8 string | 3923 ** interface returns a pointer to a zero-terminated UTF-8 string |
3688 ** and sqlite3_column_name16() returns a pointer to a zero-terminated | 3924 ** and sqlite3_column_name16() returns a pointer to a zero-terminated |
3689 ** UTF-16 string. ^The first parameter is the [prepared statement] | 3925 ** UTF-16 string. ^The first parameter is the [prepared statement] |
3690 ** that implements the [SELECT] statement. ^The second parameter is the | 3926 ** that implements the [SELECT] statement. ^The second parameter is the |
3691 ** column number. ^The leftmost column is number 0. | 3927 ** column number. ^The leftmost column is number 0. |
3692 ** | 3928 ** |
3693 ** ^The returned string pointer is valid until either the [prepared statement] | 3929 ** ^The returned string pointer is valid until either the [prepared statement] |
3694 ** is destroyed by [sqlite3_finalize()] or until the statement is automatically | 3930 ** is destroyed by [sqlite3_finalize()] or until the statement is automatically |
3695 ** reprepared by the first call to [sqlite3_step()] for a particular run | 3931 ** reprepared by the first call to [sqlite3_step()] for a particular run |
3696 ** or until the next call to | 3932 ** or until the next call to |
3697 ** sqlite3_column_name() or sqlite3_column_name16() on the same column. | 3933 ** sqlite3_column_name() or sqlite3_column_name16() on the same column. |
3698 ** | 3934 ** |
3699 ** ^If sqlite3_malloc() fails during the processing of either routine | 3935 ** ^If sqlite3_malloc() fails during the processing of either routine |
3700 ** (for example during a conversion from UTF-8 to UTF-16) then a | 3936 ** (for example during a conversion from UTF-8 to UTF-16) then a |
3701 ** NULL pointer is returned. | 3937 ** NULL pointer is returned. |
3702 ** | 3938 ** |
3703 ** ^The name of a result column is the value of the "AS" clause for | 3939 ** ^The name of a result column is the value of the "AS" clause for |
3704 ** that column, if there is an AS clause. If there is no AS clause | 3940 ** that column, if there is an AS clause. If there is no AS clause |
3705 ** then the name of the column is unspecified and may change from | 3941 ** then the name of the column is unspecified and may change from |
3706 ** one release of SQLite to the next. | 3942 ** one release of SQLite to the next. |
3707 */ | 3943 */ |
3708 SQLITE_API const char *SQLITE_STDCALL sqlite3_column_name(sqlite3_stmt*, int N); | 3944 SQLITE_API const char *sqlite3_column_name(sqlite3_stmt*, int N); |
3709 SQLITE_API const void *SQLITE_STDCALL sqlite3_column_name16(sqlite3_stmt*, int N
); | 3945 SQLITE_API const void *sqlite3_column_name16(sqlite3_stmt*, int N); |
3710 | 3946 |
3711 /* | 3947 /* |
3712 ** CAPI3REF: Source Of Data In A Query Result | 3948 ** CAPI3REF: Source Of Data In A Query Result |
3713 ** METHOD: sqlite3_stmt | 3949 ** METHOD: sqlite3_stmt |
3714 ** | 3950 ** |
3715 ** ^These routines provide a means to determine the database, table, and | 3951 ** ^These routines provide a means to determine the database, table, and |
3716 ** table column that is the origin of a particular result column in | 3952 ** table column that is the origin of a particular result column in |
3717 ** [SELECT] statement. | 3953 ** [SELECT] statement. |
3718 ** ^The name of the database or table or column can be returned as | 3954 ** ^The name of the database or table or column can be returned as |
3719 ** either a UTF-8 or UTF-16 string. ^The _database_ routines return | 3955 ** either a UTF-8 or UTF-16 string. ^The _database_ routines return |
(...skipping 27 matching lines...) Expand all Loading... |
3747 ** | 3983 ** |
3748 ** If two or more threads call one or more of these routines against the same | 3984 ** If two or more threads call one or more of these routines against the same |
3749 ** prepared statement and column at the same time then the results are | 3985 ** prepared statement and column at the same time then the results are |
3750 ** undefined. | 3986 ** undefined. |
3751 ** | 3987 ** |
3752 ** If two or more threads call one or more | 3988 ** If two or more threads call one or more |
3753 ** [sqlite3_column_database_name | column metadata interfaces] | 3989 ** [sqlite3_column_database_name | column metadata interfaces] |
3754 ** for the same [prepared statement] and result column | 3990 ** for the same [prepared statement] and result column |
3755 ** at the same time then the results are undefined. | 3991 ** at the same time then the results are undefined. |
3756 */ | 3992 */ |
3757 SQLITE_API const char *SQLITE_STDCALL sqlite3_column_database_name(sqlite3_stmt*
,int); | 3993 SQLITE_API const char *sqlite3_column_database_name(sqlite3_stmt*,int); |
3758 SQLITE_API const void *SQLITE_STDCALL sqlite3_column_database_name16(sqlite3_stm
t*,int); | 3994 SQLITE_API const void *sqlite3_column_database_name16(sqlite3_stmt*,int); |
3759 SQLITE_API const char *SQLITE_STDCALL sqlite3_column_table_name(sqlite3_stmt*,in
t); | 3995 SQLITE_API const char *sqlite3_column_table_name(sqlite3_stmt*,int); |
3760 SQLITE_API const void *SQLITE_STDCALL sqlite3_column_table_name16(sqlite3_stmt*,
int); | 3996 SQLITE_API const void *sqlite3_column_table_name16(sqlite3_stmt*,int); |
3761 SQLITE_API const char *SQLITE_STDCALL sqlite3_column_origin_name(sqlite3_stmt*,i
nt); | 3997 SQLITE_API const char *sqlite3_column_origin_name(sqlite3_stmt*,int); |
3762 SQLITE_API const void *SQLITE_STDCALL sqlite3_column_origin_name16(sqlite3_stmt*
,int); | 3998 SQLITE_API const void *sqlite3_column_origin_name16(sqlite3_stmt*,int); |
3763 | 3999 |
3764 /* | 4000 /* |
3765 ** CAPI3REF: Declared Datatype Of A Query Result | 4001 ** CAPI3REF: Declared Datatype Of A Query Result |
3766 ** METHOD: sqlite3_stmt | 4002 ** METHOD: sqlite3_stmt |
3767 ** | 4003 ** |
3768 ** ^(The first parameter is a [prepared statement]. | 4004 ** ^(The first parameter is a [prepared statement]. |
3769 ** If this statement is a [SELECT] statement and the Nth column of the | 4005 ** If this statement is a [SELECT] statement and the Nth column of the |
3770 ** returned result set of that [SELECT] is a table column (not an | 4006 ** returned result set of that [SELECT] is a table column (not an |
3771 ** expression or subquery) then the declared type of the table | 4007 ** expression or subquery) then the declared type of the table |
3772 ** column is returned.)^ ^If the Nth column of the result set is an | 4008 ** column is returned.)^ ^If the Nth column of the result set is an |
(...skipping 11 matching lines...) Expand all Loading... |
3784 ** this routine would return the string "VARIANT" for the second result | 4020 ** this routine would return the string "VARIANT" for the second result |
3785 ** column (i==1), and a NULL pointer for the first result column (i==0).)^ | 4021 ** column (i==1), and a NULL pointer for the first result column (i==0).)^ |
3786 ** | 4022 ** |
3787 ** ^SQLite uses dynamic run-time typing. ^So just because a column | 4023 ** ^SQLite uses dynamic run-time typing. ^So just because a column |
3788 ** is declared to contain a particular type does not mean that the | 4024 ** is declared to contain a particular type does not mean that the |
3789 ** data stored in that column is of the declared type. SQLite is | 4025 ** data stored in that column is of the declared type. SQLite is |
3790 ** strongly typed, but the typing is dynamic not static. ^Type | 4026 ** strongly typed, but the typing is dynamic not static. ^Type |
3791 ** is associated with individual values, not with the containers | 4027 ** is associated with individual values, not with the containers |
3792 ** used to hold those values. | 4028 ** used to hold those values. |
3793 */ | 4029 */ |
3794 SQLITE_API const char *SQLITE_STDCALL sqlite3_column_decltype(sqlite3_stmt*,int)
; | 4030 SQLITE_API const char *sqlite3_column_decltype(sqlite3_stmt*,int); |
3795 SQLITE_API const void *SQLITE_STDCALL sqlite3_column_decltype16(sqlite3_stmt*,in
t); | 4031 SQLITE_API const void *sqlite3_column_decltype16(sqlite3_stmt*,int); |
3796 | 4032 |
3797 /* | 4033 /* |
3798 ** CAPI3REF: Evaluate An SQL Statement | 4034 ** CAPI3REF: Evaluate An SQL Statement |
3799 ** METHOD: sqlite3_stmt | 4035 ** METHOD: sqlite3_stmt |
3800 ** | 4036 ** |
3801 ** After a [prepared statement] has been prepared using either | 4037 ** After a [prepared statement] has been prepared using either |
3802 ** [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or one of the legacy | 4038 ** [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or one of the legacy |
3803 ** interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], this function | 4039 ** interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], this function |
3804 ** must be called one or more times to evaluate the statement. | 4040 ** must be called one or more times to evaluate the statement. |
3805 ** | 4041 ** |
(...skipping 40 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
3846 ** already been [sqlite3_finalize | finalized] or on one that had | 4082 ** already been [sqlite3_finalize | finalized] or on one that had |
3847 ** previously returned [SQLITE_ERROR] or [SQLITE_DONE]. Or it could | 4083 ** previously returned [SQLITE_ERROR] or [SQLITE_DONE]. Or it could |
3848 ** be the case that the same database connection is being used by two or | 4084 ** be the case that the same database connection is being used by two or |
3849 ** more threads at the same moment in time. | 4085 ** more threads at the same moment in time. |
3850 ** | 4086 ** |
3851 ** For all versions of SQLite up to and including 3.6.23.1, a call to | 4087 ** For all versions of SQLite up to and including 3.6.23.1, a call to |
3852 ** [sqlite3_reset()] was required after sqlite3_step() returned anything | 4088 ** [sqlite3_reset()] was required after sqlite3_step() returned anything |
3853 ** other than [SQLITE_ROW] before any subsequent invocation of | 4089 ** other than [SQLITE_ROW] before any subsequent invocation of |
3854 ** sqlite3_step(). Failure to reset the prepared statement using | 4090 ** sqlite3_step(). Failure to reset the prepared statement using |
3855 ** [sqlite3_reset()] would result in an [SQLITE_MISUSE] return from | 4091 ** [sqlite3_reset()] would result in an [SQLITE_MISUSE] return from |
3856 ** sqlite3_step(). But after version 3.6.23.1, sqlite3_step() began | 4092 ** sqlite3_step(). But after [version 3.6.23.1] ([dateof:3.6.23.1], |
| 4093 ** sqlite3_step() began |
3857 ** calling [sqlite3_reset()] automatically in this circumstance rather | 4094 ** calling [sqlite3_reset()] automatically in this circumstance rather |
3858 ** than returning [SQLITE_MISUSE]. This is not considered a compatibility | 4095 ** than returning [SQLITE_MISUSE]. This is not considered a compatibility |
3859 ** break because any application that ever receives an SQLITE_MISUSE error | 4096 ** break because any application that ever receives an SQLITE_MISUSE error |
3860 ** is broken by definition. The [SQLITE_OMIT_AUTORESET] compile-time option | 4097 ** is broken by definition. The [SQLITE_OMIT_AUTORESET] compile-time option |
3861 ** can be used to restore the legacy behavior. | 4098 ** can be used to restore the legacy behavior. |
3862 ** | 4099 ** |
3863 ** <b>Goofy Interface Alert:</b> In the legacy interface, the sqlite3_step() | 4100 ** <b>Goofy Interface Alert:</b> In the legacy interface, the sqlite3_step() |
3864 ** API always returns a generic error code, [SQLITE_ERROR], following any | 4101 ** API always returns a generic error code, [SQLITE_ERROR], following any |
3865 ** error other than [SQLITE_BUSY] and [SQLITE_MISUSE]. You must call | 4102 ** error other than [SQLITE_BUSY] and [SQLITE_MISUSE]. You must call |
3866 ** [sqlite3_reset()] or [sqlite3_finalize()] in order to find one of the | 4103 ** [sqlite3_reset()] or [sqlite3_finalize()] in order to find one of the |
3867 ** specific [error codes] that better describes the error. | 4104 ** specific [error codes] that better describes the error. |
3868 ** We admit that this is a goofy design. The problem has been fixed | 4105 ** We admit that this is a goofy design. The problem has been fixed |
3869 ** with the "v2" interface. If you prepare all of your SQL statements | 4106 ** with the "v2" interface. If you prepare all of your SQL statements |
3870 ** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead | 4107 ** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead |
3871 ** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()] interfaces, | 4108 ** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()] interfaces, |
3872 ** then the more specific [error codes] are returned directly | 4109 ** then the more specific [error codes] are returned directly |
3873 ** by sqlite3_step(). The use of the "v2" interface is recommended. | 4110 ** by sqlite3_step(). The use of the "v2" interface is recommended. |
3874 */ | 4111 */ |
3875 SQLITE_API int SQLITE_STDCALL sqlite3_step(sqlite3_stmt*); | 4112 SQLITE_API int sqlite3_step(sqlite3_stmt*); |
3876 | 4113 |
3877 /* | 4114 /* |
3878 ** CAPI3REF: Number of columns in a result set | 4115 ** CAPI3REF: Number of columns in a result set |
3879 ** METHOD: sqlite3_stmt | 4116 ** METHOD: sqlite3_stmt |
3880 ** | 4117 ** |
3881 ** ^The sqlite3_data_count(P) interface returns the number of columns in the | 4118 ** ^The sqlite3_data_count(P) interface returns the number of columns in the |
3882 ** current row of the result set of [prepared statement] P. | 4119 ** current row of the result set of [prepared statement] P. |
3883 ** ^If prepared statement P does not have results ready to return | 4120 ** ^If prepared statement P does not have results ready to return |
3884 ** (via calls to the [sqlite3_column_int | sqlite3_column_*()] of | 4121 ** (via calls to the [sqlite3_column_int | sqlite3_column_*()] of |
3885 ** interfaces) then sqlite3_data_count(P) returns 0. | 4122 ** interfaces) then sqlite3_data_count(P) returns 0. |
3886 ** ^The sqlite3_data_count(P) routine also returns 0 if P is a NULL pointer. | 4123 ** ^The sqlite3_data_count(P) routine also returns 0 if P is a NULL pointer. |
3887 ** ^The sqlite3_data_count(P) routine returns 0 if the previous call to | 4124 ** ^The sqlite3_data_count(P) routine returns 0 if the previous call to |
3888 ** [sqlite3_step](P) returned [SQLITE_DONE]. ^The sqlite3_data_count(P) | 4125 ** [sqlite3_step](P) returned [SQLITE_DONE]. ^The sqlite3_data_count(P) |
3889 ** will return non-zero if previous call to [sqlite3_step](P) returned | 4126 ** will return non-zero if previous call to [sqlite3_step](P) returned |
3890 ** [SQLITE_ROW], except in the case of the [PRAGMA incremental_vacuum] | 4127 ** [SQLITE_ROW], except in the case of the [PRAGMA incremental_vacuum] |
3891 ** where it always returns zero since each step of that multi-step | 4128 ** where it always returns zero since each step of that multi-step |
3892 ** pragma returns 0 columns of data. | 4129 ** pragma returns 0 columns of data. |
3893 ** | 4130 ** |
3894 ** See also: [sqlite3_column_count()] | 4131 ** See also: [sqlite3_column_count()] |
3895 */ | 4132 */ |
3896 SQLITE_API int SQLITE_STDCALL sqlite3_data_count(sqlite3_stmt *pStmt); | 4133 SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt); |
3897 | 4134 |
3898 /* | 4135 /* |
3899 ** CAPI3REF: Fundamental Datatypes | 4136 ** CAPI3REF: Fundamental Datatypes |
3900 ** KEYWORDS: SQLITE_TEXT | 4137 ** KEYWORDS: SQLITE_TEXT |
3901 ** | 4138 ** |
3902 ** ^(Every value in SQLite has one of five fundamental datatypes: | 4139 ** ^(Every value in SQLite has one of five fundamental datatypes: |
3903 ** | 4140 ** |
3904 ** <ul> | 4141 ** <ul> |
3905 ** <li> 64-bit signed integer | 4142 ** <li> 64-bit signed integer |
3906 ** <li> 64-bit IEEE floating point number | 4143 ** <li> 64-bit IEEE floating point number |
(...skipping 169 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
4076 ** and BLOBs is freed automatically. Do <em>not</em> pass the pointers returned | 4313 ** and BLOBs is freed automatically. Do <em>not</em> pass the pointers returned |
4077 ** from [sqlite3_column_blob()], [sqlite3_column_text()], etc. into | 4314 ** from [sqlite3_column_blob()], [sqlite3_column_text()], etc. into |
4078 ** [sqlite3_free()]. | 4315 ** [sqlite3_free()]. |
4079 ** | 4316 ** |
4080 ** ^(If a memory allocation error occurs during the evaluation of any | 4317 ** ^(If a memory allocation error occurs during the evaluation of any |
4081 ** of these routines, a default value is returned. The default value | 4318 ** of these routines, a default value is returned. The default value |
4082 ** is either the integer 0, the floating point number 0.0, or a NULL | 4319 ** is either the integer 0, the floating point number 0.0, or a NULL |
4083 ** pointer. Subsequent calls to [sqlite3_errcode()] will return | 4320 ** pointer. Subsequent calls to [sqlite3_errcode()] will return |
4084 ** [SQLITE_NOMEM].)^ | 4321 ** [SQLITE_NOMEM].)^ |
4085 */ | 4322 */ |
4086 SQLITE_API const void *SQLITE_STDCALL sqlite3_column_blob(sqlite3_stmt*, int iCo
l); | 4323 SQLITE_API const void *sqlite3_column_blob(sqlite3_stmt*, int iCol); |
4087 SQLITE_API int SQLITE_STDCALL sqlite3_column_bytes(sqlite3_stmt*, int iCol); | 4324 SQLITE_API int sqlite3_column_bytes(sqlite3_stmt*, int iCol); |
4088 SQLITE_API int SQLITE_STDCALL sqlite3_column_bytes16(sqlite3_stmt*, int iCol); | 4325 SQLITE_API int sqlite3_column_bytes16(sqlite3_stmt*, int iCol); |
4089 SQLITE_API double SQLITE_STDCALL sqlite3_column_double(sqlite3_stmt*, int iCol); | 4326 SQLITE_API double sqlite3_column_double(sqlite3_stmt*, int iCol); |
4090 SQLITE_API int SQLITE_STDCALL sqlite3_column_int(sqlite3_stmt*, int iCol); | 4327 SQLITE_API int sqlite3_column_int(sqlite3_stmt*, int iCol); |
4091 SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_column_int64(sqlite3_stmt*, int
iCol); | 4328 SQLITE_API sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol); |
4092 SQLITE_API const unsigned char *SQLITE_STDCALL sqlite3_column_text(sqlite3_stmt*
, int iCol); | 4329 SQLITE_API const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol); |
4093 SQLITE_API const void *SQLITE_STDCALL sqlite3_column_text16(sqlite3_stmt*, int i
Col); | 4330 SQLITE_API const void *sqlite3_column_text16(sqlite3_stmt*, int iCol); |
4094 SQLITE_API int SQLITE_STDCALL sqlite3_column_type(sqlite3_stmt*, int iCol); | 4331 SQLITE_API int sqlite3_column_type(sqlite3_stmt*, int iCol); |
4095 SQLITE_API sqlite3_value *SQLITE_STDCALL sqlite3_column_value(sqlite3_stmt*, int
iCol); | 4332 SQLITE_API sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol); |
4096 | 4333 |
4097 /* | 4334 /* |
4098 ** CAPI3REF: Destroy A Prepared Statement Object | 4335 ** CAPI3REF: Destroy A Prepared Statement Object |
4099 ** DESTRUCTOR: sqlite3_stmt | 4336 ** DESTRUCTOR: sqlite3_stmt |
4100 ** | 4337 ** |
4101 ** ^The sqlite3_finalize() function is called to delete a [prepared statement]. | 4338 ** ^The sqlite3_finalize() function is called to delete a [prepared statement]. |
4102 ** ^If the most recent evaluation of the statement encountered no errors | 4339 ** ^If the most recent evaluation of the statement encountered no errors |
4103 ** or if the statement is never been evaluated, then sqlite3_finalize() returns | 4340 ** or if the statement is never been evaluated, then sqlite3_finalize() returns |
4104 ** SQLITE_OK. ^If the most recent evaluation of statement S failed, then | 4341 ** SQLITE_OK. ^If the most recent evaluation of statement S failed, then |
4105 ** sqlite3_finalize(S) returns the appropriate [error code] or | 4342 ** sqlite3_finalize(S) returns the appropriate [error code] or |
4106 ** [extended error code]. | 4343 ** [extended error code]. |
4107 ** | 4344 ** |
4108 ** ^The sqlite3_finalize(S) routine can be called at any point during | 4345 ** ^The sqlite3_finalize(S) routine can be called at any point during |
4109 ** the life cycle of [prepared statement] S: | 4346 ** the life cycle of [prepared statement] S: |
4110 ** before statement S is ever evaluated, after | 4347 ** before statement S is ever evaluated, after |
4111 ** one or more calls to [sqlite3_reset()], or after any call | 4348 ** one or more calls to [sqlite3_reset()], or after any call |
4112 ** to [sqlite3_step()] regardless of whether or not the statement has | 4349 ** to [sqlite3_step()] regardless of whether or not the statement has |
4113 ** completed execution. | 4350 ** completed execution. |
4114 ** | 4351 ** |
4115 ** ^Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op. | 4352 ** ^Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op. |
4116 ** | 4353 ** |
4117 ** The application must finalize every [prepared statement] in order to avoid | 4354 ** The application must finalize every [prepared statement] in order to avoid |
4118 ** resource leaks. It is a grievous error for the application to try to use | 4355 ** resource leaks. It is a grievous error for the application to try to use |
4119 ** a prepared statement after it has been finalized. Any use of a prepared | 4356 ** a prepared statement after it has been finalized. Any use of a prepared |
4120 ** statement after it has been finalized can result in undefined and | 4357 ** statement after it has been finalized can result in undefined and |
4121 ** undesirable behavior such as segfaults and heap corruption. | 4358 ** undesirable behavior such as segfaults and heap corruption. |
4122 */ | 4359 */ |
4123 SQLITE_API int SQLITE_STDCALL sqlite3_finalize(sqlite3_stmt *pStmt); | 4360 SQLITE_API int sqlite3_finalize(sqlite3_stmt *pStmt); |
4124 | 4361 |
4125 /* | 4362 /* |
4126 ** CAPI3REF: Reset A Prepared Statement Object | 4363 ** CAPI3REF: Reset A Prepared Statement Object |
4127 ** METHOD: sqlite3_stmt | 4364 ** METHOD: sqlite3_stmt |
4128 ** | 4365 ** |
4129 ** The sqlite3_reset() function is called to reset a [prepared statement] | 4366 ** The sqlite3_reset() function is called to reset a [prepared statement] |
4130 ** object back to its initial state, ready to be re-executed. | 4367 ** object back to its initial state, ready to be re-executed. |
4131 ** ^Any SQL statement variables that had values bound to them using | 4368 ** ^Any SQL statement variables that had values bound to them using |
4132 ** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values. | 4369 ** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values. |
4133 ** Use [sqlite3_clear_bindings()] to reset the bindings. | 4370 ** Use [sqlite3_clear_bindings()] to reset the bindings. |
4134 ** | 4371 ** |
4135 ** ^The [sqlite3_reset(S)] interface resets the [prepared statement] S | 4372 ** ^The [sqlite3_reset(S)] interface resets the [prepared statement] S |
4136 ** back to the beginning of its program. | 4373 ** back to the beginning of its program. |
4137 ** | 4374 ** |
4138 ** ^If the most recent call to [sqlite3_step(S)] for the | 4375 ** ^If the most recent call to [sqlite3_step(S)] for the |
4139 ** [prepared statement] S returned [SQLITE_ROW] or [SQLITE_DONE], | 4376 ** [prepared statement] S returned [SQLITE_ROW] or [SQLITE_DONE], |
4140 ** or if [sqlite3_step(S)] has never before been called on S, | 4377 ** or if [sqlite3_step(S)] has never before been called on S, |
4141 ** then [sqlite3_reset(S)] returns [SQLITE_OK]. | 4378 ** then [sqlite3_reset(S)] returns [SQLITE_OK]. |
4142 ** | 4379 ** |
4143 ** ^If the most recent call to [sqlite3_step(S)] for the | 4380 ** ^If the most recent call to [sqlite3_step(S)] for the |
4144 ** [prepared statement] S indicated an error, then | 4381 ** [prepared statement] S indicated an error, then |
4145 ** [sqlite3_reset(S)] returns an appropriate [error code]. | 4382 ** [sqlite3_reset(S)] returns an appropriate [error code]. |
4146 ** | 4383 ** |
4147 ** ^The [sqlite3_reset(S)] interface does not change the values | 4384 ** ^The [sqlite3_reset(S)] interface does not change the values |
4148 ** of any [sqlite3_bind_blob|bindings] on the [prepared statement] S. | 4385 ** of any [sqlite3_bind_blob|bindings] on the [prepared statement] S. |
4149 */ | 4386 */ |
4150 SQLITE_API int SQLITE_STDCALL sqlite3_reset(sqlite3_stmt *pStmt); | 4387 SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt); |
4151 | 4388 |
4152 /* | 4389 /* |
4153 ** CAPI3REF: Create Or Redefine SQL Functions | 4390 ** CAPI3REF: Create Or Redefine SQL Functions |
4154 ** KEYWORDS: {function creation routines} | 4391 ** KEYWORDS: {function creation routines} |
4155 ** KEYWORDS: {application-defined SQL function} | 4392 ** KEYWORDS: {application-defined SQL function} |
4156 ** KEYWORDS: {application-defined SQL functions} | 4393 ** KEYWORDS: {application-defined SQL functions} |
4157 ** METHOD: sqlite3 | 4394 ** METHOD: sqlite3 |
4158 ** | 4395 ** |
4159 ** ^These functions (collectively known as "function creation routines") | 4396 ** ^These functions (collectively known as "function creation routines") |
4160 ** are used to add SQL functions or aggregates or to redefine the behavior | 4397 ** are used to add SQL functions or aggregates or to redefine the behavior |
(...skipping 79 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
4240 ** is a closer match than a function where the encoding difference is | 4477 ** is a closer match than a function where the encoding difference is |
4241 ** between UTF8 and UTF16. | 4478 ** between UTF8 and UTF16. |
4242 ** | 4479 ** |
4243 ** ^Built-in functions may be overloaded by new application-defined functions. | 4480 ** ^Built-in functions may be overloaded by new application-defined functions. |
4244 ** | 4481 ** |
4245 ** ^An application-defined function is permitted to call other | 4482 ** ^An application-defined function is permitted to call other |
4246 ** SQLite interfaces. However, such calls must not | 4483 ** SQLite interfaces. However, such calls must not |
4247 ** close the database connection nor finalize or reset the prepared | 4484 ** close the database connection nor finalize or reset the prepared |
4248 ** statement in which the function is running. | 4485 ** statement in which the function is running. |
4249 */ | 4486 */ |
4250 SQLITE_API int SQLITE_STDCALL sqlite3_create_function( | 4487 SQLITE_API int sqlite3_create_function( |
4251 sqlite3 *db, | 4488 sqlite3 *db, |
4252 const char *zFunctionName, | 4489 const char *zFunctionName, |
4253 int nArg, | 4490 int nArg, |
4254 int eTextRep, | 4491 int eTextRep, |
4255 void *pApp, | 4492 void *pApp, |
4256 void (*xFunc)(sqlite3_context*,int,sqlite3_value**), | 4493 void (*xFunc)(sqlite3_context*,int,sqlite3_value**), |
4257 void (*xStep)(sqlite3_context*,int,sqlite3_value**), | 4494 void (*xStep)(sqlite3_context*,int,sqlite3_value**), |
4258 void (*xFinal)(sqlite3_context*) | 4495 void (*xFinal)(sqlite3_context*) |
4259 ); | 4496 ); |
4260 SQLITE_API int SQLITE_STDCALL sqlite3_create_function16( | 4497 SQLITE_API int sqlite3_create_function16( |
4261 sqlite3 *db, | 4498 sqlite3 *db, |
4262 const void *zFunctionName, | 4499 const void *zFunctionName, |
4263 int nArg, | 4500 int nArg, |
4264 int eTextRep, | 4501 int eTextRep, |
4265 void *pApp, | 4502 void *pApp, |
4266 void (*xFunc)(sqlite3_context*,int,sqlite3_value**), | 4503 void (*xFunc)(sqlite3_context*,int,sqlite3_value**), |
4267 void (*xStep)(sqlite3_context*,int,sqlite3_value**), | 4504 void (*xStep)(sqlite3_context*,int,sqlite3_value**), |
4268 void (*xFinal)(sqlite3_context*) | 4505 void (*xFinal)(sqlite3_context*) |
4269 ); | 4506 ); |
4270 SQLITE_API int SQLITE_STDCALL sqlite3_create_function_v2( | 4507 SQLITE_API int sqlite3_create_function_v2( |
4271 sqlite3 *db, | 4508 sqlite3 *db, |
4272 const char *zFunctionName, | 4509 const char *zFunctionName, |
4273 int nArg, | 4510 int nArg, |
4274 int eTextRep, | 4511 int eTextRep, |
4275 void *pApp, | 4512 void *pApp, |
4276 void (*xFunc)(sqlite3_context*,int,sqlite3_value**), | 4513 void (*xFunc)(sqlite3_context*,int,sqlite3_value**), |
4277 void (*xStep)(sqlite3_context*,int,sqlite3_value**), | 4514 void (*xStep)(sqlite3_context*,int,sqlite3_value**), |
4278 void (*xFinal)(sqlite3_context*), | 4515 void (*xFinal)(sqlite3_context*), |
4279 void(*xDestroy)(void*) | 4516 void(*xDestroy)(void*) |
4280 ); | 4517 ); |
(...skipping 25 matching lines...) Expand all Loading... |
4306 ** CAPI3REF: Deprecated Functions | 4543 ** CAPI3REF: Deprecated Functions |
4307 ** DEPRECATED | 4544 ** DEPRECATED |
4308 ** | 4545 ** |
4309 ** These functions are [deprecated]. In order to maintain | 4546 ** These functions are [deprecated]. In order to maintain |
4310 ** backwards compatibility with older code, these functions continue | 4547 ** backwards compatibility with older code, these functions continue |
4311 ** to be supported. However, new applications should avoid | 4548 ** to be supported. However, new applications should avoid |
4312 ** the use of these functions. To encourage programmers to avoid | 4549 ** the use of these functions. To encourage programmers to avoid |
4313 ** these functions, we will not explain what they do. | 4550 ** these functions, we will not explain what they do. |
4314 */ | 4551 */ |
4315 #ifndef SQLITE_OMIT_DEPRECATED | 4552 #ifndef SQLITE_OMIT_DEPRECATED |
4316 SQLITE_API SQLITE_DEPRECATED int SQLITE_STDCALL sqlite3_aggregate_count(sqlite3_
context*); | 4553 SQLITE_API SQLITE_DEPRECATED int sqlite3_aggregate_count(sqlite3_context*); |
4317 SQLITE_API SQLITE_DEPRECATED int SQLITE_STDCALL sqlite3_expired(sqlite3_stmt*); | 4554 SQLITE_API SQLITE_DEPRECATED int sqlite3_expired(sqlite3_stmt*); |
4318 SQLITE_API SQLITE_DEPRECATED int SQLITE_STDCALL sqlite3_transfer_bindings(sqlite
3_stmt*, sqlite3_stmt*); | 4555 SQLITE_API SQLITE_DEPRECATED int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite
3_stmt*); |
4319 SQLITE_API SQLITE_DEPRECATED int SQLITE_STDCALL sqlite3_global_recover(void); | 4556 SQLITE_API SQLITE_DEPRECATED int sqlite3_global_recover(void); |
4320 SQLITE_API SQLITE_DEPRECATED void SQLITE_STDCALL sqlite3_thread_cleanup(void); | 4557 SQLITE_API SQLITE_DEPRECATED void sqlite3_thread_cleanup(void); |
4321 SQLITE_API SQLITE_DEPRECATED int SQLITE_STDCALL sqlite3_memory_alarm(void(*)(voi
d*,sqlite3_int64,int), | 4558 SQLITE_API SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int6
4,int), |
4322 void*,sqlite3_int64); | 4559 void*,sqlite3_int64); |
4323 #endif | 4560 #endif |
4324 | 4561 |
4325 /* | 4562 /* |
4326 ** CAPI3REF: Obtaining SQL Values | 4563 ** CAPI3REF: Obtaining SQL Values |
4327 ** METHOD: sqlite3_value | 4564 ** METHOD: sqlite3_value |
4328 ** | 4565 ** |
4329 ** The C-language implementation of SQL functions and aggregates uses | 4566 ** The C-language implementation of SQL functions and aggregates uses |
4330 ** this set of interface routines to access the parameter values on | 4567 ** this set of interface routines to access the parameter values on |
4331 ** the function or aggregate. | 4568 ** the function or aggregate. |
(...skipping 29 matching lines...) Expand all Loading... |
4361 ** | 4598 ** |
4362 ** Please pay particular attention to the fact that the pointer returned | 4599 ** Please pay particular attention to the fact that the pointer returned |
4363 ** from [sqlite3_value_blob()], [sqlite3_value_text()], or | 4600 ** from [sqlite3_value_blob()], [sqlite3_value_text()], or |
4364 ** [sqlite3_value_text16()] can be invalidated by a subsequent call to | 4601 ** [sqlite3_value_text16()] can be invalidated by a subsequent call to |
4365 ** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()], | 4602 ** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()], |
4366 ** or [sqlite3_value_text16()]. | 4603 ** or [sqlite3_value_text16()]. |
4367 ** | 4604 ** |
4368 ** These routines must be called from the same thread as | 4605 ** These routines must be called from the same thread as |
4369 ** the SQL function that supplied the [sqlite3_value*] parameters. | 4606 ** the SQL function that supplied the [sqlite3_value*] parameters. |
4370 */ | 4607 */ |
4371 SQLITE_API const void *SQLITE_STDCALL sqlite3_value_blob(sqlite3_value*); | 4608 SQLITE_API const void *sqlite3_value_blob(sqlite3_value*); |
4372 SQLITE_API int SQLITE_STDCALL sqlite3_value_bytes(sqlite3_value*); | 4609 SQLITE_API int sqlite3_value_bytes(sqlite3_value*); |
4373 SQLITE_API int SQLITE_STDCALL sqlite3_value_bytes16(sqlite3_value*); | 4610 SQLITE_API int sqlite3_value_bytes16(sqlite3_value*); |
4374 SQLITE_API double SQLITE_STDCALL sqlite3_value_double(sqlite3_value*); | 4611 SQLITE_API double sqlite3_value_double(sqlite3_value*); |
4375 SQLITE_API int SQLITE_STDCALL sqlite3_value_int(sqlite3_value*); | 4612 SQLITE_API int sqlite3_value_int(sqlite3_value*); |
4376 SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_value_int64(sqlite3_value*); | 4613 SQLITE_API sqlite3_int64 sqlite3_value_int64(sqlite3_value*); |
4377 SQLITE_API const unsigned char *SQLITE_STDCALL sqlite3_value_text(sqlite3_value*
); | 4614 SQLITE_API const unsigned char *sqlite3_value_text(sqlite3_value*); |
4378 SQLITE_API const void *SQLITE_STDCALL sqlite3_value_text16(sqlite3_value*); | 4615 SQLITE_API const void *sqlite3_value_text16(sqlite3_value*); |
4379 SQLITE_API const void *SQLITE_STDCALL sqlite3_value_text16le(sqlite3_value*); | 4616 SQLITE_API const void *sqlite3_value_text16le(sqlite3_value*); |
4380 SQLITE_API const void *SQLITE_STDCALL sqlite3_value_text16be(sqlite3_value*); | 4617 SQLITE_API const void *sqlite3_value_text16be(sqlite3_value*); |
4381 SQLITE_API int SQLITE_STDCALL sqlite3_value_type(sqlite3_value*); | 4618 SQLITE_API int sqlite3_value_type(sqlite3_value*); |
4382 SQLITE_API int SQLITE_STDCALL sqlite3_value_numeric_type(sqlite3_value*); | 4619 SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*); |
4383 | 4620 |
4384 /* | 4621 /* |
4385 ** CAPI3REF: Finding The Subtype Of SQL Values | 4622 ** CAPI3REF: Finding The Subtype Of SQL Values |
4386 ** METHOD: sqlite3_value | 4623 ** METHOD: sqlite3_value |
4387 ** | 4624 ** |
4388 ** The sqlite3_value_subtype(V) function returns the subtype for | 4625 ** The sqlite3_value_subtype(V) function returns the subtype for |
4389 ** an [application-defined SQL function] argument V. The subtype | 4626 ** an [application-defined SQL function] argument V. The subtype |
4390 ** information can be used to pass a limited amount of context from | 4627 ** information can be used to pass a limited amount of context from |
4391 ** one SQL function to another. Use the [sqlite3_result_subtype()] | 4628 ** one SQL function to another. Use the [sqlite3_result_subtype()] |
4392 ** routine to set the subtype for the return value of an SQL function. | 4629 ** routine to set the subtype for the return value of an SQL function. |
4393 ** | 4630 ** |
4394 ** SQLite makes no use of subtype itself. It merely passes the subtype | 4631 ** SQLite makes no use of subtype itself. It merely passes the subtype |
4395 ** from the result of one [application-defined SQL function] into the | 4632 ** from the result of one [application-defined SQL function] into the |
4396 ** input of another. | 4633 ** input of another. |
4397 */ | 4634 */ |
4398 SQLITE_API unsigned int SQLITE_STDCALL sqlite3_value_subtype(sqlite3_value*); | 4635 SQLITE_API unsigned int sqlite3_value_subtype(sqlite3_value*); |
4399 | 4636 |
4400 /* | 4637 /* |
4401 ** CAPI3REF: Copy And Free SQL Values | 4638 ** CAPI3REF: Copy And Free SQL Values |
4402 ** METHOD: sqlite3_value | 4639 ** METHOD: sqlite3_value |
4403 ** | 4640 ** |
4404 ** ^The sqlite3_value_dup(V) interface makes a copy of the [sqlite3_value] | 4641 ** ^The sqlite3_value_dup(V) interface makes a copy of the [sqlite3_value] |
4405 ** object D and returns a pointer to that copy. ^The [sqlite3_value] returned | 4642 ** object D and returns a pointer to that copy. ^The [sqlite3_value] returned |
4406 ** is a [protected sqlite3_value] object even if the input is not. | 4643 ** is a [protected sqlite3_value] object even if the input is not. |
4407 ** ^The sqlite3_value_dup(V) interface returns NULL if V is NULL or if a | 4644 ** ^The sqlite3_value_dup(V) interface returns NULL if V is NULL or if a |
4408 ** memory allocation fails. | 4645 ** memory allocation fails. |
4409 ** | 4646 ** |
4410 ** ^The sqlite3_value_free(V) interface frees an [sqlite3_value] object | 4647 ** ^The sqlite3_value_free(V) interface frees an [sqlite3_value] object |
4411 ** previously obtained from [sqlite3_value_dup()]. ^If V is a NULL pointer | 4648 ** previously obtained from [sqlite3_value_dup()]. ^If V is a NULL pointer |
4412 ** then sqlite3_value_free(V) is a harmless no-op. | 4649 ** then sqlite3_value_free(V) is a harmless no-op. |
4413 */ | 4650 */ |
4414 SQLITE_API sqlite3_value *SQLITE_STDCALL sqlite3_value_dup(const sqlite3_value*)
; | 4651 SQLITE_API sqlite3_value *sqlite3_value_dup(const sqlite3_value*); |
4415 SQLITE_API void SQLITE_STDCALL sqlite3_value_free(sqlite3_value*); | 4652 SQLITE_API void sqlite3_value_free(sqlite3_value*); |
4416 | 4653 |
4417 /* | 4654 /* |
4418 ** CAPI3REF: Obtain Aggregate Function Context | 4655 ** CAPI3REF: Obtain Aggregate Function Context |
4419 ** METHOD: sqlite3_context | 4656 ** METHOD: sqlite3_context |
4420 ** | 4657 ** |
4421 ** Implementations of aggregate SQL functions use this | 4658 ** Implementations of aggregate SQL functions use this |
4422 ** routine to allocate memory for storing their state. | 4659 ** routine to allocate memory for storing their state. |
4423 ** | 4660 ** |
4424 ** ^The first time the sqlite3_aggregate_context(C,N) routine is called | 4661 ** ^The first time the sqlite3_aggregate_context(C,N) routine is called |
4425 ** for a particular aggregate function, SQLite | 4662 ** for a particular aggregate function, SQLite |
(...skipping 24 matching lines...) Expand all Loading... |
4450 ** sqlite3_aggregate_context() when the aggregate query concludes. | 4687 ** sqlite3_aggregate_context() when the aggregate query concludes. |
4451 ** | 4688 ** |
4452 ** The first parameter must be a copy of the | 4689 ** The first parameter must be a copy of the |
4453 ** [sqlite3_context | SQL function context] that is the first parameter | 4690 ** [sqlite3_context | SQL function context] that is the first parameter |
4454 ** to the xStep or xFinal callback routine that implements the aggregate | 4691 ** to the xStep or xFinal callback routine that implements the aggregate |
4455 ** function. | 4692 ** function. |
4456 ** | 4693 ** |
4457 ** This routine must be called from the same thread in which | 4694 ** This routine must be called from the same thread in which |
4458 ** the aggregate SQL function is running. | 4695 ** the aggregate SQL function is running. |
4459 */ | 4696 */ |
4460 SQLITE_API void *SQLITE_STDCALL sqlite3_aggregate_context(sqlite3_context*, int
nBytes); | 4697 SQLITE_API void *sqlite3_aggregate_context(sqlite3_context*, int nBytes); |
4461 | 4698 |
4462 /* | 4699 /* |
4463 ** CAPI3REF: User Data For Functions | 4700 ** CAPI3REF: User Data For Functions |
4464 ** METHOD: sqlite3_context | 4701 ** METHOD: sqlite3_context |
4465 ** | 4702 ** |
4466 ** ^The sqlite3_user_data() interface returns a copy of | 4703 ** ^The sqlite3_user_data() interface returns a copy of |
4467 ** the pointer that was the pUserData parameter (the 5th parameter) | 4704 ** the pointer that was the pUserData parameter (the 5th parameter) |
4468 ** of the [sqlite3_create_function()] | 4705 ** of the [sqlite3_create_function()] |
4469 ** and [sqlite3_create_function16()] routines that originally | 4706 ** and [sqlite3_create_function16()] routines that originally |
4470 ** registered the application defined function. | 4707 ** registered the application defined function. |
4471 ** | 4708 ** |
4472 ** This routine must be called from the same thread in which | 4709 ** This routine must be called from the same thread in which |
4473 ** the application-defined function is running. | 4710 ** the application-defined function is running. |
4474 */ | 4711 */ |
4475 SQLITE_API void *SQLITE_STDCALL sqlite3_user_data(sqlite3_context*); | 4712 SQLITE_API void *sqlite3_user_data(sqlite3_context*); |
4476 | 4713 |
4477 /* | 4714 /* |
4478 ** CAPI3REF: Database Connection For Functions | 4715 ** CAPI3REF: Database Connection For Functions |
4479 ** METHOD: sqlite3_context | 4716 ** METHOD: sqlite3_context |
4480 ** | 4717 ** |
4481 ** ^The sqlite3_context_db_handle() interface returns a copy of | 4718 ** ^The sqlite3_context_db_handle() interface returns a copy of |
4482 ** the pointer to the [database connection] (the 1st parameter) | 4719 ** the pointer to the [database connection] (the 1st parameter) |
4483 ** of the [sqlite3_create_function()] | 4720 ** of the [sqlite3_create_function()] |
4484 ** and [sqlite3_create_function16()] routines that originally | 4721 ** and [sqlite3_create_function16()] routines that originally |
4485 ** registered the application defined function. | 4722 ** registered the application defined function. |
4486 */ | 4723 */ |
4487 SQLITE_API sqlite3 *SQLITE_STDCALL sqlite3_context_db_handle(sqlite3_context*); | 4724 SQLITE_API sqlite3 *sqlite3_context_db_handle(sqlite3_context*); |
4488 | 4725 |
4489 /* | 4726 /* |
4490 ** CAPI3REF: Function Auxiliary Data | 4727 ** CAPI3REF: Function Auxiliary Data |
4491 ** METHOD: sqlite3_context | 4728 ** METHOD: sqlite3_context |
4492 ** | 4729 ** |
4493 ** These functions may be used by (non-aggregate) SQL functions to | 4730 ** These functions may be used by (non-aggregate) SQL functions to |
4494 ** associate metadata with argument values. If the same value is passed to | 4731 ** associate metadata with argument values. If the same value is passed to |
4495 ** multiple invocations of the same SQL function during query execution, under | 4732 ** multiple invocations of the same SQL function during query execution, under |
4496 ** some circumstances the associated metadata may be preserved. An example | 4733 ** some circumstances the associated metadata may be preserved. An example |
4497 ** of where this might be useful is in a regular-expression matching | 4734 ** of where this might be useful is in a regular-expression matching |
(...skipping 11 matching lines...) Expand all Loading... |
4509 ** | 4746 ** |
4510 ** ^The sqlite3_set_auxdata(C,N,P,X) interface saves P as metadata for the N-th | 4747 ** ^The sqlite3_set_auxdata(C,N,P,X) interface saves P as metadata for the N-th |
4511 ** argument of the application-defined function. ^Subsequent | 4748 ** argument of the application-defined function. ^Subsequent |
4512 ** calls to sqlite3_get_auxdata(C,N) return P from the most recent | 4749 ** calls to sqlite3_get_auxdata(C,N) return P from the most recent |
4513 ** sqlite3_set_auxdata(C,N,P,X) call if the metadata is still valid or | 4750 ** sqlite3_set_auxdata(C,N,P,X) call if the metadata is still valid or |
4514 ** NULL if the metadata has been discarded. | 4751 ** NULL if the metadata has been discarded. |
4515 ** ^After each call to sqlite3_set_auxdata(C,N,P,X) where X is not NULL, | 4752 ** ^After each call to sqlite3_set_auxdata(C,N,P,X) where X is not NULL, |
4516 ** SQLite will invoke the destructor function X with parameter P exactly | 4753 ** SQLite will invoke the destructor function X with parameter P exactly |
4517 ** once, when the metadata is discarded. | 4754 ** once, when the metadata is discarded. |
4518 ** SQLite is free to discard the metadata at any time, including: <ul> | 4755 ** SQLite is free to discard the metadata at any time, including: <ul> |
4519 ** <li> when the corresponding function parameter changes, or | 4756 ** <li> ^(when the corresponding function parameter changes)^, or |
4520 ** <li> when [sqlite3_reset()] or [sqlite3_finalize()] is called for the | 4757 ** <li> ^(when [sqlite3_reset()] or [sqlite3_finalize()] is called for the |
4521 ** SQL statement, or | 4758 ** SQL statement)^, or |
4522 ** <li> when sqlite3_set_auxdata() is invoked again on the same parameter, or | 4759 ** <li> ^(when sqlite3_set_auxdata() is invoked again on the same |
4523 ** <li> during the original sqlite3_set_auxdata() call when a memory | 4760 ** parameter)^, or |
4524 ** allocation error occurs. </ul>)^ | 4761 ** <li> ^(during the original sqlite3_set_auxdata() call when a memory |
| 4762 ** allocation error occurs.)^ </ul> |
4525 ** | 4763 ** |
4526 ** Note the last bullet in particular. The destructor X in | 4764 ** Note the last bullet in particular. The destructor X in |
4527 ** sqlite3_set_auxdata(C,N,P,X) might be called immediately, before the | 4765 ** sqlite3_set_auxdata(C,N,P,X) might be called immediately, before the |
4528 ** sqlite3_set_auxdata() interface even returns. Hence sqlite3_set_auxdata() | 4766 ** sqlite3_set_auxdata() interface even returns. Hence sqlite3_set_auxdata() |
4529 ** should be called near the end of the function implementation and the | 4767 ** should be called near the end of the function implementation and the |
4530 ** function implementation should not make any use of P after | 4768 ** function implementation should not make any use of P after |
4531 ** sqlite3_set_auxdata() has been called. | 4769 ** sqlite3_set_auxdata() has been called. |
4532 ** | 4770 ** |
4533 ** ^(In practice, metadata is preserved between function calls for | 4771 ** ^(In practice, metadata is preserved between function calls for |
4534 ** function parameters that are compile-time constants, including literal | 4772 ** function parameters that are compile-time constants, including literal |
4535 ** values and [parameters] and expressions composed from the same.)^ | 4773 ** values and [parameters] and expressions composed from the same.)^ |
4536 ** | 4774 ** |
4537 ** These routines must be called from the same thread in which | 4775 ** These routines must be called from the same thread in which |
4538 ** the SQL function is running. | 4776 ** the SQL function is running. |
4539 */ | 4777 */ |
4540 SQLITE_API void *SQLITE_STDCALL sqlite3_get_auxdata(sqlite3_context*, int N); | 4778 SQLITE_API void *sqlite3_get_auxdata(sqlite3_context*, int N); |
4541 SQLITE_API void SQLITE_STDCALL sqlite3_set_auxdata(sqlite3_context*, int N, void
*, void (*)(void*)); | 4779 SQLITE_API void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(voi
d*)); |
4542 | 4780 |
4543 | 4781 |
4544 /* | 4782 /* |
4545 ** CAPI3REF: Constants Defining Special Destructor Behavior | 4783 ** CAPI3REF: Constants Defining Special Destructor Behavior |
4546 ** | 4784 ** |
4547 ** These are special values for the destructor that is passed in as the | 4785 ** These are special values for the destructor that is passed in as the |
4548 ** final argument to routines like [sqlite3_result_blob()]. ^If the destructor | 4786 ** final argument to routines like [sqlite3_result_blob()]. ^If the destructor |
4549 ** argument is SQLITE_STATIC, it means that the content pointer is constant | 4787 ** argument is SQLITE_STATIC, it means that the content pointer is constant |
4550 ** and will never change. It does not need to be destroyed. ^The | 4788 ** and will never change. It does not need to be destroyed. ^The |
4551 ** SQLITE_TRANSIENT value means that the content will likely change in | 4789 ** SQLITE_TRANSIENT value means that the content will likely change in |
(...skipping 115 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
4667 ** so that the [sqlite3_value] specified in the parameter may change or | 4905 ** so that the [sqlite3_value] specified in the parameter may change or |
4668 ** be deallocated after sqlite3_result_value() returns without harm. | 4906 ** be deallocated after sqlite3_result_value() returns without harm. |
4669 ** ^A [protected sqlite3_value] object may always be used where an | 4907 ** ^A [protected sqlite3_value] object may always be used where an |
4670 ** [unprotected sqlite3_value] object is required, so either | 4908 ** [unprotected sqlite3_value] object is required, so either |
4671 ** kind of [sqlite3_value] object can be used with this interface. | 4909 ** kind of [sqlite3_value] object can be used with this interface. |
4672 ** | 4910 ** |
4673 ** If these routines are called from within the different thread | 4911 ** If these routines are called from within the different thread |
4674 ** than the one containing the application-defined function that received | 4912 ** than the one containing the application-defined function that received |
4675 ** the [sqlite3_context] pointer, the results are undefined. | 4913 ** the [sqlite3_context] pointer, the results are undefined. |
4676 */ | 4914 */ |
4677 SQLITE_API void SQLITE_STDCALL sqlite3_result_blob(sqlite3_context*, const void*
, int, void(*)(void*)); | 4915 SQLITE_API void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(
void*)); |
4678 SQLITE_API void SQLITE_STDCALL sqlite3_result_blob64(sqlite3_context*,const void
*, | 4916 SQLITE_API void sqlite3_result_blob64(sqlite3_context*,const void*, |
4679 sqlite3_uint64,void(*)(void*)); | 4917 sqlite3_uint64,void(*)(void*)); |
4680 SQLITE_API void SQLITE_STDCALL sqlite3_result_double(sqlite3_context*, double); | 4918 SQLITE_API void sqlite3_result_double(sqlite3_context*, double); |
4681 SQLITE_API void SQLITE_STDCALL sqlite3_result_error(sqlite3_context*, const char
*, int); | 4919 SQLITE_API void sqlite3_result_error(sqlite3_context*, const char*, int); |
4682 SQLITE_API void SQLITE_STDCALL sqlite3_result_error16(sqlite3_context*, const vo
id*, int); | 4920 SQLITE_API void sqlite3_result_error16(sqlite3_context*, const void*, int); |
4683 SQLITE_API void SQLITE_STDCALL sqlite3_result_error_toobig(sqlite3_context*); | 4921 SQLITE_API void sqlite3_result_error_toobig(sqlite3_context*); |
4684 SQLITE_API void SQLITE_STDCALL sqlite3_result_error_nomem(sqlite3_context*); | 4922 SQLITE_API void sqlite3_result_error_nomem(sqlite3_context*); |
4685 SQLITE_API void SQLITE_STDCALL sqlite3_result_error_code(sqlite3_context*, int); | 4923 SQLITE_API void sqlite3_result_error_code(sqlite3_context*, int); |
4686 SQLITE_API void SQLITE_STDCALL sqlite3_result_int(sqlite3_context*, int); | 4924 SQLITE_API void sqlite3_result_int(sqlite3_context*, int); |
4687 SQLITE_API void SQLITE_STDCALL sqlite3_result_int64(sqlite3_context*, sqlite3_in
t64); | 4925 SQLITE_API void sqlite3_result_int64(sqlite3_context*, sqlite3_int64); |
4688 SQLITE_API void SQLITE_STDCALL sqlite3_result_null(sqlite3_context*); | 4926 SQLITE_API void sqlite3_result_null(sqlite3_context*); |
4689 SQLITE_API void SQLITE_STDCALL sqlite3_result_text(sqlite3_context*, const char*
, int, void(*)(void*)); | 4927 SQLITE_API void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(
void*)); |
4690 SQLITE_API void SQLITE_STDCALL sqlite3_result_text64(sqlite3_context*, const cha
r*,sqlite3_uint64, | 4928 SQLITE_API void sqlite3_result_text64(sqlite3_context*, const char*,sqlite3_uint
64, |
4691 void(*)(void*), unsigned char encoding); | 4929 void(*)(void*), unsigned char encoding); |
4692 SQLITE_API void SQLITE_STDCALL sqlite3_result_text16(sqlite3_context*, const voi
d*, int, void(*)(void*)); | 4930 SQLITE_API void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*
)(void*)); |
4693 SQLITE_API void SQLITE_STDCALL sqlite3_result_text16le(sqlite3_context*, const v
oid*, int,void(*)(void*)); | 4931 SQLITE_API void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(
*)(void*)); |
4694 SQLITE_API void SQLITE_STDCALL sqlite3_result_text16be(sqlite3_context*, const v
oid*, int,void(*)(void*)); | 4932 SQLITE_API void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(
*)(void*)); |
4695 SQLITE_API void SQLITE_STDCALL sqlite3_result_value(sqlite3_context*, sqlite3_va
lue*); | 4933 SQLITE_API void sqlite3_result_value(sqlite3_context*, sqlite3_value*); |
4696 SQLITE_API void SQLITE_STDCALL sqlite3_result_zeroblob(sqlite3_context*, int n); | 4934 SQLITE_API void sqlite3_result_zeroblob(sqlite3_context*, int n); |
4697 SQLITE_API int SQLITE_STDCALL sqlite3_result_zeroblob64(sqlite3_context*, sqlite
3_uint64 n); | 4935 SQLITE_API int sqlite3_result_zeroblob64(sqlite3_context*, sqlite3_uint64 n); |
4698 | 4936 |
4699 | 4937 |
4700 /* | 4938 /* |
4701 ** CAPI3REF: Setting The Subtype Of An SQL Function | 4939 ** CAPI3REF: Setting The Subtype Of An SQL Function |
4702 ** METHOD: sqlite3_context | 4940 ** METHOD: sqlite3_context |
4703 ** | 4941 ** |
4704 ** The sqlite3_result_subtype(C,T) function causes the subtype of | 4942 ** The sqlite3_result_subtype(C,T) function causes the subtype of |
4705 ** the result from the [application-defined SQL function] with | 4943 ** the result from the [application-defined SQL function] with |
4706 ** [sqlite3_context] C to be the value T. Only the lower 8 bits | 4944 ** [sqlite3_context] C to be the value T. Only the lower 8 bits |
4707 ** of the subtype T are preserved in current versions of SQLite; | 4945 ** of the subtype T are preserved in current versions of SQLite; |
4708 ** higher order bits are discarded. | 4946 ** higher order bits are discarded. |
4709 ** The number of subtype bytes preserved by SQLite might increase | 4947 ** The number of subtype bytes preserved by SQLite might increase |
4710 ** in future releases of SQLite. | 4948 ** in future releases of SQLite. |
4711 */ | 4949 */ |
4712 SQLITE_API void SQLITE_STDCALL sqlite3_result_subtype(sqlite3_context*,unsigned
int); | 4950 SQLITE_API void sqlite3_result_subtype(sqlite3_context*,unsigned int); |
4713 | 4951 |
4714 /* | 4952 /* |
4715 ** CAPI3REF: Define New Collating Sequences | 4953 ** CAPI3REF: Define New Collating Sequences |
4716 ** METHOD: sqlite3 | 4954 ** METHOD: sqlite3 |
4717 ** | 4955 ** |
4718 ** ^These functions add, remove, or modify a [collation] associated | 4956 ** ^These functions add, remove, or modify a [collation] associated |
4719 ** with the [database connection] specified as the first argument. | 4957 ** with the [database connection] specified as the first argument. |
4720 ** | 4958 ** |
4721 ** ^The name of the collation is a UTF-8 string | 4959 ** ^The name of the collation is a UTF-8 string |
4722 ** for sqlite3_create_collation() and sqlite3_create_collation_v2() | 4960 ** for sqlite3_create_collation() and sqlite3_create_collation_v2() |
(...skipping 61 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
4784 ** sqlite3_create_collation_v2() function fails. Applications that invoke | 5022 ** sqlite3_create_collation_v2() function fails. Applications that invoke |
4785 ** sqlite3_create_collation_v2() with a non-NULL xDestroy argument should | 5023 ** sqlite3_create_collation_v2() with a non-NULL xDestroy argument should |
4786 ** check the return code and dispose of the application data pointer | 5024 ** check the return code and dispose of the application data pointer |
4787 ** themselves rather than expecting SQLite to deal with it for them. | 5025 ** themselves rather than expecting SQLite to deal with it for them. |
4788 ** This is different from every other SQLite interface. The inconsistency | 5026 ** This is different from every other SQLite interface. The inconsistency |
4789 ** is unfortunate but cannot be changed without breaking backwards | 5027 ** is unfortunate but cannot be changed without breaking backwards |
4790 ** compatibility. | 5028 ** compatibility. |
4791 ** | 5029 ** |
4792 ** See also: [sqlite3_collation_needed()] and [sqlite3_collation_needed16()]. | 5030 ** See also: [sqlite3_collation_needed()] and [sqlite3_collation_needed16()]. |
4793 */ | 5031 */ |
4794 SQLITE_API int SQLITE_STDCALL sqlite3_create_collation( | 5032 SQLITE_API int sqlite3_create_collation( |
4795 sqlite3*, | 5033 sqlite3*, |
4796 const char *zName, | 5034 const char *zName, |
4797 int eTextRep, | 5035 int eTextRep, |
4798 void *pArg, | 5036 void *pArg, |
4799 int(*xCompare)(void*,int,const void*,int,const void*) | 5037 int(*xCompare)(void*,int,const void*,int,const void*) |
4800 ); | 5038 ); |
4801 SQLITE_API int SQLITE_STDCALL sqlite3_create_collation_v2( | 5039 SQLITE_API int sqlite3_create_collation_v2( |
4802 sqlite3*, | 5040 sqlite3*, |
4803 const char *zName, | 5041 const char *zName, |
4804 int eTextRep, | 5042 int eTextRep, |
4805 void *pArg, | 5043 void *pArg, |
4806 int(*xCompare)(void*,int,const void*,int,const void*), | 5044 int(*xCompare)(void*,int,const void*,int,const void*), |
4807 void(*xDestroy)(void*) | 5045 void(*xDestroy)(void*) |
4808 ); | 5046 ); |
4809 SQLITE_API int SQLITE_STDCALL sqlite3_create_collation16( | 5047 SQLITE_API int sqlite3_create_collation16( |
4810 sqlite3*, | 5048 sqlite3*, |
4811 const void *zName, | 5049 const void *zName, |
4812 int eTextRep, | 5050 int eTextRep, |
4813 void *pArg, | 5051 void *pArg, |
4814 int(*xCompare)(void*,int,const void*,int,const void*) | 5052 int(*xCompare)(void*,int,const void*,int,const void*) |
4815 ); | 5053 ); |
4816 | 5054 |
4817 /* | 5055 /* |
4818 ** CAPI3REF: Collation Needed Callbacks | 5056 ** CAPI3REF: Collation Needed Callbacks |
4819 ** METHOD: sqlite3 | 5057 ** METHOD: sqlite3 |
(...skipping 14 matching lines...) Expand all Loading... |
4834 ** sqlite3_collation_needed16(). The second argument is the database | 5072 ** sqlite3_collation_needed16(). The second argument is the database |
4835 ** connection. The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE], | 5073 ** connection. The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE], |
4836 ** or [SQLITE_UTF16LE], indicating the most desirable form of the collation | 5074 ** or [SQLITE_UTF16LE], indicating the most desirable form of the collation |
4837 ** sequence function required. The fourth parameter is the name of the | 5075 ** sequence function required. The fourth parameter is the name of the |
4838 ** required collation sequence.)^ | 5076 ** required collation sequence.)^ |
4839 ** | 5077 ** |
4840 ** The callback function should register the desired collation using | 5078 ** The callback function should register the desired collation using |
4841 ** [sqlite3_create_collation()], [sqlite3_create_collation16()], or | 5079 ** [sqlite3_create_collation()], [sqlite3_create_collation16()], or |
4842 ** [sqlite3_create_collation_v2()]. | 5080 ** [sqlite3_create_collation_v2()]. |
4843 */ | 5081 */ |
4844 SQLITE_API int SQLITE_STDCALL sqlite3_collation_needed( | 5082 SQLITE_API int sqlite3_collation_needed( |
4845 sqlite3*, | 5083 sqlite3*, |
4846 void*, | 5084 void*, |
4847 void(*)(void*,sqlite3*,int eTextRep,const char*) | 5085 void(*)(void*,sqlite3*,int eTextRep,const char*) |
4848 ); | 5086 ); |
4849 SQLITE_API int SQLITE_STDCALL sqlite3_collation_needed16( | 5087 SQLITE_API int sqlite3_collation_needed16( |
4850 sqlite3*, | 5088 sqlite3*, |
4851 void*, | 5089 void*, |
4852 void(*)(void*,sqlite3*,int eTextRep,const void*) | 5090 void(*)(void*,sqlite3*,int eTextRep,const void*) |
4853 ); | 5091 ); |
4854 | 5092 |
4855 #ifdef SQLITE_HAS_CODEC | 5093 #ifdef SQLITE_HAS_CODEC |
4856 /* | 5094 /* |
4857 ** Specify the key for an encrypted database. This routine should be | 5095 ** Specify the key for an encrypted database. This routine should be |
4858 ** called right after sqlite3_open(). | 5096 ** called right after sqlite3_open(). |
4859 ** | 5097 ** |
4860 ** The code to implement this API is not available in the public release | 5098 ** The code to implement this API is not available in the public release |
4861 ** of SQLite. | 5099 ** of SQLite. |
4862 */ | 5100 */ |
4863 SQLITE_API int SQLITE_STDCALL sqlite3_key( | 5101 SQLITE_API int sqlite3_key( |
4864 sqlite3 *db, /* Database to be rekeyed */ | 5102 sqlite3 *db, /* Database to be rekeyed */ |
4865 const void *pKey, int nKey /* The key */ | 5103 const void *pKey, int nKey /* The key */ |
4866 ); | 5104 ); |
4867 SQLITE_API int SQLITE_STDCALL sqlite3_key_v2( | 5105 SQLITE_API int sqlite3_key_v2( |
4868 sqlite3 *db, /* Database to be rekeyed */ | 5106 sqlite3 *db, /* Database to be rekeyed */ |
4869 const char *zDbName, /* Name of the database */ | 5107 const char *zDbName, /* Name of the database */ |
4870 const void *pKey, int nKey /* The key */ | 5108 const void *pKey, int nKey /* The key */ |
4871 ); | 5109 ); |
4872 | 5110 |
4873 /* | 5111 /* |
4874 ** Change the key on an open database. If the current database is not | 5112 ** Change the key on an open database. If the current database is not |
4875 ** encrypted, this routine will encrypt it. If pNew==0 or nNew==0, the | 5113 ** encrypted, this routine will encrypt it. If pNew==0 or nNew==0, the |
4876 ** database is decrypted. | 5114 ** database is decrypted. |
4877 ** | 5115 ** |
4878 ** The code to implement this API is not available in the public release | 5116 ** The code to implement this API is not available in the public release |
4879 ** of SQLite. | 5117 ** of SQLite. |
4880 */ | 5118 */ |
4881 SQLITE_API int SQLITE_STDCALL sqlite3_rekey( | 5119 SQLITE_API int sqlite3_rekey( |
4882 sqlite3 *db, /* Database to be rekeyed */ | 5120 sqlite3 *db, /* Database to be rekeyed */ |
4883 const void *pKey, int nKey /* The new key */ | 5121 const void *pKey, int nKey /* The new key */ |
4884 ); | 5122 ); |
4885 SQLITE_API int SQLITE_STDCALL sqlite3_rekey_v2( | 5123 SQLITE_API int sqlite3_rekey_v2( |
4886 sqlite3 *db, /* Database to be rekeyed */ | 5124 sqlite3 *db, /* Database to be rekeyed */ |
4887 const char *zDbName, /* Name of the database */ | 5125 const char *zDbName, /* Name of the database */ |
4888 const void *pKey, int nKey /* The new key */ | 5126 const void *pKey, int nKey /* The new key */ |
4889 ); | 5127 ); |
4890 | 5128 |
4891 /* | 5129 /* |
4892 ** Specify the activation key for a SEE database. Unless | 5130 ** Specify the activation key for a SEE database. Unless |
4893 ** activated, none of the SEE routines will work. | 5131 ** activated, none of the SEE routines will work. |
4894 */ | 5132 */ |
4895 SQLITE_API void SQLITE_STDCALL sqlite3_activate_see( | 5133 SQLITE_API void sqlite3_activate_see( |
4896 const char *zPassPhrase /* Activation phrase */ | 5134 const char *zPassPhrase /* Activation phrase */ |
4897 ); | 5135 ); |
4898 #endif | 5136 #endif |
4899 | 5137 |
4900 #ifdef SQLITE_ENABLE_CEROD | 5138 #ifdef SQLITE_ENABLE_CEROD |
4901 /* | 5139 /* |
4902 ** Specify the activation key for a CEROD database. Unless | 5140 ** Specify the activation key for a CEROD database. Unless |
4903 ** activated, none of the CEROD routines will work. | 5141 ** activated, none of the CEROD routines will work. |
4904 */ | 5142 */ |
4905 SQLITE_API void SQLITE_STDCALL sqlite3_activate_cerod( | 5143 SQLITE_API void sqlite3_activate_cerod( |
4906 const char *zPassPhrase /* Activation phrase */ | 5144 const char *zPassPhrase /* Activation phrase */ |
4907 ); | 5145 ); |
4908 #endif | 5146 #endif |
4909 | 5147 |
4910 /* | 5148 /* |
4911 ** CAPI3REF: Suspend Execution For A Short Time | 5149 ** CAPI3REF: Suspend Execution For A Short Time |
4912 ** | 5150 ** |
4913 ** The sqlite3_sleep() function causes the current thread to suspend execution | 5151 ** The sqlite3_sleep() function causes the current thread to suspend execution |
4914 ** for at least a number of milliseconds specified in its parameter. | 5152 ** for at least a number of milliseconds specified in its parameter. |
4915 ** | 5153 ** |
4916 ** If the operating system does not support sleep requests with | 5154 ** If the operating system does not support sleep requests with |
4917 ** millisecond time resolution, then the time will be rounded up to | 5155 ** millisecond time resolution, then the time will be rounded up to |
4918 ** the nearest second. The number of milliseconds of sleep actually | 5156 ** the nearest second. The number of milliseconds of sleep actually |
4919 ** requested from the operating system is returned. | 5157 ** requested from the operating system is returned. |
4920 ** | 5158 ** |
4921 ** ^SQLite implements this interface by calling the xSleep() | 5159 ** ^SQLite implements this interface by calling the xSleep() |
4922 ** method of the default [sqlite3_vfs] object. If the xSleep() method | 5160 ** method of the default [sqlite3_vfs] object. If the xSleep() method |
4923 ** of the default VFS is not implemented correctly, or not implemented at | 5161 ** of the default VFS is not implemented correctly, or not implemented at |
4924 ** all, then the behavior of sqlite3_sleep() may deviate from the description | 5162 ** all, then the behavior of sqlite3_sleep() may deviate from the description |
4925 ** in the previous paragraphs. | 5163 ** in the previous paragraphs. |
4926 */ | 5164 */ |
4927 SQLITE_API int SQLITE_STDCALL sqlite3_sleep(int); | 5165 SQLITE_API int sqlite3_sleep(int); |
4928 | 5166 |
4929 /* | 5167 /* |
4930 ** CAPI3REF: Name Of The Folder Holding Temporary Files | 5168 ** CAPI3REF: Name Of The Folder Holding Temporary Files |
4931 ** | 5169 ** |
4932 ** ^(If this global variable is made to point to a string which is | 5170 ** ^(If this global variable is made to point to a string which is |
4933 ** the name of a folder (a.k.a. directory), then all temporary files | 5171 ** the name of a folder (a.k.a. directory), then all temporary files |
4934 ** created by SQLite when using a built-in [sqlite3_vfs | VFS] | 5172 ** created by SQLite when using a built-in [sqlite3_vfs | VFS] |
4935 ** will be placed in that directory.)^ ^If this variable | 5173 ** will be placed in that directory.)^ ^If this variable |
4936 ** is a NULL pointer, then SQLite performs a search for an appropriate | 5174 ** is a NULL pointer, then SQLite performs a search for an appropriate |
4937 ** temporary file directory. | 5175 ** temporary file directory. |
(...skipping 98 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
5036 ** transaction (errors including [SQLITE_FULL], [SQLITE_IOERR], | 5274 ** transaction (errors including [SQLITE_FULL], [SQLITE_IOERR], |
5037 ** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the | 5275 ** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the |
5038 ** transaction might be rolled back automatically. The only way to | 5276 ** transaction might be rolled back automatically. The only way to |
5039 ** find out whether SQLite automatically rolled back the transaction after | 5277 ** find out whether SQLite automatically rolled back the transaction after |
5040 ** an error is to use this function. | 5278 ** an error is to use this function. |
5041 ** | 5279 ** |
5042 ** If another thread changes the autocommit status of the database | 5280 ** If another thread changes the autocommit status of the database |
5043 ** connection while this routine is running, then the return value | 5281 ** connection while this routine is running, then the return value |
5044 ** is undefined. | 5282 ** is undefined. |
5045 */ | 5283 */ |
5046 SQLITE_API int SQLITE_STDCALL sqlite3_get_autocommit(sqlite3*); | 5284 SQLITE_API int sqlite3_get_autocommit(sqlite3*); |
5047 | 5285 |
5048 /* | 5286 /* |
5049 ** CAPI3REF: Find The Database Handle Of A Prepared Statement | 5287 ** CAPI3REF: Find The Database Handle Of A Prepared Statement |
5050 ** METHOD: sqlite3_stmt | 5288 ** METHOD: sqlite3_stmt |
5051 ** | 5289 ** |
5052 ** ^The sqlite3_db_handle interface returns the [database connection] handle | 5290 ** ^The sqlite3_db_handle interface returns the [database connection] handle |
5053 ** to which a [prepared statement] belongs. ^The [database connection] | 5291 ** to which a [prepared statement] belongs. ^The [database connection] |
5054 ** returned by sqlite3_db_handle is the same [database connection] | 5292 ** returned by sqlite3_db_handle is the same [database connection] |
5055 ** that was the first argument | 5293 ** that was the first argument |
5056 ** to the [sqlite3_prepare_v2()] call (or its variants) that was used to | 5294 ** to the [sqlite3_prepare_v2()] call (or its variants) that was used to |
5057 ** create the statement in the first place. | 5295 ** create the statement in the first place. |
5058 */ | 5296 */ |
5059 SQLITE_API sqlite3 *SQLITE_STDCALL sqlite3_db_handle(sqlite3_stmt*); | 5297 SQLITE_API sqlite3 *sqlite3_db_handle(sqlite3_stmt*); |
5060 | 5298 |
5061 /* | 5299 /* |
5062 ** CAPI3REF: Return The Filename For A Database Connection | 5300 ** CAPI3REF: Return The Filename For A Database Connection |
5063 ** METHOD: sqlite3 | 5301 ** METHOD: sqlite3 |
5064 ** | 5302 ** |
5065 ** ^The sqlite3_db_filename(D,N) interface returns a pointer to a filename | 5303 ** ^The sqlite3_db_filename(D,N) interface returns a pointer to a filename |
5066 ** associated with database N of connection D. ^The main database file | 5304 ** associated with database N of connection D. ^The main database file |
5067 ** has the name "main". If there is no attached database N on the database | 5305 ** has the name "main". If there is no attached database N on the database |
5068 ** connection D, or if database N is a temporary or in-memory database, then | 5306 ** connection D, or if database N is a temporary or in-memory database, then |
5069 ** a NULL pointer is returned. | 5307 ** a NULL pointer is returned. |
5070 ** | 5308 ** |
5071 ** ^The filename returned by this function is the output of the | 5309 ** ^The filename returned by this function is the output of the |
5072 ** xFullPathname method of the [VFS]. ^In other words, the filename | 5310 ** xFullPathname method of the [VFS]. ^In other words, the filename |
5073 ** will be an absolute pathname, even if the filename used | 5311 ** will be an absolute pathname, even if the filename used |
5074 ** to open the database originally was a URI or relative pathname. | 5312 ** to open the database originally was a URI or relative pathname. |
5075 */ | 5313 */ |
5076 SQLITE_API const char *SQLITE_STDCALL sqlite3_db_filename(sqlite3 *db, const cha
r *zDbName); | 5314 SQLITE_API const char *sqlite3_db_filename(sqlite3 *db, const char *zDbName); |
5077 | 5315 |
5078 /* | 5316 /* |
5079 ** CAPI3REF: Determine if a database is read-only | 5317 ** CAPI3REF: Determine if a database is read-only |
5080 ** METHOD: sqlite3 | 5318 ** METHOD: sqlite3 |
5081 ** | 5319 ** |
5082 ** ^The sqlite3_db_readonly(D,N) interface returns 1 if the database N | 5320 ** ^The sqlite3_db_readonly(D,N) interface returns 1 if the database N |
5083 ** of connection D is read-only, 0 if it is read/write, or -1 if N is not | 5321 ** of connection D is read-only, 0 if it is read/write, or -1 if N is not |
5084 ** the name of a database on connection D. | 5322 ** the name of a database on connection D. |
5085 */ | 5323 */ |
5086 SQLITE_API int SQLITE_STDCALL sqlite3_db_readonly(sqlite3 *db, const char *zDbNa
me); | 5324 SQLITE_API int sqlite3_db_readonly(sqlite3 *db, const char *zDbName); |
5087 | 5325 |
5088 /* | 5326 /* |
5089 ** CAPI3REF: Find the next prepared statement | 5327 ** CAPI3REF: Find the next prepared statement |
5090 ** METHOD: sqlite3 | 5328 ** METHOD: sqlite3 |
5091 ** | 5329 ** |
5092 ** ^This interface returns a pointer to the next [prepared statement] after | 5330 ** ^This interface returns a pointer to the next [prepared statement] after |
5093 ** pStmt associated with the [database connection] pDb. ^If pStmt is NULL | 5331 ** pStmt associated with the [database connection] pDb. ^If pStmt is NULL |
5094 ** then this interface returns a pointer to the first prepared statement | 5332 ** then this interface returns a pointer to the first prepared statement |
5095 ** associated with the database connection pDb. ^If no prepared statement | 5333 ** associated with the database connection pDb. ^If no prepared statement |
5096 ** satisfies the conditions of this routine, it returns NULL. | 5334 ** satisfies the conditions of this routine, it returns NULL. |
5097 ** | 5335 ** |
5098 ** The [database connection] pointer D in a call to | 5336 ** The [database connection] pointer D in a call to |
5099 ** [sqlite3_next_stmt(D,S)] must refer to an open database | 5337 ** [sqlite3_next_stmt(D,S)] must refer to an open database |
5100 ** connection and in particular must not be a NULL pointer. | 5338 ** connection and in particular must not be a NULL pointer. |
5101 */ | 5339 */ |
5102 SQLITE_API sqlite3_stmt *SQLITE_STDCALL sqlite3_next_stmt(sqlite3 *pDb, sqlite3_
stmt *pStmt); | 5340 SQLITE_API sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt); |
5103 | 5341 |
5104 /* | 5342 /* |
5105 ** CAPI3REF: Commit And Rollback Notification Callbacks | 5343 ** CAPI3REF: Commit And Rollback Notification Callbacks |
5106 ** METHOD: sqlite3 | 5344 ** METHOD: sqlite3 |
5107 ** | 5345 ** |
5108 ** ^The sqlite3_commit_hook() interface registers a callback | 5346 ** ^The sqlite3_commit_hook() interface registers a callback |
5109 ** function to be invoked whenever a transaction is [COMMIT | committed]. | 5347 ** function to be invoked whenever a transaction is [COMMIT | committed]. |
5110 ** ^Any callback set by a previous call to sqlite3_commit_hook() | 5348 ** ^Any callback set by a previous call to sqlite3_commit_hook() |
5111 ** for the same database connection is overridden. | 5349 ** for the same database connection is overridden. |
5112 ** ^The sqlite3_rollback_hook() interface registers a callback | 5350 ** ^The sqlite3_rollback_hook() interface registers a callback |
(...skipping 28 matching lines...) Expand all Loading... |
5141 ** hook returning non-zero, just as it would be with any other rollback. | 5379 ** hook returning non-zero, just as it would be with any other rollback. |
5142 ** | 5380 ** |
5143 ** ^For the purposes of this API, a transaction is said to have been | 5381 ** ^For the purposes of this API, a transaction is said to have been |
5144 ** rolled back if an explicit "ROLLBACK" statement is executed, or | 5382 ** rolled back if an explicit "ROLLBACK" statement is executed, or |
5145 ** an error or constraint causes an implicit rollback to occur. | 5383 ** an error or constraint causes an implicit rollback to occur. |
5146 ** ^The rollback callback is not invoked if a transaction is | 5384 ** ^The rollback callback is not invoked if a transaction is |
5147 ** automatically rolled back because the database connection is closed. | 5385 ** automatically rolled back because the database connection is closed. |
5148 ** | 5386 ** |
5149 ** See also the [sqlite3_update_hook()] interface. | 5387 ** See also the [sqlite3_update_hook()] interface. |
5150 */ | 5388 */ |
5151 SQLITE_API void *SQLITE_STDCALL sqlite3_commit_hook(sqlite3*, int(*)(void*), voi
d*); | 5389 SQLITE_API void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*); |
5152 SQLITE_API void *SQLITE_STDCALL sqlite3_rollback_hook(sqlite3*, void(*)(void *),
void*); | 5390 SQLITE_API void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*); |
5153 | 5391 |
5154 /* | 5392 /* |
5155 ** CAPI3REF: Data Change Notification Callbacks | 5393 ** CAPI3REF: Data Change Notification Callbacks |
5156 ** METHOD: sqlite3 | 5394 ** METHOD: sqlite3 |
5157 ** | 5395 ** |
5158 ** ^The sqlite3_update_hook() interface registers a callback function | 5396 ** ^The sqlite3_update_hook() interface registers a callback function |
5159 ** with the [database connection] identified by the first argument | 5397 ** with the [database connection] identified by the first argument |
5160 ** to be invoked whenever a row is updated, inserted or deleted in | 5398 ** to be invoked whenever a row is updated, inserted or deleted in |
5161 ** a rowid table. | 5399 ** a [rowid table]. |
5162 ** ^Any callback set by a previous call to this function | 5400 ** ^Any callback set by a previous call to this function |
5163 ** for the same database connection is overridden. | 5401 ** for the same database connection is overridden. |
5164 ** | 5402 ** |
5165 ** ^The second argument is a pointer to the function to invoke when a | 5403 ** ^The second argument is a pointer to the function to invoke when a |
5166 ** row is updated, inserted or deleted in a rowid table. | 5404 ** row is updated, inserted or deleted in a rowid table. |
5167 ** ^The first argument to the callback is a copy of the third argument | 5405 ** ^The first argument to the callback is a copy of the third argument |
5168 ** to sqlite3_update_hook(). | 5406 ** to sqlite3_update_hook(). |
5169 ** ^The second callback argument is one of [SQLITE_INSERT], [SQLITE_DELETE], | 5407 ** ^The second callback argument is one of [SQLITE_INSERT], [SQLITE_DELETE], |
5170 ** or [SQLITE_UPDATE], depending on the operation that caused the callback | 5408 ** or [SQLITE_UPDATE], depending on the operation that caused the callback |
5171 ** to be invoked. | 5409 ** to be invoked. |
5172 ** ^The third and fourth arguments to the callback contain pointers to the | 5410 ** ^The third and fourth arguments to the callback contain pointers to the |
5173 ** database and table name containing the affected row. | 5411 ** database and table name containing the affected row. |
5174 ** ^The final callback parameter is the [rowid] of the row. | 5412 ** ^The final callback parameter is the [rowid] of the row. |
5175 ** ^In the case of an update, this is the [rowid] after the update takes place. | 5413 ** ^In the case of an update, this is the [rowid] after the update takes place. |
5176 ** | 5414 ** |
5177 ** ^(The update hook is not invoked when internal system tables are | 5415 ** ^(The update hook is not invoked when internal system tables are |
5178 ** modified (i.e. sqlite_master and sqlite_sequence).)^ | 5416 ** modified (i.e. sqlite_master and sqlite_sequence).)^ |
5179 ** ^The update hook is not invoked when [WITHOUT ROWID] tables are modified. | 5417 ** ^The update hook is not invoked when [WITHOUT ROWID] tables are modified. |
5180 ** | 5418 ** |
5181 ** ^In the current implementation, the update hook | 5419 ** ^In the current implementation, the update hook |
5182 ** is not invoked when duplication rows are deleted because of an | 5420 ** is not invoked when conflicting rows are deleted because of an |
5183 ** [ON CONFLICT | ON CONFLICT REPLACE] clause. ^Nor is the update hook | 5421 ** [ON CONFLICT | ON CONFLICT REPLACE] clause. ^Nor is the update hook |
5184 ** invoked when rows are deleted using the [truncate optimization]. | 5422 ** invoked when rows are deleted using the [truncate optimization]. |
5185 ** The exceptions defined in this paragraph might change in a future | 5423 ** The exceptions defined in this paragraph might change in a future |
5186 ** release of SQLite. | 5424 ** release of SQLite. |
5187 ** | 5425 ** |
5188 ** The update hook implementation must not do anything that will modify | 5426 ** The update hook implementation must not do anything that will modify |
5189 ** the database connection that invoked the update hook. Any actions | 5427 ** the database connection that invoked the update hook. Any actions |
5190 ** to modify the database connection must be deferred until after the | 5428 ** to modify the database connection must be deferred until after the |
5191 ** completion of the [sqlite3_step()] call that triggered the update hook. | 5429 ** completion of the [sqlite3_step()] call that triggered the update hook. |
5192 ** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their | 5430 ** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their |
5193 ** database connections for the meaning of "modify" in this paragraph. | 5431 ** database connections for the meaning of "modify" in this paragraph. |
5194 ** | 5432 ** |
5195 ** ^The sqlite3_update_hook(D,C,P) function | 5433 ** ^The sqlite3_update_hook(D,C,P) function |
5196 ** returns the P argument from the previous call | 5434 ** returns the P argument from the previous call |
5197 ** on the same [database connection] D, or NULL for | 5435 ** on the same [database connection] D, or NULL for |
5198 ** the first call on D. | 5436 ** the first call on D. |
5199 ** | 5437 ** |
5200 ** See also the [sqlite3_commit_hook()] and [sqlite3_rollback_hook()] | 5438 ** See also the [sqlite3_commit_hook()], [sqlite3_rollback_hook()], |
5201 ** interfaces. | 5439 ** and [sqlite3_preupdate_hook()] interfaces. |
5202 */ | 5440 */ |
5203 SQLITE_API void *SQLITE_STDCALL sqlite3_update_hook( | 5441 SQLITE_API void *sqlite3_update_hook( |
5204 sqlite3*, | 5442 sqlite3*, |
5205 void(*)(void *,int ,char const *,char const *,sqlite3_int64), | 5443 void(*)(void *,int ,char const *,char const *,sqlite3_int64), |
5206 void* | 5444 void* |
5207 ); | 5445 ); |
5208 | 5446 |
5209 /* | 5447 /* |
5210 ** CAPI3REF: Enable Or Disable Shared Pager Cache | 5448 ** CAPI3REF: Enable Or Disable Shared Pager Cache |
5211 ** | 5449 ** |
5212 ** ^(This routine enables or disables the sharing of the database cache | 5450 ** ^(This routine enables or disables the sharing of the database cache |
5213 ** and schema data structures between [database connection | connections] | 5451 ** and schema data structures between [database connection | connections] |
5214 ** to the same database. Sharing is enabled if the argument is true | 5452 ** to the same database. Sharing is enabled if the argument is true |
5215 ** and disabled if the argument is false.)^ | 5453 ** and disabled if the argument is false.)^ |
5216 ** | 5454 ** |
5217 ** ^Cache sharing is enabled and disabled for an entire process. | 5455 ** ^Cache sharing is enabled and disabled for an entire process. |
5218 ** This is a change as of SQLite version 3.5.0. In prior versions of SQLite, | 5456 ** This is a change as of SQLite [version 3.5.0] ([dateof:3.5.0]). |
| 5457 ** In prior versions of SQLite, |
5219 ** sharing was enabled or disabled for each thread separately. | 5458 ** sharing was enabled or disabled for each thread separately. |
5220 ** | 5459 ** |
5221 ** ^(The cache sharing mode set by this interface effects all subsequent | 5460 ** ^(The cache sharing mode set by this interface effects all subsequent |
5222 ** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()]. | 5461 ** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()]. |
5223 ** Existing database connections continue use the sharing mode | 5462 ** Existing database connections continue use the sharing mode |
5224 ** that was in effect at the time they were opened.)^ | 5463 ** that was in effect at the time they were opened.)^ |
5225 ** | 5464 ** |
5226 ** ^(This routine returns [SQLITE_OK] if shared cache was enabled or disabled | 5465 ** ^(This routine returns [SQLITE_OK] if shared cache was enabled or disabled |
5227 ** successfully. An [error code] is returned otherwise.)^ | 5466 ** successfully. An [error code] is returned otherwise.)^ |
5228 ** | 5467 ** |
5229 ** ^Shared cache is disabled by default. But this might change in | 5468 ** ^Shared cache is disabled by default. But this might change in |
5230 ** future releases of SQLite. Applications that care about shared | 5469 ** future releases of SQLite. Applications that care about shared |
5231 ** cache setting should set it explicitly. | 5470 ** cache setting should set it explicitly. |
5232 ** | 5471 ** |
5233 ** Note: This method is disabled on MacOS X 10.7 and iOS version 5.0 | 5472 ** Note: This method is disabled on MacOS X 10.7 and iOS version 5.0 |
5234 ** and will always return SQLITE_MISUSE. On those systems, | 5473 ** and will always return SQLITE_MISUSE. On those systems, |
5235 ** shared cache mode should be enabled per-database connection via | 5474 ** shared cache mode should be enabled per-database connection via |
5236 ** [sqlite3_open_v2()] with [SQLITE_OPEN_SHAREDCACHE]. | 5475 ** [sqlite3_open_v2()] with [SQLITE_OPEN_SHAREDCACHE]. |
5237 ** | 5476 ** |
5238 ** This interface is threadsafe on processors where writing a | 5477 ** This interface is threadsafe on processors where writing a |
5239 ** 32-bit integer is atomic. | 5478 ** 32-bit integer is atomic. |
5240 ** | 5479 ** |
5241 ** See Also: [SQLite Shared-Cache Mode] | 5480 ** See Also: [SQLite Shared-Cache Mode] |
5242 */ | 5481 */ |
5243 SQLITE_API int SQLITE_STDCALL sqlite3_enable_shared_cache(int); | 5482 SQLITE_API int sqlite3_enable_shared_cache(int); |
5244 | 5483 |
5245 /* | 5484 /* |
5246 ** CAPI3REF: Attempt To Free Heap Memory | 5485 ** CAPI3REF: Attempt To Free Heap Memory |
5247 ** | 5486 ** |
5248 ** ^The sqlite3_release_memory() interface attempts to free N bytes | 5487 ** ^The sqlite3_release_memory() interface attempts to free N bytes |
5249 ** of heap memory by deallocating non-essential memory allocations | 5488 ** of heap memory by deallocating non-essential memory allocations |
5250 ** held by the database library. Memory used to cache database | 5489 ** held by the database library. Memory used to cache database |
5251 ** pages to improve performance is an example of non-essential memory. | 5490 ** pages to improve performance is an example of non-essential memory. |
5252 ** ^sqlite3_release_memory() returns the number of bytes actually freed, | 5491 ** ^sqlite3_release_memory() returns the number of bytes actually freed, |
5253 ** which might be more or less than the amount requested. | 5492 ** which might be more or less than the amount requested. |
5254 ** ^The sqlite3_release_memory() routine is a no-op returning zero | 5493 ** ^The sqlite3_release_memory() routine is a no-op returning zero |
5255 ** if SQLite is not compiled with [SQLITE_ENABLE_MEMORY_MANAGEMENT]. | 5494 ** if SQLite is not compiled with [SQLITE_ENABLE_MEMORY_MANAGEMENT]. |
5256 ** | 5495 ** |
5257 ** See also: [sqlite3_db_release_memory()] | 5496 ** See also: [sqlite3_db_release_memory()] |
5258 */ | 5497 */ |
5259 SQLITE_API int SQLITE_STDCALL sqlite3_release_memory(int); | 5498 SQLITE_API int sqlite3_release_memory(int); |
5260 | 5499 |
5261 /* | 5500 /* |
5262 ** CAPI3REF: Free Memory Used By A Database Connection | 5501 ** CAPI3REF: Free Memory Used By A Database Connection |
5263 ** METHOD: sqlite3 | 5502 ** METHOD: sqlite3 |
5264 ** | 5503 ** |
5265 ** ^The sqlite3_db_release_memory(D) interface attempts to free as much heap | 5504 ** ^The sqlite3_db_release_memory(D) interface attempts to free as much heap |
5266 ** memory as possible from database connection D. Unlike the | 5505 ** memory as possible from database connection D. Unlike the |
5267 ** [sqlite3_release_memory()] interface, this interface is in effect even | 5506 ** [sqlite3_release_memory()] interface, this interface is in effect even |
5268 ** when the [SQLITE_ENABLE_MEMORY_MANAGEMENT] compile-time option is | 5507 ** when the [SQLITE_ENABLE_MEMORY_MANAGEMENT] compile-time option is |
5269 ** omitted. | 5508 ** omitted. |
5270 ** | 5509 ** |
5271 ** See also: [sqlite3_release_memory()] | 5510 ** See also: [sqlite3_release_memory()] |
5272 */ | 5511 */ |
5273 SQLITE_API int SQLITE_STDCALL sqlite3_db_release_memory(sqlite3*); | 5512 SQLITE_API int sqlite3_db_release_memory(sqlite3*); |
5274 | 5513 |
5275 /* | 5514 /* |
5276 ** CAPI3REF: Impose A Limit On Heap Size | 5515 ** CAPI3REF: Impose A Limit On Heap Size |
5277 ** | 5516 ** |
5278 ** ^The sqlite3_soft_heap_limit64() interface sets and/or queries the | 5517 ** ^The sqlite3_soft_heap_limit64() interface sets and/or queries the |
5279 ** soft limit on the amount of heap memory that may be allocated by SQLite. | 5518 ** soft limit on the amount of heap memory that may be allocated by SQLite. |
5280 ** ^SQLite strives to keep heap memory utilization below the soft heap | 5519 ** ^SQLite strives to keep heap memory utilization below the soft heap |
5281 ** limit by reducing the number of pages held in the page cache | 5520 ** limit by reducing the number of pages held in the page cache |
5282 ** as heap memory usages approaches the limit. | 5521 ** as heap memory usages approaches the limit. |
5283 ** ^The soft heap limit is "soft" because even though SQLite strives to stay | 5522 ** ^The soft heap limit is "soft" because even though SQLite strives to stay |
(...skipping 18 matching lines...) Expand all Loading... |
5302 ** <li> Memory accounting is disabled using a combination of the | 5541 ** <li> Memory accounting is disabled using a combination of the |
5303 ** [sqlite3_config]([SQLITE_CONFIG_MEMSTATUS],...) start-time option and | 5542 ** [sqlite3_config]([SQLITE_CONFIG_MEMSTATUS],...) start-time option and |
5304 ** the [SQLITE_DEFAULT_MEMSTATUS] compile-time option. | 5543 ** the [SQLITE_DEFAULT_MEMSTATUS] compile-time option. |
5305 ** <li> An alternative page cache implementation is specified using | 5544 ** <li> An alternative page cache implementation is specified using |
5306 ** [sqlite3_config]([SQLITE_CONFIG_PCACHE2],...). | 5545 ** [sqlite3_config]([SQLITE_CONFIG_PCACHE2],...). |
5307 ** <li> The page cache allocates from its own memory pool supplied | 5546 ** <li> The page cache allocates from its own memory pool supplied |
5308 ** by [sqlite3_config]([SQLITE_CONFIG_PAGECACHE],...) rather than | 5547 ** by [sqlite3_config]([SQLITE_CONFIG_PAGECACHE],...) rather than |
5309 ** from the heap. | 5548 ** from the heap. |
5310 ** </ul>)^ | 5549 ** </ul>)^ |
5311 ** | 5550 ** |
5312 ** Beginning with SQLite version 3.7.3, the soft heap limit is enforced | 5551 ** Beginning with SQLite [version 3.7.3] ([dateof:3.7.3]), |
| 5552 ** the soft heap limit is enforced |
5313 ** regardless of whether or not the [SQLITE_ENABLE_MEMORY_MANAGEMENT] | 5553 ** regardless of whether or not the [SQLITE_ENABLE_MEMORY_MANAGEMENT] |
5314 ** compile-time option is invoked. With [SQLITE_ENABLE_MEMORY_MANAGEMENT], | 5554 ** compile-time option is invoked. With [SQLITE_ENABLE_MEMORY_MANAGEMENT], |
5315 ** the soft heap limit is enforced on every memory allocation. Without | 5555 ** the soft heap limit is enforced on every memory allocation. Without |
5316 ** [SQLITE_ENABLE_MEMORY_MANAGEMENT], the soft heap limit is only enforced | 5556 ** [SQLITE_ENABLE_MEMORY_MANAGEMENT], the soft heap limit is only enforced |
5317 ** when memory is allocated by the page cache. Testing suggests that because | 5557 ** when memory is allocated by the page cache. Testing suggests that because |
5318 ** the page cache is the predominate memory user in SQLite, most | 5558 ** the page cache is the predominate memory user in SQLite, most |
5319 ** applications will achieve adequate soft heap limit enforcement without | 5559 ** applications will achieve adequate soft heap limit enforcement without |
5320 ** the use of [SQLITE_ENABLE_MEMORY_MANAGEMENT]. | 5560 ** the use of [SQLITE_ENABLE_MEMORY_MANAGEMENT]. |
5321 ** | 5561 ** |
5322 ** The circumstances under which SQLite will enforce the soft heap limit may | 5562 ** The circumstances under which SQLite will enforce the soft heap limit may |
5323 ** changes in future releases of SQLite. | 5563 ** changes in future releases of SQLite. |
5324 */ | 5564 */ |
5325 SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_soft_heap_limit64(sqlite3_int64
N); | 5565 SQLITE_API sqlite3_int64 sqlite3_soft_heap_limit64(sqlite3_int64 N); |
5326 | 5566 |
5327 /* | 5567 /* |
5328 ** CAPI3REF: Deprecated Soft Heap Limit Interface | 5568 ** CAPI3REF: Deprecated Soft Heap Limit Interface |
5329 ** DEPRECATED | 5569 ** DEPRECATED |
5330 ** | 5570 ** |
5331 ** This is a deprecated version of the [sqlite3_soft_heap_limit64()] | 5571 ** This is a deprecated version of the [sqlite3_soft_heap_limit64()] |
5332 ** interface. This routine is provided for historical compatibility | 5572 ** interface. This routine is provided for historical compatibility |
5333 ** only. All new applications should use the | 5573 ** only. All new applications should use the |
5334 ** [sqlite3_soft_heap_limit64()] interface rather than this one. | 5574 ** [sqlite3_soft_heap_limit64()] interface rather than this one. |
5335 */ | 5575 */ |
5336 SQLITE_API SQLITE_DEPRECATED void SQLITE_STDCALL sqlite3_soft_heap_limit(int N); | 5576 SQLITE_API SQLITE_DEPRECATED void sqlite3_soft_heap_limit(int N); |
5337 | 5577 |
5338 | 5578 |
5339 /* | 5579 /* |
5340 ** CAPI3REF: Extract Metadata About A Column Of A Table | 5580 ** CAPI3REF: Extract Metadata About A Column Of A Table |
5341 ** METHOD: sqlite3 | 5581 ** METHOD: sqlite3 |
5342 ** | 5582 ** |
5343 ** ^(The sqlite3_table_column_metadata(X,D,T,C,....) routine returns | 5583 ** ^(The sqlite3_table_column_metadata(X,D,T,C,....) routine returns |
5344 ** information about column C of table T in database D | 5584 ** information about column C of table T in database D |
5345 ** on [database connection] X.)^ ^The sqlite3_table_column_metadata() | 5585 ** on [database connection] X.)^ ^The sqlite3_table_column_metadata() |
5346 ** interface returns SQLITE_OK and fills in the non-NULL pointers in | 5586 ** interface returns SQLITE_OK and fills in the non-NULL pointers in |
5347 ** the final five arguments with appropriate values if the specified | 5587 ** the final five arguments with appropriate values if the specified |
5348 ** column exists. ^The sqlite3_table_column_metadata() interface returns | 5588 ** column exists. ^The sqlite3_table_column_metadata() interface returns |
5349 ** SQLITE_ERROR and if the specified column does not exist. | 5589 ** SQLITE_ERROR and if the specified column does not exist. |
5350 ** ^If the column-name parameter to sqlite3_table_column_metadata() is a | 5590 ** ^If the column-name parameter to sqlite3_table_column_metadata() is a |
5351 ** NULL pointer, then this routine simply checks for the existance of the | 5591 ** NULL pointer, then this routine simply checks for the existence of the |
5352 ** table and returns SQLITE_OK if the table exists and SQLITE_ERROR if it | 5592 ** table and returns SQLITE_OK if the table exists and SQLITE_ERROR if it |
5353 ** does not. | 5593 ** does not. |
5354 ** | 5594 ** |
5355 ** ^The column is identified by the second, third and fourth parameters to | 5595 ** ^The column is identified by the second, third and fourth parameters to |
5356 ** this function. ^(The second parameter is either the name of the database | 5596 ** this function. ^(The second parameter is either the name of the database |
5357 ** (i.e. "main", "temp", or an attached database) containing the specified | 5597 ** (i.e. "main", "temp", or an attached database) containing the specified |
5358 ** table or NULL.)^ ^If it is NULL, then all attached databases are searched | 5598 ** table or NULL.)^ ^If it is NULL, then all attached databases are searched |
5359 ** for the table using the same algorithm used by the database engine to | 5599 ** for the table using the same algorithm used by the database engine to |
5360 ** resolve unqualified table references. | 5600 ** resolve unqualified table references. |
5361 ** | 5601 ** |
(...skipping 34 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
5396 ** collation sequence: "BINARY" | 5636 ** collation sequence: "BINARY" |
5397 ** not null: 0 | 5637 ** not null: 0 |
5398 ** primary key: 1 | 5638 ** primary key: 1 |
5399 ** auto increment: 0 | 5639 ** auto increment: 0 |
5400 ** </pre>)^ | 5640 ** </pre>)^ |
5401 ** | 5641 ** |
5402 ** ^This function causes all database schemas to be read from disk and | 5642 ** ^This function causes all database schemas to be read from disk and |
5403 ** parsed, if that has not already been done, and returns an error if | 5643 ** parsed, if that has not already been done, and returns an error if |
5404 ** any errors are encountered while loading the schema. | 5644 ** any errors are encountered while loading the schema. |
5405 */ | 5645 */ |
5406 SQLITE_API int SQLITE_STDCALL sqlite3_table_column_metadata( | 5646 SQLITE_API int sqlite3_table_column_metadata( |
5407 sqlite3 *db, /* Connection handle */ | 5647 sqlite3 *db, /* Connection handle */ |
5408 const char *zDbName, /* Database name or NULL */ | 5648 const char *zDbName, /* Database name or NULL */ |
5409 const char *zTableName, /* Table name */ | 5649 const char *zTableName, /* Table name */ |
5410 const char *zColumnName, /* Column name */ | 5650 const char *zColumnName, /* Column name */ |
5411 char const **pzDataType, /* OUTPUT: Declared data type */ | 5651 char const **pzDataType, /* OUTPUT: Declared data type */ |
5412 char const **pzCollSeq, /* OUTPUT: Collation sequence name */ | 5652 char const **pzCollSeq, /* OUTPUT: Collation sequence name */ |
5413 int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */ | 5653 int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */ |
5414 int *pPrimaryKey, /* OUTPUT: True if column part of PK */ | 5654 int *pPrimaryKey, /* OUTPUT: True if column part of PK */ |
5415 int *pAutoinc /* OUTPUT: True if column is auto-increment */ | 5655 int *pAutoinc /* OUTPUT: True if column is auto-increment */ |
5416 ); | 5656 ); |
(...skipping 21 matching lines...) Expand all Loading... |
5438 ** "." and omitting any initial "lib".)^ | 5678 ** "." and omitting any initial "lib".)^ |
5439 ** ^The sqlite3_load_extension() interface returns | 5679 ** ^The sqlite3_load_extension() interface returns |
5440 ** [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong. | 5680 ** [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong. |
5441 ** ^If an error occurs and pzErrMsg is not 0, then the | 5681 ** ^If an error occurs and pzErrMsg is not 0, then the |
5442 ** [sqlite3_load_extension()] interface shall attempt to | 5682 ** [sqlite3_load_extension()] interface shall attempt to |
5443 ** fill *pzErrMsg with error message text stored in memory | 5683 ** fill *pzErrMsg with error message text stored in memory |
5444 ** obtained from [sqlite3_malloc()]. The calling function | 5684 ** obtained from [sqlite3_malloc()]. The calling function |
5445 ** should free this memory by calling [sqlite3_free()]. | 5685 ** should free this memory by calling [sqlite3_free()]. |
5446 ** | 5686 ** |
5447 ** ^Extension loading must be enabled using | 5687 ** ^Extension loading must be enabled using |
5448 ** [sqlite3_enable_load_extension()] prior to calling this API, | 5688 ** [sqlite3_enable_load_extension()] or |
| 5689 ** [sqlite3_db_config](db,[SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION],1,NULL) |
| 5690 ** prior to calling this API, |
5449 ** otherwise an error will be returned. | 5691 ** otherwise an error will be returned. |
5450 ** | 5692 ** |
| 5693 ** <b>Security warning:</b> It is recommended that the |
| 5694 ** [SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION] method be used to enable only this |
| 5695 ** interface. The use of the [sqlite3_enable_load_extension()] interface |
| 5696 ** should be avoided. This will keep the SQL function [load_extension()] |
| 5697 ** disabled and prevent SQL injections from giving attackers |
| 5698 ** access to extension loading capabilities. |
| 5699 ** |
5451 ** See also the [load_extension() SQL function]. | 5700 ** See also the [load_extension() SQL function]. |
5452 */ | 5701 */ |
5453 SQLITE_API int SQLITE_STDCALL sqlite3_load_extension( | 5702 SQLITE_API int sqlite3_load_extension( |
5454 sqlite3 *db, /* Load the extension into this database connection */ | 5703 sqlite3 *db, /* Load the extension into this database connection */ |
5455 const char *zFile, /* Name of the shared library containing extension */ | 5704 const char *zFile, /* Name of the shared library containing extension */ |
5456 const char *zProc, /* Entry point. Derived from zFile if 0 */ | 5705 const char *zProc, /* Entry point. Derived from zFile if 0 */ |
5457 char **pzErrMsg /* Put error message here if not 0 */ | 5706 char **pzErrMsg /* Put error message here if not 0 */ |
5458 ); | 5707 ); |
5459 | 5708 |
5460 /* | 5709 /* |
5461 ** CAPI3REF: Enable Or Disable Extension Loading | 5710 ** CAPI3REF: Enable Or Disable Extension Loading |
5462 ** METHOD: sqlite3 | 5711 ** METHOD: sqlite3 |
5463 ** | 5712 ** |
5464 ** ^So as not to open security holes in older applications that are | 5713 ** ^So as not to open security holes in older applications that are |
5465 ** unprepared to deal with [extension loading], and as a means of disabling | 5714 ** unprepared to deal with [extension loading], and as a means of disabling |
5466 ** [extension loading] while evaluating user-entered SQL, the following API | 5715 ** [extension loading] while evaluating user-entered SQL, the following API |
5467 ** is provided to turn the [sqlite3_load_extension()] mechanism on and off. | 5716 ** is provided to turn the [sqlite3_load_extension()] mechanism on and off. |
5468 ** | 5717 ** |
5469 ** ^Extension loading is off by default. | 5718 ** ^Extension loading is off by default. |
5470 ** ^Call the sqlite3_enable_load_extension() routine with onoff==1 | 5719 ** ^Call the sqlite3_enable_load_extension() routine with onoff==1 |
5471 ** to turn extension loading on and call it with onoff==0 to turn | 5720 ** to turn extension loading on and call it with onoff==0 to turn |
5472 ** it back off again. | 5721 ** it back off again. |
| 5722 ** |
| 5723 ** ^This interface enables or disables both the C-API |
| 5724 ** [sqlite3_load_extension()] and the SQL function [load_extension()]. |
| 5725 ** ^(Use [sqlite3_db_config](db,[SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION],..) |
| 5726 ** to enable or disable only the C-API.)^ |
| 5727 ** |
| 5728 ** <b>Security warning:</b> It is recommended that extension loading |
| 5729 ** be disabled using the [SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION] method |
| 5730 ** rather than this interface, so the [load_extension()] SQL function |
| 5731 ** remains disabled. This will prevent SQL injections from giving attackers |
| 5732 ** access to extension loading capabilities. |
5473 */ | 5733 */ |
5474 SQLITE_API int SQLITE_STDCALL sqlite3_enable_load_extension(sqlite3 *db, int ono
ff); | 5734 SQLITE_API int sqlite3_enable_load_extension(sqlite3 *db, int onoff); |
5475 | 5735 |
5476 /* | 5736 /* |
5477 ** CAPI3REF: Automatically Load Statically Linked Extensions | 5737 ** CAPI3REF: Automatically Load Statically Linked Extensions |
5478 ** | 5738 ** |
5479 ** ^This interface causes the xEntryPoint() function to be invoked for | 5739 ** ^This interface causes the xEntryPoint() function to be invoked for |
5480 ** each new [database connection] that is created. The idea here is that | 5740 ** each new [database connection] that is created. The idea here is that |
5481 ** xEntryPoint() is the entry point for a statically linked [SQLite extension] | 5741 ** xEntryPoint() is the entry point for a statically linked [SQLite extension] |
5482 ** that is to be automatically loaded into all new database connections. | 5742 ** that is to be automatically loaded into all new database connections. |
5483 ** | 5743 ** |
5484 ** ^(Even though the function prototype shows that xEntryPoint() takes | 5744 ** ^(Even though the function prototype shows that xEntryPoint() takes |
5485 ** no arguments and returns void, SQLite invokes xEntryPoint() with three | 5745 ** no arguments and returns void, SQLite invokes xEntryPoint() with three |
5486 ** arguments and expects and integer result as if the signature of the | 5746 ** arguments and expects an integer result as if the signature of the |
5487 ** entry point where as follows: | 5747 ** entry point where as follows: |
5488 ** | 5748 ** |
5489 ** <blockquote><pre> | 5749 ** <blockquote><pre> |
5490 ** int xEntryPoint( | 5750 ** int xEntryPoint( |
5491 ** sqlite3 *db, | 5751 ** sqlite3 *db, |
5492 ** const char **pzErrMsg, | 5752 ** const char **pzErrMsg, |
5493 ** const struct sqlite3_api_routines *pThunk | 5753 ** const struct sqlite3_api_routines *pThunk |
5494 ** ); | 5754 ** ); |
5495 ** </pre></blockquote>)^ | 5755 ** </pre></blockquote>)^ |
5496 ** | 5756 ** |
5497 ** If the xEntryPoint routine encounters an error, it should make *pzErrMsg | 5757 ** If the xEntryPoint routine encounters an error, it should make *pzErrMsg |
5498 ** point to an appropriate error message (obtained from [sqlite3_mprintf()]) | 5758 ** point to an appropriate error message (obtained from [sqlite3_mprintf()]) |
5499 ** and return an appropriate [error code]. ^SQLite ensures that *pzErrMsg | 5759 ** and return an appropriate [error code]. ^SQLite ensures that *pzErrMsg |
5500 ** is NULL before calling the xEntryPoint(). ^SQLite will invoke | 5760 ** is NULL before calling the xEntryPoint(). ^SQLite will invoke |
5501 ** [sqlite3_free()] on *pzErrMsg after xEntryPoint() returns. ^If any | 5761 ** [sqlite3_free()] on *pzErrMsg after xEntryPoint() returns. ^If any |
5502 ** xEntryPoint() returns an error, the [sqlite3_open()], [sqlite3_open16()], | 5762 ** xEntryPoint() returns an error, the [sqlite3_open()], [sqlite3_open16()], |
5503 ** or [sqlite3_open_v2()] call that provoked the xEntryPoint() will fail. | 5763 ** or [sqlite3_open_v2()] call that provoked the xEntryPoint() will fail. |
5504 ** | 5764 ** |
5505 ** ^Calling sqlite3_auto_extension(X) with an entry point X that is already | 5765 ** ^Calling sqlite3_auto_extension(X) with an entry point X that is already |
5506 ** on the list of automatic extensions is a harmless no-op. ^No entry point | 5766 ** on the list of automatic extensions is a harmless no-op. ^No entry point |
5507 ** will be called more than once for each database connection that is opened. | 5767 ** will be called more than once for each database connection that is opened. |
5508 ** | 5768 ** |
5509 ** See also: [sqlite3_reset_auto_extension()] | 5769 ** See also: [sqlite3_reset_auto_extension()] |
5510 ** and [sqlite3_cancel_auto_extension()] | 5770 ** and [sqlite3_cancel_auto_extension()] |
5511 */ | 5771 */ |
5512 SQLITE_API int SQLITE_STDCALL sqlite3_auto_extension(void (*xEntryPoint)(void)); | 5772 SQLITE_API int sqlite3_auto_extension(void(*xEntryPoint)(void)); |
5513 | 5773 |
5514 /* | 5774 /* |
5515 ** CAPI3REF: Cancel Automatic Extension Loading | 5775 ** CAPI3REF: Cancel Automatic Extension Loading |
5516 ** | 5776 ** |
5517 ** ^The [sqlite3_cancel_auto_extension(X)] interface unregisters the | 5777 ** ^The [sqlite3_cancel_auto_extension(X)] interface unregisters the |
5518 ** initialization routine X that was registered using a prior call to | 5778 ** initialization routine X that was registered using a prior call to |
5519 ** [sqlite3_auto_extension(X)]. ^The [sqlite3_cancel_auto_extension(X)] | 5779 ** [sqlite3_auto_extension(X)]. ^The [sqlite3_cancel_auto_extension(X)] |
5520 ** routine returns 1 if initialization routine X was successfully | 5780 ** routine returns 1 if initialization routine X was successfully |
5521 ** unregistered and it returns 0 if X was not on the list of initialization | 5781 ** unregistered and it returns 0 if X was not on the list of initialization |
5522 ** routines. | 5782 ** routines. |
5523 */ | 5783 */ |
5524 SQLITE_API int SQLITE_STDCALL sqlite3_cancel_auto_extension(void (*xEntryPoint)(
void)); | 5784 SQLITE_API int sqlite3_cancel_auto_extension(void(*xEntryPoint)(void)); |
5525 | 5785 |
5526 /* | 5786 /* |
5527 ** CAPI3REF: Reset Automatic Extension Loading | 5787 ** CAPI3REF: Reset Automatic Extension Loading |
5528 ** | 5788 ** |
5529 ** ^This interface disables all automatic extensions previously | 5789 ** ^This interface disables all automatic extensions previously |
5530 ** registered using [sqlite3_auto_extension()]. | 5790 ** registered using [sqlite3_auto_extension()]. |
5531 */ | 5791 */ |
5532 SQLITE_API void SQLITE_STDCALL sqlite3_reset_auto_extension(void); | 5792 SQLITE_API void sqlite3_reset_auto_extension(void); |
5533 | 5793 |
5534 /* | 5794 /* |
5535 ** The interface to the virtual-table mechanism is currently considered | 5795 ** The interface to the virtual-table mechanism is currently considered |
5536 ** to be experimental. The interface might change in incompatible ways. | 5796 ** to be experimental. The interface might change in incompatible ways. |
5537 ** If this is a problem for you, do not use the interface at this time. | 5797 ** If this is a problem for you, do not use the interface at this time. |
5538 ** | 5798 ** |
5539 ** When the virtual-table mechanism stabilizes, we will declare the | 5799 ** When the virtual-table mechanism stabilizes, we will declare the |
5540 ** interface fixed, support it indefinitely, and remove this comment. | 5800 ** interface fixed, support it indefinitely, and remove this comment. |
5541 */ | 5801 */ |
5542 | 5802 |
(...skipping 133 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
5676 ** SQLite also assumes that if a call to the xUpdate() method is made as | 5936 ** SQLite also assumes that if a call to the xUpdate() method is made as |
5677 ** part of the same statement to delete or update a virtual table row and the | 5937 ** part of the same statement to delete or update a virtual table row and the |
5678 ** implementation returns SQLITE_CONSTRAINT, then there is no need to rollback | 5938 ** implementation returns SQLITE_CONSTRAINT, then there is no need to rollback |
5679 ** any database changes. In other words, if the xUpdate() returns | 5939 ** any database changes. In other words, if the xUpdate() returns |
5680 ** SQLITE_CONSTRAINT, the database contents must be exactly as they were | 5940 ** SQLITE_CONSTRAINT, the database contents must be exactly as they were |
5681 ** before xUpdate was called. By contrast, if SQLITE_INDEX_SCAN_UNIQUE is not | 5941 ** before xUpdate was called. By contrast, if SQLITE_INDEX_SCAN_UNIQUE is not |
5682 ** set and xUpdate returns SQLITE_CONSTRAINT, any database changes made by | 5942 ** set and xUpdate returns SQLITE_CONSTRAINT, any database changes made by |
5683 ** the xUpdate method are automatically rolled back by SQLite. | 5943 ** the xUpdate method are automatically rolled back by SQLite. |
5684 ** | 5944 ** |
5685 ** IMPORTANT: The estimatedRows field was added to the sqlite3_index_info | 5945 ** IMPORTANT: The estimatedRows field was added to the sqlite3_index_info |
5686 ** structure for SQLite version 3.8.2. If a virtual table extension is | 5946 ** structure for SQLite [version 3.8.2] ([dateof:3.8.2]). |
| 5947 ** If a virtual table extension is |
5687 ** used with an SQLite version earlier than 3.8.2, the results of attempting | 5948 ** used with an SQLite version earlier than 3.8.2, the results of attempting |
5688 ** to read or write the estimatedRows field are undefined (but are likely | 5949 ** to read or write the estimatedRows field are undefined (but are likely |
5689 ** to included crashing the application). The estimatedRows field should | 5950 ** to included crashing the application). The estimatedRows field should |
5690 ** therefore only be used if [sqlite3_libversion_number()] returns a | 5951 ** therefore only be used if [sqlite3_libversion_number()] returns a |
5691 ** value greater than or equal to 3008002. Similarly, the idxFlags field | 5952 ** value greater than or equal to 3008002. Similarly, the idxFlags field |
5692 ** was added for version 3.9.0. It may therefore only be used if | 5953 ** was added for [version 3.9.0] ([dateof:3.9.0]). |
| 5954 ** It may therefore only be used if |
5693 ** sqlite3_libversion_number() returns a value greater than or equal to | 5955 ** sqlite3_libversion_number() returns a value greater than or equal to |
5694 ** 3009000. | 5956 ** 3009000. |
5695 */ | 5957 */ |
5696 struct sqlite3_index_info { | 5958 struct sqlite3_index_info { |
5697 /* Inputs */ | 5959 /* Inputs */ |
5698 int nConstraint; /* Number of entries in aConstraint */ | 5960 int nConstraint; /* Number of entries in aConstraint */ |
5699 struct sqlite3_index_constraint { | 5961 struct sqlite3_index_constraint { |
5700 int iColumn; /* Column on left-hand side of constraint */ | 5962 int iColumn; /* Column constrained. -1 for ROWID */ |
5701 unsigned char op; /* Constraint operator */ | 5963 unsigned char op; /* Constraint operator */ |
5702 unsigned char usable; /* True if this constraint is usable */ | 5964 unsigned char usable; /* True if this constraint is usable */ |
5703 int iTermOffset; /* Used internally - xBestIndex should ignore */ | 5965 int iTermOffset; /* Used internally - xBestIndex should ignore */ |
5704 } *aConstraint; /* Table of WHERE clause constraints */ | 5966 } *aConstraint; /* Table of WHERE clause constraints */ |
5705 int nOrderBy; /* Number of terms in the ORDER BY clause */ | 5967 int nOrderBy; /* Number of terms in the ORDER BY clause */ |
5706 struct sqlite3_index_orderby { | 5968 struct sqlite3_index_orderby { |
5707 int iColumn; /* Column number */ | 5969 int iColumn; /* Column number */ |
5708 unsigned char desc; /* True for DESC. False for ASC. */ | 5970 unsigned char desc; /* True for DESC. False for ASC. */ |
5709 } *aOrderBy; /* The ORDER BY clause */ | 5971 } *aOrderBy; /* The ORDER BY clause */ |
5710 /* Outputs */ | 5972 /* Outputs */ |
(...skipping 56 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
5767 ** | 6029 ** |
5768 ** ^The sqlite3_create_module_v2() interface has a fifth parameter which | 6030 ** ^The sqlite3_create_module_v2() interface has a fifth parameter which |
5769 ** is a pointer to a destructor for the pClientData. ^SQLite will | 6031 ** is a pointer to a destructor for the pClientData. ^SQLite will |
5770 ** invoke the destructor function (if it is not NULL) when SQLite | 6032 ** invoke the destructor function (if it is not NULL) when SQLite |
5771 ** no longer needs the pClientData pointer. ^The destructor will also | 6033 ** no longer needs the pClientData pointer. ^The destructor will also |
5772 ** be invoked if the call to sqlite3_create_module_v2() fails. | 6034 ** be invoked if the call to sqlite3_create_module_v2() fails. |
5773 ** ^The sqlite3_create_module() | 6035 ** ^The sqlite3_create_module() |
5774 ** interface is equivalent to sqlite3_create_module_v2() with a NULL | 6036 ** interface is equivalent to sqlite3_create_module_v2() with a NULL |
5775 ** destructor. | 6037 ** destructor. |
5776 */ | 6038 */ |
5777 SQLITE_API int SQLITE_STDCALL sqlite3_create_module( | 6039 SQLITE_API int sqlite3_create_module( |
5778 sqlite3 *db, /* SQLite connection to register module with */ | 6040 sqlite3 *db, /* SQLite connection to register module with */ |
5779 const char *zName, /* Name of the module */ | 6041 const char *zName, /* Name of the module */ |
5780 const sqlite3_module *p, /* Methods for the module */ | 6042 const sqlite3_module *p, /* Methods for the module */ |
5781 void *pClientData /* Client data for xCreate/xConnect */ | 6043 void *pClientData /* Client data for xCreate/xConnect */ |
5782 ); | 6044 ); |
5783 SQLITE_API int SQLITE_STDCALL sqlite3_create_module_v2( | 6045 SQLITE_API int sqlite3_create_module_v2( |
5784 sqlite3 *db, /* SQLite connection to register module with */ | 6046 sqlite3 *db, /* SQLite connection to register module with */ |
5785 const char *zName, /* Name of the module */ | 6047 const char *zName, /* Name of the module */ |
5786 const sqlite3_module *p, /* Methods for the module */ | 6048 const sqlite3_module *p, /* Methods for the module */ |
5787 void *pClientData, /* Client data for xCreate/xConnect */ | 6049 void *pClientData, /* Client data for xCreate/xConnect */ |
5788 void(*xDestroy)(void*) /* Module destructor function */ | 6050 void(*xDestroy)(void*) /* Module destructor function */ |
5789 ); | 6051 ); |
5790 | 6052 |
5791 /* | 6053 /* |
5792 ** CAPI3REF: Virtual Table Instance Object | 6054 ** CAPI3REF: Virtual Table Instance Object |
5793 ** KEYWORDS: sqlite3_vtab | 6055 ** KEYWORDS: sqlite3_vtab |
(...skipping 42 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
5836 }; | 6098 }; |
5837 | 6099 |
5838 /* | 6100 /* |
5839 ** CAPI3REF: Declare The Schema Of A Virtual Table | 6101 ** CAPI3REF: Declare The Schema Of A Virtual Table |
5840 ** | 6102 ** |
5841 ** ^The [xCreate] and [xConnect] methods of a | 6103 ** ^The [xCreate] and [xConnect] methods of a |
5842 ** [virtual table module] call this interface | 6104 ** [virtual table module] call this interface |
5843 ** to declare the format (the names and datatypes of the columns) of | 6105 ** to declare the format (the names and datatypes of the columns) of |
5844 ** the virtual tables they implement. | 6106 ** the virtual tables they implement. |
5845 */ | 6107 */ |
5846 SQLITE_API int SQLITE_STDCALL sqlite3_declare_vtab(sqlite3*, const char *zSQL); | 6108 SQLITE_API int sqlite3_declare_vtab(sqlite3*, const char *zSQL); |
5847 | 6109 |
5848 /* | 6110 /* |
5849 ** CAPI3REF: Overload A Function For A Virtual Table | 6111 ** CAPI3REF: Overload A Function For A Virtual Table |
5850 ** METHOD: sqlite3 | 6112 ** METHOD: sqlite3 |
5851 ** | 6113 ** |
5852 ** ^(Virtual tables can provide alternative implementations of functions | 6114 ** ^(Virtual tables can provide alternative implementations of functions |
5853 ** using the [xFindFunction] method of the [virtual table module]. | 6115 ** using the [xFindFunction] method of the [virtual table module]. |
5854 ** But global versions of those functions | 6116 ** But global versions of those functions |
5855 ** must exist in order to be overloaded.)^ | 6117 ** must exist in order to be overloaded.)^ |
5856 ** | 6118 ** |
5857 ** ^(This API makes sure a global version of a function with a particular | 6119 ** ^(This API makes sure a global version of a function with a particular |
5858 ** name and number of parameters exists. If no such function exists | 6120 ** name and number of parameters exists. If no such function exists |
5859 ** before this API is called, a new function is created.)^ ^The implementation | 6121 ** before this API is called, a new function is created.)^ ^The implementation |
5860 ** of the new function always causes an exception to be thrown. So | 6122 ** of the new function always causes an exception to be thrown. So |
5861 ** the new function is not good for anything by itself. Its only | 6123 ** the new function is not good for anything by itself. Its only |
5862 ** purpose is to be a placeholder function that can be overloaded | 6124 ** purpose is to be a placeholder function that can be overloaded |
5863 ** by a [virtual table]. | 6125 ** by a [virtual table]. |
5864 */ | 6126 */ |
5865 SQLITE_API int SQLITE_STDCALL sqlite3_overload_function(sqlite3*, const char *zF
uncName, int nArg); | 6127 SQLITE_API int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nA
rg); |
5866 | 6128 |
5867 /* | 6129 /* |
5868 ** The interface to the virtual-table mechanism defined above (back up | 6130 ** The interface to the virtual-table mechanism defined above (back up |
5869 ** to a comment remarkably similar to this one) is currently considered | 6131 ** to a comment remarkably similar to this one) is currently considered |
5870 ** to be experimental. The interface might change in incompatible ways. | 6132 ** to be experimental. The interface might change in incompatible ways. |
5871 ** If this is a problem for you, do not use the interface at this time. | 6133 ** If this is a problem for you, do not use the interface at this time. |
5872 ** | 6134 ** |
5873 ** When the virtual-table mechanism stabilizes, we will declare the | 6135 ** When the virtual-table mechanism stabilizes, we will declare the |
5874 ** interface fixed, support it indefinitely, and remove this comment. | 6136 ** interface fixed, support it indefinitely, and remove this comment. |
5875 */ | 6137 */ |
(...skipping 54 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
5930 ** constraint and the blob is being opened for read/write access)^, | 6192 ** constraint and the blob is being opened for read/write access)^, |
5931 ** <li> ^([foreign key constraints | Foreign key constraints] are enabled, | 6193 ** <li> ^([foreign key constraints | Foreign key constraints] are enabled, |
5932 ** column zColumn is part of a [child key] definition and the blob is | 6194 ** column zColumn is part of a [child key] definition and the blob is |
5933 ** being opened for read/write access)^. | 6195 ** being opened for read/write access)^. |
5934 ** </ul> | 6196 ** </ul> |
5935 ** | 6197 ** |
5936 ** ^Unless it returns SQLITE_MISUSE, this function sets the | 6198 ** ^Unless it returns SQLITE_MISUSE, this function sets the |
5937 ** [database connection] error code and message accessible via | 6199 ** [database connection] error code and message accessible via |
5938 ** [sqlite3_errcode()] and [sqlite3_errmsg()] and related functions. | 6200 ** [sqlite3_errcode()] and [sqlite3_errmsg()] and related functions. |
5939 ** | 6201 ** |
| 6202 ** A BLOB referenced by sqlite3_blob_open() may be read using the |
| 6203 ** [sqlite3_blob_read()] interface and modified by using |
| 6204 ** [sqlite3_blob_write()]. The [BLOB handle] can be moved to a |
| 6205 ** different row of the same table using the [sqlite3_blob_reopen()] |
| 6206 ** interface. However, the column, table, or database of a [BLOB handle] |
| 6207 ** cannot be changed after the [BLOB handle] is opened. |
5940 ** | 6208 ** |
5941 ** ^(If the row that a BLOB handle points to is modified by an | 6209 ** ^(If the row that a BLOB handle points to is modified by an |
5942 ** [UPDATE], [DELETE], or by [ON CONFLICT] side-effects | 6210 ** [UPDATE], [DELETE], or by [ON CONFLICT] side-effects |
5943 ** then the BLOB handle is marked as "expired". | 6211 ** then the BLOB handle is marked as "expired". |
5944 ** This is true if any column of the row is changed, even a column | 6212 ** This is true if any column of the row is changed, even a column |
5945 ** other than the one the BLOB handle is open on.)^ | 6213 ** other than the one the BLOB handle is open on.)^ |
5946 ** ^Calls to [sqlite3_blob_read()] and [sqlite3_blob_write()] for | 6214 ** ^Calls to [sqlite3_blob_read()] and [sqlite3_blob_write()] for |
5947 ** an expired BLOB handle fail with a return code of [SQLITE_ABORT]. | 6215 ** an expired BLOB handle fail with a return code of [SQLITE_ABORT]. |
5948 ** ^(Changes written into a BLOB prior to the BLOB expiring are not | 6216 ** ^(Changes written into a BLOB prior to the BLOB expiring are not |
5949 ** rolled back by the expiration of the BLOB. Such changes will eventually | 6217 ** rolled back by the expiration of the BLOB. Such changes will eventually |
5950 ** commit if the transaction continues to completion.)^ | 6218 ** commit if the transaction continues to completion.)^ |
5951 ** | 6219 ** |
5952 ** ^Use the [sqlite3_blob_bytes()] interface to determine the size of | 6220 ** ^Use the [sqlite3_blob_bytes()] interface to determine the size of |
5953 ** the opened blob. ^The size of a blob may not be changed by this | 6221 ** the opened blob. ^The size of a blob may not be changed by this |
5954 ** interface. Use the [UPDATE] SQL command to change the size of a | 6222 ** interface. Use the [UPDATE] SQL command to change the size of a |
5955 ** blob. | 6223 ** blob. |
5956 ** | 6224 ** |
5957 ** ^The [sqlite3_bind_zeroblob()] and [sqlite3_result_zeroblob()] interfaces | 6225 ** ^The [sqlite3_bind_zeroblob()] and [sqlite3_result_zeroblob()] interfaces |
5958 ** and the built-in [zeroblob] SQL function may be used to create a | 6226 ** and the built-in [zeroblob] SQL function may be used to create a |
5959 ** zero-filled blob to read or write using the incremental-blob interface. | 6227 ** zero-filled blob to read or write using the incremental-blob interface. |
5960 ** | 6228 ** |
5961 ** To avoid a resource leak, every open [BLOB handle] should eventually | 6229 ** To avoid a resource leak, every open [BLOB handle] should eventually |
5962 ** be released by a call to [sqlite3_blob_close()]. | 6230 ** be released by a call to [sqlite3_blob_close()]. |
| 6231 ** |
| 6232 ** See also: [sqlite3_blob_close()], |
| 6233 ** [sqlite3_blob_reopen()], [sqlite3_blob_read()], |
| 6234 ** [sqlite3_blob_bytes()], [sqlite3_blob_write()]. |
5963 */ | 6235 */ |
5964 SQLITE_API int SQLITE_STDCALL sqlite3_blob_open( | 6236 SQLITE_API int sqlite3_blob_open( |
5965 sqlite3*, | 6237 sqlite3*, |
5966 const char *zDb, | 6238 const char *zDb, |
5967 const char *zTable, | 6239 const char *zTable, |
5968 const char *zColumn, | 6240 const char *zColumn, |
5969 sqlite3_int64 iRow, | 6241 sqlite3_int64 iRow, |
5970 int flags, | 6242 int flags, |
5971 sqlite3_blob **ppBlob | 6243 sqlite3_blob **ppBlob |
5972 ); | 6244 ); |
5973 | 6245 |
5974 /* | 6246 /* |
5975 ** CAPI3REF: Move a BLOB Handle to a New Row | 6247 ** CAPI3REF: Move a BLOB Handle to a New Row |
5976 ** METHOD: sqlite3_blob | 6248 ** METHOD: sqlite3_blob |
5977 ** | 6249 ** |
5978 ** ^This function is used to move an existing blob handle so that it points | 6250 ** ^This function is used to move an existing [BLOB handle] so that it points |
5979 ** to a different row of the same database table. ^The new row is identified | 6251 ** to a different row of the same database table. ^The new row is identified |
5980 ** by the rowid value passed as the second argument. Only the row can be | 6252 ** by the rowid value passed as the second argument. Only the row can be |
5981 ** changed. ^The database, table and column on which the blob handle is open | 6253 ** changed. ^The database, table and column on which the blob handle is open |
5982 ** remain the same. Moving an existing blob handle to a new row can be | 6254 ** remain the same. Moving an existing [BLOB handle] to a new row is |
5983 ** faster than closing the existing handle and opening a new one. | 6255 ** faster than closing the existing handle and opening a new one. |
5984 ** | 6256 ** |
5985 ** ^(The new row must meet the same criteria as for [sqlite3_blob_open()] - | 6257 ** ^(The new row must meet the same criteria as for [sqlite3_blob_open()] - |
5986 ** it must exist and there must be either a blob or text value stored in | 6258 ** it must exist and there must be either a blob or text value stored in |
5987 ** the nominated column.)^ ^If the new row is not present in the table, or if | 6259 ** the nominated column.)^ ^If the new row is not present in the table, or if |
5988 ** it does not contain a blob or text value, or if another error occurs, an | 6260 ** it does not contain a blob or text value, or if another error occurs, an |
5989 ** SQLite error code is returned and the blob handle is considered aborted. | 6261 ** SQLite error code is returned and the blob handle is considered aborted. |
5990 ** ^All subsequent calls to [sqlite3_blob_read()], [sqlite3_blob_write()] or | 6262 ** ^All subsequent calls to [sqlite3_blob_read()], [sqlite3_blob_write()] or |
5991 ** [sqlite3_blob_reopen()] on an aborted blob handle immediately return | 6263 ** [sqlite3_blob_reopen()] on an aborted blob handle immediately return |
5992 ** SQLITE_ABORT. ^Calling [sqlite3_blob_bytes()] on an aborted blob handle | 6264 ** SQLITE_ABORT. ^Calling [sqlite3_blob_bytes()] on an aborted blob handle |
5993 ** always returns zero. | 6265 ** always returns zero. |
5994 ** | 6266 ** |
5995 ** ^This function sets the database handle error code and message. | 6267 ** ^This function sets the database handle error code and message. |
5996 */ | 6268 */ |
5997 SQLITE_API int SQLITE_STDCALL sqlite3_blob_reopen(sqlite3_blob *, sqlite3_int64)
; | 6269 SQLITE_API int sqlite3_blob_reopen(sqlite3_blob *, sqlite3_int64); |
5998 | 6270 |
5999 /* | 6271 /* |
6000 ** CAPI3REF: Close A BLOB Handle | 6272 ** CAPI3REF: Close A BLOB Handle |
6001 ** DESTRUCTOR: sqlite3_blob | 6273 ** DESTRUCTOR: sqlite3_blob |
6002 ** | 6274 ** |
6003 ** ^This function closes an open [BLOB handle]. ^(The BLOB handle is closed | 6275 ** ^This function closes an open [BLOB handle]. ^(The BLOB handle is closed |
6004 ** unconditionally. Even if this routine returns an error code, the | 6276 ** unconditionally. Even if this routine returns an error code, the |
6005 ** handle is still closed.)^ | 6277 ** handle is still closed.)^ |
6006 ** | 6278 ** |
6007 ** ^If the blob handle being closed was opened for read-write access, and if | 6279 ** ^If the blob handle being closed was opened for read-write access, and if |
6008 ** the database is in auto-commit mode and there are no other open read-write | 6280 ** the database is in auto-commit mode and there are no other open read-write |
6009 ** blob handles or active write statements, the current transaction is | 6281 ** blob handles or active write statements, the current transaction is |
6010 ** committed. ^If an error occurs while committing the transaction, an error | 6282 ** committed. ^If an error occurs while committing the transaction, an error |
6011 ** code is returned and the transaction rolled back. | 6283 ** code is returned and the transaction rolled back. |
6012 ** | 6284 ** |
6013 ** Calling this function with an argument that is not a NULL pointer or an | 6285 ** Calling this function with an argument that is not a NULL pointer or an |
6014 ** open blob handle results in undefined behaviour. ^Calling this routine | 6286 ** open blob handle results in undefined behaviour. ^Calling this routine |
6015 ** with a null pointer (such as would be returned by a failed call to | 6287 ** with a null pointer (such as would be returned by a failed call to |
6016 ** [sqlite3_blob_open()]) is a harmless no-op. ^Otherwise, if this function | 6288 ** [sqlite3_blob_open()]) is a harmless no-op. ^Otherwise, if this function |
6017 ** is passed a valid open blob handle, the values returned by the | 6289 ** is passed a valid open blob handle, the values returned by the |
6018 ** sqlite3_errcode() and sqlite3_errmsg() functions are set before returning. | 6290 ** sqlite3_errcode() and sqlite3_errmsg() functions are set before returning. |
6019 */ | 6291 */ |
6020 SQLITE_API int SQLITE_STDCALL sqlite3_blob_close(sqlite3_blob *); | 6292 SQLITE_API int sqlite3_blob_close(sqlite3_blob *); |
6021 | 6293 |
6022 /* | 6294 /* |
6023 ** CAPI3REF: Return The Size Of An Open BLOB | 6295 ** CAPI3REF: Return The Size Of An Open BLOB |
6024 ** METHOD: sqlite3_blob | 6296 ** METHOD: sqlite3_blob |
6025 ** | 6297 ** |
6026 ** ^Returns the size in bytes of the BLOB accessible via the | 6298 ** ^Returns the size in bytes of the BLOB accessible via the |
6027 ** successfully opened [BLOB handle] in its only argument. ^The | 6299 ** successfully opened [BLOB handle] in its only argument. ^The |
6028 ** incremental blob I/O routines can only read or overwriting existing | 6300 ** incremental blob I/O routines can only read or overwriting existing |
6029 ** blob content; they cannot change the size of a blob. | 6301 ** blob content; they cannot change the size of a blob. |
6030 ** | 6302 ** |
6031 ** This routine only works on a [BLOB handle] which has been created | 6303 ** This routine only works on a [BLOB handle] which has been created |
6032 ** by a prior successful call to [sqlite3_blob_open()] and which has not | 6304 ** by a prior successful call to [sqlite3_blob_open()] and which has not |
6033 ** been closed by [sqlite3_blob_close()]. Passing any other pointer in | 6305 ** been closed by [sqlite3_blob_close()]. Passing any other pointer in |
6034 ** to this routine results in undefined and probably undesirable behavior. | 6306 ** to this routine results in undefined and probably undesirable behavior. |
6035 */ | 6307 */ |
6036 SQLITE_API int SQLITE_STDCALL sqlite3_blob_bytes(sqlite3_blob *); | 6308 SQLITE_API int sqlite3_blob_bytes(sqlite3_blob *); |
6037 | 6309 |
6038 /* | 6310 /* |
6039 ** CAPI3REF: Read Data From A BLOB Incrementally | 6311 ** CAPI3REF: Read Data From A BLOB Incrementally |
6040 ** METHOD: sqlite3_blob | 6312 ** METHOD: sqlite3_blob |
6041 ** | 6313 ** |
6042 ** ^(This function is used to read data from an open [BLOB handle] into a | 6314 ** ^(This function is used to read data from an open [BLOB handle] into a |
6043 ** caller-supplied buffer. N bytes of data are copied into buffer Z | 6315 ** caller-supplied buffer. N bytes of data are copied into buffer Z |
6044 ** from the open BLOB, starting at offset iOffset.)^ | 6316 ** from the open BLOB, starting at offset iOffset.)^ |
6045 ** | 6317 ** |
6046 ** ^If offset iOffset is less than N bytes from the end of the BLOB, | 6318 ** ^If offset iOffset is less than N bytes from the end of the BLOB, |
6047 ** [SQLITE_ERROR] is returned and no data is read. ^If N or iOffset is | 6319 ** [SQLITE_ERROR] is returned and no data is read. ^If N or iOffset is |
6048 ** less than zero, [SQLITE_ERROR] is returned and no data is read. | 6320 ** less than zero, [SQLITE_ERROR] is returned and no data is read. |
6049 ** ^The size of the blob (and hence the maximum value of N+iOffset) | 6321 ** ^The size of the blob (and hence the maximum value of N+iOffset) |
6050 ** can be determined using the [sqlite3_blob_bytes()] interface. | 6322 ** can be determined using the [sqlite3_blob_bytes()] interface. |
6051 ** | 6323 ** |
6052 ** ^An attempt to read from an expired [BLOB handle] fails with an | 6324 ** ^An attempt to read from an expired [BLOB handle] fails with an |
6053 ** error code of [SQLITE_ABORT]. | 6325 ** error code of [SQLITE_ABORT]. |
6054 ** | 6326 ** |
6055 ** ^(On success, sqlite3_blob_read() returns SQLITE_OK. | 6327 ** ^(On success, sqlite3_blob_read() returns SQLITE_OK. |
6056 ** Otherwise, an [error code] or an [extended error code] is returned.)^ | 6328 ** Otherwise, an [error code] or an [extended error code] is returned.)^ |
6057 ** | 6329 ** |
6058 ** This routine only works on a [BLOB handle] which has been created | 6330 ** This routine only works on a [BLOB handle] which has been created |
6059 ** by a prior successful call to [sqlite3_blob_open()] and which has not | 6331 ** by a prior successful call to [sqlite3_blob_open()] and which has not |
6060 ** been closed by [sqlite3_blob_close()]. Passing any other pointer in | 6332 ** been closed by [sqlite3_blob_close()]. Passing any other pointer in |
6061 ** to this routine results in undefined and probably undesirable behavior. | 6333 ** to this routine results in undefined and probably undesirable behavior. |
6062 ** | 6334 ** |
6063 ** See also: [sqlite3_blob_write()]. | 6335 ** See also: [sqlite3_blob_write()]. |
6064 */ | 6336 */ |
6065 SQLITE_API int SQLITE_STDCALL sqlite3_blob_read(sqlite3_blob *, void *Z, int N,
int iOffset); | 6337 SQLITE_API int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset); |
6066 | 6338 |
6067 /* | 6339 /* |
6068 ** CAPI3REF: Write Data Into A BLOB Incrementally | 6340 ** CAPI3REF: Write Data Into A BLOB Incrementally |
6069 ** METHOD: sqlite3_blob | 6341 ** METHOD: sqlite3_blob |
6070 ** | 6342 ** |
6071 ** ^(This function is used to write data into an open [BLOB handle] from a | 6343 ** ^(This function is used to write data into an open [BLOB handle] from a |
6072 ** caller-supplied buffer. N bytes of data are copied from the buffer Z | 6344 ** caller-supplied buffer. N bytes of data are copied from the buffer Z |
6073 ** into the open BLOB, starting at offset iOffset.)^ | 6345 ** into the open BLOB, starting at offset iOffset.)^ |
6074 ** | 6346 ** |
6075 ** ^(On success, sqlite3_blob_write() returns SQLITE_OK. | 6347 ** ^(On success, sqlite3_blob_write() returns SQLITE_OK. |
(...skipping 21 matching lines...) Expand all Loading... |
6097 ** have been overwritten by the statement that expired the BLOB handle | 6369 ** have been overwritten by the statement that expired the BLOB handle |
6098 ** or by other independent statements. | 6370 ** or by other independent statements. |
6099 ** | 6371 ** |
6100 ** This routine only works on a [BLOB handle] which has been created | 6372 ** This routine only works on a [BLOB handle] which has been created |
6101 ** by a prior successful call to [sqlite3_blob_open()] and which has not | 6373 ** by a prior successful call to [sqlite3_blob_open()] and which has not |
6102 ** been closed by [sqlite3_blob_close()]. Passing any other pointer in | 6374 ** been closed by [sqlite3_blob_close()]. Passing any other pointer in |
6103 ** to this routine results in undefined and probably undesirable behavior. | 6375 ** to this routine results in undefined and probably undesirable behavior. |
6104 ** | 6376 ** |
6105 ** See also: [sqlite3_blob_read()]. | 6377 ** See also: [sqlite3_blob_read()]. |
6106 */ | 6378 */ |
6107 SQLITE_API int SQLITE_STDCALL sqlite3_blob_write(sqlite3_blob *, const void *z,
int n, int iOffset); | 6379 SQLITE_API int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOff
set); |
6108 | 6380 |
6109 /* | 6381 /* |
6110 ** CAPI3REF: Virtual File System Objects | 6382 ** CAPI3REF: Virtual File System Objects |
6111 ** | 6383 ** |
6112 ** A virtual filesystem (VFS) is an [sqlite3_vfs] object | 6384 ** A virtual filesystem (VFS) is an [sqlite3_vfs] object |
6113 ** that SQLite uses to interact | 6385 ** that SQLite uses to interact |
6114 ** with the underlying operating system. Most SQLite builds come with a | 6386 ** with the underlying operating system. Most SQLite builds come with a |
6115 ** single default VFS that is appropriate for the host computer. | 6387 ** single default VFS that is appropriate for the host computer. |
6116 ** New VFSes can be registered and existing VFSes can be unregistered. | 6388 ** New VFSes can be registered and existing VFSes can be unregistered. |
6117 ** The following interfaces are provided. | 6389 ** The following interfaces are provided. |
(...skipping 10 matching lines...) Expand all Loading... |
6128 ** ^To make an existing VFS into the default VFS, register it again | 6400 ** ^To make an existing VFS into the default VFS, register it again |
6129 ** with the makeDflt flag set. If two different VFSes with the | 6401 ** with the makeDflt flag set. If two different VFSes with the |
6130 ** same name are registered, the behavior is undefined. If a | 6402 ** same name are registered, the behavior is undefined. If a |
6131 ** VFS is registered with a name that is NULL or an empty string, | 6403 ** VFS is registered with a name that is NULL or an empty string, |
6132 ** then the behavior is undefined. | 6404 ** then the behavior is undefined. |
6133 ** | 6405 ** |
6134 ** ^Unregister a VFS with the sqlite3_vfs_unregister() interface. | 6406 ** ^Unregister a VFS with the sqlite3_vfs_unregister() interface. |
6135 ** ^(If the default VFS is unregistered, another VFS is chosen as | 6407 ** ^(If the default VFS is unregistered, another VFS is chosen as |
6136 ** the default. The choice for the new VFS is arbitrary.)^ | 6408 ** the default. The choice for the new VFS is arbitrary.)^ |
6137 */ | 6409 */ |
6138 SQLITE_API sqlite3_vfs *SQLITE_STDCALL sqlite3_vfs_find(const char *zVfsName); | 6410 SQLITE_API sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName); |
6139 SQLITE_API int SQLITE_STDCALL sqlite3_vfs_register(sqlite3_vfs*, int makeDflt); | 6411 SQLITE_API int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt); |
6140 SQLITE_API int SQLITE_STDCALL sqlite3_vfs_unregister(sqlite3_vfs*); | 6412 SQLITE_API int sqlite3_vfs_unregister(sqlite3_vfs*); |
6141 | 6413 |
6142 /* | 6414 /* |
6143 ** CAPI3REF: Mutexes | 6415 ** CAPI3REF: Mutexes |
6144 ** | 6416 ** |
6145 ** The SQLite core uses these routines for thread | 6417 ** The SQLite core uses these routines for thread |
6146 ** synchronization. Though they are intended for internal | 6418 ** synchronization. Though they are intended for internal |
6147 ** use by SQLite, code that links against SQLite is | 6419 ** use by SQLite, code that links against SQLite is |
6148 ** permitted to use any of these routines. | 6420 ** permitted to use any of these routines. |
6149 ** | 6421 ** |
6150 ** The SQLite source code contains multiple implementations | 6422 ** The SQLite source code contains multiple implementations |
(...skipping 95 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
6246 ** previously entered by the same thread. The behavior | 6518 ** previously entered by the same thread. The behavior |
6247 ** is undefined if the mutex is not currently entered by the | 6519 ** is undefined if the mutex is not currently entered by the |
6248 ** calling thread or is not currently allocated. | 6520 ** calling thread or is not currently allocated. |
6249 ** | 6521 ** |
6250 ** ^If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(), or | 6522 ** ^If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(), or |
6251 ** sqlite3_mutex_leave() is a NULL pointer, then all three routines | 6523 ** sqlite3_mutex_leave() is a NULL pointer, then all three routines |
6252 ** behave as no-ops. | 6524 ** behave as no-ops. |
6253 ** | 6525 ** |
6254 ** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()]. | 6526 ** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()]. |
6255 */ | 6527 */ |
6256 SQLITE_API sqlite3_mutex *SQLITE_STDCALL sqlite3_mutex_alloc(int); | 6528 SQLITE_API sqlite3_mutex *sqlite3_mutex_alloc(int); |
6257 SQLITE_API void SQLITE_STDCALL sqlite3_mutex_free(sqlite3_mutex*); | 6529 SQLITE_API void sqlite3_mutex_free(sqlite3_mutex*); |
6258 SQLITE_API void SQLITE_STDCALL sqlite3_mutex_enter(sqlite3_mutex*); | 6530 SQLITE_API void sqlite3_mutex_enter(sqlite3_mutex*); |
6259 SQLITE_API int SQLITE_STDCALL sqlite3_mutex_try(sqlite3_mutex*); | 6531 SQLITE_API int sqlite3_mutex_try(sqlite3_mutex*); |
6260 SQLITE_API void SQLITE_STDCALL sqlite3_mutex_leave(sqlite3_mutex*); | 6532 SQLITE_API void sqlite3_mutex_leave(sqlite3_mutex*); |
6261 | 6533 |
6262 /* | 6534 /* |
6263 ** CAPI3REF: Mutex Methods Object | 6535 ** CAPI3REF: Mutex Methods Object |
6264 ** | 6536 ** |
6265 ** An instance of this structure defines the low-level routines | 6537 ** An instance of this structure defines the low-level routines |
6266 ** used to allocate and use mutexes. | 6538 ** used to allocate and use mutexes. |
6267 ** | 6539 ** |
6268 ** Usually, the default mutex implementations provided by SQLite are | 6540 ** Usually, the default mutex implementations provided by SQLite are |
6269 ** sufficient, however the application has the option of substituting a custom | 6541 ** sufficient, however the application has the option of substituting a custom |
6270 ** implementation for specialized deployments or systems for which SQLite | 6542 ** implementation for specialized deployments or systems for which SQLite |
(...skipping 89 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
6360 ** If the argument to sqlite3_mutex_held() is a NULL pointer then | 6632 ** If the argument to sqlite3_mutex_held() is a NULL pointer then |
6361 ** the routine should return 1. This seems counter-intuitive since | 6633 ** the routine should return 1. This seems counter-intuitive since |
6362 ** clearly the mutex cannot be held if it does not exist. But | 6634 ** clearly the mutex cannot be held if it does not exist. But |
6363 ** the reason the mutex does not exist is because the build is not | 6635 ** the reason the mutex does not exist is because the build is not |
6364 ** using mutexes. And we do not want the assert() containing the | 6636 ** using mutexes. And we do not want the assert() containing the |
6365 ** call to sqlite3_mutex_held() to fail, so a non-zero return is | 6637 ** call to sqlite3_mutex_held() to fail, so a non-zero return is |
6366 ** the appropriate thing to do. The sqlite3_mutex_notheld() | 6638 ** the appropriate thing to do. The sqlite3_mutex_notheld() |
6367 ** interface should also return 1 when given a NULL pointer. | 6639 ** interface should also return 1 when given a NULL pointer. |
6368 */ | 6640 */ |
6369 #ifndef NDEBUG | 6641 #ifndef NDEBUG |
6370 SQLITE_API int SQLITE_STDCALL sqlite3_mutex_held(sqlite3_mutex*); | 6642 SQLITE_API int sqlite3_mutex_held(sqlite3_mutex*); |
6371 SQLITE_API int SQLITE_STDCALL sqlite3_mutex_notheld(sqlite3_mutex*); | 6643 SQLITE_API int sqlite3_mutex_notheld(sqlite3_mutex*); |
6372 #endif | 6644 #endif |
6373 | 6645 |
6374 /* | 6646 /* |
6375 ** CAPI3REF: Mutex Types | 6647 ** CAPI3REF: Mutex Types |
6376 ** | 6648 ** |
6377 ** The [sqlite3_mutex_alloc()] interface takes a single argument | 6649 ** The [sqlite3_mutex_alloc()] interface takes a single argument |
6378 ** which is one of these integer constants. | 6650 ** which is one of these integer constants. |
6379 ** | 6651 ** |
6380 ** The set of static mutexes may change from one SQLite release to the | 6652 ** The set of static mutexes may change from one SQLite release to the |
6381 ** next. Applications that override the built-in mutex logic must be | 6653 ** next. Applications that override the built-in mutex logic must be |
6382 ** prepared to accommodate additional static mutexes. | 6654 ** prepared to accommodate additional static mutexes. |
6383 */ | 6655 */ |
6384 #define SQLITE_MUTEX_FAST 0 | 6656 #define SQLITE_MUTEX_FAST 0 |
6385 #define SQLITE_MUTEX_RECURSIVE 1 | 6657 #define SQLITE_MUTEX_RECURSIVE 1 |
6386 #define SQLITE_MUTEX_STATIC_MASTER 2 | 6658 #define SQLITE_MUTEX_STATIC_MASTER 2 |
6387 #define SQLITE_MUTEX_STATIC_MEM 3 /* sqlite3_malloc() */ | 6659 #define SQLITE_MUTEX_STATIC_MEM 3 /* sqlite3_malloc() */ |
6388 #define SQLITE_MUTEX_STATIC_MEM2 4 /* NOT USED */ | 6660 #define SQLITE_MUTEX_STATIC_MEM2 4 /* NOT USED */ |
6389 #define SQLITE_MUTEX_STATIC_OPEN 4 /* sqlite3BtreeOpen() */ | 6661 #define SQLITE_MUTEX_STATIC_OPEN 4 /* sqlite3BtreeOpen() */ |
6390 #define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_random() */ | 6662 #define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_randomness() */ |
6391 #define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */ | 6663 #define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */ |
6392 #define SQLITE_MUTEX_STATIC_LRU2 7 /* NOT USED */ | 6664 #define SQLITE_MUTEX_STATIC_LRU2 7 /* NOT USED */ |
6393 #define SQLITE_MUTEX_STATIC_PMEM 7 /* sqlite3PageMalloc() */ | 6665 #define SQLITE_MUTEX_STATIC_PMEM 7 /* sqlite3PageMalloc() */ |
6394 #define SQLITE_MUTEX_STATIC_APP1 8 /* For use by application */ | 6666 #define SQLITE_MUTEX_STATIC_APP1 8 /* For use by application */ |
6395 #define SQLITE_MUTEX_STATIC_APP2 9 /* For use by application */ | 6667 #define SQLITE_MUTEX_STATIC_APP2 9 /* For use by application */ |
6396 #define SQLITE_MUTEX_STATIC_APP3 10 /* For use by application */ | 6668 #define SQLITE_MUTEX_STATIC_APP3 10 /* For use by application */ |
6397 #define SQLITE_MUTEX_STATIC_VFS1 11 /* For use by built-in VFS */ | 6669 #define SQLITE_MUTEX_STATIC_VFS1 11 /* For use by built-in VFS */ |
6398 #define SQLITE_MUTEX_STATIC_VFS2 12 /* For use by extension VFS */ | 6670 #define SQLITE_MUTEX_STATIC_VFS2 12 /* For use by extension VFS */ |
6399 #define SQLITE_MUTEX_STATIC_VFS3 13 /* For use by application VFS */ | 6671 #define SQLITE_MUTEX_STATIC_VFS3 13 /* For use by application VFS */ |
6400 | 6672 |
6401 /* | 6673 /* |
6402 ** CAPI3REF: Retrieve the mutex for a database connection | 6674 ** CAPI3REF: Retrieve the mutex for a database connection |
6403 ** METHOD: sqlite3 | 6675 ** METHOD: sqlite3 |
6404 ** | 6676 ** |
6405 ** ^This interface returns a pointer the [sqlite3_mutex] object that | 6677 ** ^This interface returns a pointer the [sqlite3_mutex] object that |
6406 ** serializes access to the [database connection] given in the argument | 6678 ** serializes access to the [database connection] given in the argument |
6407 ** when the [threading mode] is Serialized. | 6679 ** when the [threading mode] is Serialized. |
6408 ** ^If the [threading mode] is Single-thread or Multi-thread then this | 6680 ** ^If the [threading mode] is Single-thread or Multi-thread then this |
6409 ** routine returns a NULL pointer. | 6681 ** routine returns a NULL pointer. |
6410 */ | 6682 */ |
6411 SQLITE_API sqlite3_mutex *SQLITE_STDCALL sqlite3_db_mutex(sqlite3*); | 6683 SQLITE_API sqlite3_mutex *sqlite3_db_mutex(sqlite3*); |
6412 | 6684 |
6413 /* | 6685 /* |
6414 ** CAPI3REF: Low-Level Control Of Database Files | 6686 ** CAPI3REF: Low-Level Control Of Database Files |
6415 ** METHOD: sqlite3 | 6687 ** METHOD: sqlite3 |
6416 ** | 6688 ** |
6417 ** ^The [sqlite3_file_control()] interface makes a direct call to the | 6689 ** ^The [sqlite3_file_control()] interface makes a direct call to the |
6418 ** xFileControl method for the [sqlite3_io_methods] object associated | 6690 ** xFileControl method for the [sqlite3_io_methods] object associated |
6419 ** with a particular database identified by the second argument. ^The | 6691 ** with a particular database identified by the second argument. ^The |
6420 ** name of the database is "main" for the main database or "temp" for the | 6692 ** name of the database is "main" for the main database or "temp" for the |
6421 ** TEMP database, or the name that appears after the AS keyword for | 6693 ** TEMP database, or the name that appears after the AS keyword for |
(...skipping 14 matching lines...) Expand all Loading... |
6436 ** ^If the second parameter (zDbName) does not match the name of any | 6708 ** ^If the second parameter (zDbName) does not match the name of any |
6437 ** open database file, then SQLITE_ERROR is returned. ^This error | 6709 ** open database file, then SQLITE_ERROR is returned. ^This error |
6438 ** code is not remembered and will not be recalled by [sqlite3_errcode()] | 6710 ** code is not remembered and will not be recalled by [sqlite3_errcode()] |
6439 ** or [sqlite3_errmsg()]. The underlying xFileControl method might | 6711 ** or [sqlite3_errmsg()]. The underlying xFileControl method might |
6440 ** also return SQLITE_ERROR. There is no way to distinguish between | 6712 ** also return SQLITE_ERROR. There is no way to distinguish between |
6441 ** an incorrect zDbName and an SQLITE_ERROR return from the underlying | 6713 ** an incorrect zDbName and an SQLITE_ERROR return from the underlying |
6442 ** xFileControl method. | 6714 ** xFileControl method. |
6443 ** | 6715 ** |
6444 ** See also: [SQLITE_FCNTL_LOCKSTATE] | 6716 ** See also: [SQLITE_FCNTL_LOCKSTATE] |
6445 */ | 6717 */ |
6446 SQLITE_API int SQLITE_STDCALL sqlite3_file_control(sqlite3*, const char *zDbName
, int op, void*); | 6718 SQLITE_API int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*
); |
6447 | 6719 |
6448 /* | 6720 /* |
6449 ** CAPI3REF: Testing Interface | 6721 ** CAPI3REF: Testing Interface |
6450 ** | 6722 ** |
6451 ** ^The sqlite3_test_control() interface is used to read out internal | 6723 ** ^The sqlite3_test_control() interface is used to read out internal |
6452 ** state of SQLite and to inject faults into SQLite for testing | 6724 ** state of SQLite and to inject faults into SQLite for testing |
6453 ** purposes. ^The first parameter is an operation code that determines | 6725 ** purposes. ^The first parameter is an operation code that determines |
6454 ** the number, meaning, and operation of all subsequent parameters. | 6726 ** the number, meaning, and operation of all subsequent parameters. |
6455 ** | 6727 ** |
6456 ** This interface is not for use by applications. It exists solely | 6728 ** This interface is not for use by applications. It exists solely |
6457 ** for verifying the correct operation of the SQLite library. Depending | 6729 ** for verifying the correct operation of the SQLite library. Depending |
6458 ** on how the SQLite library is compiled, this interface might not exist. | 6730 ** on how the SQLite library is compiled, this interface might not exist. |
6459 ** | 6731 ** |
6460 ** The details of the operation codes, their meanings, the parameters | 6732 ** The details of the operation codes, their meanings, the parameters |
6461 ** they take, and what they do are all subject to change without notice. | 6733 ** they take, and what they do are all subject to change without notice. |
6462 ** Unlike most of the SQLite API, this function is not guaranteed to | 6734 ** Unlike most of the SQLite API, this function is not guaranteed to |
6463 ** operate consistently from one release to the next. | 6735 ** operate consistently from one release to the next. |
6464 */ | 6736 */ |
6465 SQLITE_API int SQLITE_CDECL sqlite3_test_control(int op, ...); | 6737 SQLITE_API int sqlite3_test_control(int op, ...); |
6466 | 6738 |
6467 /* | 6739 /* |
6468 ** CAPI3REF: Testing Interface Operation Codes | 6740 ** CAPI3REF: Testing Interface Operation Codes |
6469 ** | 6741 ** |
6470 ** These constants are the valid operation code parameters used | 6742 ** These constants are the valid operation code parameters used |
6471 ** as the first argument to [sqlite3_test_control()]. | 6743 ** as the first argument to [sqlite3_test_control()]. |
6472 ** | 6744 ** |
6473 ** These parameters and their meanings are subject to change | 6745 ** These parameters and their meanings are subject to change |
6474 ** without notice. These values are for testing purposes only. | 6746 ** without notice. These values are for testing purposes only. |
6475 ** Applications should not use any of these parameters or the | 6747 ** Applications should not use any of these parameters or the |
6476 ** [sqlite3_test_control()] interface. | 6748 ** [sqlite3_test_control()] interface. |
6477 */ | 6749 */ |
6478 #define SQLITE_TESTCTRL_FIRST 5 | 6750 #define SQLITE_TESTCTRL_FIRST 5 |
6479 #define SQLITE_TESTCTRL_PRNG_SAVE 5 | 6751 #define SQLITE_TESTCTRL_PRNG_SAVE 5 |
6480 #define SQLITE_TESTCTRL_PRNG_RESTORE 6 | 6752 #define SQLITE_TESTCTRL_PRNG_RESTORE 6 |
6481 #define SQLITE_TESTCTRL_PRNG_RESET 7 | 6753 #define SQLITE_TESTCTRL_PRNG_RESET 7 |
6482 #define SQLITE_TESTCTRL_BITVEC_TEST 8 | 6754 #define SQLITE_TESTCTRL_BITVEC_TEST 8 |
6483 #define SQLITE_TESTCTRL_FAULT_INSTALL 9 | 6755 #define SQLITE_TESTCTRL_FAULT_INSTALL 9 |
6484 #define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS 10 | 6756 #define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS 10 |
6485 #define SQLITE_TESTCTRL_PENDING_BYTE 11 | 6757 #define SQLITE_TESTCTRL_PENDING_BYTE 11 |
6486 #define SQLITE_TESTCTRL_ASSERT 12 | 6758 #define SQLITE_TESTCTRL_ASSERT 12 |
6487 #define SQLITE_TESTCTRL_ALWAYS 13 | 6759 #define SQLITE_TESTCTRL_ALWAYS 13 |
6488 #define SQLITE_TESTCTRL_RESERVE 14 | 6760 #define SQLITE_TESTCTRL_RESERVE 14 |
6489 #define SQLITE_TESTCTRL_OPTIMIZATIONS 15 | 6761 #define SQLITE_TESTCTRL_OPTIMIZATIONS 15 |
6490 #define SQLITE_TESTCTRL_ISKEYWORD 16 | 6762 #define SQLITE_TESTCTRL_ISKEYWORD 16 |
6491 #define SQLITE_TESTCTRL_SCRATCHMALLOC 17 | 6763 #define SQLITE_TESTCTRL_SCRATCHMALLOC 17 |
6492 #define SQLITE_TESTCTRL_LOCALTIME_FAULT 18 | 6764 #define SQLITE_TESTCTRL_LOCALTIME_FAULT 18 |
6493 #define SQLITE_TESTCTRL_EXPLAIN_STMT 19 /* NOT USED */ | 6765 #define SQLITE_TESTCTRL_EXPLAIN_STMT 19 /* NOT USED */ |
| 6766 #define SQLITE_TESTCTRL_ONCE_RESET_THRESHOLD 19 |
6494 #define SQLITE_TESTCTRL_NEVER_CORRUPT 20 | 6767 #define SQLITE_TESTCTRL_NEVER_CORRUPT 20 |
6495 #define SQLITE_TESTCTRL_VDBE_COVERAGE 21 | 6768 #define SQLITE_TESTCTRL_VDBE_COVERAGE 21 |
6496 #define SQLITE_TESTCTRL_BYTEORDER 22 | 6769 #define SQLITE_TESTCTRL_BYTEORDER 22 |
6497 #define SQLITE_TESTCTRL_ISINIT 23 | 6770 #define SQLITE_TESTCTRL_ISINIT 23 |
6498 #define SQLITE_TESTCTRL_SORTER_MMAP 24 | 6771 #define SQLITE_TESTCTRL_SORTER_MMAP 24 |
6499 #define SQLITE_TESTCTRL_IMPOSTER 25 | 6772 #define SQLITE_TESTCTRL_IMPOSTER 25 |
6500 #define SQLITE_TESTCTRL_LAST 25 | 6773 #define SQLITE_TESTCTRL_LAST 25 |
6501 | 6774 |
6502 /* | 6775 /* |
6503 ** CAPI3REF: SQLite Runtime Status | 6776 ** CAPI3REF: SQLite Runtime Status |
(...skipping 14 matching lines...) Expand all Loading... |
6518 ** | 6791 ** |
6519 ** ^The sqlite3_status() and sqlite3_status64() routines return | 6792 ** ^The sqlite3_status() and sqlite3_status64() routines return |
6520 ** SQLITE_OK on success and a non-zero [error code] on failure. | 6793 ** SQLITE_OK on success and a non-zero [error code] on failure. |
6521 ** | 6794 ** |
6522 ** If either the current value or the highwater mark is too large to | 6795 ** If either the current value or the highwater mark is too large to |
6523 ** be represented by a 32-bit integer, then the values returned by | 6796 ** be represented by a 32-bit integer, then the values returned by |
6524 ** sqlite3_status() are undefined. | 6797 ** sqlite3_status() are undefined. |
6525 ** | 6798 ** |
6526 ** See also: [sqlite3_db_status()] | 6799 ** See also: [sqlite3_db_status()] |
6527 */ | 6800 */ |
6528 SQLITE_API int SQLITE_STDCALL sqlite3_status(int op, int *pCurrent, int *pHighwa
ter, int resetFlag); | 6801 SQLITE_API int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetF
lag); |
6529 SQLITE_API int SQLITE_STDCALL sqlite3_status64( | 6802 SQLITE_API int sqlite3_status64( |
6530 int op, | 6803 int op, |
6531 sqlite3_int64 *pCurrent, | 6804 sqlite3_int64 *pCurrent, |
6532 sqlite3_int64 *pHighwater, | 6805 sqlite3_int64 *pHighwater, |
6533 int resetFlag | 6806 int resetFlag |
6534 ); | 6807 ); |
6535 | 6808 |
6536 | 6809 |
6537 /* | 6810 /* |
6538 ** CAPI3REF: Status Parameters | 6811 ** CAPI3REF: Status Parameters |
6539 ** KEYWORDS: {status parameters} | 6812 ** KEYWORDS: {status parameters} |
(...skipping 104 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
6644 ** ^The current value of the requested parameter is written into *pCur | 6917 ** ^The current value of the requested parameter is written into *pCur |
6645 ** and the highest instantaneous value is written into *pHiwtr. ^If | 6918 ** and the highest instantaneous value is written into *pHiwtr. ^If |
6646 ** the resetFlg is true, then the highest instantaneous value is | 6919 ** the resetFlg is true, then the highest instantaneous value is |
6647 ** reset back down to the current value. | 6920 ** reset back down to the current value. |
6648 ** | 6921 ** |
6649 ** ^The sqlite3_db_status() routine returns SQLITE_OK on success and a | 6922 ** ^The sqlite3_db_status() routine returns SQLITE_OK on success and a |
6650 ** non-zero [error code] on failure. | 6923 ** non-zero [error code] on failure. |
6651 ** | 6924 ** |
6652 ** See also: [sqlite3_status()] and [sqlite3_stmt_status()]. | 6925 ** See also: [sqlite3_status()] and [sqlite3_stmt_status()]. |
6653 */ | 6926 */ |
6654 SQLITE_API int SQLITE_STDCALL sqlite3_db_status(sqlite3*, int op, int *pCur, int
*pHiwtr, int resetFlg); | 6927 SQLITE_API int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int r
esetFlg); |
6655 | 6928 |
6656 /* | 6929 /* |
6657 ** CAPI3REF: Status Parameters for database connections | 6930 ** CAPI3REF: Status Parameters for database connections |
6658 ** KEYWORDS: {SQLITE_DBSTATUS options} | 6931 ** KEYWORDS: {SQLITE_DBSTATUS options} |
6659 ** | 6932 ** |
6660 ** These constants are the available integer "verbs" that can be passed as | 6933 ** These constants are the available integer "verbs" that can be passed as |
6661 ** the second argument to the [sqlite3_db_status()] interface. | 6934 ** the second argument to the [sqlite3_db_status()] interface. |
6662 ** | 6935 ** |
6663 ** New verbs may be added in future releases of SQLite. Existing verbs | 6936 ** New verbs may be added in future releases of SQLite. Existing verbs |
6664 ** might be discontinued. Applications should check the return code from | 6937 ** might be discontinued. Applications should check the return code from |
(...skipping 25 matching lines...) Expand all Loading... |
6690 ** been satisfied using lookaside memory but failed due to all lookaside | 6963 ** been satisfied using lookaside memory but failed due to all lookaside |
6691 ** memory already being in use. | 6964 ** memory already being in use. |
6692 ** Only the high-water value is meaningful; | 6965 ** Only the high-water value is meaningful; |
6693 ** the current value is always zero.)^ | 6966 ** the current value is always zero.)^ |
6694 ** | 6967 ** |
6695 ** [[SQLITE_DBSTATUS_CACHE_USED]] ^(<dt>SQLITE_DBSTATUS_CACHE_USED</dt> | 6968 ** [[SQLITE_DBSTATUS_CACHE_USED]] ^(<dt>SQLITE_DBSTATUS_CACHE_USED</dt> |
6696 ** <dd>This parameter returns the approximate number of bytes of heap | 6969 ** <dd>This parameter returns the approximate number of bytes of heap |
6697 ** memory used by all pager caches associated with the database connection.)^ | 6970 ** memory used by all pager caches associated with the database connection.)^ |
6698 ** ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_USED is always 0. | 6971 ** ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_USED is always 0. |
6699 ** | 6972 ** |
| 6973 ** [[SQLITE_DBSTATUS_CACHE_USED_SHARED]] |
| 6974 ** ^(<dt>SQLITE_DBSTATUS_CACHE_USED_SHARED</dt> |
| 6975 ** <dd>This parameter is similar to DBSTATUS_CACHE_USED, except that if a |
| 6976 ** pager cache is shared between two or more connections the bytes of heap |
| 6977 ** memory used by that pager cache is divided evenly between the attached |
| 6978 ** connections.)^ In other words, if none of the pager caches associated |
| 6979 ** with the database connection are shared, this request returns the same |
| 6980 ** value as DBSTATUS_CACHE_USED. Or, if one or more or the pager caches are |
| 6981 ** shared, the value returned by this call will be smaller than that returned |
| 6982 ** by DBSTATUS_CACHE_USED. ^The highwater mark associated with |
| 6983 ** SQLITE_DBSTATUS_CACHE_USED_SHARED is always 0. |
| 6984 ** |
6700 ** [[SQLITE_DBSTATUS_SCHEMA_USED]] ^(<dt>SQLITE_DBSTATUS_SCHEMA_USED</dt> | 6985 ** [[SQLITE_DBSTATUS_SCHEMA_USED]] ^(<dt>SQLITE_DBSTATUS_SCHEMA_USED</dt> |
6701 ** <dd>This parameter returns the approximate number of bytes of heap | 6986 ** <dd>This parameter returns the approximate number of bytes of heap |
6702 ** memory used to store the schema for all databases associated | 6987 ** memory used to store the schema for all databases associated |
6703 ** with the connection - main, temp, and any [ATTACH]-ed databases.)^ | 6988 ** with the connection - main, temp, and any [ATTACH]-ed databases.)^ |
6704 ** ^The full amount of memory used by the schemas is reported, even if the | 6989 ** ^The full amount of memory used by the schemas is reported, even if the |
6705 ** schema memory is shared with other database connections due to | 6990 ** schema memory is shared with other database connections due to |
6706 ** [shared cache mode] being enabled. | 6991 ** [shared cache mode] being enabled. |
6707 ** ^The highwater mark associated with SQLITE_DBSTATUS_SCHEMA_USED is always 0. | 6992 ** ^The highwater mark associated with SQLITE_DBSTATUS_SCHEMA_USED is always 0. |
6708 ** | 6993 ** |
6709 ** [[SQLITE_DBSTATUS_STMT_USED]] ^(<dt>SQLITE_DBSTATUS_STMT_USED</dt> | 6994 ** [[SQLITE_DBSTATUS_STMT_USED]] ^(<dt>SQLITE_DBSTATUS_STMT_USED</dt> |
(...skipping 37 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
6747 #define SQLITE_DBSTATUS_CACHE_USED 1 | 7032 #define SQLITE_DBSTATUS_CACHE_USED 1 |
6748 #define SQLITE_DBSTATUS_SCHEMA_USED 2 | 7033 #define SQLITE_DBSTATUS_SCHEMA_USED 2 |
6749 #define SQLITE_DBSTATUS_STMT_USED 3 | 7034 #define SQLITE_DBSTATUS_STMT_USED 3 |
6750 #define SQLITE_DBSTATUS_LOOKASIDE_HIT 4 | 7035 #define SQLITE_DBSTATUS_LOOKASIDE_HIT 4 |
6751 #define SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE 5 | 7036 #define SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE 5 |
6752 #define SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL 6 | 7037 #define SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL 6 |
6753 #define SQLITE_DBSTATUS_CACHE_HIT 7 | 7038 #define SQLITE_DBSTATUS_CACHE_HIT 7 |
6754 #define SQLITE_DBSTATUS_CACHE_MISS 8 | 7039 #define SQLITE_DBSTATUS_CACHE_MISS 8 |
6755 #define SQLITE_DBSTATUS_CACHE_WRITE 9 | 7040 #define SQLITE_DBSTATUS_CACHE_WRITE 9 |
6756 #define SQLITE_DBSTATUS_DEFERRED_FKS 10 | 7041 #define SQLITE_DBSTATUS_DEFERRED_FKS 10 |
6757 #define SQLITE_DBSTATUS_MAX 10 /* Largest defined DBSTATUS */ | 7042 #define SQLITE_DBSTATUS_CACHE_USED_SHARED 11 |
| 7043 #define SQLITE_DBSTATUS_MAX 11 /* Largest defined DBSTATUS */ |
6758 | 7044 |
6759 | 7045 |
6760 /* | 7046 /* |
6761 ** CAPI3REF: Prepared Statement Status | 7047 ** CAPI3REF: Prepared Statement Status |
6762 ** METHOD: sqlite3_stmt | 7048 ** METHOD: sqlite3_stmt |
6763 ** | 7049 ** |
6764 ** ^(Each prepared statement maintains various | 7050 ** ^(Each prepared statement maintains various |
6765 ** [SQLITE_STMTSTATUS counters] that measure the number | 7051 ** [SQLITE_STMTSTATUS counters] that measure the number |
6766 ** of times it has performed specific operations.)^ These counters can | 7052 ** of times it has performed specific operations.)^ These counters can |
6767 ** be used to monitor the performance characteristics of the prepared | 7053 ** be used to monitor the performance characteristics of the prepared |
6768 ** statements. For example, if the number of table steps greatly exceeds | 7054 ** statements. For example, if the number of table steps greatly exceeds |
6769 ** the number of table searches or result rows, that would tend to indicate | 7055 ** the number of table searches or result rows, that would tend to indicate |
6770 ** that the prepared statement is using a full table scan rather than | 7056 ** that the prepared statement is using a full table scan rather than |
6771 ** an index. | 7057 ** an index. |
6772 ** | 7058 ** |
6773 ** ^(This interface is used to retrieve and reset counter values from | 7059 ** ^(This interface is used to retrieve and reset counter values from |
6774 ** a [prepared statement]. The first argument is the prepared statement | 7060 ** a [prepared statement]. The first argument is the prepared statement |
6775 ** object to be interrogated. The second argument | 7061 ** object to be interrogated. The second argument |
6776 ** is an integer code for a specific [SQLITE_STMTSTATUS counter] | 7062 ** is an integer code for a specific [SQLITE_STMTSTATUS counter] |
6777 ** to be interrogated.)^ | 7063 ** to be interrogated.)^ |
6778 ** ^The current value of the requested counter is returned. | 7064 ** ^The current value of the requested counter is returned. |
6779 ** ^If the resetFlg is true, then the counter is reset to zero after this | 7065 ** ^If the resetFlg is true, then the counter is reset to zero after this |
6780 ** interface call returns. | 7066 ** interface call returns. |
6781 ** | 7067 ** |
6782 ** See also: [sqlite3_status()] and [sqlite3_db_status()]. | 7068 ** See also: [sqlite3_status()] and [sqlite3_db_status()]. |
6783 */ | 7069 */ |
6784 SQLITE_API int SQLITE_STDCALL sqlite3_stmt_status(sqlite3_stmt*, int op,int rese
tFlg); | 7070 SQLITE_API int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg); |
6785 | 7071 |
6786 /* | 7072 /* |
6787 ** CAPI3REF: Status Parameters for prepared statements | 7073 ** CAPI3REF: Status Parameters for prepared statements |
6788 ** KEYWORDS: {SQLITE_STMTSTATUS counter} {SQLITE_STMTSTATUS counters} | 7074 ** KEYWORDS: {SQLITE_STMTSTATUS counter} {SQLITE_STMTSTATUS counters} |
6789 ** | 7075 ** |
6790 ** These preprocessor macros define integer codes that name counter | 7076 ** These preprocessor macros define integer codes that name counter |
6791 ** values associated with the [sqlite3_stmt_status()] interface. | 7077 ** values associated with the [sqlite3_stmt_status()] interface. |
6792 ** The meanings of the various counters are as follows: | 7078 ** The meanings of the various counters are as follows: |
6793 ** | 7079 ** |
6794 ** <dl> | 7080 ** <dl> |
(...skipping 306 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
7101 ** ^The database name is "main" for the main database, "temp" for the | 7387 ** ^The database name is "main" for the main database, "temp" for the |
7102 ** temporary database, or the name specified after the AS keyword in | 7388 ** temporary database, or the name specified after the AS keyword in |
7103 ** an [ATTACH] statement for an attached database. | 7389 ** an [ATTACH] statement for an attached database. |
7104 ** ^The S and M arguments passed to | 7390 ** ^The S and M arguments passed to |
7105 ** sqlite3_backup_init(D,N,S,M) identify the [database connection] | 7391 ** sqlite3_backup_init(D,N,S,M) identify the [database connection] |
7106 ** and database name of the source database, respectively. | 7392 ** and database name of the source database, respectively. |
7107 ** ^The source and destination [database connections] (parameters S and D) | 7393 ** ^The source and destination [database connections] (parameters S and D) |
7108 ** must be different or else sqlite3_backup_init(D,N,S,M) will fail with | 7394 ** must be different or else sqlite3_backup_init(D,N,S,M) will fail with |
7109 ** an error. | 7395 ** an error. |
7110 ** | 7396 ** |
7111 ** ^A call to sqlite3_backup_init() will fail, returning SQLITE_ERROR, if | 7397 ** ^A call to sqlite3_backup_init() will fail, returning NULL, if |
7112 ** there is already a read or read-write transaction open on the | 7398 ** there is already a read or read-write transaction open on the |
7113 ** destination database. | 7399 ** destination database. |
7114 ** | 7400 ** |
7115 ** ^If an error occurs within sqlite3_backup_init(D,N,S,M), then NULL is | 7401 ** ^If an error occurs within sqlite3_backup_init(D,N,S,M), then NULL is |
7116 ** returned and an error code and error message are stored in the | 7402 ** returned and an error code and error message are stored in the |
7117 ** destination [database connection] D. | 7403 ** destination [database connection] D. |
7118 ** ^The error code and message for the failed call to sqlite3_backup_init() | 7404 ** ^The error code and message for the failed call to sqlite3_backup_init() |
7119 ** can be retrieved using the [sqlite3_errcode()], [sqlite3_errmsg()], and/or | 7405 ** can be retrieved using the [sqlite3_errcode()], [sqlite3_errmsg()], and/or |
7120 ** [sqlite3_errmsg16()] functions. | 7406 ** [sqlite3_errmsg16()] functions. |
7121 ** ^A successful call to sqlite3_backup_init() returns a pointer to an | 7407 ** ^A successful call to sqlite3_backup_init() returns a pointer to an |
(...skipping 121 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
7243 ** backed up to is not accessed by any connection within the process, | 7529 ** backed up to is not accessed by any connection within the process, |
7244 ** not just the specific connection that was passed to sqlite3_backup_init(). | 7530 ** not just the specific connection that was passed to sqlite3_backup_init(). |
7245 ** | 7531 ** |
7246 ** The [sqlite3_backup] object itself is partially threadsafe. Multiple | 7532 ** The [sqlite3_backup] object itself is partially threadsafe. Multiple |
7247 ** threads may safely make multiple concurrent calls to sqlite3_backup_step(). | 7533 ** threads may safely make multiple concurrent calls to sqlite3_backup_step(). |
7248 ** However, the sqlite3_backup_remaining() and sqlite3_backup_pagecount() | 7534 ** However, the sqlite3_backup_remaining() and sqlite3_backup_pagecount() |
7249 ** APIs are not strictly speaking threadsafe. If they are invoked at the | 7535 ** APIs are not strictly speaking threadsafe. If they are invoked at the |
7250 ** same time as another thread is invoking sqlite3_backup_step() it is | 7536 ** same time as another thread is invoking sqlite3_backup_step() it is |
7251 ** possible that they return invalid values. | 7537 ** possible that they return invalid values. |
7252 */ | 7538 */ |
7253 SQLITE_API sqlite3_backup *SQLITE_STDCALL sqlite3_backup_init( | 7539 SQLITE_API sqlite3_backup *sqlite3_backup_init( |
7254 sqlite3 *pDest, /* Destination database handle */ | 7540 sqlite3 *pDest, /* Destination database handle */ |
7255 const char *zDestName, /* Destination database name */ | 7541 const char *zDestName, /* Destination database name */ |
7256 sqlite3 *pSource, /* Source database handle */ | 7542 sqlite3 *pSource, /* Source database handle */ |
7257 const char *zSourceName /* Source database name */ | 7543 const char *zSourceName /* Source database name */ |
7258 ); | 7544 ); |
7259 SQLITE_API int SQLITE_STDCALL sqlite3_backup_step(sqlite3_backup *p, int nPage); | 7545 SQLITE_API int sqlite3_backup_step(sqlite3_backup *p, int nPage); |
7260 SQLITE_API int SQLITE_STDCALL sqlite3_backup_finish(sqlite3_backup *p); | 7546 SQLITE_API int sqlite3_backup_finish(sqlite3_backup *p); |
7261 SQLITE_API int SQLITE_STDCALL sqlite3_backup_remaining(sqlite3_backup *p); | 7547 SQLITE_API int sqlite3_backup_remaining(sqlite3_backup *p); |
7262 SQLITE_API int SQLITE_STDCALL sqlite3_backup_pagecount(sqlite3_backup *p); | 7548 SQLITE_API int sqlite3_backup_pagecount(sqlite3_backup *p); |
7263 | 7549 |
7264 /* | 7550 /* |
7265 ** CAPI3REF: Unlock Notification | 7551 ** CAPI3REF: Unlock Notification |
7266 ** METHOD: sqlite3 | 7552 ** METHOD: sqlite3 |
7267 ** | 7553 ** |
7268 ** ^When running in shared-cache mode, a database operation may fail with | 7554 ** ^When running in shared-cache mode, a database operation may fail with |
7269 ** an [SQLITE_LOCKED] error if the required locks on the shared-cache or | 7555 ** an [SQLITE_LOCKED] error if the required locks on the shared-cache or |
7270 ** individual tables within the shared-cache cannot be obtained. See | 7556 ** individual tables within the shared-cache cannot be obtained. See |
7271 ** [SQLite Shared-Cache Mode] for a description of shared-cache locking. | 7557 ** [SQLite Shared-Cache Mode] for a description of shared-cache locking. |
7272 ** ^This API may be used to register a callback that SQLite will invoke | 7558 ** ^This API may be used to register a callback that SQLite will invoke |
(...skipping 96 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
7369 ** sqlite3_unlock_notify() results in the unlock-notify callback being | 7655 ** sqlite3_unlock_notify() results in the unlock-notify callback being |
7370 ** invoked immediately. If the application then re-attempts the "DROP TABLE" | 7656 ** invoked immediately. If the application then re-attempts the "DROP TABLE" |
7371 ** or "DROP INDEX" query, an infinite loop might be the result. | 7657 ** or "DROP INDEX" query, an infinite loop might be the result. |
7372 ** | 7658 ** |
7373 ** One way around this problem is to check the extended error code returned | 7659 ** One way around this problem is to check the extended error code returned |
7374 ** by an sqlite3_step() call. ^(If there is a blocking connection, then the | 7660 ** by an sqlite3_step() call. ^(If there is a blocking connection, then the |
7375 ** extended error code is set to SQLITE_LOCKED_SHAREDCACHE. Otherwise, in | 7661 ** extended error code is set to SQLITE_LOCKED_SHAREDCACHE. Otherwise, in |
7376 ** the special "DROP TABLE/INDEX" case, the extended error code is just | 7662 ** the special "DROP TABLE/INDEX" case, the extended error code is just |
7377 ** SQLITE_LOCKED.)^ | 7663 ** SQLITE_LOCKED.)^ |
7378 */ | 7664 */ |
7379 SQLITE_API int SQLITE_STDCALL sqlite3_unlock_notify( | 7665 SQLITE_API int sqlite3_unlock_notify( |
7380 sqlite3 *pBlocked, /* Waiting connection */ | 7666 sqlite3 *pBlocked, /* Waiting connection */ |
7381 void (*xNotify)(void **apArg, int nArg), /* Callback function to invoke */ | 7667 void (*xNotify)(void **apArg, int nArg), /* Callback function to invoke */ |
7382 void *pNotifyArg /* Argument to pass to xNotify */ | 7668 void *pNotifyArg /* Argument to pass to xNotify */ |
7383 ); | 7669 ); |
7384 | 7670 |
7385 | 7671 |
7386 /* | 7672 /* |
7387 ** CAPI3REF: String Comparison | 7673 ** CAPI3REF: String Comparison |
7388 ** | 7674 ** |
7389 ** ^The [sqlite3_stricmp()] and [sqlite3_strnicmp()] APIs allow applications | 7675 ** ^The [sqlite3_stricmp()] and [sqlite3_strnicmp()] APIs allow applications |
7390 ** and extensions to compare the contents of two buffers containing UTF-8 | 7676 ** and extensions to compare the contents of two buffers containing UTF-8 |
7391 ** strings in a case-independent fashion, using the same definition of "case | 7677 ** strings in a case-independent fashion, using the same definition of "case |
7392 ** independence" that SQLite uses internally when comparing identifiers. | 7678 ** independence" that SQLite uses internally when comparing identifiers. |
7393 */ | 7679 */ |
7394 SQLITE_API int SQLITE_STDCALL sqlite3_stricmp(const char *, const char *); | 7680 SQLITE_API int sqlite3_stricmp(const char *, const char *); |
7395 SQLITE_API int SQLITE_STDCALL sqlite3_strnicmp(const char *, const char *, int); | 7681 SQLITE_API int sqlite3_strnicmp(const char *, const char *, int); |
7396 | 7682 |
7397 /* | 7683 /* |
7398 ** CAPI3REF: String Globbing | 7684 ** CAPI3REF: String Globbing |
7399 * | 7685 * |
7400 ** ^The [sqlite3_strglob(P,X)] interface returns zero if and only if | 7686 ** ^The [sqlite3_strglob(P,X)] interface returns zero if and only if |
7401 ** string X matches the [GLOB] pattern P. | 7687 ** string X matches the [GLOB] pattern P. |
7402 ** ^The definition of [GLOB] pattern matching used in | 7688 ** ^The definition of [GLOB] pattern matching used in |
7403 ** [sqlite3_strglob(P,X)] is the same as for the "X GLOB P" operator in the | 7689 ** [sqlite3_strglob(P,X)] is the same as for the "X GLOB P" operator in the |
7404 ** SQL dialect understood by SQLite. ^The [sqlite3_strglob(P,X)] function | 7690 ** SQL dialect understood by SQLite. ^The [sqlite3_strglob(P,X)] function |
7405 ** is case sensitive. | 7691 ** is case sensitive. |
7406 ** | 7692 ** |
7407 ** Note that this routine returns zero on a match and non-zero if the strings | 7693 ** Note that this routine returns zero on a match and non-zero if the strings |
7408 ** do not match, the same as [sqlite3_stricmp()] and [sqlite3_strnicmp()]. | 7694 ** do not match, the same as [sqlite3_stricmp()] and [sqlite3_strnicmp()]. |
7409 ** | 7695 ** |
7410 ** See also: [sqlite3_strlike()]. | 7696 ** See also: [sqlite3_strlike()]. |
7411 */ | 7697 */ |
7412 SQLITE_API int SQLITE_STDCALL sqlite3_strglob(const char *zGlob, const char *zSt
r); | 7698 SQLITE_API int sqlite3_strglob(const char *zGlob, const char *zStr); |
7413 | 7699 |
7414 /* Begin WebDatabase patch for Chromium */ | 7700 /* Begin WebDatabase patch for Chromium */ |
7415 /* Expose some SQLite internals for the WebDatabase vfs. | 7701 /* Expose some SQLite internals for the WebDatabase vfs. |
7416 ** DO NOT EXTEND THE USE OF THIS. | 7702 ** DO NOT EXTEND THE USE OF THIS. |
7417 */ | 7703 */ |
7418 #ifndef CHROMIUM_SQLITE_API | 7704 #ifndef CHROMIUM_SQLITE_API |
7419 #define CHROMIUM_SQLITE_API SQLITE_API | 7705 #define CHROMIUM_SQLITE_API SQLITE_API |
7420 #endif | 7706 #endif |
7421 #if defined(CHROMIUM_SQLITE_INTERNALS) | 7707 #if defined(CHROMIUM_SQLITE_INTERNALS) |
7422 #ifdef _WIN32 | 7708 #ifdef _WIN32 |
(...skipping 25 matching lines...) Expand all Loading... |
7448 ** one another. | 7734 ** one another. |
7449 ** | 7735 ** |
7450 ** ^The [sqlite3_strlike(P,X,E)] function matches Unicode characters, though | 7736 ** ^The [sqlite3_strlike(P,X,E)] function matches Unicode characters, though |
7451 ** only ASCII characters are case folded. | 7737 ** only ASCII characters are case folded. |
7452 ** | 7738 ** |
7453 ** Note that this routine returns zero on a match and non-zero if the strings | 7739 ** Note that this routine returns zero on a match and non-zero if the strings |
7454 ** do not match, the same as [sqlite3_stricmp()] and [sqlite3_strnicmp()]. | 7740 ** do not match, the same as [sqlite3_stricmp()] and [sqlite3_strnicmp()]. |
7455 ** | 7741 ** |
7456 ** See also: [sqlite3_strglob()]. | 7742 ** See also: [sqlite3_strglob()]. |
7457 */ | 7743 */ |
7458 SQLITE_API int SQLITE_STDCALL sqlite3_strlike(const char *zGlob, const char *zSt
r, unsigned int cEsc); | 7744 SQLITE_API int sqlite3_strlike(const char *zGlob, const char *zStr, unsigned int
cEsc); |
7459 | 7745 |
7460 /* | 7746 /* |
7461 ** CAPI3REF: Error Logging Interface | 7747 ** CAPI3REF: Error Logging Interface |
7462 ** | 7748 ** |
7463 ** ^The [sqlite3_log()] interface writes a message into the [error log] | 7749 ** ^The [sqlite3_log()] interface writes a message into the [error log] |
7464 ** established by the [SQLITE_CONFIG_LOG] option to [sqlite3_config()]. | 7750 ** established by the [SQLITE_CONFIG_LOG] option to [sqlite3_config()]. |
7465 ** ^If logging is enabled, the zFormat string and subsequent arguments are | 7751 ** ^If logging is enabled, the zFormat string and subsequent arguments are |
7466 ** used with [sqlite3_snprintf()] to generate the final output string. | 7752 ** used with [sqlite3_snprintf()] to generate the final output string. |
7467 ** | 7753 ** |
7468 ** The sqlite3_log() interface is intended for use by extensions such as | 7754 ** The sqlite3_log() interface is intended for use by extensions such as |
7469 ** virtual tables, collating functions, and SQL functions. While there is | 7755 ** virtual tables, collating functions, and SQL functions. While there is |
7470 ** nothing to prevent an application from calling sqlite3_log(), doing so | 7756 ** nothing to prevent an application from calling sqlite3_log(), doing so |
7471 ** is considered bad form. | 7757 ** is considered bad form. |
7472 ** | 7758 ** |
7473 ** The zFormat string must not be NULL. | 7759 ** The zFormat string must not be NULL. |
7474 ** | 7760 ** |
7475 ** To avoid deadlocks and other threading problems, the sqlite3_log() routine | 7761 ** To avoid deadlocks and other threading problems, the sqlite3_log() routine |
7476 ** will not use dynamically allocated memory. The log message is stored in | 7762 ** will not use dynamically allocated memory. The log message is stored in |
7477 ** a fixed-length buffer on the stack. If the log message is longer than | 7763 ** a fixed-length buffer on the stack. If the log message is longer than |
7478 ** a few hundred characters, it will be truncated to the length of the | 7764 ** a few hundred characters, it will be truncated to the length of the |
7479 ** buffer. | 7765 ** buffer. |
7480 */ | 7766 */ |
7481 SQLITE_API void SQLITE_CDECL sqlite3_log(int iErrCode, const char *zFormat, ...)
; | 7767 SQLITE_API void sqlite3_log(int iErrCode, const char *zFormat, ...); |
7482 | 7768 |
7483 /* | 7769 /* |
7484 ** CAPI3REF: Write-Ahead Log Commit Hook | 7770 ** CAPI3REF: Write-Ahead Log Commit Hook |
7485 ** METHOD: sqlite3 | 7771 ** METHOD: sqlite3 |
7486 ** | 7772 ** |
7487 ** ^The [sqlite3_wal_hook()] function is used to register a callback that | 7773 ** ^The [sqlite3_wal_hook()] function is used to register a callback that |
7488 ** is invoked each time data is committed to a database in wal mode. | 7774 ** is invoked each time data is committed to a database in wal mode. |
7489 ** | 7775 ** |
7490 ** ^(The callback is invoked by SQLite after the commit has taken place and | 7776 ** ^(The callback is invoked by SQLite after the commit has taken place and |
7491 ** the associated write-lock on the database released)^, so the implementation | 7777 ** the associated write-lock on the database released)^, so the implementation |
(...skipping 13 matching lines...) Expand all Loading... |
7505 ** to report an error, though the commit will have still occurred. If the | 7791 ** to report an error, though the commit will have still occurred. If the |
7506 ** callback returns [SQLITE_ROW] or [SQLITE_DONE], or if it returns a value | 7792 ** callback returns [SQLITE_ROW] or [SQLITE_DONE], or if it returns a value |
7507 ** that does not correspond to any valid SQLite error code, the results | 7793 ** that does not correspond to any valid SQLite error code, the results |
7508 ** are undefined. | 7794 ** are undefined. |
7509 ** | 7795 ** |
7510 ** A single database handle may have at most a single write-ahead log callback | 7796 ** A single database handle may have at most a single write-ahead log callback |
7511 ** registered at one time. ^Calling [sqlite3_wal_hook()] replaces any | 7797 ** registered at one time. ^Calling [sqlite3_wal_hook()] replaces any |
7512 ** previously registered write-ahead log callback. ^Note that the | 7798 ** previously registered write-ahead log callback. ^Note that the |
7513 ** [sqlite3_wal_autocheckpoint()] interface and the | 7799 ** [sqlite3_wal_autocheckpoint()] interface and the |
7514 ** [wal_autocheckpoint pragma] both invoke [sqlite3_wal_hook()] and will | 7800 ** [wal_autocheckpoint pragma] both invoke [sqlite3_wal_hook()] and will |
7515 ** those overwrite any prior [sqlite3_wal_hook()] settings. | 7801 ** overwrite any prior [sqlite3_wal_hook()] settings. |
7516 */ | 7802 */ |
7517 SQLITE_API void *SQLITE_STDCALL sqlite3_wal_hook( | 7803 SQLITE_API void *sqlite3_wal_hook( |
7518 sqlite3*, | 7804 sqlite3*, |
7519 int(*)(void *,sqlite3*,const char*,int), | 7805 int(*)(void *,sqlite3*,const char*,int), |
7520 void* | 7806 void* |
7521 ); | 7807 ); |
7522 | 7808 |
7523 /* | 7809 /* |
7524 ** CAPI3REF: Configure an auto-checkpoint | 7810 ** CAPI3REF: Configure an auto-checkpoint |
7525 ** METHOD: sqlite3 | 7811 ** METHOD: sqlite3 |
7526 ** | 7812 ** |
7527 ** ^The [sqlite3_wal_autocheckpoint(D,N)] is a wrapper around | 7813 ** ^The [sqlite3_wal_autocheckpoint(D,N)] is a wrapper around |
(...skipping 14 matching lines...) Expand all Loading... |
7542 ** | 7828 ** |
7543 ** ^Checkpoints initiated by this mechanism are | 7829 ** ^Checkpoints initiated by this mechanism are |
7544 ** [sqlite3_wal_checkpoint_v2|PASSIVE]. | 7830 ** [sqlite3_wal_checkpoint_v2|PASSIVE]. |
7545 ** | 7831 ** |
7546 ** ^Every new [database connection] defaults to having the auto-checkpoint | 7832 ** ^Every new [database connection] defaults to having the auto-checkpoint |
7547 ** enabled with a threshold of 1000 or [SQLITE_DEFAULT_WAL_AUTOCHECKPOINT] | 7833 ** enabled with a threshold of 1000 or [SQLITE_DEFAULT_WAL_AUTOCHECKPOINT] |
7548 ** pages. The use of this interface | 7834 ** pages. The use of this interface |
7549 ** is only necessary if the default setting is found to be suboptimal | 7835 ** is only necessary if the default setting is found to be suboptimal |
7550 ** for a particular application. | 7836 ** for a particular application. |
7551 */ | 7837 */ |
7552 SQLITE_API int SQLITE_STDCALL sqlite3_wal_autocheckpoint(sqlite3 *db, int N); | 7838 SQLITE_API int sqlite3_wal_autocheckpoint(sqlite3 *db, int N); |
7553 | 7839 |
7554 /* | 7840 /* |
7555 ** CAPI3REF: Checkpoint a database | 7841 ** CAPI3REF: Checkpoint a database |
7556 ** METHOD: sqlite3 | 7842 ** METHOD: sqlite3 |
7557 ** | 7843 ** |
7558 ** ^(The sqlite3_wal_checkpoint(D,X) is equivalent to | 7844 ** ^(The sqlite3_wal_checkpoint(D,X) is equivalent to |
7559 ** [sqlite3_wal_checkpoint_v2](D,X,[SQLITE_CHECKPOINT_PASSIVE],0,0).)^ | 7845 ** [sqlite3_wal_checkpoint_v2](D,X,[SQLITE_CHECKPOINT_PASSIVE],0,0).)^ |
7560 ** | 7846 ** |
7561 ** In brief, sqlite3_wal_checkpoint(D,X) causes the content in the | 7847 ** In brief, sqlite3_wal_checkpoint(D,X) causes the content in the |
7562 ** [write-ahead log] for database X on [database connection] D to be | 7848 ** [write-ahead log] for database X on [database connection] D to be |
7563 ** transferred into the database file and for the write-ahead log to | 7849 ** transferred into the database file and for the write-ahead log to |
7564 ** be reset. See the [checkpointing] documentation for addition | 7850 ** be reset. See the [checkpointing] documentation for addition |
7565 ** information. | 7851 ** information. |
7566 ** | 7852 ** |
7567 ** This interface used to be the only way to cause a checkpoint to | 7853 ** This interface used to be the only way to cause a checkpoint to |
7568 ** occur. But then the newer and more powerful [sqlite3_wal_checkpoint_v2()] | 7854 ** occur. But then the newer and more powerful [sqlite3_wal_checkpoint_v2()] |
7569 ** interface was added. This interface is retained for backwards | 7855 ** interface was added. This interface is retained for backwards |
7570 ** compatibility and as a convenience for applications that need to manually | 7856 ** compatibility and as a convenience for applications that need to manually |
7571 ** start a callback but which do not need the full power (and corresponding | 7857 ** start a callback but which do not need the full power (and corresponding |
7572 ** complication) of [sqlite3_wal_checkpoint_v2()]. | 7858 ** complication) of [sqlite3_wal_checkpoint_v2()]. |
7573 */ | 7859 */ |
7574 SQLITE_API int SQLITE_STDCALL sqlite3_wal_checkpoint(sqlite3 *db, const char *zD
b); | 7860 SQLITE_API int sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb); |
7575 | 7861 |
7576 /* | 7862 /* |
7577 ** CAPI3REF: Checkpoint a database | 7863 ** CAPI3REF: Checkpoint a database |
7578 ** METHOD: sqlite3 | 7864 ** METHOD: sqlite3 |
7579 ** | 7865 ** |
7580 ** ^(The sqlite3_wal_checkpoint_v2(D,X,M,L,C) interface runs a checkpoint | 7866 ** ^(The sqlite3_wal_checkpoint_v2(D,X,M,L,C) interface runs a checkpoint |
7581 ** operation on database X of [database connection] D in mode M. Status | 7867 ** operation on database X of [database connection] D in mode M. Status |
7582 ** information is written back into integers pointed to by L and C.)^ | 7868 ** information is written back into integers pointed to by L and C.)^ |
7583 ** ^(The M parameter must be a valid [checkpoint mode]:)^ | 7869 ** ^(The M parameter must be a valid [checkpoint mode]:)^ |
7584 ** | 7870 ** |
(...skipping 73 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
7658 ** attached database, SQLITE_ERROR is returned to the caller. | 7944 ** attached database, SQLITE_ERROR is returned to the caller. |
7659 ** | 7945 ** |
7660 ** ^Unless it returns SQLITE_MISUSE, | 7946 ** ^Unless it returns SQLITE_MISUSE, |
7661 ** the sqlite3_wal_checkpoint_v2() interface | 7947 ** the sqlite3_wal_checkpoint_v2() interface |
7662 ** sets the error information that is queried by | 7948 ** sets the error information that is queried by |
7663 ** [sqlite3_errcode()] and [sqlite3_errmsg()]. | 7949 ** [sqlite3_errcode()] and [sqlite3_errmsg()]. |
7664 ** | 7950 ** |
7665 ** ^The [PRAGMA wal_checkpoint] command can be used to invoke this interface | 7951 ** ^The [PRAGMA wal_checkpoint] command can be used to invoke this interface |
7666 ** from SQL. | 7952 ** from SQL. |
7667 */ | 7953 */ |
7668 SQLITE_API int SQLITE_STDCALL sqlite3_wal_checkpoint_v2( | 7954 SQLITE_API int sqlite3_wal_checkpoint_v2( |
7669 sqlite3 *db, /* Database handle */ | 7955 sqlite3 *db, /* Database handle */ |
7670 const char *zDb, /* Name of attached database (or NULL) */ | 7956 const char *zDb, /* Name of attached database (or NULL) */ |
7671 int eMode, /* SQLITE_CHECKPOINT_* value */ | 7957 int eMode, /* SQLITE_CHECKPOINT_* value */ |
7672 int *pnLog, /* OUT: Size of WAL log in frames */ | 7958 int *pnLog, /* OUT: Size of WAL log in frames */ |
7673 int *pnCkpt /* OUT: Total number of frames checkpointed */ | 7959 int *pnCkpt /* OUT: Total number of frames checkpointed */ |
7674 ); | 7960 ); |
7675 | 7961 |
7676 /* | 7962 /* |
7677 ** CAPI3REF: Checkpoint Mode Values | 7963 ** CAPI3REF: Checkpoint Mode Values |
7678 ** KEYWORDS: {checkpoint mode} | 7964 ** KEYWORDS: {checkpoint mode} |
(...skipping 15 matching lines...) Expand all Loading... |
7694 ** of a [virtual table] implementation to configure | 7980 ** of a [virtual table] implementation to configure |
7695 ** various facets of the virtual table interface. | 7981 ** various facets of the virtual table interface. |
7696 ** | 7982 ** |
7697 ** If this interface is invoked outside the context of an xConnect or | 7983 ** If this interface is invoked outside the context of an xConnect or |
7698 ** xCreate virtual table method then the behavior is undefined. | 7984 ** xCreate virtual table method then the behavior is undefined. |
7699 ** | 7985 ** |
7700 ** At present, there is only one option that may be configured using | 7986 ** At present, there is only one option that may be configured using |
7701 ** this function. (See [SQLITE_VTAB_CONSTRAINT_SUPPORT].) Further options | 7987 ** this function. (See [SQLITE_VTAB_CONSTRAINT_SUPPORT].) Further options |
7702 ** may be added in the future. | 7988 ** may be added in the future. |
7703 */ | 7989 */ |
7704 SQLITE_API int SQLITE_CDECL sqlite3_vtab_config(sqlite3*, int op, ...); | 7990 SQLITE_API int sqlite3_vtab_config(sqlite3*, int op, ...); |
7705 | 7991 |
7706 /* | 7992 /* |
7707 ** CAPI3REF: Virtual Table Configuration Options | 7993 ** CAPI3REF: Virtual Table Configuration Options |
7708 ** | 7994 ** |
7709 ** These macros define the various options to the | 7995 ** These macros define the various options to the |
7710 ** [sqlite3_vtab_config()] interface that [virtual table] implementations | 7996 ** [sqlite3_vtab_config()] interface that [virtual table] implementations |
7711 ** can use to customize and optimize their behavior. | 7997 ** can use to customize and optimize their behavior. |
7712 ** | 7998 ** |
7713 ** <dl> | 7999 ** <dl> |
7714 ** <dt>SQLITE_VTAB_CONSTRAINT_SUPPORT | 8000 ** <dt>SQLITE_VTAB_CONSTRAINT_SUPPORT |
(...skipping 32 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
7747 /* | 8033 /* |
7748 ** CAPI3REF: Determine The Virtual Table Conflict Policy | 8034 ** CAPI3REF: Determine The Virtual Table Conflict Policy |
7749 ** | 8035 ** |
7750 ** This function may only be called from within a call to the [xUpdate] method | 8036 ** This function may only be called from within a call to the [xUpdate] method |
7751 ** of a [virtual table] implementation for an INSERT or UPDATE operation. ^The | 8037 ** of a [virtual table] implementation for an INSERT or UPDATE operation. ^The |
7752 ** value returned is one of [SQLITE_ROLLBACK], [SQLITE_IGNORE], [SQLITE_FAIL], | 8038 ** value returned is one of [SQLITE_ROLLBACK], [SQLITE_IGNORE], [SQLITE_FAIL], |
7753 ** [SQLITE_ABORT], or [SQLITE_REPLACE], according to the [ON CONFLICT] mode | 8039 ** [SQLITE_ABORT], or [SQLITE_REPLACE], according to the [ON CONFLICT] mode |
7754 ** of the SQL statement that triggered the call to the [xUpdate] method of the | 8040 ** of the SQL statement that triggered the call to the [xUpdate] method of the |
7755 ** [virtual table]. | 8041 ** [virtual table]. |
7756 */ | 8042 */ |
7757 SQLITE_API int SQLITE_STDCALL sqlite3_vtab_on_conflict(sqlite3 *); | 8043 SQLITE_API int sqlite3_vtab_on_conflict(sqlite3 *); |
7758 | 8044 |
7759 /* | 8045 /* |
7760 ** CAPI3REF: Conflict resolution modes | 8046 ** CAPI3REF: Conflict resolution modes |
7761 ** KEYWORDS: {conflict resolution mode} | 8047 ** KEYWORDS: {conflict resolution mode} |
7762 ** | 8048 ** |
7763 ** These constants are returned by [sqlite3_vtab_on_conflict()] to | 8049 ** These constants are returned by [sqlite3_vtab_on_conflict()] to |
7764 ** inform a [virtual table] implementation what the [ON CONFLICT] mode | 8050 ** inform a [virtual table] implementation what the [ON CONFLICT] mode |
7765 ** is for the SQL statement being evaluated. | 8051 ** is for the SQL statement being evaluated. |
7766 ** | 8052 ** |
7767 ** Note that the [SQLITE_IGNORE] constant is also used as a potential | 8053 ** Note that the [SQLITE_IGNORE] constant is also used as a potential |
(...skipping 84 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
7852 ** the statement - a non-zero value is returned and the variable that pOut | 8138 ** the statement - a non-zero value is returned and the variable that pOut |
7853 ** points to is unchanged. | 8139 ** points to is unchanged. |
7854 ** | 8140 ** |
7855 ** ^Statistics might not be available for all loops in all statements. ^In cases | 8141 ** ^Statistics might not be available for all loops in all statements. ^In cases |
7856 ** where there exist loops with no available statistics, this function behaves | 8142 ** where there exist loops with no available statistics, this function behaves |
7857 ** as if the loop did not exist - it returns non-zero and leave the variable | 8143 ** as if the loop did not exist - it returns non-zero and leave the variable |
7858 ** that pOut points to unchanged. | 8144 ** that pOut points to unchanged. |
7859 ** | 8145 ** |
7860 ** See also: [sqlite3_stmt_scanstatus_reset()] | 8146 ** See also: [sqlite3_stmt_scanstatus_reset()] |
7861 */ | 8147 */ |
7862 SQLITE_API int SQLITE_STDCALL sqlite3_stmt_scanstatus( | 8148 SQLITE_API int sqlite3_stmt_scanstatus( |
7863 sqlite3_stmt *pStmt, /* Prepared statement for which info desired */ | 8149 sqlite3_stmt *pStmt, /* Prepared statement for which info desired */ |
7864 int idx, /* Index of loop to report on */ | 8150 int idx, /* Index of loop to report on */ |
7865 int iScanStatusOp, /* Information desired. SQLITE_SCANSTAT_* */ | 8151 int iScanStatusOp, /* Information desired. SQLITE_SCANSTAT_* */ |
7866 void *pOut /* Result written here */ | 8152 void *pOut /* Result written here */ |
7867 ); | 8153 ); |
7868 | 8154 |
7869 /* | 8155 /* |
7870 ** CAPI3REF: Zero Scan-Status Counters | 8156 ** CAPI3REF: Zero Scan-Status Counters |
7871 ** METHOD: sqlite3_stmt | 8157 ** METHOD: sqlite3_stmt |
7872 ** | 8158 ** |
7873 ** ^Zero all [sqlite3_stmt_scanstatus()] related event counters. | 8159 ** ^Zero all [sqlite3_stmt_scanstatus()] related event counters. |
7874 ** | 8160 ** |
7875 ** This API is only available if the library is built with pre-processor | 8161 ** This API is only available if the library is built with pre-processor |
7876 ** symbol [SQLITE_ENABLE_STMT_SCANSTATUS] defined. | 8162 ** symbol [SQLITE_ENABLE_STMT_SCANSTATUS] defined. |
7877 */ | 8163 */ |
7878 SQLITE_API void SQLITE_STDCALL sqlite3_stmt_scanstatus_reset(sqlite3_stmt*); | 8164 SQLITE_API void sqlite3_stmt_scanstatus_reset(sqlite3_stmt*); |
7879 | 8165 |
7880 /* | 8166 /* |
7881 ** CAPI3REF: Flush caches to disk mid-transaction | 8167 ** CAPI3REF: Flush caches to disk mid-transaction |
7882 ** | 8168 ** |
7883 ** ^If a write-transaction is open on [database connection] D when the | 8169 ** ^If a write-transaction is open on [database connection] D when the |
7884 ** [sqlite3_db_cacheflush(D)] interface invoked, any dirty | 8170 ** [sqlite3_db_cacheflush(D)] interface invoked, any dirty |
7885 ** pages in the pager-cache that are not currently in use are written out | 8171 ** pages in the pager-cache that are not currently in use are written out |
7886 ** to disk. A dirty page may be in use if a database cursor created by an | 8172 ** to disk. A dirty page may be in use if a database cursor created by an |
7887 ** active SQL statement is reading from it, or if it is page 1 of a database | 8173 ** active SQL statement is reading from it, or if it is page 1 of a database |
7888 ** file (page 1 is always "in use"). ^The [sqlite3_db_cacheflush(D)] | 8174 ** file (page 1 is always "in use"). ^The [sqlite3_db_cacheflush(D)] |
(...skipping 11 matching lines...) Expand all Loading... |
7900 ** | 8186 ** |
7901 ** ^If any other error occurs while flushing dirty pages to disk (for | 8187 ** ^If any other error occurs while flushing dirty pages to disk (for |
7902 ** example an IO error or out-of-memory condition), then processing is | 8188 ** example an IO error or out-of-memory condition), then processing is |
7903 ** abandoned and an SQLite [error code] is returned to the caller immediately. | 8189 ** abandoned and an SQLite [error code] is returned to the caller immediately. |
7904 ** | 8190 ** |
7905 ** ^Otherwise, if no error occurs, [sqlite3_db_cacheflush()] returns SQLITE_OK. | 8191 ** ^Otherwise, if no error occurs, [sqlite3_db_cacheflush()] returns SQLITE_OK. |
7906 ** | 8192 ** |
7907 ** ^This function does not set the database handle error code or message | 8193 ** ^This function does not set the database handle error code or message |
7908 ** returned by the [sqlite3_errcode()] and [sqlite3_errmsg()] functions. | 8194 ** returned by the [sqlite3_errcode()] and [sqlite3_errmsg()] functions. |
7909 */ | 8195 */ |
7910 SQLITE_API int SQLITE_STDCALL sqlite3_db_cacheflush(sqlite3*); | 8196 SQLITE_API int sqlite3_db_cacheflush(sqlite3*); |
| 8197 |
| 8198 /* |
| 8199 ** CAPI3REF: The pre-update hook. |
| 8200 ** |
| 8201 ** ^These interfaces are only available if SQLite is compiled using the |
| 8202 ** [SQLITE_ENABLE_PREUPDATE_HOOK] compile-time option. |
| 8203 ** |
| 8204 ** ^The [sqlite3_preupdate_hook()] interface registers a callback function |
| 8205 ** that is invoked prior to each [INSERT], [UPDATE], and [DELETE] operation |
| 8206 ** on a database table. |
| 8207 ** ^At most one preupdate hook may be registered at a time on a single |
| 8208 ** [database connection]; each call to [sqlite3_preupdate_hook()] overrides |
| 8209 ** the previous setting. |
| 8210 ** ^The preupdate hook is disabled by invoking [sqlite3_preupdate_hook()] |
| 8211 ** with a NULL pointer as the second parameter. |
| 8212 ** ^The third parameter to [sqlite3_preupdate_hook()] is passed through as |
| 8213 ** the first parameter to callbacks. |
| 8214 ** |
| 8215 ** ^The preupdate hook only fires for changes to real database tables; the |
| 8216 ** preupdate hook is not invoked for changes to [virtual tables] or to |
| 8217 ** system tables like sqlite_master or sqlite_stat1. |
| 8218 ** |
| 8219 ** ^The second parameter to the preupdate callback is a pointer to |
| 8220 ** the [database connection] that registered the preupdate hook. |
| 8221 ** ^The third parameter to the preupdate callback is one of the constants |
| 8222 ** [SQLITE_INSERT], [SQLITE_DELETE], or [SQLITE_UPDATE] to identify the |
| 8223 ** kind of update operation that is about to occur. |
| 8224 ** ^(The fourth parameter to the preupdate callback is the name of the |
| 8225 ** database within the database connection that is being modified. This |
| 8226 ** will be "main" for the main database or "temp" for TEMP tables or |
| 8227 ** the name given after the AS keyword in the [ATTACH] statement for attached |
| 8228 ** databases.)^ |
| 8229 ** ^The fifth parameter to the preupdate callback is the name of the |
| 8230 ** table that is being modified. |
| 8231 ** |
| 8232 ** For an UPDATE or DELETE operation on a [rowid table], the sixth |
| 8233 ** parameter passed to the preupdate callback is the initial [rowid] of the |
| 8234 ** row being modified or deleted. For an INSERT operation on a rowid table, |
| 8235 ** or any operation on a WITHOUT ROWID table, the value of the sixth |
| 8236 ** parameter is undefined. For an INSERT or UPDATE on a rowid table the |
| 8237 ** seventh parameter is the final rowid value of the row being inserted |
| 8238 ** or updated. The value of the seventh parameter passed to the callback |
| 8239 ** function is not defined for operations on WITHOUT ROWID tables, or for |
| 8240 ** INSERT operations on rowid tables. |
| 8241 ** |
| 8242 ** The [sqlite3_preupdate_old()], [sqlite3_preupdate_new()], |
| 8243 ** [sqlite3_preupdate_count()], and [sqlite3_preupdate_depth()] interfaces |
| 8244 ** provide additional information about a preupdate event. These routines |
| 8245 ** may only be called from within a preupdate callback. Invoking any of |
| 8246 ** these routines from outside of a preupdate callback or with a |
| 8247 ** [database connection] pointer that is different from the one supplied |
| 8248 ** to the preupdate callback results in undefined and probably undesirable |
| 8249 ** behavior. |
| 8250 ** |
| 8251 ** ^The [sqlite3_preupdate_count(D)] interface returns the number of columns |
| 8252 ** in the row that is being inserted, updated, or deleted. |
| 8253 ** |
| 8254 ** ^The [sqlite3_preupdate_old(D,N,P)] interface writes into P a pointer to |
| 8255 ** a [protected sqlite3_value] that contains the value of the Nth column of |
| 8256 ** the table row before it is updated. The N parameter must be between 0 |
| 8257 ** and one less than the number of columns or the behavior will be |
| 8258 ** undefined. This must only be used within SQLITE_UPDATE and SQLITE_DELETE |
| 8259 ** preupdate callbacks; if it is used by an SQLITE_INSERT callback then the |
| 8260 ** behavior is undefined. The [sqlite3_value] that P points to |
| 8261 ** will be destroyed when the preupdate callback returns. |
| 8262 ** |
| 8263 ** ^The [sqlite3_preupdate_new(D,N,P)] interface writes into P a pointer to |
| 8264 ** a [protected sqlite3_value] that contains the value of the Nth column of |
| 8265 ** the table row after it is updated. The N parameter must be between 0 |
| 8266 ** and one less than the number of columns or the behavior will be |
| 8267 ** undefined. This must only be used within SQLITE_INSERT and SQLITE_UPDATE |
| 8268 ** preupdate callbacks; if it is used by an SQLITE_DELETE callback then the |
| 8269 ** behavior is undefined. The [sqlite3_value] that P points to |
| 8270 ** will be destroyed when the preupdate callback returns. |
| 8271 ** |
| 8272 ** ^The [sqlite3_preupdate_depth(D)] interface returns 0 if the preupdate |
| 8273 ** callback was invoked as a result of a direct insert, update, or delete |
| 8274 ** operation; or 1 for inserts, updates, or deletes invoked by top-level |
| 8275 ** triggers; or 2 for changes resulting from triggers called by top-level |
| 8276 ** triggers; and so forth. |
| 8277 ** |
| 8278 ** See also: [sqlite3_update_hook()] |
| 8279 */ |
| 8280 #if defined(SQLITE_ENABLE_PREUPDATE_HOOK) |
| 8281 SQLITE_API void *sqlite3_preupdate_hook( |
| 8282 sqlite3 *db, |
| 8283 void(*xPreUpdate)( |
| 8284 void *pCtx, /* Copy of third arg to preupdate_hook() */ |
| 8285 sqlite3 *db, /* Database handle */ |
| 8286 int op, /* SQLITE_UPDATE, DELETE or INSERT */ |
| 8287 char const *zDb, /* Database name */ |
| 8288 char const *zName, /* Table name */ |
| 8289 sqlite3_int64 iKey1, /* Rowid of row about to be deleted/updated */ |
| 8290 sqlite3_int64 iKey2 /* New rowid value (for a rowid UPDATE) */ |
| 8291 ), |
| 8292 void* |
| 8293 ); |
| 8294 SQLITE_API int sqlite3_preupdate_old(sqlite3 *, int, sqlite3_value **); |
| 8295 SQLITE_API int sqlite3_preupdate_count(sqlite3 *); |
| 8296 SQLITE_API int sqlite3_preupdate_depth(sqlite3 *); |
| 8297 SQLITE_API int sqlite3_preupdate_new(sqlite3 *, int, sqlite3_value **); |
| 8298 #endif |
| 8299 |
| 8300 /* |
| 8301 ** CAPI3REF: Low-level system error code |
| 8302 ** |
| 8303 ** ^Attempt to return the underlying operating system error code or error |
| 8304 ** number that caused the most recent I/O error or failure to open a file. |
| 8305 ** The return value is OS-dependent. For example, on unix systems, after |
| 8306 ** [sqlite3_open_v2()] returns [SQLITE_CANTOPEN], this interface could be |
| 8307 ** called to get back the underlying "errno" that caused the problem, such |
| 8308 ** as ENOSPC, EAUTH, EISDIR, and so forth. |
| 8309 */ |
| 8310 SQLITE_API int sqlite3_system_errno(sqlite3*); |
7911 | 8311 |
7912 /* | 8312 /* |
7913 ** CAPI3REF: Database Snapshot | 8313 ** CAPI3REF: Database Snapshot |
7914 ** KEYWORDS: {snapshot} | 8314 ** KEYWORDS: {snapshot} {sqlite3_snapshot} |
7915 ** EXPERIMENTAL | 8315 ** EXPERIMENTAL |
7916 ** | 8316 ** |
7917 ** An instance of the snapshot object records the state of a [WAL mode] | 8317 ** An instance of the snapshot object records the state of a [WAL mode] |
7918 ** database for some specific point in history. | 8318 ** database for some specific point in history. |
7919 ** | 8319 ** |
7920 ** In [WAL mode], multiple [database connections] that are open on the | 8320 ** In [WAL mode], multiple [database connections] that are open on the |
7921 ** same database file can each be reading a different historical version | 8321 ** same database file can each be reading a different historical version |
7922 ** of the database file. When a [database connection] begins a read | 8322 ** of the database file. When a [database connection] begins a read |
7923 ** transaction, that connection sees an unchanging copy of the database | 8323 ** transaction, that connection sees an unchanging copy of the database |
7924 ** as it existed for the point in time when the transaction first started. | 8324 ** as it existed for the point in time when the transaction first started. |
7925 ** Subsequent changes to the database from other connections are not seen | 8325 ** Subsequent changes to the database from other connections are not seen |
7926 ** by the reader until a new read transaction is started. | 8326 ** by the reader until a new read transaction is started. |
7927 ** | 8327 ** |
7928 ** The sqlite3_snapshot object records state information about an historical | 8328 ** The sqlite3_snapshot object records state information about an historical |
7929 ** version of the database file so that it is possible to later open a new read | 8329 ** version of the database file so that it is possible to later open a new read |
7930 ** transaction that sees that historical version of the database rather than | 8330 ** transaction that sees that historical version of the database rather than |
7931 ** the most recent version. | 8331 ** the most recent version. |
7932 ** | 8332 ** |
7933 ** The constructor for this object is [sqlite3_snapshot_get()]. The | 8333 ** The constructor for this object is [sqlite3_snapshot_get()]. The |
7934 ** [sqlite3_snapshot_open()] method causes a fresh read transaction to refer | 8334 ** [sqlite3_snapshot_open()] method causes a fresh read transaction to refer |
7935 ** to an historical snapshot (if possible). The destructor for | 8335 ** to an historical snapshot (if possible). The destructor for |
7936 ** sqlite3_snapshot objects is [sqlite3_snapshot_free()]. | 8336 ** sqlite3_snapshot objects is [sqlite3_snapshot_free()]. |
7937 */ | 8337 */ |
7938 typedef struct sqlite3_snapshot sqlite3_snapshot; | 8338 typedef struct sqlite3_snapshot { |
| 8339 unsigned char hidden[48]; |
| 8340 } sqlite3_snapshot; |
7939 | 8341 |
7940 /* | 8342 /* |
7941 ** CAPI3REF: Record A Database Snapshot | 8343 ** CAPI3REF: Record A Database Snapshot |
7942 ** EXPERIMENTAL | 8344 ** EXPERIMENTAL |
7943 ** | 8345 ** |
7944 ** ^The [sqlite3_snapshot_get(D,S,P)] interface attempts to make a | 8346 ** ^The [sqlite3_snapshot_get(D,S,P)] interface attempts to make a |
7945 ** new [sqlite3_snapshot] object that records the current state of | 8347 ** new [sqlite3_snapshot] object that records the current state of |
7946 ** schema S in database connection D. ^On success, the | 8348 ** schema S in database connection D. ^On success, the |
7947 ** [sqlite3_snapshot_get(D,S,P)] interface writes a pointer to the newly | 8349 ** [sqlite3_snapshot_get(D,S,P)] interface writes a pointer to the newly |
7948 ** created [sqlite3_snapshot] object into *P and returns SQLITE_OK. | 8350 ** created [sqlite3_snapshot] object into *P and returns SQLITE_OK. |
7949 ** ^If schema S of [database connection] D is not a [WAL mode] database | 8351 ** If there is not already a read-transaction open on schema S when |
7950 ** that is in a read transaction, then [sqlite3_snapshot_get(D,S,P)] | 8352 ** this function is called, one is opened automatically. |
7951 ** leaves the *P value unchanged and returns an appropriate [error code]. | 8353 ** |
| 8354 ** The following must be true for this function to succeed. If any of |
| 8355 ** the following statements are false when sqlite3_snapshot_get() is |
| 8356 ** called, SQLITE_ERROR is returned. The final value of *P is undefined |
| 8357 ** in this case. |
| 8358 ** |
| 8359 ** <ul> |
| 8360 ** <li> The database handle must be in [autocommit mode]. |
| 8361 ** |
| 8362 ** <li> Schema S of [database connection] D must be a [WAL mode] database. |
| 8363 ** |
| 8364 ** <li> There must not be a write transaction open on schema S of database |
| 8365 ** connection D. |
| 8366 ** |
| 8367 ** <li> One or more transactions must have been written to the current wal |
| 8368 ** file since it was created on disk (by any connection). This means |
| 8369 ** that a snapshot cannot be taken on a wal mode database with no wal |
| 8370 ** file immediately after it is first opened. At least one transaction |
| 8371 ** must be written to it first. |
| 8372 ** </ul> |
| 8373 ** |
| 8374 ** This function may also return SQLITE_NOMEM. If it is called with the |
| 8375 ** database handle in autocommit mode but fails for some other reason, |
| 8376 ** whether or not a read transaction is opened on schema S is undefined. |
7952 ** | 8377 ** |
7953 ** The [sqlite3_snapshot] object returned from a successful call to | 8378 ** The [sqlite3_snapshot] object returned from a successful call to |
7954 ** [sqlite3_snapshot_get()] must be freed using [sqlite3_snapshot_free()] | 8379 ** [sqlite3_snapshot_get()] must be freed using [sqlite3_snapshot_free()] |
7955 ** to avoid a memory leak. | 8380 ** to avoid a memory leak. |
7956 ** | 8381 ** |
7957 ** The [sqlite3_snapshot_get()] interface is only available when the | 8382 ** The [sqlite3_snapshot_get()] interface is only available when the |
7958 ** SQLITE_ENABLE_SNAPSHOT compile-time option is used. | 8383 ** SQLITE_ENABLE_SNAPSHOT compile-time option is used. |
7959 */ | 8384 */ |
7960 SQLITE_API SQLITE_EXPERIMENTAL int SQLITE_STDCALL sqlite3_snapshot_get( | 8385 SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_get( |
7961 sqlite3 *db, | 8386 sqlite3 *db, |
7962 const char *zSchema, | 8387 const char *zSchema, |
7963 sqlite3_snapshot **ppSnapshot | 8388 sqlite3_snapshot **ppSnapshot |
7964 ); | 8389 ); |
7965 | 8390 |
7966 /* | 8391 /* |
7967 ** CAPI3REF: Start a read transaction on an historical snapshot | 8392 ** CAPI3REF: Start a read transaction on an historical snapshot |
7968 ** EXPERIMENTAL | 8393 ** EXPERIMENTAL |
7969 ** | 8394 ** |
7970 ** ^The [sqlite3_snapshot_open(D,S,P)] interface attempts to move the | 8395 ** ^The [sqlite3_snapshot_open(D,S,P)] interface starts a |
7971 ** read transaction that is currently open on schema S of | 8396 ** read transaction for schema S of |
7972 ** [database connection] D so that it refers to historical [snapshot] P. | 8397 ** [database connection] D such that the read transaction |
| 8398 ** refers to historical [snapshot] P, rather than the most |
| 8399 ** recent change to the database. |
7973 ** ^The [sqlite3_snapshot_open()] interface returns SQLITE_OK on success | 8400 ** ^The [sqlite3_snapshot_open()] interface returns SQLITE_OK on success |
7974 ** or an appropriate [error code] if it fails. | 8401 ** or an appropriate [error code] if it fails. |
7975 ** | 8402 ** |
7976 ** ^In order to succeed, a call to [sqlite3_snapshot_open(D,S,P)] must be | 8403 ** ^In order to succeed, a call to [sqlite3_snapshot_open(D,S,P)] must be |
7977 ** the first operation, apart from other sqlite3_snapshot_open() calls, | 8404 ** the first operation following the [BEGIN] that takes the schema S |
7978 ** following the [BEGIN] that starts a new read transaction. | 8405 ** out of [autocommit mode]. |
7979 ** ^A [snapshot] will fail to open if it has been overwritten by a | 8406 ** ^In other words, schema S must not currently be in |
7980 ** [checkpoint]. | 8407 ** a transaction for [sqlite3_snapshot_open(D,S,P)] to work, but the |
| 8408 ** database connection D must be out of [autocommit mode]. |
| 8409 ** ^A [snapshot] will fail to open if it has been overwritten by a |
| 8410 ** [checkpoint]. |
| 8411 ** ^(A call to [sqlite3_snapshot_open(D,S,P)] will fail if the |
| 8412 ** database connection D does not know that the database file for |
| 8413 ** schema S is in [WAL mode]. A database connection might not know |
| 8414 ** that the database file is in [WAL mode] if there has been no prior |
| 8415 ** I/O on that database connection, or if the database entered [WAL mode] |
| 8416 ** after the most recent I/O on the database connection.)^ |
| 8417 ** (Hint: Run "[PRAGMA application_id]" against a newly opened |
| 8418 ** database connection in order to make it ready to use snapshots.) |
7981 ** | 8419 ** |
7982 ** The [sqlite3_snapshot_open()] interface is only available when the | 8420 ** The [sqlite3_snapshot_open()] interface is only available when the |
7983 ** SQLITE_ENABLE_SNAPSHOT compile-time option is used. | 8421 ** SQLITE_ENABLE_SNAPSHOT compile-time option is used. |
7984 */ | 8422 */ |
7985 SQLITE_API SQLITE_EXPERIMENTAL int SQLITE_STDCALL sqlite3_snapshot_open( | 8423 SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_open( |
7986 sqlite3 *db, | 8424 sqlite3 *db, |
7987 const char *zSchema, | 8425 const char *zSchema, |
7988 sqlite3_snapshot *pSnapshot | 8426 sqlite3_snapshot *pSnapshot |
7989 ); | 8427 ); |
7990 | 8428 |
7991 /* | 8429 /* |
7992 ** CAPI3REF: Destroy a snapshot | 8430 ** CAPI3REF: Destroy a snapshot |
7993 ** EXPERIMENTAL | 8431 ** EXPERIMENTAL |
7994 ** | 8432 ** |
7995 ** ^The [sqlite3_snapshot_free(P)] interface destroys [sqlite3_snapshot] P. | 8433 ** ^The [sqlite3_snapshot_free(P)] interface destroys [sqlite3_snapshot] P. |
7996 ** The application must eventually free every [sqlite3_snapshot] object | 8434 ** The application must eventually free every [sqlite3_snapshot] object |
7997 ** using this routine to avoid a memory leak. | 8435 ** using this routine to avoid a memory leak. |
7998 ** | 8436 ** |
7999 ** The [sqlite3_snapshot_free()] interface is only available when the | 8437 ** The [sqlite3_snapshot_free()] interface is only available when the |
8000 ** SQLITE_ENABLE_SNAPSHOT compile-time option is used. | 8438 ** SQLITE_ENABLE_SNAPSHOT compile-time option is used. |
8001 */ | 8439 */ |
8002 SQLITE_API SQLITE_EXPERIMENTAL void SQLITE_STDCALL sqlite3_snapshot_free(sqlite3
_snapshot*); | 8440 SQLITE_API SQLITE_EXPERIMENTAL void sqlite3_snapshot_free(sqlite3_snapshot*); |
| 8441 |
| 8442 /* |
| 8443 ** CAPI3REF: Compare the ages of two snapshot handles. |
| 8444 ** EXPERIMENTAL |
| 8445 ** |
| 8446 ** The sqlite3_snapshot_cmp(P1, P2) interface is used to compare the ages |
| 8447 ** of two valid snapshot handles. |
| 8448 ** |
| 8449 ** If the two snapshot handles are not associated with the same database |
| 8450 ** file, the result of the comparison is undefined. |
| 8451 ** |
| 8452 ** Additionally, the result of the comparison is only valid if both of the |
| 8453 ** snapshot handles were obtained by calling sqlite3_snapshot_get() since the |
| 8454 ** last time the wal file was deleted. The wal file is deleted when the |
| 8455 ** database is changed back to rollback mode or when the number of database |
| 8456 ** clients drops to zero. If either snapshot handle was obtained before the |
| 8457 ** wal file was last deleted, the value returned by this function |
| 8458 ** is undefined. |
| 8459 ** |
| 8460 ** Otherwise, this API returns a negative value if P1 refers to an older |
| 8461 ** snapshot than P2, zero if the two handles refer to the same database |
| 8462 ** snapshot, and a positive value if P1 is a newer snapshot than P2. |
| 8463 */ |
| 8464 SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_cmp( |
| 8465 sqlite3_snapshot *p1, |
| 8466 sqlite3_snapshot *p2 |
| 8467 ); |
| 8468 |
| 8469 /* |
| 8470 ** CAPI3REF: Recover snapshots from a wal file |
| 8471 ** EXPERIMENTAL |
| 8472 ** |
| 8473 ** If all connections disconnect from a database file but do not perform |
| 8474 ** a checkpoint, the existing wal file is opened along with the database |
| 8475 ** file the next time the database is opened. At this point it is only |
| 8476 ** possible to successfully call sqlite3_snapshot_open() to open the most |
| 8477 ** recent snapshot of the database (the one at the head of the wal file), |
| 8478 ** even though the wal file may contain other valid snapshots for which |
| 8479 ** clients have sqlite3_snapshot handles. |
| 8480 ** |
| 8481 ** This function attempts to scan the wal file associated with database zDb |
| 8482 ** of database handle db and make all valid snapshots available to |
| 8483 ** sqlite3_snapshot_open(). It is an error if there is already a read |
| 8484 ** transaction open on the database, or if the database is not a wal mode |
| 8485 ** database. |
| 8486 ** |
| 8487 ** SQLITE_OK is returned if successful, or an SQLite error code otherwise. |
| 8488 */ |
| 8489 SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_recover(sqlite3 *db, const c
har *zDb); |
8003 | 8490 |
8004 /* | 8491 /* |
8005 ** Undo the hack that converts floating point types to integer for | 8492 ** Undo the hack that converts floating point types to integer for |
8006 ** builds on processors without floating point support. | 8493 ** builds on processors without floating point support. |
8007 */ | 8494 */ |
8008 #ifdef SQLITE_OMIT_FLOATING_POINT | 8495 #ifdef SQLITE_OMIT_FLOATING_POINT |
8009 # undef double | 8496 # undef double |
8010 #endif | 8497 #endif |
8011 | 8498 |
8012 #ifdef __cplusplus | 8499 #ifdef __cplusplus |
8013 } /* End of the 'extern "C"' block */ | 8500 } /* End of the 'extern "C"' block */ |
8014 #endif | 8501 #endif |
8015 #endif /* _SQLITE3_H_ */ | 8502 #endif /* SQLITE3_H */ |
8016 | 8503 |
| 8504 /******** Begin file sqlite3rtree.h *********/ |
8017 /* | 8505 /* |
8018 ** 2010 August 30 | 8506 ** 2010 August 30 |
8019 ** | 8507 ** |
8020 ** The author disclaims copyright to this source code. In place of | 8508 ** The author disclaims copyright to this source code. In place of |
8021 ** a legal notice, here is a blessing: | 8509 ** a legal notice, here is a blessing: |
8022 ** | 8510 ** |
8023 ** May you do good and not evil. | 8511 ** May you do good and not evil. |
8024 ** May you find forgiveness for yourself and forgive others. | 8512 ** May you find forgiveness for yourself and forgive others. |
8025 ** May you share freely, never taking more than you give. | 8513 ** May you share freely, never taking more than you give. |
8026 ** | 8514 ** |
(...skipping 19 matching lines...) Expand all Loading... |
8046 #else | 8534 #else |
8047 typedef double sqlite3_rtree_dbl; | 8535 typedef double sqlite3_rtree_dbl; |
8048 #endif | 8536 #endif |
8049 | 8537 |
8050 /* | 8538 /* |
8051 ** Register a geometry callback named zGeom that can be used as part of an | 8539 ** Register a geometry callback named zGeom that can be used as part of an |
8052 ** R-Tree geometry query as follows: | 8540 ** R-Tree geometry query as follows: |
8053 ** | 8541 ** |
8054 ** SELECT ... FROM <rtree> WHERE <rtree col> MATCH $zGeom(... params ...) | 8542 ** SELECT ... FROM <rtree> WHERE <rtree col> MATCH $zGeom(... params ...) |
8055 */ | 8543 */ |
8056 SQLITE_API int SQLITE_STDCALL sqlite3_rtree_geometry_callback( | 8544 SQLITE_API int sqlite3_rtree_geometry_callback( |
8057 sqlite3 *db, | 8545 sqlite3 *db, |
8058 const char *zGeom, | 8546 const char *zGeom, |
8059 int (*xGeom)(sqlite3_rtree_geometry*, int, sqlite3_rtree_dbl*,int*), | 8547 int (*xGeom)(sqlite3_rtree_geometry*, int, sqlite3_rtree_dbl*,int*), |
8060 void *pContext | 8548 void *pContext |
8061 ); | 8549 ); |
8062 | 8550 |
8063 | 8551 |
8064 /* | 8552 /* |
8065 ** A pointer to a structure of the following type is passed as the first | 8553 ** A pointer to a structure of the following type is passed as the first |
8066 ** argument to callbacks registered using rtree_geometry_callback(). | 8554 ** argument to callbacks registered using rtree_geometry_callback(). |
8067 */ | 8555 */ |
8068 struct sqlite3_rtree_geometry { | 8556 struct sqlite3_rtree_geometry { |
8069 void *pContext; /* Copy of pContext passed to s_r_g_c() */ | 8557 void *pContext; /* Copy of pContext passed to s_r_g_c() */ |
8070 int nParam; /* Size of array aParam[] */ | 8558 int nParam; /* Size of array aParam[] */ |
8071 sqlite3_rtree_dbl *aParam; /* Parameters passed to SQL geom function */ | 8559 sqlite3_rtree_dbl *aParam; /* Parameters passed to SQL geom function */ |
8072 void *pUser; /* Callback implementation user data */ | 8560 void *pUser; /* Callback implementation user data */ |
8073 void (*xDelUser)(void *); /* Called by SQLite to clean up pUser */ | 8561 void (*xDelUser)(void *); /* Called by SQLite to clean up pUser */ |
8074 }; | 8562 }; |
8075 | 8563 |
8076 /* | 8564 /* |
8077 ** Register a 2nd-generation geometry callback named zScore that can be | 8565 ** Register a 2nd-generation geometry callback named zScore that can be |
8078 ** used as part of an R-Tree geometry query as follows: | 8566 ** used as part of an R-Tree geometry query as follows: |
8079 ** | 8567 ** |
8080 ** SELECT ... FROM <rtree> WHERE <rtree col> MATCH $zQueryFunc(... params ...) | 8568 ** SELECT ... FROM <rtree> WHERE <rtree col> MATCH $zQueryFunc(... params ...) |
8081 */ | 8569 */ |
8082 SQLITE_API int SQLITE_STDCALL sqlite3_rtree_query_callback( | 8570 SQLITE_API int sqlite3_rtree_query_callback( |
8083 sqlite3 *db, | 8571 sqlite3 *db, |
8084 const char *zQueryFunc, | 8572 const char *zQueryFunc, |
8085 int (*xQueryFunc)(sqlite3_rtree_query_info*), | 8573 int (*xQueryFunc)(sqlite3_rtree_query_info*), |
8086 void *pContext, | 8574 void *pContext, |
8087 void (*xDestructor)(void*) | 8575 void (*xDestructor)(void*) |
8088 ); | 8576 ); |
8089 | 8577 |
8090 | 8578 |
8091 /* | 8579 /* |
8092 ** A pointer to a structure of the following type is passed as the | 8580 ** A pointer to a structure of the following type is passed as the |
(...skipping 31 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
8124 #define PARTLY_WITHIN 1 /* Object partially overlaps query region */ | 8612 #define PARTLY_WITHIN 1 /* Object partially overlaps query region */ |
8125 #define FULLY_WITHIN 2 /* Object fully contained within query region */ | 8613 #define FULLY_WITHIN 2 /* Object fully contained within query region */ |
8126 | 8614 |
8127 | 8615 |
8128 #ifdef __cplusplus | 8616 #ifdef __cplusplus |
8129 } /* end of the 'extern "C"' block */ | 8617 } /* end of the 'extern "C"' block */ |
8130 #endif | 8618 #endif |
8131 | 8619 |
8132 #endif /* ifndef _SQLITE3RTREE_H_ */ | 8620 #endif /* ifndef _SQLITE3RTREE_H_ */ |
8133 | 8621 |
| 8622 /******** End of sqlite3rtree.h *********/ |
| 8623 /******** Begin file sqlite3session.h *********/ |
| 8624 |
| 8625 #if !defined(__SQLITESESSION_H_) && defined(SQLITE_ENABLE_SESSION) |
| 8626 #define __SQLITESESSION_H_ 1 |
| 8627 |
| 8628 /* |
| 8629 ** Make sure we can call this stuff from C++. |
| 8630 */ |
| 8631 #ifdef __cplusplus |
| 8632 extern "C" { |
| 8633 #endif |
| 8634 |
| 8635 |
| 8636 /* |
| 8637 ** CAPI3REF: Session Object Handle |
| 8638 */ |
| 8639 typedef struct sqlite3_session sqlite3_session; |
| 8640 |
| 8641 /* |
| 8642 ** CAPI3REF: Changeset Iterator Handle |
| 8643 */ |
| 8644 typedef struct sqlite3_changeset_iter sqlite3_changeset_iter; |
| 8645 |
| 8646 /* |
| 8647 ** CAPI3REF: Create A New Session Object |
| 8648 ** |
| 8649 ** Create a new session object attached to database handle db. If successful, |
| 8650 ** a pointer to the new object is written to *ppSession and SQLITE_OK is |
| 8651 ** returned. If an error occurs, *ppSession is set to NULL and an SQLite |
| 8652 ** error code (e.g. SQLITE_NOMEM) is returned. |
| 8653 ** |
| 8654 ** It is possible to create multiple session objects attached to a single |
| 8655 ** database handle. |
| 8656 ** |
| 8657 ** Session objects created using this function should be deleted using the |
| 8658 ** [sqlite3session_delete()] function before the database handle that they |
| 8659 ** are attached to is itself closed. If the database handle is closed before |
| 8660 ** the session object is deleted, then the results of calling any session |
| 8661 ** module function, including [sqlite3session_delete()] on the session object |
| 8662 ** are undefined. |
| 8663 ** |
| 8664 ** Because the session module uses the [sqlite3_preupdate_hook()] API, it |
| 8665 ** is not possible for an application to register a pre-update hook on a |
| 8666 ** database handle that has one or more session objects attached. Nor is |
| 8667 ** it possible to create a session object attached to a database handle for |
| 8668 ** which a pre-update hook is already defined. The results of attempting |
| 8669 ** either of these things are undefined. |
| 8670 ** |
| 8671 ** The session object will be used to create changesets for tables in |
| 8672 ** database zDb, where zDb is either "main", or "temp", or the name of an |
| 8673 ** attached database. It is not an error if database zDb is not attached |
| 8674 ** to the database when the session object is created. |
| 8675 */ |
| 8676 SQLITE_API int sqlite3session_create( |
| 8677 sqlite3 *db, /* Database handle */ |
| 8678 const char *zDb, /* Name of db (e.g. "main") */ |
| 8679 sqlite3_session **ppSession /* OUT: New session object */ |
| 8680 ); |
| 8681 |
| 8682 /* |
| 8683 ** CAPI3REF: Delete A Session Object |
| 8684 ** |
| 8685 ** Delete a session object previously allocated using |
| 8686 ** [sqlite3session_create()]. Once a session object has been deleted, the |
| 8687 ** results of attempting to use pSession with any other session module |
| 8688 ** function are undefined. |
| 8689 ** |
| 8690 ** Session objects must be deleted before the database handle to which they |
| 8691 ** are attached is closed. Refer to the documentation for |
| 8692 ** [sqlite3session_create()] for details. |
| 8693 */ |
| 8694 SQLITE_API void sqlite3session_delete(sqlite3_session *pSession); |
| 8695 |
| 8696 |
| 8697 /* |
| 8698 ** CAPI3REF: Enable Or Disable A Session Object |
| 8699 ** |
| 8700 ** Enable or disable the recording of changes by a session object. When |
| 8701 ** enabled, a session object records changes made to the database. When |
| 8702 ** disabled - it does not. A newly created session object is enabled. |
| 8703 ** Refer to the documentation for [sqlite3session_changeset()] for further |
| 8704 ** details regarding how enabling and disabling a session object affects |
| 8705 ** the eventual changesets. |
| 8706 ** |
| 8707 ** Passing zero to this function disables the session. Passing a value |
| 8708 ** greater than zero enables it. Passing a value less than zero is a |
| 8709 ** no-op, and may be used to query the current state of the session. |
| 8710 ** |
| 8711 ** The return value indicates the final state of the session object: 0 if |
| 8712 ** the session is disabled, or 1 if it is enabled. |
| 8713 */ |
| 8714 SQLITE_API int sqlite3session_enable(sqlite3_session *pSession, int bEnable); |
| 8715 |
| 8716 /* |
| 8717 ** CAPI3REF: Set Or Clear the Indirect Change Flag |
| 8718 ** |
| 8719 ** Each change recorded by a session object is marked as either direct or |
| 8720 ** indirect. A change is marked as indirect if either: |
| 8721 ** |
| 8722 ** <ul> |
| 8723 ** <li> The session object "indirect" flag is set when the change is |
| 8724 ** made, or |
| 8725 ** <li> The change is made by an SQL trigger or foreign key action |
| 8726 ** instead of directly as a result of a users SQL statement. |
| 8727 ** </ul> |
| 8728 ** |
| 8729 ** If a single row is affected by more than one operation within a session, |
| 8730 ** then the change is considered indirect if all operations meet the criteria |
| 8731 ** for an indirect change above, or direct otherwise. |
| 8732 ** |
| 8733 ** This function is used to set, clear or query the session object indirect |
| 8734 ** flag. If the second argument passed to this function is zero, then the |
| 8735 ** indirect flag is cleared. If it is greater than zero, the indirect flag |
| 8736 ** is set. Passing a value less than zero does not modify the current value |
| 8737 ** of the indirect flag, and may be used to query the current state of the |
| 8738 ** indirect flag for the specified session object. |
| 8739 ** |
| 8740 ** The return value indicates the final state of the indirect flag: 0 if |
| 8741 ** it is clear, or 1 if it is set. |
| 8742 */ |
| 8743 SQLITE_API int sqlite3session_indirect(sqlite3_session *pSession, int bIndirect)
; |
| 8744 |
| 8745 /* |
| 8746 ** CAPI3REF: Attach A Table To A Session Object |
| 8747 ** |
| 8748 ** If argument zTab is not NULL, then it is the name of a table to attach |
| 8749 ** to the session object passed as the first argument. All subsequent changes |
| 8750 ** made to the table while the session object is enabled will be recorded. See |
| 8751 ** documentation for [sqlite3session_changeset()] for further details. |
| 8752 ** |
| 8753 ** Or, if argument zTab is NULL, then changes are recorded for all tables |
| 8754 ** in the database. If additional tables are added to the database (by |
| 8755 ** executing "CREATE TABLE" statements) after this call is made, changes for |
| 8756 ** the new tables are also recorded. |
| 8757 ** |
| 8758 ** Changes can only be recorded for tables that have a PRIMARY KEY explicitly |
| 8759 ** defined as part of their CREATE TABLE statement. It does not matter if the |
| 8760 ** PRIMARY KEY is an "INTEGER PRIMARY KEY" (rowid alias) or not. The PRIMARY |
| 8761 ** KEY may consist of a single column, or may be a composite key. |
| 8762 ** |
| 8763 ** It is not an error if the named table does not exist in the database. Nor |
| 8764 ** is it an error if the named table does not have a PRIMARY KEY. However, |
| 8765 ** no changes will be recorded in either of these scenarios. |
| 8766 ** |
| 8767 ** Changes are not recorded for individual rows that have NULL values stored |
| 8768 ** in one or more of their PRIMARY KEY columns. |
| 8769 ** |
| 8770 ** SQLITE_OK is returned if the call completes without error. Or, if an error |
| 8771 ** occurs, an SQLite error code (e.g. SQLITE_NOMEM) is returned. |
| 8772 */ |
| 8773 SQLITE_API int sqlite3session_attach( |
| 8774 sqlite3_session *pSession, /* Session object */ |
| 8775 const char *zTab /* Table name */ |
| 8776 ); |
| 8777 |
| 8778 /* |
| 8779 ** CAPI3REF: Set a table filter on a Session Object. |
| 8780 ** |
| 8781 ** The second argument (xFilter) is the "filter callback". For changes to rows |
| 8782 ** in tables that are not attached to the Session object, the filter is called |
| 8783 ** to determine whether changes to the table's rows should be tracked or not. |
| 8784 ** If xFilter returns 0, changes is not tracked. Note that once a table is |
| 8785 ** attached, xFilter will not be called again. |
| 8786 */ |
| 8787 SQLITE_API void sqlite3session_table_filter( |
| 8788 sqlite3_session *pSession, /* Session object */ |
| 8789 int(*xFilter)( |
| 8790 void *pCtx, /* Copy of third arg to _filter_table() */ |
| 8791 const char *zTab /* Table name */ |
| 8792 ), |
| 8793 void *pCtx /* First argument passed to xFilter */ |
| 8794 ); |
| 8795 |
| 8796 /* |
| 8797 ** CAPI3REF: Generate A Changeset From A Session Object |
| 8798 ** |
| 8799 ** Obtain a changeset containing changes to the tables attached to the |
| 8800 ** session object passed as the first argument. If successful, |
| 8801 ** set *ppChangeset to point to a buffer containing the changeset |
| 8802 ** and *pnChangeset to the size of the changeset in bytes before returning |
| 8803 ** SQLITE_OK. If an error occurs, set both *ppChangeset and *pnChangeset to |
| 8804 ** zero and return an SQLite error code. |
| 8805 ** |
| 8806 ** A changeset consists of zero or more INSERT, UPDATE and/or DELETE changes, |
| 8807 ** each representing a change to a single row of an attached table. An INSERT |
| 8808 ** change contains the values of each field of a new database row. A DELETE |
| 8809 ** contains the original values of each field of a deleted database row. An |
| 8810 ** UPDATE change contains the original values of each field of an updated |
| 8811 ** database row along with the updated values for each updated non-primary-key |
| 8812 ** column. It is not possible for an UPDATE change to represent a change that |
| 8813 ** modifies the values of primary key columns. If such a change is made, it |
| 8814 ** is represented in a changeset as a DELETE followed by an INSERT. |
| 8815 ** |
| 8816 ** Changes are not recorded for rows that have NULL values stored in one or |
| 8817 ** more of their PRIMARY KEY columns. If such a row is inserted or deleted, |
| 8818 ** no corresponding change is present in the changesets returned by this |
| 8819 ** function. If an existing row with one or more NULL values stored in |
| 8820 ** PRIMARY KEY columns is updated so that all PRIMARY KEY columns are non-NULL, |
| 8821 ** only an INSERT is appears in the changeset. Similarly, if an existing row |
| 8822 ** with non-NULL PRIMARY KEY values is updated so that one or more of its |
| 8823 ** PRIMARY KEY columns are set to NULL, the resulting changeset contains a |
| 8824 ** DELETE change only. |
| 8825 ** |
| 8826 ** The contents of a changeset may be traversed using an iterator created |
| 8827 ** using the [sqlite3changeset_start()] API. A changeset may be applied to |
| 8828 ** a database with a compatible schema using the [sqlite3changeset_apply()] |
| 8829 ** API. |
| 8830 ** |
| 8831 ** Within a changeset generated by this function, all changes related to a |
| 8832 ** single table are grouped together. In other words, when iterating through |
| 8833 ** a changeset or when applying a changeset to a database, all changes related |
| 8834 ** to a single table are processed before moving on to the next table. Tables |
| 8835 ** are sorted in the same order in which they were attached (or auto-attached) |
| 8836 ** to the sqlite3_session object. The order in which the changes related to |
| 8837 ** a single table are stored is undefined. |
| 8838 ** |
| 8839 ** Following a successful call to this function, it is the responsibility of |
| 8840 ** the caller to eventually free the buffer that *ppChangeset points to using |
| 8841 ** [sqlite3_free()]. |
| 8842 ** |
| 8843 ** <h3>Changeset Generation</h3> |
| 8844 ** |
| 8845 ** Once a table has been attached to a session object, the session object |
| 8846 ** records the primary key values of all new rows inserted into the table. |
| 8847 ** It also records the original primary key and other column values of any |
| 8848 ** deleted or updated rows. For each unique primary key value, data is only |
| 8849 ** recorded once - the first time a row with said primary key is inserted, |
| 8850 ** updated or deleted in the lifetime of the session. |
| 8851 ** |
| 8852 ** There is one exception to the previous paragraph: when a row is inserted, |
| 8853 ** updated or deleted, if one or more of its primary key columns contain a |
| 8854 ** NULL value, no record of the change is made. |
| 8855 ** |
| 8856 ** The session object therefore accumulates two types of records - those |
| 8857 ** that consist of primary key values only (created when the user inserts |
| 8858 ** a new record) and those that consist of the primary key values and the |
| 8859 ** original values of other table columns (created when the users deletes |
| 8860 ** or updates a record). |
| 8861 ** |
| 8862 ** When this function is called, the requested changeset is created using |
| 8863 ** both the accumulated records and the current contents of the database |
| 8864 ** file. Specifically: |
| 8865 ** |
| 8866 ** <ul> |
| 8867 ** <li> For each record generated by an insert, the database is queried |
| 8868 ** for a row with a matching primary key. If one is found, an INSERT |
| 8869 ** change is added to the changeset. If no such row is found, no change |
| 8870 ** is added to the changeset. |
| 8871 ** |
| 8872 ** <li> For each record generated by an update or delete, the database is |
| 8873 ** queried for a row with a matching primary key. If such a row is |
| 8874 ** found and one or more of the non-primary key fields have been |
| 8875 ** modified from their original values, an UPDATE change is added to |
| 8876 ** the changeset. Or, if no such row is found in the table, a DELETE |
| 8877 ** change is added to the changeset. If there is a row with a matching |
| 8878 ** primary key in the database, but all fields contain their original |
| 8879 ** values, no change is added to the changeset. |
| 8880 ** </ul> |
| 8881 ** |
| 8882 ** This means, amongst other things, that if a row is inserted and then later |
| 8883 ** deleted while a session object is active, neither the insert nor the delete |
| 8884 ** will be present in the changeset. Or if a row is deleted and then later a |
| 8885 ** row with the same primary key values inserted while a session object is |
| 8886 ** active, the resulting changeset will contain an UPDATE change instead of |
| 8887 ** a DELETE and an INSERT. |
| 8888 ** |
| 8889 ** When a session object is disabled (see the [sqlite3session_enable()] API), |
| 8890 ** it does not accumulate records when rows are inserted, updated or deleted. |
| 8891 ** This may appear to have some counter-intuitive effects if a single row |
| 8892 ** is written to more than once during a session. For example, if a row |
| 8893 ** is inserted while a session object is enabled, then later deleted while |
| 8894 ** the same session object is disabled, no INSERT record will appear in the |
| 8895 ** changeset, even though the delete took place while the session was disabled. |
| 8896 ** Or, if one field of a row is updated while a session is disabled, and |
| 8897 ** another field of the same row is updated while the session is enabled, the |
| 8898 ** resulting changeset will contain an UPDATE change that updates both fields. |
| 8899 */ |
| 8900 SQLITE_API int sqlite3session_changeset( |
| 8901 sqlite3_session *pSession, /* Session object */ |
| 8902 int *pnChangeset, /* OUT: Size of buffer at *ppChangeset */ |
| 8903 void **ppChangeset /* OUT: Buffer containing changeset */ |
| 8904 ); |
| 8905 |
| 8906 /* |
| 8907 ** CAPI3REF: Load The Difference Between Tables Into A Session |
| 8908 ** |
| 8909 ** If it is not already attached to the session object passed as the first |
| 8910 ** argument, this function attaches table zTbl in the same manner as the |
| 8911 ** [sqlite3session_attach()] function. If zTbl does not exist, or if it |
| 8912 ** does not have a primary key, this function is a no-op (but does not return |
| 8913 ** an error). |
| 8914 ** |
| 8915 ** Argument zFromDb must be the name of a database ("main", "temp" etc.) |
| 8916 ** attached to the same database handle as the session object that contains |
| 8917 ** a table compatible with the table attached to the session by this function. |
| 8918 ** A table is considered compatible if it: |
| 8919 ** |
| 8920 ** <ul> |
| 8921 ** <li> Has the same name, |
| 8922 ** <li> Has the same set of columns declared in the same order, and |
| 8923 ** <li> Has the same PRIMARY KEY definition. |
| 8924 ** </ul> |
| 8925 ** |
| 8926 ** If the tables are not compatible, SQLITE_SCHEMA is returned. If the tables |
| 8927 ** are compatible but do not have any PRIMARY KEY columns, it is not an error |
| 8928 ** but no changes are added to the session object. As with other session |
| 8929 ** APIs, tables without PRIMARY KEYs are simply ignored. |
| 8930 ** |
| 8931 ** This function adds a set of changes to the session object that could be |
| 8932 ** used to update the table in database zFrom (call this the "from-table") |
| 8933 ** so that its content is the same as the table attached to the session |
| 8934 ** object (call this the "to-table"). Specifically: |
| 8935 ** |
| 8936 ** <ul> |
| 8937 ** <li> For each row (primary key) that exists in the to-table but not in |
| 8938 ** the from-table, an INSERT record is added to the session object. |
| 8939 ** |
| 8940 ** <li> For each row (primary key) that exists in the to-table but not in |
| 8941 ** the from-table, a DELETE record is added to the session object. |
| 8942 ** |
| 8943 ** <li> For each row (primary key) that exists in both tables, but features |
| 8944 ** different non-PK values in each, an UPDATE record is added to the |
| 8945 ** session. |
| 8946 ** </ul> |
| 8947 ** |
| 8948 ** To clarify, if this function is called and then a changeset constructed |
| 8949 ** using [sqlite3session_changeset()], then after applying that changeset to |
| 8950 ** database zFrom the contents of the two compatible tables would be |
| 8951 ** identical. |
| 8952 ** |
| 8953 ** It an error if database zFrom does not exist or does not contain the |
| 8954 ** required compatible table. |
| 8955 ** |
| 8956 ** If the operation successful, SQLITE_OK is returned. Otherwise, an SQLite |
| 8957 ** error code. In this case, if argument pzErrMsg is not NULL, *pzErrMsg |
| 8958 ** may be set to point to a buffer containing an English language error |
| 8959 ** message. It is the responsibility of the caller to free this buffer using |
| 8960 ** sqlite3_free(). |
| 8961 */ |
| 8962 SQLITE_API int sqlite3session_diff( |
| 8963 sqlite3_session *pSession, |
| 8964 const char *zFromDb, |
| 8965 const char *zTbl, |
| 8966 char **pzErrMsg |
| 8967 ); |
| 8968 |
| 8969 |
| 8970 /* |
| 8971 ** CAPI3REF: Generate A Patchset From A Session Object |
| 8972 ** |
| 8973 ** The differences between a patchset and a changeset are that: |
| 8974 ** |
| 8975 ** <ul> |
| 8976 ** <li> DELETE records consist of the primary key fields only. The |
| 8977 ** original values of other fields are omitted. |
| 8978 ** <li> The original values of any modified fields are omitted from |
| 8979 ** UPDATE records. |
| 8980 ** </ul> |
| 8981 ** |
| 8982 ** A patchset blob may be used with up to date versions of all |
| 8983 ** sqlite3changeset_xxx API functions except for sqlite3changeset_invert(), |
| 8984 ** which returns SQLITE_CORRUPT if it is passed a patchset. Similarly, |
| 8985 ** attempting to use a patchset blob with old versions of the |
| 8986 ** sqlite3changeset_xxx APIs also provokes an SQLITE_CORRUPT error. |
| 8987 ** |
| 8988 ** Because the non-primary key "old.*" fields are omitted, no |
| 8989 ** SQLITE_CHANGESET_DATA conflicts can be detected or reported if a patchset |
| 8990 ** is passed to the sqlite3changeset_apply() API. Other conflict types work |
| 8991 ** in the same way as for changesets. |
| 8992 ** |
| 8993 ** Changes within a patchset are ordered in the same way as for changesets |
| 8994 ** generated by the sqlite3session_changeset() function (i.e. all changes for |
| 8995 ** a single table are grouped together, tables appear in the order in which |
| 8996 ** they were attached to the session object). |
| 8997 */ |
| 8998 SQLITE_API int sqlite3session_patchset( |
| 8999 sqlite3_session *pSession, /* Session object */ |
| 9000 int *pnPatchset, /* OUT: Size of buffer at *ppChangeset */ |
| 9001 void **ppPatchset /* OUT: Buffer containing changeset */ |
| 9002 ); |
| 9003 |
| 9004 /* |
| 9005 ** CAPI3REF: Test if a changeset has recorded any changes. |
| 9006 ** |
| 9007 ** Return non-zero if no changes to attached tables have been recorded by |
| 9008 ** the session object passed as the first argument. Otherwise, if one or |
| 9009 ** more changes have been recorded, return zero. |
| 9010 ** |
| 9011 ** Even if this function returns zero, it is possible that calling |
| 9012 ** [sqlite3session_changeset()] on the session handle may still return a |
| 9013 ** changeset that contains no changes. This can happen when a row in |
| 9014 ** an attached table is modified and then later on the original values |
| 9015 ** are restored. However, if this function returns non-zero, then it is |
| 9016 ** guaranteed that a call to sqlite3session_changeset() will return a |
| 9017 ** changeset containing zero changes. |
| 9018 */ |
| 9019 SQLITE_API int sqlite3session_isempty(sqlite3_session *pSession); |
| 9020 |
| 9021 /* |
| 9022 ** CAPI3REF: Create An Iterator To Traverse A Changeset |
| 9023 ** |
| 9024 ** Create an iterator used to iterate through the contents of a changeset. |
| 9025 ** If successful, *pp is set to point to the iterator handle and SQLITE_OK |
| 9026 ** is returned. Otherwise, if an error occurs, *pp is set to zero and an |
| 9027 ** SQLite error code is returned. |
| 9028 ** |
| 9029 ** The following functions can be used to advance and query a changeset |
| 9030 ** iterator created by this function: |
| 9031 ** |
| 9032 ** <ul> |
| 9033 ** <li> [sqlite3changeset_next()] |
| 9034 ** <li> [sqlite3changeset_op()] |
| 9035 ** <li> [sqlite3changeset_new()] |
| 9036 ** <li> [sqlite3changeset_old()] |
| 9037 ** </ul> |
| 9038 ** |
| 9039 ** It is the responsibility of the caller to eventually destroy the iterator |
| 9040 ** by passing it to [sqlite3changeset_finalize()]. The buffer containing the |
| 9041 ** changeset (pChangeset) must remain valid until after the iterator is |
| 9042 ** destroyed. |
| 9043 ** |
| 9044 ** Assuming the changeset blob was created by one of the |
| 9045 ** [sqlite3session_changeset()], [sqlite3changeset_concat()] or |
| 9046 ** [sqlite3changeset_invert()] functions, all changes within the changeset |
| 9047 ** that apply to a single table are grouped together. This means that when |
| 9048 ** an application iterates through a changeset using an iterator created by |
| 9049 ** this function, all changes that relate to a single table are visited |
| 9050 ** consecutively. There is no chance that the iterator will visit a change |
| 9051 ** the applies to table X, then one for table Y, and then later on visit |
| 9052 ** another change for table X. |
| 9053 */ |
| 9054 SQLITE_API int sqlite3changeset_start( |
| 9055 sqlite3_changeset_iter **pp, /* OUT: New changeset iterator handle */ |
| 9056 int nChangeset, /* Size of changeset blob in bytes */ |
| 9057 void *pChangeset /* Pointer to blob containing changeset */ |
| 9058 ); |
| 9059 |
| 9060 |
| 9061 /* |
| 9062 ** CAPI3REF: Advance A Changeset Iterator |
| 9063 ** |
| 9064 ** This function may only be used with iterators created by function |
| 9065 ** [sqlite3changeset_start()]. If it is called on an iterator passed to |
| 9066 ** a conflict-handler callback by [sqlite3changeset_apply()], SQLITE_MISUSE |
| 9067 ** is returned and the call has no effect. |
| 9068 ** |
| 9069 ** Immediately after an iterator is created by sqlite3changeset_start(), it |
| 9070 ** does not point to any change in the changeset. Assuming the changeset |
| 9071 ** is not empty, the first call to this function advances the iterator to |
| 9072 ** point to the first change in the changeset. Each subsequent call advances |
| 9073 ** the iterator to point to the next change in the changeset (if any). If |
| 9074 ** no error occurs and the iterator points to a valid change after a call |
| 9075 ** to sqlite3changeset_next() has advanced it, SQLITE_ROW is returned. |
| 9076 ** Otherwise, if all changes in the changeset have already been visited, |
| 9077 ** SQLITE_DONE is returned. |
| 9078 ** |
| 9079 ** If an error occurs, an SQLite error code is returned. Possible error |
| 9080 ** codes include SQLITE_CORRUPT (if the changeset buffer is corrupt) or |
| 9081 ** SQLITE_NOMEM. |
| 9082 */ |
| 9083 SQLITE_API int sqlite3changeset_next(sqlite3_changeset_iter *pIter); |
| 9084 |
| 9085 /* |
| 9086 ** CAPI3REF: Obtain The Current Operation From A Changeset Iterator |
| 9087 ** |
| 9088 ** The pIter argument passed to this function may either be an iterator |
| 9089 ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator |
| 9090 ** created by [sqlite3changeset_start()]. In the latter case, the most recent |
| 9091 ** call to [sqlite3changeset_next()] must have returned [SQLITE_ROW]. If this |
| 9092 ** is not the case, this function returns [SQLITE_MISUSE]. |
| 9093 ** |
| 9094 ** If argument pzTab is not NULL, then *pzTab is set to point to a |
| 9095 ** nul-terminated utf-8 encoded string containing the name of the table |
| 9096 ** affected by the current change. The buffer remains valid until either |
| 9097 ** sqlite3changeset_next() is called on the iterator or until the |
| 9098 ** conflict-handler function returns. If pnCol is not NULL, then *pnCol is |
| 9099 ** set to the number of columns in the table affected by the change. If |
| 9100 ** pbIncorrect is not NULL, then *pbIndirect is set to true (1) if the change |
| 9101 ** is an indirect change, or false (0) otherwise. See the documentation for |
| 9102 ** [sqlite3session_indirect()] for a description of direct and indirect |
| 9103 ** changes. Finally, if pOp is not NULL, then *pOp is set to one of |
| 9104 ** [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE], depending on the |
| 9105 ** type of change that the iterator currently points to. |
| 9106 ** |
| 9107 ** If no error occurs, SQLITE_OK is returned. If an error does occur, an |
| 9108 ** SQLite error code is returned. The values of the output variables may not |
| 9109 ** be trusted in this case. |
| 9110 */ |
| 9111 SQLITE_API int sqlite3changeset_op( |
| 9112 sqlite3_changeset_iter *pIter, /* Iterator object */ |
| 9113 const char **pzTab, /* OUT: Pointer to table name */ |
| 9114 int *pnCol, /* OUT: Number of columns in table */ |
| 9115 int *pOp, /* OUT: SQLITE_INSERT, DELETE or UPDATE */ |
| 9116 int *pbIndirect /* OUT: True for an 'indirect' change */ |
| 9117 ); |
| 9118 |
| 9119 /* |
| 9120 ** CAPI3REF: Obtain The Primary Key Definition Of A Table |
| 9121 ** |
| 9122 ** For each modified table, a changeset includes the following: |
| 9123 ** |
| 9124 ** <ul> |
| 9125 ** <li> The number of columns in the table, and |
| 9126 ** <li> Which of those columns make up the tables PRIMARY KEY. |
| 9127 ** </ul> |
| 9128 ** |
| 9129 ** This function is used to find which columns comprise the PRIMARY KEY of |
| 9130 ** the table modified by the change that iterator pIter currently points to. |
| 9131 ** If successful, *pabPK is set to point to an array of nCol entries, where |
| 9132 ** nCol is the number of columns in the table. Elements of *pabPK are set to |
| 9133 ** 0x01 if the corresponding column is part of the tables primary key, or |
| 9134 ** 0x00 if it is not. |
| 9135 ** |
| 9136 ** If argument pnCol is not NULL, then *pnCol is set to the number of columns |
| 9137 ** in the table. |
| 9138 ** |
| 9139 ** If this function is called when the iterator does not point to a valid |
| 9140 ** entry, SQLITE_MISUSE is returned and the output variables zeroed. Otherwise, |
| 9141 ** SQLITE_OK is returned and the output variables populated as described |
| 9142 ** above. |
| 9143 */ |
| 9144 SQLITE_API int sqlite3changeset_pk( |
| 9145 sqlite3_changeset_iter *pIter, /* Iterator object */ |
| 9146 unsigned char **pabPK, /* OUT: Array of boolean - true for PK cols */ |
| 9147 int *pnCol /* OUT: Number of entries in output array */ |
| 9148 ); |
| 9149 |
| 9150 /* |
| 9151 ** CAPI3REF: Obtain old.* Values From A Changeset Iterator |
| 9152 ** |
| 9153 ** The pIter argument passed to this function may either be an iterator |
| 9154 ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator |
| 9155 ** created by [sqlite3changeset_start()]. In the latter case, the most recent |
| 9156 ** call to [sqlite3changeset_next()] must have returned SQLITE_ROW. |
| 9157 ** Furthermore, it may only be called if the type of change that the iterator |
| 9158 ** currently points to is either [SQLITE_DELETE] or [SQLITE_UPDATE]. Otherwise, |
| 9159 ** this function returns [SQLITE_MISUSE] and sets *ppValue to NULL. |
| 9160 ** |
| 9161 ** Argument iVal must be greater than or equal to 0, and less than the number |
| 9162 ** of columns in the table affected by the current change. Otherwise, |
| 9163 ** [SQLITE_RANGE] is returned and *ppValue is set to NULL. |
| 9164 ** |
| 9165 ** If successful, this function sets *ppValue to point to a protected |
| 9166 ** sqlite3_value object containing the iVal'th value from the vector of |
| 9167 ** original row values stored as part of the UPDATE or DELETE change and |
| 9168 ** returns SQLITE_OK. The name of the function comes from the fact that this |
| 9169 ** is similar to the "old.*" columns available to update or delete triggers. |
| 9170 ** |
| 9171 ** If some other error occurs (e.g. an OOM condition), an SQLite error code |
| 9172 ** is returned and *ppValue is set to NULL. |
| 9173 */ |
| 9174 SQLITE_API int sqlite3changeset_old( |
| 9175 sqlite3_changeset_iter *pIter, /* Changeset iterator */ |
| 9176 int iVal, /* Column number */ |
| 9177 sqlite3_value **ppValue /* OUT: Old value (or NULL pointer) */ |
| 9178 ); |
| 9179 |
| 9180 /* |
| 9181 ** CAPI3REF: Obtain new.* Values From A Changeset Iterator |
| 9182 ** |
| 9183 ** The pIter argument passed to this function may either be an iterator |
| 9184 ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator |
| 9185 ** created by [sqlite3changeset_start()]. In the latter case, the most recent |
| 9186 ** call to [sqlite3changeset_next()] must have returned SQLITE_ROW. |
| 9187 ** Furthermore, it may only be called if the type of change that the iterator |
| 9188 ** currently points to is either [SQLITE_UPDATE] or [SQLITE_INSERT]. Otherwise, |
| 9189 ** this function returns [SQLITE_MISUSE] and sets *ppValue to NULL. |
| 9190 ** |
| 9191 ** Argument iVal must be greater than or equal to 0, and less than the number |
| 9192 ** of columns in the table affected by the current change. Otherwise, |
| 9193 ** [SQLITE_RANGE] is returned and *ppValue is set to NULL. |
| 9194 ** |
| 9195 ** If successful, this function sets *ppValue to point to a protected |
| 9196 ** sqlite3_value object containing the iVal'th value from the vector of |
| 9197 ** new row values stored as part of the UPDATE or INSERT change and |
| 9198 ** returns SQLITE_OK. If the change is an UPDATE and does not include |
| 9199 ** a new value for the requested column, *ppValue is set to NULL and |
| 9200 ** SQLITE_OK returned. The name of the function comes from the fact that |
| 9201 ** this is similar to the "new.*" columns available to update or delete |
| 9202 ** triggers. |
| 9203 ** |
| 9204 ** If some other error occurs (e.g. an OOM condition), an SQLite error code |
| 9205 ** is returned and *ppValue is set to NULL. |
| 9206 */ |
| 9207 SQLITE_API int sqlite3changeset_new( |
| 9208 sqlite3_changeset_iter *pIter, /* Changeset iterator */ |
| 9209 int iVal, /* Column number */ |
| 9210 sqlite3_value **ppValue /* OUT: New value (or NULL pointer) */ |
| 9211 ); |
| 9212 |
| 9213 /* |
| 9214 ** CAPI3REF: Obtain Conflicting Row Values From A Changeset Iterator |
| 9215 ** |
| 9216 ** This function should only be used with iterator objects passed to a |
| 9217 ** conflict-handler callback by [sqlite3changeset_apply()] with either |
| 9218 ** [SQLITE_CHANGESET_DATA] or [SQLITE_CHANGESET_CONFLICT]. If this function |
| 9219 ** is called on any other iterator, [SQLITE_MISUSE] is returned and *ppValue |
| 9220 ** is set to NULL. |
| 9221 ** |
| 9222 ** Argument iVal must be greater than or equal to 0, and less than the number |
| 9223 ** of columns in the table affected by the current change. Otherwise, |
| 9224 ** [SQLITE_RANGE] is returned and *ppValue is set to NULL. |
| 9225 ** |
| 9226 ** If successful, this function sets *ppValue to point to a protected |
| 9227 ** sqlite3_value object containing the iVal'th value from the |
| 9228 ** "conflicting row" associated with the current conflict-handler callback |
| 9229 ** and returns SQLITE_OK. |
| 9230 ** |
| 9231 ** If some other error occurs (e.g. an OOM condition), an SQLite error code |
| 9232 ** is returned and *ppValue is set to NULL. |
| 9233 */ |
| 9234 SQLITE_API int sqlite3changeset_conflict( |
| 9235 sqlite3_changeset_iter *pIter, /* Changeset iterator */ |
| 9236 int iVal, /* Column number */ |
| 9237 sqlite3_value **ppValue /* OUT: Value from conflicting row */ |
| 9238 ); |
| 9239 |
| 9240 /* |
| 9241 ** CAPI3REF: Determine The Number Of Foreign Key Constraint Violations |
| 9242 ** |
| 9243 ** This function may only be called with an iterator passed to an |
| 9244 ** SQLITE_CHANGESET_FOREIGN_KEY conflict handler callback. In this case |
| 9245 ** it sets the output variable to the total number of known foreign key |
| 9246 ** violations in the destination database and returns SQLITE_OK. |
| 9247 ** |
| 9248 ** In all other cases this function returns SQLITE_MISUSE. |
| 9249 */ |
| 9250 SQLITE_API int sqlite3changeset_fk_conflicts( |
| 9251 sqlite3_changeset_iter *pIter, /* Changeset iterator */ |
| 9252 int *pnOut /* OUT: Number of FK violations */ |
| 9253 ); |
| 9254 |
| 9255 |
| 9256 /* |
| 9257 ** CAPI3REF: Finalize A Changeset Iterator |
| 9258 ** |
| 9259 ** This function is used to finalize an iterator allocated with |
| 9260 ** [sqlite3changeset_start()]. |
| 9261 ** |
| 9262 ** This function should only be called on iterators created using the |
| 9263 ** [sqlite3changeset_start()] function. If an application calls this |
| 9264 ** function with an iterator passed to a conflict-handler by |
| 9265 ** [sqlite3changeset_apply()], [SQLITE_MISUSE] is immediately returned and the |
| 9266 ** call has no effect. |
| 9267 ** |
| 9268 ** If an error was encountered within a call to an sqlite3changeset_xxx() |
| 9269 ** function (for example an [SQLITE_CORRUPT] in [sqlite3changeset_next()] or an |
| 9270 ** [SQLITE_NOMEM] in [sqlite3changeset_new()]) then an error code corresponding |
| 9271 ** to that error is returned by this function. Otherwise, SQLITE_OK is |
| 9272 ** returned. This is to allow the following pattern (pseudo-code): |
| 9273 ** |
| 9274 ** sqlite3changeset_start(); |
| 9275 ** while( SQLITE_ROW==sqlite3changeset_next() ){ |
| 9276 ** // Do something with change. |
| 9277 ** } |
| 9278 ** rc = sqlite3changeset_finalize(); |
| 9279 ** if( rc!=SQLITE_OK ){ |
| 9280 ** // An error has occurred |
| 9281 ** } |
| 9282 */ |
| 9283 SQLITE_API int sqlite3changeset_finalize(sqlite3_changeset_iter *pIter); |
| 9284 |
| 9285 /* |
| 9286 ** CAPI3REF: Invert A Changeset |
| 9287 ** |
| 9288 ** This function is used to "invert" a changeset object. Applying an inverted |
| 9289 ** changeset to a database reverses the effects of applying the uninverted |
| 9290 ** changeset. Specifically: |
| 9291 ** |
| 9292 ** <ul> |
| 9293 ** <li> Each DELETE change is changed to an INSERT, and |
| 9294 ** <li> Each INSERT change is changed to a DELETE, and |
| 9295 ** <li> For each UPDATE change, the old.* and new.* values are exchanged. |
| 9296 ** </ul> |
| 9297 ** |
| 9298 ** This function does not change the order in which changes appear within |
| 9299 ** the changeset. It merely reverses the sense of each individual change. |
| 9300 ** |
| 9301 ** If successful, a pointer to a buffer containing the inverted changeset |
| 9302 ** is stored in *ppOut, the size of the same buffer is stored in *pnOut, and |
| 9303 ** SQLITE_OK is returned. If an error occurs, both *pnOut and *ppOut are |
| 9304 ** zeroed and an SQLite error code returned. |
| 9305 ** |
| 9306 ** It is the responsibility of the caller to eventually call sqlite3_free() |
| 9307 ** on the *ppOut pointer to free the buffer allocation following a successful |
| 9308 ** call to this function. |
| 9309 ** |
| 9310 ** WARNING/TODO: This function currently assumes that the input is a valid |
| 9311 ** changeset. If it is not, the results are undefined. |
| 9312 */ |
| 9313 SQLITE_API int sqlite3changeset_invert( |
| 9314 int nIn, const void *pIn, /* Input changeset */ |
| 9315 int *pnOut, void **ppOut /* OUT: Inverse of input */ |
| 9316 ); |
| 9317 |
| 9318 /* |
| 9319 ** CAPI3REF: Concatenate Two Changeset Objects |
| 9320 ** |
| 9321 ** This function is used to concatenate two changesets, A and B, into a |
| 9322 ** single changeset. The result is a changeset equivalent to applying |
| 9323 ** changeset A followed by changeset B. |
| 9324 ** |
| 9325 ** This function combines the two input changesets using an |
| 9326 ** sqlite3_changegroup object. Calling it produces similar results as the |
| 9327 ** following code fragment: |
| 9328 ** |
| 9329 ** sqlite3_changegroup *pGrp; |
| 9330 ** rc = sqlite3_changegroup_new(&pGrp); |
| 9331 ** if( rc==SQLITE_OK ) rc = sqlite3changegroup_add(pGrp, nA, pA); |
| 9332 ** if( rc==SQLITE_OK ) rc = sqlite3changegroup_add(pGrp, nB, pB); |
| 9333 ** if( rc==SQLITE_OK ){ |
| 9334 ** rc = sqlite3changegroup_output(pGrp, pnOut, ppOut); |
| 9335 ** }else{ |
| 9336 ** *ppOut = 0; |
| 9337 ** *pnOut = 0; |
| 9338 ** } |
| 9339 ** |
| 9340 ** Refer to the sqlite3_changegroup documentation below for details. |
| 9341 */ |
| 9342 SQLITE_API int sqlite3changeset_concat( |
| 9343 int nA, /* Number of bytes in buffer pA */ |
| 9344 void *pA, /* Pointer to buffer containing changeset A */ |
| 9345 int nB, /* Number of bytes in buffer pB */ |
| 9346 void *pB, /* Pointer to buffer containing changeset B */ |
| 9347 int *pnOut, /* OUT: Number of bytes in output changeset */ |
| 9348 void **ppOut /* OUT: Buffer containing output changeset */ |
| 9349 ); |
| 9350 |
| 9351 |
| 9352 /* |
| 9353 ** CAPI3REF: Changegroup Handle |
| 9354 */ |
| 9355 typedef struct sqlite3_changegroup sqlite3_changegroup; |
| 9356 |
| 9357 /* |
| 9358 ** CAPI3REF: Create A New Changegroup Object |
| 9359 ** |
| 9360 ** An sqlite3_changegroup object is used to combine two or more changesets |
| 9361 ** (or patchsets) into a single changeset (or patchset). A single changegroup |
| 9362 ** object may combine changesets or patchsets, but not both. The output is |
| 9363 ** always in the same format as the input. |
| 9364 ** |
| 9365 ** If successful, this function returns SQLITE_OK and populates (*pp) with |
| 9366 ** a pointer to a new sqlite3_changegroup object before returning. The caller |
| 9367 ** should eventually free the returned object using a call to |
| 9368 ** sqlite3changegroup_delete(). If an error occurs, an SQLite error code |
| 9369 ** (i.e. SQLITE_NOMEM) is returned and *pp is set to NULL. |
| 9370 ** |
| 9371 ** The usual usage pattern for an sqlite3_changegroup object is as follows: |
| 9372 ** |
| 9373 ** <ul> |
| 9374 ** <li> It is created using a call to sqlite3changegroup_new(). |
| 9375 ** |
| 9376 ** <li> Zero or more changesets (or patchsets) are added to the object |
| 9377 ** by calling sqlite3changegroup_add(). |
| 9378 ** |
| 9379 ** <li> The result of combining all input changesets together is obtained |
| 9380 ** by the application via a call to sqlite3changegroup_output(). |
| 9381 ** |
| 9382 ** <li> The object is deleted using a call to sqlite3changegroup_delete(). |
| 9383 ** </ul> |
| 9384 ** |
| 9385 ** Any number of calls to add() and output() may be made between the calls to |
| 9386 ** new() and delete(), and in any order. |
| 9387 ** |
| 9388 ** As well as the regular sqlite3changegroup_add() and |
| 9389 ** sqlite3changegroup_output() functions, also available are the streaming |
| 9390 ** versions sqlite3changegroup_add_strm() and sqlite3changegroup_output_strm(). |
| 9391 */ |
| 9392 int sqlite3changegroup_new(sqlite3_changegroup **pp); |
| 9393 |
| 9394 /* |
| 9395 ** CAPI3REF: Add A Changeset To A Changegroup |
| 9396 ** |
| 9397 ** Add all changes within the changeset (or patchset) in buffer pData (size |
| 9398 ** nData bytes) to the changegroup. |
| 9399 ** |
| 9400 ** If the buffer contains a patchset, then all prior calls to this function |
| 9401 ** on the same changegroup object must also have specified patchsets. Or, if |
| 9402 ** the buffer contains a changeset, so must have the earlier calls to this |
| 9403 ** function. Otherwise, SQLITE_ERROR is returned and no changes are added |
| 9404 ** to the changegroup. |
| 9405 ** |
| 9406 ** Rows within the changeset and changegroup are identified by the values in |
| 9407 ** their PRIMARY KEY columns. A change in the changeset is considered to |
| 9408 ** apply to the same row as a change already present in the changegroup if |
| 9409 ** the two rows have the same primary key. |
| 9410 ** |
| 9411 ** Changes to rows that do not already appear in the changegroup are |
| 9412 ** simply copied into it. Or, if both the new changeset and the changegroup |
| 9413 ** contain changes that apply to a single row, the final contents of the |
| 9414 ** changegroup depends on the type of each change, as follows: |
| 9415 ** |
| 9416 ** <table border=1 style="margin-left:8ex;margin-right:8ex"> |
| 9417 ** <tr><th style="white-space:pre">Existing Change </th> |
| 9418 ** <th style="white-space:pre">New Change </th> |
| 9419 ** <th>Output Change |
| 9420 ** <tr><td>INSERT <td>INSERT <td> |
| 9421 ** The new change is ignored. This case does not occur if the new |
| 9422 ** changeset was recorded immediately after the changesets already |
| 9423 ** added to the changegroup. |
| 9424 ** <tr><td>INSERT <td>UPDATE <td> |
| 9425 ** The INSERT change remains in the changegroup. The values in the |
| 9426 ** INSERT change are modified as if the row was inserted by the |
| 9427 ** existing change and then updated according to the new change. |
| 9428 ** <tr><td>INSERT <td>DELETE <td> |
| 9429 ** The existing INSERT is removed from the changegroup. The DELETE is |
| 9430 ** not added. |
| 9431 ** <tr><td>UPDATE <td>INSERT <td> |
| 9432 ** The new change is ignored. This case does not occur if the new |
| 9433 ** changeset was recorded immediately after the changesets already |
| 9434 ** added to the changegroup. |
| 9435 ** <tr><td>UPDATE <td>UPDATE <td> |
| 9436 ** The existing UPDATE remains within the changegroup. It is amended |
| 9437 ** so that the accompanying values are as if the row was updated once |
| 9438 ** by the existing change and then again by the new change. |
| 9439 ** <tr><td>UPDATE <td>DELETE <td> |
| 9440 ** The existing UPDATE is replaced by the new DELETE within the |
| 9441 ** changegroup. |
| 9442 ** <tr><td>DELETE <td>INSERT <td> |
| 9443 ** If one or more of the column values in the row inserted by the |
| 9444 ** new change differ from those in the row deleted by the existing |
| 9445 ** change, the existing DELETE is replaced by an UPDATE within the |
| 9446 ** changegroup. Otherwise, if the inserted row is exactly the same |
| 9447 ** as the deleted row, the existing DELETE is simply discarded. |
| 9448 ** <tr><td>DELETE <td>UPDATE <td> |
| 9449 ** The new change is ignored. This case does not occur if the new |
| 9450 ** changeset was recorded immediately after the changesets already |
| 9451 ** added to the changegroup. |
| 9452 ** <tr><td>DELETE <td>DELETE <td> |
| 9453 ** The new change is ignored. This case does not occur if the new |
| 9454 ** changeset was recorded immediately after the changesets already |
| 9455 ** added to the changegroup. |
| 9456 ** </table> |
| 9457 ** |
| 9458 ** If the new changeset contains changes to a table that is already present |
| 9459 ** in the changegroup, then the number of columns and the position of the |
| 9460 ** primary key columns for the table must be consistent. If this is not the |
| 9461 ** case, this function fails with SQLITE_SCHEMA. If the input changeset |
| 9462 ** appears to be corrupt and the corruption is detected, SQLITE_CORRUPT is |
| 9463 ** returned. Or, if an out-of-memory condition occurs during processing, this |
| 9464 ** function returns SQLITE_NOMEM. In all cases, if an error occurs the |
| 9465 ** final contents of the changegroup is undefined. |
| 9466 ** |
| 9467 ** If no error occurs, SQLITE_OK is returned. |
| 9468 */ |
| 9469 int sqlite3changegroup_add(sqlite3_changegroup*, int nData, void *pData); |
| 9470 |
| 9471 /* |
| 9472 ** CAPI3REF: Obtain A Composite Changeset From A Changegroup |
| 9473 ** |
| 9474 ** Obtain a buffer containing a changeset (or patchset) representing the |
| 9475 ** current contents of the changegroup. If the inputs to the changegroup |
| 9476 ** were themselves changesets, the output is a changeset. Or, if the |
| 9477 ** inputs were patchsets, the output is also a patchset. |
| 9478 ** |
| 9479 ** As with the output of the sqlite3session_changeset() and |
| 9480 ** sqlite3session_patchset() functions, all changes related to a single |
| 9481 ** table are grouped together in the output of this function. Tables appear |
| 9482 ** in the same order as for the very first changeset added to the changegroup. |
| 9483 ** If the second or subsequent changesets added to the changegroup contain |
| 9484 ** changes for tables that do not appear in the first changeset, they are |
| 9485 ** appended onto the end of the output changeset, again in the order in |
| 9486 ** which they are first encountered. |
| 9487 ** |
| 9488 ** If an error occurs, an SQLite error code is returned and the output |
| 9489 ** variables (*pnData) and (*ppData) are set to 0. Otherwise, SQLITE_OK |
| 9490 ** is returned and the output variables are set to the size of and a |
| 9491 ** pointer to the output buffer, respectively. In this case it is the |
| 9492 ** responsibility of the caller to eventually free the buffer using a |
| 9493 ** call to sqlite3_free(). |
| 9494 */ |
| 9495 int sqlite3changegroup_output( |
| 9496 sqlite3_changegroup*, |
| 9497 int *pnData, /* OUT: Size of output buffer in bytes */ |
| 9498 void **ppData /* OUT: Pointer to output buffer */ |
| 9499 ); |
| 9500 |
| 9501 /* |
| 9502 ** CAPI3REF: Delete A Changegroup Object |
| 9503 */ |
| 9504 void sqlite3changegroup_delete(sqlite3_changegroup*); |
| 9505 |
| 9506 /* |
| 9507 ** CAPI3REF: Apply A Changeset To A Database |
| 9508 ** |
| 9509 ** Apply a changeset to a database. This function attempts to update the |
| 9510 ** "main" database attached to handle db with the changes found in the |
| 9511 ** changeset passed via the second and third arguments. |
| 9512 ** |
| 9513 ** The fourth argument (xFilter) passed to this function is the "filter |
| 9514 ** callback". If it is not NULL, then for each table affected by at least one |
| 9515 ** change in the changeset, the filter callback is invoked with |
| 9516 ** the table name as the second argument, and a copy of the context pointer |
| 9517 ** passed as the sixth argument to this function as the first. If the "filter |
| 9518 ** callback" returns zero, then no attempt is made to apply any changes to |
| 9519 ** the table. Otherwise, if the return value is non-zero or the xFilter |
| 9520 ** argument to this function is NULL, all changes related to the table are |
| 9521 ** attempted. |
| 9522 ** |
| 9523 ** For each table that is not excluded by the filter callback, this function |
| 9524 ** tests that the target database contains a compatible table. A table is |
| 9525 ** considered compatible if all of the following are true: |
| 9526 ** |
| 9527 ** <ul> |
| 9528 ** <li> The table has the same name as the name recorded in the |
| 9529 ** changeset, and |
| 9530 ** <li> The table has at least as many columns as recorded in the |
| 9531 ** changeset, and |
| 9532 ** <li> The table has primary key columns in the same position as |
| 9533 ** recorded in the changeset. |
| 9534 ** </ul> |
| 9535 ** |
| 9536 ** If there is no compatible table, it is not an error, but none of the |
| 9537 ** changes associated with the table are applied. A warning message is issued |
| 9538 ** via the sqlite3_log() mechanism with the error code SQLITE_SCHEMA. At most |
| 9539 ** one such warning is issued for each table in the changeset. |
| 9540 ** |
| 9541 ** For each change for which there is a compatible table, an attempt is made |
| 9542 ** to modify the table contents according to the UPDATE, INSERT or DELETE |
| 9543 ** change. If a change cannot be applied cleanly, the conflict handler |
| 9544 ** function passed as the fifth argument to sqlite3changeset_apply() may be |
| 9545 ** invoked. A description of exactly when the conflict handler is invoked for |
| 9546 ** each type of change is below. |
| 9547 ** |
| 9548 ** Unlike the xFilter argument, xConflict may not be passed NULL. The results |
| 9549 ** of passing anything other than a valid function pointer as the xConflict |
| 9550 ** argument are undefined. |
| 9551 ** |
| 9552 ** Each time the conflict handler function is invoked, it must return one |
| 9553 ** of [SQLITE_CHANGESET_OMIT], [SQLITE_CHANGESET_ABORT] or |
| 9554 ** [SQLITE_CHANGESET_REPLACE]. SQLITE_CHANGESET_REPLACE may only be returned |
| 9555 ** if the second argument passed to the conflict handler is either |
| 9556 ** SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If the conflict-handler |
| 9557 ** returns an illegal value, any changes already made are rolled back and |
| 9558 ** the call to sqlite3changeset_apply() returns SQLITE_MISUSE. Different |
| 9559 ** actions are taken by sqlite3changeset_apply() depending on the value |
| 9560 ** returned by each invocation of the conflict-handler function. Refer to |
| 9561 ** the documentation for the three |
| 9562 ** [SQLITE_CHANGESET_OMIT|available return values] for details. |
| 9563 ** |
| 9564 ** <dl> |
| 9565 ** <dt>DELETE Changes<dd> |
| 9566 ** For each DELETE change, this function checks if the target database |
| 9567 ** contains a row with the same primary key value (or values) as the |
| 9568 ** original row values stored in the changeset. If it does, and the values |
| 9569 ** stored in all non-primary key columns also match the values stored in |
| 9570 ** the changeset the row is deleted from the target database. |
| 9571 ** |
| 9572 ** If a row with matching primary key values is found, but one or more of |
| 9573 ** the non-primary key fields contains a value different from the original |
| 9574 ** row value stored in the changeset, the conflict-handler function is |
| 9575 ** invoked with [SQLITE_CHANGESET_DATA] as the second argument. If the |
| 9576 ** database table has more columns than are recorded in the changeset, |
| 9577 ** only the values of those non-primary key fields are compared against |
| 9578 ** the current database contents - any trailing database table columns |
| 9579 ** are ignored. |
| 9580 ** |
| 9581 ** If no row with matching primary key values is found in the database, |
| 9582 ** the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND] |
| 9583 ** passed as the second argument. |
| 9584 ** |
| 9585 ** If the DELETE operation is attempted, but SQLite returns SQLITE_CONSTRAINT |
| 9586 ** (which can only happen if a foreign key constraint is violated), the |
| 9587 ** conflict-handler function is invoked with [SQLITE_CHANGESET_CONSTRAINT] |
| 9588 ** passed as the second argument. This includes the case where the DELETE |
| 9589 ** operation is attempted because an earlier call to the conflict handler |
| 9590 ** function returned [SQLITE_CHANGESET_REPLACE]. |
| 9591 ** |
| 9592 ** <dt>INSERT Changes<dd> |
| 9593 ** For each INSERT change, an attempt is made to insert the new row into |
| 9594 ** the database. If the changeset row contains fewer fields than the |
| 9595 ** database table, the trailing fields are populated with their default |
| 9596 ** values. |
| 9597 ** |
| 9598 ** If the attempt to insert the row fails because the database already |
| 9599 ** contains a row with the same primary key values, the conflict handler |
| 9600 ** function is invoked with the second argument set to |
| 9601 ** [SQLITE_CHANGESET_CONFLICT]. |
| 9602 ** |
| 9603 ** If the attempt to insert the row fails because of some other constraint |
| 9604 ** violation (e.g. NOT NULL or UNIQUE), the conflict handler function is |
| 9605 ** invoked with the second argument set to [SQLITE_CHANGESET_CONSTRAINT]. |
| 9606 ** This includes the case where the INSERT operation is re-attempted because |
| 9607 ** an earlier call to the conflict handler function returned |
| 9608 ** [SQLITE_CHANGESET_REPLACE]. |
| 9609 ** |
| 9610 ** <dt>UPDATE Changes<dd> |
| 9611 ** For each UPDATE change, this function checks if the target database |
| 9612 ** contains a row with the same primary key value (or values) as the |
| 9613 ** original row values stored in the changeset. If it does, and the values |
| 9614 ** stored in all modified non-primary key columns also match the values |
| 9615 ** stored in the changeset the row is updated within the target database. |
| 9616 ** |
| 9617 ** If a row with matching primary key values is found, but one or more of |
| 9618 ** the modified non-primary key fields contains a value different from an |
| 9619 ** original row value stored in the changeset, the conflict-handler function |
| 9620 ** is invoked with [SQLITE_CHANGESET_DATA] as the second argument. Since |
| 9621 ** UPDATE changes only contain values for non-primary key fields that are |
| 9622 ** to be modified, only those fields need to match the original values to |
| 9623 ** avoid the SQLITE_CHANGESET_DATA conflict-handler callback. |
| 9624 ** |
| 9625 ** If no row with matching primary key values is found in the database, |
| 9626 ** the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND] |
| 9627 ** passed as the second argument. |
| 9628 ** |
| 9629 ** If the UPDATE operation is attempted, but SQLite returns |
| 9630 ** SQLITE_CONSTRAINT, the conflict-handler function is invoked with |
| 9631 ** [SQLITE_CHANGESET_CONSTRAINT] passed as the second argument. |
| 9632 ** This includes the case where the UPDATE operation is attempted after |
| 9633 ** an earlier call to the conflict handler function returned |
| 9634 ** [SQLITE_CHANGESET_REPLACE]. |
| 9635 ** </dl> |
| 9636 ** |
| 9637 ** It is safe to execute SQL statements, including those that write to the |
| 9638 ** table that the callback related to, from within the xConflict callback. |
| 9639 ** This can be used to further customize the applications conflict |
| 9640 ** resolution strategy. |
| 9641 ** |
| 9642 ** All changes made by this function are enclosed in a savepoint transaction. |
| 9643 ** If any other error (aside from a constraint failure when attempting to |
| 9644 ** write to the target database) occurs, then the savepoint transaction is |
| 9645 ** rolled back, restoring the target database to its original state, and an |
| 9646 ** SQLite error code returned. |
| 9647 */ |
| 9648 SQLITE_API int sqlite3changeset_apply( |
| 9649 sqlite3 *db, /* Apply change to "main" db of this handle */ |
| 9650 int nChangeset, /* Size of changeset in bytes */ |
| 9651 void *pChangeset, /* Changeset blob */ |
| 9652 int(*xFilter)( |
| 9653 void *pCtx, /* Copy of sixth arg to _apply() */ |
| 9654 const char *zTab /* Table name */ |
| 9655 ), |
| 9656 int(*xConflict)( |
| 9657 void *pCtx, /* Copy of sixth arg to _apply() */ |
| 9658 int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */ |
| 9659 sqlite3_changeset_iter *p /* Handle describing change and conflict */ |
| 9660 ), |
| 9661 void *pCtx /* First argument passed to xConflict */ |
| 9662 ); |
| 9663 |
| 9664 /* |
| 9665 ** CAPI3REF: Constants Passed To The Conflict Handler |
| 9666 ** |
| 9667 ** Values that may be passed as the second argument to a conflict-handler. |
| 9668 ** |
| 9669 ** <dl> |
| 9670 ** <dt>SQLITE_CHANGESET_DATA<dd> |
| 9671 ** The conflict handler is invoked with CHANGESET_DATA as the second argument |
| 9672 ** when processing a DELETE or UPDATE change if a row with the required |
| 9673 ** PRIMARY KEY fields is present in the database, but one or more other |
| 9674 ** (non primary-key) fields modified by the update do not contain the |
| 9675 ** expected "before" values. |
| 9676 ** |
| 9677 ** The conflicting row, in this case, is the database row with the matching |
| 9678 ** primary key. |
| 9679 ** |
| 9680 ** <dt>SQLITE_CHANGESET_NOTFOUND<dd> |
| 9681 ** The conflict handler is invoked with CHANGESET_NOTFOUND as the second |
| 9682 ** argument when processing a DELETE or UPDATE change if a row with the |
| 9683 ** required PRIMARY KEY fields is not present in the database. |
| 9684 ** |
| 9685 ** There is no conflicting row in this case. The results of invoking the |
| 9686 ** sqlite3changeset_conflict() API are undefined. |
| 9687 ** |
| 9688 ** <dt>SQLITE_CHANGESET_CONFLICT<dd> |
| 9689 ** CHANGESET_CONFLICT is passed as the second argument to the conflict |
| 9690 ** handler while processing an INSERT change if the operation would result |
| 9691 ** in duplicate primary key values. |
| 9692 ** |
| 9693 ** The conflicting row in this case is the database row with the matching |
| 9694 ** primary key. |
| 9695 ** |
| 9696 ** <dt>SQLITE_CHANGESET_FOREIGN_KEY<dd> |
| 9697 ** If foreign key handling is enabled, and applying a changeset leaves the |
| 9698 ** database in a state containing foreign key violations, the conflict |
| 9699 ** handler is invoked with CHANGESET_FOREIGN_KEY as the second argument |
| 9700 ** exactly once before the changeset is committed. If the conflict handler |
| 9701 ** returns CHANGESET_OMIT, the changes, including those that caused the |
| 9702 ** foreign key constraint violation, are committed. Or, if it returns |
| 9703 ** CHANGESET_ABORT, the changeset is rolled back. |
| 9704 ** |
| 9705 ** No current or conflicting row information is provided. The only function |
| 9706 ** it is possible to call on the supplied sqlite3_changeset_iter handle |
| 9707 ** is sqlite3changeset_fk_conflicts(). |
| 9708 ** |
| 9709 ** <dt>SQLITE_CHANGESET_CONSTRAINT<dd> |
| 9710 ** If any other constraint violation occurs while applying a change (i.e. |
| 9711 ** a UNIQUE, CHECK or NOT NULL constraint), the conflict handler is |
| 9712 ** invoked with CHANGESET_CONSTRAINT as the second argument. |
| 9713 ** |
| 9714 ** There is no conflicting row in this case. The results of invoking the |
| 9715 ** sqlite3changeset_conflict() API are undefined. |
| 9716 ** |
| 9717 ** </dl> |
| 9718 */ |
| 9719 #define SQLITE_CHANGESET_DATA 1 |
| 9720 #define SQLITE_CHANGESET_NOTFOUND 2 |
| 9721 #define SQLITE_CHANGESET_CONFLICT 3 |
| 9722 #define SQLITE_CHANGESET_CONSTRAINT 4 |
| 9723 #define SQLITE_CHANGESET_FOREIGN_KEY 5 |
| 9724 |
| 9725 /* |
| 9726 ** CAPI3REF: Constants Returned By The Conflict Handler |
| 9727 ** |
| 9728 ** A conflict handler callback must return one of the following three values. |
| 9729 ** |
| 9730 ** <dl> |
| 9731 ** <dt>SQLITE_CHANGESET_OMIT<dd> |
| 9732 ** If a conflict handler returns this value no special action is taken. The |
| 9733 ** change that caused the conflict is not applied. The session module |
| 9734 ** continues to the next change in the changeset. |
| 9735 ** |
| 9736 ** <dt>SQLITE_CHANGESET_REPLACE<dd> |
| 9737 ** This value may only be returned if the second argument to the conflict |
| 9738 ** handler was SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If this |
| 9739 ** is not the case, any changes applied so far are rolled back and the |
| 9740 ** call to sqlite3changeset_apply() returns SQLITE_MISUSE. |
| 9741 ** |
| 9742 ** If CHANGESET_REPLACE is returned by an SQLITE_CHANGESET_DATA conflict |
| 9743 ** handler, then the conflicting row is either updated or deleted, depending |
| 9744 ** on the type of change. |
| 9745 ** |
| 9746 ** If CHANGESET_REPLACE is returned by an SQLITE_CHANGESET_CONFLICT conflict |
| 9747 ** handler, then the conflicting row is removed from the database and a |
| 9748 ** second attempt to apply the change is made. If this second attempt fails, |
| 9749 ** the original row is restored to the database before continuing. |
| 9750 ** |
| 9751 ** <dt>SQLITE_CHANGESET_ABORT<dd> |
| 9752 ** If this value is returned, any changes applied so far are rolled back |
| 9753 ** and the call to sqlite3changeset_apply() returns SQLITE_ABORT. |
| 9754 ** </dl> |
| 9755 */ |
| 9756 #define SQLITE_CHANGESET_OMIT 0 |
| 9757 #define SQLITE_CHANGESET_REPLACE 1 |
| 9758 #define SQLITE_CHANGESET_ABORT 2 |
| 9759 |
| 9760 /* |
| 9761 ** CAPI3REF: Streaming Versions of API functions. |
| 9762 ** |
| 9763 ** The six streaming API xxx_strm() functions serve similar purposes to the |
| 9764 ** corresponding non-streaming API functions: |
| 9765 ** |
| 9766 ** <table border=1 style="margin-left:8ex;margin-right:8ex"> |
| 9767 ** <tr><th>Streaming function<th>Non-streaming equivalent</th> |
| 9768 ** <tr><td>sqlite3changeset_apply_str<td>[sqlite3changeset_apply] |
| 9769 ** <tr><td>sqlite3changeset_concat_str<td>[sqlite3changeset_concat] |
| 9770 ** <tr><td>sqlite3changeset_invert_str<td>[sqlite3changeset_invert] |
| 9771 ** <tr><td>sqlite3changeset_start_str<td>[sqlite3changeset_start] |
| 9772 ** <tr><td>sqlite3session_changeset_str<td>[sqlite3session_changeset] |
| 9773 ** <tr><td>sqlite3session_patchset_str<td>[sqlite3session_patchset] |
| 9774 ** </table> |
| 9775 ** |
| 9776 ** Non-streaming functions that accept changesets (or patchsets) as input |
| 9777 ** require that the entire changeset be stored in a single buffer in memory. |
| 9778 ** Similarly, those that return a changeset or patchset do so by returning |
| 9779 ** a pointer to a single large buffer allocated using sqlite3_malloc(). |
| 9780 ** Normally this is convenient. However, if an application running in a |
| 9781 ** low-memory environment is required to handle very large changesets, the |
| 9782 ** large contiguous memory allocations required can become onerous. |
| 9783 ** |
| 9784 ** In order to avoid this problem, instead of a single large buffer, input |
| 9785 ** is passed to a streaming API functions by way of a callback function that |
| 9786 ** the sessions module invokes to incrementally request input data as it is |
| 9787 ** required. In all cases, a pair of API function parameters such as |
| 9788 ** |
| 9789 ** <pre> |
| 9790 ** int nChangeset, |
| 9791 ** void *pChangeset, |
| 9792 ** </pre> |
| 9793 ** |
| 9794 ** Is replaced by: |
| 9795 ** |
| 9796 ** <pre> |
| 9797 ** int (*xInput)(void *pIn, void *pData, int *pnData), |
| 9798 ** void *pIn, |
| 9799 ** </pre> |
| 9800 ** |
| 9801 ** Each time the xInput callback is invoked by the sessions module, the first |
| 9802 ** argument passed is a copy of the supplied pIn context pointer. The second |
| 9803 ** argument, pData, points to a buffer (*pnData) bytes in size. Assuming no |
| 9804 ** error occurs the xInput method should copy up to (*pnData) bytes of data |
| 9805 ** into the buffer and set (*pnData) to the actual number of bytes copied |
| 9806 ** before returning SQLITE_OK. If the input is completely exhausted, (*pnData) |
| 9807 ** should be set to zero to indicate this. Or, if an error occurs, an SQLite |
| 9808 ** error code should be returned. In all cases, if an xInput callback returns |
| 9809 ** an error, all processing is abandoned and the streaming API function |
| 9810 ** returns a copy of the error code to the caller. |
| 9811 ** |
| 9812 ** In the case of sqlite3changeset_start_strm(), the xInput callback may be |
| 9813 ** invoked by the sessions module at any point during the lifetime of the |
| 9814 ** iterator. If such an xInput callback returns an error, the iterator enters |
| 9815 ** an error state, whereby all subsequent calls to iterator functions |
| 9816 ** immediately fail with the same error code as returned by xInput. |
| 9817 ** |
| 9818 ** Similarly, streaming API functions that return changesets (or patchsets) |
| 9819 ** return them in chunks by way of a callback function instead of via a |
| 9820 ** pointer to a single large buffer. In this case, a pair of parameters such |
| 9821 ** as: |
| 9822 ** |
| 9823 ** <pre> |
| 9824 ** int *pnChangeset, |
| 9825 ** void **ppChangeset, |
| 9826 ** </pre> |
| 9827 ** |
| 9828 ** Is replaced by: |
| 9829 ** |
| 9830 ** <pre> |
| 9831 ** int (*xOutput)(void *pOut, const void *pData, int nData), |
| 9832 ** void *pOut |
| 9833 ** </pre> |
| 9834 ** |
| 9835 ** The xOutput callback is invoked zero or more times to return data to |
| 9836 ** the application. The first parameter passed to each call is a copy of the |
| 9837 ** pOut pointer supplied by the application. The second parameter, pData, |
| 9838 ** points to a buffer nData bytes in size containing the chunk of output |
| 9839 ** data being returned. If the xOutput callback successfully processes the |
| 9840 ** supplied data, it should return SQLITE_OK to indicate success. Otherwise, |
| 9841 ** it should return some other SQLite error code. In this case processing |
| 9842 ** is immediately abandoned and the streaming API function returns a copy |
| 9843 ** of the xOutput error code to the application. |
| 9844 ** |
| 9845 ** The sessions module never invokes an xOutput callback with the third |
| 9846 ** parameter set to a value less than or equal to zero. Other than this, |
| 9847 ** no guarantees are made as to the size of the chunks of data returned. |
| 9848 */ |
| 9849 SQLITE_API int sqlite3changeset_apply_strm( |
| 9850 sqlite3 *db, /* Apply change to "main" db of this handle */ |
| 9851 int (*xInput)(void *pIn, void *pData, int *pnData), /* Input function */ |
| 9852 void *pIn, /* First arg for xInput */ |
| 9853 int(*xFilter)( |
| 9854 void *pCtx, /* Copy of sixth arg to _apply() */ |
| 9855 const char *zTab /* Table name */ |
| 9856 ), |
| 9857 int(*xConflict)( |
| 9858 void *pCtx, /* Copy of sixth arg to _apply() */ |
| 9859 int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */ |
| 9860 sqlite3_changeset_iter *p /* Handle describing change and conflict */ |
| 9861 ), |
| 9862 void *pCtx /* First argument passed to xConflict */ |
| 9863 ); |
| 9864 SQLITE_API int sqlite3changeset_concat_strm( |
| 9865 int (*xInputA)(void *pIn, void *pData, int *pnData), |
| 9866 void *pInA, |
| 9867 int (*xInputB)(void *pIn, void *pData, int *pnData), |
| 9868 void *pInB, |
| 9869 int (*xOutput)(void *pOut, const void *pData, int nData), |
| 9870 void *pOut |
| 9871 ); |
| 9872 SQLITE_API int sqlite3changeset_invert_strm( |
| 9873 int (*xInput)(void *pIn, void *pData, int *pnData), |
| 9874 void *pIn, |
| 9875 int (*xOutput)(void *pOut, const void *pData, int nData), |
| 9876 void *pOut |
| 9877 ); |
| 9878 SQLITE_API int sqlite3changeset_start_strm( |
| 9879 sqlite3_changeset_iter **pp, |
| 9880 int (*xInput)(void *pIn, void *pData, int *pnData), |
| 9881 void *pIn |
| 9882 ); |
| 9883 SQLITE_API int sqlite3session_changeset_strm( |
| 9884 sqlite3_session *pSession, |
| 9885 int (*xOutput)(void *pOut, const void *pData, int nData), |
| 9886 void *pOut |
| 9887 ); |
| 9888 SQLITE_API int sqlite3session_patchset_strm( |
| 9889 sqlite3_session *pSession, |
| 9890 int (*xOutput)(void *pOut, const void *pData, int nData), |
| 9891 void *pOut |
| 9892 ); |
| 9893 int sqlite3changegroup_add_strm(sqlite3_changegroup*, |
| 9894 int (*xInput)(void *pIn, void *pData, int *pnData), |
| 9895 void *pIn |
| 9896 ); |
| 9897 int sqlite3changegroup_output_strm(sqlite3_changegroup*, |
| 9898 int (*xOutput)(void *pOut, const void *pData, int nData), |
| 9899 void *pOut |
| 9900 ); |
| 9901 |
| 9902 |
| 9903 /* |
| 9904 ** Make sure we can call this stuff from C++. |
| 9905 */ |
| 9906 #ifdef __cplusplus |
| 9907 } |
| 9908 #endif |
| 9909 |
| 9910 #endif /* !defined(__SQLITESESSION_H_) && defined(SQLITE_ENABLE_SESSION) */ |
| 9911 |
| 9912 /******** End of sqlite3session.h *********/ |
| 9913 /******** Begin file fts5.h *********/ |
8134 /* | 9914 /* |
8135 ** 2014 May 31 | 9915 ** 2014 May 31 |
8136 ** | 9916 ** |
8137 ** The author disclaims copyright to this source code. In place of | 9917 ** The author disclaims copyright to this source code. In place of |
8138 ** a legal notice, here is a blessing: | 9918 ** a legal notice, here is a blessing: |
8139 ** | 9919 ** |
8140 ** May you do good and not evil. | 9920 ** May you do good and not evil. |
8141 ** May you find forgiveness for yourself and forgive others. | 9921 ** May you find forgiveness for yourself and forgive others. |
8142 ** May you share freely, never taking more than you give. | 9922 ** May you share freely, never taking more than you give. |
8143 ** | 9923 ** |
(...skipping 65 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
8209 ** If parameter iCol is less than zero, set output variable *pnToken | 9989 ** If parameter iCol is less than zero, set output variable *pnToken |
8210 ** to the total number of tokens in the current row. Or, if iCol is | 9990 ** to the total number of tokens in the current row. Or, if iCol is |
8211 ** non-negative but less than the number of columns in the table, set | 9991 ** non-negative but less than the number of columns in the table, set |
8212 ** *pnToken to the number of tokens in column iCol of the current row. | 9992 ** *pnToken to the number of tokens in column iCol of the current row. |
8213 ** | 9993 ** |
8214 ** If parameter iCol is greater than or equal to the number of columns | 9994 ** If parameter iCol is greater than or equal to the number of columns |
8215 ** in the table, SQLITE_RANGE is returned. Or, if an error occurs (e.g. | 9995 ** in the table, SQLITE_RANGE is returned. Or, if an error occurs (e.g. |
8216 ** an OOM condition or IO error), an appropriate SQLite error code is | 9996 ** an OOM condition or IO error), an appropriate SQLite error code is |
8217 ** returned. | 9997 ** returned. |
8218 ** | 9998 ** |
| 9999 ** This function may be quite inefficient if used with an FTS5 table |
| 10000 ** created with the "columnsize=0" option. |
| 10001 ** |
8219 ** xColumnText: | 10002 ** xColumnText: |
8220 ** This function attempts to retrieve the text of column iCol of the | 10003 ** This function attempts to retrieve the text of column iCol of the |
8221 ** current document. If successful, (*pz) is set to point to a buffer | 10004 ** current document. If successful, (*pz) is set to point to a buffer |
8222 ** containing the text in utf-8 encoding, (*pn) is set to the size in bytes | 10005 ** containing the text in utf-8 encoding, (*pn) is set to the size in bytes |
8223 ** (not characters) of the buffer and SQLITE_OK is returned. Otherwise, | 10006 ** (not characters) of the buffer and SQLITE_OK is returned. Otherwise, |
8224 ** if an error occurs, an SQLite error code is returned and the final values | 10007 ** if an error occurs, an SQLite error code is returned and the final values |
8225 ** of (*pz) and (*pn) are undefined. | 10008 ** of (*pz) and (*pn) are undefined. |
8226 ** | 10009 ** |
8227 ** xPhraseCount: | 10010 ** xPhraseCount: |
8228 ** Returns the number of phrases in the current query expression. | 10011 ** Returns the number of phrases in the current query expression. |
8229 ** | 10012 ** |
8230 ** xPhraseSize: | 10013 ** xPhraseSize: |
8231 ** Returns the number of tokens in phrase iPhrase of the query. Phrases | 10014 ** Returns the number of tokens in phrase iPhrase of the query. Phrases |
8232 ** are numbered starting from zero. | 10015 ** are numbered starting from zero. |
8233 ** | 10016 ** |
8234 ** xInstCount: | 10017 ** xInstCount: |
8235 ** Set *pnInst to the total number of occurrences of all phrases within | 10018 ** Set *pnInst to the total number of occurrences of all phrases within |
8236 ** the query within the current row. Return SQLITE_OK if successful, or | 10019 ** the query within the current row. Return SQLITE_OK if successful, or |
8237 ** an error code (i.e. SQLITE_NOMEM) if an error occurs. | 10020 ** an error code (i.e. SQLITE_NOMEM) if an error occurs. |
8238 ** | 10021 ** |
| 10022 ** This API can be quite slow if used with an FTS5 table created with the |
| 10023 ** "detail=none" or "detail=column" option. If the FTS5 table is created |
| 10024 ** with either "detail=none" or "detail=column" and "content=" option |
| 10025 ** (i.e. if it is a contentless table), then this API always returns 0. |
| 10026 ** |
8239 ** xInst: | 10027 ** xInst: |
8240 ** Query for the details of phrase match iIdx within the current row. | 10028 ** Query for the details of phrase match iIdx within the current row. |
8241 ** Phrase matches are numbered starting from zero, so the iIdx argument | 10029 ** Phrase matches are numbered starting from zero, so the iIdx argument |
8242 ** should be greater than or equal to zero and smaller than the value | 10030 ** should be greater than or equal to zero and smaller than the value |
8243 ** output by xInstCount(). | 10031 ** output by xInstCount(). |
8244 ** | 10032 ** |
| 10033 ** Usually, output parameter *piPhrase is set to the phrase number, *piCol |
| 10034 ** to the column in which it occurs and *piOff the token offset of the |
| 10035 ** first token of the phrase. The exception is if the table was created |
| 10036 ** with the offsets=0 option specified. In this case *piOff is always |
| 10037 ** set to -1. |
| 10038 ** |
8245 ** Returns SQLITE_OK if successful, or an error code (i.e. SQLITE_NOMEM) | 10039 ** Returns SQLITE_OK if successful, or an error code (i.e. SQLITE_NOMEM) |
8246 ** if an error occurs. | 10040 ** if an error occurs. |
8247 ** | 10041 ** |
| 10042 ** This API can be quite slow if used with an FTS5 table created with the |
| 10043 ** "detail=none" or "detail=column" option. |
| 10044 ** |
8248 ** xRowid: | 10045 ** xRowid: |
8249 ** Returns the rowid of the current row. | 10046 ** Returns the rowid of the current row. |
8250 ** | 10047 ** |
8251 ** xTokenize: | 10048 ** xTokenize: |
8252 ** Tokenize text using the tokenizer belonging to the FTS5 table. | 10049 ** Tokenize text using the tokenizer belonging to the FTS5 table. |
8253 ** | 10050 ** |
8254 ** xQueryPhrase(pFts5, iPhrase, pUserData, xCallback): | 10051 ** xQueryPhrase(pFts5, iPhrase, pUserData, xCallback): |
8255 ** This API function is used to query the FTS table for phrase iPhrase | 10052 ** This API function is used to query the FTS table for phrase iPhrase |
8256 ** of the current query. Specifically, a query equivalent to: | 10053 ** of the current query. Specifically, a query equivalent to: |
8257 ** | 10054 ** |
8258 ** ... FROM ftstable WHERE ftstable MATCH $p ORDER BY rowid | 10055 ** ... FROM ftstable WHERE ftstable MATCH $p ORDER BY rowid |
8259 ** | 10056 ** |
8260 ** with $p set to a phrase equivalent to the phrase iPhrase of the | 10057 ** with $p set to a phrase equivalent to the phrase iPhrase of the |
8261 ** current query is executed. For each row visited, the callback function | 10058 ** current query is executed. Any column filter that applies to |
8262 ** passed as the fourth argument is invoked. The context and API objects | 10059 ** phrase iPhrase of the current query is included in $p. For each |
8263 ** passed to the callback function may be used to access the properties of | 10060 ** row visited, the callback function passed as the fourth argument |
8264 ** each matched row. Invoking Api.xUserData() returns a copy of the pointer | 10061 ** is invoked. The context and API objects passed to the callback |
8265 ** passed as the third argument to pUserData. | 10062 ** function may be used to access the properties of each matched row. |
| 10063 ** Invoking Api.xUserData() returns a copy of the pointer passed as |
| 10064 ** the third argument to pUserData. |
8266 ** | 10065 ** |
8267 ** If the callback function returns any value other than SQLITE_OK, the | 10066 ** If the callback function returns any value other than SQLITE_OK, the |
8268 ** query is abandoned and the xQueryPhrase function returns immediately. | 10067 ** query is abandoned and the xQueryPhrase function returns immediately. |
8269 ** If the returned value is SQLITE_DONE, xQueryPhrase returns SQLITE_OK. | 10068 ** If the returned value is SQLITE_DONE, xQueryPhrase returns SQLITE_OK. |
8270 ** Otherwise, the error code is propagated upwards. | 10069 ** Otherwise, the error code is propagated upwards. |
8271 ** | 10070 ** |
8272 ** If the query runs to completion without incident, SQLITE_OK is returned. | 10071 ** If the query runs to completion without incident, SQLITE_OK is returned. |
8273 ** Or, if some error occurs before the query completes or is aborted by | 10072 ** Or, if some error occurs before the query completes or is aborted by |
8274 ** the callback, an SQLite error code is returned. | 10073 ** the callback, an SQLite error code is returned. |
8275 ** | 10074 ** |
(...skipping 45 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
8321 ** This function is used, along with type Fts5PhraseIter and the xPhraseNext | 10120 ** This function is used, along with type Fts5PhraseIter and the xPhraseNext |
8322 ** method, to iterate through all instances of a single query phrase within | 10121 ** method, to iterate through all instances of a single query phrase within |
8323 ** the current row. This is the same information as is accessible via the | 10122 ** the current row. This is the same information as is accessible via the |
8324 ** xInstCount/xInst APIs. While the xInstCount/xInst APIs are more convenient | 10123 ** xInstCount/xInst APIs. While the xInstCount/xInst APIs are more convenient |
8325 ** to use, this API may be faster under some circumstances. To iterate | 10124 ** to use, this API may be faster under some circumstances. To iterate |
8326 ** through instances of phrase iPhrase, use the following code: | 10125 ** through instances of phrase iPhrase, use the following code: |
8327 ** | 10126 ** |
8328 ** Fts5PhraseIter iter; | 10127 ** Fts5PhraseIter iter; |
8329 ** int iCol, iOff; | 10128 ** int iCol, iOff; |
8330 ** for(pApi->xPhraseFirst(pFts, iPhrase, &iter, &iCol, &iOff); | 10129 ** for(pApi->xPhraseFirst(pFts, iPhrase, &iter, &iCol, &iOff); |
8331 ** iOff>=0; | 10130 ** iCol>=0; |
8332 ** pApi->xPhraseNext(pFts, &iter, &iCol, &iOff) | 10131 ** pApi->xPhraseNext(pFts, &iter, &iCol, &iOff) |
8333 ** ){ | 10132 ** ){ |
8334 ** // An instance of phrase iPhrase at offset iOff of column iCol | 10133 ** // An instance of phrase iPhrase at offset iOff of column iCol |
8335 ** } | 10134 ** } |
8336 ** | 10135 ** |
8337 ** The Fts5PhraseIter structure is defined above. Applications should not | 10136 ** The Fts5PhraseIter structure is defined above. Applications should not |
8338 ** modify this structure directly - it should only be used as shown above | 10137 ** modify this structure directly - it should only be used as shown above |
8339 ** with the xPhraseFirst() and xPhraseNext() API methods. | 10138 ** with the xPhraseFirst() and xPhraseNext() API methods (and by |
| 10139 ** xPhraseFirstColumn() and xPhraseNextColumn() as illustrated below). |
| 10140 ** |
| 10141 ** This API can be quite slow if used with an FTS5 table created with the |
| 10142 ** "detail=none" or "detail=column" option. If the FTS5 table is created |
| 10143 ** with either "detail=none" or "detail=column" and "content=" option |
| 10144 ** (i.e. if it is a contentless table), then this API always iterates |
| 10145 ** through an empty set (all calls to xPhraseFirst() set iCol to -1). |
8340 ** | 10146 ** |
8341 ** xPhraseNext() | 10147 ** xPhraseNext() |
8342 ** See xPhraseFirst above. | 10148 ** See xPhraseFirst above. |
| 10149 ** |
| 10150 ** xPhraseFirstColumn() |
| 10151 ** This function and xPhraseNextColumn() are similar to the xPhraseFirst() |
| 10152 ** and xPhraseNext() APIs described above. The difference is that instead |
| 10153 ** of iterating through all instances of a phrase in the current row, these |
| 10154 ** APIs are used to iterate through the set of columns in the current row |
| 10155 ** that contain one or more instances of a specified phrase. For example: |
| 10156 ** |
| 10157 ** Fts5PhraseIter iter; |
| 10158 ** int iCol; |
| 10159 ** for(pApi->xPhraseFirstColumn(pFts, iPhrase, &iter, &iCol); |
| 10160 ** iCol>=0; |
| 10161 ** pApi->xPhraseNextColumn(pFts, &iter, &iCol) |
| 10162 ** ){ |
| 10163 ** // Column iCol contains at least one instance of phrase iPhrase |
| 10164 ** } |
| 10165 ** |
| 10166 ** This API can be quite slow if used with an FTS5 table created with the |
| 10167 ** "detail=none" option. If the FTS5 table is created with either |
| 10168 ** "detail=none" "content=" option (i.e. if it is a contentless table), |
| 10169 ** then this API always iterates through an empty set (all calls to |
| 10170 ** xPhraseFirstColumn() set iCol to -1). |
| 10171 ** |
| 10172 ** The information accessed using this API and its companion |
| 10173 ** xPhraseFirstColumn() may also be obtained using xPhraseFirst/xPhraseNext |
| 10174 ** (or xInst/xInstCount). The chief advantage of this API is that it is |
| 10175 ** significantly more efficient than those alternatives when used with |
| 10176 ** "detail=column" tables. |
| 10177 ** |
| 10178 ** xPhraseNextColumn() |
| 10179 ** See xPhraseFirstColumn above. |
8343 */ | 10180 */ |
8344 struct Fts5ExtensionApi { | 10181 struct Fts5ExtensionApi { |
8345 int iVersion; /* Currently always set to 1 */ | 10182 int iVersion; /* Currently always set to 3 */ |
8346 | 10183 |
8347 void *(*xUserData)(Fts5Context*); | 10184 void *(*xUserData)(Fts5Context*); |
8348 | 10185 |
8349 int (*xColumnCount)(Fts5Context*); | 10186 int (*xColumnCount)(Fts5Context*); |
8350 int (*xRowCount)(Fts5Context*, sqlite3_int64 *pnRow); | 10187 int (*xRowCount)(Fts5Context*, sqlite3_int64 *pnRow); |
8351 int (*xColumnTotalSize)(Fts5Context*, int iCol, sqlite3_int64 *pnToken); | 10188 int (*xColumnTotalSize)(Fts5Context*, int iCol, sqlite3_int64 *pnToken); |
8352 | 10189 |
8353 int (*xTokenize)(Fts5Context*, | 10190 int (*xTokenize)(Fts5Context*, |
8354 const char *pText, int nText, /* Text to tokenize */ | 10191 const char *pText, int nText, /* Text to tokenize */ |
8355 void *pCtx, /* Context passed to xToken() */ | 10192 void *pCtx, /* Context passed to xToken() */ |
8356 int (*xToken)(void*, int, const char*, int, int, int) /* Callback */ | 10193 int (*xToken)(void*, int, const char*, int, int, int) /* Callback */ |
8357 ); | 10194 ); |
8358 | 10195 |
8359 int (*xPhraseCount)(Fts5Context*); | 10196 int (*xPhraseCount)(Fts5Context*); |
8360 int (*xPhraseSize)(Fts5Context*, int iPhrase); | 10197 int (*xPhraseSize)(Fts5Context*, int iPhrase); |
8361 | 10198 |
8362 int (*xInstCount)(Fts5Context*, int *pnInst); | 10199 int (*xInstCount)(Fts5Context*, int *pnInst); |
8363 int (*xInst)(Fts5Context*, int iIdx, int *piPhrase, int *piCol, int *piOff); | 10200 int (*xInst)(Fts5Context*, int iIdx, int *piPhrase, int *piCol, int *piOff); |
8364 | 10201 |
8365 sqlite3_int64 (*xRowid)(Fts5Context*); | 10202 sqlite3_int64 (*xRowid)(Fts5Context*); |
8366 int (*xColumnText)(Fts5Context*, int iCol, const char **pz, int *pn); | 10203 int (*xColumnText)(Fts5Context*, int iCol, const char **pz, int *pn); |
8367 int (*xColumnSize)(Fts5Context*, int iCol, int *pnToken); | 10204 int (*xColumnSize)(Fts5Context*, int iCol, int *pnToken); |
8368 | 10205 |
8369 int (*xQueryPhrase)(Fts5Context*, int iPhrase, void *pUserData, | 10206 int (*xQueryPhrase)(Fts5Context*, int iPhrase, void *pUserData, |
8370 int(*)(const Fts5ExtensionApi*,Fts5Context*,void*) | 10207 int(*)(const Fts5ExtensionApi*,Fts5Context*,void*) |
8371 ); | 10208 ); |
8372 int (*xSetAuxdata)(Fts5Context*, void *pAux, void(*xDelete)(void*)); | 10209 int (*xSetAuxdata)(Fts5Context*, void *pAux, void(*xDelete)(void*)); |
8373 void *(*xGetAuxdata)(Fts5Context*, int bClear); | 10210 void *(*xGetAuxdata)(Fts5Context*, int bClear); |
8374 | 10211 |
8375 void (*xPhraseFirst)(Fts5Context*, int iPhrase, Fts5PhraseIter*, int*, int*); | 10212 int (*xPhraseFirst)(Fts5Context*, int iPhrase, Fts5PhraseIter*, int*, int*); |
8376 void (*xPhraseNext)(Fts5Context*, Fts5PhraseIter*, int *piCol, int *piOff); | 10213 void (*xPhraseNext)(Fts5Context*, Fts5PhraseIter*, int *piCol, int *piOff); |
| 10214 |
| 10215 int (*xPhraseFirstColumn)(Fts5Context*, int iPhrase, Fts5PhraseIter*, int*); |
| 10216 void (*xPhraseNextColumn)(Fts5Context*, Fts5PhraseIter*, int *piCol); |
8377 }; | 10217 }; |
8378 | 10218 |
8379 /* | 10219 /* |
8380 ** CUSTOM AUXILIARY FUNCTIONS | 10220 ** CUSTOM AUXILIARY FUNCTIONS |
8381 *************************************************************************/ | 10221 *************************************************************************/ |
8382 | 10222 |
8383 /************************************************************************* | 10223 /************************************************************************* |
8384 ** CUSTOM TOKENIZERS | 10224 ** CUSTOM TOKENIZERS |
8385 ** | 10225 ** |
8386 ** Applications may also register custom tokenizer types. A tokenizer | 10226 ** Applications may also register custom tokenizer types. A tokenizer |
8387 ** is registered by providing fts5 with a populated instance of the | 10227 ** is registered by providing fts5 with a populated instance of the |
8388 ** following structure. All structure methods must be defined, setting | 10228 ** following structure. All structure methods must be defined, setting |
8389 ** any member of the fts5_tokenizer struct to NULL leads to undefined | 10229 ** any member of the fts5_tokenizer struct to NULL leads to undefined |
8390 ** behaviour. The structure methods are expected to function as follows: | 10230 ** behaviour. The structure methods are expected to function as follows: |
8391 ** | 10231 ** |
8392 ** xCreate: | 10232 ** xCreate: |
8393 ** This function is used to allocate and inititalize a tokenizer instance. | 10233 ** This function is used to allocate and initialize a tokenizer instance. |
8394 ** A tokenizer instance is required to actually tokenize text. | 10234 ** A tokenizer instance is required to actually tokenize text. |
8395 ** | 10235 ** |
8396 ** The first argument passed to this function is a copy of the (void*) | 10236 ** The first argument passed to this function is a copy of the (void*) |
8397 ** pointer provided by the application when the fts5_tokenizer object | 10237 ** pointer provided by the application when the fts5_tokenizer object |
8398 ** was registered with FTS5 (the third argument to xCreateTokenizer()). | 10238 ** was registered with FTS5 (the third argument to xCreateTokenizer()). |
8399 ** The second and third arguments are an array of nul-terminated strings | 10239 ** The second and third arguments are an array of nul-terminated strings |
8400 ** containing the tokenizer arguments, if any, specified following the | 10240 ** containing the tokenizer arguments, if any, specified following the |
8401 ** tokenizer name as part of the CREATE VIRTUAL TABLE statement used | 10241 ** tokenizer name as part of the CREATE VIRTUAL TABLE statement used |
8402 ** to create the FTS5 table. | 10242 ** to create the FTS5 table. |
8403 ** | 10243 ** |
(...skipping 239 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
8643 /* | 10483 /* |
8644 ** END OF REGISTRATION API | 10484 ** END OF REGISTRATION API |
8645 *************************************************************************/ | 10485 *************************************************************************/ |
8646 | 10486 |
8647 #ifdef __cplusplus | 10487 #ifdef __cplusplus |
8648 } /* end of the 'extern "C"' block */ | 10488 } /* end of the 'extern "C"' block */ |
8649 #endif | 10489 #endif |
8650 | 10490 |
8651 #endif /* _FTS5_H */ | 10491 #endif /* _FTS5_H */ |
8652 | 10492 |
8653 | 10493 /******** End of fts5.h *********/ |
OLD | NEW |