Annotation of win32/sql/sqlite/include/sqlite3.h, revision 1.1
1.1 ! misha 1: /*
! 2: ** 2001 September 15
! 3: **
! 4: ** The author disclaims copyright to this source code. In place of
! 5: ** a legal notice, here is a blessing:
! 6: **
! 7: ** May you do good and not evil.
! 8: ** May you find forgiveness for yourself and forgive others.
! 9: ** May you share freely, never taking more than you give.
! 10: **
! 11: *************************************************************************
! 12: ** This header file defines the interface that the SQLite library
! 13: ** presents to client programs.
! 14: **
! 15: ** @(#) $Id: sqlite.h.in,v 1.121 2004/10/06 15:52:01 drh Exp $
! 16: */
! 17: #ifndef _SQLITE3_H_
! 18: #define _SQLITE3_H_
! 19: #include <stdarg.h> /* Needed for the definition of va_list */
! 20:
! 21: /*
! 22: ** Make sure we can call this stuff from C++.
! 23: */
! 24: #ifdef __cplusplus
! 25: extern "C" {
! 26: #endif
! 27:
! 28: /*
! 29: ** The version of the SQLite library.
! 30: */
! 31: #ifdef SQLITE_VERSION
! 32: # undef SQLITE_VERSION
! 33: #else
! 34: # define SQLITE_VERSION "3.0.8"
! 35: #endif
! 36:
! 37: /*
! 38: ** The version string is also compiled into the library so that a program
! 39: ** can check to make sure that the lib*.a file and the *.h file are from
! 40: ** the same version. The sqlite3_libversion() function returns a pointer
! 41: ** to the sqlite3_version variable - useful in DLLs which cannot access
! 42: ** global variables.
! 43: */
! 44: extern const char sqlite3_version[];
! 45: const char *sqlite3_libversion(void);
! 46:
! 47: /*
! 48: ** Each open sqlite database is represented by an instance of the
! 49: ** following opaque structure.
! 50: */
! 51: typedef struct sqlite3 sqlite3;
! 52:
! 53:
! 54: /*
! 55: ** Some compilers do not support the "long long" datatype. So we have
! 56: ** to do a typedef that for 64-bit integers that depends on what compiler
! 57: ** is being used.
! 58: */
! 59: #if defined(_MSC_VER) || defined(__BORLANDC__)
! 60: typedef __int64 sqlite_int64;
! 61: typedef unsigned __int64 sqlite_uint64;
! 62: #else
! 63: typedef long long int sqlite_int64;
! 64: typedef unsigned long long int sqlite_uint64;
! 65: #endif
! 66:
! 67:
! 68: /*
! 69: ** A function to close the database.
! 70: **
! 71: ** Call this function with a pointer to a structure that was previously
! 72: ** returned from sqlite3_open() and the corresponding database will by closed.
! 73: **
! 74: ** All SQL statements prepared using sqlite3_prepare() or
! 75: ** sqlite3_prepare16() must be deallocated using sqlite3_finalize() before
! 76: ** this routine is called. Otherwise, SQLITE_BUSY is returned and the
! 77: ** database connection remains open.
! 78: */
! 79: int sqlite3_close(sqlite3 *);
! 80:
! 81: /*
! 82: ** The type for a callback function.
! 83: */
! 84: typedef int (*sqlite3_callback)(void*,int,char**, char**);
! 85:
! 86: /*
! 87: ** A function to executes one or more statements of SQL.
! 88: **
! 89: ** If one or more of the SQL statements are queries, then
! 90: ** the callback function specified by the 3rd parameter is
! 91: ** invoked once for each row of the query result. This callback
! 92: ** should normally return 0. If the callback returns a non-zero
! 93: ** value then the query is aborted, all subsequent SQL statements
! 94: ** are skipped and the sqlite3_exec() function returns the SQLITE_ABORT.
! 95: **
! 96: ** The 4th parameter is an arbitrary pointer that is passed
! 97: ** to the callback function as its first parameter.
! 98: **
! 99: ** The 2nd parameter to the callback function is the number of
! 100: ** columns in the query result. The 3rd parameter to the callback
! 101: ** is an array of strings holding the values for each column.
! 102: ** The 4th parameter to the callback is an array of strings holding
! 103: ** the names of each column.
! 104: **
! 105: ** The callback function may be NULL, even for queries. A NULL
! 106: ** callback is not an error. It just means that no callback
! 107: ** will be invoked.
! 108: **
! 109: ** If an error occurs while parsing or evaluating the SQL (but
! 110: ** not while executing the callback) then an appropriate error
! 111: ** message is written into memory obtained from malloc() and
! 112: ** *errmsg is made to point to that message. The calling function
! 113: ** is responsible for freeing the memory that holds the error
! 114: ** message. Use sqlite3_free() for this. If errmsg==NULL,
! 115: ** then no error message is ever written.
! 116: **
! 117: ** The return value is is SQLITE_OK if there are no errors and
! 118: ** some other return code if there is an error. The particular
! 119: ** return value depends on the type of error.
! 120: **
! 121: ** If the query could not be executed because a database file is
! 122: ** locked or busy, then this function returns SQLITE_BUSY. (This
! 123: ** behavior can be modified somewhat using the sqlite3_busy_handler()
! 124: ** and sqlite3_busy_timeout() functions below.)
! 125: */
! 126: int sqlite3_exec(
! 127: sqlite3*, /* An open database */
! 128: const char *sql, /* SQL to be executed */
! 129: sqlite3_callback, /* Callback function */
! 130: void *, /* 1st argument to callback function */
! 131: char **errmsg /* Error msg written here */
! 132: );
! 133:
! 134: /*
! 135: ** Return values for sqlite3_exec() and sqlite3_step()
! 136: */
! 137: #define SQLITE_OK 0 /* Successful result */
! 138: #define SQLITE_ERROR 1 /* SQL error or missing database */
! 139: #define SQLITE_INTERNAL 2 /* An internal logic error in SQLite */
! 140: #define SQLITE_PERM 3 /* Access permission denied */
! 141: #define SQLITE_ABORT 4 /* Callback routine requested an abort */
! 142: #define SQLITE_BUSY 5 /* The database file is locked */
! 143: #define SQLITE_LOCKED 6 /* A table in the database is locked */
! 144: #define SQLITE_NOMEM 7 /* A malloc() failed */
! 145: #define SQLITE_READONLY 8 /* Attempt to write a readonly database */
! 146: #define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite3_interrupt()*/
! 147: #define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */
! 148: #define SQLITE_CORRUPT 11 /* The database disk image is malformed */
! 149: #define SQLITE_NOTFOUND 12 /* (Internal Only) Table or record not found */
! 150: #define SQLITE_FULL 13 /* Insertion failed because database is full */
! 151: #define SQLITE_CANTOPEN 14 /* Unable to open the database file */
! 152: #define SQLITE_PROTOCOL 15 /* Database lock protocol error */
! 153: #define SQLITE_EMPTY 16 /* Database is empty */
! 154: #define SQLITE_SCHEMA 17 /* The database schema changed */
! 155: #define SQLITE_TOOBIG 18 /* Too much data for one row of a table */
! 156: #define SQLITE_CONSTRAINT 19 /* Abort due to contraint violation */
! 157: #define SQLITE_MISMATCH 20 /* Data type mismatch */
! 158: #define SQLITE_MISUSE 21 /* Library used incorrectly */
! 159: #define SQLITE_NOLFS 22 /* Uses OS features not supported on host */
! 160: #define SQLITE_AUTH 23 /* Authorization denied */
! 161: #define SQLITE_FORMAT 24 /* Auxiliary database format error */
! 162: #define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */
! 163: #define SQLITE_NOTADB 26 /* File opened that is not a database file */
! 164: #define SQLITE_ROW 100 /* sqlite3_step() has another row ready */
! 165: #define SQLITE_DONE 101 /* sqlite3_step() has finished executing */
! 166:
! 167: /*
! 168: ** Each entry in an SQLite table has a unique integer key. (The key is
! 169: ** the value of the INTEGER PRIMARY KEY column if there is such a column,
! 170: ** otherwise the key is generated at random. The unique key is always
! 171: ** available as the ROWID, OID, or _ROWID_ column.) The following routine
! 172: ** returns the integer key of the most recent insert in the database.
! 173: **
! 174: ** This function is similar to the mysql_insert_id() function from MySQL.
! 175: */
! 176: sqlite_int64 sqlite3_last_insert_rowid(sqlite3*);
! 177:
! 178: /*
! 179: ** This function returns the number of database rows that were changed
! 180: ** (or inserted or deleted) by the most recent called sqlite3_exec().
! 181: **
! 182: ** All changes are counted, even if they were later undone by a
! 183: ** ROLLBACK or ABORT. Except, changes associated with creating and
! 184: ** dropping tables are not counted.
! 185: **
! 186: ** If a callback invokes sqlite3_exec() recursively, then the changes
! 187: ** in the inner, recursive call are counted together with the changes
! 188: ** in the outer call.
! 189: **
! 190: ** SQLite implements the command "DELETE FROM table" without a WHERE clause
! 191: ** by dropping and recreating the table. (This is much faster than going
! 192: ** through and deleting individual elements form the table.) Because of
! 193: ** this optimization, the change count for "DELETE FROM table" will be
! 194: ** zero regardless of the number of elements that were originally in the
! 195: ** table. To get an accurate count of the number of rows deleted, use
! 196: ** "DELETE FROM table WHERE 1" instead.
! 197: */
! 198: int sqlite3_changes(sqlite3*);
! 199:
! 200: /*
! 201: ** This function returns the number of database rows that have been
! 202: ** modified by INSERT, UPDATE or DELETE statements since the database handle
! 203: ** was opened. This includes UPDATE, INSERT and DELETE statements executed
! 204: ** as part of trigger programs. All changes are counted as soon as the
! 205: ** statement that makes them is completed (when the statement handle is
! 206: ** passed to sqlite3_reset() or sqlite_finalise()).
! 207: **
! 208: ** SQLite implements the command "DELETE FROM table" without a WHERE clause
! 209: ** by dropping and recreating the table. (This is much faster than going
! 210: ** through and deleting individual elements form the table.) Because of
! 211: ** this optimization, the change count for "DELETE FROM table" will be
! 212: ** zero regardless of the number of elements that were originally in the
! 213: ** table. To get an accurate count of the number of rows deleted, use
! 214: ** "DELETE FROM table WHERE 1" instead.
! 215: */
! 216: int sqlite3_total_changes(sqlite3*);
! 217:
! 218: /* This function causes any pending database operation to abort and
! 219: ** return at its earliest opportunity. This routine is typically
! 220: ** called in response to a user action such as pressing "Cancel"
! 221: ** or Ctrl-C where the user wants a long query operation to halt
! 222: ** immediately.
! 223: */
! 224: void sqlite3_interrupt(sqlite3*);
! 225:
! 226:
! 227: /* These functions return true if the given input string comprises
! 228: ** one or more complete SQL statements. For the sqlite3_complete() call,
! 229: ** the parameter must be a nul-terminated UTF-8 string. For
! 230: ** sqlite3_complete16(), a nul-terminated machine byte order UTF-16 string
! 231: ** is required.
! 232: **
! 233: ** The algorithm is simple. If the last token other than spaces
! 234: ** and comments is a semicolon, then return true. otherwise return
! 235: ** false.
! 236: */
! 237: int sqlite3_complete(const char *sql);
! 238: int sqlite3_complete16(const void *sql);
! 239:
! 240: /*
! 241: ** This routine identifies a callback function that is invoked
! 242: ** whenever an attempt is made to open a database table that is
! 243: ** currently locked by another process or thread. If the busy callback
! 244: ** is NULL, then sqlite3_exec() returns SQLITE_BUSY immediately if
! 245: ** it finds a locked table. If the busy callback is not NULL, then
! 246: ** sqlite3_exec() invokes the callback with three arguments. The
! 247: ** second argument is the name of the locked table and the third
! 248: ** argument is the number of times the table has been busy. If the
! 249: ** busy callback returns 0, then sqlite3_exec() immediately returns
! 250: ** SQLITE_BUSY. If the callback returns non-zero, then sqlite3_exec()
! 251: ** tries to open the table again and the cycle repeats.
! 252: **
! 253: ** The default busy callback is NULL.
! 254: **
! 255: ** Sqlite is re-entrant, so the busy handler may start a new query.
! 256: ** (It is not clear why anyone would every want to do this, but it
! 257: ** is allowed, in theory.) But the busy handler may not close the
! 258: ** database. Closing the database from a busy handler will delete
! 259: ** data structures out from under the executing query and will
! 260: ** probably result in a coredump.
! 261: */
! 262: int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
! 263:
! 264: /*
! 265: ** This routine sets a busy handler that sleeps for a while when a
! 266: ** table is locked. The handler will sleep multiple times until
! 267: ** at least "ms" milleseconds of sleeping have been done. After
! 268: ** "ms" milleseconds of sleeping, the handler returns 0 which
! 269: ** causes sqlite3_exec() to return SQLITE_BUSY.
! 270: **
! 271: ** Calling this routine with an argument less than or equal to zero
! 272: ** turns off all busy handlers.
! 273: */
! 274: int sqlite3_busy_timeout(sqlite3*, int ms);
! 275:
! 276: /*
! 277: ** This next routine is really just a wrapper around sqlite3_exec().
! 278: ** Instead of invoking a user-supplied callback for each row of the
! 279: ** result, this routine remembers each row of the result in memory
! 280: ** obtained from malloc(), then returns all of the result after the
! 281: ** query has finished.
! 282: **
! 283: ** As an example, suppose the query result where this table:
! 284: **
! 285: ** Name | Age
! 286: ** -----------------------
! 287: ** Alice | 43
! 288: ** Bob | 28
! 289: ** Cindy | 21
! 290: **
! 291: ** If the 3rd argument were &azResult then after the function returns
! 292: ** azResult will contain the following data:
! 293: **
! 294: ** azResult[0] = "Name";
! 295: ** azResult[1] = "Age";
! 296: ** azResult[2] = "Alice";
! 297: ** azResult[3] = "43";
! 298: ** azResult[4] = "Bob";
! 299: ** azResult[5] = "28";
! 300: ** azResult[6] = "Cindy";
! 301: ** azResult[7] = "21";
! 302: **
! 303: ** Notice that there is an extra row of data containing the column
! 304: ** headers. But the *nrow return value is still 3. *ncolumn is
! 305: ** set to 2. In general, the number of values inserted into azResult
! 306: ** will be ((*nrow) + 1)*(*ncolumn).
! 307: **
! 308: ** After the calling function has finished using the result, it should
! 309: ** pass the result data pointer to sqlite3_free_table() in order to
! 310: ** release the memory that was malloc-ed. Because of the way the
! 311: ** malloc() happens, the calling function must not try to call
! 312: ** malloc() directly. Only sqlite3_free_table() is able to release
! 313: ** the memory properly and safely.
! 314: **
! 315: ** The return value of this routine is the same as from sqlite3_exec().
! 316: */
! 317: int sqlite3_get_table(
! 318: sqlite3*, /* An open database */
! 319: const char *sql, /* SQL to be executed */
! 320: char ***resultp, /* Result written to a char *[] that this points to */
! 321: int *nrow, /* Number of result rows written here */
! 322: int *ncolumn, /* Number of result columns written here */
! 323: char **errmsg /* Error msg written here */
! 324: );
! 325:
! 326: /*
! 327: ** Call this routine to free the memory that sqlite3_get_table() allocated.
! 328: */
! 329: void sqlite3_free_table(char **result);
! 330:
! 331: /*
! 332: ** The following routines are variants of the "sprintf()" from the
! 333: ** standard C library. The resulting string is written into memory
! 334: ** obtained from malloc() so that there is never a possiblity of buffer
! 335: ** overflow. These routines also implement some additional formatting
! 336: ** options that are useful for constructing SQL statements.
! 337: **
! 338: ** The strings returned by these routines should be freed by calling
! 339: ** sqlite3_free().
! 340: **
! 341: ** All of the usual printf formatting options apply. In addition, there
! 342: ** is a "%q" option. %q works like %s in that it substitutes a null-terminated
! 343: ** string from the argument list. But %q also doubles every '\'' character.
! 344: ** %q is designed for use inside a string literal. By doubling each '\''
! 345: ** character it escapes that character and allows it to be inserted into
! 346: ** the string.
! 347: **
! 348: ** For example, so some string variable contains text as follows:
! 349: **
! 350: ** char *zText = "It's a happy day!";
! 351: **
! 352: ** We can use this text in an SQL statement as follows:
! 353: **
! 354: ** sqlite3_exec_printf(db, "INSERT INTO table VALUES('%q')",
! 355: ** callback1, 0, 0, zText);
! 356: **
! 357: ** Because the %q format string is used, the '\'' character in zText
! 358: ** is escaped and the SQL generated is as follows:
! 359: **
! 360: ** INSERT INTO table1 VALUES('It''s a happy day!')
! 361: **
! 362: ** This is correct. Had we used %s instead of %q, the generated SQL
! 363: ** would have looked like this:
! 364: **
! 365: ** INSERT INTO table1 VALUES('It's a happy day!');
! 366: **
! 367: ** This second example is an SQL syntax error. As a general rule you
! 368: ** should always use %q instead of %s when inserting text into a string
! 369: ** literal.
! 370: */
! 371: char *sqlite3_mprintf(const char*,...);
! 372: char *sqlite3_vmprintf(const char*, va_list);
! 373: void sqlite3_free(char *z);
! 374: char *sqlite3_snprintf(int,char*,const char*, ...);
! 375:
! 376: #ifndef SQLITE_OMIT_AUTHORIZATION
! 377: /*
! 378: ** This routine registers a callback with the SQLite library. The
! 379: ** callback is invoked (at compile-time, not at run-time) for each
! 380: ** attempt to access a column of a table in the database. The callback
! 381: ** returns SQLITE_OK if access is allowed, SQLITE_DENY if the entire
! 382: ** SQL statement should be aborted with an error and SQLITE_IGNORE
! 383: ** if the column should be treated as a NULL value.
! 384: */
! 385: int sqlite3_set_authorizer(
! 386: sqlite3*,
! 387: int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
! 388: void *pUserData
! 389: );
! 390: #endif
! 391:
! 392: /*
! 393: ** The second parameter to the access authorization function above will
! 394: ** be one of the values below. These values signify what kind of operation
! 395: ** is to be authorized. The 3rd and 4th parameters to the authorization
! 396: ** function will be parameters or NULL depending on which of the following
! 397: ** codes is used as the second parameter. The 5th parameter is the name
! 398: ** of the database ("main", "temp", etc.) if applicable. The 6th parameter
! 399: ** is the name of the inner-most trigger or view that is responsible for
! 400: ** the access attempt or NULL if this access attempt is directly from
! 401: ** input SQL code.
! 402: **
! 403: ** Arg-3 Arg-4
! 404: */
! 405: #define SQLITE_COPY 0 /* Table Name File Name */
! 406: #define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */
! 407: #define SQLITE_CREATE_TABLE 2 /* Table Name NULL */
! 408: #define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */
! 409: #define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */
! 410: #define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */
! 411: #define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */
! 412: #define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */
! 413: #define SQLITE_CREATE_VIEW 8 /* View Name NULL */
! 414: #define SQLITE_DELETE 9 /* Table Name NULL */
! 415: #define SQLITE_DROP_INDEX 10 /* Index Name Table Name */
! 416: #define SQLITE_DROP_TABLE 11 /* Table Name NULL */
! 417: #define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */
! 418: #define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */
! 419: #define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */
! 420: #define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */
! 421: #define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */
! 422: #define SQLITE_DROP_VIEW 17 /* View Name NULL */
! 423: #define SQLITE_INSERT 18 /* Table Name NULL */
! 424: #define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */
! 425: #define SQLITE_READ 20 /* Table Name Column Name */
! 426: #define SQLITE_SELECT 21 /* NULL NULL */
! 427: #define SQLITE_TRANSACTION 22 /* NULL NULL */
! 428: #define SQLITE_UPDATE 23 /* Table Name Column Name */
! 429: #define SQLITE_ATTACH 24 /* Filename NULL */
! 430: #define SQLITE_DETACH 25 /* Database Name NULL */
! 431:
! 432:
! 433: /*
! 434: ** The return value of the authorization function should be one of the
! 435: ** following constants:
! 436: */
! 437: /* #define SQLITE_OK 0 // Allow access (This is actually defined above) */
! 438: #define SQLITE_DENY 1 /* Abort the SQL statement with an error */
! 439: #define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */
! 440:
! 441: /*
! 442: ** Register a function that is called at every invocation of sqlite3_exec()
! 443: ** or sqlite3_prepare(). This function can be used (for example) to generate
! 444: ** a log file of all SQL executed against a database.
! 445: */
! 446: void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
! 447:
! 448: /*
! 449: ** This routine configures a callback function - the progress callback - that
! 450: ** is invoked periodically during long running calls to sqlite3_exec(),
! 451: ** sqlite3_step() and sqlite3_get_table(). An example use for this API is to keep
! 452: ** a GUI updated during a large query.
! 453: **
! 454: ** The progress callback is invoked once for every N virtual machine opcodes,
! 455: ** where N is the second argument to this function. The progress callback
! 456: ** itself is identified by the third argument to this function. The fourth
! 457: ** argument to this function is a void pointer passed to the progress callback
! 458: ** function each time it is invoked.
! 459: **
! 460: ** If a call to sqlite3_exec(), sqlite3_step() or sqlite3_get_table() results
! 461: ** in less than N opcodes being executed, then the progress callback is not
! 462: ** invoked.
! 463: **
! 464: ** To remove the progress callback altogether, pass NULL as the third
! 465: ** argument to this function.
! 466: **
! 467: ** If the progress callback returns a result other than 0, then the current
! 468: ** query is immediately terminated and any database changes rolled back. If the
! 469: ** query was part of a larger transaction, then the transaction is not rolled
! 470: ** back and remains active. The sqlite3_exec() call returns SQLITE_ABORT.
! 471: **
! 472: ******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
! 473: */
! 474: void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
! 475:
! 476: /*
! 477: ** Register a callback function to be invoked whenever a new transaction
! 478: ** is committed. The pArg argument is passed through to the callback.
! 479: ** callback. If the callback function returns non-zero, then the commit
! 480: ** is converted into a rollback.
! 481: **
! 482: ** If another function was previously registered, its pArg value is returned.
! 483: ** Otherwise NULL is returned.
! 484: **
! 485: ** Registering a NULL function disables the callback.
! 486: **
! 487: ******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
! 488: */
! 489: void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
! 490:
! 491: /*
! 492: ** Open the sqlite database file "filename". The "filename" is UTF-8
! 493: ** encoded for sqlite3_open() and UTF-16 encoded in the native byte order
! 494: ** for sqlite3_open16(). An sqlite3* handle is returned in *ppDb, even
! 495: ** if an error occurs. If the database is opened (or created) successfully,
! 496: ** then SQLITE_OK is returned. Otherwise an error code is returned. The
! 497: ** sqlite3_errmsg() or sqlite3_errmsg16() routines can be used to obtain
! 498: ** an English language description of the error.
! 499: **
! 500: ** If the database file does not exist, then a new database is created.
! 501: ** The encoding for the database is UTF-8 if sqlite3_open() is called and
! 502: ** UTF-16 if sqlite3_open16 is used.
! 503: **
! 504: ** Whether or not an error occurs when it is opened, resources associated
! 505: ** with the sqlite3* handle should be released by passing it to
! 506: ** sqlite3_close() when it is no longer required.
! 507: */
! 508: int sqlite3_open(
! 509: const char *filename, /* Database filename (UTF-8) */
! 510: sqlite3 **ppDb /* OUT: SQLite db handle */
! 511: );
! 512: int sqlite3_open16(
! 513: const void *filename, /* Database filename (UTF-16) */
! 514: sqlite3 **ppDb /* OUT: SQLite db handle */
! 515: );
! 516:
! 517: /*
! 518: ** Return the error code for the most recent sqlite3_* API call associated
! 519: ** with sqlite3 handle 'db'. SQLITE_OK is returned if the most recent
! 520: ** API call was successful.
! 521: **
! 522: ** Calls to many sqlite3_* functions set the error code and string returned
! 523: ** by sqlite3_errcode(), sqlite3_errmsg() and sqlite3_errmsg16()
! 524: ** (overwriting the previous values). Note that calls to sqlite3_errcode(),
! 525: ** sqlite3_errmsg() and sqlite3_errmsg16() themselves do not affect the
! 526: ** results of future invocations.
! 527: **
! 528: ** Assuming no other intervening sqlite3_* API calls are made, the error
! 529: ** code returned by this function is associated with the same error as
! 530: ** the strings returned by sqlite3_errmsg() and sqlite3_errmsg16().
! 531: */
! 532: int sqlite3_errcode(sqlite3 *db);
! 533:
! 534: /*
! 535: ** Return a pointer to a UTF-8 encoded string describing in english the
! 536: ** error condition for the most recent sqlite3_* API call. The returned
! 537: ** string is always terminated by an 0x00 byte.
! 538: **
! 539: ** The string "not an error" is returned when the most recent API call was
! 540: ** successful.
! 541: */
! 542: const char *sqlite3_errmsg(sqlite3*);
! 543:
! 544: /*
! 545: ** Return a pointer to a UTF-16 native byte order encoded string describing
! 546: ** in english the error condition for the most recent sqlite3_* API call.
! 547: ** The returned string is always terminated by a pair of 0x00 bytes.
! 548: **
! 549: ** The string "not an error" is returned when the most recent API call was
! 550: ** successful.
! 551: */
! 552: const void *sqlite3_errmsg16(sqlite3*);
! 553:
! 554: /*
! 555: ** An instance of the following opaque structure is used to represent
! 556: ** a compiled SQL statment.
! 557: */
! 558: typedef struct sqlite3_stmt sqlite3_stmt;
! 559:
! 560: /*
! 561: ** To execute an SQL query, it must first be compiled into a byte-code
! 562: ** program using one of the following routines. The only difference between
! 563: ** them is that the second argument, specifying the SQL statement to
! 564: ** compile, is assumed to be encoded in UTF-8 for the sqlite3_prepare()
! 565: ** function and UTF-16 for sqlite3_prepare16().
! 566: **
! 567: ** The first parameter "db" is an SQLite database handle. The second
! 568: ** parameter "zSql" is the statement to be compiled, encoded as either
! 569: ** UTF-8 or UTF-16 (see above). If the next parameter, "nBytes", is less
! 570: ** than zero, then zSql is read up to the first nul terminator. If
! 571: ** "nBytes" is not less than zero, then it is the length of the string zSql
! 572: ** in bytes (not characters).
! 573: **
! 574: ** *pzTail is made to point to the first byte past the end of the first
! 575: ** SQL statement in zSql. This routine only compiles the first statement
! 576: ** in zSql, so *pzTail is left pointing to what remains uncompiled.
! 577: **
! 578: ** *ppStmt is left pointing to a compiled SQL statement that can be
! 579: ** executed using sqlite3_step(). Or if there is an error, *ppStmt may be
! 580: ** set to NULL. If the input text contained no SQL (if the input is and
! 581: ** empty string or a comment) then *ppStmt is set to NULL.
! 582: **
! 583: ** On success, SQLITE_OK is returned. Otherwise an error code is returned.
! 584: */
! 585: int sqlite3_prepare(
! 586: sqlite3 *db, /* Database handle */
! 587: const char *zSql, /* SQL statement, UTF-8 encoded */
! 588: int nBytes, /* Length of zSql in bytes. */
! 589: sqlite3_stmt **ppStmt, /* OUT: Statement handle */
! 590: const char **pzTail /* OUT: Pointer to unused portion of zSql */
! 591: );
! 592: int sqlite3_prepare16(
! 593: sqlite3 *db, /* Database handle */
! 594: const void *zSql, /* SQL statement, UTF-16 encoded */
! 595: int nBytes, /* Length of zSql in bytes. */
! 596: sqlite3_stmt **ppStmt, /* OUT: Statement handle */
! 597: const void **pzTail /* OUT: Pointer to unused portion of zSql */
! 598: );
! 599:
! 600: /*
! 601: ** Pointers to the following two opaque structures are used to communicate
! 602: ** with the implementations of user-defined functions.
! 603: */
! 604: typedef struct sqlite3_context sqlite3_context;
! 605: typedef struct Mem sqlite3_value;
! 606:
! 607: /*
! 608: ** In the SQL strings input to sqlite3_prepare() and sqlite3_prepare16(),
! 609: ** one or more literals can be replace by a wildcard "?" or ":N:" where
! 610: ** N is an integer. These value of these wildcard literals can be set
! 611: ** using the routines listed below.
! 612: **
! 613: ** In every case, the first parameter is a pointer to the sqlite3_stmt
! 614: ** structure returned from sqlite3_prepare(). The second parameter is the
! 615: ** index of the wildcard. The first "?" has an index of 1. ":N:" wildcards
! 616: ** use the index N.
! 617: **
! 618: ** The fifth parameter to sqlite3_bind_blob(), sqlite3_bind_text(), and
! 619: ** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or
! 620: ** text after SQLite has finished with it. If the fifth argument is the
! 621: ** special value SQLITE_STATIC, then the library assumes that the information
! 622: ** is in static, unmanaged space and does not need to be freed. If the
! 623: ** fifth argument has the value SQLITE_TRANSIENT, then SQLite makes its
! 624: ** own private copy of the data.
! 625: **
! 626: ** The sqlite3_bind_* routine must be called before sqlite3_step() after
! 627: ** an sqlite3_prepare() or sqlite3_reset(). Unbound wildcards are interpreted
! 628: ** as NULL.
! 629: */
! 630: int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
! 631: int sqlite3_bind_double(sqlite3_stmt*, int, double);
! 632: int sqlite3_bind_int(sqlite3_stmt*, int, int);
! 633: int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite_int64);
! 634: int sqlite3_bind_null(sqlite3_stmt*, int);
! 635: int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
! 636: int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
! 637: int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
! 638:
! 639: /*
! 640: ** Return the number of wildcards in a compiled SQL statement. This
! 641: ** routine was added to support DBD::SQLite.
! 642: */
! 643: int sqlite3_bind_parameter_count(sqlite3_stmt*);
! 644:
! 645: /*
! 646: ** Return the name of the i-th parameter. Ordinary wildcards "?" are
! 647: ** nameless and a NULL is returned. For wildcards of the form :N or
! 648: ** $vvvv the complete text of the wildcard is returned.
! 649: ** NULL is returned if the index is out of range.
! 650: */
! 651: const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
! 652:
! 653: /*
! 654: ** Return the index of a parameter with the given name. The name
! 655: ** must match exactly. If no parameter with the given name is found,
! 656: ** return 0.
! 657: */
! 658: int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
! 659:
! 660: /*
! 661: ** Return the number of columns in the result set returned by the compiled
! 662: ** SQL statement. This routine returns 0 if pStmt is an SQL statement
! 663: ** that does not return data (for example an UPDATE).
! 664: */
! 665: int sqlite3_column_count(sqlite3_stmt *pStmt);
! 666:
! 667: /*
! 668: ** The first parameter is a compiled SQL statement. This function returns
! 669: ** the column heading for the Nth column of that statement, where N is the
! 670: ** second function parameter. The string returned is UTF-8 for
! 671: ** sqlite3_column_name() and UTF-16 for sqlite3_column_name16().
! 672: */
! 673: const char *sqlite3_column_name(sqlite3_stmt*,int);
! 674: const void *sqlite3_column_name16(sqlite3_stmt*,int);
! 675:
! 676: /*
! 677: ** The first parameter is a compiled SQL statement. If this statement
! 678: ** is a SELECT statement, the Nth column of the returned result set
! 679: ** of the SELECT is a table column then the declared type of the table
! 680: ** column is returned. If the Nth column of the result set is not at table
! 681: ** column, then a NULL pointer is returned. The returned string is always
! 682: ** UTF-8 encoded. For example, in the database schema:
! 683: **
! 684: ** CREATE TABLE t1(c1 VARIANT);
! 685: **
! 686: ** And the following statement compiled:
! 687: **
! 688: ** SELECT c1 + 1, 0 FROM t1;
! 689: **
! 690: ** Then this routine would return the string "VARIANT" for the second
! 691: ** result column (i==1), and a NULL pointer for the first result column
! 692: ** (i==0).
! 693: */
! 694: const char *sqlite3_column_decltype(sqlite3_stmt *, int i);
! 695:
! 696: /*
! 697: ** The first parameter is a compiled SQL statement. If this statement
! 698: ** is a SELECT statement, the Nth column of the returned result set
! 699: ** of the SELECT is a table column then the declared type of the table
! 700: ** column is returned. If the Nth column of the result set is not at table
! 701: ** column, then a NULL pointer is returned. The returned string is always
! 702: ** UTF-16 encoded. For example, in the database schema:
! 703: **
! 704: ** CREATE TABLE t1(c1 INTEGER);
! 705: **
! 706: ** And the following statement compiled:
! 707: **
! 708: ** SELECT c1 + 1, 0 FROM t1;
! 709: **
! 710: ** Then this routine would return the string "INTEGER" for the second
! 711: ** result column (i==1), and a NULL pointer for the first result column
! 712: ** (i==0).
! 713: */
! 714: const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
! 715:
! 716: /*
! 717: ** After an SQL query has been compiled with a call to either
! 718: ** sqlite3_prepare() or sqlite3_prepare16(), then this function must be
! 719: ** called one or more times to execute the statement.
! 720: **
! 721: ** The return value will be either SQLITE_BUSY, SQLITE_DONE,
! 722: ** SQLITE_ROW, SQLITE_ERROR, or SQLITE_MISUSE.
! 723: **
! 724: ** SQLITE_BUSY means that the database engine attempted to open
! 725: ** a locked database and there is no busy callback registered.
! 726: ** Call sqlite3_step() again to retry the open.
! 727: **
! 728: ** SQLITE_DONE means that the statement has finished executing
! 729: ** successfully. sqlite3_step() should not be called again on this virtual
! 730: ** machine.
! 731: **
! 732: ** If the SQL statement being executed returns any data, then
! 733: ** SQLITE_ROW is returned each time a new row of data is ready
! 734: ** for processing by the caller. The values may be accessed using
! 735: ** the sqlite3_column_*() functions described below. sqlite3_step()
! 736: ** is called again to retrieve the next row of data.
! 737: **
! 738: ** SQLITE_ERROR means that a run-time error (such as a constraint
! 739: ** violation) has occurred. sqlite3_step() should not be called again on
! 740: ** the VM. More information may be found by calling sqlite3_errmsg().
! 741: **
! 742: ** SQLITE_MISUSE means that the this routine was called inappropriately.
! 743: ** Perhaps it was called on a virtual machine that had already been
! 744: ** finalized or on one that had previously returned SQLITE_ERROR or
! 745: ** SQLITE_DONE. Or it could be the case the the same database connection
! 746: ** is being used simulataneously by two or more threads.
! 747: */
! 748: int sqlite3_step(sqlite3_stmt*);
! 749:
! 750: /*
! 751: ** Return the number of values in the current row of the result set.
! 752: **
! 753: ** After a call to sqlite3_step() that returns SQLITE_ROW, this routine
! 754: ** will return the same value as the sqlite3_column_count() function.
! 755: ** After sqlite3_step() has returned an SQLITE_DONE, SQLITE_BUSY or
! 756: ** error code, or before sqlite3_step() has been called on a
! 757: ** compiled SQL statement, this routine returns zero.
! 758: */
! 759: int sqlite3_data_count(sqlite3_stmt *pStmt);
! 760:
! 761: /*
! 762: ** Values are stored in the database in one of the following fundamental
! 763: ** types.
! 764: */
! 765: #define SQLITE_INTEGER 1
! 766: #define SQLITE_FLOAT 2
! 767: /* #define SQLITE_TEXT 3 // See below */
! 768: #define SQLITE_BLOB 4
! 769: #define SQLITE_NULL 5
! 770:
! 771: /*
! 772: ** SQLite version 2 defines SQLITE_TEXT differently. To allow both
! 773: ** version 2 and version 3 to be included, undefine them both if a
! 774: ** conflict is seen. Define SQLITE3_TEXT to be the version 3 value.
! 775: */
! 776: #ifdef SQLITE_TEXT
! 777: # undef SQLITE_TEXT
! 778: #else
! 779: # define SQLITE_TEXT 3
! 780: #endif
! 781: #define SQLITE3_TEXT 3
! 782:
! 783: /*
! 784: ** The next group of routines returns information about the information
! 785: ** in a single column of the current result row of a query. In every
! 786: ** case the first parameter is a pointer to the SQL statement that is being
! 787: ** executed (the sqlite_stmt* that was returned from sqlite3_prepare()) and
! 788: ** the second argument is the index of the column for which information
! 789: ** should be returned. iCol is zero-indexed. The left-most column as an
! 790: ** index of 0.
! 791: **
! 792: ** If the SQL statement is not currently point to a valid row, or if the
! 793: ** the colulmn index is out of range, the result is undefined.
! 794: **
! 795: ** These routines attempt to convert the value where appropriate. For
! 796: ** example, if the internal representation is FLOAT and a text result
! 797: ** is requested, sprintf() is used internally to do the conversion
! 798: ** automatically. The following table details the conversions that
! 799: ** are applied:
! 800: **
! 801: ** Internal Type Requested Type Conversion
! 802: ** ------------- -------------- --------------------------
! 803: ** NULL INTEGER Result is 0
! 804: ** NULL FLOAT Result is 0.0
! 805: ** NULL TEXT Result is an empty string
! 806: ** NULL BLOB Result is a zero-length BLOB
! 807: ** INTEGER FLOAT Convert from integer to float
! 808: ** INTEGER TEXT ASCII rendering of the integer
! 809: ** INTEGER BLOB Same as for INTEGER->TEXT
! 810: ** FLOAT INTEGER Convert from float to integer
! 811: ** FLOAT TEXT ASCII rendering of the float
! 812: ** FLOAT BLOB Same as FLOAT->TEXT
! 813: ** TEXT INTEGER Use atoi()
! 814: ** TEXT FLOAT Use atof()
! 815: ** TEXT BLOB No change
! 816: ** BLOB INTEGER Convert to TEXT then use atoi()
! 817: ** BLOB FLOAT Convert to TEXT then use atof()
! 818: ** BLOB TEXT Add a \000 terminator if needed
! 819: **
! 820: ** The following access routines are provided:
! 821: **
! 822: ** _type() Return the datatype of the result. This is one of
! 823: ** SQLITE_INTEGER, SQLITE_FLOAT, SQLITE_TEXT, SQLITE_BLOB,
! 824: ** or SQLITE_NULL.
! 825: ** _blob() Return the value of a BLOB.
! 826: ** _bytes() Return the number of bytes in a BLOB value or the number
! 827: ** of bytes in a TEXT value represented as UTF-8. The \000
! 828: ** terminator is included in the byte count for TEXT values.
! 829: ** _bytes16() Return the number of bytes in a BLOB value or the number
! 830: ** of bytes in a TEXT value represented as UTF-16. The \u0000
! 831: ** terminator is included in the byte count for TEXT values.
! 832: ** _double() Return a FLOAT value.
! 833: ** _int() Return an INTEGER value in the host computer's native
! 834: ** integer representation. This might be either a 32- or 64-bit
! 835: ** integer depending on the host.
! 836: ** _int64() Return an INTEGER value as a 64-bit signed integer.
! 837: ** _text() Return the value as UTF-8 text.
! 838: ** _text16() Return the value as UTF-16 text.
! 839: */
! 840: const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
! 841: int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
! 842: int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
! 843: double sqlite3_column_double(sqlite3_stmt*, int iCol);
! 844: int sqlite3_column_int(sqlite3_stmt*, int iCol);
! 845: sqlite_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
! 846: const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
! 847: const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
! 848: int sqlite3_column_type(sqlite3_stmt*, int iCol);
! 849:
! 850: /*
! 851: ** The sqlite3_finalize() function is called to delete a compiled
! 852: ** SQL statement obtained by a previous call to sqlite3_prepare()
! 853: ** or sqlite3_prepare16(). If the statement was executed successfully, or
! 854: ** not executed at all, then SQLITE_OK is returned. If execution of the
! 855: ** statement failed then an error code is returned.
! 856: **
! 857: ** This routine can be called at any point during the execution of the
! 858: ** virtual machine. If the virtual machine has not completed execution
! 859: ** when this routine is called, that is like encountering an error or
! 860: ** an interrupt. (See sqlite3_interrupt().) Incomplete updates may be
! 861: ** rolled back and transactions cancelled, depending on the circumstances,
! 862: ** and the result code returned will be SQLITE_ABORT.
! 863: */
! 864: int sqlite3_finalize(sqlite3_stmt *pStmt);
! 865:
! 866: /*
! 867: ** The sqlite3_reset() function is called to reset a compiled SQL
! 868: ** statement obtained by a previous call to sqlite3_prepare() or
! 869: ** sqlite3_prepare16() back to it's initial state, ready to be re-executed.
! 870: ** Any SQL statement variables that had values bound to them using
! 871: ** the sqlite3_bind_*() API retain their values.
! 872: */
! 873: int sqlite3_reset(sqlite3_stmt *pStmt);
! 874:
! 875: /*
! 876: ** The following two functions are used to add user functions or aggregates
! 877: ** implemented in C to the SQL langauge interpreted by SQLite. The
! 878: ** difference only between the two is that the second parameter, the
! 879: ** name of the (scalar) function or aggregate, is encoded in UTF-8 for
! 880: ** sqlite3_create_function() and UTF-16 for sqlite3_create_function16().
! 881: **
! 882: ** The first argument is the database handle that the new function or
! 883: ** aggregate is to be added to. If a single program uses more than one
! 884: ** database handle internally, then user functions or aggregates must
! 885: ** be added individually to each database handle with which they will be
! 886: ** used.
! 887: **
! 888: ** The third parameter is the number of arguments that the function or
! 889: ** aggregate takes. If this parameter is negative, then the function or
! 890: ** aggregate may take any number of arguments.
! 891: **
! 892: ** The fourth parameter is one of SQLITE_UTF* values defined below,
! 893: ** indicating the encoding that the function is most likely to handle
! 894: ** values in. This does not change the behaviour of the programming
! 895: ** interface. However, if two versions of the same function are registered
! 896: ** with different encoding values, SQLite invokes the version likely to
! 897: ** minimize conversions between text encodings.
! 898: **
! 899: ** The seventh, eighth and ninth parameters, xFunc, xStep and xFinal, are
! 900: ** pointers to user implemented C functions that implement the user
! 901: ** function or aggregate. A scalar function requires an implementation of
! 902: ** the xFunc callback only, NULL pointers should be passed as the xStep
! 903: ** and xFinal parameters. An aggregate function requires an implementation
! 904: ** of xStep and xFinal, but NULL should be passed for xFunc. To delete an
! 905: ** existing user function or aggregate, pass NULL for all three function
! 906: ** callback. Specifying an inconstent set of callback values, such as an
! 907: ** xFunc and an xFinal, or an xStep but no xFinal, SQLITE_ERROR is
! 908: ** returned.
! 909: */
! 910: int sqlite3_create_function(
! 911: sqlite3 *,
! 912: const char *zFunctionName,
! 913: int nArg,
! 914: int eTextRep,
! 915: void*,
! 916: void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
! 917: void (*xStep)(sqlite3_context*,int,sqlite3_value**),
! 918: void (*xFinal)(sqlite3_context*)
! 919: );
! 920: int sqlite3_create_function16(
! 921: sqlite3*,
! 922: const void *zFunctionName,
! 923: int nArg,
! 924: int eTextRep,
! 925: void*,
! 926: void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
! 927: void (*xStep)(sqlite3_context*,int,sqlite3_value**),
! 928: void (*xFinal)(sqlite3_context*)
! 929: );
! 930:
! 931: /*
! 932: ** The next routine returns the number of calls to xStep for a particular
! 933: ** aggregate function instance. The current call to xStep counts so this
! 934: ** routine always returns at least 1.
! 935: */
! 936: int sqlite3_aggregate_count(sqlite3_context*);
! 937:
! 938: /*
! 939: ** The next group of routines returns information about parameters to
! 940: ** a user-defined function. Function implementations use these routines
! 941: ** to access their parameters. These routines are the same as the
! 942: ** sqlite3_column_* routines except that these routines take a single
! 943: ** sqlite3_value* pointer instead of an sqlite3_stmt* and an integer
! 944: ** column number.
! 945: */
! 946: const void *sqlite3_value_blob(sqlite3_value*);
! 947: int sqlite3_value_bytes(sqlite3_value*);
! 948: int sqlite3_value_bytes16(sqlite3_value*);
! 949: double sqlite3_value_double(sqlite3_value*);
! 950: int sqlite3_value_int(sqlite3_value*);
! 951: sqlite_int64 sqlite3_value_int64(sqlite3_value*);
! 952: const unsigned char *sqlite3_value_text(sqlite3_value*);
! 953: const void *sqlite3_value_text16(sqlite3_value*);
! 954: const void *sqlite3_value_text16le(sqlite3_value*);
! 955: const void *sqlite3_value_text16be(sqlite3_value*);
! 956: int sqlite3_value_type(sqlite3_value*);
! 957:
! 958: /*
! 959: ** Aggregate functions use the following routine to allocate
! 960: ** a structure for storing their state. The first time this routine
! 961: ** is called for a particular aggregate, a new structure of size nBytes
! 962: ** is allocated, zeroed, and returned. On subsequent calls (for the
! 963: ** same aggregate instance) the same buffer is returned. The implementation
! 964: ** of the aggregate can use the returned buffer to accumulate data.
! 965: **
! 966: ** The buffer allocated is freed automatically by SQLite.
! 967: */
! 968: void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
! 969:
! 970: /*
! 971: ** The pUserData parameter to the sqlite3_create_function() and
! 972: ** sqlite3_create_aggregate() routines used to register user functions
! 973: ** is available to the implementation of the function using this
! 974: ** call.
! 975: */
! 976: void *sqlite3_user_data(sqlite3_context*);
! 977:
! 978: /*
! 979: ** The following two functions may be used by scalar user functions to
! 980: ** associate meta-data with argument values. If the same value is passed to
! 981: ** multiple invocations of the user-function during query execution, under
! 982: ** some circumstances the associated meta-data may be preserved. This may
! 983: ** be used, for example, to add a regular-expression matching scalar
! 984: ** function. The compiled version of the regular expression is stored as
! 985: ** meta-data associated with the SQL value passed as the regular expression
! 986: ** pattern.
! 987: **
! 988: ** Calling sqlite3_get_auxdata() returns a pointer to the meta data
! 989: ** associated with the Nth argument value to the current user function
! 990: ** call, where N is the second parameter. If no meta-data has been set for
! 991: ** that value, then a NULL pointer is returned.
! 992: **
! 993: ** The sqlite3_set_auxdata() is used to associate meta data with a user
! 994: ** function argument. The third parameter is a pointer to the meta data
! 995: ** to be associated with the Nth user function argument value. The fourth
! 996: ** parameter specifies a 'delete function' that will be called on the meta
! 997: ** data pointer to release it when it is no longer required. If the delete
! 998: ** function pointer is NULL, it is not invoked.
! 999: **
! 1000: ** In practice, meta-data is preserved between function calls for
! 1001: ** expressions that are constant at compile time. This includes literal
! 1002: ** values and SQL variables.
! 1003: */
! 1004: void *sqlite3_get_auxdata(sqlite3_context*, int);
! 1005: void sqlite3_set_auxdata(sqlite3_context*, int, void*, void (*)(void*));
! 1006:
! 1007:
! 1008: /*
! 1009: ** These are special value for the destructor that is passed in as the
! 1010: ** final argument to routines like sqlite3_result_blob(). If the destructor
! 1011: ** argument is SQLITE_STATIC, it means that the content pointer is constant
! 1012: ** and will never change. It does not need to be destroyed. The
! 1013: ** SQLITE_TRANSIENT value means that the content will likely change in
! 1014: ** the near future and that SQLite should make its own private copy of
! 1015: ** the content before returning.
! 1016: */
! 1017: #define SQLITE_STATIC ((void(*)(void *))0)
! 1018: #define SQLITE_TRANSIENT ((void(*)(void *))-1)
! 1019:
! 1020: /*
! 1021: ** User-defined functions invoke the following routines in order to
! 1022: ** set their return value.
! 1023: */
! 1024: void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
! 1025: void sqlite3_result_double(sqlite3_context*, double);
! 1026: void sqlite3_result_error(sqlite3_context*, const char*, int);
! 1027: void sqlite3_result_error16(sqlite3_context*, const void*, int);
! 1028: void sqlite3_result_int(sqlite3_context*, int);
! 1029: void sqlite3_result_int64(sqlite3_context*, sqlite_int64);
! 1030: void sqlite3_result_null(sqlite3_context*);
! 1031: void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
! 1032: void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
! 1033: void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
! 1034: void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
! 1035: void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
! 1036:
! 1037: /*
! 1038: ** These are the allowed values for the eTextRep argument to
! 1039: ** sqlite3_create_collation and sqlite3_create_function.
! 1040: */
! 1041: #define SQLITE_UTF8 1
! 1042: #define SQLITE_UTF16LE 2
! 1043: #define SQLITE_UTF16BE 3
! 1044: #define SQLITE_UTF16 4 /* Use native byte order */
! 1045: #define SQLITE_ANY 5 /* sqlite3_create_function only */
! 1046:
! 1047: /*
! 1048: ** These two functions are used to add new collation sequences to the
! 1049: ** sqlite3 handle specified as the first argument.
! 1050: **
! 1051: ** The name of the new collation sequence is specified as a UTF-8 string
! 1052: ** for sqlite3_create_collation() and a UTF-16 string for
! 1053: ** sqlite3_create_collation16(). In both cases the name is passed as the
! 1054: ** second function argument.
! 1055: **
! 1056: ** The third argument must be one of the constants SQLITE_UTF8,
! 1057: ** SQLITE_UTF16LE or SQLITE_UTF16BE, indicating that the user-supplied
! 1058: ** routine expects to be passed pointers to strings encoded using UTF-8,
! 1059: ** UTF-16 little-endian or UTF-16 big-endian respectively.
! 1060: **
! 1061: ** A pointer to the user supplied routine must be passed as the fifth
! 1062: ** argument. If it is NULL, this is the same as deleting the collation
! 1063: ** sequence (so that SQLite cannot call it anymore). Each time the user
! 1064: ** supplied function is invoked, it is passed a copy of the void* passed as
! 1065: ** the fourth argument to sqlite3_create_collation() or
! 1066: ** sqlite3_create_collation16() as its first parameter.
! 1067: **
! 1068: ** The remaining arguments to the user-supplied routine are two strings,
! 1069: ** each represented by a [length, data] pair and encoded in the encoding
! 1070: ** that was passed as the third argument when the collation sequence was
! 1071: ** registered. The user routine should return negative, zero or positive if
! 1072: ** the first string is less than, equal to, or greater than the second
! 1073: ** string. i.e. (STRING1 - STRING2).
! 1074: */
! 1075: int sqlite3_create_collation(
! 1076: sqlite3*,
! 1077: const char *zName,
! 1078: int eTextRep,
! 1079: void*,
! 1080: int(*xCompare)(void*,int,const void*,int,const void*)
! 1081: );
! 1082: int sqlite3_create_collation16(
! 1083: sqlite3*,
! 1084: const char *zName,
! 1085: int eTextRep,
! 1086: void*,
! 1087: int(*xCompare)(void*,int,const void*,int,const void*)
! 1088: );
! 1089:
! 1090: /*
! 1091: ** To avoid having to register all collation sequences before a database
! 1092: ** can be used, a single callback function may be registered with the
! 1093: ** database handle to be called whenever an undefined collation sequence is
! 1094: ** required.
! 1095: **
! 1096: ** If the function is registered using the sqlite3_collation_needed() API,
! 1097: ** then it is passed the names of undefined collation sequences as strings
! 1098: ** encoded in UTF-8. If sqlite3_collation_needed16() is used, the names
! 1099: ** are passed as UTF-16 in machine native byte order. A call to either
! 1100: ** function replaces any existing callback.
! 1101: **
! 1102: ** When the user-function is invoked, the first argument passed is a copy
! 1103: ** of the second argument to sqlite3_collation_needed() or
! 1104: ** sqlite3_collation_needed16(). The second argument is the database
! 1105: ** handle. The third argument is one of SQLITE_UTF8, SQLITE_UTF16BE or
! 1106: ** SQLITE_UTF16LE, indicating the most desirable form of the collation
! 1107: ** sequence function required. The fourth parameter is the name of the
! 1108: ** required collation sequence.
! 1109: **
! 1110: ** The collation sequence is returned to SQLite by a collation-needed
! 1111: ** callback using the sqlite3_create_collation() or
! 1112: ** sqlite3_create_collation16() APIs, described above.
! 1113: */
! 1114: int sqlite3_collation_needed(
! 1115: sqlite3*,
! 1116: void*,
! 1117: void(*)(void*,sqlite3*,int eTextRep,const char*)
! 1118: );
! 1119: int sqlite3_collation_needed16(
! 1120: sqlite3*,
! 1121: void*,
! 1122: void(*)(void*,sqlite3*,int eTextRep,const void*)
! 1123: );
! 1124:
! 1125: /*
! 1126: ** Specify the key for an encrypted database. This routine should be
! 1127: ** called right after sqlite3_open().
! 1128: **
! 1129: ** The code to implement this API is not available in the public release
! 1130: ** of SQLite.
! 1131: */
! 1132: int sqlite3_key(
! 1133: sqlite3 *db, /* Database to be rekeyed */
! 1134: const void *pKey, int nKey /* The key */
! 1135: );
! 1136:
! 1137: /*
! 1138: ** Change the key on an open database. If the current database is not
! 1139: ** encrypted, this routine will encrypt it. If pNew==0 or nNew==0, the
! 1140: ** database is decrypted.
! 1141: **
! 1142: ** The code to implement this API is not available in the public release
! 1143: ** of SQLite.
! 1144: */
! 1145: int sqlite3_rekey(
! 1146: sqlite3 *db, /* Database to be rekeyed */
! 1147: const void *pKey, int nKey /* The new key */
! 1148: );
! 1149:
! 1150: /*
! 1151: ** If the following global variable is made to point to a constant
! 1152: ** string which is the name of a directory, then all temporary files
! 1153: ** created by SQLite will be placed in that directory. If this variable
! 1154: ** is NULL pointer, then SQLite does a search for an appropriate temporary
! 1155: ** file directory.
! 1156: **
! 1157: ** This variable should only be changed when there are no open databases.
! 1158: ** Once sqlite3_open() has been called, this variable should not be changed
! 1159: ** until all database connections are closed.
! 1160: */
! 1161: extern const char *sqlite3_temp_directory;
! 1162:
! 1163: #ifdef __cplusplus
! 1164: } /* End of the 'extern "C"' block */
! 1165: #endif
! 1166: #endif
E-mail:
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to sqlite3.h CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [parser3project] / win32 / sql / sqlite / include