Annotation of embedaddon/php/ext/sqlite/libsqlite/src/sqlite.h.in, revision 1.1
1.1 ! misho 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 195361 2005-09-07 15:11:33Z iliaa $
! 16: */
! 17: #ifndef _SQLITE_H_
! 18: #define _SQLITE_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 "--VERS--"
! 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.
! 41: */
! 42: extern const char sqlite_version[];
! 43:
! 44: /*
! 45: ** The SQLITE_UTF8 macro is defined if the library expects to see
! 46: ** UTF-8 encoded data. The SQLITE_ISO8859 macro is defined if the
! 47: ** iso8859 encoded should be used.
! 48: */
! 49: #define SQLITE_--ENCODING-- 1
! 50:
! 51: /*
! 52: ** The following constant holds one of two strings, "UTF-8" or "iso8859",
! 53: ** depending on which character encoding the SQLite library expects to
! 54: ** see. The character encoding makes a difference for the LIKE and GLOB
! 55: ** operators and for the LENGTH() and SUBSTR() functions.
! 56: */
! 57: extern const char sqlite_encoding[];
! 58:
! 59: /*
! 60: ** Each open sqlite database is represented by an instance of the
! 61: ** following opaque structure.
! 62: */
! 63: typedef struct sqlite sqlite;
! 64:
! 65: /*
! 66: ** A function to open a new sqlite database.
! 67: **
! 68: ** If the database does not exist and mode indicates write
! 69: ** permission, then a new database is created. If the database
! 70: ** does not exist and mode does not indicate write permission,
! 71: ** then the open fails, an error message generated (if errmsg!=0)
! 72: ** and the function returns 0.
! 73: **
! 74: ** If mode does not indicates user write permission, then the
! 75: ** database is opened read-only.
! 76: **
! 77: ** The Truth: As currently implemented, all databases are opened
! 78: ** for writing all the time. Maybe someday we will provide the
! 79: ** ability to open a database readonly. The mode parameters is
! 80: ** provided in anticipation of that enhancement.
! 81: */
! 82: sqlite *sqlite_open(const char *filename, int mode, char **errmsg);
! 83:
! 84: /*
! 85: ** A function to close the database.
! 86: **
! 87: ** Call this function with a pointer to a structure that was previously
! 88: ** returned from sqlite_open() and the corresponding database will by closed.
! 89: */
! 90: void sqlite_close(sqlite *);
! 91:
! 92: /*
! 93: ** The type for a callback function.
! 94: */
! 95: typedef int (*sqlite_callback)(void*,int,char**, char**);
! 96:
! 97: /*
! 98: ** A function to executes one or more statements of SQL.
! 99: **
! 100: ** If one or more of the SQL statements are queries, then
! 101: ** the callback function specified by the 3rd parameter is
! 102: ** invoked once for each row of the query result. This callback
! 103: ** should normally return 0. If the callback returns a non-zero
! 104: ** value then the query is aborted, all subsequent SQL statements
! 105: ** are skipped and the sqlite_exec() function returns the SQLITE_ABORT.
! 106: **
! 107: ** The 4th parameter is an arbitrary pointer that is passed
! 108: ** to the callback function as its first parameter.
! 109: **
! 110: ** The 2nd parameter to the callback function is the number of
! 111: ** columns in the query result. The 3rd parameter to the callback
! 112: ** is an array of strings holding the values for each column.
! 113: ** The 4th parameter to the callback is an array of strings holding
! 114: ** the names of each column.
! 115: **
! 116: ** The callback function may be NULL, even for queries. A NULL
! 117: ** callback is not an error. It just means that no callback
! 118: ** will be invoked.
! 119: **
! 120: ** If an error occurs while parsing or evaluating the SQL (but
! 121: ** not while executing the callback) then an appropriate error
! 122: ** message is written into memory obtained from malloc() and
! 123: ** *errmsg is made to point to that message. The calling function
! 124: ** is responsible for freeing the memory that holds the error
! 125: ** message. Use sqlite_freemem() for this. If errmsg==NULL,
! 126: ** then no error message is ever written.
! 127: **
! 128: ** The return value is is SQLITE_OK if there are no errors and
! 129: ** some other return code if there is an error. The particular
! 130: ** return value depends on the type of error.
! 131: **
! 132: ** If the query could not be executed because a database file is
! 133: ** locked or busy, then this function returns SQLITE_BUSY. (This
! 134: ** behavior can be modified somewhat using the sqlite_busy_handler()
! 135: ** and sqlite_busy_timeout() functions below.)
! 136: */
! 137: int sqlite_exec(
! 138: sqlite*, /* An open database */
! 139: const char *sql, /* SQL to be executed */
! 140: sqlite_callback, /* Callback function */
! 141: void *, /* 1st argument to callback function */
! 142: char **errmsg /* Error msg written here */
! 143: );
! 144:
! 145: /*
! 146: ** Return values for sqlite_exec() and sqlite_step()
! 147: */
! 148: #define SQLITE_OK 0 /* Successful result */
! 149: #define SQLITE_ERROR 1 /* SQL error or missing database */
! 150: #define SQLITE_INTERNAL 2 /* An internal logic error in SQLite */
! 151: #define SQLITE_PERM 3 /* Access permission denied */
! 152: #define SQLITE_ABORT 4 /* Callback routine requested an abort */
! 153: #define SQLITE_BUSY 5 /* The database file is locked */
! 154: #define SQLITE_LOCKED 6 /* A table in the database is locked */
! 155: #define SQLITE_NOMEM 7 /* A malloc() failed */
! 156: #define SQLITE_READONLY 8 /* Attempt to write a readonly database */
! 157: #define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite_interrupt() */
! 158: #define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */
! 159: #define SQLITE_CORRUPT 11 /* The database disk image is malformed */
! 160: #define SQLITE_NOTFOUND 12 /* (Internal Only) Table or record not found */
! 161: #define SQLITE_FULL 13 /* Insertion failed because database is full */
! 162: #define SQLITE_CANTOPEN 14 /* Unable to open the database file */
! 163: #define SQLITE_PROTOCOL 15 /* Database lock protocol error */
! 164: #define SQLITE_EMPTY 16 /* (Internal Only) Database table is empty */
! 165: #define SQLITE_SCHEMA 17 /* The database schema changed */
! 166: #define SQLITE_TOOBIG 18 /* Too much data for one row of a table */
! 167: #define SQLITE_CONSTRAINT 19 /* Abort due to contraint violation */
! 168: #define SQLITE_MISMATCH 20 /* Data type mismatch */
! 169: #define SQLITE_MISUSE 21 /* Library used incorrectly */
! 170: #define SQLITE_NOLFS 22 /* Uses OS features not supported on host */
! 171: #define SQLITE_AUTH 23 /* Authorization denied */
! 172: #define SQLITE_FORMAT 24 /* Auxiliary database format error */
! 173: #define SQLITE_RANGE 25 /* 2nd parameter to sqlite_bind out of range */
! 174: #define SQLITE_NOTADB 26 /* File opened that is not a database file */
! 175: #define SQLITE_ROW 100 /* sqlite_step() has another row ready */
! 176: #define SQLITE_DONE 101 /* sqlite_step() has finished executing */
! 177:
! 178: /*
! 179: ** Each entry in an SQLite table has a unique integer key. (The key is
! 180: ** the value of the INTEGER PRIMARY KEY column if there is such a column,
! 181: ** otherwise the key is generated at random. The unique key is always
! 182: ** available as the ROWID, OID, or _ROWID_ column.) The following routine
! 183: ** returns the integer key of the most recent insert in the database.
! 184: **
! 185: ** This function is similar to the mysql_insert_id() function from MySQL.
! 186: */
! 187: int sqlite_last_insert_rowid(sqlite*);
! 188:
! 189: /*
! 190: ** This function returns the number of database rows that were changed
! 191: ** (or inserted or deleted) by the most recent called sqlite_exec().
! 192: **
! 193: ** All changes are counted, even if they were later undone by a
! 194: ** ROLLBACK or ABORT. Except, changes associated with creating and
! 195: ** dropping tables are not counted.
! 196: **
! 197: ** If a callback invokes sqlite_exec() recursively, then the changes
! 198: ** in the inner, recursive call are counted together with the changes
! 199: ** in the outer call.
! 200: **
! 201: ** SQLite implements the command "DELETE FROM table" without a WHERE clause
! 202: ** by dropping and recreating the table. (This is much faster than going
! 203: ** through and deleting individual elements form the table.) Because of
! 204: ** this optimization, the change count for "DELETE FROM table" will be
! 205: ** zero regardless of the number of elements that were originally in the
! 206: ** table. To get an accurate count of the number of rows deleted, use
! 207: ** "DELETE FROM table WHERE 1" instead.
! 208: */
! 209: int sqlite_changes(sqlite*);
! 210:
! 211: /*
! 212: ** This function returns the number of database rows that were changed
! 213: ** by the last INSERT, UPDATE, or DELETE statment executed by sqlite_exec(),
! 214: ** or by the last VM to run to completion. The change count is not updated
! 215: ** by SQL statements other than INSERT, UPDATE or DELETE.
! 216: **
! 217: ** Changes are counted, even if they are later undone by a ROLLBACK or
! 218: ** ABORT. Changes associated with trigger programs that execute as a
! 219: ** result of the INSERT, UPDATE, or DELETE statement are not counted.
! 220: **
! 221: ** If a callback invokes sqlite_exec() recursively, then the changes
! 222: ** in the inner, recursive call are counted together with the changes
! 223: ** in the outer call.
! 224: **
! 225: ** SQLite implements the command "DELETE FROM table" without a WHERE clause
! 226: ** by dropping and recreating the table. (This is much faster than going
! 227: ** through and deleting individual elements form the table.) Because of
! 228: ** this optimization, the change count for "DELETE FROM table" will be
! 229: ** zero regardless of the number of elements that were originally in the
! 230: ** table. To get an accurate count of the number of rows deleted, use
! 231: ** "DELETE FROM table WHERE 1" instead.
! 232: **
! 233: ******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
! 234: */
! 235: int sqlite_last_statement_changes(sqlite*);
! 236:
! 237: /* If the parameter to this routine is one of the return value constants
! 238: ** defined above, then this routine returns a constant text string which
! 239: ** descripts (in English) the meaning of the return value.
! 240: */
! 241: const char *sqlite_error_string(int);
! 242: #define sqliteErrStr sqlite_error_string /* Legacy. Do not use in new code. */
! 243:
! 244: /* This function causes any pending database operation to abort and
! 245: ** return at its earliest opportunity. This routine is typically
! 246: ** called in response to a user action such as pressing "Cancel"
! 247: ** or Ctrl-C where the user wants a long query operation to halt
! 248: ** immediately.
! 249: */
! 250: void sqlite_interrupt(sqlite*);
! 251:
! 252:
! 253: /* This function returns true if the given input string comprises
! 254: ** one or more complete SQL statements.
! 255: **
! 256: ** The algorithm is simple. If the last token other than spaces
! 257: ** and comments is a semicolon, then return true. otherwise return
! 258: ** false.
! 259: */
! 260: int sqlite_complete(const char *sql);
! 261:
! 262: /*
! 263: ** This routine identifies a callback function that is invoked
! 264: ** whenever an attempt is made to open a database table that is
! 265: ** currently locked by another process or thread. If the busy callback
! 266: ** is NULL, then sqlite_exec() returns SQLITE_BUSY immediately if
! 267: ** it finds a locked table. If the busy callback is not NULL, then
! 268: ** sqlite_exec() invokes the callback with three arguments. The
! 269: ** second argument is the name of the locked table and the third
! 270: ** argument is the number of times the table has been busy. If the
! 271: ** busy callback returns 0, then sqlite_exec() immediately returns
! 272: ** SQLITE_BUSY. If the callback returns non-zero, then sqlite_exec()
! 273: ** tries to open the table again and the cycle repeats.
! 274: **
! 275: ** The default busy callback is NULL.
! 276: **
! 277: ** Sqlite is re-entrant, so the busy handler may start a new query.
! 278: ** (It is not clear why anyone would every want to do this, but it
! 279: ** is allowed, in theory.) But the busy handler may not close the
! 280: ** database. Closing the database from a busy handler will delete
! 281: ** data structures out from under the executing query and will
! 282: ** probably result in a coredump.
! 283: */
! 284: void sqlite_busy_handler(sqlite*, int(*)(void*,const char*,int), void*);
! 285:
! 286: /*
! 287: ** This routine sets a busy handler that sleeps for a while when a
! 288: ** table is locked. The handler will sleep multiple times until
! 289: ** at least "ms" milleseconds of sleeping have been done. After
! 290: ** "ms" milleseconds of sleeping, the handler returns 0 which
! 291: ** causes sqlite_exec() to return SQLITE_BUSY.
! 292: **
! 293: ** Calling this routine with an argument less than or equal to zero
! 294: ** turns off all busy handlers.
! 295: */
! 296: void sqlite_busy_timeout(sqlite*, int ms);
! 297:
! 298: /*
! 299: ** This next routine is really just a wrapper around sqlite_exec().
! 300: ** Instead of invoking a user-supplied callback for each row of the
! 301: ** result, this routine remembers each row of the result in memory
! 302: ** obtained from malloc(), then returns all of the result after the
! 303: ** query has finished.
! 304: **
! 305: ** As an example, suppose the query result where this table:
! 306: **
! 307: ** Name | Age
! 308: ** -----------------------
! 309: ** Alice | 43
! 310: ** Bob | 28
! 311: ** Cindy | 21
! 312: **
! 313: ** If the 3rd argument were &azResult then after the function returns
! 314: ** azResult will contain the following data:
! 315: **
! 316: ** azResult[0] = "Name";
! 317: ** azResult[1] = "Age";
! 318: ** azResult[2] = "Alice";
! 319: ** azResult[3] = "43";
! 320: ** azResult[4] = "Bob";
! 321: ** azResult[5] = "28";
! 322: ** azResult[6] = "Cindy";
! 323: ** azResult[7] = "21";
! 324: **
! 325: ** Notice that there is an extra row of data containing the column
! 326: ** headers. But the *nrow return value is still 3. *ncolumn is
! 327: ** set to 2. In general, the number of values inserted into azResult
! 328: ** will be ((*nrow) + 1)*(*ncolumn).
! 329: **
! 330: ** After the calling function has finished using the result, it should
! 331: ** pass the result data pointer to sqlite_free_table() in order to
! 332: ** release the memory that was malloc-ed. Because of the way the
! 333: ** malloc() happens, the calling function must not try to call
! 334: ** malloc() directly. Only sqlite_free_table() is able to release
! 335: ** the memory properly and safely.
! 336: **
! 337: ** The return value of this routine is the same as from sqlite_exec().
! 338: */
! 339: int sqlite_get_table(
! 340: sqlite*, /* An open database */
! 341: const char *sql, /* SQL to be executed */
! 342: char ***resultp, /* Result written to a char *[] that this points to */
! 343: int *nrow, /* Number of result rows written here */
! 344: int *ncolumn, /* Number of result columns written here */
! 345: char **errmsg /* Error msg written here */
! 346: );
! 347:
! 348: /*
! 349: ** Call this routine to free the memory that sqlite_get_table() allocated.
! 350: */
! 351: void sqlite_free_table(char **result);
! 352:
! 353: /*
! 354: ** The following routines are wrappers around sqlite_exec() and
! 355: ** sqlite_get_table(). The only difference between the routines that
! 356: ** follow and the originals is that the second argument to the
! 357: ** routines that follow is really a printf()-style format
! 358: ** string describing the SQL to be executed. Arguments to the format
! 359: ** string appear at the end of the argument list.
! 360: **
! 361: ** All of the usual printf formatting options apply. In addition, there
! 362: ** is a "%q" option. %q works like %s in that it substitutes a null-terminated
! 363: ** string from the argument list. But %q also doubles every '\'' character.
! 364: ** %q is designed for use inside a string literal. By doubling each '\''
! 365: ** character it escapes that character and allows it to be inserted into
! 366: ** the string.
! 367: **
! 368: ** For example, so some string variable contains text as follows:
! 369: **
! 370: ** char *zText = "It's a happy day!";
! 371: **
! 372: ** We can use this text in an SQL statement as follows:
! 373: **
! 374: ** sqlite_exec_printf(db, "INSERT INTO table VALUES('%q')",
! 375: ** callback1, 0, 0, zText);
! 376: **
! 377: ** Because the %q format string is used, the '\'' character in zText
! 378: ** is escaped and the SQL generated is as follows:
! 379: **
! 380: ** INSERT INTO table1 VALUES('It''s a happy day!')
! 381: **
! 382: ** This is correct. Had we used %s instead of %q, the generated SQL
! 383: ** would have looked like this:
! 384: **
! 385: ** INSERT INTO table1 VALUES('It's a happy day!');
! 386: **
! 387: ** This second example is an SQL syntax error. As a general rule you
! 388: ** should always use %q instead of %s when inserting text into a string
! 389: ** literal.
! 390: */
! 391: int sqlite_exec_printf(
! 392: sqlite*, /* An open database */
! 393: const char *sqlFormat, /* printf-style format string for the SQL */
! 394: sqlite_callback, /* Callback function */
! 395: void *, /* 1st argument to callback function */
! 396: char **errmsg, /* Error msg written here */
! 397: ... /* Arguments to the format string. */
! 398: );
! 399: int sqlite_exec_vprintf(
! 400: sqlite*, /* An open database */
! 401: const char *sqlFormat, /* printf-style format string for the SQL */
! 402: sqlite_callback, /* Callback function */
! 403: void *, /* 1st argument to callback function */
! 404: char **errmsg, /* Error msg written here */
! 405: va_list ap /* Arguments to the format string. */
! 406: );
! 407: int sqlite_get_table_printf(
! 408: sqlite*, /* An open database */
! 409: const char *sqlFormat, /* printf-style format string for the SQL */
! 410: char ***resultp, /* Result written to a char *[] that this points to */
! 411: int *nrow, /* Number of result rows written here */
! 412: int *ncolumn, /* Number of result columns written here */
! 413: char **errmsg, /* Error msg written here */
! 414: ... /* Arguments to the format string */
! 415: );
! 416: int sqlite_get_table_vprintf(
! 417: sqlite*, /* An open database */
! 418: const char *sqlFormat, /* printf-style format string for the SQL */
! 419: char ***resultp, /* Result written to a char *[] that this points to */
! 420: int *nrow, /* Number of result rows written here */
! 421: int *ncolumn, /* Number of result columns written here */
! 422: char **errmsg, /* Error msg written here */
! 423: va_list ap /* Arguments to the format string */
! 424: );
! 425: char *sqlite_mprintf(const char*,...);
! 426: char *sqlite_vmprintf(const char*, va_list);
! 427:
! 428: /*
! 429: ** Windows systems should call this routine to free memory that
! 430: ** is returned in the in the errmsg parameter of sqlite_open() when
! 431: ** SQLite is a DLL. For some reason, it does not work to call free()
! 432: ** directly.
! 433: */
! 434: void sqlite_freemem(void *p);
! 435:
! 436: /*
! 437: ** Windows systems need functions to call to return the sqlite_version
! 438: ** and sqlite_encoding strings.
! 439: */
! 440: const char *sqlite_libversion(void);
! 441: const char *sqlite_libencoding(void);
! 442:
! 443: /*
! 444: ** A pointer to the following structure is used to communicate with
! 445: ** the implementations of user-defined functions.
! 446: */
! 447: typedef struct sqlite_func sqlite_func;
! 448:
! 449: /*
! 450: ** Use the following routines to create new user-defined functions. See
! 451: ** the documentation for details.
! 452: */
! 453: int sqlite_create_function(
! 454: sqlite*, /* Database where the new function is registered */
! 455: const char *zName, /* Name of the new function */
! 456: int nArg, /* Number of arguments. -1 means any number */
! 457: void (*xFunc)(sqlite_func*,int,const char**), /* C code to implement */
! 458: void *pUserData /* Available via the sqlite_user_data() call */
! 459: );
! 460: int sqlite_create_aggregate(
! 461: sqlite*, /* Database where the new function is registered */
! 462: const char *zName, /* Name of the function */
! 463: int nArg, /* Number of arguments */
! 464: void (*xStep)(sqlite_func*,int,const char**), /* Called for each row */
! 465: void (*xFinalize)(sqlite_func*), /* Called once to get final result */
! 466: void *pUserData /* Available via the sqlite_user_data() call */
! 467: );
! 468:
! 469: /*
! 470: ** Use the following routine to define the datatype returned by a
! 471: ** user-defined function. The second argument can be one of the
! 472: ** constants SQLITE_NUMERIC, SQLITE_TEXT, or SQLITE_ARGS or it
! 473: ** can be an integer greater than or equal to zero. When the datatype
! 474: ** parameter is non-negative, the type of the result will be the
! 475: ** same as the datatype-th argument. If datatype==SQLITE_NUMERIC
! 476: ** then the result is always numeric. If datatype==SQLITE_TEXT then
! 477: ** the result is always text. If datatype==SQLITE_ARGS then the result
! 478: ** is numeric if any argument is numeric and is text otherwise.
! 479: */
! 480: int sqlite_function_type(
! 481: sqlite *db, /* The database there the function is registered */
! 482: const char *zName, /* Name of the function */
! 483: int datatype /* The datatype for this function */
! 484: );
! 485: #define SQLITE_NUMERIC (-1)
! 486: /* #define SQLITE_TEXT (-2) // See below */
! 487: #define SQLITE_ARGS (-3)
! 488:
! 489: /*
! 490: ** SQLite version 3 defines SQLITE_TEXT differently. To allow both
! 491: ** version 2 and version 3 to be included, undefine them both if a
! 492: ** conflict is seen. Define SQLITE2_TEXT to be the version 2 value.
! 493: */
! 494: #ifdef SQLITE_TEXT
! 495: # undef SQLITE_TEXT
! 496: #else
! 497: # define SQLITE_TEXT (-2)
! 498: #endif
! 499: #define SQLITE2_TEXT (-2)
! 500:
! 501:
! 502:
! 503: /*
! 504: ** The user function implementations call one of the following four routines
! 505: ** in order to return their results. The first parameter to each of these
! 506: ** routines is a copy of the first argument to xFunc() or xFinialize().
! 507: ** The second parameter to these routines is the result to be returned.
! 508: ** A NULL can be passed as the second parameter to sqlite_set_result_string()
! 509: ** in order to return a NULL result.
! 510: **
! 511: ** The 3rd argument to _string and _error is the number of characters to
! 512: ** take from the string. If this argument is negative, then all characters
! 513: ** up to and including the first '\000' are used.
! 514: **
! 515: ** The sqlite_set_result_string() function allocates a buffer to hold the
! 516: ** result and returns a pointer to this buffer. The calling routine
! 517: ** (that is, the implmentation of a user function) can alter the content
! 518: ** of this buffer if desired.
! 519: */
! 520: char *sqlite_set_result_string(sqlite_func*,const char*,int);
! 521: void sqlite_set_result_int(sqlite_func*,int);
! 522: void sqlite_set_result_double(sqlite_func*,double);
! 523: void sqlite_set_result_error(sqlite_func*,const char*,int);
! 524:
! 525: /*
! 526: ** The pUserData parameter to the sqlite_create_function() and
! 527: ** sqlite_create_aggregate() routines used to register user functions
! 528: ** is available to the implementation of the function using this
! 529: ** call.
! 530: */
! 531: void *sqlite_user_data(sqlite_func*);
! 532:
! 533: /*
! 534: ** Aggregate functions use the following routine to allocate
! 535: ** a structure for storing their state. The first time this routine
! 536: ** is called for a particular aggregate, a new structure of size nBytes
! 537: ** is allocated, zeroed, and returned. On subsequent calls (for the
! 538: ** same aggregate instance) the same buffer is returned. The implementation
! 539: ** of the aggregate can use the returned buffer to accumulate data.
! 540: **
! 541: ** The buffer allocated is freed automatically be SQLite.
! 542: */
! 543: void *sqlite_aggregate_context(sqlite_func*, int nBytes);
! 544:
! 545: /*
! 546: ** The next routine returns the number of calls to xStep for a particular
! 547: ** aggregate function instance. The current call to xStep counts so this
! 548: ** routine always returns at least 1.
! 549: */
! 550: int sqlite_aggregate_count(sqlite_func*);
! 551:
! 552: /*
! 553: ** This routine registers a callback with the SQLite library. The
! 554: ** callback is invoked (at compile-time, not at run-time) for each
! 555: ** attempt to access a column of a table in the database. The callback
! 556: ** returns SQLITE_OK if access is allowed, SQLITE_DENY if the entire
! 557: ** SQL statement should be aborted with an error and SQLITE_IGNORE
! 558: ** if the column should be treated as a NULL value.
! 559: */
! 560: int sqlite_set_authorizer(
! 561: sqlite*,
! 562: int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
! 563: void *pUserData
! 564: );
! 565:
! 566: /*
! 567: ** The second parameter to the access authorization function above will
! 568: ** be one of the values below. These values signify what kind of operation
! 569: ** is to be authorized. The 3rd and 4th parameters to the authorization
! 570: ** function will be parameters or NULL depending on which of the following
! 571: ** codes is used as the second parameter. The 5th parameter is the name
! 572: ** of the database ("main", "temp", etc.) if applicable. The 6th parameter
! 573: ** is the name of the inner-most trigger or view that is responsible for
! 574: ** the access attempt or NULL if this access attempt is directly from
! 575: ** input SQL code.
! 576: **
! 577: ** Arg-3 Arg-4
! 578: */
! 579: #define SQLITE_COPY 0 /* Table Name File Name */
! 580: #define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */
! 581: #define SQLITE_CREATE_TABLE 2 /* Table Name NULL */
! 582: #define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */
! 583: #define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */
! 584: #define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */
! 585: #define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */
! 586: #define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */
! 587: #define SQLITE_CREATE_VIEW 8 /* View Name NULL */
! 588: #define SQLITE_DELETE 9 /* Table Name NULL */
! 589: #define SQLITE_DROP_INDEX 10 /* Index Name Table Name */
! 590: #define SQLITE_DROP_TABLE 11 /* Table Name NULL */
! 591: #define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */
! 592: #define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */
! 593: #define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */
! 594: #define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */
! 595: #define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */
! 596: #define SQLITE_DROP_VIEW 17 /* View Name NULL */
! 597: #define SQLITE_INSERT 18 /* Table Name NULL */
! 598: #define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */
! 599: #define SQLITE_READ 20 /* Table Name Column Name */
! 600: #define SQLITE_SELECT 21 /* NULL NULL */
! 601: #define SQLITE_TRANSACTION 22 /* NULL NULL */
! 602: #define SQLITE_UPDATE 23 /* Table Name Column Name */
! 603: #define SQLITE_ATTACH 24 /* Filename NULL */
! 604: #define SQLITE_DETACH 25 /* Database Name NULL */
! 605:
! 606:
! 607: /*
! 608: ** The return value of the authorization function should be one of the
! 609: ** following constants:
! 610: */
! 611: /* #define SQLITE_OK 0 // Allow access (This is actually defined above) */
! 612: #define SQLITE_DENY 1 /* Abort the SQL statement with an error */
! 613: #define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */
! 614:
! 615: /*
! 616: ** Register a function that is called at every invocation of sqlite_exec()
! 617: ** or sqlite_compile(). This function can be used (for example) to generate
! 618: ** a log file of all SQL executed against a database.
! 619: */
! 620: void *sqlite_trace(sqlite*, void(*xTrace)(void*,const char*), void*);
! 621:
! 622: /*** The Callback-Free API
! 623: **
! 624: ** The following routines implement a new way to access SQLite that does not
! 625: ** involve the use of callbacks.
! 626: **
! 627: ** An sqlite_vm is an opaque object that represents a single SQL statement
! 628: ** that is ready to be executed.
! 629: */
! 630: typedef struct sqlite_vm sqlite_vm;
! 631:
! 632: /*
! 633: ** To execute an SQLite query without the use of callbacks, you first have
! 634: ** to compile the SQL using this routine. The 1st parameter "db" is a pointer
! 635: ** to an sqlite object obtained from sqlite_open(). The 2nd parameter
! 636: ** "zSql" is the text of the SQL to be compiled. The remaining parameters
! 637: ** are all outputs.
! 638: **
! 639: ** *pzTail is made to point to the first character past the end of the first
! 640: ** SQL statement in zSql. This routine only compiles the first statement
! 641: ** in zSql, so *pzTail is left pointing to what remains uncompiled.
! 642: **
! 643: ** *ppVm is left pointing to a "virtual machine" that can be used to execute
! 644: ** the compiled statement. Or if there is an error, *ppVm may be set to NULL.
! 645: ** If the input text contained no SQL (if the input is and empty string or
! 646: ** a comment) then *ppVm is set to NULL.
! 647: **
! 648: ** If any errors are detected during compilation, an error message is written
! 649: ** into space obtained from malloc() and *pzErrMsg is made to point to that
! 650: ** error message. The calling routine is responsible for freeing the text
! 651: ** of this message when it has finished with it. Use sqlite_freemem() to
! 652: ** free the message. pzErrMsg may be NULL in which case no error message
! 653: ** will be generated.
! 654: **
! 655: ** On success, SQLITE_OK is returned. Otherwise and error code is returned.
! 656: */
! 657: int sqlite_compile(
! 658: sqlite *db, /* The open database */
! 659: const char *zSql, /* SQL statement to be compiled */
! 660: const char **pzTail, /* OUT: uncompiled tail of zSql */
! 661: sqlite_vm **ppVm, /* OUT: the virtual machine to execute zSql */
! 662: char **pzErrmsg /* OUT: Error message. */
! 663: );
! 664:
! 665: /*
! 666: ** After an SQL statement has been compiled, it is handed to this routine
! 667: ** to be executed. This routine executes the statement as far as it can
! 668: ** go then returns. The return value will be one of SQLITE_DONE,
! 669: ** SQLITE_ERROR, SQLITE_BUSY, SQLITE_ROW, or SQLITE_MISUSE.
! 670: **
! 671: ** SQLITE_DONE means that the execute of the SQL statement is complete
! 672: ** an no errors have occurred. sqlite_step() should not be called again
! 673: ** for the same virtual machine. *pN is set to the number of columns in
! 674: ** the result set and *pazColName is set to an array of strings that
! 675: ** describe the column names and datatypes. The name of the i-th column
! 676: ** is (*pazColName)[i] and the datatype of the i-th column is
! 677: ** (*pazColName)[i+*pN]. *pazValue is set to NULL.
! 678: **
! 679: ** SQLITE_ERROR means that the virtual machine encountered a run-time
! 680: ** error. sqlite_step() should not be called again for the same
! 681: ** virtual machine. *pN is set to 0 and *pazColName and *pazValue are set
! 682: ** to NULL. Use sqlite_finalize() to obtain the specific error code
! 683: ** and the error message text for the error.
! 684: **
! 685: ** SQLITE_BUSY means that an attempt to open the database failed because
! 686: ** another thread or process is holding a lock. The calling routine
! 687: ** can try again to open the database by calling sqlite_step() again.
! 688: ** The return code will only be SQLITE_BUSY if no busy handler is registered
! 689: ** using the sqlite_busy_handler() or sqlite_busy_timeout() routines. If
! 690: ** a busy handler callback has been registered but returns 0, then this
! 691: ** routine will return SQLITE_ERROR and sqltie_finalize() will return
! 692: ** SQLITE_BUSY when it is called.
! 693: **
! 694: ** SQLITE_ROW means that a single row of the result is now available.
! 695: ** The data is contained in *pazValue. The value of the i-th column is
! 696: ** (*azValue)[i]. *pN and *pazColName are set as described in SQLITE_DONE.
! 697: ** Invoke sqlite_step() again to advance to the next row.
! 698: **
! 699: ** SQLITE_MISUSE is returned if sqlite_step() is called incorrectly.
! 700: ** For example, if you call sqlite_step() after the virtual machine
! 701: ** has halted (after a prior call to sqlite_step() has returned SQLITE_DONE)
! 702: ** or if you call sqlite_step() with an incorrectly initialized virtual
! 703: ** machine or a virtual machine that has been deleted or that is associated
! 704: ** with an sqlite structure that has been closed.
! 705: */
! 706: int sqlite_step(
! 707: sqlite_vm *pVm, /* The virtual machine to execute */
! 708: int *pN, /* OUT: Number of columns in result */
! 709: const char ***pazValue, /* OUT: Column data */
! 710: const char ***pazColName /* OUT: Column names and datatypes */
! 711: );
! 712:
! 713: /*
! 714: ** This routine is called to delete a virtual machine after it has finished
! 715: ** executing. The return value is the result code. SQLITE_OK is returned
! 716: ** if the statement executed successfully and some other value is returned if
! 717: ** there was any kind of error. If an error occurred and pzErrMsg is not
! 718: ** NULL, then an error message is written into memory obtained from malloc()
! 719: ** and *pzErrMsg is made to point to that error message. The calling routine
! 720: ** should use sqlite_freemem() to delete this message when it has finished
! 721: ** with it.
! 722: **
! 723: ** This routine can be called at any point during the execution of the
! 724: ** virtual machine. If the virtual machine has not completed execution
! 725: ** when this routine is called, that is like encountering an error or
! 726: ** an interrupt. (See sqlite_interrupt().) Incomplete updates may be
! 727: ** rolled back and transactions cancelled, depending on the circumstances,
! 728: ** and the result code returned will be SQLITE_ABORT.
! 729: */
! 730: int sqlite_finalize(sqlite_vm*, char **pzErrMsg);
! 731:
! 732: /*
! 733: ** This routine deletes the virtual machine, writes any error message to
! 734: ** *pzErrMsg and returns an SQLite return code in the same way as the
! 735: ** sqlite_finalize() function.
! 736: **
! 737: ** Additionally, if ppVm is not NULL, *ppVm is left pointing to a new virtual
! 738: ** machine loaded with the compiled version of the original query ready for
! 739: ** execution.
! 740: **
! 741: ** If sqlite_reset() returns SQLITE_SCHEMA, then *ppVm is set to NULL.
! 742: **
! 743: ******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
! 744: */
! 745: int sqlite_reset(sqlite_vm*, char **pzErrMsg);
! 746:
! 747: /*
! 748: ** If the SQL that was handed to sqlite_compile contains variables that
! 749: ** are represeted in the SQL text by a question mark ('?'). This routine
! 750: ** is used to assign values to those variables.
! 751: **
! 752: ** The first parameter is a virtual machine obtained from sqlite_compile().
! 753: ** The 2nd "idx" parameter determines which variable in the SQL statement
! 754: ** to bind the value to. The left most '?' is 1. The 3rd parameter is
! 755: ** the value to assign to that variable. The 4th parameter is the number
! 756: ** of bytes in the value, including the terminating \000 for strings.
! 757: ** Finally, the 5th "copy" parameter is TRUE if SQLite should make its
! 758: ** own private copy of this value, or false if the space that the 3rd
! 759: ** parameter points to will be unchanging and can be used directly by
! 760: ** SQLite.
! 761: **
! 762: ** Unbound variables are treated as having a value of NULL. To explicitly
! 763: ** set a variable to NULL, call this routine with the 3rd parameter as a
! 764: ** NULL pointer.
! 765: **
! 766: ** If the 4th "len" parameter is -1, then strlen() is used to find the
! 767: ** length.
! 768: **
! 769: ** This routine can only be called immediately after sqlite_compile()
! 770: ** or sqlite_reset() and before any calls to sqlite_step().
! 771: **
! 772: ******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
! 773: */
! 774: int sqlite_bind(sqlite_vm*, int idx, const char *value, int len, int copy);
! 775:
! 776: /*
! 777: ** This routine configures a callback function - the progress callback - that
! 778: ** is invoked periodically during long running calls to sqlite_exec(),
! 779: ** sqlite_step() and sqlite_get_table(). An example use for this API is to keep
! 780: ** a GUI updated during a large query.
! 781: **
! 782: ** The progress callback is invoked once for every N virtual machine opcodes,
! 783: ** where N is the second argument to this function. The progress callback
! 784: ** itself is identified by the third argument to this function. The fourth
! 785: ** argument to this function is a void pointer passed to the progress callback
! 786: ** function each time it is invoked.
! 787: **
! 788: ** If a call to sqlite_exec(), sqlite_step() or sqlite_get_table() results
! 789: ** in less than N opcodes being executed, then the progress callback is not
! 790: ** invoked.
! 791: **
! 792: ** Calling this routine overwrites any previously installed progress callback.
! 793: ** To remove the progress callback altogether, pass NULL as the third
! 794: ** argument to this function.
! 795: **
! 796: ** If the progress callback returns a result other than 0, then the current
! 797: ** query is immediately terminated and any database changes rolled back. If the
! 798: ** query was part of a larger transaction, then the transaction is not rolled
! 799: ** back and remains active. The sqlite_exec() call returns SQLITE_ABORT.
! 800: **
! 801: ******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
! 802: */
! 803: void sqlite_progress_handler(sqlite*, int, int(*)(void*), void*);
! 804:
! 805: /*
! 806: ** Register a callback function to be invoked whenever a new transaction
! 807: ** is committed. The pArg argument is passed through to the callback.
! 808: ** callback. If the callback function returns non-zero, then the commit
! 809: ** is converted into a rollback.
! 810: **
! 811: ** If another function was previously registered, its pArg value is returned.
! 812: ** Otherwise NULL is returned.
! 813: **
! 814: ** Registering a NULL function disables the callback.
! 815: **
! 816: ******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
! 817: */
! 818: void *sqlite_commit_hook(sqlite*, int(*)(void*), void*);
! 819:
! 820: /*
! 821: ** Open an encrypted SQLite database. If pKey==0 or nKey==0, this routine
! 822: ** is the same as sqlite_open().
! 823: **
! 824: ** The code to implement this API is not available in the public release
! 825: ** of SQLite.
! 826: */
! 827: sqlite *sqlite_open_encrypted(
! 828: const char *zFilename, /* Name of the encrypted database */
! 829: const void *pKey, /* Pointer to the key */
! 830: int nKey, /* Number of bytes in the key */
! 831: int *pErrcode, /* Write error code here */
! 832: char **pzErrmsg /* Write error message here */
! 833: );
! 834:
! 835: /*
! 836: ** Change the key on an open database. If the current database is not
! 837: ** encrypted, this routine will encrypt it. If pNew==0 or nNew==0, the
! 838: ** database is decrypted.
! 839: **
! 840: ** The code to implement this API is not available in the public release
! 841: ** of SQLite.
! 842: */
! 843: int sqlite_rekey(
! 844: sqlite *db, /* Database to be rekeyed */
! 845: const void *pKey, int nKey /* The new key */
! 846: );
! 847:
! 848: /*
! 849: ** Encode a binary buffer "in" of size n bytes so that it contains
! 850: ** no instances of characters '\'' or '\000'. The output is
! 851: ** null-terminated and can be used as a string value in an INSERT
! 852: ** or UPDATE statement. Use sqlite_decode_binary() to convert the
! 853: ** string back into its original binary.
! 854: **
! 855: ** The result is written into a preallocated output buffer "out".
! 856: ** "out" must be able to hold at least 2 +(257*n)/254 bytes.
! 857: ** In other words, the output will be expanded by as much as 3
! 858: ** bytes for every 254 bytes of input plus 2 bytes of fixed overhead.
! 859: ** (This is approximately 2 + 1.0118*n or about a 1.2% size increase.)
! 860: **
! 861: ** The return value is the number of characters in the encoded
! 862: ** string, excluding the "\000" terminator.
! 863: **
! 864: ** If out==NULL then no output is generated but the routine still returns
! 865: ** the number of characters that would have been generated if out had
! 866: ** not been NULL.
! 867: */
! 868: int sqlite_encode_binary(const unsigned char *in, int n, unsigned char *out);
! 869:
! 870: /*
! 871: ** Decode the string "in" into binary data and write it into "out".
! 872: ** This routine reverses the encoding created by sqlite_encode_binary().
! 873: ** The output will always be a few bytes less than the input. The number
! 874: ** of bytes of output is returned. If the input is not a well-formed
! 875: ** encoding, -1 is returned.
! 876: **
! 877: ** The "in" and "out" parameters may point to the same buffer in order
! 878: ** to decode a string in place.
! 879: */
! 880: int sqlite_decode_binary(const unsigned char *in, unsigned char *out);
! 881:
! 882: #ifdef __cplusplus
! 883: } /* End of the 'extern "C"' block */
! 884: #endif
! 885:
! 886: #endif /* _SQLITE_H_ */
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to sqlite.h.in CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / php / ext / sqlite / libsqlite / src