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