blob: 6465245cad8e6e1522786f22a2808034bcf07c77 [file] [log] [blame]
drh75897232000-05-29 14:26:00 +00001/*
drhb19a2bc2001-09-16 00:13:26 +00002** 2001 September 15
drh75897232000-05-29 14:26:00 +00003**
drhb19a2bc2001-09-16 00:13:26 +00004** The author disclaims copyright to this source code. In place of
5** a legal notice, here is a blessing:
drh75897232000-05-29 14:26:00 +00006**
drhb19a2bc2001-09-16 00:13:26 +00007** 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.
drh75897232000-05-29 14:26:00 +000010**
11*************************************************************************
drhb19a2bc2001-09-16 00:13:26 +000012** This header file defines the interface that the SQLite library
drh6ed48bf2007-06-14 20:57:18 +000013** 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.
drh75897232000-05-29 14:26:00 +000017**
drh6ed48bf2007-06-14 20:57:18 +000018** 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**
drhf3a65f72007-08-22 20:18:21 +000033** @(#) $Id: sqlite.h.in,v 1.237 2007/08/22 20:18:22 drh Exp $
drh75897232000-05-29 14:26:00 +000034*/
drh12057d52004-09-06 17:34:12 +000035#ifndef _SQLITE3_H_
36#define _SQLITE3_H_
drha18c5682000-10-08 22:20:57 +000037#include <stdarg.h> /* Needed for the definition of va_list */
drh75897232000-05-29 14:26:00 +000038
39/*
drh382c0242001-10-06 16:33:02 +000040** Make sure we can call this stuff from C++.
41*/
42#ifdef __cplusplus
43extern "C" {
44#endif
45
drh6d2069d2007-08-14 01:58:53 +000046
drh382c0242001-10-06 16:33:02 +000047/*
drh73be5012007-08-08 12:11:21 +000048** Add the ability to override 'extern'
49*/
50#ifndef SQLITE_EXTERN
51# define SQLITE_EXTERN extern
52#endif
53
54/*
drh6ed48bf2007-06-14 20:57:18 +000055** Make sure these symbols where not defined by some previous header
56** file.
drhb86ccfb2003-01-28 23:13:10 +000057*/
drh1e284f42004-10-06 15:52:01 +000058#ifdef SQLITE_VERSION
59# undef SQLITE_VERSION
drh1e284f42004-10-06 15:52:01 +000060#endif
drh6ed48bf2007-06-14 20:57:18 +000061#ifdef SQLITE_VERSION_NUMBER
62# undef SQLITE_VERSION_NUMBER
63#endif
danielk197799ba19e2005-02-05 07:33:34 +000064
65/*
drh6ed48bf2007-06-14 20:57:18 +000066** CAPI3REF: Compile-Time Library Version Numbers
67**
68** The version of the SQLite library is contained in the sqlite3.h
69** header file in a #define named SQLITE_VERSION. The SQLITE_VERSION
70** macro resolves to a string constant.
71**
72** The format of the version string is "X.Y.Z", where
danielk197799ba19e2005-02-05 07:33:34 +000073** X is the major version number, Y is the minor version number and Z
drh6ed48bf2007-06-14 20:57:18 +000074** is the release number. The X.Y.Z might be followed by "alpha" or "beta".
danielk197799ba19e2005-02-05 07:33:34 +000075** For example "3.1.1beta".
76**
drh6ed48bf2007-06-14 20:57:18 +000077** The X value is always 3 in SQLite. The X value only changes when
78** backwards compatibility is broken and we intend to never break
79** backwards compatibility. The Y value only changes when
80** there are major feature enhancements that are forwards compatible
81** but not backwards compatible. The Z value is incremented with
82** each release but resets back to 0 when Y is incremented.
83**
danielk197799ba19e2005-02-05 07:33:34 +000084** The SQLITE_VERSION_NUMBER is an integer with the value
danielk1977e48b1f12007-05-24 09:44:10 +000085** (X*1000000 + Y*1000 + Z). For example, for version "3.1.1beta",
danielk197799ba19e2005-02-05 07:33:34 +000086** SQLITE_VERSION_NUMBER is set to 3001001. To detect if they are using
87** version 3.1.1 or greater at compile time, programs may use the test
88** (SQLITE_VERSION_NUMBER>=3001001).
drh6ed48bf2007-06-14 20:57:18 +000089**
90** See also: [sqlite3_libversion()] and [sqlite3_libversion_number()].
danielk197799ba19e2005-02-05 07:33:34 +000091*/
drh6ed48bf2007-06-14 20:57:18 +000092#define SQLITE_VERSION "--VERS--"
danielk197799ba19e2005-02-05 07:33:34 +000093#define SQLITE_VERSION_NUMBER --VERSION-NUMBER--
drhb86ccfb2003-01-28 23:13:10 +000094
95/*
drh6ed48bf2007-06-14 20:57:18 +000096** CAPI3REF: Run-Time Library Version Numbers
97**
98** These routines return values equivalent to the header constants
99** [SQLITE_VERSION] and [SQLITE_VERSION_NUMBER]. The values returned
100** by this routines should only be different from the header values
101** if you compile your program using an sqlite3.h header from a
102** different version of SQLite that the version of the library you
103** link against.
104**
105** The sqlite3_version[] string constant contains the text of the
106** [SQLITE_VERSION] string. The sqlite3_libversion() function returns
107** a poiner to the sqlite3_version[] string constant. The function
108** is provided for DLL users who can only access functions and not
109** constants within the DLL.
drhb217a572000-08-22 13:40:18 +0000110*/
drh73be5012007-08-08 12:11:21 +0000111SQLITE_EXTERN const char sqlite3_version[];
drha3f70cb2004-09-30 14:24:50 +0000112const char *sqlite3_libversion(void);
danielk197799ba19e2005-02-05 07:33:34 +0000113int sqlite3_libversion_number(void);
114
115/*
drh6ed48bf2007-06-14 20:57:18 +0000116** CAPI3REF: Database Connection Handle
117**
118** Each open SQLite database is represented by pointer to an instance of the
119** opaque structure named "sqlite3". It is useful to think of an sqlite3
drh6d2069d2007-08-14 01:58:53 +0000120** pointer as an object. The [sqlite3_open], [sqlite3_open16], and
121** [sqlite3_open_v2] interfaces are its constructors
drh6ed48bf2007-06-14 20:57:18 +0000122** and [sqlite3_close] is its destructor. There are many other interfaces
123** (such as [sqlite3_prepare_v2], [sqlite3_create_function], and
124** [sqlite3_busy_timeout] to name but three) that are methods on this
125** object.
drh75897232000-05-29 14:26:00 +0000126*/
drh9bb575f2004-09-06 17:24:11 +0000127typedef struct sqlite3 sqlite3;
danielk197765904932004-05-26 06:18:37 +0000128
drh75897232000-05-29 14:26:00 +0000129
130/*
drh6ed48bf2007-06-14 20:57:18 +0000131** CAPI3REF: 64-Bit Integer Types
132**
drhefad9992004-06-22 12:13:55 +0000133** Some compilers do not support the "long long" datatype. So we have
drh6ed48bf2007-06-14 20:57:18 +0000134** to do compiler-specific typedefs for 64-bit signed and unsigned integers.
135**
136** Many SQLite interface functions require a 64-bit integer arguments.
137** Those interfaces are declared using this typedef.
drhefad9992004-06-22 12:13:55 +0000138*/
drh27436af2006-03-28 23:57:17 +0000139#ifdef SQLITE_INT64_TYPE
drh9b8f4472006-04-04 01:54:55 +0000140 typedef SQLITE_INT64_TYPE sqlite_int64;
drh27436af2006-03-28 23:57:17 +0000141 typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;
142#elif defined(_MSC_VER) || defined(__BORLANDC__)
drhefad9992004-06-22 12:13:55 +0000143 typedef __int64 sqlite_int64;
drh1211de32004-07-26 12:24:22 +0000144 typedef unsigned __int64 sqlite_uint64;
drhefad9992004-06-22 12:13:55 +0000145#else
146 typedef long long int sqlite_int64;
drh1211de32004-07-26 12:24:22 +0000147 typedef unsigned long long int sqlite_uint64;
drhefad9992004-06-22 12:13:55 +0000148#endif
drh6d2069d2007-08-14 01:58:53 +0000149typedef sqlite_int64 sqlite3_int64;
150typedef sqlite_uint64 sqlite3_uint64;
drhefad9992004-06-22 12:13:55 +0000151
drhb37df7b2005-10-13 02:09:49 +0000152/*
153** If compiling for a processor that lacks floating point support,
154** substitute integer for floating-point
155*/
156#ifdef SQLITE_OMIT_FLOATING_POINT
drh6d2069d2007-08-14 01:58:53 +0000157# define double sqlite3_int64
drhb37df7b2005-10-13 02:09:49 +0000158#endif
drhefad9992004-06-22 12:13:55 +0000159
160/*
drh6ed48bf2007-06-14 20:57:18 +0000161** CAPI3REF: Closing A Database Connection
drh75897232000-05-29 14:26:00 +0000162**
163** Call this function with a pointer to a structure that was previously
drh6d2069d2007-08-14 01:58:53 +0000164** returned from [sqlite3_open()], [sqlite3_open16()], or
165** [sqlite3_open_v2()] and the corresponding database will by
drh6ed48bf2007-06-14 20:57:18 +0000166** closed.
danielk197796d81f92004-06-19 03:33:57 +0000167**
drh6ed48bf2007-06-14 20:57:18 +0000168** All SQL statements prepared using [sqlite3_prepare_v2()] or
169** [sqlite3_prepare16_v2()] must be destroyed using [sqlite3_finalize()]
170** before this routine is called. Otherwise, SQLITE_BUSY is returned and the
danielk197796d81f92004-06-19 03:33:57 +0000171** database connection remains open.
drhe30f4422007-08-21 16:15:55 +0000172**
173** Passing this routine a database connection that has already been
174** closed results in undefined behavior. If other interfaces that
175** reference the same database connection are pending (either in the
176** same thread or in different threads) when this routine is called,
177** then the behavior is undefined and is almost certainly undesirable.
drh75897232000-05-29 14:26:00 +0000178*/
danielk1977f9d64d22004-06-19 08:18:07 +0000179int sqlite3_close(sqlite3 *);
drh75897232000-05-29 14:26:00 +0000180
181/*
182** The type for a callback function.
drh6ed48bf2007-06-14 20:57:18 +0000183** This is legacy and deprecated. It is included for historical
184** compatibility and is not documented.
drh75897232000-05-29 14:26:00 +0000185*/
drh12057d52004-09-06 17:34:12 +0000186typedef int (*sqlite3_callback)(void*,int,char**, char**);
drh75897232000-05-29 14:26:00 +0000187
188/*
drh6ed48bf2007-06-14 20:57:18 +0000189** CAPI3REF: One-Step Query Execution Interface
190**
191** This interface is used to do a one-time evaluatation of zero
192** or more SQL statements. UTF-8 text of the SQL statements to
193** be evaluted is passed in as the second parameter. The statements
194** are prepared one by one using [sqlite3_prepare()], evaluated
195** using [sqlite3_step()], then destroyed using [sqlite3_finalize()].
drh75897232000-05-29 14:26:00 +0000196**
197** If one or more of the SQL statements are queries, then
198** the callback function specified by the 3rd parameter is
199** invoked once for each row of the query result. This callback
200** should normally return 0. If the callback returns a non-zero
201** value then the query is aborted, all subsequent SQL statements
danielk19776f8a5032004-05-10 10:34:51 +0000202** are skipped and the sqlite3_exec() function returns the SQLITE_ABORT.
drh75897232000-05-29 14:26:00 +0000203**
drh6ed48bf2007-06-14 20:57:18 +0000204** The 4th parameter to this interface is an arbitrary pointer that is
205** passed through to the callback function as its first parameter.
drh75897232000-05-29 14:26:00 +0000206**
207** The 2nd parameter to the callback function is the number of
drhb19a2bc2001-09-16 00:13:26 +0000208** columns in the query result. The 3rd parameter to the callback
drh6ed48bf2007-06-14 20:57:18 +0000209** is an array of strings holding the values for each column
210** as extracted using [sqlite3_column_text()].
211** The 4th parameter to the callback is an array of strings
212** obtained using [sqlite3_column_name()] and holding
drhb19a2bc2001-09-16 00:13:26 +0000213** the names of each column.
drh75897232000-05-29 14:26:00 +0000214**
215** The callback function may be NULL, even for queries. A NULL
216** callback is not an error. It just means that no callback
217** will be invoked.
218**
219** If an error occurs while parsing or evaluating the SQL (but
220** not while executing the callback) then an appropriate error
drh6ed48bf2007-06-14 20:57:18 +0000221** message is written into memory obtained from [sqlite3_malloc()] and
drhb19a2bc2001-09-16 00:13:26 +0000222** *errmsg is made to point to that message. The calling function
223** is responsible for freeing the memory that holds the error
drh6ed48bf2007-06-14 20:57:18 +0000224** message. Use [sqlite3_free()] for this. If errmsg==NULL,
drhb86ccfb2003-01-28 23:13:10 +0000225** then no error message is ever written.
drhb19a2bc2001-09-16 00:13:26 +0000226**
227** The return value is is SQLITE_OK if there are no errors and
drh6ed48bf2007-06-14 20:57:18 +0000228** some other [SQLITE_OK | return code] if there is an error.
229** The particular return value depends on the type of error.
drh58b95762000-06-02 01:17:37 +0000230**
drh75897232000-05-29 14:26:00 +0000231*/
danielk19776f8a5032004-05-10 10:34:51 +0000232int sqlite3_exec(
drh6ed48bf2007-06-14 20:57:18 +0000233 sqlite3*, /* An open database */
234 const char *sql, /* SQL to be evaluted */
235 int (*callback)(void*,int,char**,char**), /* Callback function */
236 void *, /* 1st argument to callback */
237 char **errmsg /* Error msg written here */
drh75897232000-05-29 14:26:00 +0000238);
239
drh58b95762000-06-02 01:17:37 +0000240/*
drh6ed48bf2007-06-14 20:57:18 +0000241** CAPI3REF: Result Codes
242** KEYWORDS: SQLITE_OK
243**
244** Many SQLite functions return an integer result code from the set shown
245** above in order to indicates success or failure.
246**
247** The result codes above are the only ones returned by SQLite in its
248** default configuration. However, the [sqlite3_extended_result_codes()]
249** API can be used to set a database connectoin to return more detailed
250** result codes.
251**
252** See also: [SQLITE_IOERR_READ | extended result codes]
253**
drh58b95762000-06-02 01:17:37 +0000254*/
drh717e6402001-09-27 03:22:32 +0000255#define SQLITE_OK 0 /* Successful result */
drh15b9a152006-01-31 20:49:13 +0000256/* beginning-of-error-codes */
drh717e6402001-09-27 03:22:32 +0000257#define SQLITE_ERROR 1 /* SQL error or missing database */
drh2db0bbc2005-08-11 02:10:18 +0000258#define SQLITE_INTERNAL 2 /* NOT USED. Internal logic error in SQLite */
drh717e6402001-09-27 03:22:32 +0000259#define SQLITE_PERM 3 /* Access permission denied */
260#define SQLITE_ABORT 4 /* Callback routine requested an abort */
261#define SQLITE_BUSY 5 /* The database file is locked */
262#define SQLITE_LOCKED 6 /* A table in the database is locked */
263#define SQLITE_NOMEM 7 /* A malloc() failed */
264#define SQLITE_READONLY 8 /* Attempt to write a readonly database */
drh24cd67e2004-05-10 16:18:47 +0000265#define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite3_interrupt()*/
drh717e6402001-09-27 03:22:32 +0000266#define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */
267#define SQLITE_CORRUPT 11 /* The database disk image is malformed */
drh2db0bbc2005-08-11 02:10:18 +0000268#define SQLITE_NOTFOUND 12 /* NOT USED. Table or record not found */
drh717e6402001-09-27 03:22:32 +0000269#define SQLITE_FULL 13 /* Insertion failed because database is full */
270#define SQLITE_CANTOPEN 14 /* Unable to open the database file */
drh4f0ee682007-03-30 20:43:40 +0000271#define SQLITE_PROTOCOL 15 /* NOT USED. Database lock protocol error */
drh24cd67e2004-05-10 16:18:47 +0000272#define SQLITE_EMPTY 16 /* Database is empty */
drh717e6402001-09-27 03:22:32 +0000273#define SQLITE_SCHEMA 17 /* The database schema changed */
drhc797d4d2007-05-08 01:08:49 +0000274#define SQLITE_TOOBIG 18 /* String or BLOB exceeds size limit */
drh717e6402001-09-27 03:22:32 +0000275#define SQLITE_CONSTRAINT 19 /* Abort due to contraint violation */
drh8aff1012001-12-22 14:49:24 +0000276#define SQLITE_MISMATCH 20 /* Data type mismatch */
drh247be432002-05-10 05:44:55 +0000277#define SQLITE_MISUSE 21 /* Library used incorrectly */
drh8766c342002-11-09 00:33:15 +0000278#define SQLITE_NOLFS 22 /* Uses OS features not supported on host */
drhed6c8672003-01-12 18:02:16 +0000279#define SQLITE_AUTH 23 /* Authorization denied */
drh1c2d8412003-03-31 00:30:47 +0000280#define SQLITE_FORMAT 24 /* Auxiliary database format error */
danielk19776f8a5032004-05-10 10:34:51 +0000281#define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */
drhc602f9a2004-02-12 19:01:04 +0000282#define SQLITE_NOTADB 26 /* File opened that is not a database file */
danielk19776f8a5032004-05-10 10:34:51 +0000283#define SQLITE_ROW 100 /* sqlite3_step() has another row ready */
284#define SQLITE_DONE 101 /* sqlite3_step() has finished executing */
drh15b9a152006-01-31 20:49:13 +0000285/* end-of-error-codes */
drh717e6402001-09-27 03:22:32 +0000286
drhaf9ff332002-01-16 21:00:27 +0000287/*
drh6ed48bf2007-06-14 20:57:18 +0000288** CAPI3REF: Extended Result Codes
drh4ac285a2006-09-15 07:28:50 +0000289**
drh6ed48bf2007-06-14 20:57:18 +0000290** In its default configuration, SQLite API routines return one of 26 integer
291** result codes described at result-codes. However, experience has shown that
292** many of these result codes are too course-grained. They do not provide as
293** much information about problems as users might like. In an effort to
294** address this, newer versions of SQLite (version 3.3.8 and later) include
295** support for additional result codes that provide more detailed information
296** about errors. The extended result codes are enabled (or disabled) for
297** each database
298** connection using the [sqlite3_extended_result_codes()] API.
299**
300** Some of the available extended result codes are listed above.
301** We expect the number of extended result codes will be expand
302** over time. Software that uses extended result codes should expect
303** to see new result codes in future releases of SQLite.
304**
305** The symbolic name for an extended result code always contains a related
306** primary result code as a prefix. Primary result codes contain a single
307** "_" character. Extended result codes contain two or more "_" characters.
308** The numeric value of an extended result code can be converted to its
309** corresponding primary result code by masking off the lower 8 bytes.
drh4ac285a2006-09-15 07:28:50 +0000310**
311** The SQLITE_OK result code will never be extended. It will always
312** be exactly zero.
drh4ac285a2006-09-15 07:28:50 +0000313*/
314#define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8))
315#define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8))
316#define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8))
317#define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4<<8))
318#define SQLITE_IOERR_DIR_FSYNC (SQLITE_IOERR | (5<<8))
319#define SQLITE_IOERR_TRUNCATE (SQLITE_IOERR | (6<<8))
320#define SQLITE_IOERR_FSTAT (SQLITE_IOERR | (7<<8))
321#define SQLITE_IOERR_UNLOCK (SQLITE_IOERR | (8<<8))
322#define SQLITE_IOERR_RDLOCK (SQLITE_IOERR | (9<<8))
danielk1977979f38e2007-03-27 16:19:51 +0000323#define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8))
danielk1977e965ac72007-06-13 15:22:28 +0000324#define SQLITE_IOERR_BLOCKED (SQLITE_IOERR | (11<<8))
drh4ac285a2006-09-15 07:28:50 +0000325
326/*
drh6d2069d2007-08-14 01:58:53 +0000327** CAPI3REF: Flags For File Open Operations
328**
329** Combination of the following bit values are used as the
330** third argument to the [sqlite3_open_v2()] interface and
331** as fourth argument to the xOpen method of the
drhd84f9462007-08-15 11:28:56 +0000332** [sqlite3_vfs] object.
drh6d2069d2007-08-14 01:58:53 +0000333**
334*/
335#define SQLITE_OPEN_READONLY 0x00000001
336#define SQLITE_OPEN_READWRITE 0x00000002
337#define SQLITE_OPEN_CREATE 0x00000004
338#define SQLITE_OPEN_DELETEONCLOSE 0x00000008
339#define SQLITE_OPEN_EXCLUSIVE 0x00000010
340#define SQLITE_OPEN_MAIN_DB 0x00000100
341#define SQLITE_OPEN_TEMP_DB 0x00000200
342#define SQLITE_OPEN_MAIN_JOURNAL 0x00000300
343#define SQLITE_OPEN_TEMP_JOURNAL 0x00000400
344#define SQLITE_OPEN_SUBJOURNAL 0x00000500
345#define SQLITE_OPEN_MASTER_JOURNAL 0x00000600
346
347/*
348** CAPI3REF: Device Characteristics
349**
350** The xDeviceCapabilities method of the [sqlite3_io_methods]
351** object returns an integer which is a vector of the following
352** bit values expressing I/O characteristics of the mass storage
353** device that holds the file that the [sqlite3_io_methods]
354** refers to.
355**
356** The SQLITE_IOCAP_ATOMIC property means that all writes of
357** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values
358** mean that writes of blocks that are nnn bytes in size and
359** are aligned to an address which is an integer multiple of
360** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means
361** that when data is appended to a file, the data is appended
362** first then the size of the file is extended, never the other
363** way around. The SQLITE_IOCAP_SEQUENTIAL property means that
364** information is written to disk in the same order as calls
365** to xWrite().
366*/
367#define SQLITE_IOCAP_ATOMIC 0x00000001
368#define SQLITE_IOCAP_ATOMIC512 0x00000002
369#define SQLITE_IOCAP_ATOMIC1K 0x00000004
370#define SQLITE_IOCAP_ATOMIC2K 0x00000008
371#define SQLITE_IOCAP_ATOMIC4K 0x00000010
372#define SQLITE_IOCAP_ATOMIC8K 0x00000020
373#define SQLITE_IOCAP_ATOMIC16K 0x00000040
374#define SQLITE_IOCAP_ATOMIC32K 0x00000080
375#define SQLITE_IOCAP_ATOMIC64K 0x00000100
376#define SQLITE_IOCAP_SAFE_APPEND 0x00000200
377#define SQLITE_IOCAP_SEQUENTIAL 0x00000400
378
379/*
380** CAPI3REF: File Locking Levels
381**
382** SQLite uses one of the following integer values as the second
383** argument to calls it makes to the xLock() and xUnlock() methods
drhd84f9462007-08-15 11:28:56 +0000384** of an [sqlite3_io_methods] object.
drh6d2069d2007-08-14 01:58:53 +0000385*/
386#define SQLITE_LOCK_NONE 0
387#define SQLITE_LOCK_SHARED 1
388#define SQLITE_LOCK_RESERVED 2
389#define SQLITE_LOCK_PENDING 3
390#define SQLITE_LOCK_EXCLUSIVE 4
391
392/*
393** CAPI3REF: Synchronization Type Flags
394**
395** When SQLite invokes the xSync() method of an [sqlite3_io_methods]
396** object it uses a combination of the following integer values as
397** the second argument.
398**
399** When the SQLITE_SYNC_DATAONLY flag is used, it means that the
400** sync operation only needs to flush data to mass storage. Inode
401** information need not be flushed. The SQLITE_SYNC_BARRIER flag
402** means that the nothing actually needs to be synched to mass storage,
403** but all write operations that occur before the barrier must complete
404** before any write operations that occur after the barrier begin.
405** The SQLITE_SYNC_NORMAL means to use normal fsync() semantics.
406** The SQLITE_SYNC_FULL flag means to use Mac OS-X style fullsync
407** instead of fsync().
408*/
409#define SQLITE_SYNC_BARRIER 0x00001
410#define SQLITE_SYNC_NORMAL 0x00002
411#define SQLITE_SYNC_FULL 0x00003
412#define SQLITE_SYNC_DATAONLY 0x00010
413
414
415/*
416** CAPI3REF: OS Interface Open File Handle
417**
418** An [sqlite3_file] object represents an open file in the OS
419** interface layer. Individual OS interface implementations will
420** want to subclass this object by appending additional fields
drhd84f9462007-08-15 11:28:56 +0000421** of their own use. The pMethods entry is a pointer to an
422** [sqlite3_io_methods] object that defines methods for performing
423** I/O operations on the open file.
drh6d2069d2007-08-14 01:58:53 +0000424*/
425typedef struct sqlite3_file sqlite3_file;
426struct sqlite3_file {
427 struct sqlite3_io_methods *pMethods; /* Methods against the open file */
428};
429
430/*
431** CAPI3REF: OS Interface File Virtual Methods Object
432**
drhd84f9462007-08-15 11:28:56 +0000433** Every open file in the [sqlite3_vfs] xOpen method contains a pointer to
drh6d2069d2007-08-14 01:58:53 +0000434** an instance of the following object. This object defines the
435** methods used to perform various operations against the open file.
drhd84f9462007-08-15 11:28:56 +0000436**
437** The flags argument to xSync may be one of SQLITE_SYNC_BARRIER,
438** SQLITE_SYNC_NORMAL, SQLITE_SYNC_FULL. The first choice means that
439** data is not necessarily synced to disk completely, only that
440** all writes that occur before the sync complete before any
441** writes that occur after the sync. The second flag is the
442** normal fsync(). The third flag is a OS-X style fullsync.
443** The SQLITE_SYNC_DATA flag may be ORed in to indicate that only
444** the data of the file and not its inode needs to be synced.
445**
446** The integer values to xLock() and xUnlock() are one of
447** SQLITE_LOCK_NONE, SQLITE_LOCK_READ, SQLITE_LOCK_RESERVED,
448** SQLITE_LOCK_PENDING, or SQLITE_LOCK_EXCLUSIVE. xLock()
449** increases the lock. xUnlock() decreases the lock.
450** The xCheckReservedLock() method looks
451** to see if any database connection, either in this
452** process or in some other process, is holding an RESERVED,
453** PENDING, or EXCLUSIVE lock on the file. It returns true
454** if such a lock exists and false if not.
455**
456** xBreakLock() attempts to break a lock held by another process.
457** This can be used to remove a stale dot-file lock, for example.
458** It returns 0 on success and non-zero for a failure.
459**
460** The xSectorSize() method returns the sector size of the
461** device that underlies the file. The sector size is the
462** minimum write that can be performed without disturbing
463** other bytes in the file. The xDeviceCharacteristics()
464** method returns a bit vector describing behaviors of the
465** underlying device:
466**
467** <ul>
468** <li> SQLITE_IOCAP_ATOMIC
469** <li> SQLITE_IOCAP_ATOMIC512
470** <li> SQLITE_IOCAP_ATOMIC1K
471** <li> SQLITE_IOCAP_ATOMIC2K
472** <li> SQLITE_IOCAP_ATOMIC4K
473** <li> SQLITE_IOCAP_ATOMIC8K
474** <li> SQLITE_IOCAP_ATOMIC16K
475** <li> SQLITE_IOCAP_ATOMIC32K
476** <li> SQLITE_IOCAP_ATOMIC64K
477** <li> SQLITE_IOCAP_SAFE_APPEND
478** <li> SQLITE_IOCAP_SEQUENTIAL
479** </ul>
480**
481** The SQLITE_IOCAP_ATOMIC property means that all writes of
482** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values
483** mean that writes of blocks that are nnn bytes in size and
484** are aligned to an address which is an integer multiple of
485** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means
486** that when data is appended to a file, the data is appended
487** first then the size of the file is extended, never the other
488** way around. The SQLITE_IOCAP_SEQUENTIAL property means that
489** information is written to disk in the same order as calls
490** to xWrite().
drh6d2069d2007-08-14 01:58:53 +0000491*/
492typedef struct sqlite3_io_methods sqlite3_io_methods;
493struct sqlite3_io_methods {
494 int iVersion;
495 int (*xClose)(sqlite3_file*);
496 int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite_int64 iOfst);
danielk197762079062007-08-15 17:08:46 +0000497 int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite_int64 iOfst);
drh6d2069d2007-08-14 01:58:53 +0000498 int (*xTruncate)(sqlite3_file*, sqlite_int64 size);
499 int (*xSync)(sqlite3_file*, int flags);
500 int (*xFileSize)(sqlite3_file*, sqlite_int64 *pSize);
501 int (*xLock)(sqlite3_file*, int);
502 int (*xUnlock)(sqlite3_file*, int);
drhd84f9462007-08-15 11:28:56 +0000503 int (*xCheckReservedLock)(sqlite3_file*);
drh6d2069d2007-08-14 01:58:53 +0000504 int (*xBreakLock)(sqlite3_file*);
danielk197790949c22007-08-17 16:50:38 +0000505 int (*xLockState)(sqlite3_file *);
drh6d2069d2007-08-14 01:58:53 +0000506 int (*xSectorSize)(sqlite3_file*);
507 int (*xDeviceCharacteristics)(sqlite3_file*);
508 /* Additional methods may be added in future releases */
509};
510
511/*
drhd84f9462007-08-15 11:28:56 +0000512** CAPI3REF: Mutex Handle
drh6d2069d2007-08-14 01:58:53 +0000513**
drhd84f9462007-08-15 11:28:56 +0000514** The mutex module within SQLite defines [sqlite3_mutex] to be an
515** abstract type for a mutex object. The SQLite core never looks
516** at the internal representation of an [sqlite3_mutex]. It only
517** deals with pointers to the [sqlite3_mutex] object.
drh6bdec4a2007-08-16 19:40:16 +0000518**
519** Mutexes are created using [sqlite3_mutex_alloc()].
drh6d2069d2007-08-14 01:58:53 +0000520*/
521typedef struct sqlite3_mutex sqlite3_mutex;
522
523/*
524** CAPI3REF: OS Interface Object
525**
drhd84f9462007-08-15 11:28:56 +0000526** An instance of this object defines the interface between the
527** SQLite core and the underlying operating system. The "vfs"
528** in the name of the object stands for "virtual file system".
drh6d2069d2007-08-14 01:58:53 +0000529**
530** The iVersion field is initially 1 but may be larger for future
drh6bdec4a2007-08-16 19:40:16 +0000531** versions of SQLite. Additional fields may be appended to this
532** object when the iVersion value is increased.
533**
534** The szOsFile field is the size of the subclassed sqlite3_file
drhd84f9462007-08-15 11:28:56 +0000535** structure used by this VFS. mxPathname is the maximum length of
536** a pathname in this VFS.
537**
538** The nRef field is incremented and decremented by SQLite to keep
539** count of the number of users of the VFS. This field and
540** vfsMutex, pNext, and pPrev are the only fields in the sqlite3_vfs
drh6bdec4a2007-08-16 19:40:16 +0000541** structure that SQLite will ever modify. SQLite will only access
542** or modify these fields while holding a particular static mutex.
543** The application should never modify any fields of the sqlite3_vfs
544** object once the object has been registered.
drh6d2069d2007-08-14 01:58:53 +0000545**
drhd84f9462007-08-15 11:28:56 +0000546** The sqlite3_vfs.vfsMutex is a mutex used by the OS interface.
547** It should initially be NULL. SQLite will initialize this field
drh6bdec4a2007-08-16 19:40:16 +0000548** using sqlite3_mutex_alloc() upon first use of the adaptor
drhd84f9462007-08-15 11:28:56 +0000549** by sqlite3_open_v2() and will deallocate the mutex when the
550** last user closes. In other words, vfsMutex will be allocated
551** when nRef transitions from 0 to 1 and will be deallocated when
552** nRef transitions from 1 to 0.
553**
554** Registered vfs modules are kept on a linked list formed by
555** the pNext and pPrev pointers. The [sqlite3_register_vfs()]
556** and [sqlite3_unregister_vfs()] interfaces manage this list
drhd677b3d2007-08-20 22:48:41 +0000557** in a thread-safe way. The [sqlite3_acquire_vfs()] searches the
drhd84f9462007-08-15 11:28:56 +0000558** list.
559**
560** The zName field holds the name of the VFS module. The name must
561** be unique across all VFS modules.
562**
drh6d2069d2007-08-14 01:58:53 +0000563** SQLite will guarantee that the zFilename string passed to
564** xOpen() is a full pathname as generated by xFullPathname() and
565** that the string will be valid and unchanged until xClose() is
drhd84f9462007-08-15 11:28:56 +0000566** called. So the sqlite3_file can store a pointer to the
drh6d2069d2007-08-14 01:58:53 +0000567** filename if it needs to remember the filename for some reason.
drhd84f9462007-08-15 11:28:56 +0000568**
drh6d2069d2007-08-14 01:58:53 +0000569** The flags argument to xOpen() is a copy of the flags argument
drhd84f9462007-08-15 11:28:56 +0000570** to sqlite3_open_v2(). If sqlite3_open() or sqlite3_open16()
571** is used, then flags is SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE.
drh6d2069d2007-08-14 01:58:53 +0000572** If xOpen() opens a file read-only then it sets *pOutFlags to
drhd84f9462007-08-15 11:28:56 +0000573** include SQLITE_OPEN_READONLY. Other bits in *pOutFlags may be
drh6d2069d2007-08-14 01:58:53 +0000574** set.
575**
576** SQLite will also add one of the following flags to the xOpen()
577** call, depending on the object being opened:
578**
579** <ul>
580** <li> [SQLITE_OPEN_MAIN_DB]
581** <li> [SQLITE_OPEN_MAIN_JOURNAL]
582** <li> [SQLITE_OPEN_TEMP_DB]
583** <li> [SQLITE_OPEN_TEMP_JOURNAL]
584** <li> [SQLITE_OPEN_SUBJOURNAL]
585** <li> [SQLITE_OPEN_MASTER_JOURNAL]
586** </ul>
drhd84f9462007-08-15 11:28:56 +0000587**
drh6d2069d2007-08-14 01:58:53 +0000588** The file I/O implementation can use the object type flags to
589** changes the way it deals with files. For example, an application
590** that does not care about crash recovery or rollback, might make
591** the open of a journal file a no-op. Writes to this journal are
drhd84f9462007-08-15 11:28:56 +0000592** also a no-op. Any attempt to read the journal return SQLITE_IOERR.
drh6d2069d2007-08-14 01:58:53 +0000593** Or the implementation might recognize the a database file will
594** be doing page-aligned sector reads and writes in a random order
595** and set up its I/O subsystem accordingly.
596**
597** SQLite might also add one of the following flags to the xOpen
598** method:
599**
600** <ul>
601** <li> [SQLITE_OPEN_DELETEONCLOSE]
602** <li> [SQLITE_OPEN_EXCLUSIVE]
603** </ul>
604**
605** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
606** deleted when it is closed. This will always be set for TEMP
607** databases and journals and for subjournals. The
608** [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened
609** for exclusive access. This flag is set for all files except
610** for the main database file.
611**
612** The sqlite3_file structure passed as the third argument to
613** xOpen is allocated by the caller. xOpen just fills it in. The
614** caller allocates a minimum of szOsFile bytes for the sqlite3_file
615** structure.
616**
617** The flags argument to xAccess() may be 0 (to test for the
618** existance of a file) or SQLITE_ACCESS_READWRITE to test to see
619** if a file is readable and writable, or SQLITE_ACCESS_READONLY
620** to test to see if a file is read-only. The file can be a
621** directory.
622**
623** SQLite will always allocate at least mxPathname+1 byte for
624** the output buffers for xGetTempName and xFullPathname.
625**
drhd84f9462007-08-15 11:28:56 +0000626** The xRandomness(), xSleep(), and xCurrentTime() interfaces
627** are not strictly a part of the filesystem, but they are
628** included in the VFS structure for completeness.
drh6d2069d2007-08-14 01:58:53 +0000629** The xRandomness() function attempts to return nBytes bytes
630** of good-quality randomness into zOut. The return value is
drhd84f9462007-08-15 11:28:56 +0000631** the actual number of bytes of randomness generated. The
632** xSleep() method cause the calling thread to sleep for at
633** least the number of microseconds given. The xCurrentTime()
634** method returns a Julian Day Number for the current date and
635** time.
drh6d2069d2007-08-14 01:58:53 +0000636*/
drhd84f9462007-08-15 11:28:56 +0000637typedef struct sqlite3_vfs sqlite3_vfs;
638struct sqlite3_vfs {
drh6d2069d2007-08-14 01:58:53 +0000639 int iVersion; /* Structure version number */
640 int szOsFile; /* Size of subclassed sqlite3_file */
drh6d2069d2007-08-14 01:58:53 +0000641 int mxPathname; /* Maximum file pathname length */
drhd84f9462007-08-15 11:28:56 +0000642 int nRef; /* Number of references to this structure */
643 sqlite3_mutex *vfsMutex; /* A mutex for this VFS */
644 sqlite3_vfs *pNext; /* Next registered VFS */
drhd84f9462007-08-15 11:28:56 +0000645 const char *zName; /* Name of this virtual file system */
drh6d2069d2007-08-14 01:58:53 +0000646 void *pAppData; /* Application context */
647 int (*xOpen)(void *pAppData, const char *zName, sqlite3_file*,
648 int flags, int *pOutFlags);
danielk1977fee2d252007-08-18 10:59:19 +0000649 int (*xDelete)(void *pAppData, const char *zName, int syncDir);
drh6d2069d2007-08-14 01:58:53 +0000650 int (*xAccess)(void *pAppData, const char *zName, int flags);
651 int (*xGetTempName)(void *pAppData, char *zOut);
652 int (*xFullPathname)(void *pAppData, const char *zName, char *zOut);
danielk1977b4b47412007-08-17 15:53:36 +0000653 void *(*xDlOpen)(void *pAppData, const char *zFilename);
654 void (*xDlError)(void *pAppData, int nByte, char *zErrMsg);
drh6d2069d2007-08-14 01:58:53 +0000655 void *(*xDlSym)(void*, const char *zSymbol);
danielk1977b4b47412007-08-17 15:53:36 +0000656 void (*xDlClose)(void*);
drh6d2069d2007-08-14 01:58:53 +0000657 int (*xRandomness)(void *pAppData, int nByte, char *zOut);
658 int (*xSleep)(void *pAppData, int microseconds);
659 int (*xCurrentTime)(void *pAppData, double*);
drhd84f9462007-08-15 11:28:56 +0000660 /* New fields may be appended in figure versions. The iVersion
drh6d2069d2007-08-14 01:58:53 +0000661 ** value will increment whenever this happens. */
662};
663
danielk1977b4b47412007-08-17 15:53:36 +0000664#define SQLITE_ACCESS_EXISTS 0
665#define SQLITE_ACCESS_READWRITE 1
666#define SQLITE_ACCESS_READONLY 2
667
drh6d2069d2007-08-14 01:58:53 +0000668/*
drh6ed48bf2007-06-14 20:57:18 +0000669** CAPI3REF: Enable Or Disable Extended Result Codes
670**
671** This routine enables or disables the
672** [SQLITE_IOERR_READ | extended result codes] feature.
673** By default, SQLite API routines return one of only 26 integer
674** [SQLITE_OK | result codes]. When extended result codes
675** are enabled by this routine, the repetoire of result codes can be
676** much larger and can (hopefully) provide more detailed information
677** about the cause of an error.
678**
679** The second argument is a boolean value that turns extended result
680** codes on and off. Extended result codes are off by default for
681** backwards compatibility with older versions of SQLite.
drh4ac285a2006-09-15 07:28:50 +0000682*/
683int sqlite3_extended_result_codes(sqlite3*, int onoff);
684
685/*
drh6ed48bf2007-06-14 20:57:18 +0000686** CAPI3REF: Last Insert Rowid
687**
688** Each entry in an SQLite table has a unique 64-bit signed integer key
689** called the "rowid". The rowid is always available as an undeclared
690** column named ROWID, OID, or _ROWID_. If the table has a column of
691** type INTEGER PRIMARY KEY then that column is another an alias for the
692** rowid.
693**
694** This routine returns the rowid of the most recent INSERT into
695** the database from the database connection given in the first
696** argument. If no inserts have ever occurred on this database
697** connection, zero is returned.
698**
699** If an INSERT occurs within a trigger, then the rowid of the
700** inserted row is returned by this routine as long as the trigger
701** is running. But once the trigger terminates, the value returned
702** by this routine reverts to the last value inserted before the
703** trigger fired.
drhe30f4422007-08-21 16:15:55 +0000704**
705** If another thread does a new insert on the same database connection
706** while this routine is running and thus changes the last insert rowid,
707** then the return value of this routine is undefined.
drhaf9ff332002-01-16 21:00:27 +0000708*/
drh6d2069d2007-08-14 01:58:53 +0000709sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
drhaf9ff332002-01-16 21:00:27 +0000710
drhc8d30ac2002-04-12 10:08:59 +0000711/*
drh6ed48bf2007-06-14 20:57:18 +0000712** CAPI3REF: Count The Number Of Rows Modified
713**
drhc8d30ac2002-04-12 10:08:59 +0000714** This function returns the number of database rows that were changed
drh930cc582007-03-28 13:07:40 +0000715** (or inserted or deleted) by the most recent SQL statement. Only
716** changes that are directly specified by the INSERT, UPDATE, or
717** DELETE statement are counted. Auxiliary changes caused by
drh6ed48bf2007-06-14 20:57:18 +0000718** triggers are not counted. Use the [sqlite3_total_changes()] function
719** to find the total number of changes including changes caused by triggers.
720**
721** Within the body of a trigger, the sqlite3_changes() interface can be
722** called to find the number of
drh930cc582007-03-28 13:07:40 +0000723** changes in the most recently completed INSERT, UPDATE, or DELETE
724** statement within the body of the trigger.
drhc8d30ac2002-04-12 10:08:59 +0000725**
726** All changes are counted, even if they were later undone by a
727** ROLLBACK or ABORT. Except, changes associated with creating and
728** dropping tables are not counted.
729**
drh6ed48bf2007-06-14 20:57:18 +0000730** If a callback invokes [sqlite3_exec()] or [sqlite3_step()] recursively,
drh930cc582007-03-28 13:07:40 +0000731** then the changes in the inner, recursive call are counted together
732** with the changes in the outer call.
drhc8d30ac2002-04-12 10:08:59 +0000733**
734** SQLite implements the command "DELETE FROM table" without a WHERE clause
735** by dropping and recreating the table. (This is much faster than going
drha6b81ba2007-06-27 10:21:38 +0000736** through and deleting individual elements from the table.) Because of
drhc8d30ac2002-04-12 10:08:59 +0000737** this optimization, the change count for "DELETE FROM table" will be
738** zero regardless of the number of elements that were originally in the
739** table. To get an accurate count of the number of rows deleted, use
740** "DELETE FROM table WHERE 1" instead.
drhe30f4422007-08-21 16:15:55 +0000741**
742** If another thread makes changes on the same database connection
743** while this routine is running then the return value of this routine
744** is undefined.
drhc8d30ac2002-04-12 10:08:59 +0000745*/
danielk1977f9d64d22004-06-19 08:18:07 +0000746int sqlite3_changes(sqlite3*);
drhc8d30ac2002-04-12 10:08:59 +0000747
rdcf146a772004-02-25 22:51:06 +0000748/*
drh6ed48bf2007-06-14 20:57:18 +0000749** CAPI3REF: Total Number Of Rows Modified
750***
danielk1977b28af712004-06-21 06:50:26 +0000751** This function returns the number of database rows that have been
752** modified by INSERT, UPDATE or DELETE statements since the database handle
753** was opened. This includes UPDATE, INSERT and DELETE statements executed
754** as part of trigger programs. All changes are counted as soon as the
755** statement that makes them is completed (when the statement handle is
drh6d2069d2007-08-14 01:58:53 +0000756** passed to [sqlite3_reset()] or [sqlite3_finalise()]).
drh6ed48bf2007-06-14 20:57:18 +0000757**
758** See also the [sqlite3_change()] interface.
rdcf146a772004-02-25 22:51:06 +0000759**
760** SQLite implements the command "DELETE FROM table" without a WHERE clause
761** by dropping and recreating the table. (This is much faster than going
762** through and deleting individual elements form the table.) Because of
763** this optimization, the change count for "DELETE FROM table" will be
764** zero regardless of the number of elements that were originally in the
765** table. To get an accurate count of the number of rows deleted, use
766** "DELETE FROM table WHERE 1" instead.
drhe30f4422007-08-21 16:15:55 +0000767**
768** If another thread makes changes on the same database connection
769** while this routine is running then the return value of this routine
770** is undefined.
rdcf146a772004-02-25 22:51:06 +0000771*/
danielk1977b28af712004-06-21 06:50:26 +0000772int sqlite3_total_changes(sqlite3*);
773
drh6ed48bf2007-06-14 20:57:18 +0000774/*
775** CAPI3REF: Interrupt A Long-Running Query
776**
777** This function causes any pending database operation to abort and
drh4c504392000-10-16 22:06:40 +0000778** return at its earliest opportunity. This routine is typically
drh66b89c82000-11-28 20:47:17 +0000779** called in response to a user action such as pressing "Cancel"
drh4c504392000-10-16 22:06:40 +0000780** or Ctrl-C where the user wants a long query operation to halt
781** immediately.
drh930cc582007-03-28 13:07:40 +0000782**
drh6ed48bf2007-06-14 20:57:18 +0000783** It is safe to call this routine from a thread different from the
drh871f6ca2007-08-14 18:03:14 +0000784** thread that is currently running the database operation. But it
785** is not safe to call this routine with a database connection that
786** is closed or might close before sqlite3_interrupt() returns.
drh6ed48bf2007-06-14 20:57:18 +0000787**
788** The SQL operation that is interrupted will return [SQLITE_INTERRUPT].
789** If an interrupted operation was an update that is inside an
790** explicit transaction, then the entire transaction will be rolled
791** back automatically.
drh4c504392000-10-16 22:06:40 +0000792*/
danielk1977f9d64d22004-06-19 08:18:07 +0000793void sqlite3_interrupt(sqlite3*);
drh4c504392000-10-16 22:06:40 +0000794
drh6ed48bf2007-06-14 20:57:18 +0000795/*
796** CAPI3REF: Determine If An SQL Statement Is Complete
797**
798** These functions return true if the given input string comprises
danielk197761de0d12004-05-27 23:56:16 +0000799** one or more complete SQL statements. For the sqlite3_complete() call,
800** the parameter must be a nul-terminated UTF-8 string. For
801** sqlite3_complete16(), a nul-terminated machine byte order UTF-16 string
802** is required.
drh75897232000-05-29 14:26:00 +0000803**
drh6ed48bf2007-06-14 20:57:18 +0000804** These routines are useful for command-line input to determine if the
805** currently entered text forms one or more complete SQL statements or
806** if additional input is needed before sending the statements into
807** SQLite for parsing. The algorithm is simple. If the
drh930cc582007-03-28 13:07:40 +0000808** last token other than spaces and comments is a semicolon, then return
809** true. Actually, the algorithm is a little more complicated than that
810** in order to deal with triggers, but the basic idea is the same: the
811** statement is not complete unless it ends in a semicolon.
drh75897232000-05-29 14:26:00 +0000812*/
danielk19776f8a5032004-05-10 10:34:51 +0000813int sqlite3_complete(const char *sql);
danielk197761de0d12004-05-27 23:56:16 +0000814int sqlite3_complete16(const void *sql);
drh75897232000-05-29 14:26:00 +0000815
drh2dfbbca2000-07-28 14:32:48 +0000816/*
drh6ed48bf2007-06-14 20:57:18 +0000817** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors
818**
819** This routine identifies a callback function that might be invoked
820** whenever an attempt is made to open a database table
821** that another thread or process has locked.
822** If the busy callback is NULL, then [SQLITE_BUSY]
823** (or sometimes [SQLITE_IOERR_BLOCKED])
824** is returned immediately upon encountering the lock.
825** If the busy callback is not NULL, then the
826** callback will be invoked with two arguments. The
drh86939b52007-01-10 12:54:51 +0000827** first argument to the handler is a copy of the void* pointer which
828** is the third argument to this routine. The second argument to
829** the handler is the number of times that the busy handler has
drh6ed48bf2007-06-14 20:57:18 +0000830** been invoked for this locking event. If the
831** busy callback returns 0, then no additional attempts are made to
832** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned.
833** If the callback returns non-zero, then another attempt is made to open the
834** database for reading and the cycle repeats.
drh2dfbbca2000-07-28 14:32:48 +0000835**
drh86939b52007-01-10 12:54:51 +0000836** The presence of a busy handler does not guarantee that
837** it will be invoked when there is lock contention.
838** If SQLite determines that invoking the busy handler could result in
drh6ed48bf2007-06-14 20:57:18 +0000839** a deadlock, it will return [SQLITE_BUSY] instead.
drh86939b52007-01-10 12:54:51 +0000840** Consider a scenario where one process is holding a read lock that
841** it is trying to promote to a reserved lock and
842** a second process is holding a reserved lock that it is trying
843** to promote to an exclusive lock. The first process cannot proceed
844** because it is blocked by the second and the second process cannot
845** proceed because it is blocked by the first. If both processes
846** invoke the busy handlers, neither will make any progress. Therefore,
drh6ed48bf2007-06-14 20:57:18 +0000847** SQLite returns [SQLITE_BUSY] for the first process, hoping that this
drh86939b52007-01-10 12:54:51 +0000848** will induce the first process to release its read lock and allow
849** the second process to proceed.
850**
drh2dfbbca2000-07-28 14:32:48 +0000851** The default busy callback is NULL.
852**
drh6ed48bf2007-06-14 20:57:18 +0000853** The [SQLITE_BUSY] error is converted to [SQLITE_IOERR_BLOCKED] when
854** SQLite is in the middle of a large transaction where all the
855** changes will not fit into the in-memory cache. SQLite will
856** already hold a RESERVED lock on the database file, but it needs
857** to promote this lock to EXCLUSIVE so that it can spill cache
858** pages into the database file without harm to concurrent
859** readers. If it is unable to promote the lock, then the in-memory
860** cache will be left in an inconsistent state and so the error
861** code is promoted from the relatively benign [SQLITE_BUSY] to
862** the more severe [SQLITE_IOERR_BLOCKED]. This error code promotion
863** forces an automatic rollback of the changes. See the
864** <a href="http://www.sqlite.org/cvstrac/wiki?p=CorruptionFollowingBusyError">
865** CorruptionFollowingBusyError</a> wiki page for a discussion of why
866** this is important.
867**
drh2dfbbca2000-07-28 14:32:48 +0000868** Sqlite is re-entrant, so the busy handler may start a new query.
drh6ed48bf2007-06-14 20:57:18 +0000869** (It is not clear why anyone would every want to do this, but it
drh2dfbbca2000-07-28 14:32:48 +0000870** is allowed, in theory.) But the busy handler may not close the
871** database. Closing the database from a busy handler will delete
872** data structures out from under the executing query and will
drh6ed48bf2007-06-14 20:57:18 +0000873** probably result in a segmentation fault or other runtime error.
874**
875** There can only be a single busy handler defined for each database
876** connection. Setting a new busy handler clears any previous one.
877** Note that calling [sqlite3_busy_timeout()] will also set or clear
878** the busy handler.
drhd677b3d2007-08-20 22:48:41 +0000879**
880** When operating in [sqlite3_enable_shared_cache | shared cache mode],
881** only a single busy handler can be defined for each database file.
882** So if two database connections share a single cache, then changing
883** the busy handler on one connection will also change the busy
884** handler in the other connection. The busy handler is invoked
885** in the thread that was running when the SQLITE_BUSY was hit.
drh2dfbbca2000-07-28 14:32:48 +0000886*/
danielk1977f9d64d22004-06-19 08:18:07 +0000887int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
drh2dfbbca2000-07-28 14:32:48 +0000888
889/*
drh6ed48bf2007-06-14 20:57:18 +0000890** CAPI3REF: Set A Busy Timeout
891**
drh2dfbbca2000-07-28 14:32:48 +0000892** This routine sets a busy handler that sleeps for a while when a
893** table is locked. The handler will sleep multiple times until
drh6ed48bf2007-06-14 20:57:18 +0000894** at least "ms" milliseconds of sleeping have been done. After
895** "ms" milliseconds of sleeping, the handler returns 0 which
896** causes [sqlite3_step()] to return [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED].
drh2dfbbca2000-07-28 14:32:48 +0000897**
898** Calling this routine with an argument less than or equal to zero
899** turns off all busy handlers.
drh6ed48bf2007-06-14 20:57:18 +0000900**
901** There can only be a single busy handler for a particular database
902** connection. If another busy handler was defined
903** (using [sqlite3_busy_handler()]) prior to calling
904** this routine, that other busy handler is cleared.
drh2dfbbca2000-07-28 14:32:48 +0000905*/
danielk1977f9d64d22004-06-19 08:18:07 +0000906int sqlite3_busy_timeout(sqlite3*, int ms);
drh2dfbbca2000-07-28 14:32:48 +0000907
drhe3710332000-09-29 13:30:53 +0000908/*
drh6ed48bf2007-06-14 20:57:18 +0000909** CAPI3REF: Convenience Routines For Running Queries
910**
911** This next routine is a convenience wrapper around [sqlite3_exec()].
drhe3710332000-09-29 13:30:53 +0000912** Instead of invoking a user-supplied callback for each row of the
913** result, this routine remembers each row of the result in memory
drh6ed48bf2007-06-14 20:57:18 +0000914** obtained from [sqlite3_malloc()], then returns all of the result after the
drha18c5682000-10-08 22:20:57 +0000915** query has finished.
916**
917** As an example, suppose the query result where this table:
918**
drh6ed48bf2007-06-14 20:57:18 +0000919** <pre>
drha18c5682000-10-08 22:20:57 +0000920** Name | Age
921** -----------------------
922** Alice | 43
923** Bob | 28
924** Cindy | 21
drh6ed48bf2007-06-14 20:57:18 +0000925** </pre>
drha18c5682000-10-08 22:20:57 +0000926**
927** If the 3rd argument were &azResult then after the function returns
drh98699b52000-10-09 12:57:00 +0000928** azResult will contain the following data:
drha18c5682000-10-08 22:20:57 +0000929**
drh6ed48bf2007-06-14 20:57:18 +0000930** <pre>
drha18c5682000-10-08 22:20:57 +0000931** azResult[0] = "Name";
932** azResult[1] = "Age";
933** azResult[2] = "Alice";
934** azResult[3] = "43";
935** azResult[4] = "Bob";
936** azResult[5] = "28";
937** azResult[6] = "Cindy";
938** azResult[7] = "21";
drh6ed48bf2007-06-14 20:57:18 +0000939** </pre>
drha18c5682000-10-08 22:20:57 +0000940**
941** Notice that there is an extra row of data containing the column
942** headers. But the *nrow return value is still 3. *ncolumn is
943** set to 2. In general, the number of values inserted into azResult
944** will be ((*nrow) + 1)*(*ncolumn).
945**
946** After the calling function has finished using the result, it should
danielk19776f8a5032004-05-10 10:34:51 +0000947** pass the result data pointer to sqlite3_free_table() in order to
drha18c5682000-10-08 22:20:57 +0000948** release the memory that was malloc-ed. Because of the way the
drh6ed48bf2007-06-14 20:57:18 +0000949** [sqlite3_malloc()] happens, the calling function must not try to call
950** [sqlite3_free()] directly. Only [sqlite3_free_table()] is able to release
drha18c5682000-10-08 22:20:57 +0000951** the memory properly and safely.
drhe3710332000-09-29 13:30:53 +0000952**
drh6ed48bf2007-06-14 20:57:18 +0000953** The return value of this routine is the same as from [sqlite3_exec()].
drhe3710332000-09-29 13:30:53 +0000954*/
danielk19776f8a5032004-05-10 10:34:51 +0000955int sqlite3_get_table(
drh6ed48bf2007-06-14 20:57:18 +0000956 sqlite3*, /* An open database */
drh9f71c2e2001-11-03 23:57:09 +0000957 const char *sql, /* SQL to be executed */
drhe3710332000-09-29 13:30:53 +0000958 char ***resultp, /* Result written to a char *[] that this points to */
959 int *nrow, /* Number of result rows written here */
960 int *ncolumn, /* Number of result columns written here */
961 char **errmsg /* Error msg written here */
962);
danielk19776f8a5032004-05-10 10:34:51 +0000963void sqlite3_free_table(char **result);
drhe3710332000-09-29 13:30:53 +0000964
drha18c5682000-10-08 22:20:57 +0000965/*
drh6ed48bf2007-06-14 20:57:18 +0000966** CAPI3REF: Formatted String Printing Functions
967**
968** These routines are workalikes of the "printf()" family of functions
969** from the standard C library.
970**
971** The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
drh6d2069d2007-08-14 01:58:53 +0000972** results into memory obtained from [sqlite3_malloc()].
drh6ed48bf2007-06-14 20:57:18 +0000973** The strings returned by these two routines should be
974** released by [sqlite3_free()]. Both routines return a
975** NULL pointer if [sqlite3_malloc()] is unable to allocate enough
976** memory to hold the resulting string.
977**
978** In sqlite3_snprintf() routine is similar to "snprintf()" from
979** the standard C library. The result is written into the
980** buffer supplied as the second parameter whose size is given by
981** the first parameter. Note that the order of the
982** first two parameters is reversed from snprintf(). This is an
983** historical accident that cannot be fixed without breaking
984** backwards compatibility. Note also that sqlite3_snprintf()
985** returns a pointer to its buffer instead of the number of
986** characters actually written into the buffer. We admit that
987** the number of characters written would be a more useful return
988** value but we cannot change the implementation of sqlite3_snprintf()
989** now without breaking compatibility.
990**
991** As long as the buffer size is greater than zero, sqlite3_snprintf()
992** guarantees that the buffer is always zero-terminated. The first
993** parameter "n" is the total size of the buffer, including space for
994** the zero terminator. So the longest string that can be completely
995** written will be n-1 characters.
996**
997** These routines all implement some additional formatting
drh4f26d6c2004-05-26 23:25:30 +0000998** options that are useful for constructing SQL statements.
drha18c5682000-10-08 22:20:57 +0000999** All of the usual printf formatting options apply. In addition, there
drh6ed48bf2007-06-14 20:57:18 +00001000** is are "%q" and "%Q" options.
1001**
1002** The %q option works like %s in that it substitutes a null-terminated
drh66b89c82000-11-28 20:47:17 +00001003** string from the argument list. But %q also doubles every '\'' character.
drha18c5682000-10-08 22:20:57 +00001004** %q is designed for use inside a string literal. By doubling each '\''
drh66b89c82000-11-28 20:47:17 +00001005** character it escapes that character and allows it to be inserted into
drha18c5682000-10-08 22:20:57 +00001006** the string.
1007**
1008** For example, so some string variable contains text as follows:
1009**
drh6ed48bf2007-06-14 20:57:18 +00001010** <blockquote><pre>
1011** char *zText = "It's a happy day!";
1012** </pre></blockquote>
drha18c5682000-10-08 22:20:57 +00001013**
drh6ed48bf2007-06-14 20:57:18 +00001014** One can use this text in an SQL statement as follows:
drha18c5682000-10-08 22:20:57 +00001015**
drh6ed48bf2007-06-14 20:57:18 +00001016** <blockquote><pre>
1017** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText);
1018** sqlite3_exec(db, zSQL, 0, 0, 0);
1019** sqlite3_free(zSQL);
1020** </pre></blockquote>
drha18c5682000-10-08 22:20:57 +00001021**
1022** Because the %q format string is used, the '\'' character in zText
1023** is escaped and the SQL generated is as follows:
1024**
drh6ed48bf2007-06-14 20:57:18 +00001025** <blockquote><pre>
1026** INSERT INTO table1 VALUES('It''s a happy day!')
1027** </pre></blockquote>
drha18c5682000-10-08 22:20:57 +00001028**
1029** This is correct. Had we used %s instead of %q, the generated SQL
1030** would have looked like this:
1031**
drh6ed48bf2007-06-14 20:57:18 +00001032** <blockquote><pre>
1033** INSERT INTO table1 VALUES('It's a happy day!');
1034** </pre></blockquote>
drha18c5682000-10-08 22:20:57 +00001035**
1036** This second example is an SQL syntax error. As a general rule you
1037** should always use %q instead of %s when inserting text into a string
1038** literal.
drh6ed48bf2007-06-14 20:57:18 +00001039**
1040** The %Q option works like %q except it also adds single quotes around
1041** the outside of the total string. Or if the parameter in the argument
1042** list is a NULL pointer, %Q substitutes the text "NULL" (without single
1043** quotes) in place of the %Q option. So, for example, one could say:
1044**
1045** <blockquote><pre>
1046** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);
1047** sqlite3_exec(db, zSQL, 0, 0, 0);
1048** sqlite3_free(zSQL);
1049** </pre></blockquote>
1050**
1051** The code above will render a correct SQL statement in the zSQL
1052** variable even if the zText variable is a NULL pointer.
drha18c5682000-10-08 22:20:57 +00001053*/
danielk19776f8a5032004-05-10 10:34:51 +00001054char *sqlite3_mprintf(const char*,...);
1055char *sqlite3_vmprintf(const char*, va_list);
drhfeac5f82004-08-01 00:10:45 +00001056char *sqlite3_snprintf(int,char*,const char*, ...);
drh5191b7e2002-03-08 02:12:00 +00001057
drh28dd4792006-06-26 21:35:44 +00001058/*
drh90f6a5b2007-08-15 13:04:54 +00001059** CAPI3REF: Memory Allocation Subsystem
drhd84f9462007-08-15 11:28:56 +00001060**
1061** The SQLite core uses these three routines for all of its own
1062** internal memory allocation needs. The default implementation
1063** of the memory allocation subsystem uses the malloc(), realloc()
1064** and free() provided by the standard C library. However, if
1065** SQLite is compiled with the following C preprocessor macro
1066**
drh90f6a5b2007-08-15 13:04:54 +00001067** <blockquote> SQLITE_OMIT_MEMORY_ALLOCATION </blockquote>
drhd84f9462007-08-15 11:28:56 +00001068**
1069** then no implementation is provided for these routines by
1070** SQLite. The application that links against SQLite is
1071** expected to provide its own implementation.
drh28dd4792006-06-26 21:35:44 +00001072*/
drhf3a65f72007-08-22 20:18:21 +00001073void *sqlite3_malloc(int);
1074void *sqlite3_realloc(void*, int);
drh28dd4792006-06-26 21:35:44 +00001075void sqlite3_free(void*);
1076
drh5191b7e2002-03-08 02:12:00 +00001077/*
drhd84f9462007-08-15 11:28:56 +00001078** CAPI3REF: Memory Allocator Statistics
1079**
1080** In addition to the basic three allocation routines
1081** [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()],
1082** the memory allocation subsystem included with the SQLite
1083** sources provides the interfaces shown below.
1084**
1085** The first of these two routines returns the amount of memory
1086** currently outstanding (malloced but not freed). The second
1087** returns the largest instantaneous amount of outstanding
1088** memory. The highwater mark is reset if the argument is
1089** true. The SQLite core does not use either of these routines
1090** and so they do not have to be implemented by the application
1091** if SQLITE_OMIT_MEMORY_ALLOCATION is defined. These routines
1092** are provided by the default memory subsystem for diagnostic
1093** purposes.
1094*/
1095sqlite3_uint64 sqlite3_memory_used(void);
1096sqlite3_uint64 sqlite3_memory_highwater(int resetFlag);
1097
1098/*
1099** CAPI3REF: Memory Allocation Alarms
1100**
1101** The [sqlite3_memory_alarm] routine is used to register
1102** a callback on memory allocation events.
1103**
1104** This routine registers or clears a callbacks that fires when
1105** the amount of memory allocated exceeds iThreshold. Only
1106** a single callback can be registered at a time. Each call
1107** to [sqlite3_memory_alarm()] overwrites the previous callback.
1108** The callback is disabled by setting xCallback to a NULL
1109** pointer.
1110**
1111** The parameters to the callback are the pArg value, the
1112** amount of memory currently in use, and the size of the
1113** allocation that provoked the callback. The callback will
1114** presumably invoke [sqlite3_free()] to free up memory space.
1115** The callback may invoke [sqlite3_malloc()] or [sqlite3_realloc()]
1116** but if it does, no additional callbacks will be invoked by
1117** the recursive calls.
1118**
1119** The [sqlite3_soft_heap_limit()] interface works by registering
1120** a memory alarm at the soft heap limit and invoking
1121** [sqlite3_release_memory()] in the alarm callback. Application
1122** programs should not attempt to use the [sqlite3_memory_alarm()]
1123** interface because doing so will interfere with the
1124** [sqlite3_soft_heap_limit()] module.
1125*/
1126int sqlite3_memory_alarm(
1127 void(*xCallback)(void *pArg, sqlite3_uint64 used, unsigned int N),
1128 void *pArg,
1129 sqlite3_uint64 iThreshold
1130);
1131
1132
1133/*
drh6ed48bf2007-06-14 20:57:18 +00001134** CAPI3REF: Compile-Time Authorization Callbacks
1135***
1136** This routine registers a authorizer callback with the SQLite library.
1137** The authorizer callback is invoked as SQL statements are being compiled
1138** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()],
1139** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()]. At various
1140** points during the compilation process, as logic is being created
1141** to perform various actions, the authorizer callback is invoked to
1142** see if those actions are allowed. The authorizer callback should
1143** return SQLITE_OK to allow the action, [SQLITE_IGNORE] to disallow the
1144** specific action but allow the SQL statement to continue to be
1145** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be
1146** rejected with an error.
1147**
1148** Depending on the action, the [SQLITE_IGNORE] and [SQLITE_DENY] return
1149** codes might mean something different or they might mean the same
1150** thing. If the action is, for example, to perform a delete opertion,
1151** then [SQLITE_IGNORE] and [SQLITE_DENY] both cause the statement compilation
1152** to fail with an error. But if the action is to read a specific column
1153** from a specific table, then [SQLITE_DENY] will cause the entire
1154** statement to fail but [SQLITE_IGNORE] will cause a NULL value to be
1155** read instead of the actual column value.
1156**
1157** The first parameter to the authorizer callback is a copy of
1158** the third parameter to the sqlite3_set_authorizer() interface.
1159** The second parameter to the callback is an integer
1160** [SQLITE_COPY | action code] that specifies the particular action
1161** to be authorized. The available action codes are
1162** [SQLITE_COPY | documented separately]. The third through sixth
1163** parameters to the callback are strings that contain additional
1164** details about the action to be authorized.
1165**
1166** An authorizer is used when preparing SQL statements from an untrusted
1167** source, to ensure that the SQL statements do not try to access data
1168** that they are not allowed to see, or that they do not try to
1169** execute malicious statements that damage the database. For
1170** example, an application may allow a user to enter arbitrary
1171** SQL queries for evaluation by a database. But the application does
1172** not want the user to be able to make arbitrary changes to the
1173** database. An authorizer could then be put in place while the
1174** user-entered SQL is being prepared that disallows everything
1175** except SELECT statements.
1176**
1177** Only a single authorizer can be in place on a database connection
1178** at a time. Each call to sqlite3_set_authorizer overrides the
1179** previous call. A NULL authorizer means that no authorization
1180** callback is invoked. The default authorizer is NULL.
1181**
1182** Note that the authorizer callback is invoked only during
1183** [sqlite3_prepare()] or its variants. Authorization is not
1184** performed during statement evaluation in [sqlite3_step()].
drhed6c8672003-01-12 18:02:16 +00001185*/
danielk19776f8a5032004-05-10 10:34:51 +00001186int sqlite3_set_authorizer(
danielk1977f9d64d22004-06-19 08:18:07 +00001187 sqlite3*,
drhe22a3342003-04-22 20:30:37 +00001188 int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
drhe5f9c642003-01-13 23:27:31 +00001189 void *pUserData
drhed6c8672003-01-12 18:02:16 +00001190);
1191
1192/*
drh6ed48bf2007-06-14 20:57:18 +00001193** CAPI3REF: Authorizer Return Codes
1194**
1195** The [sqlite3_set_authorizer | authorizer callback function] must
1196** return either [SQLITE_OK] or one of these two constants in order
1197** to signal SQLite whether or not the action is permitted. See the
1198** [sqlite3_set_authorizer | authorizer documentation] for additional
1199** information.
1200*/
1201#define SQLITE_DENY 1 /* Abort the SQL statement with an error */
1202#define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */
1203
1204/*
1205** CAPI3REF: Authorizer Action Codes
1206**
1207** The [sqlite3_set_authorizer()] interface registers a callback function
1208** that is invoked to authorizer certain SQL statement actions. The
1209** second parameter to the callback is an integer code that specifies
1210** what action is being authorized. These are the integer action codes that
1211** the authorizer callback may be passed.
1212**
1213** These action code values signify what kind of operation is to be
1214** authorized. The 3rd and 4th parameters to the authorization callback
1215** function will be parameters or NULL depending on which of these
1216** codes is used as the second parameter. The 5th parameter to the
1217** authorizer callback is the name of the database ("main", "temp",
1218** etc.) if applicable. The 6th parameter to the authorizer callback
drh5cf590c2003-04-24 01:45:04 +00001219** is the name of the inner-most trigger or view that is responsible for
1220** the access attempt or NULL if this access attempt is directly from
drh6ed48bf2007-06-14 20:57:18 +00001221** top-level SQL code.
drhed6c8672003-01-12 18:02:16 +00001222*/
drh6ed48bf2007-06-14 20:57:18 +00001223/******************************************* 3rd ************ 4th ***********/
drhe5f9c642003-01-13 23:27:31 +00001224#define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */
1225#define SQLITE_CREATE_TABLE 2 /* Table Name NULL */
1226#define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */
1227#define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */
drh77ad4e42003-01-14 02:49:27 +00001228#define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */
drhe5f9c642003-01-13 23:27:31 +00001229#define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */
drh77ad4e42003-01-14 02:49:27 +00001230#define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */
drhe5f9c642003-01-13 23:27:31 +00001231#define SQLITE_CREATE_VIEW 8 /* View Name NULL */
1232#define SQLITE_DELETE 9 /* Table Name NULL */
drh77ad4e42003-01-14 02:49:27 +00001233#define SQLITE_DROP_INDEX 10 /* Index Name Table Name */
drhe5f9c642003-01-13 23:27:31 +00001234#define SQLITE_DROP_TABLE 11 /* Table Name NULL */
drh77ad4e42003-01-14 02:49:27 +00001235#define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */
drhe5f9c642003-01-13 23:27:31 +00001236#define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */
drh77ad4e42003-01-14 02:49:27 +00001237#define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */
drhe5f9c642003-01-13 23:27:31 +00001238#define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */
drh77ad4e42003-01-14 02:49:27 +00001239#define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */
drhe5f9c642003-01-13 23:27:31 +00001240#define SQLITE_DROP_VIEW 17 /* View Name NULL */
1241#define SQLITE_INSERT 18 /* Table Name NULL */
1242#define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */
1243#define SQLITE_READ 20 /* Table Name Column Name */
1244#define SQLITE_SELECT 21 /* NULL NULL */
1245#define SQLITE_TRANSACTION 22 /* NULL NULL */
1246#define SQLITE_UPDATE 23 /* Table Name Column Name */
drh81e293b2003-06-06 19:00:42 +00001247#define SQLITE_ATTACH 24 /* Filename NULL */
1248#define SQLITE_DETACH 25 /* Database Name NULL */
danielk19771c8c23c2004-11-12 15:53:37 +00001249#define SQLITE_ALTER_TABLE 26 /* Database Name Table Name */
danielk19771d54df82004-11-23 15:41:16 +00001250#define SQLITE_REINDEX 27 /* Index Name NULL */
drhe6e04962005-07-23 02:17:03 +00001251#define SQLITE_ANALYZE 28 /* Table Name NULL */
danielk1977f1a381e2006-06-16 08:01:02 +00001252#define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */
1253#define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */
drh5169bbc2006-08-24 14:59:45 +00001254#define SQLITE_FUNCTION 31 /* Function Name NULL */
drh6ed48bf2007-06-14 20:57:18 +00001255#define SQLITE_COPY 0 /* No longer used */
drhed6c8672003-01-12 18:02:16 +00001256
1257/*
drh6ed48bf2007-06-14 20:57:18 +00001258** CAPI3REF: Tracing And Profiling Functions
1259**
1260** These routines register callback functions that can be used for
1261** tracing and profiling the execution of SQL statements.
1262** The callback function registered by sqlite3_trace() is invoked
1263** at the first [sqlite3_step()] for the evaluation of an SQL statement.
1264** The callback function registered by sqlite3_profile() is invoked
1265** as each SQL statement finishes and includes
drh19e2d372005-08-29 23:00:03 +00001266** information on how long that statement ran.
1267**
1268** The sqlite3_profile() API is currently considered experimental and
1269** is subject to change.
drh18de4822003-01-16 16:28:53 +00001270*/
danielk1977f9d64d22004-06-19 08:18:07 +00001271void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
drh19e2d372005-08-29 23:00:03 +00001272void *sqlite3_profile(sqlite3*,
drh6d2069d2007-08-14 01:58:53 +00001273 void(*xProfile)(void*,const char*,sqlite3_uint64), void*);
drh18de4822003-01-16 16:28:53 +00001274
danielk1977348bb5d2003-10-18 09:37:26 +00001275/*
drh6ed48bf2007-06-14 20:57:18 +00001276** CAPI3REF: Query Progress Callbacks
1277**
danielk1977348bb5d2003-10-18 09:37:26 +00001278** This routine configures a callback function - the progress callback - that
drh6ed48bf2007-06-14 20:57:18 +00001279** is invoked periodically during long running calls to [sqlite3_exec()],
1280** [sqlite3_step()] and [sqlite3_get_table()]. An example use for this
1281** interface is to keep a GUI updated during a large query.
danielk1977348bb5d2003-10-18 09:37:26 +00001282**
1283** The progress callback is invoked once for every N virtual machine opcodes,
1284** where N is the second argument to this function. The progress callback
1285** itself is identified by the third argument to this function. The fourth
1286** argument to this function is a void pointer passed to the progress callback
1287** function each time it is invoked.
1288**
drh6ed48bf2007-06-14 20:57:18 +00001289** If a call to [sqlite3_exec()], [sqlite3_step()], or [sqlite3_get_table()]
1290** results in fewer than N opcodes being executed, then the progress
1291** callback is never invoked.
danielk1977348bb5d2003-10-18 09:37:26 +00001292**
drh6ed48bf2007-06-14 20:57:18 +00001293** Only a single progress callback function may be registered for each
1294** open database connection. Every call to sqlite3_progress_handler()
1295** overwrites the results of the previous call.
danielk1977348bb5d2003-10-18 09:37:26 +00001296** To remove the progress callback altogether, pass NULL as the third
1297** argument to this function.
1298**
1299** If the progress callback returns a result other than 0, then the current
drh6ed48bf2007-06-14 20:57:18 +00001300** query is immediately terminated and any database changes rolled back.
1301** The containing [sqlite3_exec()], [sqlite3_step()], or
1302** [sqlite3_get_table()] call returns SQLITE_INTERRUPT. This feature
1303** can be used, for example, to implement the "Cancel" button on a
1304** progress dialog box in a GUI.
danielk1977348bb5d2003-10-18 09:37:26 +00001305*/
danielk1977f9d64d22004-06-19 08:18:07 +00001306void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
danielk1977348bb5d2003-10-18 09:37:26 +00001307
drhaa940ea2004-01-15 02:44:03 +00001308/*
drh6ed48bf2007-06-14 20:57:18 +00001309** CAPI3REF: Opening A New Database Connection
drhaa940ea2004-01-15 02:44:03 +00001310**
drh4f26d6c2004-05-26 23:25:30 +00001311** Open the sqlite database file "filename". The "filename" is UTF-8
1312** encoded for sqlite3_open() and UTF-16 encoded in the native byte order
drh6ed48bf2007-06-14 20:57:18 +00001313** for sqlite3_open16(). An [sqlite3*] handle is returned in *ppDb, even
drh4f26d6c2004-05-26 23:25:30 +00001314** if an error occurs. If the database is opened (or created) successfully,
drh6d2069d2007-08-14 01:58:53 +00001315** then [SQLITE_OK] is returned. Otherwise an error code is returned. The
1316** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain
drh4f26d6c2004-05-26 23:25:30 +00001317** an English language description of the error.
drh22fbcb82004-02-01 01:22:50 +00001318**
drh6ed48bf2007-06-14 20:57:18 +00001319** If the database file does not exist, then a new database will be created
1320** as needed. The default encoding for the database will be UTF-8 if
1321** sqlite3_open() is called and UTF-16 if sqlite3_open16 is used.
danielk197765904932004-05-26 06:18:37 +00001322**
1323** Whether or not an error occurs when it is opened, resources associated
drh6ed48bf2007-06-14 20:57:18 +00001324** with the [sqlite3*] handle should be released by passing it to
drh6d2069d2007-08-14 01:58:53 +00001325** [sqlite3_close()] when it is no longer required.
1326**
1327** The sqlite3_open_v2() interface works like sqlite3_open() except that
1328** provides two additional parameters for additional control over the
1329** new database connection. The flags parameter can be one of:
1330**
1331** <ol>
1332** <li> [SQLITE_OPEN_READONLY]
1333** <li> [SQLITE_OPEN_READWRITE]
1334** <li> [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]
1335** </ol>
1336**
1337** The first value opens the database read-only. If the database does
1338** not previously exist, an error is returned. The second option opens
1339** the database for reading and writing but the database must already
1340** exist or an error is returned. The third option opens the database
1341** for reading and writing and creates it if it does not already exist.
1342** The third options is behavior that is used always for sqlite3_open()
1343** and sqlite3_open16().
1344**
drhd84f9462007-08-15 11:28:56 +00001345** The fourth parameter to sqlite3_open_v2() is the name of the
1346** [sqlite3_vfs] object that defines the operating system
drh6d2069d2007-08-14 01:58:53 +00001347** interface that the new database connection should use. If the
1348** fourth parameter is a NULL pointer then a default suitable for
1349** the host environment is substituted.
drh6ed48bf2007-06-14 20:57:18 +00001350**
1351** Note to windows users: The encoding used for the filename argument
1352** of sqlite3_open() must be UTF-8, not whatever codepage is currently
1353** defined. Filenames containing international characters must be converted
1354** to UTF-8 prior to passing them into sqlite3_open().
danielk197765904932004-05-26 06:18:37 +00001355*/
1356int sqlite3_open(
1357 const char *filename, /* Database filename (UTF-8) */
danielk19774f057f92004-06-08 00:02:33 +00001358 sqlite3 **ppDb /* OUT: SQLite db handle */
danielk197765904932004-05-26 06:18:37 +00001359);
danielk197765904932004-05-26 06:18:37 +00001360int sqlite3_open16(
1361 const void *filename, /* Database filename (UTF-16) */
danielk19774f057f92004-06-08 00:02:33 +00001362 sqlite3 **ppDb /* OUT: SQLite db handle */
danielk197765904932004-05-26 06:18:37 +00001363);
drh6d2069d2007-08-14 01:58:53 +00001364int sqlite3_open_v2(
drhe30f4422007-08-21 16:15:55 +00001365 const void *filename, /* Database filename (UTF-8) */
drh6d2069d2007-08-14 01:58:53 +00001366 sqlite3 **ppDb, /* OUT: SQLite db handle */
1367 int flags, /* Flags */
drhd84f9462007-08-15 11:28:56 +00001368 const char *zVfs /* Name of VFS module to use */
drh6d2069d2007-08-14 01:58:53 +00001369);
danielk1977295ba552004-05-19 10:34:51 +00001370
danielk197765904932004-05-26 06:18:37 +00001371/*
drh6ed48bf2007-06-14 20:57:18 +00001372** CAPI3REF: Error Codes And Messages
1373**
1374** The sqlite3_errcode() interface returns the numeric
1375** [SQLITE_OK | result code] or [SQLITE_IOERR_READ | extended result code]
1376** for the most recent failed sqlite3_* API call associated
1377** with [sqlite3] handle 'db'. If a prior API call failed but the
1378** most recent API call succeeded, the return value from sqlite3_errcode()
1379** is undefined.
1380**
1381** The sqlite3_errmsg() and sqlite3_errmsg16() return English-langauge
1382** text that describes the error, as either UTF8 or UTF16 respectively.
1383** Memory to hold the error message string is managed internally. The
1384** string may be overwritten or deallocated by subsequent calls to SQLite
1385** interface functions.
danielk197765904932004-05-26 06:18:37 +00001386**
1387** Calls to many sqlite3_* functions set the error code and string returned
drh6ed48bf2007-06-14 20:57:18 +00001388** by [sqlite3_errcode()], [sqlite3_errmsg()], and [sqlite3_errmsg16()]
1389** (overwriting the previous values). Note that calls to [sqlite3_errcode()],
1390** [sqlite3_errmsg()], and [sqlite3_errmsg16()] themselves do not affect the
1391** results of future invocations. Calls to API routines that do not return
1392** an error code (examples: [sqlite3_data_count()] or [sqlite3_mprintf()]) do
1393** not change the error code returned by this routine.
danielk197765904932004-05-26 06:18:37 +00001394**
1395** Assuming no other intervening sqlite3_* API calls are made, the error
1396** code returned by this function is associated with the same error as
drh6ed48bf2007-06-14 20:57:18 +00001397** the strings returned by [sqlite3_errmsg()] and [sqlite3_errmsg16()].
danielk197765904932004-05-26 06:18:37 +00001398*/
1399int sqlite3_errcode(sqlite3 *db);
danielk197765904932004-05-26 06:18:37 +00001400const char *sqlite3_errmsg(sqlite3*);
danielk197765904932004-05-26 06:18:37 +00001401const void *sqlite3_errmsg16(sqlite3*);
1402
1403/*
drh6ed48bf2007-06-14 20:57:18 +00001404** CAPI3REF: SQL Statement Object
1405**
1406** Instance of this object represent single SQL statements. This
1407** is variously known as a "prepared statement" or a
1408** "compiled SQL statement" or simply as a "statement".
1409**
1410** The life of a statement object goes something like this:
1411**
1412** <ol>
1413** <li> Create the object using [sqlite3_prepare_v2()] or a related
1414** function.
1415** <li> Bind values to host parameters using
1416** [sqlite3_bind_blob | sqlite3_bind_* interfaces].
1417** <li> Run the SQL by calling [sqlite3_step()] one or more times.
1418** <li> Reset the statement using [sqlite3_reset()] then go back
1419** to step 2. Do this zero or more times.
1420** <li> Destroy the object using [sqlite3_finalize()].
1421** </ol>
1422**
1423** Refer to documentation on individual methods above for additional
1424** information.
danielk197765904932004-05-26 06:18:37 +00001425*/
danielk1977fc57d7b2004-05-26 02:04:57 +00001426typedef struct sqlite3_stmt sqlite3_stmt;
1427
danielk1977e3209e42004-05-20 01:40:18 +00001428/*
drh6ed48bf2007-06-14 20:57:18 +00001429** CAPI3REF: Compiling An SQL Statement
danielk197765904932004-05-26 06:18:37 +00001430**
drh6ed48bf2007-06-14 20:57:18 +00001431** To execute an SQL query, it must first be compiled into a byte-code
1432** program using one of these routines.
1433**
1434** The first argument "db" is an [sqlite3 | SQLite database handle]
1435** obtained from a prior call to [sqlite3_open()] or [sqlite3_open16()].
1436** The second argument "zSql" is the statement to be compiled, encoded
1437** as either UTF-8 or UTF-16. The sqlite3_prepare() and sqlite3_prepare_v2()
1438** interfaces uses UTF-8 and sqlite3_prepare16() and sqlite3_prepare16_v2()
drh21f06722007-07-19 12:41:39 +00001439** use UTF-16.
1440**
1441** If the nByte argument is less
drh6ed48bf2007-06-14 20:57:18 +00001442** than zero, then zSql is read up to the first zero terminator. If
drh21f06722007-07-19 12:41:39 +00001443** nByte is non-negative, then it is the maximum number of
1444** bytes read from zSql. When nByte is non-negative, the
1445** zSql string ends at either the first '\000' character or
1446** until the nByte-th byte, whichever comes first.
danielk197765904932004-05-26 06:18:37 +00001447**
1448** *pzTail is made to point to the first byte past the end of the first
1449** SQL statement in zSql. This routine only compiles the first statement
1450** in zSql, so *pzTail is left pointing to what remains uncompiled.
1451**
drh6ed48bf2007-06-14 20:57:18 +00001452** *ppStmt is left pointing to a compiled
1453** [sqlite3_stmt | SQL statement structure] that can be
1454** executed using [sqlite3_step()]. Or if there is an error, *ppStmt may be
danielk197765904932004-05-26 06:18:37 +00001455** set to NULL. If the input text contained no SQL (if the input is and
drh6ed48bf2007-06-14 20:57:18 +00001456** empty string or a comment) then *ppStmt is set to NULL. The calling
1457** procedure is responsible for deleting the compiled SQL statement
1458** using [sqlite3_finalize()] after it has finished with it.
danielk197765904932004-05-26 06:18:37 +00001459**
drh6ed48bf2007-06-14 20:57:18 +00001460** On success, [SQLITE_OK] is returned. Otherwise an
1461** [SQLITE_ERROR | error code] is returned.
1462**
1463** The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are
1464** recommended for all new programs. The two older interfaces are retained
1465** for backwards compatibility, but their use is discouraged.
1466** In the "v2" interfaces, the prepared statement
1467** that is returned (the [sqlite3_stmt] object) contains a copy of the
1468** original SQL text. This causes the [sqlite3_step()] interface to
1469** behave a differently in two ways:
1470**
1471** <ol>
1472** <li>
1473** If the database schema changes, instead of returning [SQLITE_SCHEMA] as it
1474** always used to do, [sqlite3_step()] will automatically recompile the SQL
1475** statement and try to run it again. If the schema has changed in a way
1476** that makes the statement no longer valid, [sqlite3_step()] will still
1477** return [SQLITE_SCHEMA]. But unlike the legacy behavior, [SQLITE_SCHEMA] is
1478** now a fatal error. Calling [sqlite3_prepare_v2()] again will not make the
1479** error go away. Note: use [sqlite3_errmsg()] to find the text of the parsing
1480** error that results in an [SQLITE_SCHEMA] return.
1481** </li>
1482**
1483** <li>
1484** When an error occurs,
1485** [sqlite3_step()] will return one of the detailed
1486** [SQLITE_ERROR | result codes] or
1487** [SQLITE_IOERR_READ | extended result codes] such as directly.
1488** The legacy behavior was that [sqlite3_step()] would only return a generic
1489** [SQLITE_ERROR] result code and you would have to make a second call to
1490** [sqlite3_reset()] in order to find the underlying cause of the problem.
1491** With the "v2" prepare interfaces, the underlying reason for the error is
1492** returned immediately.
1493** </li>
1494** </ol>
danielk197765904932004-05-26 06:18:37 +00001495*/
1496int sqlite3_prepare(
1497 sqlite3 *db, /* Database handle */
1498 const char *zSql, /* SQL statement, UTF-8 encoded */
drh21f06722007-07-19 12:41:39 +00001499 int nByte, /* Maximum length of zSql in bytes. */
danielk197765904932004-05-26 06:18:37 +00001500 sqlite3_stmt **ppStmt, /* OUT: Statement handle */
1501 const char **pzTail /* OUT: Pointer to unused portion of zSql */
1502);
drh6ed48bf2007-06-14 20:57:18 +00001503int sqlite3_prepare_v2(
1504 sqlite3 *db, /* Database handle */
1505 const char *zSql, /* SQL statement, UTF-8 encoded */
drh21f06722007-07-19 12:41:39 +00001506 int nByte, /* Maximum length of zSql in bytes. */
drh6ed48bf2007-06-14 20:57:18 +00001507 sqlite3_stmt **ppStmt, /* OUT: Statement handle */
1508 const char **pzTail /* OUT: Pointer to unused portion of zSql */
1509);
danielk197765904932004-05-26 06:18:37 +00001510int sqlite3_prepare16(
1511 sqlite3 *db, /* Database handle */
1512 const void *zSql, /* SQL statement, UTF-16 encoded */
drh21f06722007-07-19 12:41:39 +00001513 int nByte, /* Maximum length of zSql in bytes. */
danielk197765904932004-05-26 06:18:37 +00001514 sqlite3_stmt **ppStmt, /* OUT: Statement handle */
1515 const void **pzTail /* OUT: Pointer to unused portion of zSql */
1516);
drhb900aaf2006-11-09 00:24:53 +00001517int sqlite3_prepare16_v2(
1518 sqlite3 *db, /* Database handle */
1519 const void *zSql, /* SQL statement, UTF-16 encoded */
drh21f06722007-07-19 12:41:39 +00001520 int nByte, /* Maximum length of zSql in bytes. */
drhb900aaf2006-11-09 00:24:53 +00001521 sqlite3_stmt **ppStmt, /* OUT: Statement handle */
1522 const void **pzTail /* OUT: Pointer to unused portion of zSql */
1523);
1524
1525/*
drh6ed48bf2007-06-14 20:57:18 +00001526** CAPI3REF: Dynamically Typed Value Object
1527**
1528** SQLite uses dynamic typing for the values it stores. Values can
1529** be integers, floating point values, strings, BLOBs, or NULL. When
1530** passing around values internally, each value is represented as
1531** an instance of the sqlite3_value object.
drhf4479502004-05-27 03:12:53 +00001532*/
drhf4479502004-05-27 03:12:53 +00001533typedef struct Mem sqlite3_value;
1534
1535/*
drh6ed48bf2007-06-14 20:57:18 +00001536** CAPI3REF: SQL Function Context Object
drh4f26d6c2004-05-26 23:25:30 +00001537**
drh6ed48bf2007-06-14 20:57:18 +00001538** The context in which an SQL function executes is stored in an
1539** sqlite3_context object. A pointer to such an object is the
1540** first parameter to user-defined SQL functions.
1541*/
1542typedef struct sqlite3_context sqlite3_context;
1543
1544/*
1545** CAPI3REF: Binding Values To Prepared Statements
1546**
1547** In the SQL strings input to [sqlite3_prepare_v2()] and its variants,
1548** one or more literals can be replace by a parameter in one of these
1549** forms:
1550**
1551** <ul>
1552** <li> ?
1553** <li> ?NNN
1554** <li> :AAA
1555** <li> @AAA
1556** <li> $VVV
1557** </ul>
1558**
1559** In the parameter forms shown above NNN is an integer literal,
1560** AAA is an alphanumeric identifier and VVV is a variable name according
1561** to the syntax rules of the TCL programming language.
1562** The values of these parameters (also called "host parameter names")
1563** can be set using the sqlite3_bind_*() routines defined here.
1564**
1565** The first argument to the sqlite3_bind_*() routines always is a pointer
1566** to the [sqlite3_stmt] object returned from [sqlite3_prepare_v2()] or
1567** its variants. The second
1568** argument is the index of the parameter to be set. The first parameter has
1569** an index of 1. When the same named parameter is used more than once, second
1570** and subsequent
1571** occurrences have the same index as the first occurrence. The index for
1572** named parameters can be looked up using the
1573** [sqlite3_bind_parameter_name()] API if desired. The index for "?NNN"
1574** parametes is the value of NNN.
1575** The NNN value must be between 1 and the compile-time
1576** parameter SQLITE_MAX_VARIABLE_NUMBER (default value: 999).
1577** See <a href="limits.html">limits.html</a> for additional information.
1578**
1579** The third argument is the value to bind to the parameter.
1580**
1581** In those
1582** routines that have a fourth argument, its value is the number of bytes
1583** in the parameter. To be clear: the value is the number of bytes in the
1584** string, not the number of characters. The number
1585** of bytes does not include the zero-terminator at the end of strings.
1586** If the fourth parameter is negative, the length of the string is
1587** number of bytes up to the first zero terminator.
drh4f26d6c2004-05-26 23:25:30 +00001588**
drh930cc582007-03-28 13:07:40 +00001589** The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and
drh900dfba2004-07-21 15:21:36 +00001590** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or
1591** text after SQLite has finished with it. If the fifth argument is the
drh6ed48bf2007-06-14 20:57:18 +00001592** special value [SQLITE_STATIC], then the library assumes that the information
drh900dfba2004-07-21 15:21:36 +00001593** is in static, unmanaged space and does not need to be freed. If the
drh6ed48bf2007-06-14 20:57:18 +00001594** fifth argument has the value [SQLITE_TRANSIENT], then SQLite makes its
1595** own private copy of the data immediately, before the sqlite3_bind_*()
1596** routine returns.
drh4f26d6c2004-05-26 23:25:30 +00001597**
drh6ed48bf2007-06-14 20:57:18 +00001598** The sqlite3_bind_zeroblob() routine binds a BLOB of length n that
1599** is filled with zeros. A zeroblob uses a fixed amount of memory
1600** (just an integer to hold it size) while it is being processed.
1601** Zeroblobs are intended to serve as place-holders for BLOBs whose
1602** content is later written using
1603** [sqlite3_blob_open | increment BLOB I/O] routines.
1604**
1605** The sqlite3_bind_*() routines must be called after
1606** [sqlite3_prepare_v2()] (and its variants) or [sqlite3_reset()] and
1607** before [sqlite3_step()].
1608** Bindings are not cleared by the [sqlite3_reset()] routine.
1609** Unbound parameters are interpreted as NULL.
1610**
1611** These routines return [SQLITE_OK] on success or an error code if
1612** anything goes wrong. [SQLITE_RANGE] is returned if the parameter
1613** index is out of range. [SQLITE_NOMEM] is returned if malloc fails.
1614** [SQLITE_MISUSE] is returned if these routines are called on a virtual
1615** machine that is the wrong state or which has already been finalized.
drh4f26d6c2004-05-26 23:25:30 +00001616*/
danielk1977d8123362004-06-12 09:25:12 +00001617int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
drhf4479502004-05-27 03:12:53 +00001618int sqlite3_bind_double(sqlite3_stmt*, int, double);
1619int sqlite3_bind_int(sqlite3_stmt*, int, int);
drh6d2069d2007-08-14 01:58:53 +00001620int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
drhf4479502004-05-27 03:12:53 +00001621int sqlite3_bind_null(sqlite3_stmt*, int);
danielk1977d8123362004-06-12 09:25:12 +00001622int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
1623int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
drhf4479502004-05-27 03:12:53 +00001624int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
drhb026e052007-05-02 01:34:31 +00001625int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
drh4f26d6c2004-05-26 23:25:30 +00001626
1627/*
drh6ed48bf2007-06-14 20:57:18 +00001628** CAPI3REF: Number Of Host Parameters
1629**
1630** Return the largest host parameter index in the precompiled statement given
1631** as the argument. When the host parameters are of the forms like ":AAA"
1632** or "?", then they are assigned sequential increasing numbers beginning
1633** with one, so the value returned is the number of parameters. However
1634** if the same host parameter name is used multiple times, each occurrance
1635** is given the same number, so the value returned in that case is the number
1636** of unique host parameter names. If host parameters of the form "?NNN"
1637** are used (where NNN is an integer) then there might be gaps in the
1638** numbering and the value returned by this interface is the index of the
1639** host parameter with the largest index value.
drh605264d2007-08-21 15:13:19 +00001640**
1641** The prepared statement must not not be [sqlite3_finalize | finalized]
1642** prior to this routine returnning. Otherwise the results are undefined
1643** and probably undesirable.
drh75f6a032004-07-15 14:15:00 +00001644*/
1645int sqlite3_bind_parameter_count(sqlite3_stmt*);
1646
1647/*
drh6ed48bf2007-06-14 20:57:18 +00001648** CAPI3REF: Name Of A Host Parameter
1649**
1650** This routine returns a pointer to the name of the n-th parameter in a
1651** [sqlite3_stmt | prepared statement].
1652** Host parameters of the form ":AAA" or "@AAA" or "$VVV" have a name
1653** which is the string ":AAA" or "@AAA" or "$VVV".
1654** In other words, the initial ":" or "$" or "@"
1655** is included as part of the name.
1656** Parameters of the form "?" or "?NNN" have no name.
1657**
1658** The first bound parameter has an index of 1, not 0.
1659**
1660** If the value n is out of range or if the n-th parameter is nameless,
1661** then NULL is returned. The returned string is always in the
1662** UTF-8 encoding even if the named parameter was originally specified
1663** as UTF-16 in [sqlite3_prepare16()] or [sqlite3_prepare16_v2()].
drh895d7472004-08-20 16:02:39 +00001664*/
1665const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
1666
1667/*
drh6ed48bf2007-06-14 20:57:18 +00001668** CAPI3REF: Index Of A Parameter With A Given Name
1669**
1670** This routine returns the index of a host parameter with the given name.
1671** The name must match exactly. If no parameter with the given name is
1672** found, return 0. Parameter names must be UTF8.
drhfa6bc002004-09-07 16:19:52 +00001673*/
1674int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
1675
1676/*
drh6ed48bf2007-06-14 20:57:18 +00001677** CAPI3REF: Reset All Bindings On A Prepared Statement
1678**
1679** Contrary to the intuition of many, [sqlite3_reset()] does not
1680** reset the [sqlite3_bind_blob | bindings] on a
1681** [sqlite3_stmt | prepared statement]. Use this routine to
1682** reset all host parameters to NULL.
danielk1977600dd0b2005-01-20 01:14:23 +00001683*/
1684int sqlite3_clear_bindings(sqlite3_stmt*);
1685
1686/*
drh6ed48bf2007-06-14 20:57:18 +00001687** CAPI3REF: Number Of Columns In A Result Set
1688**
1689** Return the number of columns in the result set returned by the
1690** [sqlite3_stmt | compiled SQL statement]. This routine returns 0
1691** if pStmt is an SQL statement that does not return data (for
1692** example an UPDATE).
danielk197765904932004-05-26 06:18:37 +00001693*/
1694int sqlite3_column_count(sqlite3_stmt *pStmt);
1695
1696/*
drh6ed48bf2007-06-14 20:57:18 +00001697** CAPI3REF: Column Names In A Result Set
1698**
1699** These routines return the name assigned to a particular column
1700** in the result set of a SELECT statement. The sqlite3_column_name()
1701** interface returns a pointer to a UTF8 string and sqlite3_column_name16()
1702** returns a pointer to a UTF16 string. The first parameter is the
drh6d2069d2007-08-14 01:58:53 +00001703** [sqlite3_stmt | prepared statement] that implements the SELECT statement.
drh6ed48bf2007-06-14 20:57:18 +00001704** The second parameter is the column number. The left-most column is
1705** number 0.
1706**
1707** The returned string pointer is valid until either the
drh6d2069d2007-08-14 01:58:53 +00001708** [sqlite3_stmt | prepared statement] is destroyed by [sqlite3_finalize()]
drh6ed48bf2007-06-14 20:57:18 +00001709** or until the next call sqlite3_column_name() or sqlite3_column_name16()
1710** on the same column.
danielk197765904932004-05-26 06:18:37 +00001711*/
drh6ed48bf2007-06-14 20:57:18 +00001712const char *sqlite3_column_name(sqlite3_stmt*, int N);
1713const void *sqlite3_column_name16(sqlite3_stmt*, int N);
danielk197765904932004-05-26 06:18:37 +00001714
1715/*
drh6ed48bf2007-06-14 20:57:18 +00001716** CAPI3REF: Source Of Data In A Query Result
1717**
1718** These routines provide a means to determine what column of what
1719** table in which database a result of a SELECT statement comes from.
1720** The name of the database or table or column can be returned as
drhbf2564f2007-06-21 15:25:05 +00001721** either a UTF8 or UTF16 string. The _database_ routines return
1722** the database name, the _table_ routines return the table name, and
1723** the origin_ routines return the column name.
1724** The returned string is valid until
drh6ed48bf2007-06-14 20:57:18 +00001725** the [sqlite3_stmt | prepared statement] is destroyed using
1726** [sqlite3_finalize()] or until the same information is requested
drhbf2564f2007-06-21 15:25:05 +00001727** again in a different encoding.
1728**
1729** The names returned are the original un-aliased names of the
1730** database, table, and column.
drh6ed48bf2007-06-14 20:57:18 +00001731**
1732** The first argument to the following calls is a
1733** [sqlite3_stmt | compiled SQL statement].
danielk1977955de522006-02-10 02:27:42 +00001734** These functions return information about the Nth column returned by
1735** the statement, where N is the second function argument.
1736**
drh6ed48bf2007-06-14 20:57:18 +00001737** If the Nth column returned by the statement is an expression
1738** or subquery and is not a column value, then all of these functions
1739** return NULL. Otherwise, they return the
1740** name of the attached database, table and column that query result
1741** column was extracted from.
danielk1977955de522006-02-10 02:27:42 +00001742**
1743** As with all other SQLite APIs, those postfixed with "16" return UTF-16
drh6ed48bf2007-06-14 20:57:18 +00001744** encoded strings, the other functions return UTF-8.
danielk19774b1ae992006-02-10 03:06:10 +00001745**
1746** These APIs are only available if the library was compiled with the
1747** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined.
drh32bc3f62007-08-21 20:25:39 +00001748**
1749** If two or more threads call one or more of these routines against the same
1750** prepared statement and column at the same time then the results are
1751** undefined.
danielk1977955de522006-02-10 02:27:42 +00001752*/
1753const char *sqlite3_column_database_name(sqlite3_stmt*,int);
1754const void *sqlite3_column_database_name16(sqlite3_stmt*,int);
1755const char *sqlite3_column_table_name(sqlite3_stmt*,int);
1756const void *sqlite3_column_table_name16(sqlite3_stmt*,int);
1757const char *sqlite3_column_origin_name(sqlite3_stmt*,int);
1758const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);
1759
1760/*
drh6ed48bf2007-06-14 20:57:18 +00001761** CAPI3REF: Declared Datatype Of A Query Result
1762**
1763** The first parameter is a [sqlite3_stmt | compiled SQL statement].
1764** If this statement is a SELECT statement and the Nth column of the
1765** returned result set of that SELECT is a table column (not an
1766** expression or subquery) then the declared type of the table
1767** column is returned. If the Nth column of the result set is an
1768** expression or subquery, then a NULL pointer is returned.
1769** The returned string is always UTF-8 encoded. For example, in
1770** the database schema:
danielk197765904932004-05-26 06:18:37 +00001771**
1772** CREATE TABLE t1(c1 VARIANT);
1773**
1774** And the following statement compiled:
1775**
danielk1977955de522006-02-10 02:27:42 +00001776** SELECT c1 + 1, c1 FROM t1;
danielk197765904932004-05-26 06:18:37 +00001777**
1778** Then this routine would return the string "VARIANT" for the second
1779** result column (i==1), and a NULL pointer for the first result column
1780** (i==0).
drh6ed48bf2007-06-14 20:57:18 +00001781**
1782** SQLite uses dynamic run-time typing. So just because a column
1783** is declared to contain a particular type does not mean that the
1784** data stored in that column is of the declared type. SQLite is
1785** strongly typed, but the typing is dynamic not static. Type
1786** is associated with individual values, not with the containers
1787** used to hold those values.
danielk197765904932004-05-26 06:18:37 +00001788*/
1789const char *sqlite3_column_decltype(sqlite3_stmt *, int i);
danielk197765904932004-05-26 06:18:37 +00001790const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
1791
danielk1977106bb232004-05-21 10:08:53 +00001792/*
drh6ed48bf2007-06-14 20:57:18 +00001793** CAPI3REF: Evaluate An SQL Statement
danielk1977106bb232004-05-21 10:08:53 +00001794**
drh6ed48bf2007-06-14 20:57:18 +00001795** After an [sqlite3_stmt | SQL statement] has been prepared with a call
1796** to either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or to one of
1797** the legacy interfaces [sqlite3_prepare()] or [sqlite3_prepare16()],
1798** then this function must be called one or more times to evaluate the
1799** statement.
danielk1977106bb232004-05-21 10:08:53 +00001800**
drh6ed48bf2007-06-14 20:57:18 +00001801** The details of the behavior of this sqlite3_step() interface depend
1802** on whether the statement was prepared using the newer "v2" interface
1803** [sqlite3_prepare_v2()] and [sqlite3_prepare16_v2()] or the older legacy
1804** interface [sqlite3_prepare()] and [sqlite3_prepare16()]. The use of the
1805** new "v2" interface is recommended for new applications but the legacy
1806** interface will continue to be supported.
danielk1977106bb232004-05-21 10:08:53 +00001807**
drh6ed48bf2007-06-14 20:57:18 +00001808** In the lagacy interface, the return value will be either [SQLITE_BUSY],
1809** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE].
1810** With the "v2" interface, any of the other [SQLITE_OK | result code]
1811** or [SQLITE_IOERR_READ | extended result code] might be returned as
1812** well.
1813**
1814** [SQLITE_BUSY] means that the database engine was unable to acquire the
1815** database locks it needs to do its job. If the statement is a COMMIT
1816** or occurs outside of an explicit transaction, then you can retry the
1817** statement. If the statement is not a COMMIT and occurs within a
1818** explicit transaction then you should rollback the transaction before
1819** continuing.
1820**
1821** [SQLITE_DONE] means that the statement has finished executing
danielk1977106bb232004-05-21 10:08:53 +00001822** successfully. sqlite3_step() should not be called again on this virtual
drh6ed48bf2007-06-14 20:57:18 +00001823** machine without first calling [sqlite3_reset()] to reset the virtual
1824** machine back to its initial state.
danielk1977106bb232004-05-21 10:08:53 +00001825**
1826** If the SQL statement being executed returns any data, then
drh6ed48bf2007-06-14 20:57:18 +00001827** [SQLITE_ROW] is returned each time a new row of data is ready
danielk1977106bb232004-05-21 10:08:53 +00001828** for processing by the caller. The values may be accessed using
drh6ed48bf2007-06-14 20:57:18 +00001829** the [sqlite3_column_int | column access functions].
1830** sqlite3_step() is called again to retrieve the next row of data.
danielk1977106bb232004-05-21 10:08:53 +00001831**
drh6ed48bf2007-06-14 20:57:18 +00001832** [SQLITE_ERROR] means that a run-time error (such as a constraint
danielk1977106bb232004-05-21 10:08:53 +00001833** violation) has occurred. sqlite3_step() should not be called again on
drh6ed48bf2007-06-14 20:57:18 +00001834** the VM. More information may be found by calling [sqlite3_errmsg()].
1835** With the legacy interface, a more specific error code (example:
1836** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth)
1837** can be obtained by calling [sqlite3_reset()] on the
drh6d2069d2007-08-14 01:58:53 +00001838** [sqlite3_stmt | prepared statement]. In the "v2" interface,
drh6ed48bf2007-06-14 20:57:18 +00001839** the more specific error code is returned directly by sqlite3_step().
danielk1977106bb232004-05-21 10:08:53 +00001840**
drh6ed48bf2007-06-14 20:57:18 +00001841** [SQLITE_MISUSE] means that the this routine was called inappropriately.
drh6d2069d2007-08-14 01:58:53 +00001842** Perhaps it was called on a [sqlite3_stmt | prepared statement] that has
drh6ed48bf2007-06-14 20:57:18 +00001843** already been [sqlite3_finalize | finalized] or on one that had
1844** previously returned [SQLITE_ERROR] or [SQLITE_DONE]. Or it could
1845** be the case that the same database connection is being used by two or
1846** more threads at the same moment in time.
1847**
1848** <b>Goofy Interface Alert:</b>
1849** In the legacy interface,
1850** the sqlite3_step() API always returns a generic error code,
1851** [SQLITE_ERROR], following any error other than [SQLITE_BUSY]
1852** and [SQLITE_MISUSE]. You must call [sqlite3_reset()] or
1853** [sqlite3_finalize()] in order to find one of the specific
1854** [SQLITE_ERROR | result codes] that better describes the error.
1855** We admit that this is a goofy design. The problem has been fixed
1856** with the "v2" interface. If you prepare all of your SQL statements
1857** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead
1858** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()], then the
1859** more specific [SQLITE_ERROR | result codes] are returned directly
1860** by sqlite3_step(). The use of the "v2" interface is recommended.
danielk1977106bb232004-05-21 10:08:53 +00001861*/
danielk197717240fd2004-05-26 00:07:25 +00001862int sqlite3_step(sqlite3_stmt*);
danielk1977106bb232004-05-21 10:08:53 +00001863
danielk1977106bb232004-05-21 10:08:53 +00001864/*
drh6ed48bf2007-06-14 20:57:18 +00001865** CAPI3REF:
1866**
danielk1977106bb232004-05-21 10:08:53 +00001867** Return the number of values in the current row of the result set.
1868**
drh6ed48bf2007-06-14 20:57:18 +00001869** After a call to [sqlite3_step()] that returns [SQLITE_ROW], this routine
1870** will return the same value as the [sqlite3_column_count()] function.
1871** After [sqlite3_step()] has returned an [SQLITE_DONE], [SQLITE_BUSY], or
1872** a [SQLITE_ERROR | error code], or before [sqlite3_step()] has been
drh6d2069d2007-08-14 01:58:53 +00001873** called on the [sqlite3_stmt | prepared statement] for the first time,
drh6ed48bf2007-06-14 20:57:18 +00001874** this routine returns zero.
danielk1977106bb232004-05-21 10:08:53 +00001875*/
danielk197793d46752004-05-23 13:30:58 +00001876int sqlite3_data_count(sqlite3_stmt *pStmt);
danielk19774adee202004-05-08 08:23:19 +00001877
drh4f26d6c2004-05-26 23:25:30 +00001878/*
drh6ed48bf2007-06-14 20:57:18 +00001879** CAPI3REF: Fundamental Datatypes
1880**
1881** Every value in SQLite has one of five fundamental datatypes:
1882**
1883** <ul>
1884** <li> 64-bit signed integer
1885** <li> 64-bit IEEE floating point number
1886** <li> string
1887** <li> BLOB
1888** <li> NULL
1889** </ul>
1890**
1891** These constants are codes for each of those types.
1892**
1893** Note that the SQLITE_TEXT constant was also used in SQLite version 2
1894** for a completely different meaning. Software that links against both
1895** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT not
1896** SQLITE_TEXT.
drh4f26d6c2004-05-26 23:25:30 +00001897*/
drh9c054832004-05-31 18:51:57 +00001898#define SQLITE_INTEGER 1
1899#define SQLITE_FLOAT 2
drh9c054832004-05-31 18:51:57 +00001900#define SQLITE_BLOB 4
1901#define SQLITE_NULL 5
drh1e284f42004-10-06 15:52:01 +00001902#ifdef SQLITE_TEXT
1903# undef SQLITE_TEXT
1904#else
1905# define SQLITE_TEXT 3
1906#endif
1907#define SQLITE3_TEXT 3
1908
1909/*
drh6ed48bf2007-06-14 20:57:18 +00001910** CAPI3REF: Results Values From A Query
1911**
drh32bc3f62007-08-21 20:25:39 +00001912** These routines return information about
1913** a single column of the current result row of a query. In every
drh6ed48bf2007-06-14 20:57:18 +00001914** case the first argument is a pointer to the
1915** [sqlite3_stmt | SQL statement] that is being
drh32bc3f62007-08-21 20:25:39 +00001916** evaluated (the [sqlite3_stmt*] that was returned from
drh6ed48bf2007-06-14 20:57:18 +00001917** [sqlite3_prepare_v2()] or one of its variants) and
drh4f26d6c2004-05-26 23:25:30 +00001918** the second argument is the index of the column for which information
drh32bc3f62007-08-21 20:25:39 +00001919** should be returned. The left-most column of the result set
1920** has an index of 0.
danielk1977106bb232004-05-21 10:08:53 +00001921**
drh4f26d6c2004-05-26 23:25:30 +00001922** If the SQL statement is not currently point to a valid row, or if the
drh32bc3f62007-08-21 20:25:39 +00001923** the column index is out of range, the result is undefined.
1924** These routines may only be called when the most recent call to
1925** [sqlite3_step()] has returned [SQLITE_ROW] and neither
1926** [sqlite3_reset()] nor [sqlite3_finalize()] has been call subsequently.
1927** If any of these routines are called after [sqlite3_reset()] or
1928** [sqlite3_finalize()] or after [sqlite3_step()] has returned
1929** something other than [SQLITE_ROW], the results are undefined.
1930** If [sqlite3_step()] or [sqlite3_reset()] or [sqlite3_finalize()]
1931** are called from a different thread while any of these routines
1932** are pending, then the results are undefined.
drh6ed48bf2007-06-14 20:57:18 +00001933**
1934** The sqlite3_column_type() routine returns
1935** [SQLITE_INTEGER | datatype code] for the initial data type
1936** of the result column. The returned value is one of [SQLITE_INTEGER],
1937** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL]. The value
1938** returned by sqlite3_column_type() is only meaningful if no type
1939** conversions have occurred as described below. After a type conversion,
1940** the value returned by sqlite3_column_type() is undefined. Future
1941** versions of SQLite may change the behavior of sqlite3_column_type()
1942** following a type conversion.
1943**
drh6ed48bf2007-06-14 20:57:18 +00001944** If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
1945** routine returns the number of bytes in that BLOB or string.
1946** If the result is a UTF-16 string, then sqlite3_column_bytes() converts
1947** the string to UTF-8 and then returns the number of bytes.
1948** If the result is a numeric value then sqlite3_column_bytes() uses
1949** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns
1950** the number of bytes in that string.
1951** The value returned does not include the zero terminator at the end
1952** of the string. For clarity: the value returned is the number of
1953** bytes in the string, not the number of characters.
1954**
1955** The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes()
1956** but leaves the result in UTF-16 instead of UTF-8.
1957** The zero terminator is not included in this count.
drh4f26d6c2004-05-26 23:25:30 +00001958**
1959** These routines attempt to convert the value where appropriate. For
1960** example, if the internal representation is FLOAT and a text result
drh6ed48bf2007-06-14 20:57:18 +00001961** is requested, [sqlite3_snprintf()] is used internally to do the conversion
drh4f26d6c2004-05-26 23:25:30 +00001962** automatically. The following table details the conversions that
1963** are applied:
1964**
drh6ed48bf2007-06-14 20:57:18 +00001965** <blockquote>
1966** <table border="1">
1967** <tr><th> Internal <th> Requested <th>
1968** <tr><th> Type <th> Type <th> Conversion
drh4f26d6c2004-05-26 23:25:30 +00001969**
drh6ed48bf2007-06-14 20:57:18 +00001970** <tr><td> NULL <td> INTEGER <td> Result is 0
1971** <tr><td> NULL <td> FLOAT <td> Result is 0.0
1972** <tr><td> NULL <td> TEXT <td> Result is NULL pointer
1973** <tr><td> NULL <td> BLOB <td> Result is NULL pointer
1974** <tr><td> INTEGER <td> FLOAT <td> Convert from integer to float
1975** <tr><td> INTEGER <td> TEXT <td> ASCII rendering of the integer
1976** <tr><td> INTEGER <td> BLOB <td> Same as for INTEGER->TEXT
1977** <tr><td> FLOAT <td> INTEGER <td> Convert from float to integer
1978** <tr><td> FLOAT <td> TEXT <td> ASCII rendering of the float
1979** <tr><td> FLOAT <td> BLOB <td> Same as FLOAT->TEXT
1980** <tr><td> TEXT <td> INTEGER <td> Use atoi()
1981** <tr><td> TEXT <td> FLOAT <td> Use atof()
1982** <tr><td> TEXT <td> BLOB <td> No change
1983** <tr><td> BLOB <td> INTEGER <td> Convert to TEXT then use atoi()
1984** <tr><td> BLOB <td> FLOAT <td> Convert to TEXT then use atof()
1985** <tr><td> BLOB <td> TEXT <td> Add a zero terminator if needed
1986** </table>
1987** </blockquote>
drh4f26d6c2004-05-26 23:25:30 +00001988**
drh6ed48bf2007-06-14 20:57:18 +00001989** The table above makes reference to standard C library functions atoi()
1990** and atof(). SQLite does not really use these functions. It has its
1991** on equavalent internal routines. The atoi() and atof() names are
1992** used in the table for brevity and because they are familiar to most
1993** C programmers.
1994**
1995** Note that when type conversions occur, pointers returned by prior
1996** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
1997** sqlite3_column_text16() may be invalidated.
1998** Type conversions and pointer invalidations might occur
1999** in the following cases:
2000**
2001** <ul>
2002** <li><p> The initial content is a BLOB and sqlite3_column_text()
2003** or sqlite3_column_text16() is called. A zero-terminator might
2004** need to be added to the string.</p></li>
2005**
2006** <li><p> The initial content is UTF-8 text and sqlite3_column_bytes16() or
2007** sqlite3_column_text16() is called. The content must be converted
2008** to UTF-16.</p></li>
2009**
2010** <li><p> The initial content is UTF-16 text and sqlite3_column_bytes() or
2011** sqlite3_column_text() is called. The content must be converted
2012** to UTF-8.</p></li>
2013** </ul>
2014**
2015** Conversions between UTF-16be and UTF-16le are always done in place and do
2016** not invalidate a prior pointer, though of course the content of the buffer
2017** that the prior pointer points to will have been modified. Other kinds
2018** of conversion are done in place when it is possible, but sometime it is
2019** not possible and in those cases prior pointers are invalidated.
2020**
2021** The safest and easiest to remember policy is to invoke these routines
2022** in one of the following ways:
2023**
2024** <ul>
2025** <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li>
2026** <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li>
2027** <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li>
2028** </ul>
2029**
2030** In other words, you should call sqlite3_column_text(), sqlite3_column_blob(),
2031** or sqlite3_column_text16() first to force the result into the desired
2032** format, then invoke sqlite3_column_bytes() or sqlite3_column_bytes16() to
2033** find the size of the result. Do not mix call to sqlite3_column_text() or
2034** sqlite3_column_blob() with calls to sqlite3_column_bytes16(). And do not
2035** mix calls to sqlite3_column_text16() with calls to sqlite3_column_bytes().
drh32bc3f62007-08-21 20:25:39 +00002036**
2037** The pointers returned are valid until a type conversion occurs as
2038** described above, or until [sqlite3_step()] or [sqlite3_reset()] or
2039** [sqlite3_finalize()] is called. The memory space used to hold strings
2040** and blobs is freed automatically. Do <b>not</b> pass the pointers returned
2041** [sqlite3_column_blob()], [sqlite_column_text()], etc. into
2042** [sqlite3_free()].
danielk1977106bb232004-05-21 10:08:53 +00002043*/
drhf4479502004-05-27 03:12:53 +00002044const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
2045int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
2046int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
2047double sqlite3_column_double(sqlite3_stmt*, int iCol);
2048int sqlite3_column_int(sqlite3_stmt*, int iCol);
drh6d2069d2007-08-14 01:58:53 +00002049sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
drhf4479502004-05-27 03:12:53 +00002050const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
2051const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
drh4f26d6c2004-05-26 23:25:30 +00002052int sqlite3_column_type(sqlite3_stmt*, int iCol);
drh4be8b512006-06-13 23:51:34 +00002053sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
danielk19774adee202004-05-08 08:23:19 +00002054
danielk197765904932004-05-26 06:18:37 +00002055/*
drh6ed48bf2007-06-14 20:57:18 +00002056** CAPI3REF: Destroy A Prepared Statement Object
2057**
2058** The sqlite3_finalize() function is called to delete a
2059** [sqlite3_stmt | compiled SQL statement]. If the statement was
2060** executed successfully, or not executed at all, then SQLITE_OK is returned.
2061** If execution of the statement failed then an
2062** [SQLITE_ERROR | error code] or [SQLITE_IOERR_READ | extended error code]
2063** is returned.
danielk197765904932004-05-26 06:18:37 +00002064**
2065** This routine can be called at any point during the execution of the
drh6ed48bf2007-06-14 20:57:18 +00002066** [sqlite3_stmt | virtual machine]. If the virtual machine has not
2067** completed execution when this routine is called, that is like
2068** encountering an error or an interrupt. (See [sqlite3_interrupt()].)
2069** Incomplete updates may be rolled back and transactions cancelled,
2070** depending on the circumstances, and the
2071** [SQLITE_ERROR | result code] returned will be [SQLITE_ABORT].
danielk197765904932004-05-26 06:18:37 +00002072*/
2073int sqlite3_finalize(sqlite3_stmt *pStmt);
2074
2075/*
drh6ed48bf2007-06-14 20:57:18 +00002076** CAPI3REF: Reset A Prepared Statement Object
2077**
2078** The sqlite3_reset() function is called to reset a
drh6d2069d2007-08-14 01:58:53 +00002079** [sqlite3_stmt | compiled SQL statement] object.
drh6ed48bf2007-06-14 20:57:18 +00002080** back to it's initial state, ready to be re-executed.
danielk197765904932004-05-26 06:18:37 +00002081** Any SQL statement variables that had values bound to them using
drh6ed48bf2007-06-14 20:57:18 +00002082** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values.
2083** Use [sqlite3_clear_bindings()] to reset the bindings.
danielk197765904932004-05-26 06:18:37 +00002084*/
2085int sqlite3_reset(sqlite3_stmt *pStmt);
2086
2087/*
drh6ed48bf2007-06-14 20:57:18 +00002088** CAPI3REF: Create Or Redefine SQL Functions
2089**
2090** The following two functions are used to add SQL functions or aggregates
2091** or to redefine the behavior of existing SQL functions or aggregates. The
danielk197765904932004-05-26 06:18:37 +00002092** difference only between the two is that the second parameter, the
2093** name of the (scalar) function or aggregate, is encoded in UTF-8 for
2094** sqlite3_create_function() and UTF-16 for sqlite3_create_function16().
2095**
drh6ed48bf2007-06-14 20:57:18 +00002096** The first argument is the [sqlite3 | database handle] that holds the
2097** SQL function or aggregate is to be added or redefined. If a single
2098** program uses more than one database handle internally, then SQL
2099** functions or aggregates must be added individually to each database
2100** handle with which they will be used.
danielk197765904932004-05-26 06:18:37 +00002101**
drh6ed48bf2007-06-14 20:57:18 +00002102** The second parameter is the name of the SQL function to be created
2103** or redefined.
2104** The length of the name is limited to 255 bytes, exclusive of the
2105** zero-terminator. Note that the name length limit is in bytes, not
2106** characters. Any attempt to create a function with a longer name
2107** will result in an SQLITE_ERROR error.
2108**
2109** The third parameter is the number of arguments that the SQL function or
2110** aggregate takes. If this parameter is negative, then the SQL function or
danielk197765904932004-05-26 06:18:37 +00002111** aggregate may take any number of arguments.
2112**
drh6ed48bf2007-06-14 20:57:18 +00002113** The fourth parameter, eTextRep, specifies what
2114** [SQLITE_UTF8 | text encoding] this SQL function prefers for
2115** its parameters. Any SQL function implementation should be able to work
2116** work with UTF-8, UTF-16le, or UTF-16be. But some implementations may be
2117** more efficient with one encoding than another. It is allowed to
drh6d2069d2007-08-14 01:58:53 +00002118** invoke sqlite3_create_function() or sqlite3_create_function16() multiple
drh6ed48bf2007-06-14 20:57:18 +00002119** times with the same function but with different values of eTextRep.
2120** When multiple implementations of the same function are available, SQLite
2121** will pick the one that involves the least amount of data conversion.
2122** If there is only a single implementation which does not care what
2123** text encoding is used, then the fourth argument should be
2124** [SQLITE_ANY].
2125**
2126** The fifth parameter is an arbitrary pointer. The implementation
2127** of the function can gain access to this pointer using
drh6d2069d2007-08-14 01:58:53 +00002128** [sqlite3_user_data()].
danielk1977d02eb1f2004-06-06 09:44:03 +00002129**
danielk197765904932004-05-26 06:18:37 +00002130** The seventh, eighth and ninth parameters, xFunc, xStep and xFinal, are
drh6ed48bf2007-06-14 20:57:18 +00002131** pointers to C-language functions that implement the SQL
2132** function or aggregate. A scalar SQL function requires an implementation of
danielk197765904932004-05-26 06:18:37 +00002133** the xFunc callback only, NULL pointers should be passed as the xStep
drh6ed48bf2007-06-14 20:57:18 +00002134** and xFinal parameters. An aggregate SQL function requires an implementation
2135** of xStep and xFinal and NULL should be passed for xFunc. To delete an
2136** existing SQL function or aggregate, pass NULL for all three function
2137** callback.
2138**
2139** It is permitted to register multiple implementations of the same
2140** functions with the same name but with either differing numbers of
2141** arguments or differing perferred text encodings. SQLite will use
2142** the implementation most closely matches the way in which the
2143** SQL function is used.
danielk197765904932004-05-26 06:18:37 +00002144*/
2145int sqlite3_create_function(
2146 sqlite3 *,
2147 const char *zFunctionName,
2148 int nArg,
2149 int eTextRep,
danielk197765904932004-05-26 06:18:37 +00002150 void*,
2151 void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
2152 void (*xStep)(sqlite3_context*,int,sqlite3_value**),
2153 void (*xFinal)(sqlite3_context*)
2154);
2155int sqlite3_create_function16(
2156 sqlite3*,
2157 const void *zFunctionName,
2158 int nArg,
2159 int eTextRep,
danielk197765904932004-05-26 06:18:37 +00002160 void*,
2161 void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
2162 void (*xStep)(sqlite3_context*,int,sqlite3_value**),
2163 void (*xFinal)(sqlite3_context*)
2164);
2165
2166/*
drh6ed48bf2007-06-14 20:57:18 +00002167** CAPI3REF: Text Encodings
2168**
2169** These constant define integer codes that represent the various
2170** text encodings supported by SQLite.
danielk197765904932004-05-26 06:18:37 +00002171*/
drh6ed48bf2007-06-14 20:57:18 +00002172#define SQLITE_UTF8 1
2173#define SQLITE_UTF16LE 2
2174#define SQLITE_UTF16BE 3
2175#define SQLITE_UTF16 4 /* Use native byte order */
2176#define SQLITE_ANY 5 /* sqlite3_create_function only */
2177#define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */
danielk197765904932004-05-26 06:18:37 +00002178
danielk19770ffba6b2004-05-24 09:10:10 +00002179/*
drh6ed48bf2007-06-14 20:57:18 +00002180** CAPI3REF: Obsolete Functions
2181**
2182** These functions are all now obsolete. In order to maintain
2183** backwards compatibility with older code, we continue to support
2184** these functions. However, new development projects should avoid
2185** the use of these functions. To help encourage people to avoid
2186** using these functions, we are not going to tell you want they do.
2187*/
2188int sqlite3_aggregate_count(sqlite3_context*);
2189int sqlite3_expired(sqlite3_stmt*);
2190int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
2191int sqlite3_global_recover(void);
drhe30f4422007-08-21 16:15:55 +00002192void sqlite3_thread_cleanup(void);
drh6ed48bf2007-06-14 20:57:18 +00002193
2194/*
2195** CAPI3REF: Obtaining SQL Function Parameter Values
2196**
2197** The C-language implementation of SQL functions and aggregates uses
2198** this set of interface routines to access the parameter values on
2199** the function or aggregate.
2200**
2201** The xFunc (for scalar functions) or xStep (for aggregates) parameters
2202** to [sqlite3_create_function()] and [sqlite3_create_function16()]
2203** define callbacks that implement the SQL functions and aggregates.
2204** The 4th parameter to these callbacks is an array of pointers to
2205** [sqlite3_value] objects. There is one [sqlite3_value] object for
2206** each parameter to the SQL function. These routines are used to
2207** extract values from the [sqlite3_value] objects.
2208**
2209** These routines work just like the corresponding
2210** [sqlite3_column_blob | sqlite3_column_* routines] except that
2211** these routines take a single [sqlite3_value*] pointer instead
2212** of an [sqlite3_stmt*] pointer and an integer column number.
2213**
2214** The sqlite3_value_text16() interface extracts a UTF16 string
2215** in the native byte-order of the host machine. The
2216** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces
2217** extract UTF16 strings as big-endian and little-endian respectively.
2218**
2219** The sqlite3_value_numeric_type() interface attempts to apply
2220** numeric affinity to the value. This means that an attempt is
2221** made to convert the value to an integer or floating point. If
2222** such a conversion is possible without loss of information (in order
2223** words if the value is original a string that looks like a number)
2224** then it is done. Otherwise no conversion occurs. The
2225** [SQLITE_INTEGER | datatype] after conversion is returned.
2226**
2227** Please pay particular attention to the fact that the pointer that
2228** is returned from [sqlite3_value_blob()], [sqlite3_value_text()], or
2229** [sqlite3_value_text16()] can be invalidated by a subsequent call to
drh6d2069d2007-08-14 01:58:53 +00002230** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()],
drh6ed48bf2007-06-14 20:57:18 +00002231** or [sqlite3_value_text16()].
drhe53831d2007-08-17 01:14:38 +00002232**
2233** These routines must be called from the same thread as
2234** the SQL function that supplied the sqlite3_value* parameters.
drh32bc3f62007-08-21 20:25:39 +00002235** Or, if the sqlite3_value* argument comes from the [sqlite3_column_value()]
2236** interface, then these routines should be called from the same thread
2237** that ran [sqlite3_column_value()].
danielk19770ffba6b2004-05-24 09:10:10 +00002238*/
drhf4479502004-05-27 03:12:53 +00002239const void *sqlite3_value_blob(sqlite3_value*);
2240int sqlite3_value_bytes(sqlite3_value*);
2241int sqlite3_value_bytes16(sqlite3_value*);
2242double sqlite3_value_double(sqlite3_value*);
2243int sqlite3_value_int(sqlite3_value*);
drh6d2069d2007-08-14 01:58:53 +00002244sqlite3_int64 sqlite3_value_int64(sqlite3_value*);
drhf4479502004-05-27 03:12:53 +00002245const unsigned char *sqlite3_value_text(sqlite3_value*);
2246const void *sqlite3_value_text16(sqlite3_value*);
danielk1977d8123362004-06-12 09:25:12 +00002247const void *sqlite3_value_text16le(sqlite3_value*);
2248const void *sqlite3_value_text16be(sqlite3_value*);
danielk197793d46752004-05-23 13:30:58 +00002249int sqlite3_value_type(sqlite3_value*);
drh29d72102006-02-09 22:13:41 +00002250int sqlite3_value_numeric_type(sqlite3_value*);
danielk19770ffba6b2004-05-24 09:10:10 +00002251
2252/*
drh6ed48bf2007-06-14 20:57:18 +00002253** CAPI3REF: Obtain Aggregate Function Context
2254**
2255** The implementation of aggregate SQL functions use this routine to allocate
danielk19770ae8b832004-05-25 12:05:56 +00002256** a structure for storing their state. The first time this routine
2257** is called for a particular aggregate, a new structure of size nBytes
2258** is allocated, zeroed, and returned. On subsequent calls (for the
2259** same aggregate instance) the same buffer is returned. The implementation
2260** of the aggregate can use the returned buffer to accumulate data.
2261**
drh6ed48bf2007-06-14 20:57:18 +00002262** The buffer allocated is freed automatically by SQLite whan the aggregate
2263** query concludes.
2264**
2265** The first parameter should be a copy of the
2266** [sqlite3_context | SQL function context] that is the first
2267** parameter to the callback routine that implements the aggregate
2268** function.
drhe53831d2007-08-17 01:14:38 +00002269**
2270** This routine must be called from the same thread in which
drh605264d2007-08-21 15:13:19 +00002271** the aggregate SQL function is running.
danielk19770ae8b832004-05-25 12:05:56 +00002272*/
drh4f26d6c2004-05-26 23:25:30 +00002273void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
danielk19777e18c252004-05-25 11:47:24 +00002274
2275/*
drh6ed48bf2007-06-14 20:57:18 +00002276** CAPI3REF: User Data For Functions
2277**
2278** The pUserData parameter to the [sqlite3_create_function()]
2279** and [sqlite3_create_function16()] routines
2280** used to register user functions is available to
drhc0f2a012005-07-09 02:39:40 +00002281** the implementation of the function using this call.
drhe53831d2007-08-17 01:14:38 +00002282**
2283** This routine must be called from the same thread in which
drhb21c8cd2007-08-21 19:33:56 +00002284** the SQL function is running.
danielk19777e18c252004-05-25 11:47:24 +00002285*/
2286void *sqlite3_user_data(sqlite3_context*);
2287
2288/*
drh6ed48bf2007-06-14 20:57:18 +00002289** CAPI3REF: Function Auxiliary Data
2290**
2291** The following two functions may be used by scalar SQL functions to
danielk1977682f68b2004-06-05 10:22:17 +00002292** associate meta-data with argument values. If the same value is passed to
drh6ed48bf2007-06-14 20:57:18 +00002293** multiple invocations of the same SQL function during query execution, under
danielk1977682f68b2004-06-05 10:22:17 +00002294** some circumstances the associated meta-data may be preserved. This may
2295** be used, for example, to add a regular-expression matching scalar
2296** function. The compiled version of the regular expression is stored as
2297** meta-data associated with the SQL value passed as the regular expression
drh6ed48bf2007-06-14 20:57:18 +00002298** pattern. The compiled regular expression can be reused on multiple
2299** invocations of the same function so that the original pattern string
2300** does not need to be recompiled on each invocation.
danielk1977682f68b2004-06-05 10:22:17 +00002301**
drh6ed48bf2007-06-14 20:57:18 +00002302** The sqlite3_get_auxdata() interface returns a pointer to the meta-data
2303** associated with the Nth argument value to the current SQL function
danielk1977682f68b2004-06-05 10:22:17 +00002304** call, where N is the second parameter. If no meta-data has been set for
2305** that value, then a NULL pointer is returned.
2306**
drh6ed48bf2007-06-14 20:57:18 +00002307** The sqlite3_set_auxdata() is used to associate meta-data with an SQL
2308** function argument. The third parameter is a pointer to the meta-data
danielk1977682f68b2004-06-05 10:22:17 +00002309** to be associated with the Nth user function argument value. The fourth
drh6ed48bf2007-06-14 20:57:18 +00002310** parameter specifies a destructor that will be called on the meta-
2311** data pointer to release it when it is no longer required. If the
2312** destructor is NULL, it is not invoked.
danielk1977682f68b2004-06-05 10:22:17 +00002313**
2314** In practice, meta-data is preserved between function calls for
2315** expressions that are constant at compile time. This includes literal
2316** values and SQL variables.
drhe53831d2007-08-17 01:14:38 +00002317**
drhb21c8cd2007-08-21 19:33:56 +00002318** These routines must be called from the same thread in which
2319** the SQL function is running.
danielk1977682f68b2004-06-05 10:22:17 +00002320*/
2321void *sqlite3_get_auxdata(sqlite3_context*, int);
2322void sqlite3_set_auxdata(sqlite3_context*, int, void*, void (*)(void*));
2323
drha2854222004-06-17 19:04:17 +00002324
2325/*
drh6ed48bf2007-06-14 20:57:18 +00002326** CAPI3REF: Constants Defining Special Destructor Behavior
2327**
drha2854222004-06-17 19:04:17 +00002328** These are special value for the destructor that is passed in as the
drh6ed48bf2007-06-14 20:57:18 +00002329** final argument to routines like [sqlite3_result_blob()]. If the destructor
drha2854222004-06-17 19:04:17 +00002330** argument is SQLITE_STATIC, it means that the content pointer is constant
2331** and will never change. It does not need to be destroyed. The
2332** SQLITE_TRANSIENT value means that the content will likely change in
2333** the near future and that SQLite should make its own private copy of
2334** the content before returning.
drh6c9121a2007-01-26 00:51:43 +00002335**
2336** The typedef is necessary to work around problems in certain
2337** C++ compilers. See ticket #2191.
drha2854222004-06-17 19:04:17 +00002338*/
drh6c9121a2007-01-26 00:51:43 +00002339typedef void (*sqlite3_destructor_type)(void*);
2340#define SQLITE_STATIC ((sqlite3_destructor_type)0)
2341#define SQLITE_TRANSIENT ((sqlite3_destructor_type)-1)
danielk1977d8123362004-06-12 09:25:12 +00002342
danielk1977682f68b2004-06-05 10:22:17 +00002343/*
drh6ed48bf2007-06-14 20:57:18 +00002344** CAPI3REF: Setting The Result Of An SQL Function
2345**
2346** These routines are used by the xFunc or xFinal callbacks that
2347** implement SQL functions and aggregates. See
2348** [sqlite3_create_function()] and [sqlite3_create_function16()]
2349** for additional information.
2350**
2351** These functions work very much like the
2352** [sqlite3_bind_blob | sqlite3_bind_*] family of functions used
2353** to bind values to host parameters in prepared statements.
2354** Refer to the
2355** [sqlite3_bind_blob | sqlite3_bind_* documentation] for
2356** additional information.
2357**
2358** The sqlite3_result_error() and sqlite3_result_error16() functions
2359** cause the implemented SQL function to throw an exception. The
2360** parameter to sqlite3_result_error() or sqlite3_result_error16()
2361** is the text of an error message.
2362**
2363** The sqlite3_result_toobig() cause the function implementation
2364** to throw and error indicating that a string or BLOB is to long
2365** to represent.
drhe53831d2007-08-17 01:14:38 +00002366**
2367** These routines must be called from within the same thread as
2368** the SQL function associated with the [sqlite3_context] pointer.
danielk19777e18c252004-05-25 11:47:24 +00002369*/
danielk1977d8123362004-06-12 09:25:12 +00002370void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
drh4f26d6c2004-05-26 23:25:30 +00002371void sqlite3_result_double(sqlite3_context*, double);
danielk19777e18c252004-05-25 11:47:24 +00002372void sqlite3_result_error(sqlite3_context*, const char*, int);
2373void sqlite3_result_error16(sqlite3_context*, const void*, int);
drh6ed48bf2007-06-14 20:57:18 +00002374void sqlite3_result_error_toobig(sqlite3_context*);
drh4f26d6c2004-05-26 23:25:30 +00002375void sqlite3_result_int(sqlite3_context*, int);
drh6d2069d2007-08-14 01:58:53 +00002376void sqlite3_result_int64(sqlite3_context*, sqlite3_int64);
drh4f26d6c2004-05-26 23:25:30 +00002377void sqlite3_result_null(sqlite3_context*);
danielk1977d8123362004-06-12 09:25:12 +00002378void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
2379void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
2380void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
2381void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
drh4f26d6c2004-05-26 23:25:30 +00002382void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
drhb026e052007-05-02 01:34:31 +00002383void sqlite3_result_zeroblob(sqlite3_context*, int n);
drhf9b596e2004-05-26 16:54:42 +00002384
drh52619df2004-06-11 17:48:02 +00002385/*
drh6ed48bf2007-06-14 20:57:18 +00002386** CAPI3REF: Define New Collating Sequences
2387**
2388** These functions are used to add new collation sequences to the
2389** [sqlite3*] handle specified as the first argument.
danielk19777cedc8d2004-06-10 10:50:08 +00002390**
2391** The name of the new collation sequence is specified as a UTF-8 string
drh6ed48bf2007-06-14 20:57:18 +00002392** for sqlite3_create_collation() and sqlite3_create_collation_v2()
2393** and a UTF-16 string for sqlite3_create_collation16(). In all cases
2394** the name is passed as the second function argument.
danielk19777cedc8d2004-06-10 10:50:08 +00002395**
drh6ed48bf2007-06-14 20:57:18 +00002396** The third argument must be one of the constants [SQLITE_UTF8],
2397** [SQLITE_UTF16LE] or [SQLITE_UTF16BE], indicating that the user-supplied
danielk19777cedc8d2004-06-10 10:50:08 +00002398** routine expects to be passed pointers to strings encoded using UTF-8,
2399** UTF-16 little-endian or UTF-16 big-endian respectively.
2400**
2401** A pointer to the user supplied routine must be passed as the fifth
2402** argument. If it is NULL, this is the same as deleting the collation
2403** sequence (so that SQLite cannot call it anymore). Each time the user
2404** supplied function is invoked, it is passed a copy of the void* passed as
2405** the fourth argument to sqlite3_create_collation() or
2406** sqlite3_create_collation16() as its first parameter.
2407**
2408** The remaining arguments to the user-supplied routine are two strings,
2409** each represented by a [length, data] pair and encoded in the encoding
2410** that was passed as the third argument when the collation sequence was
2411** registered. The user routine should return negative, zero or positive if
2412** the first string is less than, equal to, or greater than the second
2413** string. i.e. (STRING1 - STRING2).
drh6ed48bf2007-06-14 20:57:18 +00002414**
2415** The sqlite3_create_collation_v2() works like sqlite3_create_collation()
2416** excapt that it takes an extra argument which is a destructor for
2417** the collation. The destructor is called when the collation is
2418** destroyed and is passed a copy of the fourth parameter void* pointer
2419** of the sqlite3_create_collation_v2(). Collations are destroyed when
2420** they are overridden by later calls to the collation creation functions
2421** or when the [sqlite3*] database handle is closed using [sqlite3_close()].
2422**
2423** The sqlite3_create_collation_v2() interface is experimental and
2424** subject to change in future releases. The other collation creation
2425** functions are stable.
danielk19777cedc8d2004-06-10 10:50:08 +00002426*/
danielk19770202b292004-06-09 09:55:16 +00002427int sqlite3_create_collation(
2428 sqlite3*,
2429 const char *zName,
danielk19777cedc8d2004-06-10 10:50:08 +00002430 int eTextRep,
danielk19770202b292004-06-09 09:55:16 +00002431 void*,
2432 int(*xCompare)(void*,int,const void*,int,const void*)
2433);
drh6ed48bf2007-06-14 20:57:18 +00002434int sqlite3_create_collation_v2(
2435 sqlite3*,
2436 const char *zName,
2437 int eTextRep,
2438 void*,
2439 int(*xCompare)(void*,int,const void*,int,const void*),
2440 void(*xDestroy)(void*)
2441);
danielk19770202b292004-06-09 09:55:16 +00002442int sqlite3_create_collation16(
2443 sqlite3*,
2444 const char *zName,
danielk19777cedc8d2004-06-10 10:50:08 +00002445 int eTextRep,
danielk19770202b292004-06-09 09:55:16 +00002446 void*,
2447 int(*xCompare)(void*,int,const void*,int,const void*)
2448);
2449
danielk19777cedc8d2004-06-10 10:50:08 +00002450/*
drh6ed48bf2007-06-14 20:57:18 +00002451** CAPI3REF: Collation Needed Callbacks
danielk1977a393c032007-05-07 14:58:53 +00002452**
danielk19777cedc8d2004-06-10 10:50:08 +00002453** To avoid having to register all collation sequences before a database
2454** can be used, a single callback function may be registered with the
2455** database handle to be called whenever an undefined collation sequence is
2456** required.
2457**
2458** If the function is registered using the sqlite3_collation_needed() API,
2459** then it is passed the names of undefined collation sequences as strings
2460** encoded in UTF-8. If sqlite3_collation_needed16() is used, the names
2461** are passed as UTF-16 in machine native byte order. A call to either
2462** function replaces any existing callback.
2463**
drh6ed48bf2007-06-14 20:57:18 +00002464** When the callback is invoked, the first argument passed is a copy
danielk19777cedc8d2004-06-10 10:50:08 +00002465** of the second argument to sqlite3_collation_needed() or
2466** sqlite3_collation_needed16(). The second argument is the database
drh6ed48bf2007-06-14 20:57:18 +00002467** handle. The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE], or
2468** [SQLITE_UTF16LE], indicating the most desirable form of the collation
danielk19777cedc8d2004-06-10 10:50:08 +00002469** sequence function required. The fourth parameter is the name of the
2470** required collation sequence.
2471**
drh6ed48bf2007-06-14 20:57:18 +00002472** The callback function should register the desired collation using
2473** [sqlite3_create_collation()], [sqlite3_create_collation16()], or
2474** [sqlite3_create_collation_v2()].
danielk19777cedc8d2004-06-10 10:50:08 +00002475*/
2476int sqlite3_collation_needed(
2477 sqlite3*,
2478 void*,
2479 void(*)(void*,sqlite3*,int eTextRep,const char*)
2480);
2481int sqlite3_collation_needed16(
2482 sqlite3*,
2483 void*,
2484 void(*)(void*,sqlite3*,int eTextRep,const void*)
2485);
2486
drh2011d5f2004-07-22 02:40:37 +00002487/*
2488** Specify the key for an encrypted database. This routine should be
2489** called right after sqlite3_open().
2490**
2491** The code to implement this API is not available in the public release
2492** of SQLite.
2493*/
2494int sqlite3_key(
2495 sqlite3 *db, /* Database to be rekeyed */
2496 const void *pKey, int nKey /* The key */
2497);
2498
2499/*
2500** Change the key on an open database. If the current database is not
2501** encrypted, this routine will encrypt it. If pNew==0 or nNew==0, the
2502** database is decrypted.
2503**
2504** The code to implement this API is not available in the public release
2505** of SQLite.
2506*/
2507int sqlite3_rekey(
2508 sqlite3 *db, /* Database to be rekeyed */
2509 const void *pKey, int nKey /* The new key */
2510);
danielk19770202b292004-06-09 09:55:16 +00002511
drhab3f9fe2004-08-14 17:10:10 +00002512/*
drh6ed48bf2007-06-14 20:57:18 +00002513** CAPI3REF: Suspend Execution For A Short Time
2514**
danielk1977d84d4832007-06-20 09:09:47 +00002515** This function causes the current thread to suspend execution
drh6ed48bf2007-06-14 20:57:18 +00002516** a number of milliseconds specified in its parameter.
danielk1977600dd0b2005-01-20 01:14:23 +00002517**
2518** If the operating system does not support sleep requests with
drh6ed48bf2007-06-14 20:57:18 +00002519** millisecond time resolution, then the time will be rounded up to
2520** the nearest second. The number of milliseconds of sleep actually
danielk1977600dd0b2005-01-20 01:14:23 +00002521** requested from the operating system is returned.
danielk1977600dd0b2005-01-20 01:14:23 +00002522*/
2523int sqlite3_sleep(int);
2524
2525/*
drh6ed48bf2007-06-14 20:57:18 +00002526** CAPI3REF: Name Of The Folder Holding Temporary Files
drhd89bd002005-01-22 03:03:54 +00002527**
drh6ed48bf2007-06-14 20:57:18 +00002528** If this global variable is made to point to a string which is
2529** the name of a folder (a.ka. directory), then all temporary files
drhab3f9fe2004-08-14 17:10:10 +00002530** created by SQLite will be placed in that directory. If this variable
2531** is NULL pointer, then SQLite does a search for an appropriate temporary
2532** file directory.
2533**
drh6ed48bf2007-06-14 20:57:18 +00002534** Once [sqlite3_open()] has been called, changing this variable will
2535** invalidate the current temporary database, if any. Generally speaking,
2536** it is not safe to invoke this routine after [sqlite3_open()] has
2537** been called.
drhab3f9fe2004-08-14 17:10:10 +00002538*/
drh73be5012007-08-08 12:11:21 +00002539SQLITE_EXTERN char *sqlite3_temp_directory;
drhab3f9fe2004-08-14 17:10:10 +00002540
danielk19776b456a22005-03-21 04:04:02 +00002541/*
drh6ed48bf2007-06-14 20:57:18 +00002542** CAPI3REF: Test To See If The Databse Is In Auto-Commit Mode
danielk19776b456a22005-03-21 04:04:02 +00002543**
drh3e1d8e62005-05-26 16:23:34 +00002544** Test to see whether or not the database connection is in autocommit
2545** mode. Return TRUE if it is and FALSE if not. Autocommit mode is on
2546** by default. Autocommit is disabled by a BEGIN statement and reenabled
2547** by the next COMMIT or ROLLBACK.
drhe30f4422007-08-21 16:15:55 +00002548**
2549** If another thread changes the autocommit status of the database
2550** connection while this routine is running, then the return value
2551** is undefined.
drh3e1d8e62005-05-26 16:23:34 +00002552*/
2553int sqlite3_get_autocommit(sqlite3*);
2554
drh51942bc2005-06-12 22:01:42 +00002555/*
drh6ed48bf2007-06-14 20:57:18 +00002556** CAPI3REF: Find The Database Handle Associated With A Prepared Statement
2557**
2558** Return the [sqlite3*] database handle to which a
2559** [sqlite3_stmt | prepared statement] belongs.
2560** This is the same database handle that was
2561** the first argument to the [sqlite3_prepare_v2()] or its variants
2562** that was used to create the statement in the first place.
drh51942bc2005-06-12 22:01:42 +00002563*/
2564sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
drh3e1d8e62005-05-26 16:23:34 +00002565
drh6ed48bf2007-06-14 20:57:18 +00002566
drhb37df7b2005-10-13 02:09:49 +00002567/*
drh6ed48bf2007-06-14 20:57:18 +00002568** CAPI3REF: Commit And Rollback Notification Callbacks
2569**
2570** These routines
2571** register callback functions to be invoked whenever a transaction
2572** is committed or rolled back. The pArg argument is passed through
2573** to the callback. If the callback on a commit hook function
2574** returns non-zero, then the commit is converted into a rollback.
2575**
2576** If another function was previously registered, its pArg value is returned.
2577** Otherwise NULL is returned.
2578**
2579** Registering a NULL function disables the callback.
2580**
2581** For the purposes of this API, a transaction is said to have been
2582** rolled back if an explicit "ROLLBACK" statement is executed, or
2583** an error or constraint causes an implicit rollback to occur. The
2584** callback is not invoked if a transaction is automatically rolled
2585** back because the database connection is closed.
2586**
2587** These are experimental interfaces and are subject to change.
2588*/
2589void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
2590void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
2591
2592/*
2593** CAPI3REF: Data Change Notification Callbacks
2594**
danielk197794eb6a12005-12-15 15:22:08 +00002595** Register a callback function with the database connection identified by the
2596** first argument to be invoked whenever a row is updated, inserted or deleted.
2597** Any callback set by a previous call to this function for the same
2598** database connection is overridden.
2599**
2600** The second argument is a pointer to the function to invoke when a
2601** row is updated, inserted or deleted. The first argument to the callback is
drh6ed48bf2007-06-14 20:57:18 +00002602** a copy of the third argument to sqlite3_update_hook(). The second callback
danielk197794eb6a12005-12-15 15:22:08 +00002603** argument is one of SQLITE_INSERT, SQLITE_DELETE or SQLITE_UPDATE, depending
2604** on the operation that caused the callback to be invoked. The third and
2605** fourth arguments to the callback contain pointers to the database and
2606** table name containing the affected row. The final callback parameter is
2607** the rowid of the row. In the case of an update, this is the rowid after
2608** the update takes place.
2609**
2610** The update hook is not invoked when internal system tables are
2611** modified (i.e. sqlite_master and sqlite_sequence).
danielk197771fd80b2005-12-16 06:54:01 +00002612**
2613** If another function was previously registered, its pArg value is returned.
2614** Otherwise NULL is returned.
danielk197794eb6a12005-12-15 15:22:08 +00002615*/
danielk197771fd80b2005-12-16 06:54:01 +00002616void *sqlite3_update_hook(
danielk197794eb6a12005-12-15 15:22:08 +00002617 sqlite3*,
drh6d2069d2007-08-14 01:58:53 +00002618 void(*)(void *,int ,char const *,char const *,sqlite3_int64),
danielk197794eb6a12005-12-15 15:22:08 +00002619 void*
2620);
danielk197713a68c32005-12-15 10:11:30 +00002621
danielk1977f3f06bb2005-12-16 15:24:28 +00002622/*
drh6ed48bf2007-06-14 20:57:18 +00002623** CAPI3REF: Enable Or Disable Shared Pager Cache
danielk1977f3f06bb2005-12-16 15:24:28 +00002624**
drh6ed48bf2007-06-14 20:57:18 +00002625** This routine enables or disables the sharing of the database cache
2626** and schema data structures between connections to the same database.
2627** Sharing is enabled if the argument is true and disabled if the argument
2628** is false.
danielk1977f3f06bb2005-12-16 15:24:28 +00002629**
drhe30f4422007-08-21 16:15:55 +00002630** Beginning in SQLite version 3.5.0, cache sharing is enabled and disabled
2631** for an entire process. In prior versions of SQLite, sharing was
2632** enabled or disabled for each thread separately.
drh6ed48bf2007-06-14 20:57:18 +00002633**
drhe30f4422007-08-21 16:15:55 +00002634** The cache sharing mode set by this interface effects all subsequent
2635** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()].
2636** Existing database connections continue use the sharing mode that was
2637** in effect at the time they were opened.
drh6ed48bf2007-06-14 20:57:18 +00002638**
2639** Virtual tables cannot be used with a shared cache. When shared
2640** cache is enabled, the sqlite3_create_module() API used to register
2641** virtual tables will always return an error.
2642**
2643** This routine returns [SQLITE_OK] if shared cache was
2644** enabled or disabled successfully. An [SQLITE_ERROR | error code]
2645** is returned otherwise.
2646**
2647** Shared cache is disabled by default for backward compatibility.
danielk1977aef0bf62005-12-30 16:28:01 +00002648*/
2649int sqlite3_enable_shared_cache(int);
2650
2651/*
drh6ed48bf2007-06-14 20:57:18 +00002652** CAPI3REF: Attempt To Free Heap Memory
2653**
danielk197752622822006-01-09 09:59:49 +00002654** Attempt to free N bytes of heap memory by deallocating non-essential
2655** memory allocations held by the database library (example: memory
2656** used to cache database pages to improve performance).
2657**
drh6f7adc82006-01-11 21:41:20 +00002658** This function is not a part of standard builds. It is only created
2659** if SQLite is compiled with the SQLITE_ENABLE_MEMORY_MANAGEMENT macro.
danielk197752622822006-01-09 09:59:49 +00002660*/
2661int sqlite3_release_memory(int);
2662
2663/*
drh6ed48bf2007-06-14 20:57:18 +00002664** CAPI3REF: Impose A Limit On Heap Size
2665**
drhe30f4422007-08-21 16:15:55 +00002666** Place a "soft" limit on the amount of heap memory that may be allocated
2667** by SQLite. If an internal allocation is requested
2668** that would exceed the specified limit, [sqlite3_release_memory()] is
2669** invoked one or more times to free up some space before the allocation
2670** is made.
danielk197752622822006-01-09 09:59:49 +00002671**
drhe30f4422007-08-21 16:15:55 +00002672** The limit is called "soft", because if [sqlite3_release_memory()] cannot
2673** free sufficient memory to prevent the limit from being exceeded,
2674** the memory is allocated anyway and the current operation proceeds.
drh6ed48bf2007-06-14 20:57:18 +00002675**
2676** A negative or zero value for N means that there is no soft heap limit and
drhe30f4422007-08-21 16:15:55 +00002677** [sqlite3_release_memory()] will only be called when memory is exhausted.
drh6ed48bf2007-06-14 20:57:18 +00002678** The default value for the soft heap limit is zero.
2679**
2680** SQLite makes a best effort to honor the soft heap limit. But if it
2681** is unable to reduce memory usage below the soft limit, execution will
2682** continue without error or notification. This is why the limit is
2683** called a "soft" limit. It is advisory only.
2684**
drhb21c8cd2007-08-21 19:33:56 +00002685** The soft heap limit is implemented using the [sqlite3_memory_alarm()]
2686** interface. Only a single memory alarm is available in the default
2687** implementation. This means that if the application also uses the
2688** memory alarm interface it will interfere with the operation of the
2689** soft heap limit and undefined behavior will result.
2690**
drhe30f4422007-08-21 16:15:55 +00002691** Prior to SQLite version 3.5.0, this routine only constrained the memory
2692** allocated by a single thread - the same thread in which this routine
2693** runs. Beginning with SQLite version 3.5.0, the soft heap limit is
2694** applied cumulatively to all threads.
danielk197752622822006-01-09 09:59:49 +00002695*/
drhd2d4a6b2006-01-10 15:18:27 +00002696void sqlite3_soft_heap_limit(int);
danielk197752622822006-01-09 09:59:49 +00002697
2698/*
drh6ed48bf2007-06-14 20:57:18 +00002699** CAPI3REF: Extract Metadata About A Column Of A Table
2700**
2701** This routine
2702** returns meta-data about a specific column of a specific database
danielk1977deb802c2006-02-09 13:43:28 +00002703** table accessible using the connection handle passed as the first function
2704** argument.
2705**
2706** The column is identified by the second, third and fourth parameters to
2707** this function. The second parameter is either the name of the database
2708** (i.e. "main", "temp" or an attached database) containing the specified
2709** table or NULL. If it is NULL, then all attached databases are searched
2710** for the table using the same algorithm as the database engine uses to
2711** resolve unqualified table references.
2712**
2713** The third and fourth parameters to this function are the table and column
2714** name of the desired column, respectively. Neither of these parameters
2715** may be NULL.
2716**
2717** Meta information is returned by writing to the memory locations passed as
2718** the 5th and subsequent parameters to this function. Any of these
2719** arguments may be NULL, in which case the corresponding element of meta
2720** information is ommitted.
2721**
drh6ed48bf2007-06-14 20:57:18 +00002722** <pre>
danielk1977deb802c2006-02-09 13:43:28 +00002723** Parameter Output Type Description
2724** -----------------------------------
2725**
2726** 5th const char* Data type
2727** 6th const char* Name of the default collation sequence
2728** 7th int True if the column has a NOT NULL constraint
2729** 8th int True if the column is part of the PRIMARY KEY
2730** 9th int True if the column is AUTOINCREMENT
drh6ed48bf2007-06-14 20:57:18 +00002731** </pre>
danielk1977deb802c2006-02-09 13:43:28 +00002732**
2733**
2734** The memory pointed to by the character pointers returned for the
2735** declaration type and collation sequence is valid only until the next
2736** call to any sqlite API function.
2737**
2738** If the specified table is actually a view, then an error is returned.
2739**
2740** If the specified column is "rowid", "oid" or "_rowid_" and an
2741** INTEGER PRIMARY KEY column has been explicitly declared, then the output
2742** parameters are set for the explicitly declared column. If there is no
2743** explicitly declared IPK column, then the output parameters are set as
2744** follows:
2745**
drh6ed48bf2007-06-14 20:57:18 +00002746** <pre>
danielk1977deb802c2006-02-09 13:43:28 +00002747** data type: "INTEGER"
2748** collation sequence: "BINARY"
2749** not null: 0
2750** primary key: 1
2751** auto increment: 0
drh6ed48bf2007-06-14 20:57:18 +00002752** </pre>
danielk1977deb802c2006-02-09 13:43:28 +00002753**
2754** This function may load one or more schemas from database files. If an
2755** error occurs during this process, or if the requested table or column
2756** cannot be found, an SQLITE error code is returned and an error message
2757** left in the database handle (to be retrieved using sqlite3_errmsg()).
danielk19774b1ae992006-02-10 03:06:10 +00002758**
2759** This API is only available if the library was compiled with the
2760** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined.
danielk1977deb802c2006-02-09 13:43:28 +00002761*/
2762int sqlite3_table_column_metadata(
2763 sqlite3 *db, /* Connection handle */
2764 const char *zDbName, /* Database name or NULL */
2765 const char *zTableName, /* Table name */
2766 const char *zColumnName, /* Column name */
2767 char const **pzDataType, /* OUTPUT: Declared data type */
2768 char const **pzCollSeq, /* OUTPUT: Collation sequence name */
2769 int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */
2770 int *pPrimaryKey, /* OUTPUT: True if column part of PK */
2771 int *pAutoinc /* OUTPUT: True if colums is auto-increment */
2772);
2773
2774/*
drh6ed48bf2007-06-14 20:57:18 +00002775** CAPI3REF: Load An Extension
drh1e397f82006-06-08 15:28:43 +00002776**
2777** Attempt to load an SQLite extension library contained in the file
2778** zFile. The entry point is zProc. zProc may be 0 in which case the
drhc2e87a32006-06-27 15:16:14 +00002779** name of the entry point defaults to "sqlite3_extension_init".
drh1e397f82006-06-08 15:28:43 +00002780**
drh6ed48bf2007-06-14 20:57:18 +00002781** Return [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong.
drh1e397f82006-06-08 15:28:43 +00002782**
2783** If an error occurs and pzErrMsg is not 0, then fill *pzErrMsg with
2784** error message text. The calling function should free this memory
drh6ed48bf2007-06-14 20:57:18 +00002785** by calling [sqlite3_free()].
drh1e397f82006-06-08 15:28:43 +00002786**
drh6ed48bf2007-06-14 20:57:18 +00002787** Extension loading must be enabled using [sqlite3_enable_load_extension()]
drhc2e87a32006-06-27 15:16:14 +00002788** prior to calling this API or an error will be returned.
drh1e397f82006-06-08 15:28:43 +00002789*/
2790int sqlite3_load_extension(
2791 sqlite3 *db, /* Load the extension into this database connection */
2792 const char *zFile, /* Name of the shared library containing extension */
2793 const char *zProc, /* Entry point. Derived from zFile if 0 */
2794 char **pzErrMsg /* Put error message here if not 0 */
2795);
2796
2797/*
drh6ed48bf2007-06-14 20:57:18 +00002798** CAPI3REF: Enable Or Disable Extension Loading
2799**
drhc2e87a32006-06-27 15:16:14 +00002800** So as not to open security holes in older applications that are
drh6ed48bf2007-06-14 20:57:18 +00002801** unprepared to deal with extension loading, and as a means of disabling
2802** extension loading while evaluating user-entered SQL, the following
2803** API is provided to turn the [sqlite3_load_extension()] mechanism on and
drhc2e87a32006-06-27 15:16:14 +00002804** off. It is off by default. See ticket #1863.
2805**
2806** Call this routine with onoff==1 to turn extension loading on
2807** and call it with onoff==0 to turn it back off again.
2808*/
2809int sqlite3_enable_load_extension(sqlite3 *db, int onoff);
2810
2811/*
drh6ed48bf2007-06-14 20:57:18 +00002812** CAPI3REF: Make Arrangements To Automatically Load An Extension
drh9eff6162006-06-12 21:59:13 +00002813**
drh1409be62006-08-23 20:07:20 +00002814** Register an extension entry point that is automatically invoked
drh6ed48bf2007-06-14 20:57:18 +00002815** whenever a new database connection is opened using
drh605264d2007-08-21 15:13:19 +00002816** [sqlite3_open()], [sqlite3_open16()], or [sqlite3_open_v2()].
drh1409be62006-08-23 20:07:20 +00002817**
2818** This API can be invoked at program startup in order to register
2819** one or more statically linked extensions that will be available
2820** to all new database connections.
2821**
2822** Duplicate extensions are detected so calling this routine multiple
2823** times with the same extension is harmless.
2824**
2825** This routine stores a pointer to the extension in an array
2826** that is obtained from malloc(). If you run a memory leak
2827** checker on your program and it reports a leak because of this
drh6ed48bf2007-06-14 20:57:18 +00002828** array, then invoke [sqlite3_automatic_extension_reset()] prior
drh1409be62006-08-23 20:07:20 +00002829** to shutdown to free the memory.
2830**
2831** Automatic extensions apply across all threads.
drh6ed48bf2007-06-14 20:57:18 +00002832**
2833** This interface is experimental and is subject to change or
2834** removal in future releases of SQLite.
drh1409be62006-08-23 20:07:20 +00002835*/
2836int sqlite3_auto_extension(void *xEntryPoint);
2837
2838
2839/*
drh6ed48bf2007-06-14 20:57:18 +00002840** CAPI3REF: Reset Automatic Extension Loading
drh1409be62006-08-23 20:07:20 +00002841**
2842** Disable all previously registered automatic extensions. This
drh6ed48bf2007-06-14 20:57:18 +00002843** routine undoes the effect of all prior [sqlite3_automatic_extension()]
drh1409be62006-08-23 20:07:20 +00002844** calls.
2845**
2846** This call disabled automatic extensions in all threads.
drh6ed48bf2007-06-14 20:57:18 +00002847**
2848** This interface is experimental and is subject to change or
2849** removal in future releases of SQLite.
drh1409be62006-08-23 20:07:20 +00002850*/
2851void sqlite3_reset_auto_extension(void);
2852
2853
2854/*
2855****** EXPERIMENTAL - subject to change without notice **************
2856**
drh9eff6162006-06-12 21:59:13 +00002857** The interface to the virtual-table mechanism is currently considered
2858** to be experimental. The interface might change in incompatible ways.
2859** If this is a problem for you, do not use the interface at this time.
2860**
2861** When the virtual-table mechanism stablizes, we will declare the
2862** interface fixed, support it indefinitely, and remove this comment.
2863*/
2864
2865/*
2866** Structures used by the virtual table interface
drhe09daa92006-06-10 13:29:31 +00002867*/
2868typedef struct sqlite3_vtab sqlite3_vtab;
2869typedef struct sqlite3_index_info sqlite3_index_info;
2870typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor;
2871typedef struct sqlite3_module sqlite3_module;
drh9eff6162006-06-12 21:59:13 +00002872
2873/*
2874** A module is a class of virtual tables. Each module is defined
2875** by an instance of the following structure. This structure consists
2876** mostly of methods for the module.
2877*/
drhe09daa92006-06-10 13:29:31 +00002878struct sqlite3_module {
2879 int iVersion;
danielk19779da9d472006-06-14 06:58:15 +00002880 int (*xCreate)(sqlite3*, void *pAux,
drhe4102962006-09-11 00:34:22 +00002881 int argc, const char *const*argv,
drh4ca8aac2006-09-10 17:31:58 +00002882 sqlite3_vtab **ppVTab, char**);
danielk19779da9d472006-06-14 06:58:15 +00002883 int (*xConnect)(sqlite3*, void *pAux,
drhe4102962006-09-11 00:34:22 +00002884 int argc, const char *const*argv,
drh4ca8aac2006-09-10 17:31:58 +00002885 sqlite3_vtab **ppVTab, char**);
drhe09daa92006-06-10 13:29:31 +00002886 int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*);
2887 int (*xDisconnect)(sqlite3_vtab *pVTab);
2888 int (*xDestroy)(sqlite3_vtab *pVTab);
2889 int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor);
2890 int (*xClose)(sqlite3_vtab_cursor*);
drh4be8b512006-06-13 23:51:34 +00002891 int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr,
drhe09daa92006-06-10 13:29:31 +00002892 int argc, sqlite3_value **argv);
2893 int (*xNext)(sqlite3_vtab_cursor*);
danielk1977a298e902006-06-22 09:53:48 +00002894 int (*xEof)(sqlite3_vtab_cursor*);
drhe09daa92006-06-10 13:29:31 +00002895 int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int);
drh6d2069d2007-08-14 01:58:53 +00002896 int (*xRowid)(sqlite3_vtab_cursor*, sqlite3_int64 *pRowid);
2897 int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite3_int64 *);
drhe09daa92006-06-10 13:29:31 +00002898 int (*xBegin)(sqlite3_vtab *pVTab);
2899 int (*xSync)(sqlite3_vtab *pVTab);
2900 int (*xCommit)(sqlite3_vtab *pVTab);
2901 int (*xRollback)(sqlite3_vtab *pVTab);
drhb7f6f682006-07-08 17:06:43 +00002902 int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName,
drhe94b0c32006-07-08 18:09:15 +00002903 void (**pxFunc)(sqlite3_context*,int,sqlite3_value**),
2904 void **ppArg);
danielk1977182c4ba2007-06-27 15:53:34 +00002905
2906 int (*xRename)(sqlite3_vtab *pVtab, const char *zNew);
drhe09daa92006-06-10 13:29:31 +00002907};
drh9eff6162006-06-12 21:59:13 +00002908
2909/*
2910** The sqlite3_index_info structure and its substructures is used to
2911** pass information into and receive the reply from the xBestIndex
2912** method of an sqlite3_module. The fields under **Inputs** are the
2913** inputs to xBestIndex and are read-only. xBestIndex inserts its
2914** results into the **Outputs** fields.
2915**
2916** The aConstraint[] array records WHERE clause constraints of the
2917** form:
2918**
2919** column OP expr
2920**
2921** Where OP is =, <, <=, >, or >=. The particular operator is stored
2922** in aConstraint[].op. The index of the column is stored in
2923** aConstraint[].iColumn. aConstraint[].usable is TRUE if the
2924** expr on the right-hand side can be evaluated (and thus the constraint
2925** is usable) and false if it cannot.
2926**
2927** The optimizer automatically inverts terms of the form "expr OP column"
2928** and makes other simplificatinos to the WHERE clause in an attempt to
2929** get as many WHERE clause terms into the form shown above as possible.
2930** The aConstraint[] array only reports WHERE clause terms in the correct
2931** form that refer to the particular virtual table being queried.
2932**
2933** Information about the ORDER BY clause is stored in aOrderBy[].
2934** Each term of aOrderBy records a column of the ORDER BY clause.
2935**
2936** The xBestIndex method must fill aConstraintUsage[] with information
danielk19775fac9f82006-06-13 14:16:58 +00002937** about what parameters to pass to xFilter. If argvIndex>0 then
drh9eff6162006-06-12 21:59:13 +00002938** the right-hand side of the corresponding aConstraint[] is evaluated
2939** and becomes the argvIndex-th entry in argv. If aConstraintUsage[].omit
2940** is true, then the constraint is assumed to be fully handled by the
2941** virtual table and is not checked again by SQLite.
2942**
drh4be8b512006-06-13 23:51:34 +00002943** The idxNum and idxPtr values are recorded and passed into xFilter.
2944** sqlite3_free() is used to free idxPtr if needToFreeIdxPtr is true.
drh9eff6162006-06-12 21:59:13 +00002945**
2946** The orderByConsumed means that output from xFilter will occur in
2947** the correct order to satisfy the ORDER BY clause so that no separate
2948** sorting step is required.
2949**
2950** The estimatedCost value is an estimate of the cost of doing the
2951** particular lookup. A full scan of a table with N entries should have
2952** a cost of N. A binary search of a table of N entries should have a
2953** cost of approximately log(N).
2954*/
drhe09daa92006-06-10 13:29:31 +00002955struct sqlite3_index_info {
2956 /* Inputs */
drh9eff6162006-06-12 21:59:13 +00002957 const int nConstraint; /* Number of entries in aConstraint */
2958 const struct sqlite3_index_constraint {
2959 int iColumn; /* Column on left-hand side of constraint */
2960 unsigned char op; /* Constraint operator */
2961 unsigned char usable; /* True if this constraint is usable */
2962 int iTermOffset; /* Used internally - xBestIndex should ignore */
2963 } *const aConstraint; /* Table of WHERE clause constraints */
2964 const int nOrderBy; /* Number of terms in the ORDER BY clause */
2965 const struct sqlite3_index_orderby {
2966 int iColumn; /* Column number */
2967 unsigned char desc; /* True for DESC. False for ASC. */
2968 } *const aOrderBy; /* The ORDER BY clause */
drhe09daa92006-06-10 13:29:31 +00002969
2970 /* Outputs */
drh9eff6162006-06-12 21:59:13 +00002971 struct sqlite3_index_constraint_usage {
2972 int argvIndex; /* if >0, constraint is part of argv to xFilter */
2973 unsigned char omit; /* Do not code a test for this constraint */
2974 } *const aConstraintUsage;
drh4be8b512006-06-13 23:51:34 +00002975 int idxNum; /* Number used to identify the index */
2976 char *idxStr; /* String, possibly obtained from sqlite3_malloc */
2977 int needToFreeIdxStr; /* Free idxStr using sqlite3_free() if true */
drh9eff6162006-06-12 21:59:13 +00002978 int orderByConsumed; /* True if output is already ordered */
2979 double estimatedCost; /* Estimated cost of using this index */
drhe09daa92006-06-10 13:29:31 +00002980};
drh9eff6162006-06-12 21:59:13 +00002981#define SQLITE_INDEX_CONSTRAINT_EQ 2
2982#define SQLITE_INDEX_CONSTRAINT_GT 4
2983#define SQLITE_INDEX_CONSTRAINT_LE 8
2984#define SQLITE_INDEX_CONSTRAINT_LT 16
2985#define SQLITE_INDEX_CONSTRAINT_GE 32
2986#define SQLITE_INDEX_CONSTRAINT_MATCH 64
2987
2988/*
2989** This routine is used to register a new module name with an SQLite
2990** connection. Module names must be registered before creating new
2991** virtual tables on the module, or before using preexisting virtual
2992** tables of the module.
2993*/
drhb9bb7c12006-06-11 23:41:55 +00002994int sqlite3_create_module(
drh9eff6162006-06-12 21:59:13 +00002995 sqlite3 *db, /* SQLite connection to register module with */
2996 const char *zName, /* Name of the module */
danielk1977d1ab1ba2006-06-15 04:28:13 +00002997 const sqlite3_module *, /* Methods for the module */
2998 void * /* Client data for xCreate/xConnect */
drhb9bb7c12006-06-11 23:41:55 +00002999);
drhe09daa92006-06-10 13:29:31 +00003000
drh9eff6162006-06-12 21:59:13 +00003001/*
danielk1977832a58a2007-06-22 15:21:15 +00003002** This routine is identical to the sqlite3_create_module() method above,
3003** except that it allows a destructor function to be specified. It is
3004** even more experimental than the rest of the virtual tables API.
3005*/
3006int sqlite3_create_module_v2(
3007 sqlite3 *db, /* SQLite connection to register module with */
3008 const char *zName, /* Name of the module */
3009 const sqlite3_module *, /* Methods for the module */
3010 void *, /* Client data for xCreate/xConnect */
3011 void(*xDestroy)(void*) /* Module destructor function */
3012);
3013
3014/*
drh9eff6162006-06-12 21:59:13 +00003015** Every module implementation uses a subclass of the following structure
3016** to describe a particular instance of the module. Each subclass will
3017** be taylored to the specific needs of the module implementation. The
3018** purpose of this superclass is to define certain fields that are common
3019** to all module implementations.
drhfe1368e2006-09-10 17:08:29 +00003020**
3021** Virtual tables methods can set an error message by assigning a
3022** string obtained from sqlite3_mprintf() to zErrMsg. The method should
3023** take care that any prior string is freed by a call to sqlite3_free()
3024** prior to assigning a new string to zErrMsg. After the error message
3025** is delivered up to the client application, the string will be automatically
3026** freed by sqlite3_free() and the zErrMsg field will be zeroed. Note
3027** that sqlite3_mprintf() and sqlite3_free() are used on the zErrMsg field
3028** since virtual tables are commonly implemented in loadable extensions which
3029** do not have access to sqlite3MPrintf() or sqlite3Free().
drh9eff6162006-06-12 21:59:13 +00003030*/
3031struct sqlite3_vtab {
drha967e882006-06-13 01:04:52 +00003032 const sqlite3_module *pModule; /* The module for this virtual table */
danielk1977be718892006-06-23 08:05:19 +00003033 int nRef; /* Used internally */
drh4ca8aac2006-09-10 17:31:58 +00003034 char *zErrMsg; /* Error message from sqlite3_mprintf() */
drh9eff6162006-06-12 21:59:13 +00003035 /* Virtual table implementations will typically add additional fields */
3036};
3037
3038/* Every module implementation uses a subclass of the following structure
3039** to describe cursors that point into the virtual table and are used
3040** to loop through the virtual table. Cursors are created using the
3041** xOpen method of the module. Each module implementation will define
3042** the content of a cursor structure to suit its own needs.
3043**
3044** This superclass exists in order to define fields of the cursor that
3045** are common to all implementations.
3046*/
3047struct sqlite3_vtab_cursor {
3048 sqlite3_vtab *pVtab; /* Virtual table of this cursor */
3049 /* Virtual table implementations will typically add additional fields */
3050};
3051
3052/*
3053** The xCreate and xConnect methods of a module use the following API
3054** to declare the format (the names and datatypes of the columns) of
3055** the virtual tables they implement.
3056*/
danielk19777e6ebfb2006-06-12 11:24:37 +00003057int sqlite3_declare_vtab(sqlite3*, const char *zCreateTable);
drhe09daa92006-06-10 13:29:31 +00003058
3059/*
drhb7481e72006-09-16 21:45:14 +00003060** Virtual tables can provide alternative implementations of functions
3061** using the xFindFunction method. But global versions of those functions
3062** must exist in order to be overloaded.
3063**
3064** This API makes sure a global version of a function with a particular
3065** name and number of parameters exists. If no such function exists
3066** before this API is called, a new function is created. The implementation
3067** of the new function always causes an exception to be thrown. So
3068** the new function is not good for anything by itself. Its only
3069** purpose is to be a place-holder function that can be overloaded
3070** by virtual tables.
3071**
3072** This API should be considered part of the virtual table interface,
3073** which is experimental and subject to change.
3074*/
3075int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg);
3076
3077/*
drh9eff6162006-06-12 21:59:13 +00003078** The interface to the virtual-table mechanism defined above (back up
3079** to a comment remarkably similar to this one) is currently considered
3080** to be experimental. The interface might change in incompatible ways.
3081** If this is a problem for you, do not use the interface at this time.
3082**
3083** When the virtual-table mechanism stablizes, we will declare the
3084** interface fixed, support it indefinitely, and remove this comment.
3085**
3086****** EXPERIMENTAL - subject to change without notice **************
3087*/
3088
danielk19778cbadb02007-05-03 16:31:26 +00003089/*
drh6ed48bf2007-06-14 20:57:18 +00003090** CAPI3REF: A Handle To An Open BLOB
3091**
danielk19778cbadb02007-05-03 16:31:26 +00003092** An instance of the following opaque structure is used to
drh6ed48bf2007-06-14 20:57:18 +00003093** represent an blob-handle. A blob-handle is created by
3094** [sqlite3_blob_open()] and destroyed by [sqlite3_blob_close()].
3095** The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces
3096** can be used to read or write small subsections of the blob.
3097** The [sqltie3_blob_size()] interface returns the size of the
3098** blob in bytes.
danielk19778cbadb02007-05-03 16:31:26 +00003099*/
danielk1977b4e9af92007-05-01 17:49:49 +00003100typedef struct sqlite3_blob sqlite3_blob;
3101
danielk19778cbadb02007-05-03 16:31:26 +00003102/*
drh6ed48bf2007-06-14 20:57:18 +00003103** CAPI3REF: Open A BLOB For Incremental I/O
3104**
danielk19778cbadb02007-05-03 16:31:26 +00003105** Open a handle to the blob located in row iRow,, column zColumn,
3106** table zTable in database zDb. i.e. the same blob that would
3107** be selected by:
3108**
drh6ed48bf2007-06-14 20:57:18 +00003109** <pre>
3110** SELECT zColumn FROM zDb.zTable WHERE rowid = iRow;
3111** </pre>
danielk19778cbadb02007-05-03 16:31:26 +00003112**
3113** If the flags parameter is non-zero, the blob is opened for
3114** read and write access. If it is zero, the blob is opened for read
3115** access.
3116**
drh6ed48bf2007-06-14 20:57:18 +00003117** On success, [SQLITE_OK] is returned and the new
3118** [sqlite3_blob | blob handle] is written to *ppBlob.
3119** Otherwise an error code is returned and
danielk19778cbadb02007-05-03 16:31:26 +00003120** any value written to *ppBlob should not be used by the caller.
3121** This function sets the database-handle error code and message
drh6ed48bf2007-06-14 20:57:18 +00003122** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()].
danielk19778cbadb02007-05-03 16:31:26 +00003123*/
danielk1977b4e9af92007-05-01 17:49:49 +00003124int sqlite3_blob_open(
3125 sqlite3*,
3126 const char *zDb,
3127 const char *zTable,
3128 const char *zColumn,
drh6d2069d2007-08-14 01:58:53 +00003129 sqlite3_int64 iRow,
danielk1977b4e9af92007-05-01 17:49:49 +00003130 int flags,
3131 sqlite3_blob **ppBlob
3132);
3133
danielk19778cbadb02007-05-03 16:31:26 +00003134/*
drh6ed48bf2007-06-14 20:57:18 +00003135** CAPI3REF: Close A BLOB Handle
3136**
3137** Close an open [sqlite3_blob | blob handle].
danielk19778cbadb02007-05-03 16:31:26 +00003138*/
danielk1977b4e9af92007-05-01 17:49:49 +00003139int sqlite3_blob_close(sqlite3_blob *);
3140
danielk19778cbadb02007-05-03 16:31:26 +00003141/*
drh6ed48bf2007-06-14 20:57:18 +00003142** CAPI3REF: Return The Size Of An Open BLOB
3143**
danielk19778cbadb02007-05-03 16:31:26 +00003144** Return the size in bytes of the blob accessible via the open
drh6ed48bf2007-06-14 20:57:18 +00003145** [sqlite3_blob | blob-handle] passed as an argument.
danielk19778cbadb02007-05-03 16:31:26 +00003146*/
danielk1977b4e9af92007-05-01 17:49:49 +00003147int sqlite3_blob_bytes(sqlite3_blob *);
3148
drh9eff6162006-06-12 21:59:13 +00003149/*
drh6ed48bf2007-06-14 20:57:18 +00003150** CAPI3REF: Read Data From A BLOB Incrementally
3151**
3152** This function is used to read data from an open
3153** [sqlite3_blob | blob-handle] into a caller supplied buffer.
3154** n bytes of data are copied into buffer
danielk19778cbadb02007-05-03 16:31:26 +00003155** z from the open blob, starting at offset iOffset.
3156**
drh6ed48bf2007-06-14 20:57:18 +00003157** On success, SQLITE_OK is returned. Otherwise, an
3158** [SQLITE_ERROR | SQLite error code] or an
3159** [SQLITE_IOERR_READ | extended error code] is returned.
danielk19778cbadb02007-05-03 16:31:26 +00003160*/
3161int sqlite3_blob_read(sqlite3_blob *, void *z, int n, int iOffset);
3162
3163/*
drh6ed48bf2007-06-14 20:57:18 +00003164** CAPI3REF: Write Data Into A BLOB Incrementally
3165**
3166** This function is used to write data into an open
3167** [sqlite3_blob | blob-handle] from a user supplied buffer.
3168** n bytes of data are copied from the buffer
danielk19778cbadb02007-05-03 16:31:26 +00003169** pointed to by z into the open blob, starting at offset iOffset.
3170**
drh6ed48bf2007-06-14 20:57:18 +00003171** If the [sqlite3_blob | blob-handle] passed as the first argument
3172** was not opened for writing (the flags parameter to [sqlite3_blob_open()]
3173*** was zero), this function returns [SQLITE_READONLY].
danielk19778cbadb02007-05-03 16:31:26 +00003174**
3175** This function may only modify the contents of the blob, it is
3176** not possible to increase the size of a blob using this API. If
3177** offset iOffset is less than n bytes from the end of the blob,
drh6ed48bf2007-06-14 20:57:18 +00003178** [SQLITE_ERROR] is returned and no data is written.
danielk19778cbadb02007-05-03 16:31:26 +00003179**
drh6ed48bf2007-06-14 20:57:18 +00003180** On success, SQLITE_OK is returned. Otherwise, an
3181** [SQLITE_ERROR | SQLite error code] or an
3182** [SQLITE_IOERR_READ | extended error code] is returned.
danielk19778cbadb02007-05-03 16:31:26 +00003183*/
3184int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);
3185
drhd84f9462007-08-15 11:28:56 +00003186/*
3187** CAPI3REF: Virtual File System Objects
3188**
3189** A virtual filesystem (VFS) is an [sqlite3_vfs] object
3190** that SQLite uses to interact
3191** with the underlying operating system. Most builds come with a
3192** single default VFS that is appropriate for the host computer.
3193** New VFSes can be registered and existing VFSes can be unregistered.
3194** The following interfaces are provided.
3195**
drhd677b3d2007-08-20 22:48:41 +00003196** The sqlite3_vfs_find() interface returns a pointer to a VFS given its
drhd84f9462007-08-15 11:28:56 +00003197** name. Names are case sensitive. If there is no match, a NULL
3198** pointer is returned. If zVfsName is NULL then the default
drhd677b3d2007-08-20 22:48:41 +00003199** VFS is returned. If a valid VFS pointer is returned, its
3200** vfsMutex field will have been initialized and nRef will be
3201** greater than zero. The sqlite3_vfs_release() function should
3202** be used to release the VFS when it is no longer needed.
drhd84f9462007-08-15 11:28:56 +00003203**
drhd677b3d2007-08-20 22:48:41 +00003204** New VFSes are registered with sqlite3_vfs_register(). Each
drhd84f9462007-08-15 11:28:56 +00003205** new VFS becomes the default VFS if the makeDflt flag is set.
3206** The same VFS can be registered multiple times without injury.
3207** To make an existing VFS into the default VFS, register it again
3208** with the makeDflt flag set.
3209**
drhd677b3d2007-08-20 22:48:41 +00003210** Unregister a VFS with the sqlite3_vfs_unregister() interface.
drhd84f9462007-08-15 11:28:56 +00003211** If the default VFS is unregistered, another VFS is chosen as
3212** the default. The choice for the new VFS is arbitrary.
3213*/
drhd677b3d2007-08-20 22:48:41 +00003214sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName);
3215int sqlite3_vfs_release(sqlite3_vfs*);
3216int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);
3217int sqlite3_vfs_unregister(sqlite3_vfs*);
drhd84f9462007-08-15 11:28:56 +00003218
3219/*
3220** CAPI3REF: Mutexes
3221**
3222** The SQLite core uses these routines for thread
3223** synchronization. Though they are intended for internal
3224** use by SQLite, code that links against SQLite is
3225** permitted to use any of these routines.
3226**
3227** The SQLite source code contains multiple implementations
3228** of these mutex routines that can be selected at compile-time
3229** by defining one of the following C preprocessor macros:
3230**
3231** <ul>
3232** <li> SQLITE_MUTEX_PTHREAD
3233** <li> SQLITE_MUTEX_WIN32
3234** <li> SQLITE_MUTEX_NOOP
3235** <li> SQLITE_MUTEX_APPDEF
3236** </ul>
3237**
3238** If none of the above macros is defined, the code uses
3239** a default implementation.
3240**
3241** The SQLITE_MUTEX_NOOP implementation is a set of routines
3242** that does no real locking and is appropriate for use in
3243** a single-threaded application.
3244**
3245** If the SQLITE_MUTEX_APPDEF is defined, then no mutex
3246** implementation is included with the library. The
3247** mutex interface routines defined above are external
3248** references in the SQLite library for which implementations
3249** must be provided by the application.
3250**
3251** The sqlite3_mutex_alloc() routine allocates a new
3252** mutex and returns a pointer to it. If it returns NULL
3253** that means that a mutex could not be allocated. SQLite
3254** will unwind its stack and return an error. The argument
drh6bdec4a2007-08-16 19:40:16 +00003255** to sqlite3_mutex_alloc() is one of these integer constants:
3256**
3257** <ul>
3258** <li> SQLITE_MUTEX_FAST
3259** <li> SQLITE_MUTEX_RECURSIVE
3260** <li> SQLITE_MUTEX_STATIC_MASTER
3261** <li> SQLITE_MUTEX_STATIC_MEM
drh86f8c192007-08-22 00:39:19 +00003262** <li> SQLITE_MUTEX_STATIC_MEM2
drh6bdec4a2007-08-16 19:40:16 +00003263** <li> SQLITE_MUTEX_STATIC_PRNG
3264** </ul>
3265**
3266** The first two constants cause sqlite3_mutex_alloc() to create
3267** a new mutex. The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
3268** is used but not necessarily so when SQLITE_MUTEX_FAST is used.
3269** The mutex implementation does not need to make a distinction
3270** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does
3271** not want to. But SQLite will only request a recursive mutex in
3272** cases where it really needs one. If a faster non-recursive mutex
3273** implementation is available on the host platform, the mutex subsystem
3274** might return such a mutex in response to SQLITE_MUTEX_FAST.
3275**
3276** The other allowed parameters to sqlite3_mutex_alloc() each return
3277** a pointer to a static preexisting mutex. Three static mutexes are
3278** used by the current version of SQLite. Future versions of SQLite
3279** may add additional static mutexes. Static mutexes are for internal
3280** use by SQLite only. Applications that use SQLite mutexes should
3281** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or
3282** SQLITE_MUTEX_RECURSIVE.
3283**
3284** Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST
3285** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
3286** returns a different mutex on every call. But for the static
3287** mutex types, the same mutex is returned on every call that has
3288** the same type number.
drhd84f9462007-08-15 11:28:56 +00003289**
3290** The sqlite3_mutex_free() routine deallocates a previously
drh6bdec4a2007-08-16 19:40:16 +00003291** allocated dynamic mutex. SQLite is careful to deallocate every
3292** dynamic mutex that it allocates. The dynamic mutexes must not be in
drhe53831d2007-08-17 01:14:38 +00003293** use when they are deallocated. Attempting to deallocate a static
3294** mutex results in undefined behavior. SQLite never deallocates
3295** a static mutex.
drhd84f9462007-08-15 11:28:56 +00003296**
drh6bdec4a2007-08-16 19:40:16 +00003297** The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt
3298** to enter a mutex. If another thread is already within the mutex,
3299** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return
3300** SQLITE_BUSY. The sqlite3_mutex_try() interface returns SQLITE_OK
3301** upon successful entry. Mutexes created using SQLITE_MUTEX_RECURSIVE can
3302** be entered multiple times by the same thread. In such cases the,
3303** mutex must be exited an equal number of times before another thread
3304** can enter. If the same thread tries to enter any other kind of mutex
3305** more than once, the behavior is undefined. SQLite will never exhibit
3306** such behavior in its own use of mutexes.
drhd84f9462007-08-15 11:28:56 +00003307**
3308** The sqlite3_mutex_exit() routine exits a mutex that was
3309** previously entered by the same thread. The behavior
3310** is undefined if the mutex is not currently entered or
3311** is not currently allocated. SQLite will never do either.
drhd677b3d2007-08-20 22:48:41 +00003312**
3313** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines
3314** are intended for use inside assert() statements. They should
3315** return true if the mutex in their argument is held or not held,
3316** respectively, by the current thread. The implementation is
3317** not required to provided working implementations of these
3318** routines as their intended use is within assert() statements
3319** only. If the implementation does not provide working
3320** versions of these routines, it must at least provide stubs
3321** that always return true.
3322**
3323** If the argument to sqlite3_mutex_held() is a NULL pointer then
3324** the routine should return 1. This seems counter-intuitive since
3325** clearly the mutex cannot be held if it does not exist. But the
3326** the reason the mutex does not exist is because the build is not
3327** using mutexes. And we do not want the assert() containing the
3328** call to sqlite3_mutex_held() to fail, so a non-zero return is
3329** the appropriate thing to do. The sqlite3_mutex_notheld()
3330** interface should also return 1 when given a NULL pointer.
drhd84f9462007-08-15 11:28:56 +00003331*/
3332sqlite3_mutex *sqlite3_mutex_alloc(int);
3333void sqlite3_mutex_free(sqlite3_mutex*);
drh6bdec4a2007-08-16 19:40:16 +00003334void sqlite3_mutex_enter(sqlite3_mutex*);
3335int sqlite3_mutex_try(sqlite3_mutex*);
drhd84f9462007-08-15 11:28:56 +00003336void sqlite3_mutex_leave(sqlite3_mutex*);
drhd677b3d2007-08-20 22:48:41 +00003337int sqlite3_mutex_held(sqlite3_mutex*);
3338int sqlite3_mutex_notheld(sqlite3_mutex*);
drh32bc3f62007-08-21 20:25:39 +00003339
3340/*
3341** CAPI3REF: Mutex Types
3342**
3343** The [sqlite3_mutex_alloc()] interface takes a single argument
3344** which is one of these integer constants.
3345*/
drh6bdec4a2007-08-16 19:40:16 +00003346#define SQLITE_MUTEX_FAST 0
3347#define SQLITE_MUTEX_RECURSIVE 1
3348#define SQLITE_MUTEX_STATIC_MASTER 2
drh86f8c192007-08-22 00:39:19 +00003349#define SQLITE_MUTEX_STATIC_MEM 3 /* sqlite3_malloc() */
3350#define SQLITE_MUTEX_STATIC_MEM2 4 /* sqlite3_release_memory() */
3351#define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_random() */
drh6d2069d2007-08-14 01:58:53 +00003352
3353
danielk19778cbadb02007-05-03 16:31:26 +00003354/*
drhb37df7b2005-10-13 02:09:49 +00003355** Undo the hack that converts floating point types to integer for
3356** builds on processors without floating point support.
3357*/
3358#ifdef SQLITE_OMIT_FLOATING_POINT
3359# undef double
3360#endif
3361
drh382c0242001-10-06 16:33:02 +00003362#ifdef __cplusplus
3363} /* End of the 'extern "C"' block */
3364#endif
danielk19774adee202004-05-08 08:23:19 +00003365#endif