blob: 55f9204220c49a7276d29d2831c5054c67af3fdd [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**
drh605264d2007-08-21 15:13:19 +000033** @(#) $Id: sqlite.h.in,v 1.232 2007/08/21 15:13:19 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.
drh75897232000-05-29 14:26:00 +0000172*/
danielk1977f9d64d22004-06-19 08:18:07 +0000173int sqlite3_close(sqlite3 *);
drh75897232000-05-29 14:26:00 +0000174
175/*
176** The type for a callback function.
drh6ed48bf2007-06-14 20:57:18 +0000177** This is legacy and deprecated. It is included for historical
178** compatibility and is not documented.
drh75897232000-05-29 14:26:00 +0000179*/
drh12057d52004-09-06 17:34:12 +0000180typedef int (*sqlite3_callback)(void*,int,char**, char**);
drh75897232000-05-29 14:26:00 +0000181
182/*
drh6ed48bf2007-06-14 20:57:18 +0000183** CAPI3REF: One-Step Query Execution Interface
184**
185** This interface is used to do a one-time evaluatation of zero
186** or more SQL statements. UTF-8 text of the SQL statements to
187** be evaluted is passed in as the second parameter. The statements
188** are prepared one by one using [sqlite3_prepare()], evaluated
189** using [sqlite3_step()], then destroyed using [sqlite3_finalize()].
drh75897232000-05-29 14:26:00 +0000190**
191** If one or more of the SQL statements are queries, then
192** the callback function specified by the 3rd parameter is
193** invoked once for each row of the query result. This callback
194** should normally return 0. If the callback returns a non-zero
195** value then the query is aborted, all subsequent SQL statements
danielk19776f8a5032004-05-10 10:34:51 +0000196** are skipped and the sqlite3_exec() function returns the SQLITE_ABORT.
drh75897232000-05-29 14:26:00 +0000197**
drh6ed48bf2007-06-14 20:57:18 +0000198** The 4th parameter to this interface is an arbitrary pointer that is
199** passed through to the callback function as its first parameter.
drh75897232000-05-29 14:26:00 +0000200**
201** The 2nd parameter to the callback function is the number of
drhb19a2bc2001-09-16 00:13:26 +0000202** columns in the query result. The 3rd parameter to the callback
drh6ed48bf2007-06-14 20:57:18 +0000203** is an array of strings holding the values for each column
204** as extracted using [sqlite3_column_text()].
205** The 4th parameter to the callback is an array of strings
206** obtained using [sqlite3_column_name()] and holding
drhb19a2bc2001-09-16 00:13:26 +0000207** the names of each column.
drh75897232000-05-29 14:26:00 +0000208**
209** The callback function may be NULL, even for queries. A NULL
210** callback is not an error. It just means that no callback
211** will be invoked.
212**
213** If an error occurs while parsing or evaluating the SQL (but
214** not while executing the callback) then an appropriate error
drh6ed48bf2007-06-14 20:57:18 +0000215** message is written into memory obtained from [sqlite3_malloc()] and
drhb19a2bc2001-09-16 00:13:26 +0000216** *errmsg is made to point to that message. The calling function
217** is responsible for freeing the memory that holds the error
drh6ed48bf2007-06-14 20:57:18 +0000218** message. Use [sqlite3_free()] for this. If errmsg==NULL,
drhb86ccfb2003-01-28 23:13:10 +0000219** then no error message is ever written.
drhb19a2bc2001-09-16 00:13:26 +0000220**
221** The return value is is SQLITE_OK if there are no errors and
drh6ed48bf2007-06-14 20:57:18 +0000222** some other [SQLITE_OK | return code] if there is an error.
223** The particular return value depends on the type of error.
drh58b95762000-06-02 01:17:37 +0000224**
drh75897232000-05-29 14:26:00 +0000225*/
danielk19776f8a5032004-05-10 10:34:51 +0000226int sqlite3_exec(
drh6ed48bf2007-06-14 20:57:18 +0000227 sqlite3*, /* An open database */
228 const char *sql, /* SQL to be evaluted */
229 int (*callback)(void*,int,char**,char**), /* Callback function */
230 void *, /* 1st argument to callback */
231 char **errmsg /* Error msg written here */
drh75897232000-05-29 14:26:00 +0000232);
233
drh58b95762000-06-02 01:17:37 +0000234/*
drh6ed48bf2007-06-14 20:57:18 +0000235** CAPI3REF: Result Codes
236** KEYWORDS: SQLITE_OK
237**
238** Many SQLite functions return an integer result code from the set shown
239** above in order to indicates success or failure.
240**
241** The result codes above are the only ones returned by SQLite in its
242** default configuration. However, the [sqlite3_extended_result_codes()]
243** API can be used to set a database connectoin to return more detailed
244** result codes.
245**
246** See also: [SQLITE_IOERR_READ | extended result codes]
247**
drh58b95762000-06-02 01:17:37 +0000248*/
drh717e6402001-09-27 03:22:32 +0000249#define SQLITE_OK 0 /* Successful result */
drh15b9a152006-01-31 20:49:13 +0000250/* beginning-of-error-codes */
drh717e6402001-09-27 03:22:32 +0000251#define SQLITE_ERROR 1 /* SQL error or missing database */
drh2db0bbc2005-08-11 02:10:18 +0000252#define SQLITE_INTERNAL 2 /* NOT USED. Internal logic error in SQLite */
drh717e6402001-09-27 03:22:32 +0000253#define SQLITE_PERM 3 /* Access permission denied */
254#define SQLITE_ABORT 4 /* Callback routine requested an abort */
255#define SQLITE_BUSY 5 /* The database file is locked */
256#define SQLITE_LOCKED 6 /* A table in the database is locked */
257#define SQLITE_NOMEM 7 /* A malloc() failed */
258#define SQLITE_READONLY 8 /* Attempt to write a readonly database */
drh24cd67e2004-05-10 16:18:47 +0000259#define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite3_interrupt()*/
drh717e6402001-09-27 03:22:32 +0000260#define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */
261#define SQLITE_CORRUPT 11 /* The database disk image is malformed */
drh2db0bbc2005-08-11 02:10:18 +0000262#define SQLITE_NOTFOUND 12 /* NOT USED. Table or record not found */
drh717e6402001-09-27 03:22:32 +0000263#define SQLITE_FULL 13 /* Insertion failed because database is full */
264#define SQLITE_CANTOPEN 14 /* Unable to open the database file */
drh4f0ee682007-03-30 20:43:40 +0000265#define SQLITE_PROTOCOL 15 /* NOT USED. Database lock protocol error */
drh24cd67e2004-05-10 16:18:47 +0000266#define SQLITE_EMPTY 16 /* Database is empty */
drh717e6402001-09-27 03:22:32 +0000267#define SQLITE_SCHEMA 17 /* The database schema changed */
drhc797d4d2007-05-08 01:08:49 +0000268#define SQLITE_TOOBIG 18 /* String or BLOB exceeds size limit */
drh717e6402001-09-27 03:22:32 +0000269#define SQLITE_CONSTRAINT 19 /* Abort due to contraint violation */
drh8aff1012001-12-22 14:49:24 +0000270#define SQLITE_MISMATCH 20 /* Data type mismatch */
drh247be432002-05-10 05:44:55 +0000271#define SQLITE_MISUSE 21 /* Library used incorrectly */
drh8766c342002-11-09 00:33:15 +0000272#define SQLITE_NOLFS 22 /* Uses OS features not supported on host */
drhed6c8672003-01-12 18:02:16 +0000273#define SQLITE_AUTH 23 /* Authorization denied */
drh1c2d8412003-03-31 00:30:47 +0000274#define SQLITE_FORMAT 24 /* Auxiliary database format error */
danielk19776f8a5032004-05-10 10:34:51 +0000275#define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */
drhc602f9a2004-02-12 19:01:04 +0000276#define SQLITE_NOTADB 26 /* File opened that is not a database file */
danielk19776f8a5032004-05-10 10:34:51 +0000277#define SQLITE_ROW 100 /* sqlite3_step() has another row ready */
278#define SQLITE_DONE 101 /* sqlite3_step() has finished executing */
drh15b9a152006-01-31 20:49:13 +0000279/* end-of-error-codes */
drh717e6402001-09-27 03:22:32 +0000280
drhaf9ff332002-01-16 21:00:27 +0000281/*
drh6ed48bf2007-06-14 20:57:18 +0000282** CAPI3REF: Extended Result Codes
drh4ac285a2006-09-15 07:28:50 +0000283**
drh6ed48bf2007-06-14 20:57:18 +0000284** In its default configuration, SQLite API routines return one of 26 integer
285** result codes described at result-codes. However, experience has shown that
286** many of these result codes are too course-grained. They do not provide as
287** much information about problems as users might like. In an effort to
288** address this, newer versions of SQLite (version 3.3.8 and later) include
289** support for additional result codes that provide more detailed information
290** about errors. The extended result codes are enabled (or disabled) for
291** each database
292** connection using the [sqlite3_extended_result_codes()] API.
293**
294** Some of the available extended result codes are listed above.
295** We expect the number of extended result codes will be expand
296** over time. Software that uses extended result codes should expect
297** to see new result codes in future releases of SQLite.
298**
299** The symbolic name for an extended result code always contains a related
300** primary result code as a prefix. Primary result codes contain a single
301** "_" character. Extended result codes contain two or more "_" characters.
302** The numeric value of an extended result code can be converted to its
303** corresponding primary result code by masking off the lower 8 bytes.
drh4ac285a2006-09-15 07:28:50 +0000304**
305** The SQLITE_OK result code will never be extended. It will always
306** be exactly zero.
drh4ac285a2006-09-15 07:28:50 +0000307*/
308#define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8))
309#define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8))
310#define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8))
311#define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4<<8))
312#define SQLITE_IOERR_DIR_FSYNC (SQLITE_IOERR | (5<<8))
313#define SQLITE_IOERR_TRUNCATE (SQLITE_IOERR | (6<<8))
314#define SQLITE_IOERR_FSTAT (SQLITE_IOERR | (7<<8))
315#define SQLITE_IOERR_UNLOCK (SQLITE_IOERR | (8<<8))
316#define SQLITE_IOERR_RDLOCK (SQLITE_IOERR | (9<<8))
danielk1977979f38e2007-03-27 16:19:51 +0000317#define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8))
danielk1977e965ac72007-06-13 15:22:28 +0000318#define SQLITE_IOERR_BLOCKED (SQLITE_IOERR | (11<<8))
drh4ac285a2006-09-15 07:28:50 +0000319
320/*
drh6d2069d2007-08-14 01:58:53 +0000321** CAPI3REF: Flags For File Open Operations
322**
323** Combination of the following bit values are used as the
324** third argument to the [sqlite3_open_v2()] interface and
325** as fourth argument to the xOpen method of the
drhd84f9462007-08-15 11:28:56 +0000326** [sqlite3_vfs] object.
drh6d2069d2007-08-14 01:58:53 +0000327**
328*/
329#define SQLITE_OPEN_READONLY 0x00000001
330#define SQLITE_OPEN_READWRITE 0x00000002
331#define SQLITE_OPEN_CREATE 0x00000004
332#define SQLITE_OPEN_DELETEONCLOSE 0x00000008
333#define SQLITE_OPEN_EXCLUSIVE 0x00000010
334#define SQLITE_OPEN_MAIN_DB 0x00000100
335#define SQLITE_OPEN_TEMP_DB 0x00000200
336#define SQLITE_OPEN_MAIN_JOURNAL 0x00000300
337#define SQLITE_OPEN_TEMP_JOURNAL 0x00000400
338#define SQLITE_OPEN_SUBJOURNAL 0x00000500
339#define SQLITE_OPEN_MASTER_JOURNAL 0x00000600
340
341/*
342** CAPI3REF: Device Characteristics
343**
344** The xDeviceCapabilities method of the [sqlite3_io_methods]
345** object returns an integer which is a vector of the following
346** bit values expressing I/O characteristics of the mass storage
347** device that holds the file that the [sqlite3_io_methods]
348** refers to.
349**
350** The SQLITE_IOCAP_ATOMIC property means that all writes of
351** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values
352** mean that writes of blocks that are nnn bytes in size and
353** are aligned to an address which is an integer multiple of
354** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means
355** that when data is appended to a file, the data is appended
356** first then the size of the file is extended, never the other
357** way around. The SQLITE_IOCAP_SEQUENTIAL property means that
358** information is written to disk in the same order as calls
359** to xWrite().
360*/
361#define SQLITE_IOCAP_ATOMIC 0x00000001
362#define SQLITE_IOCAP_ATOMIC512 0x00000002
363#define SQLITE_IOCAP_ATOMIC1K 0x00000004
364#define SQLITE_IOCAP_ATOMIC2K 0x00000008
365#define SQLITE_IOCAP_ATOMIC4K 0x00000010
366#define SQLITE_IOCAP_ATOMIC8K 0x00000020
367#define SQLITE_IOCAP_ATOMIC16K 0x00000040
368#define SQLITE_IOCAP_ATOMIC32K 0x00000080
369#define SQLITE_IOCAP_ATOMIC64K 0x00000100
370#define SQLITE_IOCAP_SAFE_APPEND 0x00000200
371#define SQLITE_IOCAP_SEQUENTIAL 0x00000400
372
373/*
374** CAPI3REF: File Locking Levels
375**
376** SQLite uses one of the following integer values as the second
377** argument to calls it makes to the xLock() and xUnlock() methods
drhd84f9462007-08-15 11:28:56 +0000378** of an [sqlite3_io_methods] object.
drh6d2069d2007-08-14 01:58:53 +0000379*/
380#define SQLITE_LOCK_NONE 0
381#define SQLITE_LOCK_SHARED 1
382#define SQLITE_LOCK_RESERVED 2
383#define SQLITE_LOCK_PENDING 3
384#define SQLITE_LOCK_EXCLUSIVE 4
385
386/*
387** CAPI3REF: Synchronization Type Flags
388**
389** When SQLite invokes the xSync() method of an [sqlite3_io_methods]
390** object it uses a combination of the following integer values as
391** the second argument.
392**
393** When the SQLITE_SYNC_DATAONLY flag is used, it means that the
394** sync operation only needs to flush data to mass storage. Inode
395** information need not be flushed. The SQLITE_SYNC_BARRIER flag
396** means that the nothing actually needs to be synched to mass storage,
397** but all write operations that occur before the barrier must complete
398** before any write operations that occur after the barrier begin.
399** The SQLITE_SYNC_NORMAL means to use normal fsync() semantics.
400** The SQLITE_SYNC_FULL flag means to use Mac OS-X style fullsync
401** instead of fsync().
402*/
403#define SQLITE_SYNC_BARRIER 0x00001
404#define SQLITE_SYNC_NORMAL 0x00002
405#define SQLITE_SYNC_FULL 0x00003
406#define SQLITE_SYNC_DATAONLY 0x00010
407
408
409/*
410** CAPI3REF: OS Interface Open File Handle
411**
412** An [sqlite3_file] object represents an open file in the OS
413** interface layer. Individual OS interface implementations will
414** want to subclass this object by appending additional fields
drhd84f9462007-08-15 11:28:56 +0000415** of their own use. The pMethods entry is a pointer to an
416** [sqlite3_io_methods] object that defines methods for performing
417** I/O operations on the open file.
drh6d2069d2007-08-14 01:58:53 +0000418*/
419typedef struct sqlite3_file sqlite3_file;
420struct sqlite3_file {
421 struct sqlite3_io_methods *pMethods; /* Methods against the open file */
422};
423
424/*
425** CAPI3REF: OS Interface File Virtual Methods Object
426**
drhd84f9462007-08-15 11:28:56 +0000427** Every open file in the [sqlite3_vfs] xOpen method contains a pointer to
drh6d2069d2007-08-14 01:58:53 +0000428** an instance of the following object. This object defines the
429** methods used to perform various operations against the open file.
drhd84f9462007-08-15 11:28:56 +0000430**
431** The flags argument to xSync may be one of SQLITE_SYNC_BARRIER,
432** SQLITE_SYNC_NORMAL, SQLITE_SYNC_FULL. The first choice means that
433** data is not necessarily synced to disk completely, only that
434** all writes that occur before the sync complete before any
435** writes that occur after the sync. The second flag is the
436** normal fsync(). The third flag is a OS-X style fullsync.
437** The SQLITE_SYNC_DATA flag may be ORed in to indicate that only
438** the data of the file and not its inode needs to be synced.
439**
440** The integer values to xLock() and xUnlock() are one of
441** SQLITE_LOCK_NONE, SQLITE_LOCK_READ, SQLITE_LOCK_RESERVED,
442** SQLITE_LOCK_PENDING, or SQLITE_LOCK_EXCLUSIVE. xLock()
443** increases the lock. xUnlock() decreases the lock.
444** The xCheckReservedLock() method looks
445** to see if any database connection, either in this
446** process or in some other process, is holding an RESERVED,
447** PENDING, or EXCLUSIVE lock on the file. It returns true
448** if such a lock exists and false if not.
449**
450** xBreakLock() attempts to break a lock held by another process.
451** This can be used to remove a stale dot-file lock, for example.
452** It returns 0 on success and non-zero for a failure.
453**
454** The xSectorSize() method returns the sector size of the
455** device that underlies the file. The sector size is the
456** minimum write that can be performed without disturbing
457** other bytes in the file. The xDeviceCharacteristics()
458** method returns a bit vector describing behaviors of the
459** underlying device:
460**
461** <ul>
462** <li> SQLITE_IOCAP_ATOMIC
463** <li> SQLITE_IOCAP_ATOMIC512
464** <li> SQLITE_IOCAP_ATOMIC1K
465** <li> SQLITE_IOCAP_ATOMIC2K
466** <li> SQLITE_IOCAP_ATOMIC4K
467** <li> SQLITE_IOCAP_ATOMIC8K
468** <li> SQLITE_IOCAP_ATOMIC16K
469** <li> SQLITE_IOCAP_ATOMIC32K
470** <li> SQLITE_IOCAP_ATOMIC64K
471** <li> SQLITE_IOCAP_SAFE_APPEND
472** <li> SQLITE_IOCAP_SEQUENTIAL
473** </ul>
474**
475** The SQLITE_IOCAP_ATOMIC property means that all writes of
476** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values
477** mean that writes of blocks that are nnn bytes in size and
478** are aligned to an address which is an integer multiple of
479** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means
480** that when data is appended to a file, the data is appended
481** first then the size of the file is extended, never the other
482** way around. The SQLITE_IOCAP_SEQUENTIAL property means that
483** information is written to disk in the same order as calls
484** to xWrite().
drh6d2069d2007-08-14 01:58:53 +0000485*/
486typedef struct sqlite3_io_methods sqlite3_io_methods;
487struct sqlite3_io_methods {
488 int iVersion;
489 int (*xClose)(sqlite3_file*);
490 int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite_int64 iOfst);
danielk197762079062007-08-15 17:08:46 +0000491 int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite_int64 iOfst);
drh6d2069d2007-08-14 01:58:53 +0000492 int (*xTruncate)(sqlite3_file*, sqlite_int64 size);
493 int (*xSync)(sqlite3_file*, int flags);
494 int (*xFileSize)(sqlite3_file*, sqlite_int64 *pSize);
495 int (*xLock)(sqlite3_file*, int);
496 int (*xUnlock)(sqlite3_file*, int);
drhd84f9462007-08-15 11:28:56 +0000497 int (*xCheckReservedLock)(sqlite3_file*);
drh6d2069d2007-08-14 01:58:53 +0000498 int (*xBreakLock)(sqlite3_file*);
danielk197790949c22007-08-17 16:50:38 +0000499 int (*xLockState)(sqlite3_file *);
drh6d2069d2007-08-14 01:58:53 +0000500 int (*xSectorSize)(sqlite3_file*);
501 int (*xDeviceCharacteristics)(sqlite3_file*);
502 /* Additional methods may be added in future releases */
503};
504
505/*
drhd84f9462007-08-15 11:28:56 +0000506** CAPI3REF: Mutex Handle
drh6d2069d2007-08-14 01:58:53 +0000507**
drhd84f9462007-08-15 11:28:56 +0000508** The mutex module within SQLite defines [sqlite3_mutex] to be an
509** abstract type for a mutex object. The SQLite core never looks
510** at the internal representation of an [sqlite3_mutex]. It only
511** deals with pointers to the [sqlite3_mutex] object.
drh6bdec4a2007-08-16 19:40:16 +0000512**
513** Mutexes are created using [sqlite3_mutex_alloc()].
drh6d2069d2007-08-14 01:58:53 +0000514*/
515typedef struct sqlite3_mutex sqlite3_mutex;
516
517/*
518** CAPI3REF: OS Interface Object
519**
drhd84f9462007-08-15 11:28:56 +0000520** An instance of this object defines the interface between the
521** SQLite core and the underlying operating system. The "vfs"
522** in the name of the object stands for "virtual file system".
drh6d2069d2007-08-14 01:58:53 +0000523**
524** The iVersion field is initially 1 but may be larger for future
drh6bdec4a2007-08-16 19:40:16 +0000525** versions of SQLite. Additional fields may be appended to this
526** object when the iVersion value is increased.
527**
528** The szOsFile field is the size of the subclassed sqlite3_file
drhd84f9462007-08-15 11:28:56 +0000529** structure used by this VFS. mxPathname is the maximum length of
530** a pathname in this VFS.
531**
532** The nRef field is incremented and decremented by SQLite to keep
533** count of the number of users of the VFS. This field and
534** vfsMutex, pNext, and pPrev are the only fields in the sqlite3_vfs
drh6bdec4a2007-08-16 19:40:16 +0000535** structure that SQLite will ever modify. SQLite will only access
536** or modify these fields while holding a particular static mutex.
537** The application should never modify any fields of the sqlite3_vfs
538** object once the object has been registered.
drh6d2069d2007-08-14 01:58:53 +0000539**
drhd84f9462007-08-15 11:28:56 +0000540** The sqlite3_vfs.vfsMutex is a mutex used by the OS interface.
541** It should initially be NULL. SQLite will initialize this field
drh6bdec4a2007-08-16 19:40:16 +0000542** using sqlite3_mutex_alloc() upon first use of the adaptor
drhd84f9462007-08-15 11:28:56 +0000543** by sqlite3_open_v2() and will deallocate the mutex when the
544** last user closes. In other words, vfsMutex will be allocated
545** when nRef transitions from 0 to 1 and will be deallocated when
546** nRef transitions from 1 to 0.
547**
548** Registered vfs modules are kept on a linked list formed by
549** the pNext and pPrev pointers. The [sqlite3_register_vfs()]
550** and [sqlite3_unregister_vfs()] interfaces manage this list
drhd677b3d2007-08-20 22:48:41 +0000551** in a thread-safe way. The [sqlite3_acquire_vfs()] searches the
drhd84f9462007-08-15 11:28:56 +0000552** list.
553**
554** The zName field holds the name of the VFS module. The name must
555** be unique across all VFS modules.
556**
drh6d2069d2007-08-14 01:58:53 +0000557** SQLite will guarantee that the zFilename string passed to
558** xOpen() is a full pathname as generated by xFullPathname() and
559** that the string will be valid and unchanged until xClose() is
drhd84f9462007-08-15 11:28:56 +0000560** called. So the sqlite3_file can store a pointer to the
drh6d2069d2007-08-14 01:58:53 +0000561** filename if it needs to remember the filename for some reason.
drhd84f9462007-08-15 11:28:56 +0000562**
drh6d2069d2007-08-14 01:58:53 +0000563** The flags argument to xOpen() is a copy of the flags argument
drhd84f9462007-08-15 11:28:56 +0000564** to sqlite3_open_v2(). If sqlite3_open() or sqlite3_open16()
565** is used, then flags is SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE.
drh6d2069d2007-08-14 01:58:53 +0000566** If xOpen() opens a file read-only then it sets *pOutFlags to
drhd84f9462007-08-15 11:28:56 +0000567** include SQLITE_OPEN_READONLY. Other bits in *pOutFlags may be
drh6d2069d2007-08-14 01:58:53 +0000568** set.
569**
570** SQLite will also add one of the following flags to the xOpen()
571** call, depending on the object being opened:
572**
573** <ul>
574** <li> [SQLITE_OPEN_MAIN_DB]
575** <li> [SQLITE_OPEN_MAIN_JOURNAL]
576** <li> [SQLITE_OPEN_TEMP_DB]
577** <li> [SQLITE_OPEN_TEMP_JOURNAL]
578** <li> [SQLITE_OPEN_SUBJOURNAL]
579** <li> [SQLITE_OPEN_MASTER_JOURNAL]
580** </ul>
drhd84f9462007-08-15 11:28:56 +0000581**
drh6d2069d2007-08-14 01:58:53 +0000582** The file I/O implementation can use the object type flags to
583** changes the way it deals with files. For example, an application
584** that does not care about crash recovery or rollback, might make
585** the open of a journal file a no-op. Writes to this journal are
drhd84f9462007-08-15 11:28:56 +0000586** also a no-op. Any attempt to read the journal return SQLITE_IOERR.
drh6d2069d2007-08-14 01:58:53 +0000587** Or the implementation might recognize the a database file will
588** be doing page-aligned sector reads and writes in a random order
589** and set up its I/O subsystem accordingly.
590**
591** SQLite might also add one of the following flags to the xOpen
592** method:
593**
594** <ul>
595** <li> [SQLITE_OPEN_DELETEONCLOSE]
596** <li> [SQLITE_OPEN_EXCLUSIVE]
597** </ul>
598**
599** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
600** deleted when it is closed. This will always be set for TEMP
601** databases and journals and for subjournals. The
602** [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened
603** for exclusive access. This flag is set for all files except
604** for the main database file.
605**
606** The sqlite3_file structure passed as the third argument to
607** xOpen is allocated by the caller. xOpen just fills it in. The
608** caller allocates a minimum of szOsFile bytes for the sqlite3_file
609** structure.
610**
611** The flags argument to xAccess() may be 0 (to test for the
612** existance of a file) or SQLITE_ACCESS_READWRITE to test to see
613** if a file is readable and writable, or SQLITE_ACCESS_READONLY
614** to test to see if a file is read-only. The file can be a
615** directory.
616**
617** SQLite will always allocate at least mxPathname+1 byte for
618** the output buffers for xGetTempName and xFullPathname.
619**
drhd84f9462007-08-15 11:28:56 +0000620** The xRandomness(), xSleep(), and xCurrentTime() interfaces
621** are not strictly a part of the filesystem, but they are
622** included in the VFS structure for completeness.
drh6d2069d2007-08-14 01:58:53 +0000623** The xRandomness() function attempts to return nBytes bytes
624** of good-quality randomness into zOut. The return value is
drhd84f9462007-08-15 11:28:56 +0000625** the actual number of bytes of randomness generated. The
626** xSleep() method cause the calling thread to sleep for at
627** least the number of microseconds given. The xCurrentTime()
628** method returns a Julian Day Number for the current date and
629** time.
drh6d2069d2007-08-14 01:58:53 +0000630*/
drhd84f9462007-08-15 11:28:56 +0000631typedef struct sqlite3_vfs sqlite3_vfs;
632struct sqlite3_vfs {
drh6d2069d2007-08-14 01:58:53 +0000633 int iVersion; /* Structure version number */
634 int szOsFile; /* Size of subclassed sqlite3_file */
drh6d2069d2007-08-14 01:58:53 +0000635 int mxPathname; /* Maximum file pathname length */
drhd84f9462007-08-15 11:28:56 +0000636 int nRef; /* Number of references to this structure */
637 sqlite3_mutex *vfsMutex; /* A mutex for this VFS */
638 sqlite3_vfs *pNext; /* Next registered VFS */
drhd84f9462007-08-15 11:28:56 +0000639 const char *zName; /* Name of this virtual file system */
drh6d2069d2007-08-14 01:58:53 +0000640 void *pAppData; /* Application context */
641 int (*xOpen)(void *pAppData, const char *zName, sqlite3_file*,
642 int flags, int *pOutFlags);
danielk1977fee2d252007-08-18 10:59:19 +0000643 int (*xDelete)(void *pAppData, const char *zName, int syncDir);
drh6d2069d2007-08-14 01:58:53 +0000644 int (*xAccess)(void *pAppData, const char *zName, int flags);
645 int (*xGetTempName)(void *pAppData, char *zOut);
646 int (*xFullPathname)(void *pAppData, const char *zName, char *zOut);
danielk1977b4b47412007-08-17 15:53:36 +0000647 void *(*xDlOpen)(void *pAppData, const char *zFilename);
648 void (*xDlError)(void *pAppData, int nByte, char *zErrMsg);
drh6d2069d2007-08-14 01:58:53 +0000649 void *(*xDlSym)(void*, const char *zSymbol);
danielk1977b4b47412007-08-17 15:53:36 +0000650 void (*xDlClose)(void*);
drh6d2069d2007-08-14 01:58:53 +0000651 int (*xRandomness)(void *pAppData, int nByte, char *zOut);
652 int (*xSleep)(void *pAppData, int microseconds);
653 int (*xCurrentTime)(void *pAppData, double*);
drhd84f9462007-08-15 11:28:56 +0000654 /* New fields may be appended in figure versions. The iVersion
drh6d2069d2007-08-14 01:58:53 +0000655 ** value will increment whenever this happens. */
656};
657
danielk1977b4b47412007-08-17 15:53:36 +0000658#define SQLITE_ACCESS_EXISTS 0
659#define SQLITE_ACCESS_READWRITE 1
660#define SQLITE_ACCESS_READONLY 2
661
drh6d2069d2007-08-14 01:58:53 +0000662/*
drh6ed48bf2007-06-14 20:57:18 +0000663** CAPI3REF: Enable Or Disable Extended Result Codes
664**
665** This routine enables or disables the
666** [SQLITE_IOERR_READ | extended result codes] feature.
667** By default, SQLite API routines return one of only 26 integer
668** [SQLITE_OK | result codes]. When extended result codes
669** are enabled by this routine, the repetoire of result codes can be
670** much larger and can (hopefully) provide more detailed information
671** about the cause of an error.
672**
673** The second argument is a boolean value that turns extended result
674** codes on and off. Extended result codes are off by default for
675** backwards compatibility with older versions of SQLite.
drh4ac285a2006-09-15 07:28:50 +0000676*/
677int sqlite3_extended_result_codes(sqlite3*, int onoff);
678
679/*
drh6ed48bf2007-06-14 20:57:18 +0000680** CAPI3REF: Last Insert Rowid
681**
682** Each entry in an SQLite table has a unique 64-bit signed integer key
683** called the "rowid". The rowid is always available as an undeclared
684** column named ROWID, OID, or _ROWID_. If the table has a column of
685** type INTEGER PRIMARY KEY then that column is another an alias for the
686** rowid.
687**
688** This routine returns the rowid of the most recent INSERT into
689** the database from the database connection given in the first
690** argument. If no inserts have ever occurred on this database
691** connection, zero is returned.
692**
693** If an INSERT occurs within a trigger, then the rowid of the
694** inserted row is returned by this routine as long as the trigger
695** is running. But once the trigger terminates, the value returned
696** by this routine reverts to the last value inserted before the
697** trigger fired.
drhaf9ff332002-01-16 21:00:27 +0000698*/
drh6d2069d2007-08-14 01:58:53 +0000699sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
drhaf9ff332002-01-16 21:00:27 +0000700
drhc8d30ac2002-04-12 10:08:59 +0000701/*
drh6ed48bf2007-06-14 20:57:18 +0000702** CAPI3REF: Count The Number Of Rows Modified
703**
drhc8d30ac2002-04-12 10:08:59 +0000704** This function returns the number of database rows that were changed
drh930cc582007-03-28 13:07:40 +0000705** (or inserted or deleted) by the most recent SQL statement. Only
706** changes that are directly specified by the INSERT, UPDATE, or
707** DELETE statement are counted. Auxiliary changes caused by
drh6ed48bf2007-06-14 20:57:18 +0000708** triggers are not counted. Use the [sqlite3_total_changes()] function
709** to find the total number of changes including changes caused by triggers.
710**
711** Within the body of a trigger, the sqlite3_changes() interface can be
712** called to find the number of
drh930cc582007-03-28 13:07:40 +0000713** changes in the most recently completed INSERT, UPDATE, or DELETE
714** statement within the body of the trigger.
drhc8d30ac2002-04-12 10:08:59 +0000715**
716** All changes are counted, even if they were later undone by a
717** ROLLBACK or ABORT. Except, changes associated with creating and
718** dropping tables are not counted.
719**
drh6ed48bf2007-06-14 20:57:18 +0000720** If a callback invokes [sqlite3_exec()] or [sqlite3_step()] recursively,
drh930cc582007-03-28 13:07:40 +0000721** then the changes in the inner, recursive call are counted together
722** with the changes in the outer call.
drhc8d30ac2002-04-12 10:08:59 +0000723**
724** SQLite implements the command "DELETE FROM table" without a WHERE clause
725** by dropping and recreating the table. (This is much faster than going
drha6b81ba2007-06-27 10:21:38 +0000726** through and deleting individual elements from the table.) Because of
drhc8d30ac2002-04-12 10:08:59 +0000727** this optimization, the change count for "DELETE FROM table" will be
728** zero regardless of the number of elements that were originally in the
729** table. To get an accurate count of the number of rows deleted, use
730** "DELETE FROM table WHERE 1" instead.
731*/
danielk1977f9d64d22004-06-19 08:18:07 +0000732int sqlite3_changes(sqlite3*);
drhc8d30ac2002-04-12 10:08:59 +0000733
rdcf146a772004-02-25 22:51:06 +0000734/*
drh6ed48bf2007-06-14 20:57:18 +0000735** CAPI3REF: Total Number Of Rows Modified
736***
danielk1977b28af712004-06-21 06:50:26 +0000737** This function returns the number of database rows that have been
738** modified by INSERT, UPDATE or DELETE statements since the database handle
739** was opened. This includes UPDATE, INSERT and DELETE statements executed
740** as part of trigger programs. All changes are counted as soon as the
741** statement that makes them is completed (when the statement handle is
drh6d2069d2007-08-14 01:58:53 +0000742** passed to [sqlite3_reset()] or [sqlite3_finalise()]).
drh6ed48bf2007-06-14 20:57:18 +0000743**
744** See also the [sqlite3_change()] interface.
rdcf146a772004-02-25 22:51:06 +0000745**
746** SQLite implements the command "DELETE FROM table" without a WHERE clause
747** by dropping and recreating the table. (This is much faster than going
748** through and deleting individual elements form the table.) Because of
749** this optimization, the change count for "DELETE FROM table" will be
750** zero regardless of the number of elements that were originally in the
751** table. To get an accurate count of the number of rows deleted, use
752** "DELETE FROM table WHERE 1" instead.
rdcf146a772004-02-25 22:51:06 +0000753*/
danielk1977b28af712004-06-21 06:50:26 +0000754int sqlite3_total_changes(sqlite3*);
755
drh6ed48bf2007-06-14 20:57:18 +0000756/*
757** CAPI3REF: Interrupt A Long-Running Query
758**
759** This function causes any pending database operation to abort and
drh4c504392000-10-16 22:06:40 +0000760** return at its earliest opportunity. This routine is typically
drh66b89c82000-11-28 20:47:17 +0000761** called in response to a user action such as pressing "Cancel"
drh4c504392000-10-16 22:06:40 +0000762** or Ctrl-C where the user wants a long query operation to halt
763** immediately.
drh930cc582007-03-28 13:07:40 +0000764**
drh6ed48bf2007-06-14 20:57:18 +0000765** It is safe to call this routine from a thread different from the
drh871f6ca2007-08-14 18:03:14 +0000766** thread that is currently running the database operation. But it
767** is not safe to call this routine with a database connection that
768** is closed or might close before sqlite3_interrupt() returns.
drh6ed48bf2007-06-14 20:57:18 +0000769**
770** The SQL operation that is interrupted will return [SQLITE_INTERRUPT].
771** If an interrupted operation was an update that is inside an
772** explicit transaction, then the entire transaction will be rolled
773** back automatically.
drh4c504392000-10-16 22:06:40 +0000774*/
danielk1977f9d64d22004-06-19 08:18:07 +0000775void sqlite3_interrupt(sqlite3*);
drh4c504392000-10-16 22:06:40 +0000776
drh6ed48bf2007-06-14 20:57:18 +0000777/*
778** CAPI3REF: Determine If An SQL Statement Is Complete
779**
780** These functions return true if the given input string comprises
danielk197761de0d12004-05-27 23:56:16 +0000781** one or more complete SQL statements. For the sqlite3_complete() call,
782** the parameter must be a nul-terminated UTF-8 string. For
783** sqlite3_complete16(), a nul-terminated machine byte order UTF-16 string
784** is required.
drh75897232000-05-29 14:26:00 +0000785**
drh6ed48bf2007-06-14 20:57:18 +0000786** These routines are useful for command-line input to determine if the
787** currently entered text forms one or more complete SQL statements or
788** if additional input is needed before sending the statements into
789** SQLite for parsing. The algorithm is simple. If the
drh930cc582007-03-28 13:07:40 +0000790** last token other than spaces and comments is a semicolon, then return
791** true. Actually, the algorithm is a little more complicated than that
792** in order to deal with triggers, but the basic idea is the same: the
793** statement is not complete unless it ends in a semicolon.
drh75897232000-05-29 14:26:00 +0000794*/
danielk19776f8a5032004-05-10 10:34:51 +0000795int sqlite3_complete(const char *sql);
danielk197761de0d12004-05-27 23:56:16 +0000796int sqlite3_complete16(const void *sql);
drh75897232000-05-29 14:26:00 +0000797
drh2dfbbca2000-07-28 14:32:48 +0000798/*
drh6ed48bf2007-06-14 20:57:18 +0000799** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors
800**
801** This routine identifies a callback function that might be invoked
802** whenever an attempt is made to open a database table
803** that another thread or process has locked.
804** If the busy callback is NULL, then [SQLITE_BUSY]
805** (or sometimes [SQLITE_IOERR_BLOCKED])
806** is returned immediately upon encountering the lock.
807** If the busy callback is not NULL, then the
808** callback will be invoked with two arguments. The
drh86939b52007-01-10 12:54:51 +0000809** first argument to the handler is a copy of the void* pointer which
810** is the third argument to this routine. The second argument to
811** the handler is the number of times that the busy handler has
drh6ed48bf2007-06-14 20:57:18 +0000812** been invoked for this locking event. If the
813** busy callback returns 0, then no additional attempts are made to
814** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned.
815** If the callback returns non-zero, then another attempt is made to open the
816** database for reading and the cycle repeats.
drh2dfbbca2000-07-28 14:32:48 +0000817**
drh86939b52007-01-10 12:54:51 +0000818** The presence of a busy handler does not guarantee that
819** it will be invoked when there is lock contention.
820** If SQLite determines that invoking the busy handler could result in
drh6ed48bf2007-06-14 20:57:18 +0000821** a deadlock, it will return [SQLITE_BUSY] instead.
drh86939b52007-01-10 12:54:51 +0000822** Consider a scenario where one process is holding a read lock that
823** it is trying to promote to a reserved lock and
824** a second process is holding a reserved lock that it is trying
825** to promote to an exclusive lock. The first process cannot proceed
826** because it is blocked by the second and the second process cannot
827** proceed because it is blocked by the first. If both processes
828** invoke the busy handlers, neither will make any progress. Therefore,
drh6ed48bf2007-06-14 20:57:18 +0000829** SQLite returns [SQLITE_BUSY] for the first process, hoping that this
drh86939b52007-01-10 12:54:51 +0000830** will induce the first process to release its read lock and allow
831** the second process to proceed.
832**
drh2dfbbca2000-07-28 14:32:48 +0000833** The default busy callback is NULL.
834**
drh6ed48bf2007-06-14 20:57:18 +0000835** The [SQLITE_BUSY] error is converted to [SQLITE_IOERR_BLOCKED] when
836** SQLite is in the middle of a large transaction where all the
837** changes will not fit into the in-memory cache. SQLite will
838** already hold a RESERVED lock on the database file, but it needs
839** to promote this lock to EXCLUSIVE so that it can spill cache
840** pages into the database file without harm to concurrent
841** readers. If it is unable to promote the lock, then the in-memory
842** cache will be left in an inconsistent state and so the error
843** code is promoted from the relatively benign [SQLITE_BUSY] to
844** the more severe [SQLITE_IOERR_BLOCKED]. This error code promotion
845** forces an automatic rollback of the changes. See the
846** <a href="http://www.sqlite.org/cvstrac/wiki?p=CorruptionFollowingBusyError">
847** CorruptionFollowingBusyError</a> wiki page for a discussion of why
848** this is important.
849**
drh2dfbbca2000-07-28 14:32:48 +0000850** Sqlite is re-entrant, so the busy handler may start a new query.
drh6ed48bf2007-06-14 20:57:18 +0000851** (It is not clear why anyone would every want to do this, but it
drh2dfbbca2000-07-28 14:32:48 +0000852** is allowed, in theory.) But the busy handler may not close the
853** database. Closing the database from a busy handler will delete
854** data structures out from under the executing query and will
drh6ed48bf2007-06-14 20:57:18 +0000855** probably result in a segmentation fault or other runtime error.
856**
857** There can only be a single busy handler defined for each database
858** connection. Setting a new busy handler clears any previous one.
859** Note that calling [sqlite3_busy_timeout()] will also set or clear
860** the busy handler.
drhd677b3d2007-08-20 22:48:41 +0000861**
862** When operating in [sqlite3_enable_shared_cache | shared cache mode],
863** only a single busy handler can be defined for each database file.
864** So if two database connections share a single cache, then changing
865** the busy handler on one connection will also change the busy
866** handler in the other connection. The busy handler is invoked
867** in the thread that was running when the SQLITE_BUSY was hit.
drh2dfbbca2000-07-28 14:32:48 +0000868*/
danielk1977f9d64d22004-06-19 08:18:07 +0000869int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
drh2dfbbca2000-07-28 14:32:48 +0000870
871/*
drh6ed48bf2007-06-14 20:57:18 +0000872** CAPI3REF: Set A Busy Timeout
873**
drh2dfbbca2000-07-28 14:32:48 +0000874** This routine sets a busy handler that sleeps for a while when a
875** table is locked. The handler will sleep multiple times until
drh6ed48bf2007-06-14 20:57:18 +0000876** at least "ms" milliseconds of sleeping have been done. After
877** "ms" milliseconds of sleeping, the handler returns 0 which
878** causes [sqlite3_step()] to return [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED].
drh2dfbbca2000-07-28 14:32:48 +0000879**
880** Calling this routine with an argument less than or equal to zero
881** turns off all busy handlers.
drh6ed48bf2007-06-14 20:57:18 +0000882**
883** There can only be a single busy handler for a particular database
884** connection. If another busy handler was defined
885** (using [sqlite3_busy_handler()]) prior to calling
886** this routine, that other busy handler is cleared.
drh2dfbbca2000-07-28 14:32:48 +0000887*/
danielk1977f9d64d22004-06-19 08:18:07 +0000888int sqlite3_busy_timeout(sqlite3*, int ms);
drh2dfbbca2000-07-28 14:32:48 +0000889
drhe3710332000-09-29 13:30:53 +0000890/*
drh6ed48bf2007-06-14 20:57:18 +0000891** CAPI3REF: Convenience Routines For Running Queries
892**
893** This next routine is a convenience wrapper around [sqlite3_exec()].
drhe3710332000-09-29 13:30:53 +0000894** Instead of invoking a user-supplied callback for each row of the
895** result, this routine remembers each row of the result in memory
drh6ed48bf2007-06-14 20:57:18 +0000896** obtained from [sqlite3_malloc()], then returns all of the result after the
drha18c5682000-10-08 22:20:57 +0000897** query has finished.
898**
899** As an example, suppose the query result where this table:
900**
drh6ed48bf2007-06-14 20:57:18 +0000901** <pre>
drha18c5682000-10-08 22:20:57 +0000902** Name | Age
903** -----------------------
904** Alice | 43
905** Bob | 28
906** Cindy | 21
drh6ed48bf2007-06-14 20:57:18 +0000907** </pre>
drha18c5682000-10-08 22:20:57 +0000908**
909** If the 3rd argument were &azResult then after the function returns
drh98699b52000-10-09 12:57:00 +0000910** azResult will contain the following data:
drha18c5682000-10-08 22:20:57 +0000911**
drh6ed48bf2007-06-14 20:57:18 +0000912** <pre>
drha18c5682000-10-08 22:20:57 +0000913** azResult[0] = "Name";
914** azResult[1] = "Age";
915** azResult[2] = "Alice";
916** azResult[3] = "43";
917** azResult[4] = "Bob";
918** azResult[5] = "28";
919** azResult[6] = "Cindy";
920** azResult[7] = "21";
drh6ed48bf2007-06-14 20:57:18 +0000921** </pre>
drha18c5682000-10-08 22:20:57 +0000922**
923** Notice that there is an extra row of data containing the column
924** headers. But the *nrow return value is still 3. *ncolumn is
925** set to 2. In general, the number of values inserted into azResult
926** will be ((*nrow) + 1)*(*ncolumn).
927**
928** After the calling function has finished using the result, it should
danielk19776f8a5032004-05-10 10:34:51 +0000929** pass the result data pointer to sqlite3_free_table() in order to
drha18c5682000-10-08 22:20:57 +0000930** release the memory that was malloc-ed. Because of the way the
drh6ed48bf2007-06-14 20:57:18 +0000931** [sqlite3_malloc()] happens, the calling function must not try to call
932** [sqlite3_free()] directly. Only [sqlite3_free_table()] is able to release
drha18c5682000-10-08 22:20:57 +0000933** the memory properly and safely.
drhe3710332000-09-29 13:30:53 +0000934**
drh6ed48bf2007-06-14 20:57:18 +0000935** The return value of this routine is the same as from [sqlite3_exec()].
drhe3710332000-09-29 13:30:53 +0000936*/
danielk19776f8a5032004-05-10 10:34:51 +0000937int sqlite3_get_table(
drh6ed48bf2007-06-14 20:57:18 +0000938 sqlite3*, /* An open database */
drh9f71c2e2001-11-03 23:57:09 +0000939 const char *sql, /* SQL to be executed */
drhe3710332000-09-29 13:30:53 +0000940 char ***resultp, /* Result written to a char *[] that this points to */
941 int *nrow, /* Number of result rows written here */
942 int *ncolumn, /* Number of result columns written here */
943 char **errmsg /* Error msg written here */
944);
danielk19776f8a5032004-05-10 10:34:51 +0000945void sqlite3_free_table(char **result);
drhe3710332000-09-29 13:30:53 +0000946
drha18c5682000-10-08 22:20:57 +0000947/*
drh6ed48bf2007-06-14 20:57:18 +0000948** CAPI3REF: Formatted String Printing Functions
949**
950** These routines are workalikes of the "printf()" family of functions
951** from the standard C library.
952**
953** The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
drh6d2069d2007-08-14 01:58:53 +0000954** results into memory obtained from [sqlite3_malloc()].
drh6ed48bf2007-06-14 20:57:18 +0000955** The strings returned by these two routines should be
956** released by [sqlite3_free()]. Both routines return a
957** NULL pointer if [sqlite3_malloc()] is unable to allocate enough
958** memory to hold the resulting string.
959**
960** In sqlite3_snprintf() routine is similar to "snprintf()" from
961** the standard C library. The result is written into the
962** buffer supplied as the second parameter whose size is given by
963** the first parameter. Note that the order of the
964** first two parameters is reversed from snprintf(). This is an
965** historical accident that cannot be fixed without breaking
966** backwards compatibility. Note also that sqlite3_snprintf()
967** returns a pointer to its buffer instead of the number of
968** characters actually written into the buffer. We admit that
969** the number of characters written would be a more useful return
970** value but we cannot change the implementation of sqlite3_snprintf()
971** now without breaking compatibility.
972**
973** As long as the buffer size is greater than zero, sqlite3_snprintf()
974** guarantees that the buffer is always zero-terminated. The first
975** parameter "n" is the total size of the buffer, including space for
976** the zero terminator. So the longest string that can be completely
977** written will be n-1 characters.
978**
979** These routines all implement some additional formatting
drh4f26d6c2004-05-26 23:25:30 +0000980** options that are useful for constructing SQL statements.
drha18c5682000-10-08 22:20:57 +0000981** All of the usual printf formatting options apply. In addition, there
drh6ed48bf2007-06-14 20:57:18 +0000982** is are "%q" and "%Q" options.
983**
984** The %q option works like %s in that it substitutes a null-terminated
drh66b89c82000-11-28 20:47:17 +0000985** string from the argument list. But %q also doubles every '\'' character.
drha18c5682000-10-08 22:20:57 +0000986** %q is designed for use inside a string literal. By doubling each '\''
drh66b89c82000-11-28 20:47:17 +0000987** character it escapes that character and allows it to be inserted into
drha18c5682000-10-08 22:20:57 +0000988** the string.
989**
990** For example, so some string variable contains text as follows:
991**
drh6ed48bf2007-06-14 20:57:18 +0000992** <blockquote><pre>
993** char *zText = "It's a happy day!";
994** </pre></blockquote>
drha18c5682000-10-08 22:20:57 +0000995**
drh6ed48bf2007-06-14 20:57:18 +0000996** One can use this text in an SQL statement as follows:
drha18c5682000-10-08 22:20:57 +0000997**
drh6ed48bf2007-06-14 20:57:18 +0000998** <blockquote><pre>
999** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText);
1000** sqlite3_exec(db, zSQL, 0, 0, 0);
1001** sqlite3_free(zSQL);
1002** </pre></blockquote>
drha18c5682000-10-08 22:20:57 +00001003**
1004** Because the %q format string is used, the '\'' character in zText
1005** is escaped and the SQL generated is as follows:
1006**
drh6ed48bf2007-06-14 20:57:18 +00001007** <blockquote><pre>
1008** INSERT INTO table1 VALUES('It''s a happy day!')
1009** </pre></blockquote>
drha18c5682000-10-08 22:20:57 +00001010**
1011** This is correct. Had we used %s instead of %q, the generated SQL
1012** would have looked like this:
1013**
drh6ed48bf2007-06-14 20:57:18 +00001014** <blockquote><pre>
1015** INSERT INTO table1 VALUES('It's a happy day!');
1016** </pre></blockquote>
drha18c5682000-10-08 22:20:57 +00001017**
1018** This second example is an SQL syntax error. As a general rule you
1019** should always use %q instead of %s when inserting text into a string
1020** literal.
drh6ed48bf2007-06-14 20:57:18 +00001021**
1022** The %Q option works like %q except it also adds single quotes around
1023** the outside of the total string. Or if the parameter in the argument
1024** list is a NULL pointer, %Q substitutes the text "NULL" (without single
1025** quotes) in place of the %Q option. So, for example, one could say:
1026**
1027** <blockquote><pre>
1028** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);
1029** sqlite3_exec(db, zSQL, 0, 0, 0);
1030** sqlite3_free(zSQL);
1031** </pre></blockquote>
1032**
1033** The code above will render a correct SQL statement in the zSQL
1034** variable even if the zText variable is a NULL pointer.
drha18c5682000-10-08 22:20:57 +00001035*/
danielk19776f8a5032004-05-10 10:34:51 +00001036char *sqlite3_mprintf(const char*,...);
1037char *sqlite3_vmprintf(const char*, va_list);
drhfeac5f82004-08-01 00:10:45 +00001038char *sqlite3_snprintf(int,char*,const char*, ...);
drh5191b7e2002-03-08 02:12:00 +00001039
drh28dd4792006-06-26 21:35:44 +00001040/*
drh90f6a5b2007-08-15 13:04:54 +00001041** CAPI3REF: Memory Allocation Subsystem
drhd84f9462007-08-15 11:28:56 +00001042**
1043** The SQLite core uses these three routines for all of its own
1044** internal memory allocation needs. The default implementation
1045** of the memory allocation subsystem uses the malloc(), realloc()
1046** and free() provided by the standard C library. However, if
1047** SQLite is compiled with the following C preprocessor macro
1048**
drh90f6a5b2007-08-15 13:04:54 +00001049** <blockquote> SQLITE_OMIT_MEMORY_ALLOCATION </blockquote>
drhd84f9462007-08-15 11:28:56 +00001050**
1051** then no implementation is provided for these routines by
1052** SQLite. The application that links against SQLite is
1053** expected to provide its own implementation.
drh28dd4792006-06-26 21:35:44 +00001054*/
drh90f6a5b2007-08-15 13:04:54 +00001055void *sqlite3_malloc(unsigned int);
1056void *sqlite3_realloc(void*, unsigned int);
drh28dd4792006-06-26 21:35:44 +00001057void sqlite3_free(void*);
1058
drh5191b7e2002-03-08 02:12:00 +00001059/*
drhd84f9462007-08-15 11:28:56 +00001060** CAPI3REF: Memory Allocator Statistics
1061**
1062** In addition to the basic three allocation routines
1063** [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()],
1064** the memory allocation subsystem included with the SQLite
1065** sources provides the interfaces shown below.
1066**
1067** The first of these two routines returns the amount of memory
1068** currently outstanding (malloced but not freed). The second
1069** returns the largest instantaneous amount of outstanding
1070** memory. The highwater mark is reset if the argument is
1071** true. The SQLite core does not use either of these routines
1072** and so they do not have to be implemented by the application
1073** if SQLITE_OMIT_MEMORY_ALLOCATION is defined. These routines
1074** are provided by the default memory subsystem for diagnostic
1075** purposes.
1076*/
1077sqlite3_uint64 sqlite3_memory_used(void);
1078sqlite3_uint64 sqlite3_memory_highwater(int resetFlag);
1079
1080/*
1081** CAPI3REF: Memory Allocation Alarms
1082**
1083** The [sqlite3_memory_alarm] routine is used to register
1084** a callback on memory allocation events.
1085**
1086** This routine registers or clears a callbacks that fires when
1087** the amount of memory allocated exceeds iThreshold. Only
1088** a single callback can be registered at a time. Each call
1089** to [sqlite3_memory_alarm()] overwrites the previous callback.
1090** The callback is disabled by setting xCallback to a NULL
1091** pointer.
1092**
1093** The parameters to the callback are the pArg value, the
1094** amount of memory currently in use, and the size of the
1095** allocation that provoked the callback. The callback will
1096** presumably invoke [sqlite3_free()] to free up memory space.
1097** The callback may invoke [sqlite3_malloc()] or [sqlite3_realloc()]
1098** but if it does, no additional callbacks will be invoked by
1099** the recursive calls.
1100**
1101** The [sqlite3_soft_heap_limit()] interface works by registering
1102** a memory alarm at the soft heap limit and invoking
1103** [sqlite3_release_memory()] in the alarm callback. Application
1104** programs should not attempt to use the [sqlite3_memory_alarm()]
1105** interface because doing so will interfere with the
1106** [sqlite3_soft_heap_limit()] module.
1107*/
1108int sqlite3_memory_alarm(
1109 void(*xCallback)(void *pArg, sqlite3_uint64 used, unsigned int N),
1110 void *pArg,
1111 sqlite3_uint64 iThreshold
1112);
1113
1114
1115/*
drh6ed48bf2007-06-14 20:57:18 +00001116** CAPI3REF: Compile-Time Authorization Callbacks
1117***
1118** This routine registers a authorizer callback with the SQLite library.
1119** The authorizer callback is invoked as SQL statements are being compiled
1120** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()],
1121** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()]. At various
1122** points during the compilation process, as logic is being created
1123** to perform various actions, the authorizer callback is invoked to
1124** see if those actions are allowed. The authorizer callback should
1125** return SQLITE_OK to allow the action, [SQLITE_IGNORE] to disallow the
1126** specific action but allow the SQL statement to continue to be
1127** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be
1128** rejected with an error.
1129**
1130** Depending on the action, the [SQLITE_IGNORE] and [SQLITE_DENY] return
1131** codes might mean something different or they might mean the same
1132** thing. If the action is, for example, to perform a delete opertion,
1133** then [SQLITE_IGNORE] and [SQLITE_DENY] both cause the statement compilation
1134** to fail with an error. But if the action is to read a specific column
1135** from a specific table, then [SQLITE_DENY] will cause the entire
1136** statement to fail but [SQLITE_IGNORE] will cause a NULL value to be
1137** read instead of the actual column value.
1138**
1139** The first parameter to the authorizer callback is a copy of
1140** the third parameter to the sqlite3_set_authorizer() interface.
1141** The second parameter to the callback is an integer
1142** [SQLITE_COPY | action code] that specifies the particular action
1143** to be authorized. The available action codes are
1144** [SQLITE_COPY | documented separately]. The third through sixth
1145** parameters to the callback are strings that contain additional
1146** details about the action to be authorized.
1147**
1148** An authorizer is used when preparing SQL statements from an untrusted
1149** source, to ensure that the SQL statements do not try to access data
1150** that they are not allowed to see, or that they do not try to
1151** execute malicious statements that damage the database. For
1152** example, an application may allow a user to enter arbitrary
1153** SQL queries for evaluation by a database. But the application does
1154** not want the user to be able to make arbitrary changes to the
1155** database. An authorizer could then be put in place while the
1156** user-entered SQL is being prepared that disallows everything
1157** except SELECT statements.
1158**
1159** Only a single authorizer can be in place on a database connection
1160** at a time. Each call to sqlite3_set_authorizer overrides the
1161** previous call. A NULL authorizer means that no authorization
1162** callback is invoked. The default authorizer is NULL.
1163**
1164** Note that the authorizer callback is invoked only during
1165** [sqlite3_prepare()] or its variants. Authorization is not
1166** performed during statement evaluation in [sqlite3_step()].
drhed6c8672003-01-12 18:02:16 +00001167*/
danielk19776f8a5032004-05-10 10:34:51 +00001168int sqlite3_set_authorizer(
danielk1977f9d64d22004-06-19 08:18:07 +00001169 sqlite3*,
drhe22a3342003-04-22 20:30:37 +00001170 int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
drhe5f9c642003-01-13 23:27:31 +00001171 void *pUserData
drhed6c8672003-01-12 18:02:16 +00001172);
1173
1174/*
drh6ed48bf2007-06-14 20:57:18 +00001175** CAPI3REF: Authorizer Return Codes
1176**
1177** The [sqlite3_set_authorizer | authorizer callback function] must
1178** return either [SQLITE_OK] or one of these two constants in order
1179** to signal SQLite whether or not the action is permitted. See the
1180** [sqlite3_set_authorizer | authorizer documentation] for additional
1181** information.
1182*/
1183#define SQLITE_DENY 1 /* Abort the SQL statement with an error */
1184#define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */
1185
1186/*
1187** CAPI3REF: Authorizer Action Codes
1188**
1189** The [sqlite3_set_authorizer()] interface registers a callback function
1190** that is invoked to authorizer certain SQL statement actions. The
1191** second parameter to the callback is an integer code that specifies
1192** what action is being authorized. These are the integer action codes that
1193** the authorizer callback may be passed.
1194**
1195** These action code values signify what kind of operation is to be
1196** authorized. The 3rd and 4th parameters to the authorization callback
1197** function will be parameters or NULL depending on which of these
1198** codes is used as the second parameter. The 5th parameter to the
1199** authorizer callback is the name of the database ("main", "temp",
1200** etc.) if applicable. The 6th parameter to the authorizer callback
drh5cf590c2003-04-24 01:45:04 +00001201** is the name of the inner-most trigger or view that is responsible for
1202** the access attempt or NULL if this access attempt is directly from
drh6ed48bf2007-06-14 20:57:18 +00001203** top-level SQL code.
drhed6c8672003-01-12 18:02:16 +00001204*/
drh6ed48bf2007-06-14 20:57:18 +00001205/******************************************* 3rd ************ 4th ***********/
drhe5f9c642003-01-13 23:27:31 +00001206#define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */
1207#define SQLITE_CREATE_TABLE 2 /* Table Name NULL */
1208#define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */
1209#define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */
drh77ad4e42003-01-14 02:49:27 +00001210#define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */
drhe5f9c642003-01-13 23:27:31 +00001211#define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */
drh77ad4e42003-01-14 02:49:27 +00001212#define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */
drhe5f9c642003-01-13 23:27:31 +00001213#define SQLITE_CREATE_VIEW 8 /* View Name NULL */
1214#define SQLITE_DELETE 9 /* Table Name NULL */
drh77ad4e42003-01-14 02:49:27 +00001215#define SQLITE_DROP_INDEX 10 /* Index Name Table Name */
drhe5f9c642003-01-13 23:27:31 +00001216#define SQLITE_DROP_TABLE 11 /* Table Name NULL */
drh77ad4e42003-01-14 02:49:27 +00001217#define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */
drhe5f9c642003-01-13 23:27:31 +00001218#define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */
drh77ad4e42003-01-14 02:49:27 +00001219#define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */
drhe5f9c642003-01-13 23:27:31 +00001220#define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */
drh77ad4e42003-01-14 02:49:27 +00001221#define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */
drhe5f9c642003-01-13 23:27:31 +00001222#define SQLITE_DROP_VIEW 17 /* View Name NULL */
1223#define SQLITE_INSERT 18 /* Table Name NULL */
1224#define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */
1225#define SQLITE_READ 20 /* Table Name Column Name */
1226#define SQLITE_SELECT 21 /* NULL NULL */
1227#define SQLITE_TRANSACTION 22 /* NULL NULL */
1228#define SQLITE_UPDATE 23 /* Table Name Column Name */
drh81e293b2003-06-06 19:00:42 +00001229#define SQLITE_ATTACH 24 /* Filename NULL */
1230#define SQLITE_DETACH 25 /* Database Name NULL */
danielk19771c8c23c2004-11-12 15:53:37 +00001231#define SQLITE_ALTER_TABLE 26 /* Database Name Table Name */
danielk19771d54df82004-11-23 15:41:16 +00001232#define SQLITE_REINDEX 27 /* Index Name NULL */
drhe6e04962005-07-23 02:17:03 +00001233#define SQLITE_ANALYZE 28 /* Table Name NULL */
danielk1977f1a381e2006-06-16 08:01:02 +00001234#define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */
1235#define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */
drh5169bbc2006-08-24 14:59:45 +00001236#define SQLITE_FUNCTION 31 /* Function Name NULL */
drh6ed48bf2007-06-14 20:57:18 +00001237#define SQLITE_COPY 0 /* No longer used */
drhed6c8672003-01-12 18:02:16 +00001238
1239/*
drh6ed48bf2007-06-14 20:57:18 +00001240** CAPI3REF: Tracing And Profiling Functions
1241**
1242** These routines register callback functions that can be used for
1243** tracing and profiling the execution of SQL statements.
1244** The callback function registered by sqlite3_trace() is invoked
1245** at the first [sqlite3_step()] for the evaluation of an SQL statement.
1246** The callback function registered by sqlite3_profile() is invoked
1247** as each SQL statement finishes and includes
drh19e2d372005-08-29 23:00:03 +00001248** information on how long that statement ran.
1249**
1250** The sqlite3_profile() API is currently considered experimental and
1251** is subject to change.
drh18de4822003-01-16 16:28:53 +00001252*/
danielk1977f9d64d22004-06-19 08:18:07 +00001253void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
drh19e2d372005-08-29 23:00:03 +00001254void *sqlite3_profile(sqlite3*,
drh6d2069d2007-08-14 01:58:53 +00001255 void(*xProfile)(void*,const char*,sqlite3_uint64), void*);
drh18de4822003-01-16 16:28:53 +00001256
danielk1977348bb5d2003-10-18 09:37:26 +00001257/*
drh6ed48bf2007-06-14 20:57:18 +00001258** CAPI3REF: Query Progress Callbacks
1259**
danielk1977348bb5d2003-10-18 09:37:26 +00001260** This routine configures a callback function - the progress callback - that
drh6ed48bf2007-06-14 20:57:18 +00001261** is invoked periodically during long running calls to [sqlite3_exec()],
1262** [sqlite3_step()] and [sqlite3_get_table()]. An example use for this
1263** interface is to keep a GUI updated during a large query.
danielk1977348bb5d2003-10-18 09:37:26 +00001264**
1265** The progress callback is invoked once for every N virtual machine opcodes,
1266** where N is the second argument to this function. The progress callback
1267** itself is identified by the third argument to this function. The fourth
1268** argument to this function is a void pointer passed to the progress callback
1269** function each time it is invoked.
1270**
drh6ed48bf2007-06-14 20:57:18 +00001271** If a call to [sqlite3_exec()], [sqlite3_step()], or [sqlite3_get_table()]
1272** results in fewer than N opcodes being executed, then the progress
1273** callback is never invoked.
danielk1977348bb5d2003-10-18 09:37:26 +00001274**
drh6ed48bf2007-06-14 20:57:18 +00001275** Only a single progress callback function may be registered for each
1276** open database connection. Every call to sqlite3_progress_handler()
1277** overwrites the results of the previous call.
danielk1977348bb5d2003-10-18 09:37:26 +00001278** To remove the progress callback altogether, pass NULL as the third
1279** argument to this function.
1280**
1281** If the progress callback returns a result other than 0, then the current
drh6ed48bf2007-06-14 20:57:18 +00001282** query is immediately terminated and any database changes rolled back.
1283** The containing [sqlite3_exec()], [sqlite3_step()], or
1284** [sqlite3_get_table()] call returns SQLITE_INTERRUPT. This feature
1285** can be used, for example, to implement the "Cancel" button on a
1286** progress dialog box in a GUI.
danielk1977348bb5d2003-10-18 09:37:26 +00001287*/
danielk1977f9d64d22004-06-19 08:18:07 +00001288void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
danielk1977348bb5d2003-10-18 09:37:26 +00001289
drhaa940ea2004-01-15 02:44:03 +00001290/*
drh6ed48bf2007-06-14 20:57:18 +00001291** CAPI3REF: Opening A New Database Connection
drhaa940ea2004-01-15 02:44:03 +00001292**
drh4f26d6c2004-05-26 23:25:30 +00001293** Open the sqlite database file "filename". The "filename" is UTF-8
1294** encoded for sqlite3_open() and UTF-16 encoded in the native byte order
drh6ed48bf2007-06-14 20:57:18 +00001295** for sqlite3_open16(). An [sqlite3*] handle is returned in *ppDb, even
drh4f26d6c2004-05-26 23:25:30 +00001296** if an error occurs. If the database is opened (or created) successfully,
drh6d2069d2007-08-14 01:58:53 +00001297** then [SQLITE_OK] is returned. Otherwise an error code is returned. The
1298** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain
drh4f26d6c2004-05-26 23:25:30 +00001299** an English language description of the error.
drh22fbcb82004-02-01 01:22:50 +00001300**
drh6ed48bf2007-06-14 20:57:18 +00001301** If the database file does not exist, then a new database will be created
1302** as needed. The default encoding for the database will be UTF-8 if
1303** sqlite3_open() is called and UTF-16 if sqlite3_open16 is used.
danielk197765904932004-05-26 06:18:37 +00001304**
1305** Whether or not an error occurs when it is opened, resources associated
drh6ed48bf2007-06-14 20:57:18 +00001306** with the [sqlite3*] handle should be released by passing it to
drh6d2069d2007-08-14 01:58:53 +00001307** [sqlite3_close()] when it is no longer required.
1308**
1309** The sqlite3_open_v2() interface works like sqlite3_open() except that
1310** provides two additional parameters for additional control over the
1311** new database connection. The flags parameter can be one of:
1312**
1313** <ol>
1314** <li> [SQLITE_OPEN_READONLY]
1315** <li> [SQLITE_OPEN_READWRITE]
1316** <li> [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]
1317** </ol>
1318**
1319** The first value opens the database read-only. If the database does
1320** not previously exist, an error is returned. The second option opens
1321** the database for reading and writing but the database must already
1322** exist or an error is returned. The third option opens the database
1323** for reading and writing and creates it if it does not already exist.
1324** The third options is behavior that is used always for sqlite3_open()
1325** and sqlite3_open16().
1326**
drhd84f9462007-08-15 11:28:56 +00001327** The fourth parameter to sqlite3_open_v2() is the name of the
1328** [sqlite3_vfs] object that defines the operating system
drh6d2069d2007-08-14 01:58:53 +00001329** interface that the new database connection should use. If the
1330** fourth parameter is a NULL pointer then a default suitable for
1331** the host environment is substituted.
drh6ed48bf2007-06-14 20:57:18 +00001332**
1333** Note to windows users: The encoding used for the filename argument
1334** of sqlite3_open() must be UTF-8, not whatever codepage is currently
1335** defined. Filenames containing international characters must be converted
1336** to UTF-8 prior to passing them into sqlite3_open().
danielk197765904932004-05-26 06:18:37 +00001337*/
1338int sqlite3_open(
1339 const char *filename, /* Database filename (UTF-8) */
danielk19774f057f92004-06-08 00:02:33 +00001340 sqlite3 **ppDb /* OUT: SQLite db handle */
danielk197765904932004-05-26 06:18:37 +00001341);
danielk197765904932004-05-26 06:18:37 +00001342int sqlite3_open16(
1343 const void *filename, /* Database filename (UTF-16) */
danielk19774f057f92004-06-08 00:02:33 +00001344 sqlite3 **ppDb /* OUT: SQLite db handle */
danielk197765904932004-05-26 06:18:37 +00001345);
drh6d2069d2007-08-14 01:58:53 +00001346int sqlite3_open_v2(
1347 const void *filename, /* Database filename (UTF-16) */
1348 sqlite3 **ppDb, /* OUT: SQLite db handle */
1349 int flags, /* Flags */
drhd84f9462007-08-15 11:28:56 +00001350 const char *zVfs /* Name of VFS module to use */
drh6d2069d2007-08-14 01:58:53 +00001351);
danielk1977295ba552004-05-19 10:34:51 +00001352
danielk197765904932004-05-26 06:18:37 +00001353/*
drh6ed48bf2007-06-14 20:57:18 +00001354** CAPI3REF: Error Codes And Messages
1355**
1356** The sqlite3_errcode() interface returns the numeric
1357** [SQLITE_OK | result code] or [SQLITE_IOERR_READ | extended result code]
1358** for the most recent failed sqlite3_* API call associated
1359** with [sqlite3] handle 'db'. If a prior API call failed but the
1360** most recent API call succeeded, the return value from sqlite3_errcode()
1361** is undefined.
1362**
1363** The sqlite3_errmsg() and sqlite3_errmsg16() return English-langauge
1364** text that describes the error, as either UTF8 or UTF16 respectively.
1365** Memory to hold the error message string is managed internally. The
1366** string may be overwritten or deallocated by subsequent calls to SQLite
1367** interface functions.
danielk197765904932004-05-26 06:18:37 +00001368**
1369** Calls to many sqlite3_* functions set the error code and string returned
drh6ed48bf2007-06-14 20:57:18 +00001370** by [sqlite3_errcode()], [sqlite3_errmsg()], and [sqlite3_errmsg16()]
1371** (overwriting the previous values). Note that calls to [sqlite3_errcode()],
1372** [sqlite3_errmsg()], and [sqlite3_errmsg16()] themselves do not affect the
1373** results of future invocations. Calls to API routines that do not return
1374** an error code (examples: [sqlite3_data_count()] or [sqlite3_mprintf()]) do
1375** not change the error code returned by this routine.
danielk197765904932004-05-26 06:18:37 +00001376**
1377** Assuming no other intervening sqlite3_* API calls are made, the error
1378** code returned by this function is associated with the same error as
drh6ed48bf2007-06-14 20:57:18 +00001379** the strings returned by [sqlite3_errmsg()] and [sqlite3_errmsg16()].
danielk197765904932004-05-26 06:18:37 +00001380*/
1381int sqlite3_errcode(sqlite3 *db);
danielk197765904932004-05-26 06:18:37 +00001382const char *sqlite3_errmsg(sqlite3*);
danielk197765904932004-05-26 06:18:37 +00001383const void *sqlite3_errmsg16(sqlite3*);
1384
1385/*
drh6ed48bf2007-06-14 20:57:18 +00001386** CAPI3REF: SQL Statement Object
1387**
1388** Instance of this object represent single SQL statements. This
1389** is variously known as a "prepared statement" or a
1390** "compiled SQL statement" or simply as a "statement".
1391**
1392** The life of a statement object goes something like this:
1393**
1394** <ol>
1395** <li> Create the object using [sqlite3_prepare_v2()] or a related
1396** function.
1397** <li> Bind values to host parameters using
1398** [sqlite3_bind_blob | sqlite3_bind_* interfaces].
1399** <li> Run the SQL by calling [sqlite3_step()] one or more times.
1400** <li> Reset the statement using [sqlite3_reset()] then go back
1401** to step 2. Do this zero or more times.
1402** <li> Destroy the object using [sqlite3_finalize()].
1403** </ol>
1404**
1405** Refer to documentation on individual methods above for additional
1406** information.
danielk197765904932004-05-26 06:18:37 +00001407*/
danielk1977fc57d7b2004-05-26 02:04:57 +00001408typedef struct sqlite3_stmt sqlite3_stmt;
1409
danielk1977e3209e42004-05-20 01:40:18 +00001410/*
drh6ed48bf2007-06-14 20:57:18 +00001411** CAPI3REF: Compiling An SQL Statement
danielk197765904932004-05-26 06:18:37 +00001412**
drh6ed48bf2007-06-14 20:57:18 +00001413** To execute an SQL query, it must first be compiled into a byte-code
1414** program using one of these routines.
1415**
1416** The first argument "db" is an [sqlite3 | SQLite database handle]
1417** obtained from a prior call to [sqlite3_open()] or [sqlite3_open16()].
1418** The second argument "zSql" is the statement to be compiled, encoded
1419** as either UTF-8 or UTF-16. The sqlite3_prepare() and sqlite3_prepare_v2()
1420** interfaces uses UTF-8 and sqlite3_prepare16() and sqlite3_prepare16_v2()
drh21f06722007-07-19 12:41:39 +00001421** use UTF-16.
1422**
1423** If the nByte argument is less
drh6ed48bf2007-06-14 20:57:18 +00001424** than zero, then zSql is read up to the first zero terminator. If
drh21f06722007-07-19 12:41:39 +00001425** nByte is non-negative, then it is the maximum number of
1426** bytes read from zSql. When nByte is non-negative, the
1427** zSql string ends at either the first '\000' character or
1428** until the nByte-th byte, whichever comes first.
danielk197765904932004-05-26 06:18:37 +00001429**
1430** *pzTail is made to point to the first byte past the end of the first
1431** SQL statement in zSql. This routine only compiles the first statement
1432** in zSql, so *pzTail is left pointing to what remains uncompiled.
1433**
drh6ed48bf2007-06-14 20:57:18 +00001434** *ppStmt is left pointing to a compiled
1435** [sqlite3_stmt | SQL statement structure] that can be
1436** executed using [sqlite3_step()]. Or if there is an error, *ppStmt may be
danielk197765904932004-05-26 06:18:37 +00001437** set to NULL. If the input text contained no SQL (if the input is and
drh6ed48bf2007-06-14 20:57:18 +00001438** empty string or a comment) then *ppStmt is set to NULL. The calling
1439** procedure is responsible for deleting the compiled SQL statement
1440** using [sqlite3_finalize()] after it has finished with it.
danielk197765904932004-05-26 06:18:37 +00001441**
drh6ed48bf2007-06-14 20:57:18 +00001442** On success, [SQLITE_OK] is returned. Otherwise an
1443** [SQLITE_ERROR | error code] is returned.
1444**
1445** The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are
1446** recommended for all new programs. The two older interfaces are retained
1447** for backwards compatibility, but their use is discouraged.
1448** In the "v2" interfaces, the prepared statement
1449** that is returned (the [sqlite3_stmt] object) contains a copy of the
1450** original SQL text. This causes the [sqlite3_step()] interface to
1451** behave a differently in two ways:
1452**
1453** <ol>
1454** <li>
1455** If the database schema changes, instead of returning [SQLITE_SCHEMA] as it
1456** always used to do, [sqlite3_step()] will automatically recompile the SQL
1457** statement and try to run it again. If the schema has changed in a way
1458** that makes the statement no longer valid, [sqlite3_step()] will still
1459** return [SQLITE_SCHEMA]. But unlike the legacy behavior, [SQLITE_SCHEMA] is
1460** now a fatal error. Calling [sqlite3_prepare_v2()] again will not make the
1461** error go away. Note: use [sqlite3_errmsg()] to find the text of the parsing
1462** error that results in an [SQLITE_SCHEMA] return.
1463** </li>
1464**
1465** <li>
1466** When an error occurs,
1467** [sqlite3_step()] will return one of the detailed
1468** [SQLITE_ERROR | result codes] or
1469** [SQLITE_IOERR_READ | extended result codes] such as directly.
1470** The legacy behavior was that [sqlite3_step()] would only return a generic
1471** [SQLITE_ERROR] result code and you would have to make a second call to
1472** [sqlite3_reset()] in order to find the underlying cause of the problem.
1473** With the "v2" prepare interfaces, the underlying reason for the error is
1474** returned immediately.
1475** </li>
1476** </ol>
danielk197765904932004-05-26 06:18:37 +00001477*/
1478int sqlite3_prepare(
1479 sqlite3 *db, /* Database handle */
1480 const char *zSql, /* SQL statement, UTF-8 encoded */
drh21f06722007-07-19 12:41:39 +00001481 int nByte, /* Maximum length of zSql in bytes. */
danielk197765904932004-05-26 06:18:37 +00001482 sqlite3_stmt **ppStmt, /* OUT: Statement handle */
1483 const char **pzTail /* OUT: Pointer to unused portion of zSql */
1484);
drh6ed48bf2007-06-14 20:57:18 +00001485int sqlite3_prepare_v2(
1486 sqlite3 *db, /* Database handle */
1487 const char *zSql, /* SQL statement, UTF-8 encoded */
drh21f06722007-07-19 12:41:39 +00001488 int nByte, /* Maximum length of zSql in bytes. */
drh6ed48bf2007-06-14 20:57:18 +00001489 sqlite3_stmt **ppStmt, /* OUT: Statement handle */
1490 const char **pzTail /* OUT: Pointer to unused portion of zSql */
1491);
danielk197765904932004-05-26 06:18:37 +00001492int sqlite3_prepare16(
1493 sqlite3 *db, /* Database handle */
1494 const void *zSql, /* SQL statement, UTF-16 encoded */
drh21f06722007-07-19 12:41:39 +00001495 int nByte, /* Maximum length of zSql in bytes. */
danielk197765904932004-05-26 06:18:37 +00001496 sqlite3_stmt **ppStmt, /* OUT: Statement handle */
1497 const void **pzTail /* OUT: Pointer to unused portion of zSql */
1498);
drhb900aaf2006-11-09 00:24:53 +00001499int sqlite3_prepare16_v2(
1500 sqlite3 *db, /* Database handle */
1501 const void *zSql, /* SQL statement, UTF-16 encoded */
drh21f06722007-07-19 12:41:39 +00001502 int nByte, /* Maximum length of zSql in bytes. */
drhb900aaf2006-11-09 00:24:53 +00001503 sqlite3_stmt **ppStmt, /* OUT: Statement handle */
1504 const void **pzTail /* OUT: Pointer to unused portion of zSql */
1505);
1506
1507/*
drh6ed48bf2007-06-14 20:57:18 +00001508** CAPI3REF: Dynamically Typed Value Object
1509**
1510** SQLite uses dynamic typing for the values it stores. Values can
1511** be integers, floating point values, strings, BLOBs, or NULL. When
1512** passing around values internally, each value is represented as
1513** an instance of the sqlite3_value object.
drhf4479502004-05-27 03:12:53 +00001514*/
drhf4479502004-05-27 03:12:53 +00001515typedef struct Mem sqlite3_value;
1516
1517/*
drh6ed48bf2007-06-14 20:57:18 +00001518** CAPI3REF: SQL Function Context Object
drh4f26d6c2004-05-26 23:25:30 +00001519**
drh6ed48bf2007-06-14 20:57:18 +00001520** The context in which an SQL function executes is stored in an
1521** sqlite3_context object. A pointer to such an object is the
1522** first parameter to user-defined SQL functions.
1523*/
1524typedef struct sqlite3_context sqlite3_context;
1525
1526/*
1527** CAPI3REF: Binding Values To Prepared Statements
1528**
1529** In the SQL strings input to [sqlite3_prepare_v2()] and its variants,
1530** one or more literals can be replace by a parameter in one of these
1531** forms:
1532**
1533** <ul>
1534** <li> ?
1535** <li> ?NNN
1536** <li> :AAA
1537** <li> @AAA
1538** <li> $VVV
1539** </ul>
1540**
1541** In the parameter forms shown above NNN is an integer literal,
1542** AAA is an alphanumeric identifier and VVV is a variable name according
1543** to the syntax rules of the TCL programming language.
1544** The values of these parameters (also called "host parameter names")
1545** can be set using the sqlite3_bind_*() routines defined here.
1546**
1547** The first argument to the sqlite3_bind_*() routines always is a pointer
1548** to the [sqlite3_stmt] object returned from [sqlite3_prepare_v2()] or
1549** its variants. The second
1550** argument is the index of the parameter to be set. The first parameter has
1551** an index of 1. When the same named parameter is used more than once, second
1552** and subsequent
1553** occurrences have the same index as the first occurrence. The index for
1554** named parameters can be looked up using the
1555** [sqlite3_bind_parameter_name()] API if desired. The index for "?NNN"
1556** parametes is the value of NNN.
1557** The NNN value must be between 1 and the compile-time
1558** parameter SQLITE_MAX_VARIABLE_NUMBER (default value: 999).
1559** See <a href="limits.html">limits.html</a> for additional information.
1560**
1561** The third argument is the value to bind to the parameter.
1562**
1563** In those
1564** routines that have a fourth argument, its value is the number of bytes
1565** in the parameter. To be clear: the value is the number of bytes in the
1566** string, not the number of characters. The number
1567** of bytes does not include the zero-terminator at the end of strings.
1568** If the fourth parameter is negative, the length of the string is
1569** number of bytes up to the first zero terminator.
drh4f26d6c2004-05-26 23:25:30 +00001570**
drh930cc582007-03-28 13:07:40 +00001571** The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and
drh900dfba2004-07-21 15:21:36 +00001572** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or
1573** text after SQLite has finished with it. If the fifth argument is the
drh6ed48bf2007-06-14 20:57:18 +00001574** special value [SQLITE_STATIC], then the library assumes that the information
drh900dfba2004-07-21 15:21:36 +00001575** is in static, unmanaged space and does not need to be freed. If the
drh6ed48bf2007-06-14 20:57:18 +00001576** fifth argument has the value [SQLITE_TRANSIENT], then SQLite makes its
1577** own private copy of the data immediately, before the sqlite3_bind_*()
1578** routine returns.
drh4f26d6c2004-05-26 23:25:30 +00001579**
drh6ed48bf2007-06-14 20:57:18 +00001580** The sqlite3_bind_zeroblob() routine binds a BLOB of length n that
1581** is filled with zeros. A zeroblob uses a fixed amount of memory
1582** (just an integer to hold it size) while it is being processed.
1583** Zeroblobs are intended to serve as place-holders for BLOBs whose
1584** content is later written using
1585** [sqlite3_blob_open | increment BLOB I/O] routines.
1586**
1587** The sqlite3_bind_*() routines must be called after
1588** [sqlite3_prepare_v2()] (and its variants) or [sqlite3_reset()] and
1589** before [sqlite3_step()].
1590** Bindings are not cleared by the [sqlite3_reset()] routine.
1591** Unbound parameters are interpreted as NULL.
1592**
1593** These routines return [SQLITE_OK] on success or an error code if
1594** anything goes wrong. [SQLITE_RANGE] is returned if the parameter
1595** index is out of range. [SQLITE_NOMEM] is returned if malloc fails.
1596** [SQLITE_MISUSE] is returned if these routines are called on a virtual
1597** machine that is the wrong state or which has already been finalized.
drh4f26d6c2004-05-26 23:25:30 +00001598*/
danielk1977d8123362004-06-12 09:25:12 +00001599int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
drhf4479502004-05-27 03:12:53 +00001600int sqlite3_bind_double(sqlite3_stmt*, int, double);
1601int sqlite3_bind_int(sqlite3_stmt*, int, int);
drh6d2069d2007-08-14 01:58:53 +00001602int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
drhf4479502004-05-27 03:12:53 +00001603int sqlite3_bind_null(sqlite3_stmt*, int);
danielk1977d8123362004-06-12 09:25:12 +00001604int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
1605int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
drhf4479502004-05-27 03:12:53 +00001606int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
drhb026e052007-05-02 01:34:31 +00001607int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
drh4f26d6c2004-05-26 23:25:30 +00001608
1609/*
drh6ed48bf2007-06-14 20:57:18 +00001610** CAPI3REF: Number Of Host Parameters
1611**
1612** Return the largest host parameter index in the precompiled statement given
1613** as the argument. When the host parameters are of the forms like ":AAA"
1614** or "?", then they are assigned sequential increasing numbers beginning
1615** with one, so the value returned is the number of parameters. However
1616** if the same host parameter name is used multiple times, each occurrance
1617** is given the same number, so the value returned in that case is the number
1618** of unique host parameter names. If host parameters of the form "?NNN"
1619** are used (where NNN is an integer) then there might be gaps in the
1620** numbering and the value returned by this interface is the index of the
1621** host parameter with the largest index value.
drh605264d2007-08-21 15:13:19 +00001622**
1623** The prepared statement must not not be [sqlite3_finalize | finalized]
1624** prior to this routine returnning. Otherwise the results are undefined
1625** and probably undesirable.
drh75f6a032004-07-15 14:15:00 +00001626*/
1627int sqlite3_bind_parameter_count(sqlite3_stmt*);
1628
1629/*
drh6ed48bf2007-06-14 20:57:18 +00001630** CAPI3REF: Name Of A Host Parameter
1631**
1632** This routine returns a pointer to the name of the n-th parameter in a
1633** [sqlite3_stmt | prepared statement].
1634** Host parameters of the form ":AAA" or "@AAA" or "$VVV" have a name
1635** which is the string ":AAA" or "@AAA" or "$VVV".
1636** In other words, the initial ":" or "$" or "@"
1637** is included as part of the name.
1638** Parameters of the form "?" or "?NNN" have no name.
1639**
1640** The first bound parameter has an index of 1, not 0.
1641**
1642** If the value n is out of range or if the n-th parameter is nameless,
1643** then NULL is returned. The returned string is always in the
1644** UTF-8 encoding even if the named parameter was originally specified
1645** as UTF-16 in [sqlite3_prepare16()] or [sqlite3_prepare16_v2()].
drh895d7472004-08-20 16:02:39 +00001646*/
1647const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
1648
1649/*
drh6ed48bf2007-06-14 20:57:18 +00001650** CAPI3REF: Index Of A Parameter With A Given Name
1651**
1652** This routine returns the index of a host parameter with the given name.
1653** The name must match exactly. If no parameter with the given name is
1654** found, return 0. Parameter names must be UTF8.
drhfa6bc002004-09-07 16:19:52 +00001655*/
1656int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
1657
1658/*
drh6ed48bf2007-06-14 20:57:18 +00001659** CAPI3REF: Reset All Bindings On A Prepared Statement
1660**
1661** Contrary to the intuition of many, [sqlite3_reset()] does not
1662** reset the [sqlite3_bind_blob | bindings] on a
1663** [sqlite3_stmt | prepared statement]. Use this routine to
1664** reset all host parameters to NULL.
danielk1977600dd0b2005-01-20 01:14:23 +00001665*/
1666int sqlite3_clear_bindings(sqlite3_stmt*);
1667
1668/*
drh6ed48bf2007-06-14 20:57:18 +00001669** CAPI3REF: Number Of Columns In A Result Set
1670**
1671** Return the number of columns in the result set returned by the
1672** [sqlite3_stmt | compiled SQL statement]. This routine returns 0
1673** if pStmt is an SQL statement that does not return data (for
1674** example an UPDATE).
danielk197765904932004-05-26 06:18:37 +00001675*/
1676int sqlite3_column_count(sqlite3_stmt *pStmt);
1677
1678/*
drh6ed48bf2007-06-14 20:57:18 +00001679** CAPI3REF: Column Names In A Result Set
1680**
1681** These routines return the name assigned to a particular column
1682** in the result set of a SELECT statement. The sqlite3_column_name()
1683** interface returns a pointer to a UTF8 string and sqlite3_column_name16()
1684** returns a pointer to a UTF16 string. The first parameter is the
drh6d2069d2007-08-14 01:58:53 +00001685** [sqlite3_stmt | prepared statement] that implements the SELECT statement.
drh6ed48bf2007-06-14 20:57:18 +00001686** The second parameter is the column number. The left-most column is
1687** number 0.
1688**
1689** The returned string pointer is valid until either the
drh6d2069d2007-08-14 01:58:53 +00001690** [sqlite3_stmt | prepared statement] is destroyed by [sqlite3_finalize()]
drh6ed48bf2007-06-14 20:57:18 +00001691** or until the next call sqlite3_column_name() or sqlite3_column_name16()
1692** on the same column.
danielk197765904932004-05-26 06:18:37 +00001693*/
drh6ed48bf2007-06-14 20:57:18 +00001694const char *sqlite3_column_name(sqlite3_stmt*, int N);
1695const void *sqlite3_column_name16(sqlite3_stmt*, int N);
danielk197765904932004-05-26 06:18:37 +00001696
1697/*
drh6ed48bf2007-06-14 20:57:18 +00001698** CAPI3REF: Source Of Data In A Query Result
1699**
1700** These routines provide a means to determine what column of what
1701** table in which database a result of a SELECT statement comes from.
1702** The name of the database or table or column can be returned as
drhbf2564f2007-06-21 15:25:05 +00001703** either a UTF8 or UTF16 string. The _database_ routines return
1704** the database name, the _table_ routines return the table name, and
1705** the origin_ routines return the column name.
1706** The returned string is valid until
drh6ed48bf2007-06-14 20:57:18 +00001707** the [sqlite3_stmt | prepared statement] is destroyed using
1708** [sqlite3_finalize()] or until the same information is requested
drhbf2564f2007-06-21 15:25:05 +00001709** again in a different encoding.
1710**
1711** The names returned are the original un-aliased names of the
1712** database, table, and column.
drh6ed48bf2007-06-14 20:57:18 +00001713**
1714** The first argument to the following calls is a
1715** [sqlite3_stmt | compiled SQL statement].
danielk1977955de522006-02-10 02:27:42 +00001716** These functions return information about the Nth column returned by
1717** the statement, where N is the second function argument.
1718**
drh6ed48bf2007-06-14 20:57:18 +00001719** If the Nth column returned by the statement is an expression
1720** or subquery and is not a column value, then all of these functions
1721** return NULL. Otherwise, they return the
1722** name of the attached database, table and column that query result
1723** column was extracted from.
danielk1977955de522006-02-10 02:27:42 +00001724**
1725** As with all other SQLite APIs, those postfixed with "16" return UTF-16
drh6ed48bf2007-06-14 20:57:18 +00001726** encoded strings, the other functions return UTF-8.
danielk19774b1ae992006-02-10 03:06:10 +00001727**
1728** These APIs are only available if the library was compiled with the
1729** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined.
danielk1977955de522006-02-10 02:27:42 +00001730*/
1731const char *sqlite3_column_database_name(sqlite3_stmt*,int);
1732const void *sqlite3_column_database_name16(sqlite3_stmt*,int);
1733const char *sqlite3_column_table_name(sqlite3_stmt*,int);
1734const void *sqlite3_column_table_name16(sqlite3_stmt*,int);
1735const char *sqlite3_column_origin_name(sqlite3_stmt*,int);
1736const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);
1737
1738/*
drh6ed48bf2007-06-14 20:57:18 +00001739** CAPI3REF: Declared Datatype Of A Query Result
1740**
1741** The first parameter is a [sqlite3_stmt | compiled SQL statement].
1742** If this statement is a SELECT statement and the Nth column of the
1743** returned result set of that SELECT is a table column (not an
1744** expression or subquery) then the declared type of the table
1745** column is returned. If the Nth column of the result set is an
1746** expression or subquery, then a NULL pointer is returned.
1747** The returned string is always UTF-8 encoded. For example, in
1748** the database schema:
danielk197765904932004-05-26 06:18:37 +00001749**
1750** CREATE TABLE t1(c1 VARIANT);
1751**
1752** And the following statement compiled:
1753**
danielk1977955de522006-02-10 02:27:42 +00001754** SELECT c1 + 1, c1 FROM t1;
danielk197765904932004-05-26 06:18:37 +00001755**
1756** Then this routine would return the string "VARIANT" for the second
1757** result column (i==1), and a NULL pointer for the first result column
1758** (i==0).
drh6ed48bf2007-06-14 20:57:18 +00001759**
1760** SQLite uses dynamic run-time typing. So just because a column
1761** is declared to contain a particular type does not mean that the
1762** data stored in that column is of the declared type. SQLite is
1763** strongly typed, but the typing is dynamic not static. Type
1764** is associated with individual values, not with the containers
1765** used to hold those values.
danielk197765904932004-05-26 06:18:37 +00001766*/
1767const char *sqlite3_column_decltype(sqlite3_stmt *, int i);
danielk197765904932004-05-26 06:18:37 +00001768const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
1769
danielk1977106bb232004-05-21 10:08:53 +00001770/*
drh6ed48bf2007-06-14 20:57:18 +00001771** CAPI3REF: Evaluate An SQL Statement
danielk1977106bb232004-05-21 10:08:53 +00001772**
drh6ed48bf2007-06-14 20:57:18 +00001773** After an [sqlite3_stmt | SQL statement] has been prepared with a call
1774** to either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or to one of
1775** the legacy interfaces [sqlite3_prepare()] or [sqlite3_prepare16()],
1776** then this function must be called one or more times to evaluate the
1777** statement.
danielk1977106bb232004-05-21 10:08:53 +00001778**
drh6ed48bf2007-06-14 20:57:18 +00001779** The details of the behavior of this sqlite3_step() interface depend
1780** on whether the statement was prepared using the newer "v2" interface
1781** [sqlite3_prepare_v2()] and [sqlite3_prepare16_v2()] or the older legacy
1782** interface [sqlite3_prepare()] and [sqlite3_prepare16()]. The use of the
1783** new "v2" interface is recommended for new applications but the legacy
1784** interface will continue to be supported.
danielk1977106bb232004-05-21 10:08:53 +00001785**
drh6ed48bf2007-06-14 20:57:18 +00001786** In the lagacy interface, the return value will be either [SQLITE_BUSY],
1787** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE].
1788** With the "v2" interface, any of the other [SQLITE_OK | result code]
1789** or [SQLITE_IOERR_READ | extended result code] might be returned as
1790** well.
1791**
1792** [SQLITE_BUSY] means that the database engine was unable to acquire the
1793** database locks it needs to do its job. If the statement is a COMMIT
1794** or occurs outside of an explicit transaction, then you can retry the
1795** statement. If the statement is not a COMMIT and occurs within a
1796** explicit transaction then you should rollback the transaction before
1797** continuing.
1798**
1799** [SQLITE_DONE] means that the statement has finished executing
danielk1977106bb232004-05-21 10:08:53 +00001800** successfully. sqlite3_step() should not be called again on this virtual
drh6ed48bf2007-06-14 20:57:18 +00001801** machine without first calling [sqlite3_reset()] to reset the virtual
1802** machine back to its initial state.
danielk1977106bb232004-05-21 10:08:53 +00001803**
1804** If the SQL statement being executed returns any data, then
drh6ed48bf2007-06-14 20:57:18 +00001805** [SQLITE_ROW] is returned each time a new row of data is ready
danielk1977106bb232004-05-21 10:08:53 +00001806** for processing by the caller. The values may be accessed using
drh6ed48bf2007-06-14 20:57:18 +00001807** the [sqlite3_column_int | column access functions].
1808** sqlite3_step() is called again to retrieve the next row of data.
danielk1977106bb232004-05-21 10:08:53 +00001809**
drh6ed48bf2007-06-14 20:57:18 +00001810** [SQLITE_ERROR] means that a run-time error (such as a constraint
danielk1977106bb232004-05-21 10:08:53 +00001811** violation) has occurred. sqlite3_step() should not be called again on
drh6ed48bf2007-06-14 20:57:18 +00001812** the VM. More information may be found by calling [sqlite3_errmsg()].
1813** With the legacy interface, a more specific error code (example:
1814** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth)
1815** can be obtained by calling [sqlite3_reset()] on the
drh6d2069d2007-08-14 01:58:53 +00001816** [sqlite3_stmt | prepared statement]. In the "v2" interface,
drh6ed48bf2007-06-14 20:57:18 +00001817** the more specific error code is returned directly by sqlite3_step().
danielk1977106bb232004-05-21 10:08:53 +00001818**
drh6ed48bf2007-06-14 20:57:18 +00001819** [SQLITE_MISUSE] means that the this routine was called inappropriately.
drh6d2069d2007-08-14 01:58:53 +00001820** Perhaps it was called on a [sqlite3_stmt | prepared statement] that has
drh6ed48bf2007-06-14 20:57:18 +00001821** already been [sqlite3_finalize | finalized] or on one that had
1822** previously returned [SQLITE_ERROR] or [SQLITE_DONE]. Or it could
1823** be the case that the same database connection is being used by two or
1824** more threads at the same moment in time.
1825**
1826** <b>Goofy Interface Alert:</b>
1827** In the legacy interface,
1828** the sqlite3_step() API always returns a generic error code,
1829** [SQLITE_ERROR], following any error other than [SQLITE_BUSY]
1830** and [SQLITE_MISUSE]. You must call [sqlite3_reset()] or
1831** [sqlite3_finalize()] in order to find one of the specific
1832** [SQLITE_ERROR | result codes] that better describes the error.
1833** We admit that this is a goofy design. The problem has been fixed
1834** with the "v2" interface. If you prepare all of your SQL statements
1835** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead
1836** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()], then the
1837** more specific [SQLITE_ERROR | result codes] are returned directly
1838** by sqlite3_step(). The use of the "v2" interface is recommended.
danielk1977106bb232004-05-21 10:08:53 +00001839*/
danielk197717240fd2004-05-26 00:07:25 +00001840int sqlite3_step(sqlite3_stmt*);
danielk1977106bb232004-05-21 10:08:53 +00001841
danielk1977106bb232004-05-21 10:08:53 +00001842/*
drh6ed48bf2007-06-14 20:57:18 +00001843** CAPI3REF:
1844**
danielk1977106bb232004-05-21 10:08:53 +00001845** Return the number of values in the current row of the result set.
1846**
drh6ed48bf2007-06-14 20:57:18 +00001847** After a call to [sqlite3_step()] that returns [SQLITE_ROW], this routine
1848** will return the same value as the [sqlite3_column_count()] function.
1849** After [sqlite3_step()] has returned an [SQLITE_DONE], [SQLITE_BUSY], or
1850** a [SQLITE_ERROR | error code], or before [sqlite3_step()] has been
drh6d2069d2007-08-14 01:58:53 +00001851** called on the [sqlite3_stmt | prepared statement] for the first time,
drh6ed48bf2007-06-14 20:57:18 +00001852** this routine returns zero.
danielk1977106bb232004-05-21 10:08:53 +00001853*/
danielk197793d46752004-05-23 13:30:58 +00001854int sqlite3_data_count(sqlite3_stmt *pStmt);
danielk19774adee202004-05-08 08:23:19 +00001855
drh4f26d6c2004-05-26 23:25:30 +00001856/*
drh6ed48bf2007-06-14 20:57:18 +00001857** CAPI3REF: Fundamental Datatypes
1858**
1859** Every value in SQLite has one of five fundamental datatypes:
1860**
1861** <ul>
1862** <li> 64-bit signed integer
1863** <li> 64-bit IEEE floating point number
1864** <li> string
1865** <li> BLOB
1866** <li> NULL
1867** </ul>
1868**
1869** These constants are codes for each of those types.
1870**
1871** Note that the SQLITE_TEXT constant was also used in SQLite version 2
1872** for a completely different meaning. Software that links against both
1873** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT not
1874** SQLITE_TEXT.
drh4f26d6c2004-05-26 23:25:30 +00001875*/
drh9c054832004-05-31 18:51:57 +00001876#define SQLITE_INTEGER 1
1877#define SQLITE_FLOAT 2
drh9c054832004-05-31 18:51:57 +00001878#define SQLITE_BLOB 4
1879#define SQLITE_NULL 5
drh1e284f42004-10-06 15:52:01 +00001880#ifdef SQLITE_TEXT
1881# undef SQLITE_TEXT
1882#else
1883# define SQLITE_TEXT 3
1884#endif
1885#define SQLITE3_TEXT 3
1886
1887/*
drh6ed48bf2007-06-14 20:57:18 +00001888** CAPI3REF: Results Values From A Query
1889**
1890** These routines return information about the information
drh4f26d6c2004-05-26 23:25:30 +00001891** in a single column of the current result row of a query. In every
drh6ed48bf2007-06-14 20:57:18 +00001892** case the first argument is a pointer to the
1893** [sqlite3_stmt | SQL statement] that is being
drh6d2069d2007-08-14 01:58:53 +00001894** evaluate (the [sqlite3_stmt*] that was returned from
drh6ed48bf2007-06-14 20:57:18 +00001895** [sqlite3_prepare_v2()] or one of its variants) and
drh4f26d6c2004-05-26 23:25:30 +00001896** the second argument is the index of the column for which information
drh6ed48bf2007-06-14 20:57:18 +00001897** should be returned. The left-most column has an index of 0.
danielk1977106bb232004-05-21 10:08:53 +00001898**
drh4f26d6c2004-05-26 23:25:30 +00001899** If the SQL statement is not currently point to a valid row, or if the
drh6ed48bf2007-06-14 20:57:18 +00001900** the column index is out of range, the result is undefined.
1901**
1902** The sqlite3_column_type() routine returns
1903** [SQLITE_INTEGER | datatype code] for the initial data type
1904** of the result column. The returned value is one of [SQLITE_INTEGER],
1905** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL]. The value
1906** returned by sqlite3_column_type() is only meaningful if no type
1907** conversions have occurred as described below. After a type conversion,
1908** the value returned by sqlite3_column_type() is undefined. Future
1909** versions of SQLite may change the behavior of sqlite3_column_type()
1910** following a type conversion.
1911**
drh6ed48bf2007-06-14 20:57:18 +00001912** If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
1913** routine returns the number of bytes in that BLOB or string.
1914** If the result is a UTF-16 string, then sqlite3_column_bytes() converts
1915** the string to UTF-8 and then returns the number of bytes.
1916** If the result is a numeric value then sqlite3_column_bytes() uses
1917** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns
1918** the number of bytes in that string.
1919** The value returned does not include the zero terminator at the end
1920** of the string. For clarity: the value returned is the number of
1921** bytes in the string, not the number of characters.
1922**
1923** The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes()
1924** but leaves the result in UTF-16 instead of UTF-8.
1925** The zero terminator is not included in this count.
drh4f26d6c2004-05-26 23:25:30 +00001926**
1927** These routines attempt to convert the value where appropriate. For
1928** example, if the internal representation is FLOAT and a text result
drh6ed48bf2007-06-14 20:57:18 +00001929** is requested, [sqlite3_snprintf()] is used internally to do the conversion
drh4f26d6c2004-05-26 23:25:30 +00001930** automatically. The following table details the conversions that
1931** are applied:
1932**
drh6ed48bf2007-06-14 20:57:18 +00001933** <blockquote>
1934** <table border="1">
1935** <tr><th> Internal <th> Requested <th>
1936** <tr><th> Type <th> Type <th> Conversion
drh4f26d6c2004-05-26 23:25:30 +00001937**
drh6ed48bf2007-06-14 20:57:18 +00001938** <tr><td> NULL <td> INTEGER <td> Result is 0
1939** <tr><td> NULL <td> FLOAT <td> Result is 0.0
1940** <tr><td> NULL <td> TEXT <td> Result is NULL pointer
1941** <tr><td> NULL <td> BLOB <td> Result is NULL pointer
1942** <tr><td> INTEGER <td> FLOAT <td> Convert from integer to float
1943** <tr><td> INTEGER <td> TEXT <td> ASCII rendering of the integer
1944** <tr><td> INTEGER <td> BLOB <td> Same as for INTEGER->TEXT
1945** <tr><td> FLOAT <td> INTEGER <td> Convert from float to integer
1946** <tr><td> FLOAT <td> TEXT <td> ASCII rendering of the float
1947** <tr><td> FLOAT <td> BLOB <td> Same as FLOAT->TEXT
1948** <tr><td> TEXT <td> INTEGER <td> Use atoi()
1949** <tr><td> TEXT <td> FLOAT <td> Use atof()
1950** <tr><td> TEXT <td> BLOB <td> No change
1951** <tr><td> BLOB <td> INTEGER <td> Convert to TEXT then use atoi()
1952** <tr><td> BLOB <td> FLOAT <td> Convert to TEXT then use atof()
1953** <tr><td> BLOB <td> TEXT <td> Add a zero terminator if needed
1954** </table>
1955** </blockquote>
drh4f26d6c2004-05-26 23:25:30 +00001956**
drh6ed48bf2007-06-14 20:57:18 +00001957** The table above makes reference to standard C library functions atoi()
1958** and atof(). SQLite does not really use these functions. It has its
1959** on equavalent internal routines. The atoi() and atof() names are
1960** used in the table for brevity and because they are familiar to most
1961** C programmers.
1962**
1963** Note that when type conversions occur, pointers returned by prior
1964** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
1965** sqlite3_column_text16() may be invalidated.
1966** Type conversions and pointer invalidations might occur
1967** in the following cases:
1968**
1969** <ul>
1970** <li><p> The initial content is a BLOB and sqlite3_column_text()
1971** or sqlite3_column_text16() is called. A zero-terminator might
1972** need to be added to the string.</p></li>
1973**
1974** <li><p> The initial content is UTF-8 text and sqlite3_column_bytes16() or
1975** sqlite3_column_text16() is called. The content must be converted
1976** to UTF-16.</p></li>
1977**
1978** <li><p> The initial content is UTF-16 text and sqlite3_column_bytes() or
1979** sqlite3_column_text() is called. The content must be converted
1980** to UTF-8.</p></li>
1981** </ul>
1982**
1983** Conversions between UTF-16be and UTF-16le are always done in place and do
1984** not invalidate a prior pointer, though of course the content of the buffer
1985** that the prior pointer points to will have been modified. Other kinds
1986** of conversion are done in place when it is possible, but sometime it is
1987** not possible and in those cases prior pointers are invalidated.
1988**
1989** The safest and easiest to remember policy is to invoke these routines
1990** in one of the following ways:
1991**
1992** <ul>
1993** <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li>
1994** <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li>
1995** <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li>
1996** </ul>
1997**
1998** In other words, you should call sqlite3_column_text(), sqlite3_column_blob(),
1999** or sqlite3_column_text16() first to force the result into the desired
2000** format, then invoke sqlite3_column_bytes() or sqlite3_column_bytes16() to
2001** find the size of the result. Do not mix call to sqlite3_column_text() or
2002** sqlite3_column_blob() with calls to sqlite3_column_bytes16(). And do not
2003** mix calls to sqlite3_column_text16() with calls to sqlite3_column_bytes().
danielk1977106bb232004-05-21 10:08:53 +00002004*/
drhf4479502004-05-27 03:12:53 +00002005const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
2006int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
2007int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
2008double sqlite3_column_double(sqlite3_stmt*, int iCol);
2009int sqlite3_column_int(sqlite3_stmt*, int iCol);
drh6d2069d2007-08-14 01:58:53 +00002010sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
drhf4479502004-05-27 03:12:53 +00002011const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
2012const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
drh4f26d6c2004-05-26 23:25:30 +00002013int sqlite3_column_type(sqlite3_stmt*, int iCol);
drh4be8b512006-06-13 23:51:34 +00002014sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
danielk19774adee202004-05-08 08:23:19 +00002015
danielk197765904932004-05-26 06:18:37 +00002016/*
drh6ed48bf2007-06-14 20:57:18 +00002017** CAPI3REF: Destroy A Prepared Statement Object
2018**
2019** The sqlite3_finalize() function is called to delete a
2020** [sqlite3_stmt | compiled SQL statement]. If the statement was
2021** executed successfully, or not executed at all, then SQLITE_OK is returned.
2022** If execution of the statement failed then an
2023** [SQLITE_ERROR | error code] or [SQLITE_IOERR_READ | extended error code]
2024** is returned.
danielk197765904932004-05-26 06:18:37 +00002025**
2026** This routine can be called at any point during the execution of the
drh6ed48bf2007-06-14 20:57:18 +00002027** [sqlite3_stmt | virtual machine]. If the virtual machine has not
2028** completed execution when this routine is called, that is like
2029** encountering an error or an interrupt. (See [sqlite3_interrupt()].)
2030** Incomplete updates may be rolled back and transactions cancelled,
2031** depending on the circumstances, and the
2032** [SQLITE_ERROR | result code] returned will be [SQLITE_ABORT].
danielk197765904932004-05-26 06:18:37 +00002033*/
2034int sqlite3_finalize(sqlite3_stmt *pStmt);
2035
2036/*
drh6ed48bf2007-06-14 20:57:18 +00002037** CAPI3REF: Reset A Prepared Statement Object
2038**
2039** The sqlite3_reset() function is called to reset a
drh6d2069d2007-08-14 01:58:53 +00002040** [sqlite3_stmt | compiled SQL statement] object.
drh6ed48bf2007-06-14 20:57:18 +00002041** back to it's initial state, ready to be re-executed.
danielk197765904932004-05-26 06:18:37 +00002042** Any SQL statement variables that had values bound to them using
drh6ed48bf2007-06-14 20:57:18 +00002043** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values.
2044** Use [sqlite3_clear_bindings()] to reset the bindings.
danielk197765904932004-05-26 06:18:37 +00002045*/
2046int sqlite3_reset(sqlite3_stmt *pStmt);
2047
2048/*
drh6ed48bf2007-06-14 20:57:18 +00002049** CAPI3REF: Create Or Redefine SQL Functions
2050**
2051** The following two functions are used to add SQL functions or aggregates
2052** or to redefine the behavior of existing SQL functions or aggregates. The
danielk197765904932004-05-26 06:18:37 +00002053** difference only between the two is that the second parameter, the
2054** name of the (scalar) function or aggregate, is encoded in UTF-8 for
2055** sqlite3_create_function() and UTF-16 for sqlite3_create_function16().
2056**
drh6ed48bf2007-06-14 20:57:18 +00002057** The first argument is the [sqlite3 | database handle] that holds the
2058** SQL function or aggregate is to be added or redefined. If a single
2059** program uses more than one database handle internally, then SQL
2060** functions or aggregates must be added individually to each database
2061** handle with which they will be used.
danielk197765904932004-05-26 06:18:37 +00002062**
drh6ed48bf2007-06-14 20:57:18 +00002063** The second parameter is the name of the SQL function to be created
2064** or redefined.
2065** The length of the name is limited to 255 bytes, exclusive of the
2066** zero-terminator. Note that the name length limit is in bytes, not
2067** characters. Any attempt to create a function with a longer name
2068** will result in an SQLITE_ERROR error.
2069**
2070** The third parameter is the number of arguments that the SQL function or
2071** aggregate takes. If this parameter is negative, then the SQL function or
danielk197765904932004-05-26 06:18:37 +00002072** aggregate may take any number of arguments.
2073**
drh6ed48bf2007-06-14 20:57:18 +00002074** The fourth parameter, eTextRep, specifies what
2075** [SQLITE_UTF8 | text encoding] this SQL function prefers for
2076** its parameters. Any SQL function implementation should be able to work
2077** work with UTF-8, UTF-16le, or UTF-16be. But some implementations may be
2078** more efficient with one encoding than another. It is allowed to
drh6d2069d2007-08-14 01:58:53 +00002079** invoke sqlite3_create_function() or sqlite3_create_function16() multiple
drh6ed48bf2007-06-14 20:57:18 +00002080** times with the same function but with different values of eTextRep.
2081** When multiple implementations of the same function are available, SQLite
2082** will pick the one that involves the least amount of data conversion.
2083** If there is only a single implementation which does not care what
2084** text encoding is used, then the fourth argument should be
2085** [SQLITE_ANY].
2086**
2087** The fifth parameter is an arbitrary pointer. The implementation
2088** of the function can gain access to this pointer using
drh6d2069d2007-08-14 01:58:53 +00002089** [sqlite3_user_data()].
danielk1977d02eb1f2004-06-06 09:44:03 +00002090**
danielk197765904932004-05-26 06:18:37 +00002091** The seventh, eighth and ninth parameters, xFunc, xStep and xFinal, are
drh6ed48bf2007-06-14 20:57:18 +00002092** pointers to C-language functions that implement the SQL
2093** function or aggregate. A scalar SQL function requires an implementation of
danielk197765904932004-05-26 06:18:37 +00002094** the xFunc callback only, NULL pointers should be passed as the xStep
drh6ed48bf2007-06-14 20:57:18 +00002095** and xFinal parameters. An aggregate SQL function requires an implementation
2096** of xStep and xFinal and NULL should be passed for xFunc. To delete an
2097** existing SQL function or aggregate, pass NULL for all three function
2098** callback.
2099**
2100** It is permitted to register multiple implementations of the same
2101** functions with the same name but with either differing numbers of
2102** arguments or differing perferred text encodings. SQLite will use
2103** the implementation most closely matches the way in which the
2104** SQL function is used.
danielk197765904932004-05-26 06:18:37 +00002105*/
2106int sqlite3_create_function(
2107 sqlite3 *,
2108 const char *zFunctionName,
2109 int nArg,
2110 int eTextRep,
danielk197765904932004-05-26 06:18:37 +00002111 void*,
2112 void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
2113 void (*xStep)(sqlite3_context*,int,sqlite3_value**),
2114 void (*xFinal)(sqlite3_context*)
2115);
2116int sqlite3_create_function16(
2117 sqlite3*,
2118 const void *zFunctionName,
2119 int nArg,
2120 int eTextRep,
danielk197765904932004-05-26 06:18:37 +00002121 void*,
2122 void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
2123 void (*xStep)(sqlite3_context*,int,sqlite3_value**),
2124 void (*xFinal)(sqlite3_context*)
2125);
2126
2127/*
drh6ed48bf2007-06-14 20:57:18 +00002128** CAPI3REF: Text Encodings
2129**
2130** These constant define integer codes that represent the various
2131** text encodings supported by SQLite.
danielk197765904932004-05-26 06:18:37 +00002132*/
drh6ed48bf2007-06-14 20:57:18 +00002133#define SQLITE_UTF8 1
2134#define SQLITE_UTF16LE 2
2135#define SQLITE_UTF16BE 3
2136#define SQLITE_UTF16 4 /* Use native byte order */
2137#define SQLITE_ANY 5 /* sqlite3_create_function only */
2138#define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */
danielk197765904932004-05-26 06:18:37 +00002139
danielk19770ffba6b2004-05-24 09:10:10 +00002140/*
drh6ed48bf2007-06-14 20:57:18 +00002141** CAPI3REF: Obsolete Functions
2142**
2143** These functions are all now obsolete. In order to maintain
2144** backwards compatibility with older code, we continue to support
2145** these functions. However, new development projects should avoid
2146** the use of these functions. To help encourage people to avoid
2147** using these functions, we are not going to tell you want they do.
2148*/
2149int sqlite3_aggregate_count(sqlite3_context*);
2150int sqlite3_expired(sqlite3_stmt*);
2151int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
2152int sqlite3_global_recover(void);
2153
2154
2155/*
2156** CAPI3REF: Obtaining SQL Function Parameter Values
2157**
2158** The C-language implementation of SQL functions and aggregates uses
2159** this set of interface routines to access the parameter values on
2160** the function or aggregate.
2161**
2162** The xFunc (for scalar functions) or xStep (for aggregates) parameters
2163** to [sqlite3_create_function()] and [sqlite3_create_function16()]
2164** define callbacks that implement the SQL functions and aggregates.
2165** The 4th parameter to these callbacks is an array of pointers to
2166** [sqlite3_value] objects. There is one [sqlite3_value] object for
2167** each parameter to the SQL function. These routines are used to
2168** extract values from the [sqlite3_value] objects.
2169**
2170** These routines work just like the corresponding
2171** [sqlite3_column_blob | sqlite3_column_* routines] except that
2172** these routines take a single [sqlite3_value*] pointer instead
2173** of an [sqlite3_stmt*] pointer and an integer column number.
2174**
2175** The sqlite3_value_text16() interface extracts a UTF16 string
2176** in the native byte-order of the host machine. The
2177** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces
2178** extract UTF16 strings as big-endian and little-endian respectively.
2179**
2180** The sqlite3_value_numeric_type() interface attempts to apply
2181** numeric affinity to the value. This means that an attempt is
2182** made to convert the value to an integer or floating point. If
2183** such a conversion is possible without loss of information (in order
2184** words if the value is original a string that looks like a number)
2185** then it is done. Otherwise no conversion occurs. The
2186** [SQLITE_INTEGER | datatype] after conversion is returned.
2187**
2188** Please pay particular attention to the fact that the pointer that
2189** is returned from [sqlite3_value_blob()], [sqlite3_value_text()], or
2190** [sqlite3_value_text16()] can be invalidated by a subsequent call to
drh6d2069d2007-08-14 01:58:53 +00002191** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()],
drh6ed48bf2007-06-14 20:57:18 +00002192** or [sqlite3_value_text16()].
drhe53831d2007-08-17 01:14:38 +00002193**
2194** These routines must be called from the same thread as
2195** the SQL function that supplied the sqlite3_value* parameters.
danielk19770ffba6b2004-05-24 09:10:10 +00002196*/
drhf4479502004-05-27 03:12:53 +00002197const void *sqlite3_value_blob(sqlite3_value*);
2198int sqlite3_value_bytes(sqlite3_value*);
2199int sqlite3_value_bytes16(sqlite3_value*);
2200double sqlite3_value_double(sqlite3_value*);
2201int sqlite3_value_int(sqlite3_value*);
drh6d2069d2007-08-14 01:58:53 +00002202sqlite3_int64 sqlite3_value_int64(sqlite3_value*);
drhf4479502004-05-27 03:12:53 +00002203const unsigned char *sqlite3_value_text(sqlite3_value*);
2204const void *sqlite3_value_text16(sqlite3_value*);
danielk1977d8123362004-06-12 09:25:12 +00002205const void *sqlite3_value_text16le(sqlite3_value*);
2206const void *sqlite3_value_text16be(sqlite3_value*);
danielk197793d46752004-05-23 13:30:58 +00002207int sqlite3_value_type(sqlite3_value*);
drh29d72102006-02-09 22:13:41 +00002208int sqlite3_value_numeric_type(sqlite3_value*);
danielk19770ffba6b2004-05-24 09:10:10 +00002209
2210/*
drh6ed48bf2007-06-14 20:57:18 +00002211** CAPI3REF: Obtain Aggregate Function Context
2212**
2213** The implementation of aggregate SQL functions use this routine to allocate
danielk19770ae8b832004-05-25 12:05:56 +00002214** a structure for storing their state. The first time this routine
2215** is called for a particular aggregate, a new structure of size nBytes
2216** is allocated, zeroed, and returned. On subsequent calls (for the
2217** same aggregate instance) the same buffer is returned. The implementation
2218** of the aggregate can use the returned buffer to accumulate data.
2219**
drh6ed48bf2007-06-14 20:57:18 +00002220** The buffer allocated is freed automatically by SQLite whan the aggregate
2221** query concludes.
2222**
2223** The first parameter should be a copy of the
2224** [sqlite3_context | SQL function context] that is the first
2225** parameter to the callback routine that implements the aggregate
2226** function.
drhe53831d2007-08-17 01:14:38 +00002227**
2228** This routine must be called from the same thread in which
drh605264d2007-08-21 15:13:19 +00002229** the aggregate SQL function is running.
danielk19770ae8b832004-05-25 12:05:56 +00002230*/
drh4f26d6c2004-05-26 23:25:30 +00002231void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
danielk19777e18c252004-05-25 11:47:24 +00002232
2233/*
drh6ed48bf2007-06-14 20:57:18 +00002234** CAPI3REF: User Data For Functions
2235**
2236** The pUserData parameter to the [sqlite3_create_function()]
2237** and [sqlite3_create_function16()] routines
2238** used to register user functions is available to
drhc0f2a012005-07-09 02:39:40 +00002239** the implementation of the function using this call.
drhe53831d2007-08-17 01:14:38 +00002240**
2241** This routine must be called from the same thread in which
2242** the SQL function was originally invoked.
danielk19777e18c252004-05-25 11:47:24 +00002243*/
2244void *sqlite3_user_data(sqlite3_context*);
2245
2246/*
drh6ed48bf2007-06-14 20:57:18 +00002247** CAPI3REF: Function Auxiliary Data
2248**
2249** The following two functions may be used by scalar SQL functions to
danielk1977682f68b2004-06-05 10:22:17 +00002250** associate meta-data with argument values. If the same value is passed to
drh6ed48bf2007-06-14 20:57:18 +00002251** multiple invocations of the same SQL function during query execution, under
danielk1977682f68b2004-06-05 10:22:17 +00002252** some circumstances the associated meta-data may be preserved. This may
2253** be used, for example, to add a regular-expression matching scalar
2254** function. The compiled version of the regular expression is stored as
2255** meta-data associated with the SQL value passed as the regular expression
drh6ed48bf2007-06-14 20:57:18 +00002256** pattern. The compiled regular expression can be reused on multiple
2257** invocations of the same function so that the original pattern string
2258** does not need to be recompiled on each invocation.
danielk1977682f68b2004-06-05 10:22:17 +00002259**
drh6ed48bf2007-06-14 20:57:18 +00002260** The sqlite3_get_auxdata() interface returns a pointer to the meta-data
2261** associated with the Nth argument value to the current SQL function
danielk1977682f68b2004-06-05 10:22:17 +00002262** call, where N is the second parameter. If no meta-data has been set for
2263** that value, then a NULL pointer is returned.
2264**
drh6ed48bf2007-06-14 20:57:18 +00002265** The sqlite3_set_auxdata() is used to associate meta-data with an SQL
2266** function argument. The third parameter is a pointer to the meta-data
danielk1977682f68b2004-06-05 10:22:17 +00002267** to be associated with the Nth user function argument value. The fourth
drh6ed48bf2007-06-14 20:57:18 +00002268** parameter specifies a destructor that will be called on the meta-
2269** data pointer to release it when it is no longer required. If the
2270** destructor is NULL, it is not invoked.
danielk1977682f68b2004-06-05 10:22:17 +00002271**
2272** In practice, meta-data is preserved between function calls for
2273** expressions that are constant at compile time. This includes literal
2274** values and SQL variables.
drhe53831d2007-08-17 01:14:38 +00002275**
2276** These routine must be called from the same thread in which
2277** the SQL function was originally invoked.
danielk1977682f68b2004-06-05 10:22:17 +00002278*/
2279void *sqlite3_get_auxdata(sqlite3_context*, int);
2280void sqlite3_set_auxdata(sqlite3_context*, int, void*, void (*)(void*));
2281
drha2854222004-06-17 19:04:17 +00002282
2283/*
drh6ed48bf2007-06-14 20:57:18 +00002284** CAPI3REF: Constants Defining Special Destructor Behavior
2285**
drha2854222004-06-17 19:04:17 +00002286** These are special value for the destructor that is passed in as the
drh6ed48bf2007-06-14 20:57:18 +00002287** final argument to routines like [sqlite3_result_blob()]. If the destructor
drha2854222004-06-17 19:04:17 +00002288** argument is SQLITE_STATIC, it means that the content pointer is constant
2289** and will never change. It does not need to be destroyed. The
2290** SQLITE_TRANSIENT value means that the content will likely change in
2291** the near future and that SQLite should make its own private copy of
2292** the content before returning.
drh6c9121a2007-01-26 00:51:43 +00002293**
2294** The typedef is necessary to work around problems in certain
2295** C++ compilers. See ticket #2191.
drha2854222004-06-17 19:04:17 +00002296*/
drh6c9121a2007-01-26 00:51:43 +00002297typedef void (*sqlite3_destructor_type)(void*);
2298#define SQLITE_STATIC ((sqlite3_destructor_type)0)
2299#define SQLITE_TRANSIENT ((sqlite3_destructor_type)-1)
danielk1977d8123362004-06-12 09:25:12 +00002300
danielk1977682f68b2004-06-05 10:22:17 +00002301/*
drh6ed48bf2007-06-14 20:57:18 +00002302** CAPI3REF: Setting The Result Of An SQL Function
2303**
2304** These routines are used by the xFunc or xFinal callbacks that
2305** implement SQL functions and aggregates. See
2306** [sqlite3_create_function()] and [sqlite3_create_function16()]
2307** for additional information.
2308**
2309** These functions work very much like the
2310** [sqlite3_bind_blob | sqlite3_bind_*] family of functions used
2311** to bind values to host parameters in prepared statements.
2312** Refer to the
2313** [sqlite3_bind_blob | sqlite3_bind_* documentation] for
2314** additional information.
2315**
2316** The sqlite3_result_error() and sqlite3_result_error16() functions
2317** cause the implemented SQL function to throw an exception. The
2318** parameter to sqlite3_result_error() or sqlite3_result_error16()
2319** is the text of an error message.
2320**
2321** The sqlite3_result_toobig() cause the function implementation
2322** to throw and error indicating that a string or BLOB is to long
2323** to represent.
drhe53831d2007-08-17 01:14:38 +00002324**
2325** These routines must be called from within the same thread as
2326** the SQL function associated with the [sqlite3_context] pointer.
danielk19777e18c252004-05-25 11:47:24 +00002327*/
danielk1977d8123362004-06-12 09:25:12 +00002328void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
drh4f26d6c2004-05-26 23:25:30 +00002329void sqlite3_result_double(sqlite3_context*, double);
danielk19777e18c252004-05-25 11:47:24 +00002330void sqlite3_result_error(sqlite3_context*, const char*, int);
2331void sqlite3_result_error16(sqlite3_context*, const void*, int);
drh6ed48bf2007-06-14 20:57:18 +00002332void sqlite3_result_error_toobig(sqlite3_context*);
drh4f26d6c2004-05-26 23:25:30 +00002333void sqlite3_result_int(sqlite3_context*, int);
drh6d2069d2007-08-14 01:58:53 +00002334void sqlite3_result_int64(sqlite3_context*, sqlite3_int64);
drh4f26d6c2004-05-26 23:25:30 +00002335void sqlite3_result_null(sqlite3_context*);
danielk1977d8123362004-06-12 09:25:12 +00002336void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
2337void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
2338void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
2339void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
drh4f26d6c2004-05-26 23:25:30 +00002340void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
drhb026e052007-05-02 01:34:31 +00002341void sqlite3_result_zeroblob(sqlite3_context*, int n);
drhf9b596e2004-05-26 16:54:42 +00002342
drh52619df2004-06-11 17:48:02 +00002343/*
drh6ed48bf2007-06-14 20:57:18 +00002344** CAPI3REF: Define New Collating Sequences
2345**
2346** These functions are used to add new collation sequences to the
2347** [sqlite3*] handle specified as the first argument.
danielk19777cedc8d2004-06-10 10:50:08 +00002348**
2349** The name of the new collation sequence is specified as a UTF-8 string
drh6ed48bf2007-06-14 20:57:18 +00002350** for sqlite3_create_collation() and sqlite3_create_collation_v2()
2351** and a UTF-16 string for sqlite3_create_collation16(). In all cases
2352** the name is passed as the second function argument.
danielk19777cedc8d2004-06-10 10:50:08 +00002353**
drh6ed48bf2007-06-14 20:57:18 +00002354** The third argument must be one of the constants [SQLITE_UTF8],
2355** [SQLITE_UTF16LE] or [SQLITE_UTF16BE], indicating that the user-supplied
danielk19777cedc8d2004-06-10 10:50:08 +00002356** routine expects to be passed pointers to strings encoded using UTF-8,
2357** UTF-16 little-endian or UTF-16 big-endian respectively.
2358**
2359** A pointer to the user supplied routine must be passed as the fifth
2360** argument. If it is NULL, this is the same as deleting the collation
2361** sequence (so that SQLite cannot call it anymore). Each time the user
2362** supplied function is invoked, it is passed a copy of the void* passed as
2363** the fourth argument to sqlite3_create_collation() or
2364** sqlite3_create_collation16() as its first parameter.
2365**
2366** The remaining arguments to the user-supplied routine are two strings,
2367** each represented by a [length, data] pair and encoded in the encoding
2368** that was passed as the third argument when the collation sequence was
2369** registered. The user routine should return negative, zero or positive if
2370** the first string is less than, equal to, or greater than the second
2371** string. i.e. (STRING1 - STRING2).
drh6ed48bf2007-06-14 20:57:18 +00002372**
2373** The sqlite3_create_collation_v2() works like sqlite3_create_collation()
2374** excapt that it takes an extra argument which is a destructor for
2375** the collation. The destructor is called when the collation is
2376** destroyed and is passed a copy of the fourth parameter void* pointer
2377** of the sqlite3_create_collation_v2(). Collations are destroyed when
2378** they are overridden by later calls to the collation creation functions
2379** or when the [sqlite3*] database handle is closed using [sqlite3_close()].
2380**
2381** The sqlite3_create_collation_v2() interface is experimental and
2382** subject to change in future releases. The other collation creation
2383** functions are stable.
danielk19777cedc8d2004-06-10 10:50:08 +00002384*/
danielk19770202b292004-06-09 09:55:16 +00002385int sqlite3_create_collation(
2386 sqlite3*,
2387 const char *zName,
danielk19777cedc8d2004-06-10 10:50:08 +00002388 int eTextRep,
danielk19770202b292004-06-09 09:55:16 +00002389 void*,
2390 int(*xCompare)(void*,int,const void*,int,const void*)
2391);
drh6ed48bf2007-06-14 20:57:18 +00002392int sqlite3_create_collation_v2(
2393 sqlite3*,
2394 const char *zName,
2395 int eTextRep,
2396 void*,
2397 int(*xCompare)(void*,int,const void*,int,const void*),
2398 void(*xDestroy)(void*)
2399);
danielk19770202b292004-06-09 09:55:16 +00002400int sqlite3_create_collation16(
2401 sqlite3*,
2402 const char *zName,
danielk19777cedc8d2004-06-10 10:50:08 +00002403 int eTextRep,
danielk19770202b292004-06-09 09:55:16 +00002404 void*,
2405 int(*xCompare)(void*,int,const void*,int,const void*)
2406);
2407
danielk19777cedc8d2004-06-10 10:50:08 +00002408/*
drh6ed48bf2007-06-14 20:57:18 +00002409** CAPI3REF: Collation Needed Callbacks
danielk1977a393c032007-05-07 14:58:53 +00002410**
danielk19777cedc8d2004-06-10 10:50:08 +00002411** To avoid having to register all collation sequences before a database
2412** can be used, a single callback function may be registered with the
2413** database handle to be called whenever an undefined collation sequence is
2414** required.
2415**
2416** If the function is registered using the sqlite3_collation_needed() API,
2417** then it is passed the names of undefined collation sequences as strings
2418** encoded in UTF-8. If sqlite3_collation_needed16() is used, the names
2419** are passed as UTF-16 in machine native byte order. A call to either
2420** function replaces any existing callback.
2421**
drh6ed48bf2007-06-14 20:57:18 +00002422** When the callback is invoked, the first argument passed is a copy
danielk19777cedc8d2004-06-10 10:50:08 +00002423** of the second argument to sqlite3_collation_needed() or
2424** sqlite3_collation_needed16(). The second argument is the database
drh6ed48bf2007-06-14 20:57:18 +00002425** handle. The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE], or
2426** [SQLITE_UTF16LE], indicating the most desirable form of the collation
danielk19777cedc8d2004-06-10 10:50:08 +00002427** sequence function required. The fourth parameter is the name of the
2428** required collation sequence.
2429**
drh6ed48bf2007-06-14 20:57:18 +00002430** The callback function should register the desired collation using
2431** [sqlite3_create_collation()], [sqlite3_create_collation16()], or
2432** [sqlite3_create_collation_v2()].
danielk19777cedc8d2004-06-10 10:50:08 +00002433*/
2434int sqlite3_collation_needed(
2435 sqlite3*,
2436 void*,
2437 void(*)(void*,sqlite3*,int eTextRep,const char*)
2438);
2439int sqlite3_collation_needed16(
2440 sqlite3*,
2441 void*,
2442 void(*)(void*,sqlite3*,int eTextRep,const void*)
2443);
2444
drh2011d5f2004-07-22 02:40:37 +00002445/*
2446** Specify the key for an encrypted database. This routine should be
2447** called right after sqlite3_open().
2448**
2449** The code to implement this API is not available in the public release
2450** of SQLite.
2451*/
2452int sqlite3_key(
2453 sqlite3 *db, /* Database to be rekeyed */
2454 const void *pKey, int nKey /* The key */
2455);
2456
2457/*
2458** Change the key on an open database. If the current database is not
2459** encrypted, this routine will encrypt it. If pNew==0 or nNew==0, the
2460** database is decrypted.
2461**
2462** The code to implement this API is not available in the public release
2463** of SQLite.
2464*/
2465int sqlite3_rekey(
2466 sqlite3 *db, /* Database to be rekeyed */
2467 const void *pKey, int nKey /* The new key */
2468);
danielk19770202b292004-06-09 09:55:16 +00002469
drhab3f9fe2004-08-14 17:10:10 +00002470/*
drh6ed48bf2007-06-14 20:57:18 +00002471** CAPI3REF: Suspend Execution For A Short Time
2472**
danielk1977d84d4832007-06-20 09:09:47 +00002473** This function causes the current thread to suspend execution
drh6ed48bf2007-06-14 20:57:18 +00002474** a number of milliseconds specified in its parameter.
danielk1977600dd0b2005-01-20 01:14:23 +00002475**
2476** If the operating system does not support sleep requests with
drh6ed48bf2007-06-14 20:57:18 +00002477** millisecond time resolution, then the time will be rounded up to
2478** the nearest second. The number of milliseconds of sleep actually
danielk1977600dd0b2005-01-20 01:14:23 +00002479** requested from the operating system is returned.
danielk1977600dd0b2005-01-20 01:14:23 +00002480*/
2481int sqlite3_sleep(int);
2482
2483/*
drh6ed48bf2007-06-14 20:57:18 +00002484** CAPI3REF: Name Of The Folder Holding Temporary Files
drhd89bd002005-01-22 03:03:54 +00002485**
drh6ed48bf2007-06-14 20:57:18 +00002486** If this global variable is made to point to a string which is
2487** the name of a folder (a.ka. directory), then all temporary files
drhab3f9fe2004-08-14 17:10:10 +00002488** created by SQLite will be placed in that directory. If this variable
2489** is NULL pointer, then SQLite does a search for an appropriate temporary
2490** file directory.
2491**
drh6ed48bf2007-06-14 20:57:18 +00002492** Once [sqlite3_open()] has been called, changing this variable will
2493** invalidate the current temporary database, if any. Generally speaking,
2494** it is not safe to invoke this routine after [sqlite3_open()] has
2495** been called.
drhab3f9fe2004-08-14 17:10:10 +00002496*/
drh73be5012007-08-08 12:11:21 +00002497SQLITE_EXTERN char *sqlite3_temp_directory;
drhab3f9fe2004-08-14 17:10:10 +00002498
danielk19776b456a22005-03-21 04:04:02 +00002499/*
drh6ed48bf2007-06-14 20:57:18 +00002500** CAPI3REF: Test To See If The Databse Is In Auto-Commit Mode
danielk19776b456a22005-03-21 04:04:02 +00002501**
drh3e1d8e62005-05-26 16:23:34 +00002502** Test to see whether or not the database connection is in autocommit
2503** mode. Return TRUE if it is and FALSE if not. Autocommit mode is on
2504** by default. Autocommit is disabled by a BEGIN statement and reenabled
2505** by the next COMMIT or ROLLBACK.
drh3e1d8e62005-05-26 16:23:34 +00002506*/
2507int sqlite3_get_autocommit(sqlite3*);
2508
drh51942bc2005-06-12 22:01:42 +00002509/*
drh6ed48bf2007-06-14 20:57:18 +00002510** CAPI3REF: Find The Database Handle Associated With A Prepared Statement
2511**
2512** Return the [sqlite3*] database handle to which a
2513** [sqlite3_stmt | prepared statement] belongs.
2514** This is the same database handle that was
2515** the first argument to the [sqlite3_prepare_v2()] or its variants
2516** that was used to create the statement in the first place.
drh51942bc2005-06-12 22:01:42 +00002517*/
2518sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
drh3e1d8e62005-05-26 16:23:34 +00002519
drh6ed48bf2007-06-14 20:57:18 +00002520
drhb37df7b2005-10-13 02:09:49 +00002521/*
drh6ed48bf2007-06-14 20:57:18 +00002522** CAPI3REF: Commit And Rollback Notification Callbacks
2523**
2524** These routines
2525** register callback functions to be invoked whenever a transaction
2526** is committed or rolled back. The pArg argument is passed through
2527** to the callback. If the callback on a commit hook function
2528** returns non-zero, then the commit is converted into a rollback.
2529**
2530** If another function was previously registered, its pArg value is returned.
2531** Otherwise NULL is returned.
2532**
2533** Registering a NULL function disables the callback.
2534**
2535** For the purposes of this API, a transaction is said to have been
2536** rolled back if an explicit "ROLLBACK" statement is executed, or
2537** an error or constraint causes an implicit rollback to occur. The
2538** callback is not invoked if a transaction is automatically rolled
2539** back because the database connection is closed.
2540**
2541** These are experimental interfaces and are subject to change.
2542*/
2543void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
2544void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
2545
2546/*
2547** CAPI3REF: Data Change Notification Callbacks
2548**
danielk197794eb6a12005-12-15 15:22:08 +00002549** Register a callback function with the database connection identified by the
2550** first argument to be invoked whenever a row is updated, inserted or deleted.
2551** Any callback set by a previous call to this function for the same
2552** database connection is overridden.
2553**
2554** The second argument is a pointer to the function to invoke when a
2555** row is updated, inserted or deleted. The first argument to the callback is
drh6ed48bf2007-06-14 20:57:18 +00002556** a copy of the third argument to sqlite3_update_hook(). The second callback
danielk197794eb6a12005-12-15 15:22:08 +00002557** argument is one of SQLITE_INSERT, SQLITE_DELETE or SQLITE_UPDATE, depending
2558** on the operation that caused the callback to be invoked. The third and
2559** fourth arguments to the callback contain pointers to the database and
2560** table name containing the affected row. The final callback parameter is
2561** the rowid of the row. In the case of an update, this is the rowid after
2562** the update takes place.
2563**
2564** The update hook is not invoked when internal system tables are
2565** modified (i.e. sqlite_master and sqlite_sequence).
danielk197771fd80b2005-12-16 06:54:01 +00002566**
2567** If another function was previously registered, its pArg value is returned.
2568** Otherwise NULL is returned.
danielk197794eb6a12005-12-15 15:22:08 +00002569*/
danielk197771fd80b2005-12-16 06:54:01 +00002570void *sqlite3_update_hook(
danielk197794eb6a12005-12-15 15:22:08 +00002571 sqlite3*,
drh6d2069d2007-08-14 01:58:53 +00002572 void(*)(void *,int ,char const *,char const *,sqlite3_int64),
danielk197794eb6a12005-12-15 15:22:08 +00002573 void*
2574);
danielk197713a68c32005-12-15 10:11:30 +00002575
danielk1977f3f06bb2005-12-16 15:24:28 +00002576/*
drh6ed48bf2007-06-14 20:57:18 +00002577** CAPI3REF: Enable Or Disable Shared Pager Cache
danielk1977f3f06bb2005-12-16 15:24:28 +00002578**
drh6ed48bf2007-06-14 20:57:18 +00002579** This routine enables or disables the sharing of the database cache
2580** and schema data structures between connections to the same database.
2581** Sharing is enabled if the argument is true and disabled if the argument
2582** is false.
danielk1977f3f06bb2005-12-16 15:24:28 +00002583**
drh6ed48bf2007-06-14 20:57:18 +00002584** Cache sharing is enabled and disabled on a thread-by-thread basis.
2585** Each call to this routine enables or disables cache sharing only for
2586** connections created in the same thread in which this routine is called.
2587** There is no mechanism for sharing cache between database connections
2588** running in different threads.
2589**
2590** Sharing must be disabled prior to shutting down a thread or else
2591** the thread will leak memory. Call this routine with an argument of
2592** 0 to turn off sharing. Or use the sqlite3_thread_cleanup() API.
2593**
2594** This routine must not be called when any database connections
2595** are active in the current thread. Enabling or disabling shared
2596** cache while there are active database connections will result
2597** in memory corruption.
2598**
2599** When the shared cache is enabled, the
2600** following routines must always be called from the same thread:
2601** [sqlite3_open()], [sqlite3_prepare_v2()], [sqlite3_step()],
2602** [sqlite3_reset()], [sqlite3_finalize()], and [sqlite3_close()].
2603** This is due to the fact that the shared cache makes use of
2604** thread-specific storage so that it will be available for sharing
2605** with other connections.
2606**
2607** Virtual tables cannot be used with a shared cache. When shared
2608** cache is enabled, the sqlite3_create_module() API used to register
2609** virtual tables will always return an error.
2610**
2611** This routine returns [SQLITE_OK] if shared cache was
2612** enabled or disabled successfully. An [SQLITE_ERROR | error code]
2613** is returned otherwise.
2614**
2615** Shared cache is disabled by default for backward compatibility.
danielk1977aef0bf62005-12-30 16:28:01 +00002616*/
2617int sqlite3_enable_shared_cache(int);
2618
2619/*
drh6ed48bf2007-06-14 20:57:18 +00002620** CAPI3REF: Attempt To Free Heap Memory
2621**
danielk197752622822006-01-09 09:59:49 +00002622** Attempt to free N bytes of heap memory by deallocating non-essential
2623** memory allocations held by the database library (example: memory
2624** used to cache database pages to improve performance).
2625**
drh6f7adc82006-01-11 21:41:20 +00002626** This function is not a part of standard builds. It is only created
2627** if SQLite is compiled with the SQLITE_ENABLE_MEMORY_MANAGEMENT macro.
danielk197752622822006-01-09 09:59:49 +00002628*/
2629int sqlite3_release_memory(int);
2630
2631/*
drh6ed48bf2007-06-14 20:57:18 +00002632** CAPI3REF: Impose A Limit On Heap Size
2633**
danielk197752622822006-01-09 09:59:49 +00002634** Place a "soft" limit on the amount of heap memory that may be allocated by
2635** SQLite within the current thread. If an internal allocation is requested
drh6ed48bf2007-06-14 20:57:18 +00002636** that would exceed the specified limit, [sqlite3_release_memory()] is invoked
danielk197752622822006-01-09 09:59:49 +00002637** one or more times to free up some space before the allocation is made.
2638**
drh6ed48bf2007-06-14 20:57:18 +00002639** The limit is called "soft", because if [sqlite3_release_memory()] cannot free
danielk197752622822006-01-09 09:59:49 +00002640** sufficient memory to prevent the limit from being exceeded, the memory is
2641** allocated anyway and the current operation proceeds.
2642**
drh6ed48bf2007-06-14 20:57:18 +00002643** Prior to shutting down a thread sqlite3_soft_heap_limit() must be set to
2644** zero (the default) or else the thread will leak memory. Alternatively, use
2645** the [sqlite3_thread_cleanup()] API.
2646**
2647** A negative or zero value for N means that there is no soft heap limit and
2648** [sqlite3_release_memory()] will only be called when memory is exhaused.
2649** The default value for the soft heap limit is zero.
2650**
2651** SQLite makes a best effort to honor the soft heap limit. But if it
2652** is unable to reduce memory usage below the soft limit, execution will
2653** continue without error or notification. This is why the limit is
2654** called a "soft" limit. It is advisory only.
2655**
drh6f7adc82006-01-11 21:41:20 +00002656** This function is only available if the library was compiled with the
2657** SQLITE_ENABLE_MEMORY_MANAGEMENT option set.
danielk197752622822006-01-09 09:59:49 +00002658** memory-management has been enabled.
2659*/
drhd2d4a6b2006-01-10 15:18:27 +00002660void sqlite3_soft_heap_limit(int);
danielk197752622822006-01-09 09:59:49 +00002661
2662/*
drh6ed48bf2007-06-14 20:57:18 +00002663** CAPI3REF: Clean Up Thread Local Storage
2664**
drh6f7adc82006-01-11 21:41:20 +00002665** This routine makes sure that all thread-local storage has been
2666** deallocated for the current thread.
2667**
2668** This routine is not technically necessary. All thread-local storage
2669** will be automatically deallocated once memory-management and
2670** shared-cache are disabled and the soft heap limit has been set
2671** to zero. This routine is provided as a convenience for users who
2672** want to make absolutely sure they have not forgotten something
2673** prior to killing off a thread.
2674*/
2675void sqlite3_thread_cleanup(void);
2676
2677/*
drh6ed48bf2007-06-14 20:57:18 +00002678** CAPI3REF: Extract Metadata About A Column Of A Table
2679**
2680** This routine
2681** returns meta-data about a specific column of a specific database
danielk1977deb802c2006-02-09 13:43:28 +00002682** table accessible using the connection handle passed as the first function
2683** argument.
2684**
2685** The column is identified by the second, third and fourth parameters to
2686** this function. The second parameter is either the name of the database
2687** (i.e. "main", "temp" or an attached database) containing the specified
2688** table or NULL. If it is NULL, then all attached databases are searched
2689** for the table using the same algorithm as the database engine uses to
2690** resolve unqualified table references.
2691**
2692** The third and fourth parameters to this function are the table and column
2693** name of the desired column, respectively. Neither of these parameters
2694** may be NULL.
2695**
2696** Meta information is returned by writing to the memory locations passed as
2697** the 5th and subsequent parameters to this function. Any of these
2698** arguments may be NULL, in which case the corresponding element of meta
2699** information is ommitted.
2700**
drh6ed48bf2007-06-14 20:57:18 +00002701** <pre>
danielk1977deb802c2006-02-09 13:43:28 +00002702** Parameter Output Type Description
2703** -----------------------------------
2704**
2705** 5th const char* Data type
2706** 6th const char* Name of the default collation sequence
2707** 7th int True if the column has a NOT NULL constraint
2708** 8th int True if the column is part of the PRIMARY KEY
2709** 9th int True if the column is AUTOINCREMENT
drh6ed48bf2007-06-14 20:57:18 +00002710** </pre>
danielk1977deb802c2006-02-09 13:43:28 +00002711**
2712**
2713** The memory pointed to by the character pointers returned for the
2714** declaration type and collation sequence is valid only until the next
2715** call to any sqlite API function.
2716**
2717** If the specified table is actually a view, then an error is returned.
2718**
2719** If the specified column is "rowid", "oid" or "_rowid_" and an
2720** INTEGER PRIMARY KEY column has been explicitly declared, then the output
2721** parameters are set for the explicitly declared column. If there is no
2722** explicitly declared IPK column, then the output parameters are set as
2723** follows:
2724**
drh6ed48bf2007-06-14 20:57:18 +00002725** <pre>
danielk1977deb802c2006-02-09 13:43:28 +00002726** data type: "INTEGER"
2727** collation sequence: "BINARY"
2728** not null: 0
2729** primary key: 1
2730** auto increment: 0
drh6ed48bf2007-06-14 20:57:18 +00002731** </pre>
danielk1977deb802c2006-02-09 13:43:28 +00002732**
2733** This function may load one or more schemas from database files. If an
2734** error occurs during this process, or if the requested table or column
2735** cannot be found, an SQLITE error code is returned and an error message
2736** left in the database handle (to be retrieved using sqlite3_errmsg()).
danielk19774b1ae992006-02-10 03:06:10 +00002737**
2738** This API is only available if the library was compiled with the
2739** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined.
danielk1977deb802c2006-02-09 13:43:28 +00002740*/
2741int sqlite3_table_column_metadata(
2742 sqlite3 *db, /* Connection handle */
2743 const char *zDbName, /* Database name or NULL */
2744 const char *zTableName, /* Table name */
2745 const char *zColumnName, /* Column name */
2746 char const **pzDataType, /* OUTPUT: Declared data type */
2747 char const **pzCollSeq, /* OUTPUT: Collation sequence name */
2748 int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */
2749 int *pPrimaryKey, /* OUTPUT: True if column part of PK */
2750 int *pAutoinc /* OUTPUT: True if colums is auto-increment */
2751);
2752
2753/*
drh6ed48bf2007-06-14 20:57:18 +00002754** CAPI3REF: Load An Extension
drh1e397f82006-06-08 15:28:43 +00002755**
2756** Attempt to load an SQLite extension library contained in the file
2757** zFile. The entry point is zProc. zProc may be 0 in which case the
drhc2e87a32006-06-27 15:16:14 +00002758** name of the entry point defaults to "sqlite3_extension_init".
drh1e397f82006-06-08 15:28:43 +00002759**
drh6ed48bf2007-06-14 20:57:18 +00002760** Return [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong.
drh1e397f82006-06-08 15:28:43 +00002761**
2762** If an error occurs and pzErrMsg is not 0, then fill *pzErrMsg with
2763** error message text. The calling function should free this memory
drh6ed48bf2007-06-14 20:57:18 +00002764** by calling [sqlite3_free()].
drh1e397f82006-06-08 15:28:43 +00002765**
drh6ed48bf2007-06-14 20:57:18 +00002766** Extension loading must be enabled using [sqlite3_enable_load_extension()]
drhc2e87a32006-06-27 15:16:14 +00002767** prior to calling this API or an error will be returned.
drh1e397f82006-06-08 15:28:43 +00002768*/
2769int sqlite3_load_extension(
2770 sqlite3 *db, /* Load the extension into this database connection */
2771 const char *zFile, /* Name of the shared library containing extension */
2772 const char *zProc, /* Entry point. Derived from zFile if 0 */
2773 char **pzErrMsg /* Put error message here if not 0 */
2774);
2775
2776/*
drh6ed48bf2007-06-14 20:57:18 +00002777** CAPI3REF: Enable Or Disable Extension Loading
2778**
drhc2e87a32006-06-27 15:16:14 +00002779** So as not to open security holes in older applications that are
drh6ed48bf2007-06-14 20:57:18 +00002780** unprepared to deal with extension loading, and as a means of disabling
2781** extension loading while evaluating user-entered SQL, the following
2782** API is provided to turn the [sqlite3_load_extension()] mechanism on and
drhc2e87a32006-06-27 15:16:14 +00002783** off. It is off by default. See ticket #1863.
2784**
2785** Call this routine with onoff==1 to turn extension loading on
2786** and call it with onoff==0 to turn it back off again.
2787*/
2788int sqlite3_enable_load_extension(sqlite3 *db, int onoff);
2789
2790/*
drh6ed48bf2007-06-14 20:57:18 +00002791** CAPI3REF: Make Arrangements To Automatically Load An Extension
drh9eff6162006-06-12 21:59:13 +00002792**
drh1409be62006-08-23 20:07:20 +00002793** Register an extension entry point that is automatically invoked
drh6ed48bf2007-06-14 20:57:18 +00002794** whenever a new database connection is opened using
drh605264d2007-08-21 15:13:19 +00002795** [sqlite3_open()], [sqlite3_open16()], or [sqlite3_open_v2()].
drh1409be62006-08-23 20:07:20 +00002796**
2797** This API can be invoked at program startup in order to register
2798** one or more statically linked extensions that will be available
2799** to all new database connections.
2800**
2801** Duplicate extensions are detected so calling this routine multiple
2802** times with the same extension is harmless.
2803**
2804** This routine stores a pointer to the extension in an array
2805** that is obtained from malloc(). If you run a memory leak
2806** checker on your program and it reports a leak because of this
drh6ed48bf2007-06-14 20:57:18 +00002807** array, then invoke [sqlite3_automatic_extension_reset()] prior
drh1409be62006-08-23 20:07:20 +00002808** to shutdown to free the memory.
2809**
2810** Automatic extensions apply across all threads.
drh6ed48bf2007-06-14 20:57:18 +00002811**
2812** This interface is experimental and is subject to change or
2813** removal in future releases of SQLite.
drh1409be62006-08-23 20:07:20 +00002814*/
2815int sqlite3_auto_extension(void *xEntryPoint);
2816
2817
2818/*
drh6ed48bf2007-06-14 20:57:18 +00002819** CAPI3REF: Reset Automatic Extension Loading
drh1409be62006-08-23 20:07:20 +00002820**
2821** Disable all previously registered automatic extensions. This
drh6ed48bf2007-06-14 20:57:18 +00002822** routine undoes the effect of all prior [sqlite3_automatic_extension()]
drh1409be62006-08-23 20:07:20 +00002823** calls.
2824**
2825** This call disabled automatic extensions in all threads.
drh6ed48bf2007-06-14 20:57:18 +00002826**
2827** This interface is experimental and is subject to change or
2828** removal in future releases of SQLite.
drh1409be62006-08-23 20:07:20 +00002829*/
2830void sqlite3_reset_auto_extension(void);
2831
2832
2833/*
2834****** EXPERIMENTAL - subject to change without notice **************
2835**
drh9eff6162006-06-12 21:59:13 +00002836** The interface to the virtual-table mechanism is currently considered
2837** to be experimental. The interface might change in incompatible ways.
2838** If this is a problem for you, do not use the interface at this time.
2839**
2840** When the virtual-table mechanism stablizes, we will declare the
2841** interface fixed, support it indefinitely, and remove this comment.
2842*/
2843
2844/*
2845** Structures used by the virtual table interface
drhe09daa92006-06-10 13:29:31 +00002846*/
2847typedef struct sqlite3_vtab sqlite3_vtab;
2848typedef struct sqlite3_index_info sqlite3_index_info;
2849typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor;
2850typedef struct sqlite3_module sqlite3_module;
drh9eff6162006-06-12 21:59:13 +00002851
2852/*
2853** A module is a class of virtual tables. Each module is defined
2854** by an instance of the following structure. This structure consists
2855** mostly of methods for the module.
2856*/
drhe09daa92006-06-10 13:29:31 +00002857struct sqlite3_module {
2858 int iVersion;
danielk19779da9d472006-06-14 06:58:15 +00002859 int (*xCreate)(sqlite3*, void *pAux,
drhe4102962006-09-11 00:34:22 +00002860 int argc, const char *const*argv,
drh4ca8aac2006-09-10 17:31:58 +00002861 sqlite3_vtab **ppVTab, char**);
danielk19779da9d472006-06-14 06:58:15 +00002862 int (*xConnect)(sqlite3*, void *pAux,
drhe4102962006-09-11 00:34:22 +00002863 int argc, const char *const*argv,
drh4ca8aac2006-09-10 17:31:58 +00002864 sqlite3_vtab **ppVTab, char**);
drhe09daa92006-06-10 13:29:31 +00002865 int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*);
2866 int (*xDisconnect)(sqlite3_vtab *pVTab);
2867 int (*xDestroy)(sqlite3_vtab *pVTab);
2868 int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor);
2869 int (*xClose)(sqlite3_vtab_cursor*);
drh4be8b512006-06-13 23:51:34 +00002870 int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr,
drhe09daa92006-06-10 13:29:31 +00002871 int argc, sqlite3_value **argv);
2872 int (*xNext)(sqlite3_vtab_cursor*);
danielk1977a298e902006-06-22 09:53:48 +00002873 int (*xEof)(sqlite3_vtab_cursor*);
drhe09daa92006-06-10 13:29:31 +00002874 int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int);
drh6d2069d2007-08-14 01:58:53 +00002875 int (*xRowid)(sqlite3_vtab_cursor*, sqlite3_int64 *pRowid);
2876 int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite3_int64 *);
drhe09daa92006-06-10 13:29:31 +00002877 int (*xBegin)(sqlite3_vtab *pVTab);
2878 int (*xSync)(sqlite3_vtab *pVTab);
2879 int (*xCommit)(sqlite3_vtab *pVTab);
2880 int (*xRollback)(sqlite3_vtab *pVTab);
drhb7f6f682006-07-08 17:06:43 +00002881 int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName,
drhe94b0c32006-07-08 18:09:15 +00002882 void (**pxFunc)(sqlite3_context*,int,sqlite3_value**),
2883 void **ppArg);
danielk1977182c4ba2007-06-27 15:53:34 +00002884
2885 int (*xRename)(sqlite3_vtab *pVtab, const char *zNew);
drhe09daa92006-06-10 13:29:31 +00002886};
drh9eff6162006-06-12 21:59:13 +00002887
2888/*
2889** The sqlite3_index_info structure and its substructures is used to
2890** pass information into and receive the reply from the xBestIndex
2891** method of an sqlite3_module. The fields under **Inputs** are the
2892** inputs to xBestIndex and are read-only. xBestIndex inserts its
2893** results into the **Outputs** fields.
2894**
2895** The aConstraint[] array records WHERE clause constraints of the
2896** form:
2897**
2898** column OP expr
2899**
2900** Where OP is =, <, <=, >, or >=. The particular operator is stored
2901** in aConstraint[].op. The index of the column is stored in
2902** aConstraint[].iColumn. aConstraint[].usable is TRUE if the
2903** expr on the right-hand side can be evaluated (and thus the constraint
2904** is usable) and false if it cannot.
2905**
2906** The optimizer automatically inverts terms of the form "expr OP column"
2907** and makes other simplificatinos to the WHERE clause in an attempt to
2908** get as many WHERE clause terms into the form shown above as possible.
2909** The aConstraint[] array only reports WHERE clause terms in the correct
2910** form that refer to the particular virtual table being queried.
2911**
2912** Information about the ORDER BY clause is stored in aOrderBy[].
2913** Each term of aOrderBy records a column of the ORDER BY clause.
2914**
2915** The xBestIndex method must fill aConstraintUsage[] with information
danielk19775fac9f82006-06-13 14:16:58 +00002916** about what parameters to pass to xFilter. If argvIndex>0 then
drh9eff6162006-06-12 21:59:13 +00002917** the right-hand side of the corresponding aConstraint[] is evaluated
2918** and becomes the argvIndex-th entry in argv. If aConstraintUsage[].omit
2919** is true, then the constraint is assumed to be fully handled by the
2920** virtual table and is not checked again by SQLite.
2921**
drh4be8b512006-06-13 23:51:34 +00002922** The idxNum and idxPtr values are recorded and passed into xFilter.
2923** sqlite3_free() is used to free idxPtr if needToFreeIdxPtr is true.
drh9eff6162006-06-12 21:59:13 +00002924**
2925** The orderByConsumed means that output from xFilter will occur in
2926** the correct order to satisfy the ORDER BY clause so that no separate
2927** sorting step is required.
2928**
2929** The estimatedCost value is an estimate of the cost of doing the
2930** particular lookup. A full scan of a table with N entries should have
2931** a cost of N. A binary search of a table of N entries should have a
2932** cost of approximately log(N).
2933*/
drhe09daa92006-06-10 13:29:31 +00002934struct sqlite3_index_info {
2935 /* Inputs */
drh9eff6162006-06-12 21:59:13 +00002936 const int nConstraint; /* Number of entries in aConstraint */
2937 const struct sqlite3_index_constraint {
2938 int iColumn; /* Column on left-hand side of constraint */
2939 unsigned char op; /* Constraint operator */
2940 unsigned char usable; /* True if this constraint is usable */
2941 int iTermOffset; /* Used internally - xBestIndex should ignore */
2942 } *const aConstraint; /* Table of WHERE clause constraints */
2943 const int nOrderBy; /* Number of terms in the ORDER BY clause */
2944 const struct sqlite3_index_orderby {
2945 int iColumn; /* Column number */
2946 unsigned char desc; /* True for DESC. False for ASC. */
2947 } *const aOrderBy; /* The ORDER BY clause */
drhe09daa92006-06-10 13:29:31 +00002948
2949 /* Outputs */
drh9eff6162006-06-12 21:59:13 +00002950 struct sqlite3_index_constraint_usage {
2951 int argvIndex; /* if >0, constraint is part of argv to xFilter */
2952 unsigned char omit; /* Do not code a test for this constraint */
2953 } *const aConstraintUsage;
drh4be8b512006-06-13 23:51:34 +00002954 int idxNum; /* Number used to identify the index */
2955 char *idxStr; /* String, possibly obtained from sqlite3_malloc */
2956 int needToFreeIdxStr; /* Free idxStr using sqlite3_free() if true */
drh9eff6162006-06-12 21:59:13 +00002957 int orderByConsumed; /* True if output is already ordered */
2958 double estimatedCost; /* Estimated cost of using this index */
drhe09daa92006-06-10 13:29:31 +00002959};
drh9eff6162006-06-12 21:59:13 +00002960#define SQLITE_INDEX_CONSTRAINT_EQ 2
2961#define SQLITE_INDEX_CONSTRAINT_GT 4
2962#define SQLITE_INDEX_CONSTRAINT_LE 8
2963#define SQLITE_INDEX_CONSTRAINT_LT 16
2964#define SQLITE_INDEX_CONSTRAINT_GE 32
2965#define SQLITE_INDEX_CONSTRAINT_MATCH 64
2966
2967/*
2968** This routine is used to register a new module name with an SQLite
2969** connection. Module names must be registered before creating new
2970** virtual tables on the module, or before using preexisting virtual
2971** tables of the module.
2972*/
drhb9bb7c12006-06-11 23:41:55 +00002973int sqlite3_create_module(
drh9eff6162006-06-12 21:59:13 +00002974 sqlite3 *db, /* SQLite connection to register module with */
2975 const char *zName, /* Name of the module */
danielk1977d1ab1ba2006-06-15 04:28:13 +00002976 const sqlite3_module *, /* Methods for the module */
2977 void * /* Client data for xCreate/xConnect */
drhb9bb7c12006-06-11 23:41:55 +00002978);
drhe09daa92006-06-10 13:29:31 +00002979
drh9eff6162006-06-12 21:59:13 +00002980/*
danielk1977832a58a2007-06-22 15:21:15 +00002981** This routine is identical to the sqlite3_create_module() method above,
2982** except that it allows a destructor function to be specified. It is
2983** even more experimental than the rest of the virtual tables API.
2984*/
2985int sqlite3_create_module_v2(
2986 sqlite3 *db, /* SQLite connection to register module with */
2987 const char *zName, /* Name of the module */
2988 const sqlite3_module *, /* Methods for the module */
2989 void *, /* Client data for xCreate/xConnect */
2990 void(*xDestroy)(void*) /* Module destructor function */
2991);
2992
2993/*
drh9eff6162006-06-12 21:59:13 +00002994** Every module implementation uses a subclass of the following structure
2995** to describe a particular instance of the module. Each subclass will
2996** be taylored to the specific needs of the module implementation. The
2997** purpose of this superclass is to define certain fields that are common
2998** to all module implementations.
drhfe1368e2006-09-10 17:08:29 +00002999**
3000** Virtual tables methods can set an error message by assigning a
3001** string obtained from sqlite3_mprintf() to zErrMsg. The method should
3002** take care that any prior string is freed by a call to sqlite3_free()
3003** prior to assigning a new string to zErrMsg. After the error message
3004** is delivered up to the client application, the string will be automatically
3005** freed by sqlite3_free() and the zErrMsg field will be zeroed. Note
3006** that sqlite3_mprintf() and sqlite3_free() are used on the zErrMsg field
3007** since virtual tables are commonly implemented in loadable extensions which
3008** do not have access to sqlite3MPrintf() or sqlite3Free().
drh9eff6162006-06-12 21:59:13 +00003009*/
3010struct sqlite3_vtab {
drha967e882006-06-13 01:04:52 +00003011 const sqlite3_module *pModule; /* The module for this virtual table */
danielk1977be718892006-06-23 08:05:19 +00003012 int nRef; /* Used internally */
drh4ca8aac2006-09-10 17:31:58 +00003013 char *zErrMsg; /* Error message from sqlite3_mprintf() */
drh9eff6162006-06-12 21:59:13 +00003014 /* Virtual table implementations will typically add additional fields */
3015};
3016
3017/* Every module implementation uses a subclass of the following structure
3018** to describe cursors that point into the virtual table and are used
3019** to loop through the virtual table. Cursors are created using the
3020** xOpen method of the module. Each module implementation will define
3021** the content of a cursor structure to suit its own needs.
3022**
3023** This superclass exists in order to define fields of the cursor that
3024** are common to all implementations.
3025*/
3026struct sqlite3_vtab_cursor {
3027 sqlite3_vtab *pVtab; /* Virtual table of this cursor */
3028 /* Virtual table implementations will typically add additional fields */
3029};
3030
3031/*
3032** The xCreate and xConnect methods of a module use the following API
3033** to declare the format (the names and datatypes of the columns) of
3034** the virtual tables they implement.
3035*/
danielk19777e6ebfb2006-06-12 11:24:37 +00003036int sqlite3_declare_vtab(sqlite3*, const char *zCreateTable);
drhe09daa92006-06-10 13:29:31 +00003037
3038/*
drhb7481e72006-09-16 21:45:14 +00003039** Virtual tables can provide alternative implementations of functions
3040** using the xFindFunction method. But global versions of those functions
3041** must exist in order to be overloaded.
3042**
3043** This API makes sure a global version of a function with a particular
3044** name and number of parameters exists. If no such function exists
3045** before this API is called, a new function is created. The implementation
3046** of the new function always causes an exception to be thrown. So
3047** the new function is not good for anything by itself. Its only
3048** purpose is to be a place-holder function that can be overloaded
3049** by virtual tables.
3050**
3051** This API should be considered part of the virtual table interface,
3052** which is experimental and subject to change.
3053*/
3054int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg);
3055
3056/*
drh9eff6162006-06-12 21:59:13 +00003057** The interface to the virtual-table mechanism defined above (back up
3058** to a comment remarkably similar to this one) is currently considered
3059** to be experimental. The interface might change in incompatible ways.
3060** If this is a problem for you, do not use the interface at this time.
3061**
3062** When the virtual-table mechanism stablizes, we will declare the
3063** interface fixed, support it indefinitely, and remove this comment.
3064**
3065****** EXPERIMENTAL - subject to change without notice **************
3066*/
3067
danielk19778cbadb02007-05-03 16:31:26 +00003068/*
drh6ed48bf2007-06-14 20:57:18 +00003069** CAPI3REF: A Handle To An Open BLOB
3070**
danielk19778cbadb02007-05-03 16:31:26 +00003071** An instance of the following opaque structure is used to
drh6ed48bf2007-06-14 20:57:18 +00003072** represent an blob-handle. A blob-handle is created by
3073** [sqlite3_blob_open()] and destroyed by [sqlite3_blob_close()].
3074** The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces
3075** can be used to read or write small subsections of the blob.
3076** The [sqltie3_blob_size()] interface returns the size of the
3077** blob in bytes.
danielk19778cbadb02007-05-03 16:31:26 +00003078*/
danielk1977b4e9af92007-05-01 17:49:49 +00003079typedef struct sqlite3_blob sqlite3_blob;
3080
danielk19778cbadb02007-05-03 16:31:26 +00003081/*
drh6ed48bf2007-06-14 20:57:18 +00003082** CAPI3REF: Open A BLOB For Incremental I/O
3083**
danielk19778cbadb02007-05-03 16:31:26 +00003084** Open a handle to the blob located in row iRow,, column zColumn,
3085** table zTable in database zDb. i.e. the same blob that would
3086** be selected by:
3087**
drh6ed48bf2007-06-14 20:57:18 +00003088** <pre>
3089** SELECT zColumn FROM zDb.zTable WHERE rowid = iRow;
3090** </pre>
danielk19778cbadb02007-05-03 16:31:26 +00003091**
3092** If the flags parameter is non-zero, the blob is opened for
3093** read and write access. If it is zero, the blob is opened for read
3094** access.
3095**
drh6ed48bf2007-06-14 20:57:18 +00003096** On success, [SQLITE_OK] is returned and the new
3097** [sqlite3_blob | blob handle] is written to *ppBlob.
3098** Otherwise an error code is returned and
danielk19778cbadb02007-05-03 16:31:26 +00003099** any value written to *ppBlob should not be used by the caller.
3100** This function sets the database-handle error code and message
drh6ed48bf2007-06-14 20:57:18 +00003101** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()].
danielk19778cbadb02007-05-03 16:31:26 +00003102*/
danielk1977b4e9af92007-05-01 17:49:49 +00003103int sqlite3_blob_open(
3104 sqlite3*,
3105 const char *zDb,
3106 const char *zTable,
3107 const char *zColumn,
drh6d2069d2007-08-14 01:58:53 +00003108 sqlite3_int64 iRow,
danielk1977b4e9af92007-05-01 17:49:49 +00003109 int flags,
3110 sqlite3_blob **ppBlob
3111);
3112
danielk19778cbadb02007-05-03 16:31:26 +00003113/*
drh6ed48bf2007-06-14 20:57:18 +00003114** CAPI3REF: Close A BLOB Handle
3115**
3116** Close an open [sqlite3_blob | blob handle].
danielk19778cbadb02007-05-03 16:31:26 +00003117*/
danielk1977b4e9af92007-05-01 17:49:49 +00003118int sqlite3_blob_close(sqlite3_blob *);
3119
danielk19778cbadb02007-05-03 16:31:26 +00003120/*
drh6ed48bf2007-06-14 20:57:18 +00003121** CAPI3REF: Return The Size Of An Open BLOB
3122**
danielk19778cbadb02007-05-03 16:31:26 +00003123** Return the size in bytes of the blob accessible via the open
drh6ed48bf2007-06-14 20:57:18 +00003124** [sqlite3_blob | blob-handle] passed as an argument.
danielk19778cbadb02007-05-03 16:31:26 +00003125*/
danielk1977b4e9af92007-05-01 17:49:49 +00003126int sqlite3_blob_bytes(sqlite3_blob *);
3127
drh9eff6162006-06-12 21:59:13 +00003128/*
drh6ed48bf2007-06-14 20:57:18 +00003129** CAPI3REF: Read Data From A BLOB Incrementally
3130**
3131** This function is used to read data from an open
3132** [sqlite3_blob | blob-handle] into a caller supplied buffer.
3133** n bytes of data are copied into buffer
danielk19778cbadb02007-05-03 16:31:26 +00003134** z from the open blob, starting at offset iOffset.
3135**
drh6ed48bf2007-06-14 20:57:18 +00003136** On success, SQLITE_OK is returned. Otherwise, an
3137** [SQLITE_ERROR | SQLite error code] or an
3138** [SQLITE_IOERR_READ | extended error code] is returned.
danielk19778cbadb02007-05-03 16:31:26 +00003139*/
3140int sqlite3_blob_read(sqlite3_blob *, void *z, int n, int iOffset);
3141
3142/*
drh6ed48bf2007-06-14 20:57:18 +00003143** CAPI3REF: Write Data Into A BLOB Incrementally
3144**
3145** This function is used to write data into an open
3146** [sqlite3_blob | blob-handle] from a user supplied buffer.
3147** n bytes of data are copied from the buffer
danielk19778cbadb02007-05-03 16:31:26 +00003148** pointed to by z into the open blob, starting at offset iOffset.
3149**
drh6ed48bf2007-06-14 20:57:18 +00003150** If the [sqlite3_blob | blob-handle] passed as the first argument
3151** was not opened for writing (the flags parameter to [sqlite3_blob_open()]
3152*** was zero), this function returns [SQLITE_READONLY].
danielk19778cbadb02007-05-03 16:31:26 +00003153**
3154** This function may only modify the contents of the blob, it is
3155** not possible to increase the size of a blob using this API. If
3156** offset iOffset is less than n bytes from the end of the blob,
drh6ed48bf2007-06-14 20:57:18 +00003157** [SQLITE_ERROR] is returned and no data is written.
danielk19778cbadb02007-05-03 16:31:26 +00003158**
drh6ed48bf2007-06-14 20:57:18 +00003159** On success, SQLITE_OK is returned. Otherwise, an
3160** [SQLITE_ERROR | SQLite error code] or an
3161** [SQLITE_IOERR_READ | extended error code] is returned.
danielk19778cbadb02007-05-03 16:31:26 +00003162*/
3163int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);
3164
drhd84f9462007-08-15 11:28:56 +00003165/*
3166** CAPI3REF: Virtual File System Objects
3167**
3168** A virtual filesystem (VFS) is an [sqlite3_vfs] object
3169** that SQLite uses to interact
3170** with the underlying operating system. Most builds come with a
3171** single default VFS that is appropriate for the host computer.
3172** New VFSes can be registered and existing VFSes can be unregistered.
3173** The following interfaces are provided.
3174**
drhd677b3d2007-08-20 22:48:41 +00003175** The sqlite3_vfs_find() interface returns a pointer to a VFS given its
drhd84f9462007-08-15 11:28:56 +00003176** name. Names are case sensitive. If there is no match, a NULL
3177** pointer is returned. If zVfsName is NULL then the default
drhd677b3d2007-08-20 22:48:41 +00003178** VFS is returned. If a valid VFS pointer is returned, its
3179** vfsMutex field will have been initialized and nRef will be
3180** greater than zero. The sqlite3_vfs_release() function should
3181** be used to release the VFS when it is no longer needed.
drhd84f9462007-08-15 11:28:56 +00003182**
drhd677b3d2007-08-20 22:48:41 +00003183** New VFSes are registered with sqlite3_vfs_register(). Each
drhd84f9462007-08-15 11:28:56 +00003184** new VFS becomes the default VFS if the makeDflt flag is set.
3185** The same VFS can be registered multiple times without injury.
3186** To make an existing VFS into the default VFS, register it again
3187** with the makeDflt flag set.
3188**
drhd677b3d2007-08-20 22:48:41 +00003189** Unregister a VFS with the sqlite3_vfs_unregister() interface.
drhd84f9462007-08-15 11:28:56 +00003190** If the default VFS is unregistered, another VFS is chosen as
3191** the default. The choice for the new VFS is arbitrary.
3192*/
drhd677b3d2007-08-20 22:48:41 +00003193sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName);
3194int sqlite3_vfs_release(sqlite3_vfs*);
3195int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);
3196int sqlite3_vfs_unregister(sqlite3_vfs*);
drhd84f9462007-08-15 11:28:56 +00003197
3198/*
3199** CAPI3REF: Mutexes
3200**
3201** The SQLite core uses these routines for thread
3202** synchronization. Though they are intended for internal
3203** use by SQLite, code that links against SQLite is
3204** permitted to use any of these routines.
3205**
3206** The SQLite source code contains multiple implementations
3207** of these mutex routines that can be selected at compile-time
3208** by defining one of the following C preprocessor macros:
3209**
3210** <ul>
3211** <li> SQLITE_MUTEX_PTHREAD
3212** <li> SQLITE_MUTEX_WIN32
3213** <li> SQLITE_MUTEX_NOOP
3214** <li> SQLITE_MUTEX_APPDEF
3215** </ul>
3216**
3217** If none of the above macros is defined, the code uses
3218** a default implementation.
3219**
3220** The SQLITE_MUTEX_NOOP implementation is a set of routines
3221** that does no real locking and is appropriate for use in
3222** a single-threaded application.
3223**
3224** If the SQLITE_MUTEX_APPDEF is defined, then no mutex
3225** implementation is included with the library. The
3226** mutex interface routines defined above are external
3227** references in the SQLite library for which implementations
3228** must be provided by the application.
3229**
3230** The sqlite3_mutex_alloc() routine allocates a new
3231** mutex and returns a pointer to it. If it returns NULL
3232** that means that a mutex could not be allocated. SQLite
3233** will unwind its stack and return an error. The argument
drh6bdec4a2007-08-16 19:40:16 +00003234** to sqlite3_mutex_alloc() is one of these integer constants:
3235**
3236** <ul>
3237** <li> SQLITE_MUTEX_FAST
3238** <li> SQLITE_MUTEX_RECURSIVE
3239** <li> SQLITE_MUTEX_STATIC_MASTER
3240** <li> SQLITE_MUTEX_STATIC_MEM
3241** <li> SQLITE_MUTEX_STATIC_PRNG
3242** </ul>
3243**
3244** The first two constants cause sqlite3_mutex_alloc() to create
3245** a new mutex. The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
3246** is used but not necessarily so when SQLITE_MUTEX_FAST is used.
3247** The mutex implementation does not need to make a distinction
3248** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does
3249** not want to. But SQLite will only request a recursive mutex in
3250** cases where it really needs one. If a faster non-recursive mutex
3251** implementation is available on the host platform, the mutex subsystem
3252** might return such a mutex in response to SQLITE_MUTEX_FAST.
3253**
3254** The other allowed parameters to sqlite3_mutex_alloc() each return
3255** a pointer to a static preexisting mutex. Three static mutexes are
3256** used by the current version of SQLite. Future versions of SQLite
3257** may add additional static mutexes. Static mutexes are for internal
3258** use by SQLite only. Applications that use SQLite mutexes should
3259** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or
3260** SQLITE_MUTEX_RECURSIVE.
3261**
3262** Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST
3263** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
3264** returns a different mutex on every call. But for the static
3265** mutex types, the same mutex is returned on every call that has
3266** the same type number.
drhd84f9462007-08-15 11:28:56 +00003267**
3268** The sqlite3_mutex_free() routine deallocates a previously
drh6bdec4a2007-08-16 19:40:16 +00003269** allocated dynamic mutex. SQLite is careful to deallocate every
3270** dynamic mutex that it allocates. The dynamic mutexes must not be in
drhe53831d2007-08-17 01:14:38 +00003271** use when they are deallocated. Attempting to deallocate a static
3272** mutex results in undefined behavior. SQLite never deallocates
3273** a static mutex.
drhd84f9462007-08-15 11:28:56 +00003274**
drh6bdec4a2007-08-16 19:40:16 +00003275** The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt
3276** to enter a mutex. If another thread is already within the mutex,
3277** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return
3278** SQLITE_BUSY. The sqlite3_mutex_try() interface returns SQLITE_OK
3279** upon successful entry. Mutexes created using SQLITE_MUTEX_RECURSIVE can
3280** be entered multiple times by the same thread. In such cases the,
3281** mutex must be exited an equal number of times before another thread
3282** can enter. If the same thread tries to enter any other kind of mutex
3283** more than once, the behavior is undefined. SQLite will never exhibit
3284** such behavior in its own use of mutexes.
drhd84f9462007-08-15 11:28:56 +00003285**
3286** The sqlite3_mutex_exit() routine exits a mutex that was
3287** previously entered by the same thread. The behavior
3288** is undefined if the mutex is not currently entered or
3289** is not currently allocated. SQLite will never do either.
drhd677b3d2007-08-20 22:48:41 +00003290**
3291** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines
3292** are intended for use inside assert() statements. They should
3293** return true if the mutex in their argument is held or not held,
3294** respectively, by the current thread. The implementation is
3295** not required to provided working implementations of these
3296** routines as their intended use is within assert() statements
3297** only. If the implementation does not provide working
3298** versions of these routines, it must at least provide stubs
3299** that always return true.
3300**
3301** If the argument to sqlite3_mutex_held() is a NULL pointer then
3302** the routine should return 1. This seems counter-intuitive since
3303** clearly the mutex cannot be held if it does not exist. But the
3304** the reason the mutex does not exist is because the build is not
3305** using mutexes. And we do not want the assert() containing the
3306** call to sqlite3_mutex_held() to fail, so a non-zero return is
3307** the appropriate thing to do. The sqlite3_mutex_notheld()
3308** interface should also return 1 when given a NULL pointer.
drhd84f9462007-08-15 11:28:56 +00003309*/
3310sqlite3_mutex *sqlite3_mutex_alloc(int);
3311void sqlite3_mutex_free(sqlite3_mutex*);
drh6bdec4a2007-08-16 19:40:16 +00003312void sqlite3_mutex_enter(sqlite3_mutex*);
3313int sqlite3_mutex_try(sqlite3_mutex*);
drhd84f9462007-08-15 11:28:56 +00003314void sqlite3_mutex_leave(sqlite3_mutex*);
drhd677b3d2007-08-20 22:48:41 +00003315int sqlite3_mutex_held(sqlite3_mutex*);
3316int sqlite3_mutex_notheld(sqlite3_mutex*);
drh6bdec4a2007-08-16 19:40:16 +00003317#define SQLITE_MUTEX_FAST 0
3318#define SQLITE_MUTEX_RECURSIVE 1
3319#define SQLITE_MUTEX_STATIC_MASTER 2
3320#define SQLITE_MUTEX_STATIC_MEM 3
3321#define SQLITE_MUTEX_STATIC_PRNG 4
drh6d2069d2007-08-14 01:58:53 +00003322
3323
danielk19778cbadb02007-05-03 16:31:26 +00003324/*
drhb37df7b2005-10-13 02:09:49 +00003325** Undo the hack that converts floating point types to integer for
3326** builds on processors without floating point support.
3327*/
3328#ifdef SQLITE_OMIT_FLOATING_POINT
3329# undef double
3330#endif
3331
drh382c0242001-10-06 16:33:02 +00003332#ifdef __cplusplus
3333} /* End of the 'extern "C"' block */
3334#endif
danielk19774adee202004-05-08 08:23:19 +00003335#endif