WebCore: For continuous scrolling devices on the Mac (trackpads and Mighty/Magic
[WebKit-https.git] / WebKitLibraries / WebCoreSQLite3 / sqlite3.h
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.212 2007/06/14 20:57:19 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 ** Make sure these symbols where not defined by some previous header
48 ** file.
49 */
50 #ifdef SQLITE_VERSION
51 # undef SQLITE_VERSION
52 #endif
53 #ifdef SQLITE_VERSION_NUMBER
54 # undef SQLITE_VERSION_NUMBER
55 #endif
56
57 /*
58 ** CAPI3REF: Compile-Time Library Version Numbers
59 **
60 ** The version of the SQLite library is contained in the sqlite3.h
61 ** header file in a #define named SQLITE_VERSION.  The SQLITE_VERSION
62 ** macro resolves to a string constant.
63 **
64 ** The format of the version string is "X.Y.Z", where
65 ** X is the major version number, Y is the minor version number and Z
66 ** is the release number.  The X.Y.Z might be followed by "alpha" or "beta".
67 ** For example "3.1.1beta".
68 **
69 ** The X value is always 3 in SQLite.  The X value only changes when
70 ** backwards compatibility is broken and we intend to never break
71 ** backwards compatibility.  The Y value only changes when
72 ** there are major feature enhancements that are forwards compatible
73 ** but not backwards compatible.  The Z value is incremented with
74 ** each release but resets back to 0 when Y is incremented.
75 **
76 ** The SQLITE_VERSION_NUMBER is an integer with the value 
77 ** (X*1000000 + Y*1000 + Z). For example, for version "3.1.1beta", 
78 ** SQLITE_VERSION_NUMBER is set to 3001001. To detect if they are using 
79 ** version 3.1.1 or greater at compile time, programs may use the test 
80 ** (SQLITE_VERSION_NUMBER>=3001001).
81 **
82 ** See also: [sqlite3_libversion()] and [sqlite3_libversion_number()].
83 */
84 #define SQLITE_VERSION         "3.4.0"
85 #define SQLITE_VERSION_NUMBER 3004000
86
87 /*
88 ** CAPI3REF: Run-Time Library Version Numbers
89 **
90 ** These routines return values equivalent to the header constants
91 ** [SQLITE_VERSION] and [SQLITE_VERSION_NUMBER].  The values returned
92 ** by this routines should only be different from the header values
93 ** if you compile your program using an sqlite3.h header from a
94 ** different version of SQLite that the version of the library you
95 ** link against.
96 **
97 ** The sqlite3_version[] string constant contains the text of the
98 ** [SQLITE_VERSION] string.  The sqlite3_libversion() function returns
99 ** a poiner to the sqlite3_version[] string constant.  The function
100 ** is provided for DLL users who can only access functions and not
101 ** constants within the DLL.
102 */
103 extern const char sqlite3_version[];
104 const char *sqlite3_libversion(void);
105 int sqlite3_libversion_number(void);
106
107 /*
108 ** CAPI3REF: Database Connection Handle
109 **
110 ** Each open SQLite database is represented by pointer to an instance of the
111 ** opaque structure named "sqlite3".  It is useful to think of an sqlite3
112 ** pointer as an object.  The [sqlite3_open] interface is its constructor
113 ** and [sqlite3_close] is its destructor.  There are many other interfaces
114 ** (such as [sqlite3_prepare_v2], [sqlite3_create_function], and
115 ** [sqlite3_busy_timeout] to name but three) that are methods on this
116 ** object.
117 */
118 typedef struct sqlite3 sqlite3;
119
120
121 /*
122 ** CAPI3REF: 64-Bit Integer Types
123 **
124 ** Some compilers do not support the "long long" datatype.  So we have
125 ** to do compiler-specific typedefs for 64-bit signed and unsigned integers.
126 **
127 ** Many SQLite interface functions require a 64-bit integer arguments.
128 ** Those interfaces are declared using this typedef.
129 */
130 #ifdef SQLITE_INT64_TYPE
131   typedef SQLITE_INT64_TYPE sqlite_int64;
132   typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;
133 #elif defined(_MSC_VER) || defined(__BORLANDC__)
134   typedef __int64 sqlite_int64;
135   typedef unsigned __int64 sqlite_uint64;
136 #else
137   typedef long long int sqlite_int64;
138   typedef unsigned long long int sqlite_uint64;
139 #endif
140
141 /*
142 ** If compiling for a processor that lacks floating point support,
143 ** substitute integer for floating-point
144 */
145 #ifdef SQLITE_OMIT_FLOATING_POINT
146 # define double sqlite_int64
147 #endif
148
149 /*
150 ** CAPI3REF: Closing A Database Connection
151 **
152 ** Call this function with a pointer to a structure that was previously
153 ** returned from [sqlite3_open()] and the corresponding database will by
154 ** closed.
155 **
156 ** All SQL statements prepared using [sqlite3_prepare_v2()] or
157 ** [sqlite3_prepare16_v2()] must be destroyed using [sqlite3_finalize()]
158 ** before this routine is called. Otherwise, SQLITE_BUSY is returned and the
159 ** database connection remains open.
160 */
161 int sqlite3_close(sqlite3 *);
162
163 /*
164 ** The type for a callback function.
165 ** This is legacy and deprecated.  It is included for historical
166 ** compatibility and is not documented.
167 */
168 typedef int (*sqlite3_callback)(void*,int,char**, char**);
169
170 /*
171 ** CAPI3REF: One-Step Query Execution Interface
172 **
173 ** This interface is used to do a one-time evaluatation of zero
174 ** or more SQL statements.  UTF-8 text of the SQL statements to
175 ** be evaluted is passed in as the second parameter.  The statements
176 ** are prepared one by one using [sqlite3_prepare()], evaluated
177 ** using [sqlite3_step()], then destroyed using [sqlite3_finalize()].
178 **
179 ** If one or more of the SQL statements are queries, then
180 ** the callback function specified by the 3rd parameter is
181 ** invoked once for each row of the query result.  This callback
182 ** should normally return 0.  If the callback returns a non-zero
183 ** value then the query is aborted, all subsequent SQL statements
184 ** are skipped and the sqlite3_exec() function returns the SQLITE_ABORT.
185 **
186 ** The 4th parameter to this interface is an arbitrary pointer that is
187 ** passed through to the callback function as its first parameter.
188 **
189 ** The 2nd parameter to the callback function is the number of
190 ** columns in the query result.  The 3rd parameter to the callback
191 ** is an array of strings holding the values for each column
192 ** as extracted using [sqlite3_column_text()].
193 ** The 4th parameter to the callback is an array of strings
194 ** obtained using [sqlite3_column_name()] and holding
195 ** the names of each column.
196 **
197 ** The callback function may be NULL, even for queries.  A NULL
198 ** callback is not an error.  It just means that no callback
199 ** will be invoked.
200 **
201 ** If an error occurs while parsing or evaluating the SQL (but
202 ** not while executing the callback) then an appropriate error
203 ** message is written into memory obtained from [sqlite3_malloc()] and
204 ** *errmsg is made to point to that message.  The calling function
205 ** is responsible for freeing the memory that holds the error
206 ** message.   Use [sqlite3_free()] for this.  If errmsg==NULL,
207 ** then no error message is ever written.
208 **
209 ** The return value is is SQLITE_OK if there are no errors and
210 ** some other [SQLITE_OK | return code] if there is an error.  
211 ** The particular return value depends on the type of error. 
212 **
213 */
214 int sqlite3_exec(
215   sqlite3*,                                  /* An open database */
216   const char *sql,                           /* SQL to be evaluted */
217   int (*callback)(void*,int,char**,char**),  /* Callback function */
218   void *,                                    /* 1st argument to callback */
219   char **errmsg                              /* Error msg written here */
220 );
221
222 /*
223 ** CAPI3REF: Result Codes
224 ** KEYWORDS: SQLITE_OK
225 **
226 ** Many SQLite functions return an integer result code from the set shown
227 ** above in order to indicates success or failure.
228 **
229 ** The result codes above are the only ones returned by SQLite in its
230 ** default configuration.  However, the [sqlite3_extended_result_codes()]
231 ** API can be used to set a database connectoin to return more detailed
232 ** result codes.
233 **
234 ** See also: [SQLITE_IOERR_READ | extended result codes]
235 **
236 */
237 #define SQLITE_OK           0   /* Successful result */
238 /* beginning-of-error-codes */
239 #define SQLITE_ERROR        1   /* SQL error or missing database */
240 #define SQLITE_INTERNAL     2   /* NOT USED. Internal logic error in SQLite */
241 #define SQLITE_PERM         3   /* Access permission denied */
242 #define SQLITE_ABORT        4   /* Callback routine requested an abort */
243 #define SQLITE_BUSY         5   /* The database file is locked */
244 #define SQLITE_LOCKED       6   /* A table in the database is locked */
245 #define SQLITE_NOMEM        7   /* A malloc() failed */
246 #define SQLITE_READONLY     8   /* Attempt to write a readonly database */
247 #define SQLITE_INTERRUPT    9   /* Operation terminated by sqlite3_interrupt()*/
248 #define SQLITE_IOERR       10   /* Some kind of disk I/O error occurred */
249 #define SQLITE_CORRUPT     11   /* The database disk image is malformed */
250 #define SQLITE_NOTFOUND    12   /* NOT USED. Table or record not found */
251 #define SQLITE_FULL        13   /* Insertion failed because database is full */
252 #define SQLITE_CANTOPEN    14   /* Unable to open the database file */
253 #define SQLITE_PROTOCOL    15   /* NOT USED. Database lock protocol error */
254 #define SQLITE_EMPTY       16   /* Database is empty */
255 #define SQLITE_SCHEMA      17   /* The database schema changed */
256 #define SQLITE_TOOBIG      18   /* String or BLOB exceeds size limit */
257 #define SQLITE_CONSTRAINT  19   /* Abort due to contraint violation */
258 #define SQLITE_MISMATCH    20   /* Data type mismatch */
259 #define SQLITE_MISUSE      21   /* Library used incorrectly */
260 #define SQLITE_NOLFS       22   /* Uses OS features not supported on host */
261 #define SQLITE_AUTH        23   /* Authorization denied */
262 #define SQLITE_FORMAT      24   /* Auxiliary database format error */
263 #define SQLITE_RANGE       25   /* 2nd parameter to sqlite3_bind out of range */
264 #define SQLITE_NOTADB      26   /* File opened that is not a database file */
265 #define SQLITE_ROW         100  /* sqlite3_step() has another row ready */
266 #define SQLITE_DONE        101  /* sqlite3_step() has finished executing */
267 /* end-of-error-codes */
268
269 /*
270 ** CAPI3REF: Extended Result Codes
271 **
272 ** In its default configuration, SQLite API routines return one of 26 integer
273 ** result codes described at result-codes.  However, experience has shown that
274 ** many of these result codes are too course-grained.  They do not provide as
275 ** much information about problems as users might like.  In an effort to
276 ** address this, newer versions of SQLite (version 3.3.8 and later) include
277 ** support for additional result codes that provide more detailed information
278 ** about errors.  The extended result codes are enabled (or disabled) for 
279 ** each database
280 ** connection using the [sqlite3_extended_result_codes()] API.
281 ** 
282 ** Some of the available extended result codes are listed above.
283 ** We expect the number of extended result codes will be expand
284 ** over time.  Software that uses extended result codes should expect
285 ** to see new result codes in future releases of SQLite.
286 ** 
287 ** The symbolic name for an extended result code always contains a related
288 ** primary result code as a prefix.  Primary result codes contain a single
289 ** "_" character.  Extended result codes contain two or more "_" characters.
290 ** The numeric value of an extended result code can be converted to its
291 ** corresponding primary result code by masking off the lower 8 bytes.
292 **
293 ** The SQLITE_OK result code will never be extended.  It will always
294 ** be exactly zero.
295 */
296 #define SQLITE_IOERR_READ          (SQLITE_IOERR | (1<<8))
297 #define SQLITE_IOERR_SHORT_READ    (SQLITE_IOERR | (2<<8))
298 #define SQLITE_IOERR_WRITE         (SQLITE_IOERR | (3<<8))
299 #define SQLITE_IOERR_FSYNC         (SQLITE_IOERR | (4<<8))
300 #define SQLITE_IOERR_DIR_FSYNC     (SQLITE_IOERR | (5<<8))
301 #define SQLITE_IOERR_TRUNCATE      (SQLITE_IOERR | (6<<8))
302 #define SQLITE_IOERR_FSTAT         (SQLITE_IOERR | (7<<8))
303 #define SQLITE_IOERR_UNLOCK        (SQLITE_IOERR | (8<<8))
304 #define SQLITE_IOERR_RDLOCK        (SQLITE_IOERR | (9<<8))
305 #define SQLITE_IOERR_DELETE        (SQLITE_IOERR | (10<<8))
306 #define SQLITE_IOERR_BLOCKED       (SQLITE_IOERR | (11<<8))
307
308 /*
309 ** CAPI3REF: Enable Or Disable Extended Result Codes
310 **
311 ** This routine enables or disables the
312 ** [SQLITE_IOERR_READ | extended result codes] feature.
313 ** By default, SQLite API routines return one of only 26 integer
314 ** [SQLITE_OK | result codes].  When extended result codes
315 ** are enabled by this routine, the repetoire of result codes can be
316 ** much larger and can (hopefully) provide more detailed information
317 ** about the cause of an error.
318 **
319 ** The second argument is a boolean value that turns extended result
320 ** codes on and off.  Extended result codes are off by default for
321 ** backwards compatibility with older versions of SQLite.
322 */
323 int sqlite3_extended_result_codes(sqlite3*, int onoff);
324
325 /*
326 ** CAPI3REF: Last Insert Rowid
327 **
328 ** Each entry in an SQLite table has a unique 64-bit signed integer key
329 ** called the "rowid". The rowid is always available as an undeclared
330 ** column named ROWID, OID, or _ROWID_.  If the table has a column of
331 ** type INTEGER PRIMARY KEY then that column is another an alias for the
332 ** rowid.
333 **
334 ** This routine returns the rowid of the most recent INSERT into
335 ** the database from the database connection given in the first 
336 ** argument.  If no inserts have ever occurred on this database
337 ** connection, zero is returned.
338 **
339 ** If an INSERT occurs within a trigger, then the rowid of the
340 ** inserted row is returned by this routine as long as the trigger
341 ** is running.  But once the trigger terminates, the value returned
342 ** by this routine reverts to the last value inserted before the
343 ** trigger fired.
344 */
345 sqlite_int64 sqlite3_last_insert_rowid(sqlite3*);
346
347 /*
348 ** CAPI3REF: Count The Number Of Rows Modified
349 **
350 ** This function returns the number of database rows that were changed
351 ** (or inserted or deleted) by the most recent SQL statement.  Only
352 ** changes that are directly specified by the INSERT, UPDATE, or
353 ** DELETE statement are counted.  Auxiliary changes caused by
354 ** triggers are not counted.  Use the [sqlite3_total_changes()] function
355 ** to find the total number of changes including changes caused by triggers.
356 **
357 ** Within the body of a trigger, the sqlite3_changes() interface can be
358 ** called to find the number of
359 ** changes in the most recently completed INSERT, UPDATE, or DELETE
360 ** statement within the body of the trigger.
361 **
362 ** All changes are counted, even if they were later undone by a
363 ** ROLLBACK or ABORT.  Except, changes associated with creating and
364 ** dropping tables are not counted.
365 **
366 ** If a callback invokes [sqlite3_exec()] or [sqlite3_step()] recursively,
367 ** then the changes in the inner, recursive call are counted together
368 ** with the changes in the outer call.
369 **
370 ** SQLite implements the command "DELETE FROM table" without a WHERE clause
371 ** by dropping and recreating the table.  (This is much faster than going
372 ** through and deleting individual elements form the table.)  Because of
373 ** this optimization, the change count for "DELETE FROM table" will be
374 ** zero regardless of the number of elements that were originally in the
375 ** table. To get an accurate count of the number of rows deleted, use
376 ** "DELETE FROM table WHERE 1" instead.
377 */
378 int sqlite3_changes(sqlite3*);
379
380 /*
381 ** CAPI3REF: Total Number Of Rows Modified
382 ***
383 ** This function returns the number of database rows that have been
384 ** modified by INSERT, UPDATE or DELETE statements since the database handle
385 ** was opened. This includes UPDATE, INSERT and DELETE statements executed
386 ** as part of trigger programs. All changes are counted as soon as the
387 ** statement that makes them is completed (when the statement handle is
388 ** passed to [sqlite3_reset()] or [sqlite_finalise()]).
389 **
390 ** See also the [sqlite3_change()] interface.
391 **
392 ** SQLite implements the command "DELETE FROM table" without a WHERE clause
393 ** by dropping and recreating the table.  (This is much faster than going
394 ** through and deleting individual elements form the table.)  Because of
395 ** this optimization, the change count for "DELETE FROM table" will be
396 ** zero regardless of the number of elements that were originally in the
397 ** table. To get an accurate count of the number of rows deleted, use
398 ** "DELETE FROM table WHERE 1" instead.
399 */
400 int sqlite3_total_changes(sqlite3*);
401
402 /*
403 ** CAPI3REF: Interrupt A Long-Running Query
404 **
405 ** This function causes any pending database operation to abort and
406 ** return at its earliest opportunity.  This routine is typically
407 ** called in response to a user action such as pressing "Cancel"
408 ** or Ctrl-C where the user wants a long query operation to halt
409 ** immediately.
410 **
411 ** It is safe to call this routine from a thread different from the
412 ** thread that is currently running the database operation.
413 **
414 ** The SQL operation that is interrupted will return [SQLITE_INTERRUPT].
415 ** If an interrupted operation was an update that is inside an
416 ** explicit transaction, then the entire transaction will be rolled
417 ** back automatically.
418 */
419 void sqlite3_interrupt(sqlite3*);
420
421 /*
422 ** CAPI3REF: Determine If An SQL Statement Is Complete
423 **
424 ** These functions return true if the given input string comprises
425 ** one or more complete SQL statements. For the sqlite3_complete() call,
426 ** the parameter must be a nul-terminated UTF-8 string. For
427 ** sqlite3_complete16(), a nul-terminated machine byte order UTF-16 string
428 ** is required.
429 **
430 ** These routines are useful for command-line input to determine if the
431 ** currently entered text forms one or more complete SQL statements or
432 ** if additional input is needed before sending the statements into
433 ** SQLite for parsing. The algorithm is simple.  If the 
434 ** last token other than spaces and comments is a semicolon, then return 
435 ** true.  Actually, the algorithm is a little more complicated than that
436 ** in order to deal with triggers, but the basic idea is the same:  the
437 ** statement is not complete unless it ends in a semicolon.
438 */
439 int sqlite3_complete(const char *sql);
440 int sqlite3_complete16(const void *sql);
441
442 /*
443 ** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors
444 **
445 ** This routine identifies a callback function that might be invoked
446 ** whenever an attempt is made to open a database table 
447 ** that another thread or process has locked.
448 ** If the busy callback is NULL, then [SQLITE_BUSY]
449 ** (or sometimes [SQLITE_IOERR_BLOCKED])
450 ** is returned immediately upon encountering the lock.
451 ** If the busy callback is not NULL, then the
452 ** callback will be invoked with two arguments.  The
453 ** first argument to the handler is a copy of the void* pointer which
454 ** is the third argument to this routine.  The second argument to
455 ** the handler is the number of times that the busy handler has
456 ** been invoked for this locking event. If the
457 ** busy callback returns 0, then no additional attempts are made to
458 ** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned.
459 ** If the callback returns non-zero, then another attempt is made to open the
460 ** database for reading and the cycle repeats.
461 **
462 ** The presence of a busy handler does not guarantee that
463 ** it will be invoked when there is lock contention.
464 ** If SQLite determines that invoking the busy handler could result in
465 ** a deadlock, it will return [SQLITE_BUSY] instead.
466 ** Consider a scenario where one process is holding a read lock that
467 ** it is trying to promote to a reserved lock and
468 ** a second process is holding a reserved lock that it is trying
469 ** to promote to an exclusive lock.  The first process cannot proceed
470 ** because it is blocked by the second and the second process cannot
471 ** proceed because it is blocked by the first.  If both processes
472 ** invoke the busy handlers, neither will make any progress.  Therefore,
473 ** SQLite returns [SQLITE_BUSY] for the first process, hoping that this
474 ** will induce the first process to release its read lock and allow
475 ** the second process to proceed.
476 **
477 ** The default busy callback is NULL.
478 **
479 ** The [SQLITE_BUSY] error is converted to [SQLITE_IOERR_BLOCKED] when
480 ** SQLite is in the middle of a large transaction where all the
481 ** changes will not fit into the in-memory cache.  SQLite will
482 ** already hold a RESERVED lock on the database file, but it needs
483 ** to promote this lock to EXCLUSIVE so that it can spill cache
484 ** pages into the database file without harm to concurrent
485 ** readers.  If it is unable to promote the lock, then the in-memory
486 ** cache will be left in an inconsistent state and so the error
487 ** code is promoted from the relatively benign [SQLITE_BUSY] to
488 ** the more severe [SQLITE_IOERR_BLOCKED].  This error code promotion
489 ** forces an automatic rollback of the changes. See the
490 ** <a href="http://www.sqlite.org/cvstrac/wiki?p=CorruptionFollowingBusyError">
491 ** CorruptionFollowingBusyError</a> wiki page for a discussion of why
492 ** this is important.
493 **      
494 ** Sqlite is re-entrant, so the busy handler may start a new query. 
495 ** (It is not clear why anyone would every want to do this, but it
496 ** is allowed, in theory.)  But the busy handler may not close the
497 ** database.  Closing the database from a busy handler will delete 
498 ** data structures out from under the executing query and will 
499 ** probably result in a segmentation fault or other runtime error.
500 **
501 ** There can only be a single busy handler defined for each database
502 ** connection.  Setting a new busy handler clears any previous one.
503 ** Note that calling [sqlite3_busy_timeout()] will also set or clear
504 ** the busy handler.
505 */
506 int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
507
508 /*
509 ** CAPI3REF: Set A Busy Timeout
510 **
511 ** This routine sets a busy handler that sleeps for a while when a
512 ** table is locked.  The handler will sleep multiple times until 
513 ** at least "ms" milliseconds of sleeping have been done.  After
514 ** "ms" milliseconds of sleeping, the handler returns 0 which
515 ** causes [sqlite3_step()] to return [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED].
516 **
517 ** Calling this routine with an argument less than or equal to zero
518 ** turns off all busy handlers.
519 **
520 ** There can only be a single busy handler for a particular database
521 ** connection.  If another busy handler was defined  
522 ** (using [sqlite3_busy_handler()]) prior to calling
523 ** this routine, that other busy handler is cleared.
524 */
525 int sqlite3_busy_timeout(sqlite3*, int ms);
526
527 /*
528 ** CAPI3REF: Convenience Routines For Running Queries
529 **
530 ** This next routine is a convenience wrapper around [sqlite3_exec()].
531 ** Instead of invoking a user-supplied callback for each row of the
532 ** result, this routine remembers each row of the result in memory
533 ** obtained from [sqlite3_malloc()], then returns all of the result after the
534 ** query has finished. 
535 **
536 ** As an example, suppose the query result where this table:
537 **
538 ** <pre>
539 **        Name        | Age
540 **        -----------------------
541 **        Alice       | 43
542 **        Bob         | 28
543 **        Cindy       | 21
544 ** </pre>
545 **
546 ** If the 3rd argument were &azResult then after the function returns
547 ** azResult will contain the following data:
548 **
549 ** <pre>
550 **        azResult[0] = "Name";
551 **        azResult[1] = "Age";
552 **        azResult[2] = "Alice";
553 **        azResult[3] = "43";
554 **        azResult[4] = "Bob";
555 **        azResult[5] = "28";
556 **        azResult[6] = "Cindy";
557 **        azResult[7] = "21";
558 ** </pre>
559 **
560 ** Notice that there is an extra row of data containing the column
561 ** headers.  But the *nrow return value is still 3.  *ncolumn is
562 ** set to 2.  In general, the number of values inserted into azResult
563 ** will be ((*nrow) + 1)*(*ncolumn).
564 **
565 ** After the calling function has finished using the result, it should 
566 ** pass the result data pointer to sqlite3_free_table() in order to 
567 ** release the memory that was malloc-ed.  Because of the way the 
568 ** [sqlite3_malloc()] happens, the calling function must not try to call 
569 ** [sqlite3_free()] directly.  Only [sqlite3_free_table()] is able to release 
570 ** the memory properly and safely.
571 **
572 ** The return value of this routine is the same as from [sqlite3_exec()].
573 */
574 int sqlite3_get_table(
575   sqlite3*,              /* An open database */
576   const char *sql,       /* SQL to be executed */
577   char ***resultp,       /* Result written to a char *[]  that this points to */
578   int *nrow,             /* Number of result rows written here */
579   int *ncolumn,          /* Number of result columns written here */
580   char **errmsg          /* Error msg written here */
581 );
582 void sqlite3_free_table(char **result);
583
584 /*
585 ** CAPI3REF: Formatted String Printing Functions
586 **
587 ** These routines are workalikes of the "printf()" family of functions
588 ** from the standard C library.
589 **
590 ** The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
591 ** results into memory obtained from [sqlite_malloc()].
592 ** The strings returned by these two routines should be
593 ** released by [sqlite3_free()].  Both routines return a
594 ** NULL pointer if [sqlite3_malloc()] is unable to allocate enough
595 ** memory to hold the resulting string.
596 **
597 ** In sqlite3_snprintf() routine is similar to "snprintf()" from
598 ** the standard C library.  The result is written into the
599 ** buffer supplied as the second parameter whose size is given by
600 ** the first parameter.  Note that the order of the
601 ** first two parameters is reversed from snprintf().  This is an
602 ** historical accident that cannot be fixed without breaking
603 ** backwards compatibility.  Note also that sqlite3_snprintf()
604 ** returns a pointer to its buffer instead of the number of
605 ** characters actually written into the buffer.  We admit that
606 ** the number of characters written would be a more useful return
607 ** value but we cannot change the implementation of sqlite3_snprintf()
608 ** now without breaking compatibility.
609 **
610 ** As long as the buffer size is greater than zero, sqlite3_snprintf()
611 ** guarantees that the buffer is always zero-terminated.  The first
612 ** parameter "n" is the total size of the buffer, including space for
613 ** the zero terminator.  So the longest string that can be completely
614 ** written will be n-1 characters.
615 **
616 ** These routines all implement some additional formatting
617 ** options that are useful for constructing SQL statements.
618 ** All of the usual printf formatting options apply.  In addition, there
619 ** is are "%q" and "%Q" options.
620 **
621 ** The %q option works like %s in that it substitutes a null-terminated
622 ** string from the argument list.  But %q also doubles every '\'' character.
623 ** %q is designed for use inside a string literal.  By doubling each '\''
624 ** character it escapes that character and allows it to be inserted into
625 ** the string.
626 **
627 ** For example, so some string variable contains text as follows:
628 **
629 ** <blockquote><pre>
630 **  char *zText = "It's a happy day!";
631 ** </pre></blockquote>
632 **
633 ** One can use this text in an SQL statement as follows:
634 **
635 ** <blockquote><pre>
636 **  char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText);
637 **  sqlite3_exec(db, zSQL, 0, 0, 0);
638 **  sqlite3_free(zSQL);
639 ** </pre></blockquote>
640 **
641 ** Because the %q format string is used, the '\'' character in zText
642 ** is escaped and the SQL generated is as follows:
643 **
644 ** <blockquote><pre>
645 **  INSERT INTO table1 VALUES('It''s a happy day!')
646 ** </pre></blockquote>
647 **
648 ** This is correct.  Had we used %s instead of %q, the generated SQL
649 ** would have looked like this:
650 **
651 ** <blockquote><pre>
652 **  INSERT INTO table1 VALUES('It's a happy day!');
653 ** </pre></blockquote>
654 **
655 ** This second example is an SQL syntax error.  As a general rule you
656 ** should always use %q instead of %s when inserting text into a string 
657 ** literal.
658 **
659 ** The %Q option works like %q except it also adds single quotes around
660 ** the outside of the total string.  Or if the parameter in the argument
661 ** list is a NULL pointer, %Q substitutes the text "NULL" (without single
662 ** quotes) in place of the %Q option.  So, for example, one could say:
663 **
664 ** <blockquote><pre>
665 **  char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);
666 **  sqlite3_exec(db, zSQL, 0, 0, 0);
667 **  sqlite3_free(zSQL);
668 ** </pre></blockquote>
669 **
670 ** The code above will render a correct SQL statement in the zSQL
671 ** variable even if the zText variable is a NULL pointer.
672 */
673 char *sqlite3_mprintf(const char*,...);
674 char *sqlite3_vmprintf(const char*, va_list);
675 char *sqlite3_snprintf(int,char*,const char*, ...);
676
677 /*
678 ** CAPI3REF: Memory Allocation Functions
679 **
680 ** SQLite uses its own memory allocator.  On some installations, this
681 ** memory allocator is identical to the standard malloc()/realloc()/free()
682 ** and can be used interchangable.  On others, the implementations are
683 ** different.  For maximum portability, it is best not to mix calls
684 ** to the standard malloc/realloc/free with the sqlite versions.
685 */
686 void *sqlite3_malloc(int);
687 void *sqlite3_realloc(void*, int);
688 void sqlite3_free(void*);
689
690 /*
691 ** CAPI3REF: Compile-Time Authorization Callbacks
692 ***
693 ** This routine registers a authorizer callback with the SQLite library.  
694 ** The authorizer callback is invoked as SQL statements are being compiled
695 ** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()],
696 ** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()].  At various
697 ** points during the compilation process, as logic is being created
698 ** to perform various actions, the authorizer callback is invoked to
699 ** see if those actions are allowed.  The authorizer callback should
700 ** return SQLITE_OK to allow the action, [SQLITE_IGNORE] to disallow the
701 ** specific action but allow the SQL statement to continue to be
702 ** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be
703 ** rejected with an error.  
704 **
705 ** Depending on the action, the [SQLITE_IGNORE] and [SQLITE_DENY] return
706 ** codes might mean something different or they might mean the same
707 ** thing.  If the action is, for example, to perform a delete opertion,
708 ** then [SQLITE_IGNORE] and [SQLITE_DENY] both cause the statement compilation
709 ** to fail with an error.  But if the action is to read a specific column
710 ** from a specific table, then [SQLITE_DENY] will cause the entire
711 ** statement to fail but [SQLITE_IGNORE] will cause a NULL value to be
712 ** read instead of the actual column value.
713 **
714 ** The first parameter to the authorizer callback is a copy of
715 ** the third parameter to the sqlite3_set_authorizer() interface.
716 ** The second parameter to the callback is an integer 
717 ** [SQLITE_COPY | action code] that specifies the particular action
718 ** to be authorized.  The available action codes are
719 ** [SQLITE_COPY | documented separately].  The third through sixth
720 ** parameters to the callback are strings that contain additional
721 ** details about the action to be authorized.
722 **
723 ** An authorizer is used when preparing SQL statements from an untrusted
724 ** source, to ensure that the SQL statements do not try to access data
725 ** that they are not allowed to see, or that they do not try to
726 ** execute malicious statements that damage the database.  For
727 ** example, an application may allow a user to enter arbitrary
728 ** SQL queries for evaluation by a database.  But the application does
729 ** not want the user to be able to make arbitrary changes to the
730 ** database.  An authorizer could then be put in place while the
731 ** user-entered SQL is being prepared that disallows everything
732 ** except SELECT statements.  
733 **
734 ** Only a single authorizer can be in place on a database connection
735 ** at a time.  Each call to sqlite3_set_authorizer overrides the
736 ** previous call.  A NULL authorizer means that no authorization
737 ** callback is invoked.  The default authorizer is NULL.
738 **
739 ** Note that the authorizer callback is invoked only during 
740 ** [sqlite3_prepare()] or its variants.  Authorization is not
741 ** performed during statement evaluation in [sqlite3_step()].
742 */
743 int sqlite3_set_authorizer(
744   sqlite3*,
745   int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
746   void *pUserData
747 );
748
749 /*
750 ** CAPI3REF: Authorizer Return Codes
751 **
752 ** The [sqlite3_set_authorizer | authorizer callback function] must
753 ** return either [SQLITE_OK] or one of these two constants in order
754 ** to signal SQLite whether or not the action is permitted.  See the
755 ** [sqlite3_set_authorizer | authorizer documentation] for additional
756 ** information.
757 */
758 #define SQLITE_DENY   1   /* Abort the SQL statement with an error */
759 #define SQLITE_IGNORE 2   /* Don't allow access, but don't generate an error */
760
761 /*
762 ** CAPI3REF: Authorizer Action Codes
763 **
764 ** The [sqlite3_set_authorizer()] interface registers a callback function
765 ** that is invoked to authorizer certain SQL statement actions.  The
766 ** second parameter to the callback is an integer code that specifies
767 ** what action is being authorized.  These are the integer action codes that
768 ** the authorizer callback may be passed.
769 **
770 ** These action code values signify what kind of operation is to be 
771 ** authorized.  The 3rd and 4th parameters to the authorization callback
772 ** function will be parameters or NULL depending on which of these
773 ** codes is used as the second parameter.  The 5th parameter to the
774 ** authorizer callback is the name of the database ("main", "temp", 
775 ** etc.) if applicable.  The 6th parameter to the authorizer callback
776 ** is the name of the inner-most trigger or view that is responsible for
777 ** the access attempt or NULL if this access attempt is directly from 
778 ** top-level SQL code.
779 */
780 /******************************************* 3rd ************ 4th ***********/
781 #define SQLITE_CREATE_INDEX          1   /* Index Name      Table Name      */
782 #define SQLITE_CREATE_TABLE          2   /* Table Name      NULL            */
783 #define SQLITE_CREATE_TEMP_INDEX     3   /* Index Name      Table Name      */
784 #define SQLITE_CREATE_TEMP_TABLE     4   /* Table Name      NULL            */
785 #define SQLITE_CREATE_TEMP_TRIGGER   5   /* Trigger Name    Table Name      */
786 #define SQLITE_CREATE_TEMP_VIEW      6   /* View Name       NULL            */
787 #define SQLITE_CREATE_TRIGGER        7   /* Trigger Name    Table Name      */
788 #define SQLITE_CREATE_VIEW           8   /* View Name       NULL            */
789 #define SQLITE_DELETE                9   /* Table Name      NULL            */
790 #define SQLITE_DROP_INDEX           10   /* Index Name      Table Name      */
791 #define SQLITE_DROP_TABLE           11   /* Table Name      NULL            */
792 #define SQLITE_DROP_TEMP_INDEX      12   /* Index Name      Table Name      */
793 #define SQLITE_DROP_TEMP_TABLE      13   /* Table Name      NULL            */
794 #define SQLITE_DROP_TEMP_TRIGGER    14   /* Trigger Name    Table Name      */
795 #define SQLITE_DROP_TEMP_VIEW       15   /* View Name       NULL            */
796 #define SQLITE_DROP_TRIGGER         16   /* Trigger Name    Table Name      */
797 #define SQLITE_DROP_VIEW            17   /* View Name       NULL            */
798 #define SQLITE_INSERT               18   /* Table Name      NULL            */
799 #define SQLITE_PRAGMA               19   /* Pragma Name     1st arg or NULL */
800 #define SQLITE_READ                 20   /* Table Name      Column Name     */
801 #define SQLITE_SELECT               21   /* NULL            NULL            */
802 #define SQLITE_TRANSACTION          22   /* NULL            NULL            */
803 #define SQLITE_UPDATE               23   /* Table Name      Column Name     */
804 #define SQLITE_ATTACH               24   /* Filename        NULL            */
805 #define SQLITE_DETACH               25   /* Database Name   NULL            */
806 #define SQLITE_ALTER_TABLE          26   /* Database Name   Table Name      */
807 #define SQLITE_REINDEX              27   /* Index Name      NULL            */
808 #define SQLITE_ANALYZE              28   /* Table Name      NULL            */
809 #define SQLITE_CREATE_VTABLE        29   /* Table Name      Module Name     */
810 #define SQLITE_DROP_VTABLE          30   /* Table Name      Module Name     */
811 #define SQLITE_FUNCTION             31   /* Function Name   NULL            */
812 #define SQLITE_COPY                  0   /* No longer used */
813
814 /*
815 ** CAPI3REF: Tracing And Profiling Functions
816 **
817 ** These routines register callback functions that can be used for
818 ** tracing and profiling the execution of SQL statements.
819 ** The callback function registered by sqlite3_trace() is invoked
820 ** at the first [sqlite3_step()] for the evaluation of an SQL statement.
821 ** The callback function registered by sqlite3_profile() is invoked
822 ** as each SQL statement finishes and includes
823 ** information on how long that statement ran.
824 **
825 ** The sqlite3_profile() API is currently considered experimental and
826 ** is subject to change.
827 */
828 void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
829 void *sqlite3_profile(sqlite3*,
830    void(*xProfile)(void*,const char*,sqlite_uint64), void*);
831
832 /*
833 ** CAPI3REF: Query Progress Callbacks
834 **
835 ** This routine configures a callback function - the progress callback - that
836 ** is invoked periodically during long running calls to [sqlite3_exec()],
837 ** [sqlite3_step()] and [sqlite3_get_table()].  An example use for this 
838 ** interface is to keep a GUI updated during a large query.
839 **
840 ** The progress callback is invoked once for every N virtual machine opcodes,
841 ** where N is the second argument to this function. The progress callback
842 ** itself is identified by the third argument to this function. The fourth
843 ** argument to this function is a void pointer passed to the progress callback
844 ** function each time it is invoked.
845 **
846 ** If a call to [sqlite3_exec()], [sqlite3_step()], or [sqlite3_get_table()]
847 ** results in fewer than N opcodes being executed, then the progress 
848 ** callback is never invoked.
849 ** 
850 ** Only a single progress callback function may be registered for each
851 ** open database connection.  Every call to sqlite3_progress_handler()
852 ** overwrites the results of the previous call.
853 ** To remove the progress callback altogether, pass NULL as the third
854 ** argument to this function.
855 **
856 ** If the progress callback returns a result other than 0, then the current 
857 ** query is immediately terminated and any database changes rolled back.
858 ** The containing [sqlite3_exec()], [sqlite3_step()], or
859 ** [sqlite3_get_table()] call returns SQLITE_INTERRUPT.   This feature
860 ** can be used, for example, to implement the "Cancel" button on a
861 ** progress dialog box in a GUI.
862 */
863 void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
864
865 /*
866 ** CAPI3REF: Opening A New Database Connection
867 **
868 ** Open the sqlite database file "filename".  The "filename" is UTF-8
869 ** encoded for sqlite3_open() and UTF-16 encoded in the native byte order
870 ** for sqlite3_open16().  An [sqlite3*] handle is returned in *ppDb, even
871 ** if an error occurs. If the database is opened (or created) successfully,
872 ** then SQLITE_OK is returned. Otherwise an error code is returned. The
873 ** sqlite3_errmsg() or sqlite3_errmsg16()  routines can be used to obtain
874 ** an English language description of the error.
875 **
876 ** If the database file does not exist, then a new database will be created
877 ** as needed.  The default encoding for the database will be UTF-8 if
878 ** sqlite3_open() is called and UTF-16 if sqlite3_open16 is used.
879 **
880 ** Whether or not an error occurs when it is opened, resources associated
881 ** with the [sqlite3*] handle should be released by passing it to
882 ** sqlite3_close() when it is no longer required.
883 **
884 ** Note to windows users:  The encoding used for the filename argument
885 ** of sqlite3_open() must be UTF-8, not whatever codepage is currently
886 ** defined.  Filenames containing international characters must be converted
887 ** to UTF-8 prior to passing them into sqlite3_open().
888 */
889 int sqlite3_open(
890   const char *filename,   /* Database filename (UTF-8) */
891   sqlite3 **ppDb          /* OUT: SQLite db handle */
892 );
893 int sqlite3_open16(
894   const void *filename,   /* Database filename (UTF-16) */
895   sqlite3 **ppDb          /* OUT: SQLite db handle */
896 );
897
898 /*
899 ** CAPI3REF: Error Codes And Messages
900 **
901 ** The sqlite3_errcode() interface returns the numeric
902 ** [SQLITE_OK | result code] or [SQLITE_IOERR_READ | extended result code]
903 ** for the most recent failed sqlite3_* API call associated
904 ** with [sqlite3] handle 'db'.  If a prior API call failed but the
905 ** most recent API call succeeded, the return value from sqlite3_errcode()
906 ** is undefined. 
907 **
908 ** The sqlite3_errmsg() and sqlite3_errmsg16() return English-langauge
909 ** text that describes the error, as either UTF8 or UTF16 respectively.
910 ** Memory to hold the error message string is managed internally.  The 
911 ** string may be overwritten or deallocated by subsequent calls to SQLite
912 ** interface functions.
913 **
914 ** Calls to many sqlite3_* functions set the error code and string returned
915 ** by [sqlite3_errcode()], [sqlite3_errmsg()], and [sqlite3_errmsg16()]
916 ** (overwriting the previous values). Note that calls to [sqlite3_errcode()],
917 ** [sqlite3_errmsg()], and [sqlite3_errmsg16()] themselves do not affect the
918 ** results of future invocations.  Calls to API routines that do not return
919 ** an error code (examples: [sqlite3_data_count()] or [sqlite3_mprintf()]) do
920 ** not change the error code returned by this routine.
921 **
922 ** Assuming no other intervening sqlite3_* API calls are made, the error
923 ** code returned by this function is associated with the same error as
924 ** the strings returned by [sqlite3_errmsg()] and [sqlite3_errmsg16()].
925 */
926 int sqlite3_errcode(sqlite3 *db);
927 const char *sqlite3_errmsg(sqlite3*);
928 const void *sqlite3_errmsg16(sqlite3*);
929
930 /*
931 ** CAPI3REF: SQL Statement Object
932 **
933 ** Instance of this object represent single SQL statements.  This
934 ** is variously known as a "prepared statement" or a 
935 ** "compiled SQL statement" or simply as a "statement".
936 ** 
937 ** The life of a statement object goes something like this:
938 **
939 ** <ol>
940 ** <li> Create the object using [sqlite3_prepare_v2()] or a related
941 **      function.
942 ** <li> Bind values to host parameters using
943 **      [sqlite3_bind_blob | sqlite3_bind_* interfaces].
944 ** <li> Run the SQL by calling [sqlite3_step()] one or more times.
945 ** <li> Reset the statement using [sqlite3_reset()] then go back
946 **      to step 2.  Do this zero or more times.
947 ** <li> Destroy the object using [sqlite3_finalize()].
948 ** </ol>
949 **
950 ** Refer to documentation on individual methods above for additional
951 ** information.
952 */
953 typedef struct sqlite3_stmt sqlite3_stmt;
954
955 /*
956 ** CAPI3REF: Compiling An SQL Statement
957 **
958 ** To execute an SQL query, it must first be compiled into a byte-code
959 ** program using one of these routines. 
960 **
961 ** The first argument "db" is an [sqlite3 | SQLite database handle] 
962 ** obtained from a prior call to [sqlite3_open()] or [sqlite3_open16()].
963 ** The second argument "zSql" is the statement to be compiled, encoded
964 ** as either UTF-8 or UTF-16.  The sqlite3_prepare() and sqlite3_prepare_v2()
965 ** interfaces uses UTF-8 and sqlite3_prepare16() and sqlite3_prepare16_v2()
966 ** use UTF-16. If the next argument, "nBytes", is less
967 ** than zero, then zSql is read up to the first zero terminator.  If
968 ** "nBytes" is not less than zero, then it is the length of the string zSql
969 ** in bytes (not characters).
970 **
971 ** *pzTail is made to point to the first byte past the end of the first
972 ** SQL statement in zSql.  This routine only compiles the first statement
973 ** in zSql, so *pzTail is left pointing to what remains uncompiled.
974 **
975 ** *ppStmt is left pointing to a compiled 
976 ** [sqlite3_stmt | SQL statement structure] that can be
977 ** executed using [sqlite3_step()].  Or if there is an error, *ppStmt may be
978 ** set to NULL.  If the input text contained no SQL (if the input is and
979 ** empty string or a comment) then *ppStmt is set to NULL.  The calling
980 ** procedure is responsible for deleting the compiled SQL statement
981 ** using [sqlite3_finalize()] after it has finished with it.
982 **
983 ** On success, [SQLITE_OK] is returned.  Otherwise an 
984 ** [SQLITE_ERROR | error code] is returned.
985 **
986 ** The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are
987 ** recommended for all new programs. The two older interfaces are retained
988 ** for backwards compatibility, but their use is discouraged.
989 ** In the "v2" interfaces, the prepared statement
990 ** that is returned (the [sqlite3_stmt] object) contains a copy of the 
991 ** original SQL text. This causes the [sqlite3_step()] interface to
992 ** behave a differently in two ways:
993 **
994 ** <ol>
995 ** <li>
996 ** If the database schema changes, instead of returning [SQLITE_SCHEMA] as it
997 ** always used to do, [sqlite3_step()] will automatically recompile the SQL
998 ** statement and try to run it again.  If the schema has changed in a way
999 ** that makes the statement no longer valid, [sqlite3_step()] will still
1000 ** return [SQLITE_SCHEMA].  But unlike the legacy behavior, [SQLITE_SCHEMA] is
1001 ** now a fatal error.  Calling [sqlite3_prepare_v2()] again will not make the
1002 ** error go away.  Note: use [sqlite3_errmsg()] to find the text of the parsing
1003 ** error that results in an [SQLITE_SCHEMA] return.
1004 ** </li>
1005 **
1006 ** <li>
1007 ** When an error occurs, 
1008 ** [sqlite3_step()] will return one of the detailed 
1009 ** [SQLITE_ERROR | result codes] or
1010 ** [SQLITE_IOERR_READ | extended result codes] such as directly.
1011 ** The legacy behavior was that [sqlite3_step()] would only return a generic
1012 ** [SQLITE_ERROR] result code and you would have to make a second call to
1013 ** [sqlite3_reset()] in order to find the underlying cause of the problem.
1014 ** With the "v2" prepare interfaces, the underlying reason for the error is
1015 ** returned immediately.
1016 ** </li>
1017 ** </ol>
1018 */
1019 int sqlite3_prepare(
1020   sqlite3 *db,            /* Database handle */
1021   const char *zSql,       /* SQL statement, UTF-8 encoded */
1022   int nBytes,             /* Length of zSql in bytes. */
1023   sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
1024   const char **pzTail     /* OUT: Pointer to unused portion of zSql */
1025 );
1026 int sqlite3_prepare_v2(
1027   sqlite3 *db,            /* Database handle */
1028   const char *zSql,       /* SQL statement, UTF-8 encoded */
1029   int nBytes,             /* Length of zSql in bytes. */
1030   sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
1031   const char **pzTail     /* OUT: Pointer to unused portion of zSql */
1032 );
1033 int sqlite3_prepare16(
1034   sqlite3 *db,            /* Database handle */
1035   const void *zSql,       /* SQL statement, UTF-16 encoded */
1036   int nBytes,             /* Length of zSql in bytes. */
1037   sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
1038   const void **pzTail     /* OUT: Pointer to unused portion of zSql */
1039 );
1040 int sqlite3_prepare16_v2(
1041   sqlite3 *db,            /* Database handle */
1042   const void *zSql,       /* SQL statement, UTF-16 encoded */
1043   int nBytes,             /* Length of zSql in bytes. */
1044   sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
1045   const void **pzTail     /* OUT: Pointer to unused portion of zSql */
1046 );
1047
1048 /*
1049 ** CAPI3REF:  Dynamically Typed Value Object
1050 **
1051 ** SQLite uses dynamic typing for the values it stores.  Values can 
1052 ** be integers, floating point values, strings, BLOBs, or NULL.  When
1053 ** passing around values internally, each value is represented as
1054 ** an instance of the sqlite3_value object.
1055 */
1056 typedef struct Mem sqlite3_value;
1057
1058 /*
1059 ** CAPI3REF:  SQL Function Context Object
1060 **
1061 ** The context in which an SQL function executes is stored in an
1062 ** sqlite3_context object.  A pointer to such an object is the
1063 ** first parameter to user-defined SQL functions.
1064 */
1065 typedef struct sqlite3_context sqlite3_context;
1066
1067 /*
1068 ** CAPI3REF:  Binding Values To Prepared Statements
1069 **
1070 ** In the SQL strings input to [sqlite3_prepare_v2()] and its variants,
1071 ** one or more literals can be replace by a parameter in one of these
1072 ** forms:
1073 **
1074 ** <ul>
1075 ** <li>  ?
1076 ** <li>  ?NNN
1077 ** <li>  :AAA
1078 ** <li>  @AAA
1079 ** <li>  $VVV
1080 ** </ul>
1081 **
1082 ** In the parameter forms shown above NNN is an integer literal,
1083 ** AAA is an alphanumeric identifier and VVV is a variable name according
1084 ** to the syntax rules of the TCL programming language.
1085 ** The values of these parameters (also called "host parameter names")
1086 ** can be set using the sqlite3_bind_*() routines defined here.
1087 **
1088 ** The first argument to the sqlite3_bind_*() routines always is a pointer
1089 ** to the [sqlite3_stmt] object returned from [sqlite3_prepare_v2()] or
1090 ** its variants.  The second
1091 ** argument is the index of the parameter to be set.  The first parameter has
1092 ** an index of 1. When the same named parameter is used more than once, second
1093 ** and subsequent
1094 ** occurrences have the same index as the first occurrence.  The index for
1095 ** named parameters can be looked up using the
1096 ** [sqlite3_bind_parameter_name()] API if desired.  The index for "?NNN"
1097 ** parametes is the value of NNN.
1098 ** The NNN value must be between 1 and the compile-time
1099 ** parameter SQLITE_MAX_VARIABLE_NUMBER (default value: 999).
1100 ** See <a href="limits.html">limits.html</a> for additional information.
1101 **
1102 ** The third argument is the value to bind to the parameter.
1103 **
1104 ** In those
1105 ** routines that have a fourth argument, its value is the number of bytes
1106 ** in the parameter.  To be clear: the value is the number of bytes in the
1107 ** string, not the number of characters.  The number
1108 ** of bytes does not include the zero-terminator at the end of strings.
1109 ** If the fourth parameter is negative, the length of the string is
1110 ** number of bytes up to the first zero terminator.
1111 **
1112 ** The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and
1113 ** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or
1114 ** text after SQLite has finished with it.  If the fifth argument is the
1115 ** special value [SQLITE_STATIC], then the library assumes that the information
1116 ** is in static, unmanaged space and does not need to be freed.  If the
1117 ** fifth argument has the value [SQLITE_TRANSIENT], then SQLite makes its
1118 ** own private copy of the data immediately, before the sqlite3_bind_*()
1119 ** routine returns.
1120 **
1121 ** The sqlite3_bind_zeroblob() routine binds a BLOB of length n that
1122 ** is filled with zeros.  A zeroblob uses a fixed amount of memory
1123 ** (just an integer to hold it size) while it is being processed.
1124 ** Zeroblobs are intended to serve as place-holders for BLOBs whose
1125 ** content is later written using 
1126 ** [sqlite3_blob_open | increment BLOB I/O] routines.
1127 **
1128 ** The sqlite3_bind_*() routines must be called after
1129 ** [sqlite3_prepare_v2()] (and its variants) or [sqlite3_reset()] and
1130 ** before [sqlite3_step()].
1131 ** Bindings are not cleared by the [sqlite3_reset()] routine.
1132 ** Unbound parameters are interpreted as NULL.
1133 **
1134 ** These routines return [SQLITE_OK] on success or an error code if
1135 ** anything goes wrong.  [SQLITE_RANGE] is returned if the parameter
1136 ** index is out of range.  [SQLITE_NOMEM] is returned if malloc fails.
1137 ** [SQLITE_MISUSE] is returned if these routines are called on a virtual
1138 ** machine that is the wrong state or which has already been finalized.
1139 */
1140 int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
1141 int sqlite3_bind_double(sqlite3_stmt*, int, double);
1142 int sqlite3_bind_int(sqlite3_stmt*, int, int);
1143 int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite_int64);
1144 int sqlite3_bind_null(sqlite3_stmt*, int);
1145 int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
1146 int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
1147 int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
1148 int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
1149
1150 /*
1151 ** CAPI3REF: Number Of Host Parameters
1152 **
1153 ** Return the largest host parameter index in the precompiled statement given
1154 ** as the argument.  When the host parameters are of the forms like ":AAA"
1155 ** or "?", then they are assigned sequential increasing numbers beginning
1156 ** with one, so the value returned is the number of parameters.  However
1157 ** if the same host parameter name is used multiple times, each occurrance
1158 ** is given the same number, so the value returned in that case is the number
1159 ** of unique host parameter names.  If host parameters of the form "?NNN"
1160 ** are used (where NNN is an integer) then there might be gaps in the
1161 ** numbering and the value returned by this interface is the index of the
1162 ** host parameter with the largest index value.
1163 */
1164 int sqlite3_bind_parameter_count(sqlite3_stmt*);
1165
1166 /*
1167 ** CAPI3REF: Name Of A Host Parameter
1168 **
1169 ** This routine returns a pointer to the name of the n-th parameter in a 
1170 ** [sqlite3_stmt | prepared statement].
1171 ** Host parameters of the form ":AAA" or "@AAA" or "$VVV" have a name
1172 ** which is the string ":AAA" or "@AAA" or "$VVV".  
1173 ** In other words, the initial ":" or "$" or "@"
1174 ** is included as part of the name.
1175 ** Parameters of the form "?" or "?NNN" have no name.
1176 **
1177 ** The first bound parameter has an index of 1, not 0.
1178 **
1179 ** If the value n is out of range or if the n-th parameter is nameless,
1180 ** then NULL is returned.  The returned string is always in the
1181 ** UTF-8 encoding even if the named parameter was originally specified
1182 ** as UTF-16 in [sqlite3_prepare16()] or [sqlite3_prepare16_v2()].
1183 */
1184 const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
1185
1186 /*
1187 ** CAPI3REF: Index Of A Parameter With A Given Name
1188 **
1189 ** This routine returns the index of a host parameter with the given name.
1190 ** The name must match exactly.  If no parameter with the given name is 
1191 ** found, return 0.  Parameter names must be UTF8.
1192 */
1193 int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
1194
1195 /*
1196 ** CAPI3REF: Reset All Bindings On A Prepared Statement
1197 **
1198 ** Contrary to the intuition of many, [sqlite3_reset()] does not
1199 ** reset the [sqlite3_bind_blob | bindings] on a 
1200 ** [sqlite3_stmt | prepared statement].  Use this routine to
1201 ** reset all host parameters to NULL.
1202 */
1203 int sqlite3_clear_bindings(sqlite3_stmt*);
1204
1205 /*
1206 ** CAPI3REF: Number Of Columns In A Result Set
1207 **
1208 ** Return the number of columns in the result set returned by the 
1209 ** [sqlite3_stmt | compiled SQL statement]. This routine returns 0
1210 ** if pStmt is an SQL statement that does not return data (for 
1211 ** example an UPDATE).
1212 */
1213 int sqlite3_column_count(sqlite3_stmt *pStmt);
1214
1215 /*
1216 ** CAPI3REF: Column Names In A Result Set
1217 **
1218 ** These routines return the name assigned to a particular column
1219 ** in the result set of a SELECT statement.  The sqlite3_column_name()
1220 ** interface returns a pointer to a UTF8 string and sqlite3_column_name16()
1221 ** returns a pointer to a UTF16 string.  The first parameter is the
1222 ** [sqlite_stmt | prepared statement] that implements the SELECT statement.
1223 ** The second parameter is the column number.  The left-most column is
1224 ** number 0.
1225 **
1226 ** The returned string pointer is valid until either the 
1227 ** [sqlite_stmt | prepared statement] is destroyed by [sqlite3_finalize()]
1228 ** or until the next call sqlite3_column_name() or sqlite3_column_name16()
1229 ** on the same column.
1230 */
1231 const char *sqlite3_column_name(sqlite3_stmt*, int N);
1232 const void *sqlite3_column_name16(sqlite3_stmt*, int N);
1233
1234 /*
1235 ** CAPI3REF: Source Of Data In A Query Result
1236 **
1237 ** These routines provide a means to determine what column of what
1238 ** table in which database a result of a SELECT statement comes from.
1239 ** The name of the database or table or column can be returned as
1240 ** either a UTF8 or UTF16 string.  The returned string is valid until
1241 ** the [sqlite3_stmt | prepared statement] is destroyed using
1242 ** [sqlite3_finalize()] or until the same information is requested
1243 ** again about the same column.
1244 **
1245 ** The first argument to the following calls is a 
1246 ** [sqlite3_stmt | compiled SQL statement].
1247 ** These functions return information about the Nth column returned by 
1248 ** the statement, where N is the second function argument.
1249 **
1250 ** If the Nth column returned by the statement is an expression
1251 ** or subquery and is not a column value, then all of these functions
1252 ** return NULL. Otherwise, they return the 
1253 ** name of the attached database, table and column that query result
1254 ** column was extracted from.
1255 **
1256 ** As with all other SQLite APIs, those postfixed with "16" return UTF-16
1257 ** encoded strings, the other functions return UTF-8.
1258 **
1259 ** These APIs are only available if the library was compiled with the 
1260 ** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined.
1261 */
1262 const char *sqlite3_column_database_name(sqlite3_stmt*,int);
1263 const void *sqlite3_column_database_name16(sqlite3_stmt*,int);
1264 const char *sqlite3_column_table_name(sqlite3_stmt*,int);
1265 const void *sqlite3_column_table_name16(sqlite3_stmt*,int);
1266 const char *sqlite3_column_origin_name(sqlite3_stmt*,int);
1267 const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);
1268
1269 /*
1270 ** CAPI3REF: Declared Datatype Of A Query Result
1271 **
1272 ** The first parameter is a [sqlite3_stmt | compiled SQL statement]. 
1273 ** If this statement is a SELECT statement and the Nth column of the 
1274 ** returned result set  of that SELECT is a table column (not an
1275 ** expression or subquery) then the declared type of the table
1276 ** column is returned. If the Nth column of the result set is an
1277 ** expression or subquery, then a NULL pointer is returned.
1278 ** The returned string is always UTF-8 encoded. For example, in
1279 ** the database schema:
1280 **
1281 ** CREATE TABLE t1(c1 VARIANT);
1282 **
1283 ** And the following statement compiled:
1284 **
1285 ** SELECT c1 + 1, c1 FROM t1;
1286 **
1287 ** Then this routine would return the string "VARIANT" for the second
1288 ** result column (i==1), and a NULL pointer for the first result column
1289 ** (i==0).
1290 **
1291 ** SQLite uses dynamic run-time typing.  So just because a column
1292 ** is declared to contain a particular type does not mean that the
1293 ** data stored in that column is of the declared type.  SQLite is
1294 ** strongly typed, but the typing is dynamic not static.  Type
1295 ** is associated with individual values, not with the containers
1296 ** used to hold those values.
1297 */
1298 const char *sqlite3_column_decltype(sqlite3_stmt *, int i);
1299 const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
1300
1301 /* 
1302 ** CAPI3REF:  Evaluate An SQL Statement
1303 **
1304 ** After an [sqlite3_stmt | SQL statement] has been prepared with a call
1305 ** to either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or to one of
1306 ** the legacy interfaces [sqlite3_prepare()] or [sqlite3_prepare16()],
1307 ** then this function must be called one or more times to evaluate the 
1308 ** statement.
1309 **
1310 ** The details of the behavior of this sqlite3_step() interface depend
1311 ** on whether the statement was prepared using the newer "v2" interface
1312 ** [sqlite3_prepare_v2()] and [sqlite3_prepare16_v2()] or the older legacy
1313 ** interface [sqlite3_prepare()] and [sqlite3_prepare16()].  The use of the
1314 ** new "v2" interface is recommended for new applications but the legacy
1315 ** interface will continue to be supported.
1316 **
1317 ** In the lagacy interface, the return value will be either [SQLITE_BUSY], 
1318 ** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE].
1319 ** With the "v2" interface, any of the other [SQLITE_OK | result code]
1320 ** or [SQLITE_IOERR_READ | extended result code] might be returned as
1321 ** well.
1322 **
1323 ** [SQLITE_BUSY] means that the database engine was unable to acquire the
1324 ** database locks it needs to do its job.  If the statement is a COMMIT
1325 ** or occurs outside of an explicit transaction, then you can retry the
1326 ** statement.  If the statement is not a COMMIT and occurs within a
1327 ** explicit transaction then you should rollback the transaction before
1328 ** continuing.
1329 **
1330 ** [SQLITE_DONE] means that the statement has finished executing
1331 ** successfully.  sqlite3_step() should not be called again on this virtual
1332 ** machine without first calling [sqlite3_reset()] to reset the virtual
1333 ** machine back to its initial state.
1334 **
1335 ** If the SQL statement being executed returns any data, then 
1336 ** [SQLITE_ROW] is returned each time a new row of data is ready
1337 ** for processing by the caller. The values may be accessed using
1338 ** the [sqlite3_column_int | column access functions].
1339 ** sqlite3_step() is called again to retrieve the next row of data.
1340 ** 
1341 ** [SQLITE_ERROR] means that a run-time error (such as a constraint
1342 ** violation) has occurred.  sqlite3_step() should not be called again on
1343 ** the VM. More information may be found by calling [sqlite3_errmsg()].
1344 ** With the legacy interface, a more specific error code (example:
1345 ** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth)
1346 ** can be obtained by calling [sqlite3_reset()] on the
1347 ** [sqlite_stmt | prepared statement].  In the "v2" interface,
1348 ** the more specific error code is returned directly by sqlite3_step().
1349 **
1350 ** [SQLITE_MISUSE] means that the this routine was called inappropriately.
1351 ** Perhaps it was called on a [sqlite_stmt | prepared statement] that has
1352 ** already been [sqlite3_finalize | finalized] or on one that had 
1353 ** previously returned [SQLITE_ERROR] or [SQLITE_DONE].  Or it could
1354 ** be the case that the same database connection is being used by two or
1355 ** more threads at the same moment in time.
1356 **
1357 ** <b>Goofy Interface Alert:</b>
1358 ** In the legacy interface, 
1359 ** the sqlite3_step() API always returns a generic error code,
1360 ** [SQLITE_ERROR], following any error other than [SQLITE_BUSY]
1361 ** and [SQLITE_MISUSE].  You must call [sqlite3_reset()] or
1362 ** [sqlite3_finalize()] in order to find one of the specific
1363 ** [SQLITE_ERROR | result codes] that better describes the error.
1364 ** We admit that this is a goofy design.  The problem has been fixed
1365 ** with the "v2" interface.  If you prepare all of your SQL statements
1366 ** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead
1367 ** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()], then the 
1368 ** more specific [SQLITE_ERROR | result codes] are returned directly
1369 ** by sqlite3_step().  The use of the "v2" interface is recommended.
1370 */
1371 int sqlite3_step(sqlite3_stmt*);
1372
1373 /*
1374 ** CAPI3REF:
1375 **
1376 ** Return the number of values in the current row of the result set.
1377 **
1378 ** After a call to [sqlite3_step()] that returns [SQLITE_ROW], this routine
1379 ** will return the same value as the [sqlite3_column_count()] function.
1380 ** After [sqlite3_step()] has returned an [SQLITE_DONE], [SQLITE_BUSY], or
1381 ** a [SQLITE_ERROR | error code], or before [sqlite3_step()] has been 
1382 ** called on the [sqlite_stmt | prepared statement] for the first time,
1383 ** this routine returns zero.
1384 */
1385 int sqlite3_data_count(sqlite3_stmt *pStmt);
1386
1387 /*
1388 ** CAPI3REF: Fundamental Datatypes
1389 **
1390 ** Every value in SQLite has one of five fundamental datatypes:
1391 **
1392 ** <ul>
1393 ** <li> 64-bit signed integer
1394 ** <li> 64-bit IEEE floating point number
1395 ** <li> string
1396 ** <li> BLOB
1397 ** <li> NULL
1398 ** </ul>
1399 **
1400 ** These constants are codes for each of those types.
1401 **
1402 ** Note that the SQLITE_TEXT constant was also used in SQLite version 2
1403 ** for a completely different meaning.  Software that links against both
1404 ** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT not
1405 ** SQLITE_TEXT.
1406 */
1407 #define SQLITE_INTEGER  1
1408 #define SQLITE_FLOAT    2
1409 #define SQLITE_BLOB     4
1410 #define SQLITE_NULL     5
1411 #ifdef SQLITE_TEXT
1412 # undef SQLITE_TEXT
1413 #else
1414 # define SQLITE_TEXT     3
1415 #endif
1416 #define SQLITE3_TEXT     3
1417
1418 /*
1419 ** CAPI3REF: Results Values From A Query
1420 **
1421 ** These routines return information about the information
1422 ** in a single column of the current result row of a query.  In every
1423 ** case the first argument is a pointer to the 
1424 ** [sqlite3_stmt | SQL statement] that is being
1425 ** evaluate (the [sqlite_stmt*] that was returned from 
1426 ** [sqlite3_prepare_v2()] or one of its variants) and
1427 ** the second argument is the index of the column for which information 
1428 ** should be returned.  The left-most column has an index of 0.
1429 **
1430 ** If the SQL statement is not currently point to a valid row, or if the
1431 ** the column index is out of range, the result is undefined.
1432 **
1433 ** The sqlite3_column_type() routine returns 
1434 ** [SQLITE_INTEGER | datatype code] for the initial data type
1435 ** of the result column.  The returned value is one of [SQLITE_INTEGER],
1436 ** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL].  The value
1437 ** returned by sqlite3_column_type() is only meaningful if no type
1438 ** conversions have occurred as described below.  After a type conversion,
1439 ** the value returned by sqlite3_column_type() is undefined.  Future
1440 ** versions of SQLite may change the behavior of sqlite3_column_type()
1441 ** following a type conversion.
1442 **
1443 *** The sqlite3_column_nm
1444 **
1445 ** If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes() 
1446 ** routine returns the number of bytes in that BLOB or string.
1447 ** If the result is a UTF-16 string, then sqlite3_column_bytes() converts
1448 ** the string to UTF-8 and then returns the number of bytes.
1449 ** If the result is a numeric value then sqlite3_column_bytes() uses
1450 ** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns
1451 ** the number of bytes in that string.
1452 ** The value returned does not include the zero terminator at the end
1453 ** of the string.  For clarity: the value returned is the number of
1454 ** bytes in the string, not the number of characters.
1455 **
1456 ** The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes()
1457 ** but leaves the result in UTF-16 instead of UTF-8.  
1458 ** The zero terminator is not included in this count.
1459 **
1460 ** These routines attempt to convert the value where appropriate.  For
1461 ** example, if the internal representation is FLOAT and a text result
1462 ** is requested, [sqlite3_snprintf()] is used internally to do the conversion
1463 ** automatically.  The following table details the conversions that
1464 ** are applied:
1465 **
1466 ** <blockquote>
1467 ** <table border="1">
1468 ** <tr><th> Internal <th> Requested <th> 
1469 ** <tr><th>  Type    <th>    Type   <th> Conversion
1470 **
1471 ** <tr><td>  NULL    <td> INTEGER   <td> Result is 0
1472 ** <tr><td>  NULL    <td>  FLOAT    <td> Result is 0.0
1473 ** <tr><td>  NULL    <td>   TEXT    <td> Result is NULL pointer
1474 ** <tr><td>  NULL    <td>   BLOB    <td> Result is NULL pointer
1475 ** <tr><td> INTEGER  <td>  FLOAT    <td> Convert from integer to float
1476 ** <tr><td> INTEGER  <td>   TEXT    <td> ASCII rendering of the integer
1477 ** <tr><td> INTEGER  <td>   BLOB    <td> Same as for INTEGER->TEXT
1478 ** <tr><td>  FLOAT   <td> INTEGER   <td> Convert from float to integer
1479 ** <tr><td>  FLOAT   <td>   TEXT    <td> ASCII rendering of the float
1480 ** <tr><td>  FLOAT   <td>   BLOB    <td> Same as FLOAT->TEXT
1481 ** <tr><td>  TEXT    <td> INTEGER   <td> Use atoi()
1482 ** <tr><td>  TEXT    <td>  FLOAT    <td> Use atof()
1483 ** <tr><td>  TEXT    <td>   BLOB    <td> No change
1484 ** <tr><td>  BLOB    <td> INTEGER   <td> Convert to TEXT then use atoi()
1485 ** <tr><td>  BLOB    <td>  FLOAT    <td> Convert to TEXT then use atof()
1486 ** <tr><td>  BLOB    <td>   TEXT    <td> Add a zero terminator if needed
1487 ** </table>
1488 ** </blockquote>
1489 **
1490 ** The table above makes reference to standard C library functions atoi()
1491 ** and atof().  SQLite does not really use these functions.  It has its
1492 ** on equavalent internal routines.  The atoi() and atof() names are
1493 ** used in the table for brevity and because they are familiar to most
1494 ** C programmers.
1495 **
1496 ** Note that when type conversions occur, pointers returned by prior
1497 ** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
1498 ** sqlite3_column_text16() may be invalidated. 
1499 ** Type conversions and pointer invalidations might occur
1500 ** in the following cases:
1501 **
1502 ** <ul>
1503 ** <li><p>  The initial content is a BLOB and sqlite3_column_text() 
1504 **          or sqlite3_column_text16() is called.  A zero-terminator might
1505 **          need to be added to the string.</p></li>
1506 **
1507 ** <li><p>  The initial content is UTF-8 text and sqlite3_column_bytes16() or
1508 **          sqlite3_column_text16() is called.  The content must be converted
1509 **          to UTF-16.</p></li>
1510 **
1511 ** <li><p>  The initial content is UTF-16 text and sqlite3_column_bytes() or
1512 **          sqlite3_column_text() is called.  The content must be converted
1513 **          to UTF-8.</p></li>
1514 ** </ul>
1515 **
1516 ** Conversions between UTF-16be and UTF-16le are always done in place and do
1517 ** not invalidate a prior pointer, though of course the content of the buffer
1518 ** that the prior pointer points to will have been modified.  Other kinds
1519 ** of conversion are done in place when it is possible, but sometime it is
1520 ** not possible and in those cases prior pointers are invalidated.  
1521 **
1522 ** The safest and easiest to remember policy is to invoke these routines
1523 ** in one of the following ways:
1524 **
1525 **  <ul>
1526 **  <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li>
1527 **  <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li>
1528 **  <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li>
1529 **  </ul>
1530 **
1531 ** In other words, you should call sqlite3_column_text(), sqlite3_column_blob(),
1532 ** or sqlite3_column_text16() first to force the result into the desired
1533 ** format, then invoke sqlite3_column_bytes() or sqlite3_column_bytes16() to
1534 ** find the size of the result.  Do not mix call to sqlite3_column_text() or
1535 ** sqlite3_column_blob() with calls to sqlite3_column_bytes16().  And do not
1536 ** mix calls to sqlite3_column_text16() with calls to sqlite3_column_bytes().
1537 */
1538 const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
1539 int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
1540 int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
1541 double sqlite3_column_double(sqlite3_stmt*, int iCol);
1542 int sqlite3_column_int(sqlite3_stmt*, int iCol);
1543 sqlite_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
1544 const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
1545 const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
1546 int sqlite3_column_type(sqlite3_stmt*, int iCol);
1547 sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
1548
1549 /*
1550 ** CAPI3REF: Destroy A Prepared Statement Object
1551 **
1552 ** The sqlite3_finalize() function is called to delete a 
1553 ** [sqlite3_stmt | compiled SQL statement]. If the statement was
1554 ** executed successfully, or not executed at all, then SQLITE_OK is returned.
1555 ** If execution of the statement failed then an 
1556 ** [SQLITE_ERROR | error code] or [SQLITE_IOERR_READ | extended error code]
1557 ** is returned. 
1558 **
1559 ** This routine can be called at any point during the execution of the
1560 ** [sqlite3_stmt | virtual machine].  If the virtual machine has not 
1561 ** completed execution when this routine is called, that is like
1562 ** encountering an error or an interrupt.  (See [sqlite3_interrupt()].) 
1563 ** Incomplete updates may be rolled back and transactions cancelled,  
1564 ** depending on the circumstances, and the 
1565 ** [SQLITE_ERROR | result code] returned will be [SQLITE_ABORT].
1566 */
1567 int sqlite3_finalize(sqlite3_stmt *pStmt);
1568
1569 /*
1570 ** CAPI3REF: Reset A Prepared Statement Object
1571 **
1572 ** The sqlite3_reset() function is called to reset a 
1573 ** [sqlite_stmt | compiled SQL statement] object.
1574 ** back to it's initial state, ready to be re-executed.
1575 ** Any SQL statement variables that had values bound to them using
1576 ** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values.
1577 ** Use [sqlite3_clear_bindings()] to reset the bindings.
1578 */
1579 int sqlite3_reset(sqlite3_stmt *pStmt);
1580
1581 /*
1582 ** CAPI3REF: Create Or Redefine SQL Functions
1583 **
1584 ** The following two functions are used to add SQL functions or aggregates
1585 ** or to redefine the behavior of existing SQL functions or aggregates.  The
1586 ** difference only between the two is that the second parameter, the
1587 ** name of the (scalar) function or aggregate, is encoded in UTF-8 for
1588 ** sqlite3_create_function() and UTF-16 for sqlite3_create_function16().
1589 **
1590 ** The first argument is the [sqlite3 | database handle] that holds the
1591 ** SQL function or aggregate is to be added or redefined. If a single
1592 ** program uses more than one database handle internally, then SQL
1593 ** functions or aggregates must be added individually to each database
1594 ** handle with which they will be used.
1595 **
1596 ** The second parameter is the name of the SQL function to be created
1597 ** or redefined.
1598 ** The length of the name is limited to 255 bytes, exclusive of the 
1599 ** zero-terminator.  Note that the name length limit is in bytes, not
1600 ** characters.  Any attempt to create a function with a longer name
1601 ** will result in an SQLITE_ERROR error.
1602 **
1603 ** The third parameter is the number of arguments that the SQL function or
1604 ** aggregate takes. If this parameter is negative, then the SQL function or
1605 ** aggregate may take any number of arguments.
1606 **
1607 ** The fourth parameter, eTextRep, specifies what 
1608 ** [SQLITE_UTF8 | text encoding] this SQL function prefers for
1609 ** its parameters.  Any SQL function implementation should be able to work
1610 ** work with UTF-8, UTF-16le, or UTF-16be.  But some implementations may be
1611 ** more efficient with one encoding than another.  It is allowed to
1612 ** invoke sqlite_create_function() or sqlite3_create_function16() multiple
1613 ** times with the same function but with different values of eTextRep.
1614 ** When multiple implementations of the same function are available, SQLite
1615 ** will pick the one that involves the least amount of data conversion.
1616 ** If there is only a single implementation which does not care what
1617 ** text encoding is used, then the fourth argument should be
1618 ** [SQLITE_ANY].
1619 **
1620 ** The fifth parameter is an arbitrary pointer.  The implementation
1621 ** of the function can gain access to this pointer using
1622 ** [sqlite_user_data()].
1623 **
1624 ** The seventh, eighth and ninth parameters, xFunc, xStep and xFinal, are
1625 ** pointers to C-language functions that implement the SQL
1626 ** function or aggregate. A scalar SQL function requires an implementation of
1627 ** the xFunc callback only, NULL pointers should be passed as the xStep
1628 ** and xFinal parameters. An aggregate SQL function requires an implementation
1629 ** of xStep and xFinal and NULL should be passed for xFunc. To delete an
1630 ** existing SQL function or aggregate, pass NULL for all three function
1631 ** callback.
1632 **
1633 ** It is permitted to register multiple implementations of the same
1634 ** functions with the same name but with either differing numbers of
1635 ** arguments or differing perferred text encodings.  SQLite will use
1636 ** the implementation most closely matches the way in which the
1637 ** SQL function is used.
1638 */
1639 int sqlite3_create_function(
1640   sqlite3 *,
1641   const char *zFunctionName,
1642   int nArg,
1643   int eTextRep,
1644   void*,
1645   void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
1646   void (*xStep)(sqlite3_context*,int,sqlite3_value**),
1647   void (*xFinal)(sqlite3_context*)
1648 );
1649 int sqlite3_create_function16(
1650   sqlite3*,
1651   const void *zFunctionName,
1652   int nArg,
1653   int eTextRep,
1654   void*,
1655   void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
1656   void (*xStep)(sqlite3_context*,int,sqlite3_value**),
1657   void (*xFinal)(sqlite3_context*)
1658 );
1659
1660 /*
1661 ** CAPI3REF: Text Encodings
1662 **
1663 ** These constant define integer codes that represent the various
1664 ** text encodings supported by SQLite.
1665 */
1666 #define SQLITE_UTF8           1
1667 #define SQLITE_UTF16LE        2
1668 #define SQLITE_UTF16BE        3
1669 #define SQLITE_UTF16          4    /* Use native byte order */
1670 #define SQLITE_ANY            5    /* sqlite3_create_function only */
1671 #define SQLITE_UTF16_ALIGNED  8    /* sqlite3_create_collation only */
1672
1673 /*
1674 ** CAPI3REF: Obsolete Functions
1675 **
1676 ** These functions are all now obsolete.  In order to maintain
1677 ** backwards compatibility with older code, we continue to support
1678 ** these functions.  However, new development projects should avoid
1679 ** the use of these functions.  To help encourage people to avoid
1680 ** using these functions, we are not going to tell you want they do.
1681 */
1682 int sqlite3_aggregate_count(sqlite3_context*);
1683 int sqlite3_expired(sqlite3_stmt*);
1684 int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
1685 int sqlite3_global_recover(void);
1686
1687
1688 /*
1689 ** CAPI3REF: Obtaining SQL Function Parameter Values
1690 **
1691 ** The C-language implementation of SQL functions and aggregates uses
1692 ** this set of interface routines to access the parameter values on
1693 ** the function or aggregate.
1694 **
1695 ** The xFunc (for scalar functions) or xStep (for aggregates) parameters
1696 ** to [sqlite3_create_function()] and [sqlite3_create_function16()]
1697 ** define callbacks that implement the SQL functions and aggregates.
1698 ** The 4th parameter to these callbacks is an array of pointers to
1699 ** [sqlite3_value] objects.  There is one [sqlite3_value] object for
1700 ** each parameter to the SQL function.  These routines are used to
1701 ** extract values from the [sqlite3_value] objects.
1702 **
1703 ** These routines work just like the corresponding 
1704 ** [sqlite3_column_blob | sqlite3_column_* routines] except that 
1705 ** these routines take a single [sqlite3_value*] pointer instead
1706 ** of an [sqlite3_stmt*] pointer and an integer column number.
1707 **
1708 ** The sqlite3_value_text16() interface extracts a UTF16 string
1709 ** in the native byte-order of the host machine.  The
1710 ** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces
1711 ** extract UTF16 strings as big-endian and little-endian respectively.
1712 **
1713 ** The sqlite3_value_numeric_type() interface attempts to apply
1714 ** numeric affinity to the value.  This means that an attempt is
1715 ** made to convert the value to an integer or floating point.  If
1716 ** such a conversion is possible without loss of information (in order
1717 ** words if the value is original a string that looks like a number)
1718 ** then it is done.  Otherwise no conversion occurs.  The 
1719 ** [SQLITE_INTEGER | datatype] after conversion is returned.
1720 **
1721 ** Please pay particular attention to the fact that the pointer that
1722 ** is returned from [sqlite3_value_blob()], [sqlite3_value_text()], or
1723 ** [sqlite3_value_text16()] can be invalidated by a subsequent call to
1724 ** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite_value_text()],
1725 ** or [sqlite3_value_text16()].  
1726 */
1727 const void *sqlite3_value_blob(sqlite3_value*);
1728 int sqlite3_value_bytes(sqlite3_value*);
1729 int sqlite3_value_bytes16(sqlite3_value*);
1730 double sqlite3_value_double(sqlite3_value*);
1731 int sqlite3_value_int(sqlite3_value*);
1732 sqlite_int64 sqlite3_value_int64(sqlite3_value*);
1733 const unsigned char *sqlite3_value_text(sqlite3_value*);
1734 const void *sqlite3_value_text16(sqlite3_value*);
1735 const void *sqlite3_value_text16le(sqlite3_value*);
1736 const void *sqlite3_value_text16be(sqlite3_value*);
1737 int sqlite3_value_type(sqlite3_value*);
1738 int sqlite3_value_numeric_type(sqlite3_value*);
1739
1740 /*
1741 ** CAPI3REF: Obtain Aggregate Function Context
1742 **
1743 ** The implementation of aggregate SQL functions use this routine to allocate
1744 ** a structure for storing their state.  The first time this routine
1745 ** is called for a particular aggregate, a new structure of size nBytes
1746 ** is allocated, zeroed, and returned.  On subsequent calls (for the
1747 ** same aggregate instance) the same buffer is returned.  The implementation
1748 ** of the aggregate can use the returned buffer to accumulate data.
1749 **
1750 ** The buffer allocated is freed automatically by SQLite whan the aggregate
1751 ** query concludes.
1752 **
1753 ** The first parameter should be a copy of the 
1754 ** [sqlite3_context | SQL function context] that is the first
1755 ** parameter to the callback routine that implements the aggregate
1756 ** function.
1757 */
1758 void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
1759
1760 /*
1761 ** CAPI3REF: User Data For Functions
1762 **
1763 ** The pUserData parameter to the [sqlite3_create_function()]
1764 ** and [sqlite3_create_function16()] routines
1765 ** used to register user functions is available to
1766 ** the implementation of the function using this call.
1767 */
1768 void *sqlite3_user_data(sqlite3_context*);
1769
1770 /*
1771 ** CAPI3REF: Function Auxiliary Data
1772 **
1773 ** The following two functions may be used by scalar SQL functions to
1774 ** associate meta-data with argument values. If the same value is passed to
1775 ** multiple invocations of the same SQL function during query execution, under
1776 ** some circumstances the associated meta-data may be preserved. This may
1777 ** be used, for example, to add a regular-expression matching scalar
1778 ** function. The compiled version of the regular expression is stored as
1779 ** meta-data associated with the SQL value passed as the regular expression
1780 ** pattern.  The compiled regular expression can be reused on multiple
1781 ** invocations of the same function so that the original pattern string
1782 ** does not need to be recompiled on each invocation.
1783 **
1784 ** The sqlite3_get_auxdata() interface returns a pointer to the meta-data
1785 ** associated with the Nth argument value to the current SQL function
1786 ** call, where N is the second parameter. If no meta-data has been set for
1787 ** that value, then a NULL pointer is returned.
1788 **
1789 ** The sqlite3_set_auxdata() is used to associate meta-data with an SQL
1790 ** function argument. The third parameter is a pointer to the meta-data
1791 ** to be associated with the Nth user function argument value. The fourth
1792 ** parameter specifies a destructor that will be called on the meta-
1793 ** data pointer to release it when it is no longer required. If the 
1794 ** destructor is NULL, it is not invoked.
1795 **
1796 ** In practice, meta-data is preserved between function calls for
1797 ** expressions that are constant at compile time. This includes literal
1798 ** values and SQL variables.
1799 */
1800 void *sqlite3_get_auxdata(sqlite3_context*, int);
1801 void sqlite3_set_auxdata(sqlite3_context*, int, void*, void (*)(void*));
1802
1803
1804 /*
1805 ** CAPI3REF: Constants Defining Special Destructor Behavior
1806 **
1807 ** These are special value for the destructor that is passed in as the
1808 ** final argument to routines like [sqlite3_result_blob()].  If the destructor
1809 ** argument is SQLITE_STATIC, it means that the content pointer is constant
1810 ** and will never change.  It does not need to be destroyed.  The 
1811 ** SQLITE_TRANSIENT value means that the content will likely change in
1812 ** the near future and that SQLite should make its own private copy of
1813 ** the content before returning.
1814 **
1815 ** The typedef is necessary to work around problems in certain
1816 ** C++ compilers.  See ticket #2191.
1817 */
1818 typedef void (*sqlite3_destructor_type)(void*);
1819 #define SQLITE_STATIC      ((sqlite3_destructor_type)0)
1820 #define SQLITE_TRANSIENT   ((sqlite3_destructor_type)-1)
1821
1822 /*
1823 ** CAPI3REF: Setting The Result Of An SQL Function
1824 **
1825 ** These routines are used by the xFunc or xFinal callbacks that
1826 ** implement SQL functions and aggregates.  See
1827 ** [sqlite3_create_function()] and [sqlite3_create_function16()]
1828 ** for additional information.
1829 **
1830 ** These functions work very much like the 
1831 ** [sqlite3_bind_blob | sqlite3_bind_*] family of functions used
1832 ** to bind values to host parameters in prepared statements.
1833 ** Refer to the
1834 ** [sqlite3_bind_blob | sqlite3_bind_* documentation] for
1835 ** additional information.
1836 **
1837 ** The sqlite3_result_error() and sqlite3_result_error16() functions
1838 ** cause the implemented SQL function to throw an exception.  The
1839 ** parameter to sqlite3_result_error() or sqlite3_result_error16()
1840 ** is the text of an error message.
1841 **
1842 ** The sqlite3_result_toobig() cause the function implementation
1843 ** to throw and error indicating that a string or BLOB is to long
1844 ** to represent.
1845 */
1846 void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
1847 void sqlite3_result_double(sqlite3_context*, double);
1848 void sqlite3_result_error(sqlite3_context*, const char*, int);
1849 void sqlite3_result_error16(sqlite3_context*, const void*, int);
1850 void sqlite3_result_error_toobig(sqlite3_context*);
1851 void sqlite3_result_int(sqlite3_context*, int);
1852 void sqlite3_result_int64(sqlite3_context*, sqlite_int64);
1853 void sqlite3_result_null(sqlite3_context*);
1854 void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
1855 void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
1856 void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
1857 void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
1858 void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
1859 void sqlite3_result_zeroblob(sqlite3_context*, int n);
1860
1861 /*
1862 ** CAPI3REF: Define New Collating Sequences
1863 **
1864 ** These functions are used to add new collation sequences to the
1865 ** [sqlite3*] handle specified as the first argument. 
1866 **
1867 ** The name of the new collation sequence is specified as a UTF-8 string
1868 ** for sqlite3_create_collation() and sqlite3_create_collation_v2()
1869 ** and a UTF-16 string for sqlite3_create_collation16().  In all cases
1870 ** the name is passed as the second function argument.
1871 **
1872 ** The third argument must be one of the constants [SQLITE_UTF8],
1873 ** [SQLITE_UTF16LE] or [SQLITE_UTF16BE], indicating that the user-supplied
1874 ** routine expects to be passed pointers to strings encoded using UTF-8,
1875 ** UTF-16 little-endian or UTF-16 big-endian respectively.
1876 **
1877 ** A pointer to the user supplied routine must be passed as the fifth
1878 ** argument. If it is NULL, this is the same as deleting the collation
1879 ** sequence (so that SQLite cannot call it anymore). Each time the user
1880 ** supplied function is invoked, it is passed a copy of the void* passed as
1881 ** the fourth argument to sqlite3_create_collation() or
1882 ** sqlite3_create_collation16() as its first parameter.
1883 **
1884 ** The remaining arguments to the user-supplied routine are two strings,
1885 ** each represented by a [length, data] pair and encoded in the encoding
1886 ** that was passed as the third argument when the collation sequence was
1887 ** registered. The user routine should return negative, zero or positive if
1888 ** the first string is less than, equal to, or greater than the second
1889 ** string. i.e. (STRING1 - STRING2).
1890 **
1891 ** The sqlite3_create_collation_v2() works like sqlite3_create_collation()
1892 ** excapt that it takes an extra argument which is a destructor for
1893 ** the collation.  The destructor is called when the collation is
1894 ** destroyed and is passed a copy of the fourth parameter void* pointer
1895 ** of the sqlite3_create_collation_v2().  Collations are destroyed when
1896 ** they are overridden by later calls to the collation creation functions
1897 ** or when the [sqlite3*] database handle is closed using [sqlite3_close()].
1898 **
1899 ** The sqlite3_create_collation_v2() interface is experimental and
1900 ** subject to change in future releases.  The other collation creation
1901 ** functions are stable.
1902 */
1903 int sqlite3_create_collation(
1904   sqlite3*, 
1905   const char *zName, 
1906   int eTextRep, 
1907   void*,
1908   int(*xCompare)(void*,int,const void*,int,const void*)
1909 );
1910 int sqlite3_create_collation_v2(
1911   sqlite3*, 
1912   const char *zName, 
1913   int eTextRep, 
1914   void*,
1915   int(*xCompare)(void*,int,const void*,int,const void*),
1916   void(*xDestroy)(void*)
1917 );
1918 int sqlite3_create_collation16(
1919   sqlite3*, 
1920   const char *zName, 
1921   int eTextRep, 
1922   void*,
1923   int(*xCompare)(void*,int,const void*,int,const void*)
1924 );
1925
1926 /*
1927 ** CAPI3REF: Collation Needed Callbacks
1928 **
1929 ** To avoid having to register all collation sequences before a database
1930 ** can be used, a single callback function may be registered with the
1931 ** database handle to be called whenever an undefined collation sequence is
1932 ** required.
1933 **
1934 ** If the function is registered using the sqlite3_collation_needed() API,
1935 ** then it is passed the names of undefined collation sequences as strings
1936 ** encoded in UTF-8. If sqlite3_collation_needed16() is used, the names
1937 ** are passed as UTF-16 in machine native byte order. A call to either
1938 ** function replaces any existing callback.
1939 **
1940 ** When the callback is invoked, the first argument passed is a copy
1941 ** of the second argument to sqlite3_collation_needed() or
1942 ** sqlite3_collation_needed16(). The second argument is the database
1943 ** handle. The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE], or
1944 ** [SQLITE_UTF16LE], indicating the most desirable form of the collation
1945 ** sequence function required. The fourth parameter is the name of the
1946 ** required collation sequence.
1947 **
1948 ** The callback function should register the desired collation using
1949 ** [sqlite3_create_collation()], [sqlite3_create_collation16()], or
1950 ** [sqlite3_create_collation_v2()].
1951 */
1952 int sqlite3_collation_needed(
1953   sqlite3*, 
1954   void*, 
1955   void(*)(void*,sqlite3*,int eTextRep,const char*)
1956 );
1957 int sqlite3_collation_needed16(
1958   sqlite3*, 
1959   void*,
1960   void(*)(void*,sqlite3*,int eTextRep,const void*)
1961 );
1962
1963 /*
1964 ** Specify the key for an encrypted database.  This routine should be
1965 ** called right after sqlite3_open().
1966 **
1967 ** The code to implement this API is not available in the public release
1968 ** of SQLite.
1969 */
1970 int sqlite3_key(
1971   sqlite3 *db,                   /* Database to be rekeyed */
1972   const void *pKey, int nKey     /* The key */
1973 );
1974
1975 /*
1976 ** Change the key on an open database.  If the current database is not
1977 ** encrypted, this routine will encrypt it.  If pNew==0 or nNew==0, the
1978 ** database is decrypted.
1979 **
1980 ** The code to implement this API is not available in the public release
1981 ** of SQLite.
1982 */
1983 int sqlite3_rekey(
1984   sqlite3 *db,                   /* Database to be rekeyed */
1985   const void *pKey, int nKey     /* The new key */
1986 );
1987
1988 /*
1989 ** CAPI3REF:  Suspend Execution For A Short Time
1990 **
1991 ** This function causes the current thread to suspect execution
1992 ** a number of milliseconds specified in its parameter.
1993 **
1994 ** If the operating system does not support sleep requests with 
1995 ** millisecond time resolution, then the time will be rounded up to 
1996 ** the nearest second. The number of milliseconds of sleep actually 
1997 ** requested from the operating system is returned.
1998 */
1999 int sqlite3_sleep(int);
2000
2001 /*
2002 ** CAPI3REF:  Name Of The Folder Holding Temporary Files
2003 **
2004 ** If this global variable is made to point to a string which is
2005 ** the name of a folder (a.ka. directory), then all temporary files
2006 ** created by SQLite will be placed in that directory.  If this variable
2007 ** is NULL pointer, then SQLite does a search for an appropriate temporary
2008 ** file directory.
2009 **
2010 ** Once [sqlite3_open()] has been called, changing this variable will
2011 ** invalidate the current temporary database, if any.  Generally speaking,
2012 ** it is not safe to invoke this routine after [sqlite3_open()] has
2013 ** been called.
2014 */
2015 extern char *sqlite3_temp_directory;
2016
2017 /*
2018 ** CAPI3REF:  Test To See If The Databse Is In Auto-Commit Mode
2019 **
2020 ** Test to see whether or not the database connection is in autocommit
2021 ** mode.  Return TRUE if it is and FALSE if not.  Autocommit mode is on
2022 ** by default.  Autocommit is disabled by a BEGIN statement and reenabled
2023 ** by the next COMMIT or ROLLBACK.
2024 */
2025 int sqlite3_get_autocommit(sqlite3*);
2026
2027 /*
2028 ** CAPI3REF:  Find The Database Handle Associated With A Prepared Statement
2029 **
2030 ** Return the [sqlite3*] database handle to which a
2031 ** [sqlite3_stmt | prepared statement] belongs.
2032 ** This is the same database handle that was
2033 ** the first argument to the [sqlite3_prepare_v2()] or its variants
2034 ** that was used to create the statement in the first place.
2035 */
2036 sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
2037
2038
2039 /*
2040 ** CAPI3REF: Commit And Rollback Notification Callbacks
2041 **
2042 ** These routines
2043 ** register callback functions to be invoked whenever a transaction
2044 ** is committed or rolled back.  The pArg argument is passed through
2045 ** to the callback.  If the callback on a commit hook function 
2046 ** returns non-zero, then the commit is converted into a rollback.
2047 **
2048 ** If another function was previously registered, its pArg value is returned.
2049 ** Otherwise NULL is returned.
2050 **
2051 ** Registering a NULL function disables the callback.
2052 **
2053 ** For the purposes of this API, a transaction is said to have been 
2054 ** rolled back if an explicit "ROLLBACK" statement is executed, or
2055 ** an error or constraint causes an implicit rollback to occur. The 
2056 ** callback is not invoked if a transaction is automatically rolled
2057 ** back because the database connection is closed.
2058 **
2059 ** These are experimental interfaces and are subject to change.
2060 */
2061 void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
2062 void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
2063
2064 /*
2065 ** CAPI3REF: Data Change Notification Callbacks
2066 **
2067 ** Register a callback function with the database connection identified by the 
2068 ** first argument to be invoked whenever a row is updated, inserted or deleted.
2069 ** Any callback set by a previous call to this function for the same 
2070 ** database connection is overridden.
2071 **
2072 ** The second argument is a pointer to the function to invoke when a 
2073 ** row is updated, inserted or deleted. The first argument to the callback is
2074 ** a copy of the third argument to sqlite3_update_hook(). The second callback 
2075 ** argument is one of SQLITE_INSERT, SQLITE_DELETE or SQLITE_UPDATE, depending
2076 ** on the operation that caused the callback to be invoked. The third and 
2077 ** fourth arguments to the callback contain pointers to the database and 
2078 ** table name containing the affected row. The final callback parameter is 
2079 ** the rowid of the row. In the case of an update, this is the rowid after 
2080 ** the update takes place.
2081 **
2082 ** The update hook is not invoked when internal system tables are
2083 ** modified (i.e. sqlite_master and sqlite_sequence).
2084 **
2085 ** If another function was previously registered, its pArg value is returned.
2086 ** Otherwise NULL is returned.
2087 */
2088 void *sqlite3_update_hook(
2089   sqlite3*, 
2090   void(*)(void *,int ,char const *,char const *,sqlite_int64),
2091   void*
2092 );
2093
2094 /*
2095 ** CAPI3REF:  Enable Or Disable Shared Pager Cache
2096 **
2097 ** This routine enables or disables the sharing of the database cache
2098 ** and schema data structures between connections to the same database.
2099 ** Sharing is enabled if the argument is true and disabled if the argument
2100 ** is false.
2101 **
2102 ** Cache sharing is enabled and disabled on a thread-by-thread basis.
2103 ** Each call to this routine enables or disables cache sharing only for
2104 ** connections created in the same thread in which this routine is called.
2105 ** There is no mechanism for sharing cache between database connections
2106 ** running in different threads.
2107 **
2108 ** Sharing must be disabled prior to shutting down a thread or else
2109 ** the thread will leak memory.  Call this routine with an argument of
2110 ** 0 to turn off sharing.  Or use the sqlite3_thread_cleanup() API.
2111 **
2112 ** This routine must not be called when any database connections
2113 ** are active in the current thread.  Enabling or disabling shared
2114 ** cache while there are active database connections will result
2115 ** in memory corruption.
2116 **
2117 ** When the shared cache is enabled, the
2118 ** following routines must always be called from the same thread:
2119 ** [sqlite3_open()], [sqlite3_prepare_v2()], [sqlite3_step()],
2120 ** [sqlite3_reset()], [sqlite3_finalize()], and [sqlite3_close()].
2121 ** This is due to the fact that the shared cache makes use of
2122 ** thread-specific storage so that it will be available for sharing
2123 ** with other connections.
2124 **
2125 ** Virtual tables cannot be used with a shared cache.  When shared
2126 ** cache is enabled, the sqlite3_create_module() API used to register
2127 ** virtual tables will always return an error.
2128 **
2129 ** This routine returns [SQLITE_OK] if shared cache was
2130 ** enabled or disabled successfully.  An [SQLITE_ERROR | error code]
2131 ** is returned otherwise.
2132 **
2133 ** Shared cache is disabled by default for backward compatibility.
2134 */
2135 int sqlite3_enable_shared_cache(int);
2136
2137 /*
2138 ** CAPI3REF:  Attempt To Free Heap Memory
2139 **
2140 ** Attempt to free N bytes of heap memory by deallocating non-essential
2141 ** memory allocations held by the database library (example: memory 
2142 ** used to cache database pages to improve performance).
2143 **
2144 ** This function is not a part of standard builds.  It is only created
2145 ** if SQLite is compiled with the SQLITE_ENABLE_MEMORY_MANAGEMENT macro.
2146 */
2147 int sqlite3_release_memory(int);
2148
2149 /*
2150 ** CAPI3REF:  Impose A Limit On Heap Size
2151 **
2152 ** Place a "soft" limit on the amount of heap memory that may be allocated by
2153 ** SQLite within the current thread. If an internal allocation is requested 
2154 ** that would exceed the specified limit, [sqlite3_release_memory()] is invoked
2155 ** one or more times to free up some space before the allocation is made.
2156 **
2157 ** The limit is called "soft", because if [sqlite3_release_memory()] cannot free
2158 ** sufficient memory to prevent the limit from being exceeded, the memory is
2159 ** allocated anyway and the current operation proceeds.
2160 **
2161 ** Prior to shutting down a thread sqlite3_soft_heap_limit() must be set to 
2162 ** zero (the default) or else the thread will leak memory. Alternatively, use
2163 ** the [sqlite3_thread_cleanup()] API.
2164 **
2165 ** A negative or zero value for N means that there is no soft heap limit and
2166 ** [sqlite3_release_memory()] will only be called when memory is exhaused.
2167 ** The default value for the soft heap limit is zero.
2168 **
2169 ** SQLite makes a best effort to honor the soft heap limit.  But if it
2170 ** is unable to reduce memory usage below the soft limit, execution will
2171 ** continue without error or notification.  This is why the limit is 
2172 ** called a "soft" limit.  It is advisory only.
2173 **
2174 ** This function is only available if the library was compiled with the 
2175 ** SQLITE_ENABLE_MEMORY_MANAGEMENT option set.
2176 ** memory-management has been enabled.
2177 */
2178 void sqlite3_soft_heap_limit(int);
2179
2180 /*
2181 ** CAPI3REF:  Clean Up Thread Local Storage
2182 **
2183 ** This routine makes sure that all thread-local storage has been
2184 ** deallocated for the current thread.
2185 **
2186 ** This routine is not technically necessary.  All thread-local storage
2187 ** will be automatically deallocated once memory-management and
2188 ** shared-cache are disabled and the soft heap limit has been set
2189 ** to zero.  This routine is provided as a convenience for users who
2190 ** want to make absolutely sure they have not forgotten something
2191 ** prior to killing off a thread.
2192 */
2193 void sqlite3_thread_cleanup(void);
2194
2195 /*
2196 ** CAPI3REF:  Extract Metadata About A Column Of A Table
2197 **
2198 ** This routine
2199 ** returns meta-data about a specific column of a specific database
2200 ** table accessible using the connection handle passed as the first function 
2201 ** argument.
2202 **
2203 ** The column is identified by the second, third and fourth parameters to 
2204 ** this function. The second parameter is either the name of the database
2205 ** (i.e. "main", "temp" or an attached database) containing the specified
2206 ** table or NULL. If it is NULL, then all attached databases are searched
2207 ** for the table using the same algorithm as the database engine uses to 
2208 ** resolve unqualified table references.
2209 **
2210 ** The third and fourth parameters to this function are the table and column 
2211 ** name of the desired column, respectively. Neither of these parameters 
2212 ** may be NULL.
2213 **
2214 ** Meta information is returned by writing to the memory locations passed as
2215 ** the 5th and subsequent parameters to this function. Any of these 
2216 ** arguments may be NULL, in which case the corresponding element of meta 
2217 ** information is ommitted.
2218 **
2219 ** <pre>
2220 ** Parameter     Output Type      Description
2221 ** -----------------------------------
2222 **
2223 **   5th         const char*      Data type
2224 **   6th         const char*      Name of the default collation sequence 
2225 **   7th         int              True if the column has a NOT NULL constraint
2226 **   8th         int              True if the column is part of the PRIMARY KEY
2227 **   9th         int              True if the column is AUTOINCREMENT
2228 ** </pre>
2229 **
2230 **
2231 ** The memory pointed to by the character pointers returned for the 
2232 ** declaration type and collation sequence is valid only until the next 
2233 ** call to any sqlite API function.
2234 **
2235 ** If the specified table is actually a view, then an error is returned.
2236 **
2237 ** If the specified column is "rowid", "oid" or "_rowid_" and an 
2238 ** INTEGER PRIMARY KEY column has been explicitly declared, then the output 
2239 ** parameters are set for the explicitly declared column. If there is no
2240 ** explicitly declared IPK column, then the output parameters are set as 
2241 ** follows:
2242 **
2243 ** <pre>
2244 **     data type: "INTEGER"
2245 **     collation sequence: "BINARY"
2246 **     not null: 0
2247 **     primary key: 1
2248 **     auto increment: 0
2249 ** </pre>
2250 **
2251 ** This function may load one or more schemas from database files. If an
2252 ** error occurs during this process, or if the requested table or column
2253 ** cannot be found, an SQLITE error code is returned and an error message
2254 ** left in the database handle (to be retrieved using sqlite3_errmsg()).
2255 **
2256 ** This API is only available if the library was compiled with the
2257 ** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined.
2258 */
2259 int sqlite3_table_column_metadata(
2260   sqlite3 *db,                /* Connection handle */
2261   const char *zDbName,        /* Database name or NULL */
2262   const char *zTableName,     /* Table name */
2263   const char *zColumnName,    /* Column name */
2264   char const **pzDataType,    /* OUTPUT: Declared data type */
2265   char const **pzCollSeq,     /* OUTPUT: Collation sequence name */
2266   int *pNotNull,              /* OUTPUT: True if NOT NULL constraint exists */
2267   int *pPrimaryKey,           /* OUTPUT: True if column part of PK */
2268   int *pAutoinc               /* OUTPUT: True if colums is auto-increment */
2269 );
2270
2271 /*
2272 ** CAPI3REF: Load An Extension
2273 **
2274 ** Attempt to load an SQLite extension library contained in the file
2275 ** zFile.  The entry point is zProc.  zProc may be 0 in which case the
2276 ** name of the entry point defaults to "sqlite3_extension_init".
2277 **
2278 ** Return [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong.
2279 **
2280 ** If an error occurs and pzErrMsg is not 0, then fill *pzErrMsg with 
2281 ** error message text.  The calling function should free this memory
2282 ** by calling [sqlite3_free()].
2283 **
2284 ** Extension loading must be enabled using [sqlite3_enable_load_extension()]
2285 ** prior to calling this API or an error will be returned.
2286 */
2287 int sqlite3_load_extension(
2288   sqlite3 *db,          /* Load the extension into this database connection */
2289   const char *zFile,    /* Name of the shared library containing extension */
2290   const char *zProc,    /* Entry point.  Derived from zFile if 0 */
2291   char **pzErrMsg       /* Put error message here if not 0 */
2292 );
2293
2294 /*
2295 ** CAPI3REF:  Enable Or Disable Extension Loading
2296 **
2297 ** So as not to open security holes in older applications that are
2298 ** unprepared to deal with extension loading, and as a means of disabling
2299 ** extension loading while evaluating user-entered SQL, the following
2300 ** API is provided to turn the [sqlite3_load_extension()] mechanism on and
2301 ** off.  It is off by default.  See ticket #1863.
2302 **
2303 ** Call this routine with onoff==1 to turn extension loading on
2304 ** and call it with onoff==0 to turn it back off again.
2305 */
2306 int sqlite3_enable_load_extension(sqlite3 *db, int onoff);
2307
2308 /*
2309 ** CAPI3REF: Make Arrangements To Automatically Load An Extension
2310 **
2311 ** Register an extension entry point that is automatically invoked
2312 ** whenever a new database connection is opened using
2313 ** [sqlite3_open()] or [sqlite3_open16()].
2314 **
2315 ** This API can be invoked at program startup in order to register
2316 ** one or more statically linked extensions that will be available
2317 ** to all new database connections.
2318 **
2319 ** Duplicate extensions are detected so calling this routine multiple
2320 ** times with the same extension is harmless.
2321 **
2322 ** This routine stores a pointer to the extension in an array
2323 ** that is obtained from malloc().  If you run a memory leak
2324 ** checker on your program and it reports a leak because of this
2325 ** array, then invoke [sqlite3_automatic_extension_reset()] prior
2326 ** to shutdown to free the memory.
2327 **
2328 ** Automatic extensions apply across all threads.
2329 **
2330 ** This interface is experimental and is subject to change or
2331 ** removal in future releases of SQLite.
2332 */
2333 int sqlite3_auto_extension(void *xEntryPoint);
2334
2335
2336 /*
2337 ** CAPI3REF: Reset Automatic Extension Loading
2338 **
2339 ** Disable all previously registered automatic extensions.  This
2340 ** routine undoes the effect of all prior [sqlite3_automatic_extension()]
2341 ** calls.
2342 **
2343 ** This call disabled automatic extensions in all threads.
2344 **
2345 ** This interface is experimental and is subject to change or
2346 ** removal in future releases of SQLite.
2347 */
2348 void sqlite3_reset_auto_extension(void);
2349
2350
2351 /*
2352 ****** EXPERIMENTAL - subject to change without notice **************
2353 **
2354 ** The interface to the virtual-table mechanism is currently considered
2355 ** to be experimental.  The interface might change in incompatible ways.
2356 ** If this is a problem for you, do not use the interface at this time.
2357 **
2358 ** When the virtual-table mechanism stablizes, we will declare the
2359 ** interface fixed, support it indefinitely, and remove this comment.
2360 */
2361
2362 /*
2363 ** Structures used by the virtual table interface
2364 */
2365 typedef struct sqlite3_vtab sqlite3_vtab;
2366 typedef struct sqlite3_index_info sqlite3_index_info;
2367 typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor;
2368 typedef struct sqlite3_module sqlite3_module;
2369
2370 /*
2371 ** A module is a class of virtual tables.  Each module is defined
2372 ** by an instance of the following structure.  This structure consists
2373 ** mostly of methods for the module.
2374 */
2375 struct sqlite3_module {
2376   int iVersion;
2377   int (*xCreate)(sqlite3*, void *pAux,
2378                int argc, const char *const*argv,
2379                sqlite3_vtab **ppVTab, char**);
2380   int (*xConnect)(sqlite3*, void *pAux,
2381                int argc, const char *const*argv,
2382                sqlite3_vtab **ppVTab, char**);
2383   int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*);
2384   int (*xDisconnect)(sqlite3_vtab *pVTab);
2385   int (*xDestroy)(sqlite3_vtab *pVTab);
2386   int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor);
2387   int (*xClose)(sqlite3_vtab_cursor*);
2388   int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr,
2389                 int argc, sqlite3_value **argv);
2390   int (*xNext)(sqlite3_vtab_cursor*);
2391   int (*xEof)(sqlite3_vtab_cursor*);
2392   int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int);
2393   int (*xRowid)(sqlite3_vtab_cursor*, sqlite_int64 *pRowid);
2394   int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite_int64 *);
2395   int (*xBegin)(sqlite3_vtab *pVTab);
2396   int (*xSync)(sqlite3_vtab *pVTab);
2397   int (*xCommit)(sqlite3_vtab *pVTab);
2398   int (*xRollback)(sqlite3_vtab *pVTab);
2399   int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName,
2400                        void (**pxFunc)(sqlite3_context*,int,sqlite3_value**),
2401                        void **ppArg);
2402 };
2403
2404 /*
2405 ** The sqlite3_index_info structure and its substructures is used to
2406 ** pass information into and receive the reply from the xBestIndex
2407 ** method of an sqlite3_module.  The fields under **Inputs** are the
2408 ** inputs to xBestIndex and are read-only.  xBestIndex inserts its
2409 ** results into the **Outputs** fields.
2410 **
2411 ** The aConstraint[] array records WHERE clause constraints of the
2412 ** form:
2413 **
2414 **         column OP expr
2415 **
2416 ** Where OP is =, <, <=, >, or >=.  The particular operator is stored
2417 ** in aConstraint[].op.  The index of the column is stored in 
2418 ** aConstraint[].iColumn.  aConstraint[].usable is TRUE if the
2419 ** expr on the right-hand side can be evaluated (and thus the constraint
2420 ** is usable) and false if it cannot.
2421 **
2422 ** The optimizer automatically inverts terms of the form "expr OP column"
2423 ** and makes other simplificatinos to the WHERE clause in an attempt to
2424 ** get as many WHERE clause terms into the form shown above as possible.
2425 ** The aConstraint[] array only reports WHERE clause terms in the correct
2426 ** form that refer to the particular virtual table being queried.
2427 **
2428 ** Information about the ORDER BY clause is stored in aOrderBy[].
2429 ** Each term of aOrderBy records a column of the ORDER BY clause.
2430 **
2431 ** The xBestIndex method must fill aConstraintUsage[] with information
2432 ** about what parameters to pass to xFilter.  If argvIndex>0 then
2433 ** the right-hand side of the corresponding aConstraint[] is evaluated
2434 ** and becomes the argvIndex-th entry in argv.  If aConstraintUsage[].omit
2435 ** is true, then the constraint is assumed to be fully handled by the
2436 ** virtual table and is not checked again by SQLite.
2437 **
2438 ** The idxNum and idxPtr values are recorded and passed into xFilter.
2439 ** sqlite3_free() is used to free idxPtr if needToFreeIdxPtr is true.
2440 **
2441 ** The orderByConsumed means that output from xFilter will occur in
2442 ** the correct order to satisfy the ORDER BY clause so that no separate
2443 ** sorting step is required.
2444 **
2445 ** The estimatedCost value is an estimate of the cost of doing the
2446 ** particular lookup.  A full scan of a table with N entries should have
2447 ** a cost of N.  A binary search of a table of N entries should have a
2448 ** cost of approximately log(N).
2449 */
2450 struct sqlite3_index_info {
2451   /* Inputs */
2452   const int nConstraint;     /* Number of entries in aConstraint */
2453   const struct sqlite3_index_constraint {
2454      int iColumn;              /* Column on left-hand side of constraint */
2455      unsigned char op;         /* Constraint operator */
2456      unsigned char usable;     /* True if this constraint is usable */
2457      int iTermOffset;          /* Used internally - xBestIndex should ignore */
2458   } *const aConstraint;      /* Table of WHERE clause constraints */
2459   const int nOrderBy;        /* Number of terms in the ORDER BY clause */
2460   const struct sqlite3_index_orderby {
2461      int iColumn;              /* Column number */
2462      unsigned char desc;       /* True for DESC.  False for ASC. */
2463   } *const aOrderBy;         /* The ORDER BY clause */
2464
2465   /* Outputs */
2466   struct sqlite3_index_constraint_usage {
2467     int argvIndex;           /* if >0, constraint is part of argv to xFilter */
2468     unsigned char omit;      /* Do not code a test for this constraint */
2469   } *const aConstraintUsage;
2470   int idxNum;                /* Number used to identify the index */
2471   char *idxStr;              /* String, possibly obtained from sqlite3_malloc */
2472   int needToFreeIdxStr;      /* Free idxStr using sqlite3_free() if true */
2473   int orderByConsumed;       /* True if output is already ordered */
2474   double estimatedCost;      /* Estimated cost of using this index */
2475 };
2476 #define SQLITE_INDEX_CONSTRAINT_EQ    2
2477 #define SQLITE_INDEX_CONSTRAINT_GT    4
2478 #define SQLITE_INDEX_CONSTRAINT_LE    8
2479 #define SQLITE_INDEX_CONSTRAINT_LT    16
2480 #define SQLITE_INDEX_CONSTRAINT_GE    32
2481 #define SQLITE_INDEX_CONSTRAINT_MATCH 64
2482
2483 /*
2484 ** This routine is used to register a new module name with an SQLite
2485 ** connection.  Module names must be registered before creating new
2486 ** virtual tables on the module, or before using preexisting virtual
2487 ** tables of the module.
2488 */
2489 int sqlite3_create_module(
2490   sqlite3 *db,               /* SQLite connection to register module with */
2491   const char *zName,         /* Name of the module */
2492   const sqlite3_module *,    /* Methods for the module */
2493   void *                     /* Client data for xCreate/xConnect */
2494 );
2495
2496 /*
2497 ** Every module implementation uses a subclass of the following structure
2498 ** to describe a particular instance of the module.  Each subclass will
2499 ** be taylored to the specific needs of the module implementation.   The
2500 ** purpose of this superclass is to define certain fields that are common
2501 ** to all module implementations.
2502 **
2503 ** Virtual tables methods can set an error message by assigning a
2504 ** string obtained from sqlite3_mprintf() to zErrMsg.  The method should
2505 ** take care that any prior string is freed by a call to sqlite3_free()
2506 ** prior to assigning a new string to zErrMsg.  After the error message
2507 ** is delivered up to the client application, the string will be automatically
2508 ** freed by sqlite3_free() and the zErrMsg field will be zeroed.  Note
2509 ** that sqlite3_mprintf() and sqlite3_free() are used on the zErrMsg field
2510 ** since virtual tables are commonly implemented in loadable extensions which
2511 ** do not have access to sqlite3MPrintf() or sqlite3Free().
2512 */
2513 struct sqlite3_vtab {
2514   const sqlite3_module *pModule;  /* The module for this virtual table */
2515   int nRef;                       /* Used internally */
2516   char *zErrMsg;                  /* Error message from sqlite3_mprintf() */
2517   /* Virtual table implementations will typically add additional fields */
2518 };
2519
2520 /* Every module implementation uses a subclass of the following structure
2521 ** to describe cursors that point into the virtual table and are used
2522 ** to loop through the virtual table.  Cursors are created using the
2523 ** xOpen method of the module.  Each module implementation will define
2524 ** the content of a cursor structure to suit its own needs.
2525 **
2526 ** This superclass exists in order to define fields of the cursor that
2527 ** are common to all implementations.
2528 */
2529 struct sqlite3_vtab_cursor {
2530   sqlite3_vtab *pVtab;      /* Virtual table of this cursor */
2531   /* Virtual table implementations will typically add additional fields */
2532 };
2533
2534 /*
2535 ** The xCreate and xConnect methods of a module use the following API
2536 ** to declare the format (the names and datatypes of the columns) of
2537 ** the virtual tables they implement.
2538 */
2539 int sqlite3_declare_vtab(sqlite3*, const char *zCreateTable);
2540
2541 /*
2542 ** Virtual tables can provide alternative implementations of functions
2543 ** using the xFindFunction method.  But global versions of those functions
2544 ** must exist in order to be overloaded.
2545 **
2546 ** This API makes sure a global version of a function with a particular
2547 ** name and number of parameters exists.  If no such function exists
2548 ** before this API is called, a new function is created.  The implementation
2549 ** of the new function always causes an exception to be thrown.  So
2550 ** the new function is not good for anything by itself.  Its only
2551 ** purpose is to be a place-holder function that can be overloaded
2552 ** by virtual tables.
2553 **
2554 ** This API should be considered part of the virtual table interface,
2555 ** which is experimental and subject to change.
2556 */
2557 int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg);
2558
2559 /*
2560 ** The interface to the virtual-table mechanism defined above (back up
2561 ** to a comment remarkably similar to this one) is currently considered
2562 ** to be experimental.  The interface might change in incompatible ways.
2563 ** If this is a problem for you, do not use the interface at this time.
2564 **
2565 ** When the virtual-table mechanism stablizes, we will declare the
2566 ** interface fixed, support it indefinitely, and remove this comment.
2567 **
2568 ****** EXPERIMENTAL - subject to change without notice **************
2569 */
2570
2571 /*
2572 ** CAPI3REF: A Handle To An Open BLOB
2573 **
2574 ** An instance of the following opaque structure is used to 
2575 ** represent an blob-handle.  A blob-handle is created by
2576 ** [sqlite3_blob_open()] and destroyed by [sqlite3_blob_close()].
2577 ** The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces
2578 ** can be used to read or write small subsections of the blob.
2579 ** The [sqltie3_blob_size()] interface returns the size of the
2580 ** blob in bytes.
2581 */
2582 typedef struct sqlite3_blob sqlite3_blob;
2583
2584 /*
2585 ** CAPI3REF: Open A BLOB For Incremental I/O
2586 **
2587 ** Open a handle to the blob located in row iRow,, column zColumn, 
2588 ** table zTable in database zDb. i.e. the same blob that would
2589 ** be selected by:
2590 **
2591 ** <pre>
2592 **     SELECT zColumn FROM zDb.zTable WHERE rowid = iRow;
2593 ** </pre>
2594 **
2595 ** If the flags parameter is non-zero, the blob is opened for 
2596 ** read and write access. If it is zero, the blob is opened for read 
2597 ** access.
2598 **
2599 ** On success, [SQLITE_OK] is returned and the new 
2600 ** [sqlite3_blob | blob handle] is written to *ppBlob.
2601 ** Otherwise an error code is returned and 
2602 ** any value written to *ppBlob should not be used by the caller.
2603 ** This function sets the database-handle error code and message
2604 ** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()].
2605 */
2606 int sqlite3_blob_open(
2607   sqlite3*,
2608   const char *zDb,
2609   const char *zTable,
2610   const char *zColumn,
2611   sqlite_int64 iRow,
2612   int flags,
2613   sqlite3_blob **ppBlob
2614 );
2615
2616 /*
2617 ** CAPI3REF:  Close A BLOB Handle
2618 **
2619 ** Close an open [sqlite3_blob | blob handle].
2620 */
2621 int sqlite3_blob_close(sqlite3_blob *);
2622
2623 /*
2624 ** CAPI3REF:  Return The Size Of An Open BLOB
2625 **
2626 ** Return the size in bytes of the blob accessible via the open 
2627 ** [sqlite3_blob | blob-handle] passed as an argument.
2628 */
2629 int sqlite3_blob_bytes(sqlite3_blob *);
2630
2631 /*
2632 ** CAPI3REF:  Read Data From A BLOB Incrementally
2633 **
2634 ** This function is used to read data from an open 
2635 ** [sqlite3_blob | blob-handle] into a caller supplied buffer.
2636 ** n bytes of data are copied into buffer
2637 ** z from the open blob, starting at offset iOffset.
2638 **
2639 ** On success, SQLITE_OK is returned. Otherwise, an 
2640 ** [SQLITE_ERROR | SQLite error code] or an
2641 ** [SQLITE_IOERR_READ | extended error code] is returned.
2642 */
2643 int sqlite3_blob_read(sqlite3_blob *, void *z, int n, int iOffset);
2644
2645 /*
2646 ** CAPI3REF:  Write Data Into A BLOB Incrementally
2647 **
2648 ** This function is used to write data into an open 
2649 ** [sqlite3_blob | blob-handle] from a user supplied buffer.
2650 ** n bytes of data are copied from the buffer
2651 ** pointed to by z into the open blob, starting at offset iOffset.
2652 **
2653 ** If the [sqlite3_blob | blob-handle] passed as the first argument
2654 ** was not opened for writing (the flags parameter to [sqlite3_blob_open()]
2655 *** was zero), this function returns [SQLITE_READONLY].
2656 **
2657 ** This function may only modify the contents of the blob, it is
2658 ** not possible to increase the size of a blob using this API. If
2659 ** offset iOffset is less than n bytes from the end of the blob, 
2660 ** [SQLITE_ERROR] is returned and no data is written.
2661 **
2662 ** On success, SQLITE_OK is returned. Otherwise, an 
2663 ** [SQLITE_ERROR | SQLite error code] or an
2664 ** [SQLITE_IOERR_READ | extended error code] is returned.
2665 */
2666 int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);
2667
2668 /*
2669 ** Undo the hack that converts floating point types to integer for
2670 ** builds on processors without floating point support.
2671 */
2672 #ifdef SQLITE_OMIT_FLOATING_POINT
2673 # undef double
2674 #endif
2675
2676 #ifdef __cplusplus
2677 }  /* End of the 'extern "C"' block */
2678 #endif
2679 #endif