diff options
author | dan miller | 2007-10-20 05:34:26 +0000 |
---|---|---|
committer | dan miller | 2007-10-20 05:34:26 +0000 |
commit | 354ea97baf765759911f0c56d3ed511350ebe348 (patch) | |
tree | 1adf96a98045d24b8741ba02bf21d195e70993ca /libraries/sqlite/win32/sqlite3.h | |
parent | sqlite source (unix build) added to libraries (diff) | |
download | opensim-SC_OLD-354ea97baf765759911f0c56d3ed511350ebe348.zip opensim-SC_OLD-354ea97baf765759911f0c56d3ed511350ebe348.tar.gz opensim-SC_OLD-354ea97baf765759911f0c56d3ed511350ebe348.tar.bz2 opensim-SC_OLD-354ea97baf765759911f0c56d3ed511350ebe348.tar.xz |
sqlite 3.5.1 windows source
Diffstat (limited to '')
-rwxr-xr-x | libraries/sqlite/win32/sqlite3.h | 3552 |
1 files changed, 3552 insertions, 0 deletions
diff --git a/libraries/sqlite/win32/sqlite3.h b/libraries/sqlite/win32/sqlite3.h new file mode 100755 index 0000000..562ae80 --- /dev/null +++ b/libraries/sqlite/win32/sqlite3.h | |||
@@ -0,0 +1,3552 @@ | |||
1 | /* | ||
2 | ** 2001 September 15 | ||
3 | ** | ||
4 | ** The author disclaims copyright to this source code. In place of | ||
5 | ** a legal notice, here is a blessing: | ||
6 | ** | ||
7 | ** May you do good and not evil. | ||
8 | ** May you find forgiveness for yourself and forgive others. | ||
9 | ** May you share freely, never taking more than you give. | ||
10 | ** | ||
11 | ************************************************************************* | ||
12 | ** This header file defines the interface that the SQLite library | ||
13 | ** presents to client programs. If a C-function, structure, datatype, | ||
14 | ** or constant definition does not appear in this file, then it is | ||
15 | ** not a published API of SQLite, is subject to change without | ||
16 | ** notice, and should not be referenced by programs that use SQLite. | ||
17 | ** | ||
18 | ** Some of the definitions that are in this file are marked as | ||
19 | ** "experimental". Experimental interfaces are normally new | ||
20 | ** features recently added to SQLite. We do not anticipate changes | ||
21 | ** to experimental interfaces but reserve to make minor changes if | ||
22 | ** experience from use "in the wild" suggest such changes are prudent. | ||
23 | ** | ||
24 | ** The official C-language API documentation for SQLite is derived | ||
25 | ** from comments in this file. This file is the authoritative source | ||
26 | ** on how SQLite interfaces are suppose to operate. | ||
27 | ** | ||
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 | ||
30 | ** the version number) and changes its name to "sqlite3.h" as | ||
31 | ** part of the build process. | ||
32 | ** | ||
33 | ** @(#) $Id: sqlite.h.in,v 1.266 2007/10/03 20:15:28 drh Exp $ | ||
34 | */ | ||
35 | #ifndef _SQLITE3_H_ | ||
36 | #define _SQLITE3_H_ | ||
37 | #include <stdarg.h> /* Needed for the definition of va_list */ | ||
38 | |||
39 | /* | ||
40 | ** Make sure we can call this stuff from C++. | ||
41 | */ | ||
42 | #ifdef __cplusplus | ||
43 | extern "C" { | ||
44 | #endif | ||
45 | |||
46 | |||
47 | /* | ||
48 | ** Add the ability to override 'extern' | ||
49 | */ | ||
50 | #ifndef SQLITE_EXTERN | ||
51 | # define SQLITE_EXTERN extern | ||
52 | #endif | ||
53 | |||
54 | /* | ||
55 | ** Make sure these symbols where not defined by some previous header | ||
56 | ** file. | ||
57 | */ | ||
58 | #ifdef SQLITE_VERSION | ||
59 | # undef SQLITE_VERSION | ||
60 | #endif | ||
61 | #ifdef SQLITE_VERSION_NUMBER | ||
62 | # undef SQLITE_VERSION_NUMBER | ||
63 | #endif | ||
64 | |||
65 | /* | ||
66 | ** CAPI3REF: Compile-Time Library Version Numbers | ||
67 | ** | ||
68 | ** The version of the SQLite library is contained in the sqlite3.h | ||
69 | ** header file in a #define named SQLITE_VERSION. The SQLITE_VERSION | ||
70 | ** macro resolves to a string constant. | ||
71 | ** | ||
72 | ** The format of the version string is "X.Y.Z", where | ||
73 | ** X is the major version number, Y is the minor version number and Z | ||
74 | ** is the release number. The X.Y.Z might be followed by "alpha" or "beta". | ||
75 | ** For example "3.1.1beta". | ||
76 | ** | ||
77 | ** The X value is always 3 in SQLite. The X value only changes when | ||
78 | ** backwards compatibility is broken and we intend to never break | ||
79 | ** backwards compatibility. The Y value only changes when | ||
80 | ** there are major feature enhancements that are forwards compatible | ||
81 | ** but not backwards compatible. The Z value is incremented with | ||
82 | ** each release but resets back to 0 when Y is incremented. | ||
83 | ** | ||
84 | ** The SQLITE_VERSION_NUMBER is an integer with the value | ||
85 | ** (X*1000000 + Y*1000 + Z). For example, for version "3.1.1beta", | ||
86 | ** SQLITE_VERSION_NUMBER is set to 3001001. To detect if they are using | ||
87 | ** version 3.1.1 or greater at compile time, programs may use the test | ||
88 | ** (SQLITE_VERSION_NUMBER>=3001001). | ||
89 | ** | ||
90 | ** See also: [sqlite3_libversion()] and [sqlite3_libversion_number()]. | ||
91 | */ | ||
92 | #define SQLITE_VERSION "3.5.1" | ||
93 | #define SQLITE_VERSION_NUMBER 3005001 | ||
94 | |||
95 | /* | ||
96 | ** CAPI3REF: Run-Time Library Version Numbers | ||
97 | ** | ||
98 | ** These routines return values equivalent to the header constants | ||
99 | ** [SQLITE_VERSION] and [SQLITE_VERSION_NUMBER]. The values returned | ||
100 | ** by this routines should only be different from the header values | ||
101 | ** if you compile your program using an sqlite3.h header from a | ||
102 | ** different version of SQLite that the version of the library you | ||
103 | ** link against. | ||
104 | ** | ||
105 | ** The sqlite3_version[] string constant contains the text of the | ||
106 | ** [SQLITE_VERSION] string. The sqlite3_libversion() function returns | ||
107 | ** a poiner to the sqlite3_version[] string constant. The function | ||
108 | ** is provided for DLL users who can only access functions and not | ||
109 | ** constants within the DLL. | ||
110 | */ | ||
111 | SQLITE_EXTERN const char sqlite3_version[]; | ||
112 | const char *sqlite3_libversion(void); | ||
113 | int sqlite3_libversion_number(void); | ||
114 | |||
115 | /* | ||
116 | ** CAPI3REF: Test To See If The Library Is Threadsafe | ||
117 | ** | ||
118 | ** This routine returns TRUE (nonzero) if SQLite was compiled with | ||
119 | ** all of its mutexes enabled and is thus threadsafe. It returns | ||
120 | ** zero if the particular build is for single-threaded operation | ||
121 | ** only. | ||
122 | ** | ||
123 | ** Really all this routine does is return true if SQLite was compiled | ||
124 | ** with the -DSQLITE_THREADSAFE=1 option and false if | ||
125 | ** compiled with -DSQLITE_THREADSAFE=0. If SQLite uses an | ||
126 | ** application-defined mutex subsystem, malloc subsystem, collating | ||
127 | ** sequence, VFS, SQL function, progress callback, commit hook, | ||
128 | ** extension, or other accessories and these add-ons are not | ||
129 | ** threadsafe, then clearly the combination will not be threadsafe | ||
130 | ** either. Hence, this routine never reports that the library | ||
131 | ** is guaranteed to be threadsafe, only when it is guaranteed not | ||
132 | ** to be. | ||
133 | ** | ||
134 | ** This is an experimental API and may go away or change in future | ||
135 | ** releases. | ||
136 | */ | ||
137 | int sqlite3_threadsafe(void); | ||
138 | |||
139 | /* | ||
140 | ** CAPI3REF: Database Connection Handle | ||
141 | ** | ||
142 | ** Each open SQLite database is represented by pointer to an instance of the | ||
143 | ** opaque structure named "sqlite3". It is useful to think of an sqlite3 | ||
144 | ** pointer as an object. The [sqlite3_open()], [sqlite3_open16()], and | ||
145 | ** [sqlite3_open_v2()] interfaces are its constructors | ||
146 | ** and [sqlite3_close()] is its destructor. There are many other interfaces | ||
147 | ** (such as [sqlite3_prepare_v2()], [sqlite3_create_function()], and | ||
148 | ** [sqlite3_busy_timeout()] to name but three) that are methods on this | ||
149 | ** object. | ||
150 | */ | ||
151 | typedef struct sqlite3 sqlite3; | ||
152 | |||
153 | |||
154 | /* | ||
155 | ** CAPI3REF: 64-Bit Integer Types | ||
156 | ** | ||
157 | ** Some compilers do not support the "long long" datatype. So we have | ||
158 | ** to do compiler-specific typedefs for 64-bit signed and unsigned integers. | ||
159 | ** | ||
160 | ** Many SQLite interface functions require a 64-bit integer arguments. | ||
161 | ** Those interfaces are declared using this typedef. | ||
162 | */ | ||
163 | #ifdef SQLITE_INT64_TYPE | ||
164 | typedef SQLITE_INT64_TYPE sqlite_int64; | ||
165 | typedef unsigned SQLITE_INT64_TYPE sqlite_uint64; | ||
166 | #elif defined(_MSC_VER) || defined(__BORLANDC__) | ||
167 | typedef __int64 sqlite_int64; | ||
168 | typedef unsigned __int64 sqlite_uint64; | ||
169 | #else | ||
170 | typedef long long int sqlite_int64; | ||
171 | typedef unsigned long long int sqlite_uint64; | ||
172 | #endif | ||
173 | typedef sqlite_int64 sqlite3_int64; | ||
174 | typedef sqlite_uint64 sqlite3_uint64; | ||
175 | |||
176 | /* | ||
177 | ** If compiling for a processor that lacks floating point support, | ||
178 | ** substitute integer for floating-point | ||
179 | */ | ||
180 | #ifdef SQLITE_OMIT_FLOATING_POINT | ||
181 | # define double sqlite3_int64 | ||
182 | #endif | ||
183 | |||
184 | /* | ||
185 | ** CAPI3REF: Closing A Database Connection | ||
186 | ** | ||
187 | ** Call this function with a pointer to a structure that was previously | ||
188 | ** returned from [sqlite3_open()], [sqlite3_open16()], or | ||
189 | ** [sqlite3_open_v2()] and the corresponding database will by | ||
190 | ** closed. | ||
191 | ** | ||
192 | ** All SQL statements prepared using [sqlite3_prepare_v2()] or | ||
193 | ** [sqlite3_prepare16_v2()] must be destroyed using [sqlite3_finalize()] | ||
194 | ** before this routine is called. Otherwise, SQLITE_BUSY is returned and the | ||
195 | ** database connection remains open. | ||
196 | ** | ||
197 | ** Passing this routine a database connection that has already been | ||
198 | ** closed results in undefined behavior. If other interfaces that | ||
199 | ** reference the same database connection are pending (either in the | ||
200 | ** same thread or in different threads) when this routine is called, | ||
201 | ** then the behavior is undefined and is almost certainly undesirable. | ||
202 | */ | ||
203 | int sqlite3_close(sqlite3 *); | ||
204 | |||
205 | /* | ||
206 | ** The type for a callback function. | ||
207 | ** This is legacy and deprecated. It is included for historical | ||
208 | ** compatibility and is not documented. | ||
209 | */ | ||
210 | typedef int (*sqlite3_callback)(void*,int,char**, char**); | ||
211 | |||
212 | /* | ||
213 | ** CAPI3REF: One-Step Query Execution Interface | ||
214 | ** | ||
215 | ** This interface is used to do a one-time evaluatation of zero | ||
216 | ** or more SQL statements. UTF-8 text of the SQL statements to | ||
217 | ** be evaluted is passed in as the second parameter. The statements | ||
218 | ** are prepared one by one using [sqlite3_prepare()], evaluated | ||
219 | ** using [sqlite3_step()], then destroyed using [sqlite3_finalize()]. | ||
220 | ** | ||
221 | ** If one or more of the SQL statements are queries, then | ||
222 | ** the callback function specified by the 3rd parameter is | ||
223 | ** invoked once for each row of the query result. This callback | ||
224 | ** should normally return 0. If the callback returns a non-zero | ||
225 | ** value then the query is aborted, all subsequent SQL statements | ||
226 | ** are skipped and the sqlite3_exec() function returns the [SQLITE_ABORT]. | ||
227 | ** | ||
228 | ** The 4th parameter to this interface is an arbitrary pointer that is | ||
229 | ** passed through to the callback function as its first parameter. | ||
230 | ** | ||
231 | ** The 2nd parameter to the callback function is the number of | ||
232 | ** columns in the query result. The 3rd parameter to the callback | ||
233 | ** is an array of strings holding the values for each column | ||
234 | ** as extracted using [sqlite3_column_text()]. | ||
235 | ** The 4th parameter to the callback is an array of strings | ||
236 | ** obtained using [sqlite3_column_name()] and holding | ||
237 | ** the names of each column. | ||
238 | ** | ||
239 | ** The callback function may be NULL, even for queries. A NULL | ||
240 | ** callback is not an error. It just means that no callback | ||
241 | ** will be invoked. | ||
242 | ** | ||
243 | ** If an error occurs while parsing or evaluating the SQL (but | ||
244 | ** not while executing the callback) then an appropriate error | ||
245 | ** message is written into memory obtained from [sqlite3_malloc()] and | ||
246 | ** *errmsg is made to point to that message. The calling function | ||
247 | ** is responsible for freeing the memory using [sqlite3_free()]. | ||
248 | ** If errmsg==NULL, then no error message is ever written. | ||
249 | ** | ||
250 | ** The return value is is SQLITE_OK if there are no errors and | ||
251 | ** some other [SQLITE_OK | return code] if there is an error. | ||
252 | ** The particular return value depends on the type of error. | ||
253 | ** | ||
254 | */ | ||
255 | int sqlite3_exec( | ||
256 | sqlite3*, /* An open database */ | ||
257 | const char *sql, /* SQL to be evaluted */ | ||
258 | int (*callback)(void*,int,char**,char**), /* Callback function */ | ||
259 | void *, /* 1st argument to callback */ | ||
260 | char **errmsg /* Error msg written here */ | ||
261 | ); | ||
262 | |||
263 | /* | ||
264 | ** CAPI3REF: Result Codes | ||
265 | ** KEYWORDS: SQLITE_OK | ||
266 | ** | ||
267 | ** Many SQLite functions return an integer result code from the set shown | ||
268 | ** above in order to indicates success or failure. | ||
269 | ** | ||
270 | ** The result codes above are the only ones returned by SQLite in its | ||
271 | ** default configuration. However, the [sqlite3_extended_result_codes()] | ||
272 | ** API can be used to set a database connectoin to return more detailed | ||
273 | ** result codes. | ||
274 | ** | ||
275 | ** See also: [SQLITE_IOERR_READ | extended result codes] | ||
276 | ** | ||
277 | */ | ||
278 | #define SQLITE_OK 0 /* Successful result */ | ||
279 | /* beginning-of-error-codes */ | ||
280 | #define SQLITE_ERROR 1 /* SQL error or missing database */ | ||
281 | #define SQLITE_INTERNAL 2 /* NOT USED. Internal logic error in SQLite */ | ||
282 | #define SQLITE_PERM 3 /* Access permission denied */ | ||
283 | #define SQLITE_ABORT 4 /* Callback routine requested an abort */ | ||
284 | #define SQLITE_BUSY 5 /* The database file is locked */ | ||
285 | #define SQLITE_LOCKED 6 /* A table in the database is locked */ | ||
286 | #define SQLITE_NOMEM 7 /* A malloc() failed */ | ||
287 | #define SQLITE_READONLY 8 /* Attempt to write a readonly database */ | ||
288 | #define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite3_interrupt()*/ | ||
289 | #define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */ | ||
290 | #define SQLITE_CORRUPT 11 /* The database disk image is malformed */ | ||
291 | #define SQLITE_NOTFOUND 12 /* NOT USED. Table or record not found */ | ||
292 | #define SQLITE_FULL 13 /* Insertion failed because database is full */ | ||
293 | #define SQLITE_CANTOPEN 14 /* Unable to open the database file */ | ||
294 | #define SQLITE_PROTOCOL 15 /* NOT USED. Database lock protocol error */ | ||
295 | #define SQLITE_EMPTY 16 /* Database is empty */ | ||
296 | #define SQLITE_SCHEMA 17 /* The database schema changed */ | ||
297 | #define SQLITE_TOOBIG 18 /* String or BLOB exceeds size limit */ | ||
298 | #define SQLITE_CONSTRAINT 19 /* Abort due to constraint violation */ | ||
299 | #define SQLITE_MISMATCH 20 /* Data type mismatch */ | ||
300 | #define SQLITE_MISUSE 21 /* Library used incorrectly */ | ||
301 | #define SQLITE_NOLFS 22 /* Uses OS features not supported on host */ | ||
302 | #define SQLITE_AUTH 23 /* Authorization denied */ | ||
303 | #define SQLITE_FORMAT 24 /* Auxiliary database format error */ | ||
304 | #define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */ | ||
305 | #define SQLITE_NOTADB 26 /* File opened that is not a database file */ | ||
306 | #define SQLITE_ROW 100 /* sqlite3_step() has another row ready */ | ||
307 | #define SQLITE_DONE 101 /* sqlite3_step() has finished executing */ | ||
308 | /* end-of-error-codes */ | ||
309 | |||
310 | /* | ||
311 | ** CAPI3REF: Extended Result Codes | ||
312 | ** | ||
313 | ** In its default configuration, SQLite API routines return one of 26 integer | ||
314 | ** result codes described at result-codes. However, experience has shown that | ||
315 | ** many of these result codes are too course-grained. They do not provide as | ||
316 | ** much information about problems as users might like. In an effort to | ||
317 | ** address this, newer versions of SQLite (version 3.3.8 and later) include | ||
318 | ** support for additional result codes that provide more detailed information | ||
319 | ** about errors. The extended result codes are enabled (or disabled) for | ||
320 | ** each database | ||
321 | ** connection using the [sqlite3_extended_result_codes()] API. | ||
322 | ** | ||
323 | ** Some of the available extended result codes are listed above. | ||
324 | ** We expect the number of extended result codes will be expand | ||
325 | ** over time. Software that uses extended result codes should expect | ||
326 | ** to see new result codes in future releases of SQLite. | ||
327 | ** | ||
328 | ** The symbolic name for an extended result code always contains a related | ||
329 | ** primary result code as a prefix. Primary result codes contain a single | ||
330 | ** "_" character. Extended result codes contain two or more "_" characters. | ||
331 | ** The numeric value of an extended result code can be converted to its | ||
332 | ** corresponding primary result code by masking off the lower 8 bytes. | ||
333 | ** | ||
334 | ** The SQLITE_OK result code will never be extended. It will always | ||
335 | ** be exactly zero. | ||
336 | */ | ||
337 | #define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8)) | ||
338 | #define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8)) | ||
339 | #define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8)) | ||
340 | #define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4<<8)) | ||
341 | #define SQLITE_IOERR_DIR_FSYNC (SQLITE_IOERR | (5<<8)) | ||
342 | #define SQLITE_IOERR_TRUNCATE (SQLITE_IOERR | (6<<8)) | ||
343 | #define SQLITE_IOERR_FSTAT (SQLITE_IOERR | (7<<8)) | ||
344 | #define SQLITE_IOERR_UNLOCK (SQLITE_IOERR | (8<<8)) | ||
345 | #define SQLITE_IOERR_RDLOCK (SQLITE_IOERR | (9<<8)) | ||
346 | #define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8)) | ||
347 | #define SQLITE_IOERR_BLOCKED (SQLITE_IOERR | (11<<8)) | ||
348 | #define SQLITE_IOERR_NOMEM (SQLITE_IOERR | (12<<8)) | ||
349 | |||
350 | /* | ||
351 | ** CAPI3REF: Flags For File Open Operations | ||
352 | ** | ||
353 | ** Combination of the following bit values are used as the | ||
354 | ** third argument to the [sqlite3_open_v2()] interface and | ||
355 | ** as fourth argument to the xOpen method of the | ||
356 | ** [sqlite3_vfs] object. | ||
357 | ** | ||
358 | */ | ||
359 | #define SQLITE_OPEN_READONLY 0x00000001 | ||
360 | #define SQLITE_OPEN_READWRITE 0x00000002 | ||
361 | #define SQLITE_OPEN_CREATE 0x00000004 | ||
362 | #define SQLITE_OPEN_DELETEONCLOSE 0x00000008 | ||
363 | #define SQLITE_OPEN_EXCLUSIVE 0x00000010 | ||
364 | #define SQLITE_OPEN_MAIN_DB 0x00000100 | ||
365 | #define SQLITE_OPEN_TEMP_DB 0x00000200 | ||
366 | #define SQLITE_OPEN_TRANSIENT_DB 0x00000400 | ||
367 | #define SQLITE_OPEN_MAIN_JOURNAL 0x00000800 | ||
368 | #define SQLITE_OPEN_TEMP_JOURNAL 0x00001000 | ||
369 | #define SQLITE_OPEN_SUBJOURNAL 0x00002000 | ||
370 | #define SQLITE_OPEN_MASTER_JOURNAL 0x00004000 | ||
371 | |||
372 | /* | ||
373 | ** CAPI3REF: Device Characteristics | ||
374 | ** | ||
375 | ** The xDeviceCapabilities method of the [sqlite3_io_methods] | ||
376 | ** object returns an integer which is a vector of the following | ||
377 | ** bit values expressing I/O characteristics of the mass storage | ||
378 | ** device that holds the file that the [sqlite3_io_methods] | ||
379 | ** refers to. | ||
380 | ** | ||
381 | ** The SQLITE_IOCAP_ATOMIC property means that all writes of | ||
382 | ** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values | ||
383 | ** mean that writes of blocks that are nnn bytes in size and | ||
384 | ** are aligned to an address which is an integer multiple of | ||
385 | ** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means | ||
386 | ** that when data is appended to a file, the data is appended | ||
387 | ** first then the size of the file is extended, never the other | ||
388 | ** way around. The SQLITE_IOCAP_SEQUENTIAL property means that | ||
389 | ** information is written to disk in the same order as calls | ||
390 | ** to xWrite(). | ||
391 | */ | ||
392 | #define SQLITE_IOCAP_ATOMIC 0x00000001 | ||
393 | #define SQLITE_IOCAP_ATOMIC512 0x00000002 | ||
394 | #define SQLITE_IOCAP_ATOMIC1K 0x00000004 | ||
395 | #define SQLITE_IOCAP_ATOMIC2K 0x00000008 | ||
396 | #define SQLITE_IOCAP_ATOMIC4K 0x00000010 | ||
397 | #define SQLITE_IOCAP_ATOMIC8K 0x00000020 | ||
398 | #define SQLITE_IOCAP_ATOMIC16K 0x00000040 | ||
399 | #define SQLITE_IOCAP_ATOMIC32K 0x00000080 | ||
400 | #define SQLITE_IOCAP_ATOMIC64K 0x00000100 | ||
401 | #define SQLITE_IOCAP_SAFE_APPEND 0x00000200 | ||
402 | #define SQLITE_IOCAP_SEQUENTIAL 0x00000400 | ||
403 | |||
404 | /* | ||
405 | ** CAPI3REF: File Locking Levels | ||
406 | ** | ||
407 | ** SQLite uses one of the following integer values as the second | ||
408 | ** argument to calls it makes to the xLock() and xUnlock() methods | ||
409 | ** of an [sqlite3_io_methods] object. | ||
410 | */ | ||
411 | #define SQLITE_LOCK_NONE 0 | ||
412 | #define SQLITE_LOCK_SHARED 1 | ||
413 | #define SQLITE_LOCK_RESERVED 2 | ||
414 | #define SQLITE_LOCK_PENDING 3 | ||
415 | #define SQLITE_LOCK_EXCLUSIVE 4 | ||
416 | |||
417 | /* | ||
418 | ** CAPI3REF: Synchronization Type Flags | ||
419 | ** | ||
420 | ** When SQLite invokes the xSync() method of an [sqlite3_io_methods] | ||
421 | ** object it uses a combination of the following integer values as | ||
422 | ** the second argument. | ||
423 | ** | ||
424 | ** When the SQLITE_SYNC_DATAONLY flag is used, it means that the | ||
425 | ** sync operation only needs to flush data to mass storage. Inode | ||
426 | ** information need not be flushed. The SQLITE_SYNC_NORMAL means | ||
427 | ** to use normal fsync() semantics. The SQLITE_SYNC_FULL flag means | ||
428 | ** to use Mac OS-X style fullsync instead of fsync(). | ||
429 | */ | ||
430 | #define SQLITE_SYNC_NORMAL 0x00002 | ||
431 | #define SQLITE_SYNC_FULL 0x00003 | ||
432 | #define SQLITE_SYNC_DATAONLY 0x00010 | ||
433 | |||
434 | |||
435 | /* | ||
436 | ** CAPI3REF: OS Interface Open File Handle | ||
437 | ** | ||
438 | ** An [sqlite3_file] object represents an open file in the OS | ||
439 | ** interface layer. Individual OS interface implementations will | ||
440 | ** want to subclass this object by appending additional fields | ||
441 | ** for their own use. The pMethods entry is a pointer to an | ||
442 | ** [sqlite3_io_methods] object that defines methods for performing | ||
443 | ** I/O operations on the open file. | ||
444 | */ | ||
445 | typedef struct sqlite3_file sqlite3_file; | ||
446 | struct sqlite3_file { | ||
447 | const struct sqlite3_io_methods *pMethods; /* Methods for an open file */ | ||
448 | }; | ||
449 | |||
450 | /* | ||
451 | ** CAPI3REF: OS Interface File Virtual Methods Object | ||
452 | ** | ||
453 | ** Every file opened by the [sqlite3_vfs] xOpen method contains a pointer to | ||
454 | ** an instance of the this object. This object defines the | ||
455 | ** methods used to perform various operations against the open file. | ||
456 | ** | ||
457 | ** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or | ||
458 | ** [SQLITE_SYNC_FULL]. The first choice is the normal fsync(). | ||
459 | * The second choice is an | ||
460 | ** OS-X style fullsync. The SQLITE_SYNC_DATA flag may be ORed in to | ||
461 | ** indicate that only the data of the file and not its inode needs to be | ||
462 | ** synced. | ||
463 | ** | ||
464 | ** The integer values to xLock() and xUnlock() are one of | ||
465 | ** <ul> | ||
466 | ** <li> [SQLITE_LOCK_NONE], | ||
467 | ** <li> [SQLITE_LOCK_SHARED], | ||
468 | ** <li> [SQLITE_LOCK_RESERVED], | ||
469 | ** <li> [SQLITE_LOCK_PENDING], or | ||
470 | ** <li> [SQLITE_LOCK_EXCLUSIVE]. | ||
471 | ** </ul> | ||
472 | ** xLock() increases the lock. xUnlock() decreases the lock. | ||
473 | ** The xCheckReservedLock() method looks | ||
474 | ** to see if any database connection, either in this | ||
475 | ** process or in some other process, is holding an RESERVED, | ||
476 | ** PENDING, or EXCLUSIVE lock on the file. It returns true | ||
477 | ** if such a lock exists and false if not. | ||
478 | ** | ||
479 | ** The xFileControl() method is a generic interface that allows custom | ||
480 | ** VFS implementations to directly control an open file using the | ||
481 | ** [sqlite3_file_control()] interface. The second "op" argument | ||
482 | ** is an integer opcode. The third | ||
483 | ** argument is a generic pointer which is intended to be a pointer | ||
484 | ** to a structure that may contain arguments or space in which to | ||
485 | ** write return values. Potential uses for xFileControl() might be | ||
486 | ** functions to enable blocking locks with timeouts, to change the | ||
487 | ** locking strategy (for example to use dot-file locks), to inquire | ||
488 | ** about the status of a lock, or to break stale locks. The SQLite | ||
489 | ** core reserves opcodes less than 100 for its own use. | ||
490 | ** A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available. | ||
491 | ** Applications that define a custom xFileControl method should use opcodes | ||
492 | ** greater than 100 to avoid conflicts. | ||
493 | ** | ||
494 | ** The xSectorSize() method returns the sector size of the | ||
495 | ** device that underlies the file. The sector size is the | ||
496 | ** minimum write that can be performed without disturbing | ||
497 | ** other bytes in the file. The xDeviceCharacteristics() | ||
498 | ** method returns a bit vector describing behaviors of the | ||
499 | ** underlying device: | ||
500 | ** | ||
501 | ** <ul> | ||
502 | ** <li> [SQLITE_IOCAP_ATOMIC] | ||
503 | ** <li> [SQLITE_IOCAP_ATOMIC512] | ||
504 | ** <li> [SQLITE_IOCAP_ATOMIC1K] | ||
505 | ** <li> [SQLITE_IOCAP_ATOMIC2K] | ||
506 | ** <li> [SQLITE_IOCAP_ATOMIC4K] | ||
507 | ** <li> [SQLITE_IOCAP_ATOMIC8K] | ||
508 | ** <li> [SQLITE_IOCAP_ATOMIC16K] | ||
509 | ** <li> [SQLITE_IOCAP_ATOMIC32K] | ||
510 | ** <li> [SQLITE_IOCAP_ATOMIC64K] | ||
511 | ** <li> [SQLITE_IOCAP_SAFE_APPEND] | ||
512 | ** <li> [SQLITE_IOCAP_SEQUENTIAL] | ||
513 | ** </ul> | ||
514 | ** | ||
515 | ** The SQLITE_IOCAP_ATOMIC property means that all writes of | ||
516 | ** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values | ||
517 | ** mean that writes of blocks that are nnn bytes in size and | ||
518 | ** are aligned to an address which is an integer multiple of | ||
519 | ** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means | ||
520 | ** that when data is appended to a file, the data is appended | ||
521 | ** first then the size of the file is extended, never the other | ||
522 | ** way around. The SQLITE_IOCAP_SEQUENTIAL property means that | ||
523 | ** information is written to disk in the same order as calls | ||
524 | ** to xWrite(). | ||
525 | */ | ||
526 | typedef struct sqlite3_io_methods sqlite3_io_methods; | ||
527 | struct sqlite3_io_methods { | ||
528 | int iVersion; | ||
529 | int (*xClose)(sqlite3_file*); | ||
530 | int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst); | ||
531 | int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst); | ||
532 | int (*xTruncate)(sqlite3_file*, sqlite3_int64 size); | ||
533 | int (*xSync)(sqlite3_file*, int flags); | ||
534 | int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize); | ||
535 | int (*xLock)(sqlite3_file*, int); | ||
536 | int (*xUnlock)(sqlite3_file*, int); | ||
537 | int (*xCheckReservedLock)(sqlite3_file*); | ||
538 | int (*xFileControl)(sqlite3_file*, int op, void *pArg); | ||
539 | int (*xSectorSize)(sqlite3_file*); | ||
540 | int (*xDeviceCharacteristics)(sqlite3_file*); | ||
541 | /* Additional methods may be added in future releases */ | ||
542 | }; | ||
543 | |||
544 | /* | ||
545 | ** CAPI3REF: Standard File Control Opcodes | ||
546 | ** | ||
547 | ** These integer constants are opcodes for the xFileControl method | ||
548 | ** of the [sqlite3_io_methods] object and to the [sqlite3_file_control()] | ||
549 | ** interface. | ||
550 | ** | ||
551 | ** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging. This | ||
552 | ** opcode cases the xFileControl method to write the current state of | ||
553 | ** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED], | ||
554 | ** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE]) | ||
555 | ** into an integer that the pArg argument points to. This capability | ||
556 | ** is used during testing and only needs to be supported when SQLITE_TEST | ||
557 | ** is defined. | ||
558 | */ | ||
559 | #define SQLITE_FCNTL_LOCKSTATE 1 | ||
560 | |||
561 | /* | ||
562 | ** CAPI3REF: Mutex Handle | ||
563 | ** | ||
564 | ** The mutex module within SQLite defines [sqlite3_mutex] to be an | ||
565 | ** abstract type for a mutex object. The SQLite core never looks | ||
566 | ** at the internal representation of an [sqlite3_mutex]. It only | ||
567 | ** deals with pointers to the [sqlite3_mutex] object. | ||
568 | ** | ||
569 | ** Mutexes are created using [sqlite3_mutex_alloc()]. | ||
570 | */ | ||
571 | typedef struct sqlite3_mutex sqlite3_mutex; | ||
572 | |||
573 | /* | ||
574 | ** CAPI3REF: OS Interface Object | ||
575 | ** | ||
576 | ** An instance of this object defines the interface between the | ||
577 | ** SQLite core and the underlying operating system. The "vfs" | ||
578 | ** in the name of the object stands for "virtual file system". | ||
579 | ** | ||
580 | ** The iVersion field is initially 1 but may be larger for future | ||
581 | ** versions of SQLite. Additional fields may be appended to this | ||
582 | ** object when the iVersion value is increased. | ||
583 | ** | ||
584 | ** The szOsFile field is the size of the subclassed [sqlite3_file] | ||
585 | ** structure used by this VFS. mxPathname is the maximum length of | ||
586 | ** a pathname in this VFS. | ||
587 | ** | ||
588 | ** Registered vfs modules are kept on a linked list formed by | ||
589 | ** the pNext pointer. The [sqlite3_vfs_register()] | ||
590 | ** and [sqlite3_vfs_unregister()] interfaces manage this list | ||
591 | ** in a thread-safe way. The [sqlite3_vfs_find()] interface | ||
592 | ** searches the list. | ||
593 | ** | ||
594 | ** The pNext field is the only fields in the sqlite3_vfs | ||
595 | ** structure that SQLite will ever modify. SQLite will only access | ||
596 | ** or modify this field while holding a particular static mutex. | ||
597 | ** The application should never modify anything within the sqlite3_vfs | ||
598 | ** object once the object has been registered. | ||
599 | ** | ||
600 | ** The zName field holds the name of the VFS module. The name must | ||
601 | ** be unique across all VFS modules. | ||
602 | ** | ||
603 | ** SQLite will guarantee that the zFilename string passed to | ||
604 | ** xOpen() is a full pathname as generated by xFullPathname() and | ||
605 | ** that the string will be valid and unchanged until xClose() is | ||
606 | ** called. So the [sqlite3_file] can store a pointer to the | ||
607 | ** filename if it needs to remember the filename for some reason. | ||
608 | ** | ||
609 | ** The flags argument to xOpen() is a copy of the flags argument | ||
610 | ** to [sqlite3_open_v2()]. If [sqlite3_open()] or [sqlite3_open16()] | ||
611 | ** is used, then flags is [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]. | ||
612 | ** If xOpen() opens a file read-only then it sets *pOutFlags to | ||
613 | ** include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be | ||
614 | ** set. | ||
615 | ** | ||
616 | ** SQLite will also add one of the following flags to the xOpen() | ||
617 | ** call, depending on the object being opened: | ||
618 | ** | ||
619 | ** <ul> | ||
620 | ** <li> [SQLITE_OPEN_MAIN_DB] | ||
621 | ** <li> [SQLITE_OPEN_MAIN_JOURNAL] | ||
622 | ** <li> [SQLITE_OPEN_TEMP_DB] | ||
623 | ** <li> [SQLITE_OPEN_TEMP_JOURNAL] | ||
624 | ** <li> [SQLITE_OPEN_TRANSIENT_DB] | ||
625 | ** <li> [SQLITE_OPEN_SUBJOURNAL] | ||
626 | ** <li> [SQLITE_OPEN_MASTER_JOURNAL] | ||
627 | ** </ul> | ||
628 | ** | ||
629 | ** The file I/O implementation can use the object type flags to | ||
630 | ** changes the way it deals with files. For example, an application | ||
631 | ** that does not care about crash recovery or rollback, might make | ||
632 | ** the open of a journal file a no-op. Writes to this journal are | ||
633 | ** also a no-op. Any attempt to read the journal return SQLITE_IOERR. | ||
634 | ** Or the implementation might recognize the a database file will | ||
635 | ** be doing page-aligned sector reads and writes in a random order | ||
636 | ** and set up its I/O subsystem accordingly. | ||
637 | ** | ||
638 | ** SQLite might also add one of the following flags to the xOpen | ||
639 | ** method: | ||
640 | ** | ||
641 | ** <ul> | ||
642 | ** <li> [SQLITE_OPEN_DELETEONCLOSE] | ||
643 | ** <li> [SQLITE_OPEN_EXCLUSIVE] | ||
644 | ** </ul> | ||
645 | ** | ||
646 | ** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be | ||
647 | ** deleted when it is closed. This will always be set for TEMP | ||
648 | ** databases and journals and for subjournals. The | ||
649 | ** [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened | ||
650 | ** for exclusive access. This flag is set for all files except | ||
651 | ** for the main database file. | ||
652 | ** | ||
653 | ** Space to hold the [sqlite3_file] structure passed as the third | ||
654 | ** argument to xOpen is allocated by caller (the SQLite core). | ||
655 | ** szOsFile bytes are allocated for this object. The xOpen method | ||
656 | ** fills in the allocated space. | ||
657 | ** | ||
658 | ** The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS] | ||
659 | ** to test for the existance of a file, | ||
660 | ** or [SQLITE_ACCESS_READWRITE] to test to see | ||
661 | ** if a file is readable and writable, or [SQLITE_ACCESS_READ] | ||
662 | ** to test to see if a file is at least readable. The file can be a | ||
663 | ** directory. | ||
664 | ** | ||
665 | ** SQLite will always allocate at least mxPathname+1 byte for | ||
666 | ** the output buffers for xGetTempname and xFullPathname. The exact | ||
667 | ** size of the output buffer is also passed as a parameter to both | ||
668 | ** methods. If the output buffer is not large enough, SQLITE_CANTOPEN | ||
669 | ** should be returned. As this is handled as a fatal error by SQLite, | ||
670 | ** vfs implementations should endevour to prevent this by setting | ||
671 | ** mxPathname to a sufficiently large value. | ||
672 | ** | ||
673 | ** The xRandomness(), xSleep(), and xCurrentTime() interfaces | ||
674 | ** are not strictly a part of the filesystem, but they are | ||
675 | ** included in the VFS structure for completeness. | ||
676 | ** The xRandomness() function attempts to return nBytes bytes | ||
677 | ** of good-quality randomness into zOut. The return value is | ||
678 | ** the actual number of bytes of randomness obtained. The | ||
679 | ** xSleep() method cause the calling thread to sleep for at | ||
680 | ** least the number of microseconds given. The xCurrentTime() | ||
681 | ** method returns a Julian Day Number for the current date and | ||
682 | ** time. | ||
683 | */ | ||
684 | typedef struct sqlite3_vfs sqlite3_vfs; | ||
685 | struct sqlite3_vfs { | ||
686 | int iVersion; /* Structure version number */ | ||
687 | int szOsFile; /* Size of subclassed sqlite3_file */ | ||
688 | int mxPathname; /* Maximum file pathname length */ | ||
689 | sqlite3_vfs *pNext; /* Next registered VFS */ | ||
690 | const char *zName; /* Name of this virtual file system */ | ||
691 | void *pAppData; /* Pointer to application-specific data */ | ||
692 | int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*, | ||
693 | int flags, int *pOutFlags); | ||
694 | int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir); | ||
695 | int (*xAccess)(sqlite3_vfs*, const char *zName, int flags); | ||
696 | int (*xGetTempname)(sqlite3_vfs*, int nOut, char *zOut); | ||
697 | int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut); | ||
698 | void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename); | ||
699 | void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg); | ||
700 | void *(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol); | ||
701 | void (*xDlClose)(sqlite3_vfs*, void*); | ||
702 | int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut); | ||
703 | int (*xSleep)(sqlite3_vfs*, int microseconds); | ||
704 | int (*xCurrentTime)(sqlite3_vfs*, double*); | ||
705 | /* New fields may be appended in figure versions. The iVersion | ||
706 | ** value will increment whenever this happens. */ | ||
707 | }; | ||
708 | |||
709 | /* | ||
710 | ** CAPI3REF: Flags for the xAccess VFS method | ||
711 | ** | ||
712 | ** These integer constants can be used as the third parameter to | ||
713 | ** the xAccess method of an [sqlite3_vfs] object. They determine | ||
714 | ** the kind of what kind of permissions the xAccess method is | ||
715 | ** looking for. With SQLITE_ACCESS_EXISTS, the xAccess method | ||
716 | ** simply checks to see if the file exists. With SQLITE_ACCESS_READWRITE, | ||
717 | ** the xAccess method checks to see if the file is both readable | ||
718 | ** and writable. With SQLITE_ACCESS_READ the xAccess method | ||
719 | ** checks to see if the file is readable. | ||
720 | */ | ||
721 | #define SQLITE_ACCESS_EXISTS 0 | ||
722 | #define SQLITE_ACCESS_READWRITE 1 | ||
723 | #define SQLITE_ACCESS_READ 2 | ||
724 | |||
725 | /* | ||
726 | ** CAPI3REF: Enable Or Disable Extended Result Codes | ||
727 | ** | ||
728 | ** This routine enables or disables the | ||
729 | ** [SQLITE_IOERR_READ | extended result codes] feature. | ||
730 | ** By default, SQLite API routines return one of only 26 integer | ||
731 | ** [SQLITE_OK | result codes]. When extended result codes | ||
732 | ** are enabled by this routine, the repetoire of result codes can be | ||
733 | ** much larger and can (hopefully) provide more detailed information | ||
734 | ** about the cause of an error. | ||
735 | ** | ||
736 | ** The second argument is a boolean value that turns extended result | ||
737 | ** codes on and off. Extended result codes are off by default for | ||
738 | ** backwards compatibility with older versions of SQLite. | ||
739 | */ | ||
740 | int sqlite3_extended_result_codes(sqlite3*, int onoff); | ||
741 | |||
742 | /* | ||
743 | ** CAPI3REF: Last Insert Rowid | ||
744 | ** | ||
745 | ** Each entry in an SQLite table has a unique 64-bit signed integer key | ||
746 | ** called the "rowid". The rowid is always available as an undeclared | ||
747 | ** column named ROWID, OID, or _ROWID_. If the table has a column of | ||
748 | ** type INTEGER PRIMARY KEY then that column is another an alias for the | ||
749 | ** rowid. | ||
750 | ** | ||
751 | ** This routine returns the rowid of the most recent INSERT into | ||
752 | ** the database from the database connection given in the first | ||
753 | ** argument. If no inserts have ever occurred on this database | ||
754 | ** connection, zero is returned. | ||
755 | ** | ||
756 | ** If an INSERT occurs within a trigger, then the rowid of the | ||
757 | ** inserted row is returned by this routine as long as the trigger | ||
758 | ** is running. But once the trigger terminates, the value returned | ||
759 | ** by this routine reverts to the last value inserted before the | ||
760 | ** trigger fired. | ||
761 | ** | ||
762 | ** If another thread does a new insert on the same database connection | ||
763 | ** while this routine is running and thus changes the last insert rowid, | ||
764 | ** then the return value of this routine is undefined. | ||
765 | */ | ||
766 | sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*); | ||
767 | |||
768 | /* | ||
769 | ** CAPI3REF: Count The Number Of Rows Modified | ||
770 | ** | ||
771 | ** This function returns the number of database rows that were changed | ||
772 | ** (or inserted or deleted) by the most recent SQL statement. Only | ||
773 | ** changes that are directly specified by the INSERT, UPDATE, or | ||
774 | ** DELETE statement are counted. Auxiliary changes caused by | ||
775 | ** triggers are not counted. Use the [sqlite3_total_changes()] function | ||
776 | ** to find the total number of changes including changes caused by triggers. | ||
777 | ** | ||
778 | ** Within the body of a trigger, the sqlite3_changes() interface can be | ||
779 | ** called to find the number of | ||
780 | ** changes in the most recently completed INSERT, UPDATE, or DELETE | ||
781 | ** statement within the body of the trigger. | ||
782 | ** | ||
783 | ** All changes are counted, even if they were later undone by a | ||
784 | ** ROLLBACK or ABORT. Except, changes associated with creating and | ||
785 | ** dropping tables are not counted. | ||
786 | ** | ||
787 | ** If a callback invokes [sqlite3_exec()] or [sqlite3_step()] recursively, | ||
788 | ** then the changes in the inner, recursive call are counted together | ||
789 | ** with the changes in the outer call. | ||
790 | ** | ||
791 | ** SQLite implements the command "DELETE FROM table" without a WHERE clause | ||
792 | ** by dropping and recreating the table. (This is much faster than going | ||
793 | ** through and deleting individual elements from the table.) Because of | ||
794 | ** this optimization, the change count for "DELETE FROM table" will be | ||
795 | ** zero regardless of the number of elements that were originally in the | ||
796 | ** table. To get an accurate count of the number of rows deleted, use | ||
797 | ** "DELETE FROM table WHERE 1" instead. | ||
798 | ** | ||
799 | ** If another thread makes changes on the same database connection | ||
800 | ** while this routine is running then the return value of this routine | ||
801 | ** is undefined. | ||
802 | */ | ||
803 | int sqlite3_changes(sqlite3*); | ||
804 | |||
805 | /* | ||
806 | ** CAPI3REF: Total Number Of Rows Modified | ||
807 | *** | ||
808 | ** This function returns the number of database rows that have been | ||
809 | ** modified by INSERT, UPDATE or DELETE statements since the database handle | ||
810 | ** was opened. This includes UPDATE, INSERT and DELETE statements executed | ||
811 | ** as part of trigger programs. All changes are counted as soon as the | ||
812 | ** statement that makes them is completed (when the statement handle is | ||
813 | ** passed to [sqlite3_reset()] or [sqlite3_finalize()]). | ||
814 | ** | ||
815 | ** See also the [sqlite3_change()] interface. | ||
816 | ** | ||
817 | ** SQLite implements the command "DELETE FROM table" without a WHERE clause | ||
818 | ** by dropping and recreating the table. (This is much faster than going | ||
819 | ** through and deleting individual elements form the table.) Because of | ||
820 | ** this optimization, the change count for "DELETE FROM table" will be | ||
821 | ** zero regardless of the number of elements that were originally in the | ||
822 | ** table. To get an accurate count of the number of rows deleted, use | ||
823 | ** "DELETE FROM table WHERE 1" instead. | ||
824 | ** | ||
825 | ** If another thread makes changes on the same database connection | ||
826 | ** while this routine is running then the return value of this routine | ||
827 | ** is undefined. | ||
828 | */ | ||
829 | int sqlite3_total_changes(sqlite3*); | ||
830 | |||
831 | /* | ||
832 | ** CAPI3REF: Interrupt A Long-Running Query | ||
833 | ** | ||
834 | ** This function causes any pending database operation to abort and | ||
835 | ** return at its earliest opportunity. This routine is typically | ||
836 | ** called in response to a user action such as pressing "Cancel" | ||
837 | ** or Ctrl-C where the user wants a long query operation to halt | ||
838 | ** immediately. | ||
839 | ** | ||
840 | ** It is safe to call this routine from a thread different from the | ||
841 | ** thread that is currently running the database operation. But it | ||
842 | ** is not safe to call this routine with a database connection that | ||
843 | ** is closed or might close before sqlite3_interrupt() returns. | ||
844 | ** | ||
845 | ** The SQL operation that is interrupted will return [SQLITE_INTERRUPT]. | ||
846 | ** If an interrupted operation was an update that is inside an | ||
847 | ** explicit transaction, then the entire transaction will be rolled | ||
848 | ** back automatically. | ||
849 | */ | ||
850 | void sqlite3_interrupt(sqlite3*); | ||
851 | |||
852 | /* | ||
853 | ** CAPI3REF: Determine If An SQL Statement Is Complete | ||
854 | ** | ||
855 | ** These functions return true if the given input string comprises | ||
856 | ** one or more complete SQL statements. For the sqlite3_complete() call, | ||
857 | ** the parameter must be a nul-terminated UTF-8 string. For | ||
858 | ** sqlite3_complete16(), a nul-terminated machine byte order UTF-16 string | ||
859 | ** is required. | ||
860 | ** | ||
861 | ** These routines are useful for command-line input to determine if the | ||
862 | ** currently entered text forms one or more complete SQL statements or | ||
863 | ** if additional input is needed before sending the statements into | ||
864 | ** SQLite for parsing. The algorithm is simple. If the | ||
865 | ** last token other than spaces and comments is a semicolon, then return | ||
866 | ** true. Actually, the algorithm is a little more complicated than that | ||
867 | ** in order to deal with triggers, but the basic idea is the same: the | ||
868 | ** statement is not complete unless it ends in a semicolon. | ||
869 | */ | ||
870 | int sqlite3_complete(const char *sql); | ||
871 | int sqlite3_complete16(const void *sql); | ||
872 | |||
873 | /* | ||
874 | ** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors | ||
875 | ** | ||
876 | ** This routine identifies a callback function that might be invoked | ||
877 | ** whenever an attempt is made to open a database table | ||
878 | ** that another thread or process has locked. | ||
879 | ** If the busy callback is NULL, then [SQLITE_BUSY] | ||
880 | ** (or sometimes [SQLITE_IOERR_BLOCKED]) | ||
881 | ** is returned immediately upon encountering the lock. | ||
882 | ** If the busy callback is not NULL, then the | ||
883 | ** callback will be invoked with two arguments. The | ||
884 | ** first argument to the handler is a copy of the void* pointer which | ||
885 | ** is the third argument to this routine. The second argument to | ||
886 | ** the handler is the number of times that the busy handler has | ||
887 | ** been invoked for this locking event. If the | ||
888 | ** busy callback returns 0, then no additional attempts are made to | ||
889 | ** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned. | ||
890 | ** If the callback returns non-zero, then another attempt is made to open the | ||
891 | ** database for reading and the cycle repeats. | ||
892 | ** | ||
893 | ** The presence of a busy handler does not guarantee that | ||
894 | ** it will be invoked when there is lock contention. | ||
895 | ** If SQLite determines that invoking the busy handler could result in | ||
896 | ** a deadlock, it will return [SQLITE_BUSY] instead. | ||
897 | ** Consider a scenario where one process is holding a read lock that | ||
898 | ** it is trying to promote to a reserved lock and | ||
899 | ** a second process is holding a reserved lock that it is trying | ||
900 | ** to promote to an exclusive lock. The first process cannot proceed | ||
901 | ** because it is blocked by the second and the second process cannot | ||
902 | ** proceed because it is blocked by the first. If both processes | ||
903 | ** invoke the busy handlers, neither will make any progress. Therefore, | ||
904 | ** SQLite returns [SQLITE_BUSY] for the first process, hoping that this | ||
905 | ** will induce the first process to release its read lock and allow | ||
906 | ** the second process to proceed. | ||
907 | ** | ||
908 | ** The default busy callback is NULL. | ||
909 | ** | ||
910 | ** The [SQLITE_BUSY] error is converted to [SQLITE_IOERR_BLOCKED] when | ||
911 | ** SQLite is in the middle of a large transaction where all the | ||
912 | ** changes will not fit into the in-memory cache. SQLite will | ||
913 | ** already hold a RESERVED lock on the database file, but it needs | ||
914 | ** to promote this lock to EXCLUSIVE so that it can spill cache | ||
915 | ** pages into the database file without harm to concurrent | ||
916 | ** readers. If it is unable to promote the lock, then the in-memory | ||
917 | ** cache will be left in an inconsistent state and so the error | ||
918 | ** code is promoted from the relatively benign [SQLITE_BUSY] to | ||
919 | ** the more severe [SQLITE_IOERR_BLOCKED]. This error code promotion | ||
920 | ** forces an automatic rollback of the changes. See the | ||
921 | ** <a href="http://www.sqlite.org/cvstrac/wiki?p=CorruptionFollowingBusyError"> | ||
922 | ** CorruptionFollowingBusyError</a> wiki page for a discussion of why | ||
923 | ** this is important. | ||
924 | ** | ||
925 | ** Sqlite is re-entrant, so the busy handler may start a new query. | ||
926 | ** (It is not clear why anyone would every want to do this, but it | ||
927 | ** is allowed, in theory.) But the busy handler may not close the | ||
928 | ** database. Closing the database from a busy handler will delete | ||
929 | ** data structures out from under the executing query and will | ||
930 | ** probably result in a segmentation fault or other runtime error. | ||
931 | ** | ||
932 | ** There can only be a single busy handler defined for each database | ||
933 | ** connection. Setting a new busy handler clears any previous one. | ||
934 | ** Note that calling [sqlite3_busy_timeout()] will also set or clear | ||
935 | ** the busy handler. | ||
936 | ** | ||
937 | ** When operating in [sqlite3_enable_shared_cache | shared cache mode], | ||
938 | ** only a single busy handler can be defined for each database file. | ||
939 | ** So if two database connections share a single cache, then changing | ||
940 | ** the busy handler on one connection will also change the busy | ||
941 | ** handler in the other connection. The busy handler is invoked | ||
942 | ** in the thread that was running when the SQLITE_BUSY was hit. | ||
943 | */ | ||
944 | int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*); | ||
945 | |||
946 | /* | ||
947 | ** CAPI3REF: Set A Busy Timeout | ||
948 | ** | ||
949 | ** This routine sets a busy handler that sleeps for a while when a | ||
950 | ** table is locked. The handler will sleep multiple times until | ||
951 | ** at least "ms" milliseconds of sleeping have been done. After | ||
952 | ** "ms" milliseconds of sleeping, the handler returns 0 which | ||
953 | ** causes [sqlite3_step()] to return [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED]. | ||
954 | ** | ||
955 | ** Calling this routine with an argument less than or equal to zero | ||
956 | ** turns off all busy handlers. | ||
957 | ** | ||
958 | ** There can only be a single busy handler for a particular database | ||
959 | ** connection. If another busy handler was defined | ||
960 | ** (using [sqlite3_busy_handler()]) prior to calling | ||
961 | ** this routine, that other busy handler is cleared. | ||
962 | */ | ||
963 | int sqlite3_busy_timeout(sqlite3*, int ms); | ||
964 | |||
965 | /* | ||
966 | ** CAPI3REF: Convenience Routines For Running Queries | ||
967 | ** | ||
968 | ** This next routine is a convenience wrapper around [sqlite3_exec()]. | ||
969 | ** Instead of invoking a user-supplied callback for each row of the | ||
970 | ** result, this routine remembers each row of the result in memory | ||
971 | ** obtained from [sqlite3_malloc()], then returns all of the result after the | ||
972 | ** query has finished. | ||
973 | ** | ||
974 | ** As an example, suppose the query result where this table: | ||
975 | ** | ||
976 | ** <blockquote><pre> | ||
977 | ** Name | Age | ||
978 | ** ----------------------- | ||
979 | ** Alice | 43 | ||
980 | ** Bob | 28 | ||
981 | ** Cindy | 21 | ||
982 | ** </pre></blockquote> | ||
983 | ** | ||
984 | ** If the 3rd argument were &azResult then after the function returns | ||
985 | ** azResult will contain the following data: | ||
986 | ** | ||
987 | ** <blockquote><pre> | ||
988 | ** azResult[0] = "Name"; | ||
989 | ** azResult[1] = "Age"; | ||
990 | ** azResult[2] = "Alice"; | ||
991 | ** azResult[3] = "43"; | ||
992 | ** azResult[4] = "Bob"; | ||
993 | ** azResult[5] = "28"; | ||
994 | ** azResult[6] = "Cindy"; | ||
995 | ** azResult[7] = "21"; | ||
996 | ** </pre></blockquote> | ||
997 | ** | ||
998 | ** Notice that there is an extra row of data containing the column | ||
999 | ** headers. But the *nrow return value is still 3. *ncolumn is | ||
1000 | ** set to 2. In general, the number of values inserted into azResult | ||
1001 | ** will be ((*nrow) + 1)*(*ncolumn). | ||
1002 | ** | ||
1003 | ** After the calling function has finished using the result, it should | ||
1004 | ** pass the result data pointer to sqlite3_free_table() in order to | ||
1005 | ** release the memory that was malloc-ed. Because of the way the | ||
1006 | ** [sqlite3_malloc()] happens, the calling function must not try to call | ||
1007 | ** [sqlite3_free()] directly. Only [sqlite3_free_table()] is able to release | ||
1008 | ** the memory properly and safely. | ||
1009 | ** | ||
1010 | ** The return value of this routine is the same as from [sqlite3_exec()]. | ||
1011 | */ | ||
1012 | int sqlite3_get_table( | ||
1013 | sqlite3*, /* An open database */ | ||
1014 | const char *sql, /* SQL to be executed */ | ||
1015 | char ***resultp, /* Result written to a char *[] that this points to */ | ||
1016 | int *nrow, /* Number of result rows written here */ | ||
1017 | int *ncolumn, /* Number of result columns written here */ | ||
1018 | char **errmsg /* Error msg written here */ | ||
1019 | ); | ||
1020 | void sqlite3_free_table(char **result); | ||
1021 | |||
1022 | /* | ||
1023 | ** CAPI3REF: Formatted String Printing Functions | ||
1024 | ** | ||
1025 | ** These routines are workalikes of the "printf()" family of functions | ||
1026 | ** from the standard C library. | ||
1027 | ** | ||
1028 | ** The sqlite3_mprintf() and sqlite3_vmprintf() routines write their | ||
1029 | ** results into memory obtained from [sqlite3_malloc()]. | ||
1030 | ** The strings returned by these two routines should be | ||
1031 | ** released by [sqlite3_free()]. Both routines return a | ||
1032 | ** NULL pointer if [sqlite3_malloc()] is unable to allocate enough | ||
1033 | ** memory to hold the resulting string. | ||
1034 | ** | ||
1035 | ** In sqlite3_snprintf() routine is similar to "snprintf()" from | ||
1036 | ** the standard C library. The result is written into the | ||
1037 | ** buffer supplied as the second parameter whose size is given by | ||
1038 | ** the first parameter. Note that the order of the | ||
1039 | ** first two parameters is reversed from snprintf(). This is an | ||
1040 | ** historical accident that cannot be fixed without breaking | ||
1041 | ** backwards compatibility. Note also that sqlite3_snprintf() | ||
1042 | ** returns a pointer to its buffer instead of the number of | ||
1043 | ** characters actually written into the buffer. We admit that | ||
1044 | ** the number of characters written would be a more useful return | ||
1045 | ** value but we cannot change the implementation of sqlite3_snprintf() | ||
1046 | ** now without breaking compatibility. | ||
1047 | ** | ||
1048 | ** As long as the buffer size is greater than zero, sqlite3_snprintf() | ||
1049 | ** guarantees that the buffer is always zero-terminated. The first | ||
1050 | ** parameter "n" is the total size of the buffer, including space for | ||
1051 | ** the zero terminator. So the longest string that can be completely | ||
1052 | ** written will be n-1 characters. | ||
1053 | ** | ||
1054 | ** These routines all implement some additional formatting | ||
1055 | ** options that are useful for constructing SQL statements. | ||
1056 | ** All of the usual printf formatting options apply. In addition, there | ||
1057 | ** is are "%q", "%Q", and "%z" options. | ||
1058 | ** | ||
1059 | ** The %q option works like %s in that it substitutes a null-terminated | ||
1060 | ** string from the argument list. But %q also doubles every '\'' character. | ||
1061 | ** %q is designed for use inside a string literal. By doubling each '\'' | ||
1062 | ** character it escapes that character and allows it to be inserted into | ||
1063 | ** the string. | ||
1064 | ** | ||
1065 | ** For example, so some string variable contains text as follows: | ||
1066 | ** | ||
1067 | ** <blockquote><pre> | ||
1068 | ** char *zText = "It's a happy day!"; | ||
1069 | ** </pre></blockquote> | ||
1070 | ** | ||
1071 | ** One can use this text in an SQL statement as follows: | ||
1072 | ** | ||
1073 | ** <blockquote><pre> | ||
1074 | ** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText); | ||
1075 | ** sqlite3_exec(db, zSQL, 0, 0, 0); | ||
1076 | ** sqlite3_free(zSQL); | ||
1077 | ** </pre></blockquote> | ||
1078 | ** | ||
1079 | ** Because the %q format string is used, the '\'' character in zText | ||
1080 | ** is escaped and the SQL generated is as follows: | ||
1081 | ** | ||
1082 | ** <blockquote><pre> | ||
1083 | ** INSERT INTO table1 VALUES('It''s a happy day!') | ||
1084 | ** </pre></blockquote> | ||
1085 | ** | ||
1086 | ** This is correct. Had we used %s instead of %q, the generated SQL | ||
1087 | ** would have looked like this: | ||
1088 | ** | ||
1089 | ** <blockquote><pre> | ||
1090 | ** INSERT INTO table1 VALUES('It's a happy day!'); | ||
1091 | ** </pre></blockquote> | ||
1092 | ** | ||
1093 | ** This second example is an SQL syntax error. As a general rule you | ||
1094 | ** should always use %q instead of %s when inserting text into a string | ||
1095 | ** literal. | ||
1096 | ** | ||
1097 | ** The %Q option works like %q except it also adds single quotes around | ||
1098 | ** the outside of the total string. Or if the parameter in the argument | ||
1099 | ** list is a NULL pointer, %Q substitutes the text "NULL" (without single | ||
1100 | ** quotes) in place of the %Q option. So, for example, one could say: | ||
1101 | ** | ||
1102 | ** <blockquote><pre> | ||
1103 | ** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText); | ||
1104 | ** sqlite3_exec(db, zSQL, 0, 0, 0); | ||
1105 | ** sqlite3_free(zSQL); | ||
1106 | ** </pre></blockquote> | ||
1107 | ** | ||
1108 | ** The code above will render a correct SQL statement in the zSQL | ||
1109 | ** variable even if the zText variable is a NULL pointer. | ||
1110 | ** | ||
1111 | ** The "%z" formatting option works exactly like "%s" with the | ||
1112 | ** addition that after the string has been read and copied into | ||
1113 | ** the result, [sqlite3_free()] is called on the input string. | ||
1114 | */ | ||
1115 | char *sqlite3_mprintf(const char*,...); | ||
1116 | char *sqlite3_vmprintf(const char*, va_list); | ||
1117 | char *sqlite3_snprintf(int,char*,const char*, ...); | ||
1118 | |||
1119 | /* | ||
1120 | ** CAPI3REF: Memory Allocation Subsystem | ||
1121 | ** | ||
1122 | ** The SQLite core uses these three routines for all of its own | ||
1123 | ** internal memory allocation needs. (See the exception below.) | ||
1124 | ** The default implementation | ||
1125 | ** of the memory allocation subsystem uses the malloc(), realloc() | ||
1126 | ** and free() provided by the standard C library. However, if | ||
1127 | ** SQLite is compiled with the following C preprocessor macro | ||
1128 | ** | ||
1129 | ** <blockquote> SQLITE_OMIT_MEMORY_ALLOCATION </blockquote> | ||
1130 | ** | ||
1131 | ** then no implementation is provided for these routines by | ||
1132 | ** SQLite. The application that links against SQLite is | ||
1133 | ** expected to provide its own implementation. If the application | ||
1134 | ** does provide its own implementation for these routines, then | ||
1135 | ** it must also provide an implementations for | ||
1136 | ** [sqlite3_memory_alarm()], [sqlite3_memory_used()], and | ||
1137 | ** [sqlite3_memory_highwater()]. The alternative implementations | ||
1138 | ** for these last three routines need not actually work, but | ||
1139 | ** stub functions at least are needed to statisfy the linker. | ||
1140 | ** SQLite never calls [sqlite3_memory_highwater()] itself, but | ||
1141 | ** the symbol is included in a table as part of the | ||
1142 | ** [sqlite3_load_extension()] interface. The | ||
1143 | ** [sqlite3_memory_alarm()] and [sqlite3_memory_used()] interfaces | ||
1144 | ** are called by [sqlite3_soft_heap_limit()] and working implementations | ||
1145 | ** of both routines must be provided if [sqlite3_soft_heap_limit()] | ||
1146 | ** is to operate correctly. | ||
1147 | ** | ||
1148 | ** <b>Exception:</b> The windows OS interface layer calls | ||
1149 | ** the system malloc() and free() directly when converting | ||
1150 | ** filenames between the UTF-8 encoding used by SQLite | ||
1151 | ** and whatever filename encoding is used by the particular windows | ||
1152 | ** installation. Memory allocation errors are detected, but | ||
1153 | ** they are reported back as [SQLITE_CANTOPEN] or | ||
1154 | ** [SQLITE_IOERR] rather than [SQLITE_NOMEM]. | ||
1155 | */ | ||
1156 | void *sqlite3_malloc(int); | ||
1157 | void *sqlite3_realloc(void*, int); | ||
1158 | void sqlite3_free(void*); | ||
1159 | |||
1160 | /* | ||
1161 | ** CAPI3REF: Memory Allocator Statistics | ||
1162 | ** | ||
1163 | ** In addition to the basic three allocation routines | ||
1164 | ** [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()], | ||
1165 | ** the memory allocation subsystem included with the SQLite | ||
1166 | ** sources provides the interfaces shown below. | ||
1167 | ** | ||
1168 | ** The first of these two routines returns the amount of memory | ||
1169 | ** currently outstanding (malloced but not freed). The second | ||
1170 | ** returns the largest instantaneous amount of outstanding | ||
1171 | ** memory. The highwater mark is reset if the argument is | ||
1172 | ** true. | ||
1173 | ** | ||
1174 | ** The implementation of these routines in the SQLite core | ||
1175 | ** is omitted if the application is compiled with the | ||
1176 | ** SQLITE_OMIT_MEMORY_ALLOCATION macro defined. In that case, | ||
1177 | ** the application that links SQLite must provide its own | ||
1178 | ** alternative implementation. See the documentation on | ||
1179 | ** [sqlite3_malloc()] for additional information. | ||
1180 | */ | ||
1181 | sqlite3_int64 sqlite3_memory_used(void); | ||
1182 | sqlite3_int64 sqlite3_memory_highwater(int resetFlag); | ||
1183 | |||
1184 | /* | ||
1185 | ** CAPI3REF: Memory Allocation Alarms | ||
1186 | ** | ||
1187 | ** The [sqlite3_memory_alarm] routine is used to register | ||
1188 | ** a callback on memory allocation events. | ||
1189 | ** | ||
1190 | ** This routine registers or clears a callbacks that fires when | ||
1191 | ** the amount of memory allocated exceeds iThreshold. Only | ||
1192 | ** a single callback can be registered at a time. Each call | ||
1193 | ** to [sqlite3_memory_alarm()] overwrites the previous callback. | ||
1194 | ** The callback is disabled by setting xCallback to a NULL | ||
1195 | ** pointer. | ||
1196 | ** | ||
1197 | ** The parameters to the callback are the pArg value, the | ||
1198 | ** amount of memory currently in use, and the size of the | ||
1199 | ** allocation that provoked the callback. The callback will | ||
1200 | ** presumably invoke [sqlite3_free()] to free up memory space. | ||
1201 | ** The callback may invoke [sqlite3_malloc()] or [sqlite3_realloc()] | ||
1202 | ** but if it does, no additional callbacks will be invoked by | ||
1203 | ** the recursive calls. | ||
1204 | ** | ||
1205 | ** The [sqlite3_soft_heap_limit()] interface works by registering | ||
1206 | ** a memory alarm at the soft heap limit and invoking | ||
1207 | ** [sqlite3_release_memory()] in the alarm callback. Application | ||
1208 | ** programs should not attempt to use the [sqlite3_memory_alarm()] | ||
1209 | ** interface because doing so will interfere with the | ||
1210 | ** [sqlite3_soft_heap_limit()] module. This interface is exposed | ||
1211 | ** only so that applications can provide their own | ||
1212 | ** alternative implementation when the SQLite core is | ||
1213 | ** compiled with SQLITE_OMIT_MEMORY_ALLOCATION. | ||
1214 | */ | ||
1215 | int sqlite3_memory_alarm( | ||
1216 | void(*xCallback)(void *pArg, sqlite3_int64 used, int N), | ||
1217 | void *pArg, | ||
1218 | sqlite3_int64 iThreshold | ||
1219 | ); | ||
1220 | |||
1221 | |||
1222 | /* | ||
1223 | ** CAPI3REF: Compile-Time Authorization Callbacks | ||
1224 | *** | ||
1225 | ** This routine registers a authorizer callback with the SQLite library. | ||
1226 | ** The authorizer callback is invoked as SQL statements are being compiled | ||
1227 | ** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()], | ||
1228 | ** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()]. At various | ||
1229 | ** points during the compilation process, as logic is being created | ||
1230 | ** to perform various actions, the authorizer callback is invoked to | ||
1231 | ** see if those actions are allowed. The authorizer callback should | ||
1232 | ** return SQLITE_OK to allow the action, [SQLITE_IGNORE] to disallow the | ||
1233 | ** specific action but allow the SQL statement to continue to be | ||
1234 | ** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be | ||
1235 | ** rejected with an error. | ||
1236 | ** | ||
1237 | ** Depending on the action, the [SQLITE_IGNORE] and [SQLITE_DENY] return | ||
1238 | ** codes might mean something different or they might mean the same | ||
1239 | ** thing. If the action is, for example, to perform a delete opertion, | ||
1240 | ** then [SQLITE_IGNORE] and [SQLITE_DENY] both cause the statement compilation | ||
1241 | ** to fail with an error. But if the action is to read a specific column | ||
1242 | ** from a specific table, then [SQLITE_DENY] will cause the entire | ||
1243 | ** statement to fail but [SQLITE_IGNORE] will cause a NULL value to be | ||
1244 | ** read instead of the actual column value. | ||
1245 | ** | ||
1246 | ** The first parameter to the authorizer callback is a copy of | ||
1247 | ** the third parameter to the sqlite3_set_authorizer() interface. | ||
1248 | ** The second parameter to the callback is an integer | ||
1249 | ** [SQLITE_COPY | action code] that specifies the particular action | ||
1250 | ** to be authorized. The available action codes are | ||
1251 | ** [SQLITE_COPY | documented separately]. The third through sixth | ||
1252 | ** parameters to the callback are strings that contain additional | ||
1253 | ** details about the action to be authorized. | ||
1254 | ** | ||
1255 | ** An authorizer is used when preparing SQL statements from an untrusted | ||
1256 | ** source, to ensure that the SQL statements do not try to access data | ||
1257 | ** that they are not allowed to see, or that they do not try to | ||
1258 | ** execute malicious statements that damage the database. For | ||
1259 | ** example, an application may allow a user to enter arbitrary | ||
1260 | ** SQL queries for evaluation by a database. But the application does | ||
1261 | ** not want the user to be able to make arbitrary changes to the | ||
1262 | ** database. An authorizer could then be put in place while the | ||
1263 | ** user-entered SQL is being prepared that disallows everything | ||
1264 | ** except SELECT statements. | ||
1265 | ** | ||
1266 | ** Only a single authorizer can be in place on a database connection | ||
1267 | ** at a time. Each call to sqlite3_set_authorizer overrides the | ||
1268 | ** previous call. A NULL authorizer means that no authorization | ||
1269 | ** callback is invoked. The default authorizer is NULL. | ||
1270 | ** | ||
1271 | ** Note that the authorizer callback is invoked only during | ||
1272 | ** [sqlite3_prepare()] or its variants. Authorization is not | ||
1273 | ** performed during statement evaluation in [sqlite3_step()]. | ||
1274 | */ | ||
1275 | int sqlite3_set_authorizer( | ||
1276 | sqlite3*, | ||
1277 | int (*xAuth)(void*,int,const char*,const char*,const char*,const char*), | ||
1278 | void *pUserData | ||
1279 | ); | ||
1280 | |||
1281 | /* | ||
1282 | ** CAPI3REF: Authorizer Return Codes | ||
1283 | ** | ||
1284 | ** The [sqlite3_set_authorizer | authorizer callback function] must | ||
1285 | ** return either [SQLITE_OK] or one of these two constants in order | ||
1286 | ** to signal SQLite whether or not the action is permitted. See the | ||
1287 | ** [sqlite3_set_authorizer | authorizer documentation] for additional | ||
1288 | ** information. | ||
1289 | */ | ||
1290 | #define SQLITE_DENY 1 /* Abort the SQL statement with an error */ | ||
1291 | #define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */ | ||
1292 | |||
1293 | /* | ||
1294 | ** CAPI3REF: Authorizer Action Codes | ||
1295 | ** | ||
1296 | ** The [sqlite3_set_authorizer()] interface registers a callback function | ||
1297 | ** that is invoked to authorizer certain SQL statement actions. The | ||
1298 | ** second parameter to the callback is an integer code that specifies | ||
1299 | ** what action is being authorized. These are the integer action codes that | ||
1300 | ** the authorizer callback may be passed. | ||
1301 | ** | ||
1302 | ** These action code values signify what kind of operation is to be | ||
1303 | ** authorized. The 3rd and 4th parameters to the authorization callback | ||
1304 | ** function will be parameters or NULL depending on which of these | ||
1305 | ** codes is used as the second parameter. The 5th parameter to the | ||
1306 | ** authorizer callback is the name of the database ("main", "temp", | ||
1307 | ** etc.) if applicable. The 6th parameter to the authorizer callback | ||
1308 | ** is the name of the inner-most trigger or view that is responsible for | ||
1309 | ** the access attempt or NULL if this access attempt is directly from | ||
1310 | ** top-level SQL code. | ||
1311 | */ | ||
1312 | /******************************************* 3rd ************ 4th ***********/ | ||
1313 | #define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */ | ||
1314 | #define SQLITE_CREATE_TABLE 2 /* Table Name NULL */ | ||
1315 | #define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */ | ||
1316 | #define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */ | ||
1317 | #define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */ | ||
1318 | #define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */ | ||
1319 | #define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */ | ||
1320 | #define SQLITE_CREATE_VIEW 8 /* View Name NULL */ | ||
1321 | #define SQLITE_DELETE 9 /* Table Name NULL */ | ||
1322 | #define SQLITE_DROP_INDEX 10 /* Index Name Table Name */ | ||
1323 | #define SQLITE_DROP_TABLE 11 /* Table Name NULL */ | ||
1324 | #define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */ | ||
1325 | #define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */ | ||
1326 | #define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */ | ||
1327 | #define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */ | ||
1328 | #define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */ | ||
1329 | #define SQLITE_DROP_VIEW 17 /* View Name NULL */ | ||
1330 | #define SQLITE_INSERT 18 /* Table Name NULL */ | ||
1331 | #define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */ | ||
1332 | #define SQLITE_READ 20 /* Table Name Column Name */ | ||
1333 | #define SQLITE_SELECT 21 /* NULL NULL */ | ||
1334 | #define SQLITE_TRANSACTION 22 /* NULL NULL */ | ||
1335 | #define SQLITE_UPDATE 23 /* Table Name Column Name */ | ||
1336 | #define SQLITE_ATTACH 24 /* Filename NULL */ | ||
1337 | #define SQLITE_DETACH 25 /* Database Name NULL */ | ||
1338 | #define SQLITE_ALTER_TABLE 26 /* Database Name Table Name */ | ||
1339 | #define SQLITE_REINDEX 27 /* Index Name NULL */ | ||
1340 | #define SQLITE_ANALYZE 28 /* Table Name NULL */ | ||
1341 | #define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */ | ||
1342 | #define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */ | ||
1343 | #define SQLITE_FUNCTION 31 /* Function Name NULL */ | ||
1344 | #define SQLITE_COPY 0 /* No longer used */ | ||
1345 | |||
1346 | /* | ||
1347 | ** CAPI3REF: Tracing And Profiling Functions | ||
1348 | ** | ||
1349 | ** These routines register callback functions that can be used for | ||
1350 | ** tracing and profiling the execution of SQL statements. | ||
1351 | ** The callback function registered by sqlite3_trace() is invoked | ||
1352 | ** at the first [sqlite3_step()] for the evaluation of an SQL statement. | ||
1353 | ** The callback function registered by sqlite3_profile() is invoked | ||
1354 | ** as each SQL statement finishes and includes | ||
1355 | ** information on how long that statement ran. | ||
1356 | ** | ||
1357 | ** The sqlite3_profile() API is currently considered experimental and | ||
1358 | ** is subject to change. | ||
1359 | */ | ||
1360 | void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*); | ||
1361 | void *sqlite3_profile(sqlite3*, | ||
1362 | void(*xProfile)(void*,const char*,sqlite3_uint64), void*); | ||
1363 | |||
1364 | /* | ||
1365 | ** CAPI3REF: Query Progress Callbacks | ||
1366 | ** | ||
1367 | ** This routine configures a callback function - the progress callback - that | ||
1368 | ** is invoked periodically during long running calls to [sqlite3_exec()], | ||
1369 | ** [sqlite3_step()] and [sqlite3_get_table()]. An example use for this | ||
1370 | ** interface is to keep a GUI updated during a large query. | ||
1371 | ** | ||
1372 | ** The progress callback is invoked once for every N virtual machine opcodes, | ||
1373 | ** where N is the second argument to this function. The progress callback | ||
1374 | ** itself is identified by the third argument to this function. The fourth | ||
1375 | ** argument to this function is a void pointer passed to the progress callback | ||
1376 | ** function each time it is invoked. | ||
1377 | ** | ||
1378 | ** If a call to [sqlite3_exec()], [sqlite3_step()], or [sqlite3_get_table()] | ||
1379 | ** results in fewer than N opcodes being executed, then the progress | ||
1380 | ** callback is never invoked. | ||
1381 | ** | ||
1382 | ** Only a single progress callback function may be registered for each | ||
1383 | ** open database connection. Every call to sqlite3_progress_handler() | ||
1384 | ** overwrites the results of the previous call. | ||
1385 | ** To remove the progress callback altogether, pass NULL as the third | ||
1386 | ** argument to this function. | ||
1387 | ** | ||
1388 | ** If the progress callback returns a result other than 0, then the current | ||
1389 | ** query is immediately terminated and any database changes rolled back. | ||
1390 | ** The containing [sqlite3_exec()], [sqlite3_step()], or | ||
1391 | ** [sqlite3_get_table()] call returns SQLITE_INTERRUPT. This feature | ||
1392 | ** can be used, for example, to implement the "Cancel" button on a | ||
1393 | ** progress dialog box in a GUI. | ||
1394 | */ | ||
1395 | void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*); | ||
1396 | |||
1397 | /* | ||
1398 | ** CAPI3REF: Opening A New Database Connection | ||
1399 | ** | ||
1400 | ** Open the sqlite database file "filename". The "filename" is UTF-8 | ||
1401 | ** encoded for [sqlite3_open()] and [sqlite3_open_v2()] and UTF-16 encoded | ||
1402 | ** in the native byte order for [sqlite3_open16()]. | ||
1403 | ** An [sqlite3*] handle is returned in *ppDb, even | ||
1404 | ** if an error occurs. If the database is opened (or created) successfully, | ||
1405 | ** then [SQLITE_OK] is returned. Otherwise an error code is returned. The | ||
1406 | ** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain | ||
1407 | ** an English language description of the error. | ||
1408 | ** | ||
1409 | ** The default encoding for the database will be UTF-8 if | ||
1410 | ** [sqlite3_open()] or [sqlite3_open_v2()] is called and | ||
1411 | ** UTF-16 if [sqlite3_open16()] is used. | ||
1412 | ** | ||
1413 | ** Whether or not an error occurs when it is opened, resources associated | ||
1414 | ** with the [sqlite3*] handle should be released by passing it to | ||
1415 | ** [sqlite3_close()] when it is no longer required. | ||
1416 | ** | ||
1417 | ** The [sqlite3_open_v2()] interface works like [sqlite3_open()] except that | ||
1418 | ** provides two additional parameters for additional control over the | ||
1419 | ** new database connection. The flags parameter can be one of: | ||
1420 | ** | ||
1421 | ** <ol> | ||
1422 | ** <li> [SQLITE_OPEN_READONLY] | ||
1423 | ** <li> [SQLITE_OPEN_READWRITE] | ||
1424 | ** <li> [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE] | ||
1425 | ** </ol> | ||
1426 | ** | ||
1427 | ** The first value opens the database read-only. If the database does | ||
1428 | ** not previously exist, an error is returned. The second option opens | ||
1429 | ** the database for reading and writing if possible, or reading only if | ||
1430 | ** if the file is write protected. In either case the database must already | ||
1431 | ** exist or an error is returned. The third option opens the database | ||
1432 | ** for reading and writing and creates it if it does not already exist. | ||
1433 | ** The third options is behavior that is always used for [sqlite3_open()] | ||
1434 | ** and [sqlite3_open16()]. | ||
1435 | ** | ||
1436 | ** If the filename is ":memory:", then an private | ||
1437 | ** in-memory database is created for the connection. This in-memory | ||
1438 | ** database will vanish when the database connection is closed. Future | ||
1439 | ** version of SQLite might make use of additional special filenames | ||
1440 | ** that begin with the ":" character. It is recommended that | ||
1441 | ** when a database filename really does begin with | ||
1442 | ** ":" that you prefix the filename with a pathname like "./" to | ||
1443 | ** avoid ambiguity. | ||
1444 | ** | ||
1445 | ** If the filename is an empty string, then a private temporary | ||
1446 | ** on-disk database will be created. This private database will be | ||
1447 | ** automatically deleted as soon as the database connection is closed. | ||
1448 | ** | ||
1449 | ** The fourth parameter to sqlite3_open_v2() is the name of the | ||
1450 | ** [sqlite3_vfs] object that defines the operating system | ||
1451 | ** interface that the new database connection should use. If the | ||
1452 | ** fourth parameter is a NULL pointer then the default [sqlite3_vfs] | ||
1453 | ** object is used. | ||
1454 | ** | ||
1455 | ** <b>Note to windows users:</b> The encoding used for the filename argument | ||
1456 | ** of [sqlite3_open()] and [sqlite3_open_v2()] must be UTF-8, not whatever | ||
1457 | ** codepage is currently defined. Filenames containing international | ||
1458 | ** characters must be converted to UTF-8 prior to passing them into | ||
1459 | ** [sqlite3_open()] or [sqlite3_open_v2()]. | ||
1460 | */ | ||
1461 | int sqlite3_open( | ||
1462 | const char *filename, /* Database filename (UTF-8) */ | ||
1463 | sqlite3 **ppDb /* OUT: SQLite db handle */ | ||
1464 | ); | ||
1465 | int sqlite3_open16( | ||
1466 | const void *filename, /* Database filename (UTF-16) */ | ||
1467 | sqlite3 **ppDb /* OUT: SQLite db handle */ | ||
1468 | ); | ||
1469 | int sqlite3_open_v2( | ||
1470 | const char *filename, /* Database filename (UTF-8) */ | ||
1471 | sqlite3 **ppDb, /* OUT: SQLite db handle */ | ||
1472 | int flags, /* Flags */ | ||
1473 | const char *zVfs /* Name of VFS module to use */ | ||
1474 | ); | ||
1475 | |||
1476 | /* | ||
1477 | ** CAPI3REF: Error Codes And Messages | ||
1478 | ** | ||
1479 | ** The sqlite3_errcode() interface returns the numeric | ||
1480 | ** [SQLITE_OK | result code] or [SQLITE_IOERR_READ | extended result code] | ||
1481 | ** for the most recent failed sqlite3_* API call associated | ||
1482 | ** with [sqlite3] handle 'db'. If a prior API call failed but the | ||
1483 | ** most recent API call succeeded, the return value from sqlite3_errcode() | ||
1484 | ** is undefined. | ||
1485 | ** | ||
1486 | ** The sqlite3_errmsg() and sqlite3_errmsg16() return English-language | ||
1487 | ** text that describes the error, as either UTF8 or UTF16 respectively. | ||
1488 | ** Memory to hold the error message string is managed internally. The | ||
1489 | ** string may be overwritten or deallocated by subsequent calls to SQLite | ||
1490 | ** interface functions. | ||
1491 | ** | ||
1492 | ** Calls to many sqlite3_* functions set the error code and string returned | ||
1493 | ** by [sqlite3_errcode()], [sqlite3_errmsg()], and [sqlite3_errmsg16()] | ||
1494 | ** (overwriting the previous values). Note that calls to [sqlite3_errcode()], | ||
1495 | ** [sqlite3_errmsg()], and [sqlite3_errmsg16()] themselves do not affect the | ||
1496 | ** results of future invocations. Calls to API routines that do not return | ||
1497 | ** an error code (example: [sqlite3_data_count()]) do not | ||
1498 | ** change the error code returned by this routine. Interfaces that are | ||
1499 | ** not associated with a specific database connection (examples: | ||
1500 | ** [sqlite3_mprintf()] or [sqlite3_enable_shared_cache()] do not change | ||
1501 | ** the return code. | ||
1502 | ** | ||
1503 | ** Assuming no other intervening sqlite3_* API calls are made, the error | ||
1504 | ** code returned by this function is associated with the same error as | ||
1505 | ** the strings returned by [sqlite3_errmsg()] and [sqlite3_errmsg16()]. | ||
1506 | */ | ||
1507 | int sqlite3_errcode(sqlite3 *db); | ||
1508 | const char *sqlite3_errmsg(sqlite3*); | ||
1509 | const void *sqlite3_errmsg16(sqlite3*); | ||
1510 | |||
1511 | /* | ||
1512 | ** CAPI3REF: SQL Statement Object | ||
1513 | ** | ||
1514 | ** Instance of this object represent single SQL statements. This | ||
1515 | ** is variously known as a "prepared statement" or a | ||
1516 | ** "compiled SQL statement" or simply as a "statement". | ||
1517 | ** | ||
1518 | ** The life of a statement object goes something like this: | ||
1519 | ** | ||
1520 | ** <ol> | ||
1521 | ** <li> Create the object using [sqlite3_prepare_v2()] or a related | ||
1522 | ** function. | ||
1523 | ** <li> Bind values to host parameters using | ||
1524 | ** [sqlite3_bind_blob | sqlite3_bind_* interfaces]. | ||
1525 | ** <li> Run the SQL by calling [sqlite3_step()] one or more times. | ||
1526 | ** <li> Reset the statement using [sqlite3_reset()] then go back | ||
1527 | ** to step 2. Do this zero or more times. | ||
1528 | ** <li> Destroy the object using [sqlite3_finalize()]. | ||
1529 | ** </ol> | ||
1530 | ** | ||
1531 | ** Refer to documentation on individual methods above for additional | ||
1532 | ** information. | ||
1533 | */ | ||
1534 | typedef struct sqlite3_stmt sqlite3_stmt; | ||
1535 | |||
1536 | /* | ||
1537 | ** CAPI3REF: Compiling An SQL Statement | ||
1538 | ** | ||
1539 | ** To execute an SQL query, it must first be compiled into a byte-code | ||
1540 | ** program using one of these routines. | ||
1541 | ** | ||
1542 | ** The first argument "db" is an [sqlite3 | SQLite database handle] | ||
1543 | ** obtained from a prior call to [sqlite3_open()], [sqlite3_open_v2()] | ||
1544 | ** or [sqlite3_open16()]. | ||
1545 | ** The second argument "zSql" is the statement to be compiled, encoded | ||
1546 | ** as either UTF-8 or UTF-16. The sqlite3_prepare() and sqlite3_prepare_v2() | ||
1547 | ** interfaces uses UTF-8 and sqlite3_prepare16() and sqlite3_prepare16_v2() | ||
1548 | ** use UTF-16. | ||
1549 | ** | ||
1550 | ** If the nByte argument is less | ||
1551 | ** than zero, then zSql is read up to the first zero terminator. If | ||
1552 | ** nByte is non-negative, then it is the maximum number of | ||
1553 | ** bytes read from zSql. When nByte is non-negative, the | ||
1554 | ** zSql string ends at either the first '\000' character or | ||
1555 | ** until the nByte-th byte, whichever comes first. | ||
1556 | ** | ||
1557 | ** *pzTail is made to point to the first byte past the end of the first | ||
1558 | ** SQL statement in zSql. This routine only compiles the first statement | ||
1559 | ** in zSql, so *pzTail is left pointing to what remains uncompiled. | ||
1560 | ** | ||
1561 | ** *ppStmt is left pointing to a compiled | ||
1562 | ** [sqlite3_stmt | SQL statement structure] that can be | ||
1563 | ** executed using [sqlite3_step()]. Or if there is an error, *ppStmt may be | ||
1564 | ** set to NULL. If the input text contained no SQL (if the input is and | ||
1565 | ** empty string or a comment) then *ppStmt is set to NULL. The calling | ||
1566 | ** procedure is responsible for deleting the compiled SQL statement | ||
1567 | ** using [sqlite3_finalize()] after it has finished with it. | ||
1568 | ** | ||
1569 | ** On success, [SQLITE_OK] is returned. Otherwise an | ||
1570 | ** [SQLITE_ERROR | error code] is returned. | ||
1571 | ** | ||
1572 | ** The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are | ||
1573 | ** recommended for all new programs. The two older interfaces are retained | ||
1574 | ** for backwards compatibility, but their use is discouraged. | ||
1575 | ** In the "v2" interfaces, the prepared statement | ||
1576 | ** that is returned (the [sqlite3_stmt] object) contains a copy of the | ||
1577 | ** original SQL text. This causes the [sqlite3_step()] interface to | ||
1578 | ** behave a differently in two ways: | ||
1579 | ** | ||
1580 | ** <ol> | ||
1581 | ** <li> | ||
1582 | ** If the database schema changes, instead of returning [SQLITE_SCHEMA] as it | ||
1583 | ** always used to do, [sqlite3_step()] will automatically recompile the SQL | ||
1584 | ** statement and try to run it again. If the schema has changed in a way | ||
1585 | ** that makes the statement no longer valid, [sqlite3_step()] will still | ||
1586 | ** return [SQLITE_SCHEMA]. But unlike the legacy behavior, [SQLITE_SCHEMA] is | ||
1587 | ** now a fatal error. Calling [sqlite3_prepare_v2()] again will not make the | ||
1588 | ** error go away. Note: use [sqlite3_errmsg()] to find the text of the parsing | ||
1589 | ** error that results in an [SQLITE_SCHEMA] return. | ||
1590 | ** </li> | ||
1591 | ** | ||
1592 | ** <li> | ||
1593 | ** When an error occurs, | ||
1594 | ** [sqlite3_step()] will return one of the detailed | ||
1595 | ** [SQLITE_ERROR | result codes] or | ||
1596 | ** [SQLITE_IOERR_READ | extended result codes] such as directly. | ||
1597 | ** The legacy behavior was that [sqlite3_step()] would only return a generic | ||
1598 | ** [SQLITE_ERROR] result code and you would have to make a second call to | ||
1599 | ** [sqlite3_reset()] in order to find the underlying cause of the problem. | ||
1600 | ** With the "v2" prepare interfaces, the underlying reason for the error is | ||
1601 | ** returned immediately. | ||
1602 | ** </li> | ||
1603 | ** </ol> | ||
1604 | */ | ||
1605 | int sqlite3_prepare( | ||
1606 | sqlite3 *db, /* Database handle */ | ||
1607 | const char *zSql, /* SQL statement, UTF-8 encoded */ | ||
1608 | int nByte, /* Maximum length of zSql in bytes. */ | ||
1609 | sqlite3_stmt **ppStmt, /* OUT: Statement handle */ | ||
1610 | const char **pzTail /* OUT: Pointer to unused portion of zSql */ | ||
1611 | ); | ||
1612 | int sqlite3_prepare_v2( | ||
1613 | sqlite3 *db, /* Database handle */ | ||
1614 | const char *zSql, /* SQL statement, UTF-8 encoded */ | ||
1615 | int nByte, /* Maximum length of zSql in bytes. */ | ||
1616 | sqlite3_stmt **ppStmt, /* OUT: Statement handle */ | ||
1617 | const char **pzTail /* OUT: Pointer to unused portion of zSql */ | ||
1618 | ); | ||
1619 | int sqlite3_prepare16( | ||
1620 | sqlite3 *db, /* Database handle */ | ||
1621 | const void *zSql, /* SQL statement, UTF-16 encoded */ | ||
1622 | int nByte, /* Maximum length of zSql in bytes. */ | ||
1623 | sqlite3_stmt **ppStmt, /* OUT: Statement handle */ | ||
1624 | const void **pzTail /* OUT: Pointer to unused portion of zSql */ | ||
1625 | ); | ||
1626 | int sqlite3_prepare16_v2( | ||
1627 | sqlite3 *db, /* Database handle */ | ||
1628 | const void *zSql, /* SQL statement, UTF-16 encoded */ | ||
1629 | int nByte, /* Maximum length of zSql in bytes. */ | ||
1630 | sqlite3_stmt **ppStmt, /* OUT: Statement handle */ | ||
1631 | const void **pzTail /* OUT: Pointer to unused portion of zSql */ | ||
1632 | ); | ||
1633 | |||
1634 | /* | ||
1635 | ** CAPI3REF: Dynamically Typed Value Object | ||
1636 | ** | ||
1637 | ** SQLite uses dynamic typing for the values it stores. Values can | ||
1638 | ** be integers, floating point values, strings, BLOBs, or NULL. When | ||
1639 | ** passing around values internally, each value is represented as | ||
1640 | ** an instance of the sqlite3_value object. | ||
1641 | */ | ||
1642 | typedef struct Mem sqlite3_value; | ||
1643 | |||
1644 | /* | ||
1645 | ** CAPI3REF: SQL Function Context Object | ||
1646 | ** | ||
1647 | ** The context in which an SQL function executes is stored in an | ||
1648 | ** sqlite3_context object. A pointer to such an object is the | ||
1649 | ** first parameter to user-defined SQL functions. | ||
1650 | */ | ||
1651 | typedef struct sqlite3_context sqlite3_context; | ||
1652 | |||
1653 | /* | ||
1654 | ** CAPI3REF: Binding Values To Prepared Statements | ||
1655 | ** | ||
1656 | ** In the SQL strings input to [sqlite3_prepare_v2()] and its variants, | ||
1657 | ** one or more literals can be replace by a parameter in one of these | ||
1658 | ** forms: | ||
1659 | ** | ||
1660 | ** <ul> | ||
1661 | ** <li> ? | ||
1662 | ** <li> ?NNN | ||
1663 | ** <li> :AAA | ||
1664 | ** <li> @AAA | ||
1665 | ** <li> $VVV | ||
1666 | ** </ul> | ||
1667 | ** | ||
1668 | ** In the parameter forms shown above NNN is an integer literal, | ||
1669 | ** AAA is an alphanumeric identifier and VVV is a variable name according | ||
1670 | ** to the syntax rules of the TCL programming language. | ||
1671 | ** The values of these parameters (also called "host parameter names") | ||
1672 | ** can be set using the sqlite3_bind_*() routines defined here. | ||
1673 | ** | ||
1674 | ** The first argument to the sqlite3_bind_*() routines always is a pointer | ||
1675 | ** to the [sqlite3_stmt] object returned from [sqlite3_prepare_v2()] or | ||
1676 | ** its variants. The second | ||
1677 | ** argument is the index of the parameter to be set. The first parameter has | ||
1678 | ** an index of 1. When the same named parameter is used more than once, second | ||
1679 | ** and subsequent | ||
1680 | ** occurrences have the same index as the first occurrence. The index for | ||
1681 | ** named parameters can be looked up using the | ||
1682 | ** [sqlite3_bind_parameter_name()] API if desired. The index for "?NNN" | ||
1683 | ** parametes is the value of NNN. | ||
1684 | ** The NNN value must be between 1 and the compile-time | ||
1685 | ** parameter SQLITE_MAX_VARIABLE_NUMBER (default value: 999). | ||
1686 | ** See <a href="limits.html">limits.html</a> for additional information. | ||
1687 | ** | ||
1688 | ** The third argument is the value to bind to the parameter. | ||
1689 | ** | ||
1690 | ** In those | ||
1691 | ** routines that have a fourth argument, its value is the number of bytes | ||
1692 | ** in the parameter. To be clear: the value is the number of bytes in the | ||
1693 | ** string, not the number of characters. The number | ||
1694 | ** of bytes does not include the zero-terminator at the end of strings. | ||
1695 | ** If the fourth parameter is negative, the length of the string is | ||
1696 | ** number of bytes up to the first zero terminator. | ||
1697 | ** | ||
1698 | ** The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and | ||
1699 | ** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or | ||
1700 | ** text after SQLite has finished with it. If the fifth argument is the | ||
1701 | ** special value [SQLITE_STATIC], then the library assumes that the information | ||
1702 | ** is in static, unmanaged space and does not need to be freed. If the | ||
1703 | ** fifth argument has the value [SQLITE_TRANSIENT], then SQLite makes its | ||
1704 | ** own private copy of the data immediately, before the sqlite3_bind_*() | ||
1705 | ** routine returns. | ||
1706 | ** | ||
1707 | ** The sqlite3_bind_zeroblob() routine binds a BLOB of length n that | ||
1708 | ** is filled with zeros. A zeroblob uses a fixed amount of memory | ||
1709 | ** (just an integer to hold it size) while it is being processed. | ||
1710 | ** Zeroblobs are intended to serve as place-holders for BLOBs whose | ||
1711 | ** content is later written using | ||
1712 | ** [sqlite3_blob_open | increment BLOB I/O] routines. A negative | ||
1713 | ** value for the zeroblob results in a zero-length BLOB. | ||
1714 | ** | ||
1715 | ** The sqlite3_bind_*() routines must be called after | ||
1716 | ** [sqlite3_prepare_v2()] (and its variants) or [sqlite3_reset()] and | ||
1717 | ** before [sqlite3_step()]. | ||
1718 | ** Bindings are not cleared by the [sqlite3_reset()] routine. | ||
1719 | ** Unbound parameters are interpreted as NULL. | ||
1720 | ** | ||
1721 | ** These routines return [SQLITE_OK] on success or an error code if | ||
1722 | ** anything goes wrong. [SQLITE_RANGE] is returned if the parameter | ||
1723 | ** index is out of range. [SQLITE_NOMEM] is returned if malloc fails. | ||
1724 | ** [SQLITE_MISUSE] is returned if these routines are called on a virtual | ||
1725 | ** machine that is the wrong state or which has already been finalized. | ||
1726 | */ | ||
1727 | int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*)); | ||
1728 | int sqlite3_bind_double(sqlite3_stmt*, int, double); | ||
1729 | int sqlite3_bind_int(sqlite3_stmt*, int, int); | ||
1730 | int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64); | ||
1731 | int sqlite3_bind_null(sqlite3_stmt*, int); | ||
1732 | int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*)); | ||
1733 | int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*)); | ||
1734 | int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*); | ||
1735 | int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n); | ||
1736 | |||
1737 | /* | ||
1738 | ** CAPI3REF: Number Of Host Parameters | ||
1739 | ** | ||
1740 | ** Return the largest host parameter index in the precompiled statement given | ||
1741 | ** as the argument. When the host parameters are of the forms like ":AAA" | ||
1742 | ** or "?", then they are assigned sequential increasing numbers beginning | ||
1743 | ** with one, so the value returned is the number of parameters. However | ||
1744 | ** if the same host parameter name is used multiple times, each occurrance | ||
1745 | ** is given the same number, so the value returned in that case is the number | ||
1746 | ** of unique host parameter names. If host parameters of the form "?NNN" | ||
1747 | ** are used (where NNN is an integer) then there might be gaps in the | ||
1748 | ** numbering and the value returned by this interface is the index of the | ||
1749 | ** host parameter with the largest index value. | ||
1750 | ** | ||
1751 | ** The prepared statement must not be [sqlite3_finalize | finalized] | ||
1752 | ** prior to this routine returnning. Otherwise the results are undefined | ||
1753 | ** and probably undesirable. | ||
1754 | */ | ||
1755 | int sqlite3_bind_parameter_count(sqlite3_stmt*); | ||
1756 | |||
1757 | /* | ||
1758 | ** CAPI3REF: Name Of A Host Parameter | ||
1759 | ** | ||
1760 | ** This routine returns a pointer to the name of the n-th parameter in a | ||
1761 | ** [sqlite3_stmt | prepared statement]. | ||
1762 | ** Host parameters of the form ":AAA" or "@AAA" or "$VVV" have a name | ||
1763 | ** which is the string ":AAA" or "@AAA" or "$VVV". | ||
1764 | ** In other words, the initial ":" or "$" or "@" | ||
1765 | ** is included as part of the name. | ||
1766 | ** Parameters of the form "?" or "?NNN" have no name. | ||
1767 | ** | ||
1768 | ** The first bound parameter has an index of 1, not 0. | ||
1769 | ** | ||
1770 | ** If the value n is out of range or if the n-th parameter is nameless, | ||
1771 | ** then NULL is returned. The returned string is always in the | ||
1772 | ** UTF-8 encoding even if the named parameter was originally specified | ||
1773 | ** as UTF-16 in [sqlite3_prepare16()] or [sqlite3_prepare16_v2()]. | ||
1774 | */ | ||
1775 | const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int); | ||
1776 | |||
1777 | /* | ||
1778 | ** CAPI3REF: Index Of A Parameter With A Given Name | ||
1779 | ** | ||
1780 | ** This routine returns the index of a host parameter with the given name. | ||
1781 | ** The name must match exactly. If no parameter with the given name is | ||
1782 | ** found, return 0. Parameter names must be UTF8. | ||
1783 | */ | ||
1784 | int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName); | ||
1785 | |||
1786 | /* | ||
1787 | ** CAPI3REF: Reset All Bindings On A Prepared Statement | ||
1788 | ** | ||
1789 | ** Contrary to the intuition of many, [sqlite3_reset()] does not | ||
1790 | ** reset the [sqlite3_bind_blob | bindings] on a | ||
1791 | ** [sqlite3_stmt | prepared statement]. Use this routine to | ||
1792 | ** reset all host parameters to NULL. | ||
1793 | */ | ||
1794 | int sqlite3_clear_bindings(sqlite3_stmt*); | ||
1795 | |||
1796 | /* | ||
1797 | ** CAPI3REF: Number Of Columns In A Result Set | ||
1798 | ** | ||
1799 | ** Return the number of columns in the result set returned by the | ||
1800 | ** [sqlite3_stmt | compiled SQL statement]. This routine returns 0 | ||
1801 | ** if pStmt is an SQL statement that does not return data (for | ||
1802 | ** example an UPDATE). | ||
1803 | */ | ||
1804 | int sqlite3_column_count(sqlite3_stmt *pStmt); | ||
1805 | |||
1806 | /* | ||
1807 | ** CAPI3REF: Column Names In A Result Set | ||
1808 | ** | ||
1809 | ** These routines return the name assigned to a particular column | ||
1810 | ** in the result set of a SELECT statement. The sqlite3_column_name() | ||
1811 | ** interface returns a pointer to a UTF8 string and sqlite3_column_name16() | ||
1812 | ** returns a pointer to a UTF16 string. The first parameter is the | ||
1813 | ** [sqlite3_stmt | prepared statement] that implements the SELECT statement. | ||
1814 | ** The second parameter is the column number. The left-most column is | ||
1815 | ** number 0. | ||
1816 | ** | ||
1817 | ** The returned string pointer is valid until either the | ||
1818 | ** [sqlite3_stmt | prepared statement] is destroyed by [sqlite3_finalize()] | ||
1819 | ** or until the next call sqlite3_column_name() or sqlite3_column_name16() | ||
1820 | ** on the same column. | ||
1821 | ** | ||
1822 | ** If sqlite3_malloc() fails during the processing of either routine | ||
1823 | ** (for example during a conversion from UTF-8 to UTF-16) then a | ||
1824 | ** NULL pointer is returned. | ||
1825 | */ | ||
1826 | const char *sqlite3_column_name(sqlite3_stmt*, int N); | ||
1827 | const void *sqlite3_column_name16(sqlite3_stmt*, int N); | ||
1828 | |||
1829 | /* | ||
1830 | ** CAPI3REF: Source Of Data In A Query Result | ||
1831 | ** | ||
1832 | ** These routines provide a means to determine what column of what | ||
1833 | ** table in which database a result of a SELECT statement comes from. | ||
1834 | ** The name of the database or table or column can be returned as | ||
1835 | ** either a UTF8 or UTF16 string. The _database_ routines return | ||
1836 | ** the database name, the _table_ routines return the table name, and | ||
1837 | ** the origin_ routines return the column name. | ||
1838 | ** The returned string is valid until | ||
1839 | ** the [sqlite3_stmt | prepared statement] is destroyed using | ||
1840 | ** [sqlite3_finalize()] or until the same information is requested | ||
1841 | ** again in a different encoding. | ||
1842 | ** | ||
1843 | ** The names returned are the original un-aliased names of the | ||
1844 | ** database, table, and column. | ||
1845 | ** | ||
1846 | ** The first argument to the following calls is a | ||
1847 | ** [sqlite3_stmt | compiled SQL statement]. | ||
1848 | ** These functions return information about the Nth column returned by | ||
1849 | ** the statement, where N is the second function argument. | ||
1850 | ** | ||
1851 | ** If the Nth column returned by the statement is an expression | ||
1852 | ** or subquery and is not a column value, then all of these functions | ||
1853 | ** return NULL. Otherwise, they return the | ||
1854 | ** name of the attached database, table and column that query result | ||
1855 | ** column was extracted from. | ||
1856 | ** | ||
1857 | ** As with all other SQLite APIs, those postfixed with "16" return UTF-16 | ||
1858 | ** encoded strings, the other functions return UTF-8. | ||
1859 | ** | ||
1860 | ** These APIs are only available if the library was compiled with the | ||
1861 | ** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined. | ||
1862 | ** | ||
1863 | ** If two or more threads call one or more of these routines against the same | ||
1864 | ** prepared statement and column at the same time then the results are | ||
1865 | ** undefined. | ||
1866 | */ | ||
1867 | const char *sqlite3_column_database_name(sqlite3_stmt*,int); | ||
1868 | const void *sqlite3_column_database_name16(sqlite3_stmt*,int); | ||
1869 | const char *sqlite3_column_table_name(sqlite3_stmt*,int); | ||
1870 | const void *sqlite3_column_table_name16(sqlite3_stmt*,int); | ||
1871 | const char *sqlite3_column_origin_name(sqlite3_stmt*,int); | ||
1872 | const void *sqlite3_column_origin_name16(sqlite3_stmt*,int); | ||
1873 | |||
1874 | /* | ||
1875 | ** CAPI3REF: Declared Datatype Of A Query Result | ||
1876 | ** | ||
1877 | ** The first parameter is a [sqlite3_stmt | compiled SQL statement]. | ||
1878 | ** If this statement is a SELECT statement and the Nth column of the | ||
1879 | ** returned result set of that SELECT is a table column (not an | ||
1880 | ** expression or subquery) then the declared type of the table | ||
1881 | ** column is returned. If the Nth column of the result set is an | ||
1882 | ** expression or subquery, then a NULL pointer is returned. | ||
1883 | ** The returned string is always UTF-8 encoded. For example, in | ||
1884 | ** the database schema: | ||
1885 | ** | ||
1886 | ** CREATE TABLE t1(c1 VARIANT); | ||
1887 | ** | ||
1888 | ** And the following statement compiled: | ||
1889 | ** | ||
1890 | ** SELECT c1 + 1, c1 FROM t1; | ||
1891 | ** | ||
1892 | ** Then this routine would return the string "VARIANT" for the second | ||
1893 | ** result column (i==1), and a NULL pointer for the first result column | ||
1894 | ** (i==0). | ||
1895 | ** | ||
1896 | ** SQLite uses dynamic run-time typing. So just because a column | ||
1897 | ** is declared to contain a particular type does not mean that the | ||
1898 | ** data stored in that column is of the declared type. SQLite is | ||
1899 | ** strongly typed, but the typing is dynamic not static. Type | ||
1900 | ** is associated with individual values, not with the containers | ||
1901 | ** used to hold those values. | ||
1902 | */ | ||
1903 | const char *sqlite3_column_decltype(sqlite3_stmt *, int i); | ||
1904 | const void *sqlite3_column_decltype16(sqlite3_stmt*,int); | ||
1905 | |||
1906 | /* | ||
1907 | ** CAPI3REF: Evaluate An SQL Statement | ||
1908 | ** | ||
1909 | ** After an [sqlite3_stmt | SQL statement] has been prepared with a call | ||
1910 | ** to either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or to one of | ||
1911 | ** the legacy interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], | ||
1912 | ** then this function must be called one or more times to evaluate the | ||
1913 | ** statement. | ||
1914 | ** | ||
1915 | ** The details of the behavior of this sqlite3_step() interface depend | ||
1916 | ** on whether the statement was prepared using the newer "v2" interface | ||
1917 | ** [sqlite3_prepare_v2()] and [sqlite3_prepare16_v2()] or the older legacy | ||
1918 | ** interface [sqlite3_prepare()] and [sqlite3_prepare16()]. The use of the | ||
1919 | ** new "v2" interface is recommended for new applications but the legacy | ||
1920 | ** interface will continue to be supported. | ||
1921 | ** | ||
1922 | ** In the lagacy interface, the return value will be either [SQLITE_BUSY], | ||
1923 | ** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE]. | ||
1924 | ** With the "v2" interface, any of the other [SQLITE_OK | result code] | ||
1925 | ** or [SQLITE_IOERR_READ | extended result code] might be returned as | ||
1926 | ** well. | ||
1927 | ** | ||
1928 | ** [SQLITE_BUSY] means that the database engine was unable to acquire the | ||
1929 | ** database locks it needs to do its job. If the statement is a COMMIT | ||
1930 | ** or occurs outside of an explicit transaction, then you can retry the | ||
1931 | ** statement. If the statement is not a COMMIT and occurs within a | ||
1932 | ** explicit transaction then you should rollback the transaction before | ||
1933 | ** continuing. | ||
1934 | ** | ||
1935 | ** [SQLITE_DONE] means that the statement has finished executing | ||
1936 | ** successfully. sqlite3_step() should not be called again on this virtual | ||
1937 | ** machine without first calling [sqlite3_reset()] to reset the virtual | ||
1938 | ** machine back to its initial state. | ||
1939 | ** | ||
1940 | ** If the SQL statement being executed returns any data, then | ||
1941 | ** [SQLITE_ROW] is returned each time a new row of data is ready | ||
1942 | ** for processing by the caller. The values may be accessed using | ||
1943 | ** the [sqlite3_column_int | column access functions]. | ||
1944 | ** sqlite3_step() is called again to retrieve the next row of data. | ||
1945 | ** | ||
1946 | ** [SQLITE_ERROR] means that a run-time error (such as a constraint | ||
1947 | ** violation) has occurred. sqlite3_step() should not be called again on | ||
1948 | ** the VM. More information may be found by calling [sqlite3_errmsg()]. | ||
1949 | ** With the legacy interface, a more specific error code (example: | ||
1950 | ** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth) | ||
1951 | ** can be obtained by calling [sqlite3_reset()] on the | ||
1952 | ** [sqlite3_stmt | prepared statement]. In the "v2" interface, | ||
1953 | ** the more specific error code is returned directly by sqlite3_step(). | ||
1954 | ** | ||
1955 | ** [SQLITE_MISUSE] means that the this routine was called inappropriately. | ||
1956 | ** Perhaps it was called on a [sqlite3_stmt | prepared statement] that has | ||
1957 | ** already been [sqlite3_finalize | finalized] or on one that had | ||
1958 | ** previously returned [SQLITE_ERROR] or [SQLITE_DONE]. Or it could | ||
1959 | ** be the case that the same database connection is being used by two or | ||
1960 | ** more threads at the same moment in time. | ||
1961 | ** | ||
1962 | ** <b>Goofy Interface Alert:</b> | ||
1963 | ** In the legacy interface, | ||
1964 | ** the sqlite3_step() API always returns a generic error code, | ||
1965 | ** [SQLITE_ERROR], following any error other than [SQLITE_BUSY] | ||
1966 | ** and [SQLITE_MISUSE]. You must call [sqlite3_reset()] or | ||
1967 | ** [sqlite3_finalize()] in order to find one of the specific | ||
1968 | ** [SQLITE_ERROR | result codes] that better describes the error. | ||
1969 | ** We admit that this is a goofy design. The problem has been fixed | ||
1970 | ** with the "v2" interface. If you prepare all of your SQL statements | ||
1971 | ** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead | ||
1972 | ** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()], then the | ||
1973 | ** more specific [SQLITE_ERROR | result codes] are returned directly | ||
1974 | ** by sqlite3_step(). The use of the "v2" interface is recommended. | ||
1975 | */ | ||
1976 | int sqlite3_step(sqlite3_stmt*); | ||
1977 | |||
1978 | /* | ||
1979 | ** CAPI3REF: | ||
1980 | ** | ||
1981 | ** Return the number of values in the current row of the result set. | ||
1982 | ** | ||
1983 | ** After a call to [sqlite3_step()] that returns [SQLITE_ROW], this routine | ||
1984 | ** will return the same value as the [sqlite3_column_count()] function. | ||
1985 | ** After [sqlite3_step()] has returned an [SQLITE_DONE], [SQLITE_BUSY], or | ||
1986 | ** a [SQLITE_ERROR | error code], or before [sqlite3_step()] has been | ||
1987 | ** called on the [sqlite3_stmt | prepared statement] for the first time, | ||
1988 | ** this routine returns zero. | ||
1989 | */ | ||
1990 | int sqlite3_data_count(sqlite3_stmt *pStmt); | ||
1991 | |||
1992 | /* | ||
1993 | ** CAPI3REF: Fundamental Datatypes | ||
1994 | ** | ||
1995 | ** Every value in SQLite has one of five fundamental datatypes: | ||
1996 | ** | ||
1997 | ** <ul> | ||
1998 | ** <li> 64-bit signed integer | ||
1999 | ** <li> 64-bit IEEE floating point number | ||
2000 | ** <li> string | ||
2001 | ** <li> BLOB | ||
2002 | ** <li> NULL | ||
2003 | ** </ul> | ||
2004 | ** | ||
2005 | ** These constants are codes for each of those types. | ||
2006 | ** | ||
2007 | ** Note that the SQLITE_TEXT constant was also used in SQLite version 2 | ||
2008 | ** for a completely different meaning. Software that links against both | ||
2009 | ** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT not | ||
2010 | ** SQLITE_TEXT. | ||
2011 | */ | ||
2012 | #define SQLITE_INTEGER 1 | ||
2013 | #define SQLITE_FLOAT 2 | ||
2014 | #define SQLITE_BLOB 4 | ||
2015 | #define SQLITE_NULL 5 | ||
2016 | #ifdef SQLITE_TEXT | ||
2017 | # undef SQLITE_TEXT | ||
2018 | #else | ||
2019 | # define SQLITE_TEXT 3 | ||
2020 | #endif | ||
2021 | #define SQLITE3_TEXT 3 | ||
2022 | |||
2023 | /* | ||
2024 | ** CAPI3REF: Results Values From A Query | ||
2025 | ** | ||
2026 | ** These routines return information about | ||
2027 | ** a single column of the current result row of a query. In every | ||
2028 | ** case the first argument is a pointer to the | ||
2029 | ** [sqlite3_stmt | SQL statement] that is being | ||
2030 | ** evaluated (the [sqlite3_stmt*] that was returned from | ||
2031 | ** [sqlite3_prepare_v2()] or one of its variants) and | ||
2032 | ** the second argument is the index of the column for which information | ||
2033 | ** should be returned. The left-most column of the result set | ||
2034 | ** has an index of 0. | ||
2035 | ** | ||
2036 | ** If the SQL statement is not currently point to a valid row, or if the | ||
2037 | ** the column index is out of range, the result is undefined. | ||
2038 | ** These routines may only be called when the most recent call to | ||
2039 | ** [sqlite3_step()] has returned [SQLITE_ROW] and neither | ||
2040 | ** [sqlite3_reset()] nor [sqlite3_finalize()] has been call subsequently. | ||
2041 | ** If any of these routines are called after [sqlite3_reset()] or | ||
2042 | ** [sqlite3_finalize()] or after [sqlite3_step()] has returned | ||
2043 | ** something other than [SQLITE_ROW], the results are undefined. | ||
2044 | ** If [sqlite3_step()] or [sqlite3_reset()] or [sqlite3_finalize()] | ||
2045 | ** are called from a different thread while any of these routines | ||
2046 | ** are pending, then the results are undefined. | ||
2047 | ** | ||
2048 | ** The sqlite3_column_type() routine returns | ||
2049 | ** [SQLITE_INTEGER | datatype code] for the initial data type | ||
2050 | ** of the result column. The returned value is one of [SQLITE_INTEGER], | ||
2051 | ** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL]. The value | ||
2052 | ** returned by sqlite3_column_type() is only meaningful if no type | ||
2053 | ** conversions have occurred as described below. After a type conversion, | ||
2054 | ** the value returned by sqlite3_column_type() is undefined. Future | ||
2055 | ** versions of SQLite may change the behavior of sqlite3_column_type() | ||
2056 | ** following a type conversion. | ||
2057 | ** | ||
2058 | ** If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes() | ||
2059 | ** routine returns the number of bytes in that BLOB or string. | ||
2060 | ** If the result is a UTF-16 string, then sqlite3_column_bytes() converts | ||
2061 | ** the string to UTF-8 and then returns the number of bytes. | ||
2062 | ** If the result is a numeric value then sqlite3_column_bytes() uses | ||
2063 | ** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns | ||
2064 | ** the number of bytes in that string. | ||
2065 | ** The value returned does not include the zero terminator at the end | ||
2066 | ** of the string. For clarity: the value returned is the number of | ||
2067 | ** bytes in the string, not the number of characters. | ||
2068 | ** | ||
2069 | ** Strings returned by sqlite3_column_text() and sqlite3_column_text16(), | ||
2070 | ** even zero-length strings, are always zero terminated. The return | ||
2071 | ** value from sqlite3_column_blob() for a zero-length blob is an arbitrary | ||
2072 | ** pointer, possibly even a NULL pointer. | ||
2073 | ** | ||
2074 | ** The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes() | ||
2075 | ** but leaves the result in UTF-16 instead of UTF-8. | ||
2076 | ** The zero terminator is not included in this count. | ||
2077 | ** | ||
2078 | ** These routines attempt to convert the value where appropriate. For | ||
2079 | ** example, if the internal representation is FLOAT and a text result | ||
2080 | ** is requested, [sqlite3_snprintf()] is used internally to do the conversion | ||
2081 | ** automatically. The following table details the conversions that | ||
2082 | ** are applied: | ||
2083 | ** | ||
2084 | ** <blockquote> | ||
2085 | ** <table border="1"> | ||
2086 | ** <tr><th> Internal<br>Type <th> Requested<br>Type <th> Conversion | ||
2087 | ** | ||
2088 | ** <tr><td> NULL <td> INTEGER <td> Result is 0 | ||
2089 | ** <tr><td> NULL <td> FLOAT <td> Result is 0.0 | ||
2090 | ** <tr><td> NULL <td> TEXT <td> Result is NULL pointer | ||
2091 | ** <tr><td> NULL <td> BLOB <td> Result is NULL pointer | ||
2092 | ** <tr><td> INTEGER <td> FLOAT <td> Convert from integer to float | ||
2093 | ** <tr><td> INTEGER <td> TEXT <td> ASCII rendering of the integer | ||
2094 | ** <tr><td> INTEGER <td> BLOB <td> Same as for INTEGER->TEXT | ||
2095 | ** <tr><td> FLOAT <td> INTEGER <td> Convert from float to integer | ||
2096 | ** <tr><td> FLOAT <td> TEXT <td> ASCII rendering of the float | ||
2097 | ** <tr><td> FLOAT <td> BLOB <td> Same as FLOAT->TEXT | ||
2098 | ** <tr><td> TEXT <td> INTEGER <td> Use atoi() | ||
2099 | ** <tr><td> TEXT <td> FLOAT <td> Use atof() | ||
2100 | ** <tr><td> TEXT <td> BLOB <td> No change | ||
2101 | ** <tr><td> BLOB <td> INTEGER <td> Convert to TEXT then use atoi() | ||
2102 | ** <tr><td> BLOB <td> FLOAT <td> Convert to TEXT then use atof() | ||
2103 | ** <tr><td> BLOB <td> TEXT <td> Add a zero terminator if needed | ||
2104 | ** </table> | ||
2105 | ** </blockquote> | ||
2106 | ** | ||
2107 | ** The table above makes reference to standard C library functions atoi() | ||
2108 | ** and atof(). SQLite does not really use these functions. It has its | ||
2109 | ** on equavalent internal routines. The atoi() and atof() names are | ||
2110 | ** used in the table for brevity and because they are familiar to most | ||
2111 | ** C programmers. | ||
2112 | ** | ||
2113 | ** Note that when type conversions occur, pointers returned by prior | ||
2114 | ** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or | ||
2115 | ** sqlite3_column_text16() may be invalidated. | ||
2116 | ** Type conversions and pointer invalidations might occur | ||
2117 | ** in the following cases: | ||
2118 | ** | ||
2119 | ** <ul> | ||
2120 | ** <li><p> The initial content is a BLOB and sqlite3_column_text() | ||
2121 | ** or sqlite3_column_text16() is called. A zero-terminator might | ||
2122 | ** need to be added to the string.</p></li> | ||
2123 | ** | ||
2124 | ** <li><p> The initial content is UTF-8 text and sqlite3_column_bytes16() or | ||
2125 | ** sqlite3_column_text16() is called. The content must be converted | ||
2126 | ** to UTF-16.</p></li> | ||
2127 | ** | ||
2128 | ** <li><p> The initial content is UTF-16 text and sqlite3_column_bytes() or | ||
2129 | ** sqlite3_column_text() is called. The content must be converted | ||
2130 | ** to UTF-8.</p></li> | ||
2131 | ** </ul> | ||
2132 | ** | ||
2133 | ** Conversions between UTF-16be and UTF-16le are always done in place and do | ||
2134 | ** not invalidate a prior pointer, though of course the content of the buffer | ||
2135 | ** that the prior pointer points to will have been modified. Other kinds | ||
2136 | ** of conversion are done in place when it is possible, but sometime it is | ||
2137 | ** not possible and in those cases prior pointers are invalidated. | ||
2138 | ** | ||
2139 | ** The safest and easiest to remember policy is to invoke these routines | ||
2140 | ** in one of the following ways: | ||
2141 | ** | ||
2142 | ** <ul> | ||
2143 | ** <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li> | ||
2144 | ** <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li> | ||
2145 | ** <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li> | ||
2146 | ** </ul> | ||
2147 | ** | ||
2148 | ** In other words, you should call sqlite3_column_text(), sqlite3_column_blob(), | ||
2149 | ** or sqlite3_column_text16() first to force the result into the desired | ||
2150 | ** format, then invoke sqlite3_column_bytes() or sqlite3_column_bytes16() to | ||
2151 | ** find the size of the result. Do not mix call to sqlite3_column_text() or | ||
2152 | ** sqlite3_column_blob() with calls to sqlite3_column_bytes16(). And do not | ||
2153 | ** mix calls to sqlite3_column_text16() with calls to sqlite3_column_bytes(). | ||
2154 | ** | ||
2155 | ** The pointers returned are valid until a type conversion occurs as | ||
2156 | ** described above, or until [sqlite3_step()] or [sqlite3_reset()] or | ||
2157 | ** [sqlite3_finalize()] is called. The memory space used to hold strings | ||
2158 | ** and blobs is freed automatically. Do <b>not</b> pass the pointers returned | ||
2159 | ** [sqlite3_column_blob()], [sqlite3_column_text()], etc. into | ||
2160 | ** [sqlite3_free()]. | ||
2161 | ** | ||
2162 | ** If a memory allocation error occurs during the evaluation of any | ||
2163 | ** of these routines, a default value is returned. The default value | ||
2164 | ** is either the integer 0, the floating point number 0.0, or a NULL | ||
2165 | ** pointer. Subsequent calls to [sqlite3_errcode()] will return | ||
2166 | ** [SQLITE_NOMEM]. | ||
2167 | */ | ||
2168 | const void *sqlite3_column_blob(sqlite3_stmt*, int iCol); | ||
2169 | int sqlite3_column_bytes(sqlite3_stmt*, int iCol); | ||
2170 | int sqlite3_column_bytes16(sqlite3_stmt*, int iCol); | ||
2171 | double sqlite3_column_double(sqlite3_stmt*, int iCol); | ||
2172 | int sqlite3_column_int(sqlite3_stmt*, int iCol); | ||
2173 | sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol); | ||
2174 | const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol); | ||
2175 | const void *sqlite3_column_text16(sqlite3_stmt*, int iCol); | ||
2176 | int sqlite3_column_type(sqlite3_stmt*, int iCol); | ||
2177 | sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol); | ||
2178 | |||
2179 | /* | ||
2180 | ** CAPI3REF: Destroy A Prepared Statement Object | ||
2181 | ** | ||
2182 | ** The sqlite3_finalize() function is called to delete a | ||
2183 | ** [sqlite3_stmt | compiled SQL statement]. If the statement was | ||
2184 | ** executed successfully, or not executed at all, then SQLITE_OK is returned. | ||
2185 | ** If execution of the statement failed then an | ||
2186 | ** [SQLITE_ERROR | error code] or [SQLITE_IOERR_READ | extended error code] | ||
2187 | ** is returned. | ||
2188 | ** | ||
2189 | ** This routine can be called at any point during the execution of the | ||
2190 | ** [sqlite3_stmt | virtual machine]. If the virtual machine has not | ||
2191 | ** completed execution when this routine is called, that is like | ||
2192 | ** encountering an error or an interrupt. (See [sqlite3_interrupt()].) | ||
2193 | ** Incomplete updates may be rolled back and transactions cancelled, | ||
2194 | ** depending on the circumstances, and the | ||
2195 | ** [SQLITE_ERROR | result code] returned will be [SQLITE_ABORT]. | ||
2196 | */ | ||
2197 | int sqlite3_finalize(sqlite3_stmt *pStmt); | ||
2198 | |||
2199 | /* | ||
2200 | ** CAPI3REF: Reset A Prepared Statement Object | ||
2201 | ** | ||
2202 | ** The sqlite3_reset() function is called to reset a | ||
2203 | ** [sqlite3_stmt | compiled SQL statement] object. | ||
2204 | ** back to it's initial state, ready to be re-executed. | ||
2205 | ** Any SQL statement variables that had values bound to them using | ||
2206 | ** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values. | ||
2207 | ** Use [sqlite3_clear_bindings()] to reset the bindings. | ||
2208 | */ | ||
2209 | int sqlite3_reset(sqlite3_stmt *pStmt); | ||
2210 | |||
2211 | /* | ||
2212 | ** CAPI3REF: Create Or Redefine SQL Functions | ||
2213 | ** | ||
2214 | ** The following two functions are used to add SQL functions or aggregates | ||
2215 | ** or to redefine the behavior of existing SQL functions or aggregates. The | ||
2216 | ** difference only between the two is that the second parameter, the | ||
2217 | ** name of the (scalar) function or aggregate, is encoded in UTF-8 for | ||
2218 | ** sqlite3_create_function() and UTF-16 for sqlite3_create_function16(). | ||
2219 | ** | ||
2220 | ** The first argument is the [sqlite3 | database handle] that holds the | ||
2221 | ** SQL function or aggregate is to be added or redefined. If a single | ||
2222 | ** program uses more than one database handle internally, then SQL | ||
2223 | ** functions or aggregates must be added individually to each database | ||
2224 | ** handle with which they will be used. | ||
2225 | ** | ||
2226 | ** The second parameter is the name of the SQL function to be created | ||
2227 | ** or redefined. | ||
2228 | ** The length of the name is limited to 255 bytes, exclusive of the | ||
2229 | ** zero-terminator. Note that the name length limit is in bytes, not | ||
2230 | ** characters. Any attempt to create a function with a longer name | ||
2231 | ** will result in an SQLITE_ERROR error. | ||
2232 | ** | ||
2233 | ** The third parameter is the number of arguments that the SQL function or | ||
2234 | ** aggregate takes. If this parameter is negative, then the SQL function or | ||
2235 | ** aggregate may take any number of arguments. | ||
2236 | ** | ||
2237 | ** The fourth parameter, eTextRep, specifies what | ||
2238 | ** [SQLITE_UTF8 | text encoding] this SQL function prefers for | ||
2239 | ** its parameters. Any SQL function implementation should be able to work | ||
2240 | ** work with UTF-8, UTF-16le, or UTF-16be. But some implementations may be | ||
2241 | ** more efficient with one encoding than another. It is allowed to | ||
2242 | ** invoke sqlite3_create_function() or sqlite3_create_function16() multiple | ||
2243 | ** times with the same function but with different values of eTextRep. | ||
2244 | ** When multiple implementations of the same function are available, SQLite | ||
2245 | ** will pick the one that involves the least amount of data conversion. | ||
2246 | ** If there is only a single implementation which does not care what | ||
2247 | ** text encoding is used, then the fourth argument should be | ||
2248 | ** [SQLITE_ANY]. | ||
2249 | ** | ||
2250 | ** The fifth parameter is an arbitrary pointer. The implementation | ||
2251 | ** of the function can gain access to this pointer using | ||
2252 | ** [sqlite3_user_data()]. | ||
2253 | ** | ||
2254 | ** The seventh, eighth and ninth parameters, xFunc, xStep and xFinal, are | ||
2255 | ** pointers to C-language functions that implement the SQL | ||
2256 | ** function or aggregate. A scalar SQL function requires an implementation of | ||
2257 | ** the xFunc callback only, NULL pointers should be passed as the xStep | ||
2258 | ** and xFinal parameters. An aggregate SQL function requires an implementation | ||
2259 | ** of xStep and xFinal and NULL should be passed for xFunc. To delete an | ||
2260 | ** existing SQL function or aggregate, pass NULL for all three function | ||
2261 | ** callback. | ||
2262 | ** | ||
2263 | ** It is permitted to register multiple implementations of the same | ||
2264 | ** functions with the same name but with either differing numbers of | ||
2265 | ** arguments or differing perferred text encodings. SQLite will use | ||
2266 | ** the implementation most closely matches the way in which the | ||
2267 | ** SQL function is used. | ||
2268 | */ | ||
2269 | int sqlite3_create_function( | ||
2270 | sqlite3 *, | ||
2271 | const char *zFunctionName, | ||
2272 | int nArg, | ||
2273 | int eTextRep, | ||
2274 | void*, | ||
2275 | void (*xFunc)(sqlite3_context*,int,sqlite3_value**), | ||
2276 | void (*xStep)(sqlite3_context*,int,sqlite3_value**), | ||
2277 | void (*xFinal)(sqlite3_context*) | ||
2278 | ); | ||
2279 | int sqlite3_create_function16( | ||
2280 | sqlite3*, | ||
2281 | const void *zFunctionName, | ||
2282 | int nArg, | ||
2283 | int eTextRep, | ||
2284 | void*, | ||
2285 | void (*xFunc)(sqlite3_context*,int,sqlite3_value**), | ||
2286 | void (*xStep)(sqlite3_context*,int,sqlite3_value**), | ||
2287 | void (*xFinal)(sqlite3_context*) | ||
2288 | ); | ||
2289 | |||
2290 | /* | ||
2291 | ** CAPI3REF: Text Encodings | ||
2292 | ** | ||
2293 | ** These constant define integer codes that represent the various | ||
2294 | ** text encodings supported by SQLite. | ||
2295 | */ | ||
2296 | #define SQLITE_UTF8 1 | ||
2297 | #define SQLITE_UTF16LE 2 | ||
2298 | #define SQLITE_UTF16BE 3 | ||
2299 | #define SQLITE_UTF16 4 /* Use native byte order */ | ||
2300 | #define SQLITE_ANY 5 /* sqlite3_create_function only */ | ||
2301 | #define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */ | ||
2302 | |||
2303 | /* | ||
2304 | ** CAPI3REF: Obsolete Functions | ||
2305 | ** | ||
2306 | ** These functions are all now obsolete. In order to maintain | ||
2307 | ** backwards compatibility with older code, we continue to support | ||
2308 | ** these functions. However, new development projects should avoid | ||
2309 | ** the use of these functions. To help encourage people to avoid | ||
2310 | ** using these functions, we are not going to tell you want they do. | ||
2311 | */ | ||
2312 | int sqlite3_aggregate_count(sqlite3_context*); | ||
2313 | int sqlite3_expired(sqlite3_stmt*); | ||
2314 | int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*); | ||
2315 | int sqlite3_global_recover(void); | ||
2316 | void sqlite3_thread_cleanup(void); | ||
2317 | |||
2318 | /* | ||
2319 | ** CAPI3REF: Obtaining SQL Function Parameter Values | ||
2320 | ** | ||
2321 | ** The C-language implementation of SQL functions and aggregates uses | ||
2322 | ** this set of interface routines to access the parameter values on | ||
2323 | ** the function or aggregate. | ||
2324 | ** | ||
2325 | ** The xFunc (for scalar functions) or xStep (for aggregates) parameters | ||
2326 | ** to [sqlite3_create_function()] and [sqlite3_create_function16()] | ||
2327 | ** define callbacks that implement the SQL functions and aggregates. | ||
2328 | ** The 4th parameter to these callbacks is an array of pointers to | ||
2329 | ** [sqlite3_value] objects. There is one [sqlite3_value] object for | ||
2330 | ** each parameter to the SQL function. These routines are used to | ||
2331 | ** extract values from the [sqlite3_value] objects. | ||
2332 | ** | ||
2333 | ** These routines work just like the corresponding | ||
2334 | ** [sqlite3_column_blob | sqlite3_column_* routines] except that | ||
2335 | ** these routines take a single [sqlite3_value*] pointer instead | ||
2336 | ** of an [sqlite3_stmt*] pointer and an integer column number. | ||
2337 | ** | ||
2338 | ** The sqlite3_value_text16() interface extracts a UTF16 string | ||
2339 | ** in the native byte-order of the host machine. The | ||
2340 | ** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces | ||
2341 | ** extract UTF16 strings as big-endian and little-endian respectively. | ||
2342 | ** | ||
2343 | ** The sqlite3_value_numeric_type() interface attempts to apply | ||
2344 | ** numeric affinity to the value. This means that an attempt is | ||
2345 | ** made to convert the value to an integer or floating point. If | ||
2346 | ** such a conversion is possible without loss of information (in order | ||
2347 | ** words if the value is original a string that looks like a number) | ||
2348 | ** then it is done. Otherwise no conversion occurs. The | ||
2349 | ** [SQLITE_INTEGER | datatype] after conversion is returned. | ||
2350 | ** | ||
2351 | ** Please pay particular attention to the fact that the pointer that | ||
2352 | ** is returned from [sqlite3_value_blob()], [sqlite3_value_text()], or | ||
2353 | ** [sqlite3_value_text16()] can be invalidated by a subsequent call to | ||
2354 | ** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()], | ||
2355 | ** or [sqlite3_value_text16()]. | ||
2356 | ** | ||
2357 | ** These routines must be called from the same thread as | ||
2358 | ** the SQL function that supplied the sqlite3_value* parameters. | ||
2359 | ** Or, if the sqlite3_value* argument comes from the [sqlite3_column_value()] | ||
2360 | ** interface, then these routines should be called from the same thread | ||
2361 | ** that ran [sqlite3_column_value()]. | ||
2362 | */ | ||
2363 | const void *sqlite3_value_blob(sqlite3_value*); | ||
2364 | int sqlite3_value_bytes(sqlite3_value*); | ||
2365 | int sqlite3_value_bytes16(sqlite3_value*); | ||
2366 | double sqlite3_value_double(sqlite3_value*); | ||
2367 | int sqlite3_value_int(sqlite3_value*); | ||
2368 | sqlite3_int64 sqlite3_value_int64(sqlite3_value*); | ||
2369 | const unsigned char *sqlite3_value_text(sqlite3_value*); | ||
2370 | const void *sqlite3_value_text16(sqlite3_value*); | ||
2371 | const void *sqlite3_value_text16le(sqlite3_value*); | ||
2372 | const void *sqlite3_value_text16be(sqlite3_value*); | ||
2373 | int sqlite3_value_type(sqlite3_value*); | ||
2374 | int sqlite3_value_numeric_type(sqlite3_value*); | ||
2375 | |||
2376 | /* | ||
2377 | ** CAPI3REF: Obtain Aggregate Function Context | ||
2378 | ** | ||
2379 | ** The implementation of aggregate SQL functions use this routine to allocate | ||
2380 | ** a structure for storing their state. The first time this routine | ||
2381 | ** is called for a particular aggregate, a new structure of size nBytes | ||
2382 | ** is allocated, zeroed, and returned. On subsequent calls (for the | ||
2383 | ** same aggregate instance) the same buffer is returned. The implementation | ||
2384 | ** of the aggregate can use the returned buffer to accumulate data. | ||
2385 | ** | ||
2386 | ** The buffer allocated is freed automatically by SQLite whan the aggregate | ||
2387 | ** query concludes. | ||
2388 | ** | ||
2389 | ** The first parameter should be a copy of the | ||
2390 | ** [sqlite3_context | SQL function context] that is the first | ||
2391 | ** parameter to the callback routine that implements the aggregate | ||
2392 | ** function. | ||
2393 | ** | ||
2394 | ** This routine must be called from the same thread in which | ||
2395 | ** the aggregate SQL function is running. | ||
2396 | */ | ||
2397 | void *sqlite3_aggregate_context(sqlite3_context*, int nBytes); | ||
2398 | |||
2399 | /* | ||
2400 | ** CAPI3REF: User Data For Functions | ||
2401 | ** | ||
2402 | ** The pUserData parameter to the [sqlite3_create_function()] | ||
2403 | ** and [sqlite3_create_function16()] routines | ||
2404 | ** used to register user functions is available to | ||
2405 | ** the implementation of the function using this call. | ||
2406 | ** | ||
2407 | ** This routine must be called from the same thread in which | ||
2408 | ** the SQL function is running. | ||
2409 | */ | ||
2410 | void *sqlite3_user_data(sqlite3_context*); | ||
2411 | |||
2412 | /* | ||
2413 | ** CAPI3REF: Function Auxiliary Data | ||
2414 | ** | ||
2415 | ** The following two functions may be used by scalar SQL functions to | ||
2416 | ** associate meta-data with argument values. If the same value is passed to | ||
2417 | ** multiple invocations of the same SQL function during query execution, under | ||
2418 | ** some circumstances the associated meta-data may be preserved. This may | ||
2419 | ** be used, for example, to add a regular-expression matching scalar | ||
2420 | ** function. The compiled version of the regular expression is stored as | ||
2421 | ** meta-data associated with the SQL value passed as the regular expression | ||
2422 | ** pattern. The compiled regular expression can be reused on multiple | ||
2423 | ** invocations of the same function so that the original pattern string | ||
2424 | ** does not need to be recompiled on each invocation. | ||
2425 | ** | ||
2426 | ** The sqlite3_get_auxdata() interface returns a pointer to the meta-data | ||
2427 | ** associated with the Nth argument value to the current SQL function | ||
2428 | ** call, where N is the second parameter. If no meta-data has been set for | ||
2429 | ** that value, then a NULL pointer is returned. | ||
2430 | ** | ||
2431 | ** The sqlite3_set_auxdata() is used to associate meta-data with an SQL | ||
2432 | ** function argument. The third parameter is a pointer to the meta-data | ||
2433 | ** to be associated with the Nth user function argument value. The fourth | ||
2434 | ** parameter specifies a destructor that will be called on the meta- | ||
2435 | ** data pointer to release it when it is no longer required. If the | ||
2436 | ** destructor is NULL, it is not invoked. | ||
2437 | ** | ||
2438 | ** In practice, meta-data is preserved between function calls for | ||
2439 | ** expressions that are constant at compile time. This includes literal | ||
2440 | ** values and SQL variables. | ||
2441 | ** | ||
2442 | ** These routines must be called from the same thread in which | ||
2443 | ** the SQL function is running. | ||
2444 | */ | ||
2445 | void *sqlite3_get_auxdata(sqlite3_context*, int); | ||
2446 | void sqlite3_set_auxdata(sqlite3_context*, int, void*, void (*)(void*)); | ||
2447 | |||
2448 | |||
2449 | /* | ||
2450 | ** CAPI3REF: Constants Defining Special Destructor Behavior | ||
2451 | ** | ||
2452 | ** These are special value for the destructor that is passed in as the | ||
2453 | ** final argument to routines like [sqlite3_result_blob()]. If the destructor | ||
2454 | ** argument is SQLITE_STATIC, it means that the content pointer is constant | ||
2455 | ** and will never change. It does not need to be destroyed. The | ||
2456 | ** SQLITE_TRANSIENT value means that the content will likely change in | ||
2457 | ** the near future and that SQLite should make its own private copy of | ||
2458 | ** the content before returning. | ||
2459 | ** | ||
2460 | ** The typedef is necessary to work around problems in certain | ||
2461 | ** C++ compilers. See ticket #2191. | ||
2462 | */ | ||
2463 | typedef void (*sqlite3_destructor_type)(void*); | ||
2464 | #define SQLITE_STATIC ((sqlite3_destructor_type)0) | ||
2465 | #define SQLITE_TRANSIENT ((sqlite3_destructor_type)-1) | ||
2466 | |||
2467 | /* | ||
2468 | ** CAPI3REF: Setting The Result Of An SQL Function | ||
2469 | ** | ||
2470 | ** These routines are used by the xFunc or xFinal callbacks that | ||
2471 | ** implement SQL functions and aggregates. See | ||
2472 | ** [sqlite3_create_function()] and [sqlite3_create_function16()] | ||
2473 | ** for additional information. | ||
2474 | ** | ||
2475 | ** These functions work very much like the | ||
2476 | ** [sqlite3_bind_blob | sqlite3_bind_*] family of functions used | ||
2477 | ** to bind values to host parameters in prepared statements. | ||
2478 | ** Refer to the | ||
2479 | ** [sqlite3_bind_blob | sqlite3_bind_* documentation] for | ||
2480 | ** additional information. | ||
2481 | ** | ||
2482 | ** The sqlite3_result_error() and sqlite3_result_error16() functions | ||
2483 | ** cause the implemented SQL function to throw an exception. The | ||
2484 | ** parameter to sqlite3_result_error() or sqlite3_result_error16() | ||
2485 | ** is the text of an error message. | ||
2486 | ** | ||
2487 | ** The sqlite3_result_toobig() cause the function implementation | ||
2488 | ** to throw and error indicating that a string or BLOB is to long | ||
2489 | ** to represent. | ||
2490 | ** | ||
2491 | ** These routines must be called from within the same thread as | ||
2492 | ** the SQL function associated with the [sqlite3_context] pointer. | ||
2493 | */ | ||
2494 | void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*)); | ||
2495 | void sqlite3_result_double(sqlite3_context*, double); | ||
2496 | void sqlite3_result_error(sqlite3_context*, const char*, int); | ||
2497 | void sqlite3_result_error16(sqlite3_context*, const void*, int); | ||
2498 | void sqlite3_result_error_toobig(sqlite3_context*); | ||
2499 | void sqlite3_result_error_nomem(sqlite3_context*); | ||
2500 | void sqlite3_result_int(sqlite3_context*, int); | ||
2501 | void sqlite3_result_int64(sqlite3_context*, sqlite3_int64); | ||
2502 | void sqlite3_result_null(sqlite3_context*); | ||
2503 | void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*)); | ||
2504 | void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*)); | ||
2505 | void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*)); | ||
2506 | void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*)); | ||
2507 | void sqlite3_result_value(sqlite3_context*, sqlite3_value*); | ||
2508 | void sqlite3_result_zeroblob(sqlite3_context*, int n); | ||
2509 | |||
2510 | /* | ||
2511 | ** CAPI3REF: Define New Collating Sequences | ||
2512 | ** | ||
2513 | ** These functions are used to add new collation sequences to the | ||
2514 | ** [sqlite3*] handle specified as the first argument. | ||
2515 | ** | ||
2516 | ** The name of the new collation sequence is specified as a UTF-8 string | ||
2517 | ** for sqlite3_create_collation() and sqlite3_create_collation_v2() | ||
2518 | ** and a UTF-16 string for sqlite3_create_collation16(). In all cases | ||
2519 | ** the name is passed as the second function argument. | ||
2520 | ** | ||
2521 | ** The third argument must be one of the constants [SQLITE_UTF8], | ||
2522 | ** [SQLITE_UTF16LE] or [SQLITE_UTF16BE], indicating that the user-supplied | ||
2523 | ** routine expects to be passed pointers to strings encoded using UTF-8, | ||
2524 | ** UTF-16 little-endian or UTF-16 big-endian respectively. | ||
2525 | ** | ||
2526 | ** A pointer to the user supplied routine must be passed as the fifth | ||
2527 | ** argument. If it is NULL, this is the same as deleting the collation | ||
2528 | ** sequence (so that SQLite cannot call it anymore). Each time the user | ||
2529 | ** supplied function is invoked, it is passed a copy of the void* passed as | ||
2530 | ** the fourth argument to sqlite3_create_collation() or | ||
2531 | ** sqlite3_create_collation16() as its first parameter. | ||
2532 | ** | ||
2533 | ** The remaining arguments to the user-supplied routine are two strings, | ||
2534 | ** each represented by a [length, data] pair and encoded in the encoding | ||
2535 | ** that was passed as the third argument when the collation sequence was | ||
2536 | ** registered. The user routine should return negative, zero or positive if | ||
2537 | ** the first string is less than, equal to, or greater than the second | ||
2538 | ** string. i.e. (STRING1 - STRING2). | ||
2539 | ** | ||
2540 | ** The sqlite3_create_collation_v2() works like sqlite3_create_collation() | ||
2541 | ** excapt that it takes an extra argument which is a destructor for | ||
2542 | ** the collation. The destructor is called when the collation is | ||
2543 | ** destroyed and is passed a copy of the fourth parameter void* pointer | ||
2544 | ** of the sqlite3_create_collation_v2(). Collations are destroyed when | ||
2545 | ** they are overridden by later calls to the collation creation functions | ||
2546 | ** or when the [sqlite3*] database handle is closed using [sqlite3_close()]. | ||
2547 | ** | ||
2548 | ** The sqlite3_create_collation_v2() interface is experimental and | ||
2549 | ** subject to change in future releases. The other collation creation | ||
2550 | ** functions are stable. | ||
2551 | */ | ||
2552 | int sqlite3_create_collation( | ||
2553 | sqlite3*, | ||
2554 | const char *zName, | ||
2555 | int eTextRep, | ||
2556 | void*, | ||
2557 | int(*xCompare)(void*,int,const void*,int,const void*) | ||
2558 | ); | ||
2559 | int sqlite3_create_collation_v2( | ||
2560 | sqlite3*, | ||
2561 | const char *zName, | ||
2562 | int eTextRep, | ||
2563 | void*, | ||
2564 | int(*xCompare)(void*,int,const void*,int,const void*), | ||
2565 | void(*xDestroy)(void*) | ||
2566 | ); | ||
2567 | int sqlite3_create_collation16( | ||
2568 | sqlite3*, | ||
2569 | const char *zName, | ||
2570 | int eTextRep, | ||
2571 | void*, | ||
2572 | int(*xCompare)(void*,int,const void*,int,const void*) | ||
2573 | ); | ||
2574 | |||
2575 | /* | ||
2576 | ** CAPI3REF: Collation Needed Callbacks | ||
2577 | ** | ||
2578 | ** To avoid having to register all collation sequences before a database | ||
2579 | ** can be used, a single callback function may be registered with the | ||
2580 | ** database handle to be called whenever an undefined collation sequence is | ||
2581 | ** required. | ||
2582 | ** | ||
2583 | ** If the function is registered using the sqlite3_collation_needed() API, | ||
2584 | ** then it is passed the names of undefined collation sequences as strings | ||
2585 | ** encoded in UTF-8. If sqlite3_collation_needed16() is used, the names | ||
2586 | ** are passed as UTF-16 in machine native byte order. A call to either | ||
2587 | ** function replaces any existing callback. | ||
2588 | ** | ||
2589 | ** When the callback is invoked, the first argument passed is a copy | ||
2590 | ** of the second argument to sqlite3_collation_needed() or | ||
2591 | ** sqlite3_collation_needed16(). The second argument is the database | ||
2592 | ** handle. The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE], or | ||
2593 | ** [SQLITE_UTF16LE], indicating the most desirable form of the collation | ||
2594 | ** sequence function required. The fourth parameter is the name of the | ||
2595 | ** required collation sequence. | ||
2596 | ** | ||
2597 | ** The callback function should register the desired collation using | ||
2598 | ** [sqlite3_create_collation()], [sqlite3_create_collation16()], or | ||
2599 | ** [sqlite3_create_collation_v2()]. | ||
2600 | */ | ||
2601 | int sqlite3_collation_needed( | ||
2602 | sqlite3*, | ||
2603 | void*, | ||
2604 | void(*)(void*,sqlite3*,int eTextRep,const char*) | ||
2605 | ); | ||
2606 | int sqlite3_collation_needed16( | ||
2607 | sqlite3*, | ||
2608 | void*, | ||
2609 | void(*)(void*,sqlite3*,int eTextRep,const void*) | ||
2610 | ); | ||
2611 | |||
2612 | /* | ||
2613 | ** Specify the key for an encrypted database. This routine should be | ||
2614 | ** called right after sqlite3_open(). | ||
2615 | ** | ||
2616 | ** The code to implement this API is not available in the public release | ||
2617 | ** of SQLite. | ||
2618 | */ | ||
2619 | int sqlite3_key( | ||
2620 | sqlite3 *db, /* Database to be rekeyed */ | ||
2621 | const void *pKey, int nKey /* The key */ | ||
2622 | ); | ||
2623 | |||
2624 | /* | ||
2625 | ** Change the key on an open database. If the current database is not | ||
2626 | ** encrypted, this routine will encrypt it. If pNew==0 or nNew==0, the | ||
2627 | ** database is decrypted. | ||
2628 | ** | ||
2629 | ** The code to implement this API is not available in the public release | ||
2630 | ** of SQLite. | ||
2631 | */ | ||
2632 | int sqlite3_rekey( | ||
2633 | sqlite3 *db, /* Database to be rekeyed */ | ||
2634 | const void *pKey, int nKey /* The new key */ | ||
2635 | ); | ||
2636 | |||
2637 | /* | ||
2638 | ** CAPI3REF: Suspend Execution For A Short Time | ||
2639 | ** | ||
2640 | ** This function causes the current thread to suspend execution | ||
2641 | ** a number of milliseconds specified in its parameter. | ||
2642 | ** | ||
2643 | ** If the operating system does not support sleep requests with | ||
2644 | ** millisecond time resolution, then the time will be rounded up to | ||
2645 | ** the nearest second. The number of milliseconds of sleep actually | ||
2646 | ** requested from the operating system is returned. | ||
2647 | ** | ||
2648 | ** SQLite implements this interface by calling the xSleep() | ||
2649 | ** method of the default [sqlite3_vfs] object. | ||
2650 | */ | ||
2651 | int sqlite3_sleep(int); | ||
2652 | |||
2653 | /* | ||
2654 | ** CAPI3REF: Name Of The Folder Holding Temporary Files | ||
2655 | ** | ||
2656 | ** If this global variable is made to point to a string which is | ||
2657 | ** the name of a folder (a.ka. directory), then all temporary files | ||
2658 | ** created by SQLite will be placed in that directory. If this variable | ||
2659 | ** is NULL pointer, then SQLite does a search for an appropriate temporary | ||
2660 | ** file directory. | ||
2661 | ** | ||
2662 | ** It is not safe to modify this variable once a database connection | ||
2663 | ** has been opened. It is intended that this variable be set once | ||
2664 | ** as part of process initialization and before any SQLite interface | ||
2665 | ** routines have been call and remain unchanged thereafter. | ||
2666 | */ | ||
2667 | SQLITE_EXTERN char *sqlite3_temp_directory; | ||
2668 | |||
2669 | /* | ||
2670 | ** CAPI3REF: Test To See If The Database Is In Auto-Commit Mode | ||
2671 | ** | ||
2672 | ** Test to see whether or not the database connection is in autocommit | ||
2673 | ** mode. Return TRUE if it is and FALSE if not. Autocommit mode is on | ||
2674 | ** by default. Autocommit is disabled by a BEGIN statement and reenabled | ||
2675 | ** by the next COMMIT or ROLLBACK. | ||
2676 | ** | ||
2677 | ** If certain kinds of errors occur on a statement within a multi-statement | ||
2678 | ** transactions (errors including [SQLITE_FULL], [SQLITE_IOERR], | ||
2679 | ** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the | ||
2680 | ** transaction might be rolled back automatically. The only way to | ||
2681 | ** find out if SQLite automatically rolled back the transaction after | ||
2682 | ** an error is to use this function. | ||
2683 | ** | ||
2684 | ** If another thread changes the autocommit status of the database | ||
2685 | ** connection while this routine is running, then the return value | ||
2686 | ** is undefined. | ||
2687 | */ | ||
2688 | int sqlite3_get_autocommit(sqlite3*); | ||
2689 | |||
2690 | /* | ||
2691 | ** CAPI3REF: Find The Database Handle Associated With A Prepared Statement | ||
2692 | ** | ||
2693 | ** Return the [sqlite3*] database handle to which a | ||
2694 | ** [sqlite3_stmt | prepared statement] belongs. | ||
2695 | ** This is the same database handle that was | ||
2696 | ** the first argument to the [sqlite3_prepare_v2()] or its variants | ||
2697 | ** that was used to create the statement in the first place. | ||
2698 | */ | ||
2699 | sqlite3 *sqlite3_db_handle(sqlite3_stmt*); | ||
2700 | |||
2701 | |||
2702 | /* | ||
2703 | ** CAPI3REF: Commit And Rollback Notification Callbacks | ||
2704 | ** | ||
2705 | ** These routines | ||
2706 | ** register callback functions to be invoked whenever a transaction | ||
2707 | ** is committed or rolled back. The pArg argument is passed through | ||
2708 | ** to the callback. If the callback on a commit hook function | ||
2709 | ** returns non-zero, then the commit is converted into a rollback. | ||
2710 | ** | ||
2711 | ** If another function was previously registered, its pArg value is returned. | ||
2712 | ** Otherwise NULL is returned. | ||
2713 | ** | ||
2714 | ** Registering a NULL function disables the callback. | ||
2715 | ** | ||
2716 | ** For the purposes of this API, a transaction is said to have been | ||
2717 | ** rolled back if an explicit "ROLLBACK" statement is executed, or | ||
2718 | ** an error or constraint causes an implicit rollback to occur. The | ||
2719 | ** callback is not invoked if a transaction is automatically rolled | ||
2720 | ** back because the database connection is closed. | ||
2721 | ** | ||
2722 | ** These are experimental interfaces and are subject to change. | ||
2723 | */ | ||
2724 | void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*); | ||
2725 | void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*); | ||
2726 | |||
2727 | /* | ||
2728 | ** CAPI3REF: Data Change Notification Callbacks | ||
2729 | ** | ||
2730 | ** Register a callback function with the database connection identified by the | ||
2731 | ** first argument to be invoked whenever a row is updated, inserted or deleted. | ||
2732 | ** Any callback set by a previous call to this function for the same | ||
2733 | ** database connection is overridden. | ||
2734 | ** | ||
2735 | ** The second argument is a pointer to the function to invoke when a | ||
2736 | ** row is updated, inserted or deleted. The first argument to the callback is | ||
2737 | ** a copy of the third argument to sqlite3_update_hook(). The second callback | ||
2738 | ** argument is one of SQLITE_INSERT, SQLITE_DELETE or SQLITE_UPDATE, depending | ||
2739 | ** on the operation that caused the callback to be invoked. The third and | ||
2740 | ** fourth arguments to the callback contain pointers to the database and | ||
2741 | ** table name containing the affected row. The final callback parameter is | ||
2742 | ** the rowid of the row. In the case of an update, this is the rowid after | ||
2743 | ** the update takes place. | ||
2744 | ** | ||
2745 | ** The update hook is not invoked when internal system tables are | ||
2746 | ** modified (i.e. sqlite_master and sqlite_sequence). | ||
2747 | ** | ||
2748 | ** If another function was previously registered, its pArg value is returned. | ||
2749 | ** Otherwise NULL is returned. | ||
2750 | */ | ||
2751 | void *sqlite3_update_hook( | ||
2752 | sqlite3*, | ||
2753 | void(*)(void *,int ,char const *,char const *,sqlite3_int64), | ||
2754 | void* | ||
2755 | ); | ||
2756 | |||
2757 | /* | ||
2758 | ** CAPI3REF: Enable Or Disable Shared Pager Cache | ||
2759 | ** | ||
2760 | ** This routine enables or disables the sharing of the database cache | ||
2761 | ** and schema data structures between connections to the same database. | ||
2762 | ** Sharing is enabled if the argument is true and disabled if the argument | ||
2763 | ** is false. | ||
2764 | ** | ||
2765 | ** Beginning in SQLite version 3.5.0, cache sharing is enabled and disabled | ||
2766 | ** for an entire process. In prior versions of SQLite, sharing was | ||
2767 | ** enabled or disabled for each thread separately. | ||
2768 | ** | ||
2769 | ** The cache sharing mode set by this interface effects all subsequent | ||
2770 | ** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()]. | ||
2771 | ** Existing database connections continue use the sharing mode that was | ||
2772 | ** in effect at the time they were opened. | ||
2773 | ** | ||
2774 | ** Virtual tables cannot be used with a shared cache. When shared | ||
2775 | ** cache is enabled, the [sqlite3_create_module()] API used to register | ||
2776 | ** virtual tables will always return an error. | ||
2777 | ** | ||
2778 | ** This routine returns [SQLITE_OK] if shared cache was | ||
2779 | ** enabled or disabled successfully. An [SQLITE_ERROR | error code] | ||
2780 | ** is returned otherwise. | ||
2781 | ** | ||
2782 | ** Shared cache is disabled by default. But this might change in | ||
2783 | ** future releases of SQLite. Applications that care about shared | ||
2784 | ** cache setting should set it explicitly. | ||
2785 | */ | ||
2786 | int sqlite3_enable_shared_cache(int); | ||
2787 | |||
2788 | /* | ||
2789 | ** CAPI3REF: Attempt To Free Heap Memory | ||
2790 | ** | ||
2791 | ** Attempt to free N bytes of heap memory by deallocating non-essential | ||
2792 | ** memory allocations held by the database library (example: memory | ||
2793 | ** used to cache database pages to improve performance). | ||
2794 | */ | ||
2795 | int sqlite3_release_memory(int); | ||
2796 | |||
2797 | /* | ||
2798 | ** CAPI3REF: Impose A Limit On Heap Size | ||
2799 | ** | ||
2800 | ** Place a "soft" limit on the amount of heap memory that may be allocated | ||
2801 | ** by SQLite. If an internal allocation is requested | ||
2802 | ** that would exceed the specified limit, [sqlite3_release_memory()] is | ||
2803 | ** invoked one or more times to free up some space before the allocation | ||
2804 | ** is made. | ||
2805 | ** | ||
2806 | ** The limit is called "soft", because if [sqlite3_release_memory()] cannot | ||
2807 | ** free sufficient memory to prevent the limit from being exceeded, | ||
2808 | ** the memory is allocated anyway and the current operation proceeds. | ||
2809 | ** | ||
2810 | ** A negative or zero value for N means that there is no soft heap limit and | ||
2811 | ** [sqlite3_release_memory()] will only be called when memory is exhausted. | ||
2812 | ** The default value for the soft heap limit is zero. | ||
2813 | ** | ||
2814 | ** SQLite makes a best effort to honor the soft heap limit. But if it | ||
2815 | ** is unable to reduce memory usage below the soft limit, execution will | ||
2816 | ** continue without error or notification. This is why the limit is | ||
2817 | ** called a "soft" limit. It is advisory only. | ||
2818 | ** | ||
2819 | ** The soft heap limit is implemented using the [sqlite3_memory_alarm()] | ||
2820 | ** interface. Only a single memory alarm is available in the default | ||
2821 | ** implementation. This means that if the application also uses the | ||
2822 | ** memory alarm interface it will interfere with the operation of the | ||
2823 | ** soft heap limit and undefined behavior will result. | ||
2824 | ** | ||
2825 | ** Prior to SQLite version 3.5.0, this routine only constrained the memory | ||
2826 | ** allocated by a single thread - the same thread in which this routine | ||
2827 | ** runs. Beginning with SQLite version 3.5.0, the soft heap limit is | ||
2828 | ** applied to all threads. The value specified for the soft heap limit | ||
2829 | ** is an upper bound on the total memory allocation for all threads. In | ||
2830 | ** version 3.5.0 there is no mechanism for limiting the heap usage for | ||
2831 | ** individual threads. | ||
2832 | */ | ||
2833 | void sqlite3_soft_heap_limit(int); | ||
2834 | |||
2835 | /* | ||
2836 | ** CAPI3REF: Extract Metadata About A Column Of A Table | ||
2837 | ** | ||
2838 | ** This routine | ||
2839 | ** returns meta-data about a specific column of a specific database | ||
2840 | ** table accessible using the connection handle passed as the first function | ||
2841 | ** argument. | ||
2842 | ** | ||
2843 | ** The column is identified by the second, third and fourth parameters to | ||
2844 | ** this function. The second parameter is either the name of the database | ||
2845 | ** (i.e. "main", "temp" or an attached database) containing the specified | ||
2846 | ** table or NULL. If it is NULL, then all attached databases are searched | ||
2847 | ** for the table using the same algorithm as the database engine uses to | ||
2848 | ** resolve unqualified table references. | ||
2849 | ** | ||
2850 | ** The third and fourth parameters to this function are the table and column | ||
2851 | ** name of the desired column, respectively. Neither of these parameters | ||
2852 | ** may be NULL. | ||
2853 | ** | ||
2854 | ** Meta information is returned by writing to the memory locations passed as | ||
2855 | ** the 5th and subsequent parameters to this function. Any of these | ||
2856 | ** arguments may be NULL, in which case the corresponding element of meta | ||
2857 | ** information is ommitted. | ||
2858 | ** | ||
2859 | ** <pre> | ||
2860 | ** Parameter Output Type Description | ||
2861 | ** ----------------------------------- | ||
2862 | ** | ||
2863 | ** 5th const char* Data type | ||
2864 | ** 6th const char* Name of the default collation sequence | ||
2865 | ** 7th int True if the column has a NOT NULL constraint | ||
2866 | ** 8th int True if the column is part of the PRIMARY KEY | ||
2867 | ** 9th int True if the column is AUTOINCREMENT | ||
2868 | ** </pre> | ||
2869 | ** | ||
2870 | ** | ||
2871 | ** The memory pointed to by the character pointers returned for the | ||
2872 | ** declaration type and collation sequence is valid only until the next | ||
2873 | ** call to any sqlite API function. | ||
2874 | ** | ||
2875 | ** If the specified table is actually a view, then an error is returned. | ||
2876 | ** | ||
2877 | ** If the specified column is "rowid", "oid" or "_rowid_" and an | ||
2878 | ** INTEGER PRIMARY KEY column has been explicitly declared, then the output | ||
2879 | ** parameters are set for the explicitly declared column. If there is no | ||
2880 | ** explicitly declared IPK column, then the output parameters are set as | ||
2881 | ** follows: | ||
2882 | ** | ||
2883 | ** <pre> | ||
2884 | ** data type: "INTEGER" | ||
2885 | ** collation sequence: "BINARY" | ||
2886 | ** not null: 0 | ||
2887 | ** primary key: 1 | ||
2888 | ** auto increment: 0 | ||
2889 | ** </pre> | ||
2890 | ** | ||
2891 | ** This function may load one or more schemas from database files. If an | ||
2892 | ** error occurs during this process, or if the requested table or column | ||
2893 | ** cannot be found, an SQLITE error code is returned and an error message | ||
2894 | ** left in the database handle (to be retrieved using sqlite3_errmsg()). | ||
2895 | ** | ||
2896 | ** This API is only available if the library was compiled with the | ||
2897 | ** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined. | ||
2898 | */ | ||
2899 | int sqlite3_table_column_metadata( | ||
2900 | sqlite3 *db, /* Connection handle */ | ||
2901 | const char *zDbName, /* Database name or NULL */ | ||
2902 | const char *zTableName, /* Table name */ | ||
2903 | const char *zColumnName, /* Column name */ | ||
2904 | char const **pzDataType, /* OUTPUT: Declared data type */ | ||
2905 | char const **pzCollSeq, /* OUTPUT: Collation sequence name */ | ||
2906 | int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */ | ||
2907 | int *pPrimaryKey, /* OUTPUT: True if column part of PK */ | ||
2908 | int *pAutoinc /* OUTPUT: True if column is auto-increment */ | ||
2909 | ); | ||
2910 | |||
2911 | /* | ||
2912 | ** CAPI3REF: Load An Extension | ||
2913 | ** | ||
2914 | ** Attempt to load an SQLite extension library contained in the file | ||
2915 | ** zFile. The entry point is zProc. zProc may be 0 in which case the | ||
2916 | ** name of the entry point defaults to "sqlite3_extension_init". | ||
2917 | ** | ||
2918 | ** Return [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong. | ||
2919 | ** | ||
2920 | ** If an error occurs and pzErrMsg is not 0, then fill *pzErrMsg with | ||
2921 | ** error message text. The calling function should free this memory | ||
2922 | ** by calling [sqlite3_free()]. | ||
2923 | ** | ||
2924 | ** Extension loading must be enabled using [sqlite3_enable_load_extension()] | ||
2925 | ** prior to calling this API or an error will be returned. | ||
2926 | */ | ||
2927 | int sqlite3_load_extension( | ||
2928 | sqlite3 *db, /* Load the extension into this database connection */ | ||
2929 | const char *zFile, /* Name of the shared library containing extension */ | ||
2930 | const char *zProc, /* Entry point. Derived from zFile if 0 */ | ||
2931 | char **pzErrMsg /* Put error message here if not 0 */ | ||
2932 | ); | ||
2933 | |||
2934 | /* | ||
2935 | ** CAPI3REF: Enable Or Disable Extension Loading | ||
2936 | ** | ||
2937 | ** So as not to open security holes in older applications that are | ||
2938 | ** unprepared to deal with extension loading, and as a means of disabling | ||
2939 | ** extension loading while evaluating user-entered SQL, the following | ||
2940 | ** API is provided to turn the [sqlite3_load_extension()] mechanism on and | ||
2941 | ** off. It is off by default. See ticket #1863. | ||
2942 | ** | ||
2943 | ** Call this routine with onoff==1 to turn extension loading on | ||
2944 | ** and call it with onoff==0 to turn it back off again. | ||
2945 | */ | ||
2946 | int sqlite3_enable_load_extension(sqlite3 *db, int onoff); | ||
2947 | |||
2948 | /* | ||
2949 | ** CAPI3REF: Make Arrangements To Automatically Load An Extension | ||
2950 | ** | ||
2951 | ** Register an extension entry point that is automatically invoked | ||
2952 | ** whenever a new database connection is opened using | ||
2953 | ** [sqlite3_open()], [sqlite3_open16()], or [sqlite3_open_v2()]. | ||
2954 | ** | ||
2955 | ** This API can be invoked at program startup in order to register | ||
2956 | ** one or more statically linked extensions that will be available | ||
2957 | ** to all new database connections. | ||
2958 | ** | ||
2959 | ** Duplicate extensions are detected so calling this routine multiple | ||
2960 | ** times with the same extension is harmless. | ||
2961 | ** | ||
2962 | ** This routine stores a pointer to the extension in an array | ||
2963 | ** that is obtained from malloc(). If you run a memory leak | ||
2964 | ** checker on your program and it reports a leak because of this | ||
2965 | ** array, then invoke [sqlite3_automatic_extension_reset()] prior | ||
2966 | ** to shutdown to free the memory. | ||
2967 | ** | ||
2968 | ** Automatic extensions apply across all threads. | ||
2969 | ** | ||
2970 | ** This interface is experimental and is subject to change or | ||
2971 | ** removal in future releases of SQLite. | ||
2972 | */ | ||
2973 | int sqlite3_auto_extension(void *xEntryPoint); | ||
2974 | |||
2975 | |||
2976 | /* | ||
2977 | ** CAPI3REF: Reset Automatic Extension Loading | ||
2978 | ** | ||
2979 | ** Disable all previously registered automatic extensions. This | ||
2980 | ** routine undoes the effect of all prior [sqlite3_automatic_extension()] | ||
2981 | ** calls. | ||
2982 | ** | ||
2983 | ** This call disabled automatic extensions in all threads. | ||
2984 | ** | ||
2985 | ** This interface is experimental and is subject to change or | ||
2986 | ** removal in future releases of SQLite. | ||
2987 | */ | ||
2988 | void sqlite3_reset_auto_extension(void); | ||
2989 | |||
2990 | |||
2991 | /* | ||
2992 | ****** EXPERIMENTAL - subject to change without notice ************** | ||
2993 | ** | ||
2994 | ** The interface to the virtual-table mechanism is currently considered | ||
2995 | ** to be experimental. The interface might change in incompatible ways. | ||
2996 | ** If this is a problem for you, do not use the interface at this time. | ||
2997 | ** | ||
2998 | ** When the virtual-table mechanism stablizes, we will declare the | ||
2999 | ** interface fixed, support it indefinitely, and remove this comment. | ||
3000 | */ | ||
3001 | |||
3002 | /* | ||
3003 | ** Structures used by the virtual table interface | ||
3004 | */ | ||
3005 | typedef struct sqlite3_vtab sqlite3_vtab; | ||
3006 | typedef struct sqlite3_index_info sqlite3_index_info; | ||
3007 | typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor; | ||
3008 | typedef struct sqlite3_module sqlite3_module; | ||
3009 | |||
3010 | /* | ||
3011 | ** A module is a class of virtual tables. Each module is defined | ||
3012 | ** by an instance of the following structure. This structure consists | ||
3013 | ** mostly of methods for the module. | ||
3014 | */ | ||
3015 | struct sqlite3_module { | ||
3016 | int iVersion; | ||
3017 | int (*xCreate)(sqlite3*, void *pAux, | ||
3018 | int argc, const char *const*argv, | ||
3019 | sqlite3_vtab **ppVTab, char**); | ||
3020 | int (*xConnect)(sqlite3*, void *pAux, | ||
3021 | int argc, const char *const*argv, | ||
3022 | sqlite3_vtab **ppVTab, char**); | ||
3023 | int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*); | ||
3024 | int (*xDisconnect)(sqlite3_vtab *pVTab); | ||
3025 | int (*xDestroy)(sqlite3_vtab *pVTab); | ||
3026 | int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor); | ||
3027 | int (*xClose)(sqlite3_vtab_cursor*); | ||
3028 | int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr, | ||
3029 | int argc, sqlite3_value **argv); | ||
3030 | int (*xNext)(sqlite3_vtab_cursor*); | ||
3031 | int (*xEof)(sqlite3_vtab_cursor*); | ||
3032 | int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int); | ||
3033 | int (*xRowid)(sqlite3_vtab_cursor*, sqlite3_int64 *pRowid); | ||
3034 | int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite3_int64 *); | ||
3035 | int (*xBegin)(sqlite3_vtab *pVTab); | ||
3036 | int (*xSync)(sqlite3_vtab *pVTab); | ||
3037 | int (*xCommit)(sqlite3_vtab *pVTab); | ||
3038 | int (*xRollback)(sqlite3_vtab *pVTab); | ||
3039 | int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName, | ||
3040 | void (**pxFunc)(sqlite3_context*,int,sqlite3_value**), | ||
3041 | void **ppArg); | ||
3042 | |||
3043 | int (*xRename)(sqlite3_vtab *pVtab, const char *zNew); | ||
3044 | }; | ||
3045 | |||
3046 | /* | ||
3047 | ** The sqlite3_index_info structure and its substructures is used to | ||
3048 | ** pass information into and receive the reply from the xBestIndex | ||
3049 | ** method of an sqlite3_module. The fields under **Inputs** are the | ||
3050 | ** inputs to xBestIndex and are read-only. xBestIndex inserts its | ||
3051 | ** results into the **Outputs** fields. | ||
3052 | ** | ||
3053 | ** The aConstraint[] array records WHERE clause constraints of the | ||
3054 | ** form: | ||
3055 | ** | ||
3056 | ** column OP expr | ||
3057 | ** | ||
3058 | ** Where OP is =, <, <=, >, or >=. The particular operator is stored | ||
3059 | ** in aConstraint[].op. The index of the column is stored in | ||
3060 | ** aConstraint[].iColumn. aConstraint[].usable is TRUE if the | ||
3061 | ** expr on the right-hand side can be evaluated (and thus the constraint | ||
3062 | ** is usable) and false if it cannot. | ||
3063 | ** | ||
3064 | ** The optimizer automatically inverts terms of the form "expr OP column" | ||
3065 | ** and makes other simplifications to the WHERE clause in an attempt to | ||
3066 | ** get as many WHERE clause terms into the form shown above as possible. | ||
3067 | ** The aConstraint[] array only reports WHERE clause terms in the correct | ||
3068 | ** form that refer to the particular virtual table being queried. | ||
3069 | ** | ||
3070 | ** Information about the ORDER BY clause is stored in aOrderBy[]. | ||
3071 | ** Each term of aOrderBy records a column of the ORDER BY clause. | ||
3072 | ** | ||
3073 | ** The xBestIndex method must fill aConstraintUsage[] with information | ||
3074 | ** about what parameters to pass to xFilter. If argvIndex>0 then | ||
3075 | ** the right-hand side of the corresponding aConstraint[] is evaluated | ||
3076 | ** and becomes the argvIndex-th entry in argv. If aConstraintUsage[].omit | ||
3077 | ** is true, then the constraint is assumed to be fully handled by the | ||
3078 | ** virtual table and is not checked again by SQLite. | ||
3079 | ** | ||
3080 | ** The idxNum and idxPtr values are recorded and passed into xFilter. | ||
3081 | ** sqlite3_free() is used to free idxPtr if needToFreeIdxPtr is true. | ||
3082 | ** | ||
3083 | ** The orderByConsumed means that output from xFilter will occur in | ||
3084 | ** the correct order to satisfy the ORDER BY clause so that no separate | ||
3085 | ** sorting step is required. | ||
3086 | ** | ||
3087 | ** The estimatedCost value is an estimate of the cost of doing the | ||
3088 | ** particular lookup. A full scan of a table with N entries should have | ||
3089 | ** a cost of N. A binary search of a table of N entries should have a | ||
3090 | ** cost of approximately log(N). | ||
3091 | */ | ||
3092 | struct sqlite3_index_info { | ||
3093 | /* Inputs */ | ||
3094 | int nConstraint; /* Number of entries in aConstraint */ | ||
3095 | struct sqlite3_index_constraint { | ||
3096 | int iColumn; /* Column on left-hand side of constraint */ | ||
3097 | unsigned char op; /* Constraint operator */ | ||
3098 | unsigned char usable; /* True if this constraint is usable */ | ||
3099 | int iTermOffset; /* Used internally - xBestIndex should ignore */ | ||
3100 | } *aConstraint; /* Table of WHERE clause constraints */ | ||
3101 | int nOrderBy; /* Number of terms in the ORDER BY clause */ | ||
3102 | struct sqlite3_index_orderby { | ||
3103 | int iColumn; /* Column number */ | ||
3104 | unsigned char desc; /* True for DESC. False for ASC. */ | ||
3105 | } *aOrderBy; /* The ORDER BY clause */ | ||
3106 | |||
3107 | /* Outputs */ | ||
3108 | struct sqlite3_index_constraint_usage { | ||
3109 | int argvIndex; /* if >0, constraint is part of argv to xFilter */ | ||
3110 | unsigned char omit; /* Do not code a test for this constraint */ | ||
3111 | } *aConstraintUsage; | ||
3112 | int idxNum; /* Number used to identify the index */ | ||
3113 | char *idxStr; /* String, possibly obtained from sqlite3_malloc */ | ||
3114 | int needToFreeIdxStr; /* Free idxStr using sqlite3_free() if true */ | ||
3115 | int orderByConsumed; /* True if output is already ordered */ | ||
3116 | double estimatedCost; /* Estimated cost of using this index */ | ||
3117 | }; | ||
3118 | #define SQLITE_INDEX_CONSTRAINT_EQ 2 | ||
3119 | #define SQLITE_INDEX_CONSTRAINT_GT 4 | ||
3120 | #define SQLITE_INDEX_CONSTRAINT_LE 8 | ||
3121 | #define SQLITE_INDEX_CONSTRAINT_LT 16 | ||
3122 | #define SQLITE_INDEX_CONSTRAINT_GE 32 | ||
3123 | #define SQLITE_INDEX_CONSTRAINT_MATCH 64 | ||
3124 | |||
3125 | /* | ||
3126 | ** This routine is used to register a new module name with an SQLite | ||
3127 | ** connection. Module names must be registered before creating new | ||
3128 | ** virtual tables on the module, or before using preexisting virtual | ||
3129 | ** tables of the module. | ||
3130 | */ | ||
3131 | int sqlite3_create_module( | ||
3132 | sqlite3 *db, /* SQLite connection to register module with */ | ||
3133 | const char *zName, /* Name of the module */ | ||
3134 | const sqlite3_module *, /* Methods for the module */ | ||
3135 | void * /* Client data for xCreate/xConnect */ | ||
3136 | ); | ||
3137 | |||
3138 | /* | ||
3139 | ** This routine is identical to the sqlite3_create_module() method above, | ||
3140 | ** except that it allows a destructor function to be specified. It is | ||
3141 | ** even more experimental than the rest of the virtual tables API. | ||
3142 | */ | ||
3143 | int sqlite3_create_module_v2( | ||
3144 | sqlite3 *db, /* SQLite connection to register module with */ | ||
3145 | const char *zName, /* Name of the module */ | ||
3146 | const sqlite3_module *, /* Methods for the module */ | ||
3147 | void *, /* Client data for xCreate/xConnect */ | ||
3148 | void(*xDestroy)(void*) /* Module destructor function */ | ||
3149 | ); | ||
3150 | |||
3151 | /* | ||
3152 | ** Every module implementation uses a subclass of the following structure | ||
3153 | ** to describe a particular instance of the module. Each subclass will | ||
3154 | ** be tailored to the specific needs of the module implementation. The | ||
3155 | ** purpose of this superclass is to define certain fields that are common | ||
3156 | ** to all module implementations. | ||
3157 | ** | ||
3158 | ** Virtual tables methods can set an error message by assigning a | ||
3159 | ** string obtained from sqlite3_mprintf() to zErrMsg. The method should | ||
3160 | ** take care that any prior string is freed by a call to sqlite3_free() | ||
3161 | ** prior to assigning a new string to zErrMsg. After the error message | ||
3162 | ** is delivered up to the client application, the string will be automatically | ||
3163 | ** freed by sqlite3_free() and the zErrMsg field will be zeroed. Note | ||
3164 | ** that sqlite3_mprintf() and sqlite3_free() are used on the zErrMsg field | ||
3165 | ** since virtual tables are commonly implemented in loadable extensions which | ||
3166 | ** do not have access to sqlite3MPrintf() or sqlite3Free(). | ||
3167 | */ | ||
3168 | struct sqlite3_vtab { | ||
3169 | const sqlite3_module *pModule; /* The module for this virtual table */ | ||
3170 | int nRef; /* Used internally */ | ||
3171 | char *zErrMsg; /* Error message from sqlite3_mprintf() */ | ||
3172 | /* Virtual table implementations will typically add additional fields */ | ||
3173 | }; | ||
3174 | |||
3175 | /* Every module implementation uses a subclass of the following structure | ||
3176 | ** to describe cursors that point into the virtual table and are used | ||
3177 | ** to loop through the virtual table. Cursors are created using the | ||
3178 | ** xOpen method of the module. Each module implementation will define | ||
3179 | ** the content of a cursor structure to suit its own needs. | ||
3180 | ** | ||
3181 | ** This superclass exists in order to define fields of the cursor that | ||
3182 | ** are common to all implementations. | ||
3183 | */ | ||
3184 | struct sqlite3_vtab_cursor { | ||
3185 | sqlite3_vtab *pVtab; /* Virtual table of this cursor */ | ||
3186 | /* Virtual table implementations will typically add additional fields */ | ||
3187 | }; | ||
3188 | |||
3189 | /* | ||
3190 | ** The xCreate and xConnect methods of a module use the following API | ||
3191 | ** to declare the format (the names and datatypes of the columns) of | ||
3192 | ** the virtual tables they implement. | ||
3193 | */ | ||
3194 | int sqlite3_declare_vtab(sqlite3*, const char *zCreateTable); | ||
3195 | |||
3196 | /* | ||
3197 | ** Virtual tables can provide alternative implementations of functions | ||
3198 | ** using the xFindFunction method. But global versions of those functions | ||
3199 | ** must exist in order to be overloaded. | ||
3200 | ** | ||
3201 | ** This API makes sure a global version of a function with a particular | ||
3202 | ** name and number of parameters exists. If no such function exists | ||
3203 | ** before this API is called, a new function is created. The implementation | ||
3204 | ** of the new function always causes an exception to be thrown. So | ||
3205 | ** the new function is not good for anything by itself. Its only | ||
3206 | ** purpose is to be a place-holder function that can be overloaded | ||
3207 | ** by virtual tables. | ||
3208 | ** | ||
3209 | ** This API should be considered part of the virtual table interface, | ||
3210 | ** which is experimental and subject to change. | ||
3211 | */ | ||
3212 | int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg); | ||
3213 | |||
3214 | /* | ||
3215 | ** The interface to the virtual-table mechanism defined above (back up | ||
3216 | ** to a comment remarkably similar to this one) is currently considered | ||
3217 | ** to be experimental. The interface might change in incompatible ways. | ||
3218 | ** If this is a problem for you, do not use the interface at this time. | ||
3219 | ** | ||
3220 | ** When the virtual-table mechanism stabilizes, we will declare the | ||
3221 | ** interface fixed, support it indefinitely, and remove this comment. | ||
3222 | ** | ||
3223 | ****** EXPERIMENTAL - subject to change without notice ************** | ||
3224 | */ | ||
3225 | |||
3226 | /* | ||
3227 | ** CAPI3REF: A Handle To An Open BLOB | ||
3228 | ** | ||
3229 | ** An instance of the following opaque structure is used to | ||
3230 | ** represent an blob-handle. A blob-handle is created by | ||
3231 | ** [sqlite3_blob_open()] and destroyed by [sqlite3_blob_close()]. | ||
3232 | ** The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces | ||
3233 | ** can be used to read or write small subsections of the blob. | ||
3234 | ** The [sqlite3_blob_bytes()] interface returns the size of the | ||
3235 | ** blob in bytes. | ||
3236 | */ | ||
3237 | typedef struct sqlite3_blob sqlite3_blob; | ||
3238 | |||
3239 | /* | ||
3240 | ** CAPI3REF: Open A BLOB For Incremental I/O | ||
3241 | ** | ||
3242 | ** Open a handle to the blob located in row iRow,, column zColumn, | ||
3243 | ** table zTable in database zDb. i.e. the same blob that would | ||
3244 | ** be selected by: | ||
3245 | ** | ||
3246 | ** <pre> | ||
3247 | ** SELECT zColumn FROM zDb.zTable WHERE rowid = iRow; | ||
3248 | ** </pre> | ||
3249 | ** | ||
3250 | ** If the flags parameter is non-zero, the blob is opened for | ||
3251 | ** read and write access. If it is zero, the blob is opened for read | ||
3252 | ** access. | ||
3253 | ** | ||
3254 | ** On success, [SQLITE_OK] is returned and the new | ||
3255 | ** [sqlite3_blob | blob handle] is written to *ppBlob. | ||
3256 | ** Otherwise an error code is returned and | ||
3257 | ** any value written to *ppBlob should not be used by the caller. | ||
3258 | ** This function sets the database-handle error code and message | ||
3259 | ** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()]. | ||
3260 | */ | ||
3261 | int sqlite3_blob_open( | ||
3262 | sqlite3*, | ||
3263 | const char *zDb, | ||
3264 | const char *zTable, | ||
3265 | const char *zColumn, | ||
3266 | sqlite3_int64 iRow, | ||
3267 | int flags, | ||
3268 | sqlite3_blob **ppBlob | ||
3269 | ); | ||
3270 | |||
3271 | /* | ||
3272 | ** CAPI3REF: Close A BLOB Handle | ||
3273 | ** | ||
3274 | ** Close an open [sqlite3_blob | blob handle]. | ||
3275 | */ | ||
3276 | int sqlite3_blob_close(sqlite3_blob *); | ||
3277 | |||
3278 | /* | ||
3279 | ** CAPI3REF: Return The Size Of An Open BLOB | ||
3280 | ** | ||
3281 | ** Return the size in bytes of the blob accessible via the open | ||
3282 | ** [sqlite3_blob | blob-handle] passed as an argument. | ||
3283 | */ | ||
3284 | int sqlite3_blob_bytes(sqlite3_blob *); | ||
3285 | |||
3286 | /* | ||
3287 | ** CAPI3REF: Read Data From A BLOB Incrementally | ||
3288 | ** | ||
3289 | ** This function is used to read data from an open | ||
3290 | ** [sqlite3_blob | blob-handle] into a caller supplied buffer. | ||
3291 | ** n bytes of data are copied into buffer | ||
3292 | ** z from the open blob, starting at offset iOffset. | ||
3293 | ** | ||
3294 | ** On success, SQLITE_OK is returned. Otherwise, an | ||
3295 | ** [SQLITE_ERROR | SQLite error code] or an | ||
3296 | ** [SQLITE_IOERR_READ | extended error code] is returned. | ||
3297 | */ | ||
3298 | int sqlite3_blob_read(sqlite3_blob *, void *z, int n, int iOffset); | ||
3299 | |||
3300 | /* | ||
3301 | ** CAPI3REF: Write Data Into A BLOB Incrementally | ||
3302 | ** | ||
3303 | ** This function is used to write data into an open | ||
3304 | ** [sqlite3_blob | blob-handle] from a user supplied buffer. | ||
3305 | ** n bytes of data are copied from the buffer | ||
3306 | ** pointed to by z into the open blob, starting at offset iOffset. | ||
3307 | ** | ||
3308 | ** If the [sqlite3_blob | blob-handle] passed as the first argument | ||
3309 | ** was not opened for writing (the flags parameter to [sqlite3_blob_open()] | ||
3310 | *** was zero), this function returns [SQLITE_READONLY]. | ||
3311 | ** | ||
3312 | ** This function may only modify the contents of the blob, it is | ||
3313 | ** not possible to increase the size of a blob using this API. If | ||
3314 | ** offset iOffset is less than n bytes from the end of the blob, | ||
3315 | ** [SQLITE_ERROR] is returned and no data is written. | ||
3316 | ** | ||
3317 | ** On success, SQLITE_OK is returned. Otherwise, an | ||
3318 | ** [SQLITE_ERROR | SQLite error code] or an | ||
3319 | ** [SQLITE_IOERR_READ | extended error code] is returned. | ||
3320 | */ | ||
3321 | int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset); | ||
3322 | |||
3323 | /* | ||
3324 | ** CAPI3REF: Virtual File System Objects | ||
3325 | ** | ||
3326 | ** A virtual filesystem (VFS) is an [sqlite3_vfs] object | ||
3327 | ** that SQLite uses to interact | ||
3328 | ** with the underlying operating system. Most builds come with a | ||
3329 | ** single default VFS that is appropriate for the host computer. | ||
3330 | ** New VFSes can be registered and existing VFSes can be unregistered. | ||
3331 | ** The following interfaces are provided. | ||
3332 | ** | ||
3333 | ** The sqlite3_vfs_find() interface returns a pointer to a VFS given its | ||
3334 | ** name. Names are case sensitive. If there is no match, a NULL | ||
3335 | ** pointer is returned. If zVfsName is NULL then the default | ||
3336 | ** VFS is returned. | ||
3337 | ** | ||
3338 | ** New VFSes are registered with sqlite3_vfs_register(). Each | ||
3339 | ** new VFS becomes the default VFS if the makeDflt flag is set. | ||
3340 | ** The same VFS can be registered multiple times without injury. | ||
3341 | ** To make an existing VFS into the default VFS, register it again | ||
3342 | ** with the makeDflt flag set. If two different VFSes with the | ||
3343 | ** same name are registered, the behavior is undefined. If a | ||
3344 | ** VFS is registered with a name that is NULL or an empty string, | ||
3345 | ** then the behavior is undefined. | ||
3346 | ** | ||
3347 | ** Unregister a VFS with the sqlite3_vfs_unregister() interface. | ||
3348 | ** If the default VFS is unregistered, another VFS is chosen as | ||
3349 | ** the default. The choice for the new VFS is arbitrary. | ||
3350 | */ | ||
3351 | sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName); | ||
3352 | int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt); | ||
3353 | int sqlite3_vfs_unregister(sqlite3_vfs*); | ||
3354 | |||
3355 | /* | ||
3356 | ** CAPI3REF: Mutexes | ||
3357 | ** | ||
3358 | ** The SQLite core uses these routines for thread | ||
3359 | ** synchronization. Though they are intended for internal | ||
3360 | ** use by SQLite, code that links against SQLite is | ||
3361 | ** permitted to use any of these routines. | ||
3362 | ** | ||
3363 | ** The SQLite source code contains multiple implementations | ||
3364 | ** of these mutex routines. An appropriate implementation | ||
3365 | ** is selected automatically at compile-time. The following | ||
3366 | ** implementations are available in the SQLite core: | ||
3367 | ** | ||
3368 | ** <ul> | ||
3369 | ** <li> SQLITE_MUTEX_OS2 | ||
3370 | ** <li> SQLITE_MUTEX_PTHREAD | ||
3371 | ** <li> SQLITE_MUTEX_W32 | ||
3372 | ** <li> SQLITE_MUTEX_NOOP | ||
3373 | ** </ul> | ||
3374 | ** | ||
3375 | ** The SQLITE_MUTEX_NOOP implementation is a set of routines | ||
3376 | ** that does no real locking and is appropriate for use in | ||
3377 | ** a single-threaded application. The SQLITE_MUTEX_OS2, | ||
3378 | ** SQLITE_MUTEX_PTHREAD, and SQLITE_MUTEX_W32 implementations | ||
3379 | ** are appropriate for use on os/2, unix, and windows. | ||
3380 | ** | ||
3381 | ** If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor | ||
3382 | ** macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex | ||
3383 | ** implementation is included with the library. The | ||
3384 | ** mutex interface routines defined here become external | ||
3385 | ** references in the SQLite library for which implementations | ||
3386 | ** must be provided by the application. This facility allows an | ||
3387 | ** application that links against SQLite to provide its own mutex | ||
3388 | ** implementation without having to modify the SQLite core. | ||
3389 | ** | ||
3390 | ** The sqlite3_mutex_alloc() routine allocates a new | ||
3391 | ** mutex and returns a pointer to it. If it returns NULL | ||
3392 | ** that means that a mutex could not be allocated. SQLite | ||
3393 | ** will unwind its stack and return an error. The argument | ||
3394 | ** to sqlite3_mutex_alloc() is one of these integer constants: | ||
3395 | ** | ||
3396 | ** <ul> | ||
3397 | ** <li> SQLITE_MUTEX_FAST | ||
3398 | ** <li> SQLITE_MUTEX_RECURSIVE | ||
3399 | ** <li> SQLITE_MUTEX_STATIC_MASTER | ||
3400 | ** <li> SQLITE_MUTEX_STATIC_MEM | ||
3401 | ** <li> SQLITE_MUTEX_STATIC_MEM2 | ||
3402 | ** <li> SQLITE_MUTEX_STATIC_PRNG | ||
3403 | ** <li> SQLITE_MUTEX_STATIC_LRU | ||
3404 | ** </ul> | ||
3405 | ** | ||
3406 | ** The first two constants cause sqlite3_mutex_alloc() to create | ||
3407 | ** a new mutex. The new mutex is recursive when SQLITE_MUTEX_RECURSIVE | ||
3408 | ** is used but not necessarily so when SQLITE_MUTEX_FAST is used. | ||
3409 | ** The mutex implementation does not need to make a distinction | ||
3410 | ** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does | ||
3411 | ** not want to. But SQLite will only request a recursive mutex in | ||
3412 | ** cases where it really needs one. If a faster non-recursive mutex | ||
3413 | ** implementation is available on the host platform, the mutex subsystem | ||
3414 | ** might return such a mutex in response to SQLITE_MUTEX_FAST. | ||
3415 | ** | ||
3416 | ** The other allowed parameters to sqlite3_mutex_alloc() each return | ||
3417 | ** a pointer to a static preexisting mutex. Four static mutexes are | ||
3418 | ** used by the current version of SQLite. Future versions of SQLite | ||
3419 | ** may add additional static mutexes. Static mutexes are for internal | ||
3420 | ** use by SQLite only. Applications that use SQLite mutexes should | ||
3421 | ** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or | ||
3422 | ** SQLITE_MUTEX_RECURSIVE. | ||
3423 | ** | ||
3424 | ** Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST | ||
3425 | ** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc() | ||
3426 | ** returns a different mutex on every call. But for the static | ||
3427 | ** mutex types, the same mutex is returned on every call that has | ||
3428 | ** the same type number. | ||
3429 | ** | ||
3430 | ** The sqlite3_mutex_free() routine deallocates a previously | ||
3431 | ** allocated dynamic mutex. SQLite is careful to deallocate every | ||
3432 | ** dynamic mutex that it allocates. The dynamic mutexes must not be in | ||
3433 | ** use when they are deallocated. Attempting to deallocate a static | ||
3434 | ** mutex results in undefined behavior. SQLite never deallocates | ||
3435 | ** a static mutex. | ||
3436 | ** | ||
3437 | ** The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt | ||
3438 | ** to enter a mutex. If another thread is already within the mutex, | ||
3439 | ** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return | ||
3440 | ** SQLITE_BUSY. The sqlite3_mutex_try() interface returns SQLITE_OK | ||
3441 | ** upon successful entry. Mutexes created using SQLITE_MUTEX_RECURSIVE can | ||
3442 | ** be entered multiple times by the same thread. In such cases the, | ||
3443 | ** mutex must be exited an equal number of times before another thread | ||
3444 | ** can enter. If the same thread tries to enter any other kind of mutex | ||
3445 | ** more than once, the behavior is undefined. SQLite will never exhibit | ||
3446 | ** such behavior in its own use of mutexes. | ||
3447 | ** | ||
3448 | ** Some systems (ex: windows95) do not the operation implemented by | ||
3449 | ** sqlite3_mutex_try(). On those systems, sqlite3_mutex_try() will | ||
3450 | ** always return SQLITE_BUSY. The SQLite core only ever uses | ||
3451 | ** sqlite3_mutex_try() as an optimization so this is acceptable behavior. | ||
3452 | ** | ||
3453 | ** The sqlite3_mutex_leave() routine exits a mutex that was | ||
3454 | ** previously entered by the same thread. The behavior | ||
3455 | ** is undefined if the mutex is not currently entered by the | ||
3456 | ** calling thread or is not currently allocated. SQLite will | ||
3457 | ** never do either. | ||
3458 | ** | ||
3459 | ** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()]. | ||
3460 | */ | ||
3461 | sqlite3_mutex *sqlite3_mutex_alloc(int); | ||
3462 | void sqlite3_mutex_free(sqlite3_mutex*); | ||
3463 | void sqlite3_mutex_enter(sqlite3_mutex*); | ||
3464 | int sqlite3_mutex_try(sqlite3_mutex*); | ||
3465 | void sqlite3_mutex_leave(sqlite3_mutex*); | ||
3466 | |||
3467 | /* | ||
3468 | ** CAPI3REF: Mutex Verifcation Routines | ||
3469 | ** | ||
3470 | ** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines | ||
3471 | ** are intended for use inside assert() statements. The SQLite core | ||
3472 | ** never uses these routines except inside an assert() and applications | ||
3473 | ** are advised to follow the lead of the core. The core only | ||
3474 | ** provides implementations for these routines when it is compiled | ||
3475 | ** with the SQLITE_DEBUG flag. External mutex implementations | ||
3476 | ** are only required to provide these routines if SQLITE_DEBUG is | ||
3477 | ** defined and if NDEBUG is not defined. | ||
3478 | ** | ||
3479 | ** These routines should return true if the mutex in their argument | ||
3480 | ** is held or not held, respectively, by the calling thread. | ||
3481 | ** | ||
3482 | ** The implementation is not required to provided versions of these | ||
3483 | ** routines that actually work. | ||
3484 | ** If the implementation does not provide working | ||
3485 | ** versions of these routines, it should at least provide stubs | ||
3486 | ** that always return true so that one does not get spurious | ||
3487 | ** assertion failures. | ||
3488 | ** | ||
3489 | ** If the argument to sqlite3_mutex_held() is a NULL pointer then | ||
3490 | ** the routine should return 1. This seems counter-intuitive since | ||
3491 | ** clearly the mutex cannot be held if it does not exist. But the | ||
3492 | ** the reason the mutex does not exist is because the build is not | ||
3493 | ** using mutexes. And we do not want the assert() containing the | ||
3494 | ** call to sqlite3_mutex_held() to fail, so a non-zero return is | ||
3495 | ** the appropriate thing to do. The sqlite3_mutex_notheld() | ||
3496 | ** interface should also return 1 when given a NULL pointer. | ||
3497 | */ | ||
3498 | int sqlite3_mutex_held(sqlite3_mutex*); | ||
3499 | int sqlite3_mutex_notheld(sqlite3_mutex*); | ||
3500 | |||
3501 | /* | ||
3502 | ** CAPI3REF: Mutex Types | ||
3503 | ** | ||
3504 | ** The [sqlite3_mutex_alloc()] interface takes a single argument | ||
3505 | ** which is one of these integer constants. | ||
3506 | */ | ||
3507 | #define SQLITE_MUTEX_FAST 0 | ||
3508 | #define SQLITE_MUTEX_RECURSIVE 1 | ||
3509 | #define SQLITE_MUTEX_STATIC_MASTER 2 | ||
3510 | #define SQLITE_MUTEX_STATIC_MEM 3 /* sqlite3_malloc() */ | ||
3511 | #define SQLITE_MUTEX_STATIC_MEM2 4 /* sqlite3_release_memory() */ | ||
3512 | #define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_random() */ | ||
3513 | #define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */ | ||
3514 | |||
3515 | /* | ||
3516 | ** CAPI3REF: Low-Level Control Of Database Files | ||
3517 | ** | ||
3518 | ** The [sqlite3_file_control()] interface makes a direct call to the | ||
3519 | ** xFileControl method for the [sqlite3_io_methods] object associated | ||
3520 | ** with a particular database identified by the second argument. The | ||
3521 | ** name of the database is the name assigned to the database by the | ||
3522 | ** <a href="lang_attach.html">ATTACH</a> SQL command that opened the | ||
3523 | ** database. To control the main database file, use the name "main" | ||
3524 | ** or a NULL pointer. The third and fourth parameters to this routine | ||
3525 | ** are passed directly through to the second and third parameters of | ||
3526 | ** the xFileControl method. The return value of the xFileControl | ||
3527 | ** method becomes the return value of this routine. | ||
3528 | ** | ||
3529 | ** If the second parameter (zDbName) does not match the name of any | ||
3530 | ** open database file, then SQLITE_ERROR is returned. This error | ||
3531 | ** code is not remembered and will not be recalled by [sqlite3_errcode()] | ||
3532 | ** or [sqlite3_errmsg()]. The underlying xFileControl method might | ||
3533 | ** also return SQLITE_ERROR. There is no way to distinguish between | ||
3534 | ** an incorrect zDbName and an SQLITE_ERROR return from the underlying | ||
3535 | ** xFileControl method. | ||
3536 | ** | ||
3537 | ** See also: [SQLITE_FCNTL_LOCKSTATE] | ||
3538 | */ | ||
3539 | int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*); | ||
3540 | |||
3541 | /* | ||
3542 | ** Undo the hack that converts floating point types to integer for | ||
3543 | ** builds on processors without floating point support. | ||
3544 | */ | ||
3545 | #ifdef SQLITE_OMIT_FLOATING_POINT | ||
3546 | # undef double | ||
3547 | #endif | ||
3548 | |||
3549 | #ifdef __cplusplus | ||
3550 | } /* End of the 'extern "C"' block */ | ||
3551 | #endif | ||
3552 | #endif | ||