Back to index

php5  5.3.10
sqlite.w32.h
Go to the documentation of this file.
00001 /*
00002 ** 2001 September 15
00003 **
00004 ** The author disclaims copyright to this source code.  In place of
00005 ** a legal notice, here is a blessing:
00006 **
00007 **    May you do good and not evil.
00008 **    May you find forgiveness for yourself and forgive others.
00009 **    May you share freely, never taking more than you give.
00010 **
00011 *************************************************************************
00012 ** This header file defines the interface that the SQLite library
00013 ** presents to client programs.
00014 **
00015 ** @(#) $Id: sqlite.w32.h 203289 2005-12-20 15:26:26Z iliaa $
00016 */
00017 #ifndef _SQLITE_H_
00018 #define _SQLITE_H_
00019 #include <stdarg.h>     /* Needed for the definition of va_list */
00020 
00021 /*
00022 ** Make sure we can call this stuff from C++.
00023 */
00024 #ifdef __cplusplus
00025 extern "C" {
00026 #endif
00027 
00028 /*
00029 ** The version of the SQLite library.
00030 */
00031 #define SQLITE_VERSION         "2.8.17"
00032 
00033 /*
00034 ** The version string is also compiled into the library so that a program
00035 ** can check to make sure that the lib*.a file and the *.h file are from
00036 ** the same version.
00037 */
00038 extern const char sqlite_version[];
00039 
00040 /*
00041 ** The SQLITE_UTF8 macro is defined if the library expects to see
00042 ** UTF-8 encoded data.  The SQLITE_ISO8859 macro is defined if the
00043 ** iso8859 encoded should be used.
00044 */
00045 #define SQLITE_ISO8859 1
00046 
00047 /*
00048 ** The following constant holds one of two strings, "UTF-8" or "iso8859",
00049 ** depending on which character encoding the SQLite library expects to
00050 ** see.  The character encoding makes a difference for the LIKE and GLOB
00051 ** operators and for the LENGTH() and SUBSTR() functions.
00052 */
00053 extern const char sqlite_encoding[];
00054 
00055 /*
00056 ** Each open sqlite database is represented by an instance of the
00057 ** following opaque structure.
00058 */
00059 typedef struct sqlite sqlite;
00060 
00061 /*
00062 ** A function to open a new sqlite database.  
00063 **
00064 ** If the database does not exist and mode indicates write
00065 ** permission, then a new database is created.  If the database
00066 ** does not exist and mode does not indicate write permission,
00067 ** then the open fails, an error message generated (if errmsg!=0)
00068 ** and the function returns 0.
00069 ** 
00070 ** If mode does not indicates user write permission, then the 
00071 ** database is opened read-only.
00072 **
00073 ** The Truth:  As currently implemented, all databases are opened
00074 ** for writing all the time.  Maybe someday we will provide the
00075 ** ability to open a database readonly.  The mode parameters is
00076 ** provided in anticipation of that enhancement.
00077 */
00078 sqlite *sqlite_open(const char *filename, int mode, char **errmsg);
00079 
00080 /*
00081 ** A function to close the database.
00082 **
00083 ** Call this function with a pointer to a structure that was previously
00084 ** returned from sqlite_open() and the corresponding database will by closed.
00085 */
00086 void sqlite_close(sqlite *);
00087 
00088 /*
00089 ** The type for a callback function.
00090 */
00091 typedef int (*sqlite_callback)(void*,int,char**, char**);
00092 
00093 /*
00094 ** A function to executes one or more statements of SQL.
00095 **
00096 ** If one or more of the SQL statements are queries, then
00097 ** the callback function specified by the 3rd parameter is
00098 ** invoked once for each row of the query result.  This callback
00099 ** should normally return 0.  If the callback returns a non-zero
00100 ** value then the query is aborted, all subsequent SQL statements
00101 ** are skipped and the sqlite_exec() function returns the SQLITE_ABORT.
00102 **
00103 ** The 4th parameter is an arbitrary pointer that is passed
00104 ** to the callback function as its first parameter.
00105 **
00106 ** The 2nd parameter to the callback function is the number of
00107 ** columns in the query result.  The 3rd parameter to the callback
00108 ** is an array of strings holding the values for each column.
00109 ** The 4th parameter to the callback is an array of strings holding
00110 ** the names of each column.
00111 **
00112 ** The callback function may be NULL, even for queries.  A NULL
00113 ** callback is not an error.  It just means that no callback
00114 ** will be invoked.
00115 **
00116 ** If an error occurs while parsing or evaluating the SQL (but
00117 ** not while executing the callback) then an appropriate error
00118 ** message is written into memory obtained from malloc() and
00119 ** *errmsg is made to point to that message.  The calling function
00120 ** is responsible for freeing the memory that holds the error
00121 ** message.   Use sqlite_freemem() for this.  If errmsg==NULL,
00122 ** then no error message is ever written.
00123 **
00124 ** The return value is is SQLITE_OK if there are no errors and
00125 ** some other return code if there is an error.  The particular
00126 ** return value depends on the type of error. 
00127 **
00128 ** If the query could not be executed because a database file is
00129 ** locked or busy, then this function returns SQLITE_BUSY.  (This
00130 ** behavior can be modified somewhat using the sqlite_busy_handler()
00131 ** and sqlite_busy_timeout() functions below.)
00132 */
00133 int sqlite_exec(
00134   sqlite*,                      /* An open database */
00135   const char *sql,              /* SQL to be executed */
00136   sqlite_callback,              /* Callback function */
00137   void *,                       /* 1st argument to callback function */
00138   char **errmsg                 /* Error msg written here */
00139 );
00140 
00141 /*
00142 ** Return values for sqlite_exec() and sqlite_step()
00143 */
00144 #define SQLITE_OK           0   /* Successful result */
00145 #define SQLITE_ERROR        1   /* SQL error or missing database */
00146 #define SQLITE_INTERNAL     2   /* An internal logic error in SQLite */
00147 #define SQLITE_PERM         3   /* Access permission denied */
00148 #define SQLITE_ABORT        4   /* Callback routine requested an abort */
00149 #define SQLITE_BUSY         5   /* The database file is locked */
00150 #define SQLITE_LOCKED       6   /* A table in the database is locked */
00151 #define SQLITE_NOMEM        7   /* A malloc() failed */
00152 #define SQLITE_READONLY     8   /* Attempt to write a readonly database */
00153 #define SQLITE_INTERRUPT    9   /* Operation terminated by sqlite_interrupt() */
00154 #define SQLITE_IOERR       10   /* Some kind of disk I/O error occurred */
00155 #define SQLITE_CORRUPT     11   /* The database disk image is malformed */
00156 #define SQLITE_NOTFOUND    12   /* (Internal Only) Table or record not found */
00157 #define SQLITE_FULL        13   /* Insertion failed because database is full */
00158 #define SQLITE_CANTOPEN    14   /* Unable to open the database file */
00159 #define SQLITE_PROTOCOL    15   /* Database lock protocol error */
00160 #define SQLITE_EMPTY       16   /* (Internal Only) Database table is empty */
00161 #define SQLITE_SCHEMA      17   /* The database schema changed */
00162 #define SQLITE_TOOBIG      18   /* Too much data for one row of a table */
00163 #define SQLITE_CONSTRAINT  19   /* Abort due to contraint violation */
00164 #define SQLITE_MISMATCH    20   /* Data type mismatch */
00165 #define SQLITE_MISUSE      21   /* Library used incorrectly */
00166 #define SQLITE_NOLFS       22   /* Uses OS features not supported on host */
00167 #define SQLITE_AUTH        23   /* Authorization denied */
00168 #define SQLITE_FORMAT      24   /* Auxiliary database format error */
00169 #define SQLITE_RANGE       25   /* 2nd parameter to sqlite_bind out of range */
00170 #define SQLITE_NOTADB      26   /* File opened that is not a database file */
00171 #define SQLITE_ROW         100  /* sqlite_step() has another row ready */
00172 #define SQLITE_DONE        101  /* sqlite_step() has finished executing */
00173 
00174 /*
00175 ** Each entry in an SQLite table has a unique integer key.  (The key is
00176 ** the value of the INTEGER PRIMARY KEY column if there is such a column,
00177 ** otherwise the key is generated at random.  The unique key is always
00178 ** available as the ROWID, OID, or _ROWID_ column.)  The following routine
00179 ** returns the integer key of the most recent insert in the database.
00180 **
00181 ** This function is similar to the mysql_insert_id() function from MySQL.
00182 */
00183 int sqlite_last_insert_rowid(sqlite*);
00184 
00185 /*
00186 ** This function returns the number of database rows that were changed
00187 ** (or inserted or deleted) by the most recent called sqlite_exec().
00188 **
00189 ** All changes are counted, even if they were later undone by a
00190 ** ROLLBACK or ABORT.  Except, changes associated with creating and
00191 ** dropping tables are not counted.
00192 **
00193 ** If a callback invokes sqlite_exec() recursively, then the changes
00194 ** in the inner, recursive call are counted together with the changes
00195 ** in the outer call.
00196 **
00197 ** SQLite implements the command "DELETE FROM table" without a WHERE clause
00198 ** by dropping and recreating the table.  (This is much faster than going
00199 ** through and deleting individual elements form the table.)  Because of
00200 ** this optimization, the change count for "DELETE FROM table" will be
00201 ** zero regardless of the number of elements that were originally in the
00202 ** table. To get an accurate count of the number of rows deleted, use
00203 ** "DELETE FROM table WHERE 1" instead.
00204 */
00205 int sqlite_changes(sqlite*);
00206 
00207 /* If the parameter to this routine is one of the return value constants
00208 ** defined above, then this routine returns a constant text string which
00209 ** descripts (in English) the meaning of the return value.
00210 */
00211 const char *sqlite_error_string(int);
00212 #define sqliteErrStr sqlite_error_string  /* Legacy. Do not use in new code. */
00213 
00214 /* This function causes any pending database operation to abort and
00215 ** return at its earliest opportunity.  This routine is typically
00216 ** called in response to a user action such as pressing "Cancel"
00217 ** or Ctrl-C where the user wants a long query operation to halt
00218 ** immediately.
00219 */
00220 void sqlite_interrupt(sqlite*);
00221 
00222 
00223 /* This function returns true if the given input string comprises
00224 ** one or more complete SQL statements.
00225 **
00226 ** The algorithm is simple.  If the last token other than spaces
00227 ** and comments is a semicolon, then return true.  otherwise return
00228 ** false.
00229 */
00230 int sqlite_complete(const char *sql);
00231 
00232 /*
00233 ** This routine identifies a callback function that is invoked
00234 ** whenever an attempt is made to open a database table that is
00235 ** currently locked by another process or thread.  If the busy callback
00236 ** is NULL, then sqlite_exec() returns SQLITE_BUSY immediately if
00237 ** it finds a locked table.  If the busy callback is not NULL, then
00238 ** sqlite_exec() invokes the callback with three arguments.  The
00239 ** second argument is the name of the locked table and the third
00240 ** argument is the number of times the table has been busy.  If the
00241 ** busy callback returns 0, then sqlite_exec() immediately returns
00242 ** SQLITE_BUSY.  If the callback returns non-zero, then sqlite_exec()
00243 ** tries to open the table again and the cycle repeats.
00244 **
00245 ** The default busy callback is NULL.
00246 **
00247 ** Sqlite is re-entrant, so the busy handler may start a new query. 
00248 ** (It is not clear why anyone would every want to do this, but it
00249 ** is allowed, in theory.)  But the busy handler may not close the
00250 ** database.  Closing the database from a busy handler will delete 
00251 ** data structures out from under the executing query and will 
00252 ** probably result in a coredump.
00253 */
00254 void sqlite_busy_handler(sqlite*, int(*)(void*,const char*,int), void*);
00255 
00256 /*
00257 ** This routine sets a busy handler that sleeps for a while when a
00258 ** table is locked.  The handler will sleep multiple times until 
00259 ** at least "ms" milleseconds of sleeping have been done.  After
00260 ** "ms" milleseconds of sleeping, the handler returns 0 which
00261 ** causes sqlite_exec() to return SQLITE_BUSY.
00262 **
00263 ** Calling this routine with an argument less than or equal to zero
00264 ** turns off all busy handlers.
00265 */
00266 void sqlite_busy_timeout(sqlite*, int ms);
00267 
00268 /*
00269 ** This next routine is really just a wrapper around sqlite_exec().
00270 ** Instead of invoking a user-supplied callback for each row of the
00271 ** result, this routine remembers each row of the result in memory
00272 ** obtained from malloc(), then returns all of the result after the
00273 ** query has finished. 
00274 **
00275 ** As an example, suppose the query result where this table:
00276 **
00277 **        Name        | Age
00278 **        -----------------------
00279 **        Alice       | 43
00280 **        Bob         | 28
00281 **        Cindy       | 21
00282 **
00283 ** If the 3rd argument were &azResult then after the function returns
00284 ** azResult will contain the following data:
00285 **
00286 **        azResult[0] = "Name";
00287 **        azResult[1] = "Age";
00288 **        azResult[2] = "Alice";
00289 **        azResult[3] = "43";
00290 **        azResult[4] = "Bob";
00291 **        azResult[5] = "28";
00292 **        azResult[6] = "Cindy";
00293 **        azResult[7] = "21";
00294 **
00295 ** Notice that there is an extra row of data containing the column
00296 ** headers.  But the *nrow return value is still 3.  *ncolumn is
00297 ** set to 2.  In general, the number of values inserted into azResult
00298 ** will be ((*nrow) + 1)*(*ncolumn).
00299 **
00300 ** After the calling function has finished using the result, it should 
00301 ** pass the result data pointer to sqlite_free_table() in order to 
00302 ** release the memory that was malloc-ed.  Because of the way the 
00303 ** malloc() happens, the calling function must not try to call 
00304 ** malloc() directly.  Only sqlite_free_table() is able to release 
00305 ** the memory properly and safely.
00306 **
00307 ** The return value of this routine is the same as from sqlite_exec().
00308 */
00309 int sqlite_get_table(
00310   sqlite*,               /* An open database */
00311   const char *sql,       /* SQL to be executed */
00312   char ***resultp,       /* Result written to a char *[]  that this points to */
00313   int *nrow,             /* Number of result rows written here */
00314   int *ncolumn,          /* Number of result columns written here */
00315   char **errmsg          /* Error msg written here */
00316 );
00317 
00318 /*
00319 ** Call this routine to free the memory that sqlite_get_table() allocated.
00320 */
00321 void sqlite_free_table(char **result);
00322 
00323 /*
00324 ** The following routines are wrappers around sqlite_exec() and
00325 ** sqlite_get_table().  The only difference between the routines that
00326 ** follow and the originals is that the second argument to the 
00327 ** routines that follow is really a printf()-style format
00328 ** string describing the SQL to be executed.  Arguments to the format
00329 ** string appear at the end of the argument list.
00330 **
00331 ** All of the usual printf formatting options apply.  In addition, there
00332 ** is a "%q" option.  %q works like %s in that it substitutes a null-terminated
00333 ** string from the argument list.  But %q also doubles every '\'' character.
00334 ** %q is designed for use inside a string literal.  By doubling each '\''
00335 ** character it escapes that character and allows it to be inserted into
00336 ** the string.
00337 **
00338 ** For example, so some string variable contains text as follows:
00339 **
00340 **      char *zText = "It's a happy day!";
00341 **
00342 ** We can use this text in an SQL statement as follows:
00343 **
00344 **      sqlite_exec_printf(db, "INSERT INTO table VALUES('%q')",
00345 **          callback1, 0, 0, zText);
00346 **
00347 ** Because the %q format string is used, the '\'' character in zText
00348 ** is escaped and the SQL generated is as follows:
00349 **
00350 **      INSERT INTO table1 VALUES('It''s a happy day!')
00351 **
00352 ** This is correct.  Had we used %s instead of %q, the generated SQL
00353 ** would have looked like this:
00354 **
00355 **      INSERT INTO table1 VALUES('It's a happy day!');
00356 **
00357 ** This second example is an SQL syntax error.  As a general rule you
00358 ** should always use %q instead of %s when inserting text into a string 
00359 ** literal.
00360 */
00361 int sqlite_exec_printf(
00362   sqlite*,                      /* An open database */
00363   const char *sqlFormat,        /* printf-style format string for the SQL */
00364   sqlite_callback,              /* Callback function */
00365   void *,                       /* 1st argument to callback function */
00366   char **errmsg,                /* Error msg written here */
00367   ...                           /* Arguments to the format string. */
00368 );
00369 int sqlite_exec_vprintf(
00370   sqlite*,                      /* An open database */
00371   const char *sqlFormat,        /* printf-style format string for the SQL */
00372   sqlite_callback,              /* Callback function */
00373   void *,                       /* 1st argument to callback function */
00374   char **errmsg,                /* Error msg written here */
00375   va_list ap                    /* Arguments to the format string. */
00376 );
00377 int sqlite_get_table_printf(
00378   sqlite*,               /* An open database */
00379   const char *sqlFormat, /* printf-style format string for the SQL */
00380   char ***resultp,       /* Result written to a char *[]  that this points to */
00381   int *nrow,             /* Number of result rows written here */
00382   int *ncolumn,          /* Number of result columns written here */
00383   char **errmsg,         /* Error msg written here */
00384   ...                    /* Arguments to the format string */
00385 );
00386 int sqlite_get_table_vprintf(
00387   sqlite*,               /* An open database */
00388   const char *sqlFormat, /* printf-style format string for the SQL */
00389   char ***resultp,       /* Result written to a char *[]  that this points to */
00390   int *nrow,             /* Number of result rows written here */
00391   int *ncolumn,          /* Number of result columns written here */
00392   char **errmsg,         /* Error msg written here */
00393   va_list ap             /* Arguments to the format string */
00394 );
00395 char *sqlite_mprintf(const char*,...);
00396 char *sqlite_vmprintf(const char*, va_list);
00397 
00398 /*
00399 ** Windows systems should call this routine to free memory that
00400 ** is returned in the in the errmsg parameter of sqlite_open() when
00401 ** SQLite is a DLL.  For some reason, it does not work to call free()
00402 ** directly.
00403 */
00404 void sqlite_freemem(void *p);
00405 
00406 /*
00407 ** Windows systems need functions to call to return the sqlite_version
00408 ** and sqlite_encoding strings.
00409 */
00410 const char *sqlite_libversion(void);
00411 const char *sqlite_libencoding(void);
00412 
00413 /*
00414 ** A pointer to the following structure is used to communicate with
00415 ** the implementations of user-defined functions.
00416 */
00417 typedef struct sqlite_func sqlite_func;
00418 
00419 /*
00420 ** Use the following routines to create new user-defined functions.  See
00421 ** the documentation for details.
00422 */
00423 int sqlite_create_function(
00424   sqlite*,                  /* Database where the new function is registered */
00425   const char *zName,        /* Name of the new function */
00426   int nArg,                 /* Number of arguments.  -1 means any number */
00427   void (*xFunc)(sqlite_func*,int,const char**),  /* C code to implement */
00428   void *pUserData           /* Available via the sqlite_user_data() call */
00429 );
00430 int sqlite_create_aggregate(
00431   sqlite*,                  /* Database where the new function is registered */
00432   const char *zName,        /* Name of the function */
00433   int nArg,                 /* Number of arguments */
00434   void (*xStep)(sqlite_func*,int,const char**), /* Called for each row */
00435   void (*xFinalize)(sqlite_func*),       /* Called once to get final result */
00436   void *pUserData           /* Available via the sqlite_user_data() call */
00437 );
00438 
00439 /*
00440 ** Use the following routine to define the datatype returned by a
00441 ** user-defined function.  The second argument can be one of the
00442 ** constants SQLITE_NUMERIC, SQLITE_TEXT, or SQLITE_ARGS or it
00443 ** can be an integer greater than or equal to zero.  The datatype
00444 ** will be numeric or text (the only two types supported) if the
00445 ** argument is SQLITE_NUMERIC or SQLITE_TEXT.  If the argument is
00446 ** SQLITE_ARGS, then the datatype is numeric if any argument to the
00447 ** function is numeric and is text otherwise.  If the second argument
00448 ** is an integer, then the datatype of the result is the same as the
00449 ** parameter to the function that corresponds to that integer.
00450 */
00451 int sqlite_function_type(
00452   sqlite *db,               /* The database there the function is registered */
00453   const char *zName,        /* Name of the function */
00454   int datatype              /* The datatype for this function */
00455 );
00456 #define SQLITE_NUMERIC     (-1)
00457 #define SQLITE_TEXT        (-2)
00458 #define SQLITE_ARGS        (-3)
00459 
00460 /*
00461 ** The user function implementations call one of the following four routines
00462 ** in order to return their results.  The first parameter to each of these
00463 ** routines is a copy of the first argument to xFunc() or xFinialize().
00464 ** The second parameter to these routines is the result to be returned.
00465 ** A NULL can be passed as the second parameter to sqlite_set_result_string()
00466 ** in order to return a NULL result.
00467 **
00468 ** The 3rd argument to _string and _error is the number of characters to
00469 ** take from the string.  If this argument is negative, then all characters
00470 ** up to and including the first '\000' are used.
00471 **
00472 ** The sqlite_set_result_string() function allocates a buffer to hold the
00473 ** result and returns a pointer to this buffer.  The calling routine
00474 ** (that is, the implmentation of a user function) can alter the content
00475 ** of this buffer if desired.
00476 */
00477 char *sqlite_set_result_string(sqlite_func*,const char*,int);
00478 void sqlite_set_result_int(sqlite_func*,int);
00479 void sqlite_set_result_double(sqlite_func*,double);
00480 void sqlite_set_result_error(sqlite_func*,const char*,int);
00481 
00482 /*
00483 ** The pUserData parameter to the sqlite_create_function() and
00484 ** sqlite_create_aggregate() routines used to register user functions
00485 ** is available to the implementation of the function using this
00486 ** call.
00487 */
00488 void *sqlite_user_data(sqlite_func*);
00489 
00490 /*
00491 ** Aggregate functions use the following routine to allocate
00492 ** a structure for storing their state.  The first time this routine
00493 ** is called for a particular aggregate, a new structure of size nBytes
00494 ** is allocated, zeroed, and returned.  On subsequent calls (for the
00495 ** same aggregate instance) the same buffer is returned.  The implementation
00496 ** of the aggregate can use the returned buffer to accumulate data.
00497 **
00498 ** The buffer allocated is freed automatically be SQLite.
00499 */
00500 void *sqlite_aggregate_context(sqlite_func*, int nBytes);
00501 
00502 /*
00503 ** The next routine returns the number of calls to xStep for a particular
00504 ** aggregate function instance.  The current call to xStep counts so this
00505 ** routine always returns at least 1.
00506 */
00507 int sqlite_aggregate_count(sqlite_func*);
00508 
00509 /*
00510 ** This routine registers a callback with the SQLite library.  The
00511 ** callback is invoked (at compile-time, not at run-time) for each
00512 ** attempt to access a column of a table in the database.  The callback
00513 ** returns SQLITE_OK if access is allowed, SQLITE_DENY if the entire
00514 ** SQL statement should be aborted with an error and SQLITE_IGNORE
00515 ** if the column should be treated as a NULL value.
00516 */
00517 int sqlite_set_authorizer(
00518   sqlite*,
00519   int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
00520   void *pUserData
00521 );
00522 
00523 /*
00524 ** The second parameter to the access authorization function above will
00525 ** be one of the values below.  These values signify what kind of operation
00526 ** is to be authorized.  The 3rd and 4th parameters to the authorization
00527 ** function will be parameters or NULL depending on which of the following
00528 ** codes is used as the second parameter.  The 5th parameter is the name
00529 ** of the database ("main", "temp", etc.) if applicable.  The 6th parameter
00530 ** is the name of the inner-most trigger or view that is responsible for
00531 ** the access attempt or NULL if this access attempt is directly from 
00532 ** input SQL code.
00533 **
00534 **                                          Arg-3           Arg-4
00535 */
00536 #define SQLITE_COPY                  0   /* Table Name      File Name       */
00537 #define SQLITE_CREATE_INDEX          1   /* Index Name      Table Name      */
00538 #define SQLITE_CREATE_TABLE          2   /* Table Name      NULL            */
00539 #define SQLITE_CREATE_TEMP_INDEX     3   /* Index Name      Table Name      */
00540 #define SQLITE_CREATE_TEMP_TABLE     4   /* Table Name      NULL            */
00541 #define SQLITE_CREATE_TEMP_TRIGGER   5   /* Trigger Name    Table Name      */
00542 #define SQLITE_CREATE_TEMP_VIEW      6   /* View Name       NULL            */
00543 #define SQLITE_CREATE_TRIGGER        7   /* Trigger Name    Table Name      */
00544 #define SQLITE_CREATE_VIEW           8   /* View Name       NULL            */
00545 #define SQLITE_DELETE                9   /* Table Name      NULL            */
00546 #define SQLITE_DROP_INDEX           10   /* Index Name      Table Name      */
00547 #define SQLITE_DROP_TABLE           11   /* Table Name      NULL            */
00548 #define SQLITE_DROP_TEMP_INDEX      12   /* Index Name      Table Name      */
00549 #define SQLITE_DROP_TEMP_TABLE      13   /* Table Name      NULL            */
00550 #define SQLITE_DROP_TEMP_TRIGGER    14   /* Trigger Name    Table Name      */
00551 #define SQLITE_DROP_TEMP_VIEW       15   /* View Name       NULL            */
00552 #define SQLITE_DROP_TRIGGER         16   /* Trigger Name    Table Name      */
00553 #define SQLITE_DROP_VIEW            17   /* View Name       NULL            */
00554 #define SQLITE_INSERT               18   /* Table Name      NULL            */
00555 #define SQLITE_PRAGMA               19   /* Pragma Name     1st arg or NULL */
00556 #define SQLITE_READ                 20   /* Table Name      Column Name     */
00557 #define SQLITE_SELECT               21   /* NULL            NULL            */
00558 #define SQLITE_TRANSACTION          22   /* NULL            NULL            */
00559 #define SQLITE_UPDATE               23   /* Table Name      Column Name     */
00560 #define SQLITE_ATTACH               24   /* Filename        NULL            */
00561 #define SQLITE_DETACH               25   /* Database Name   NULL            */
00562 
00563 
00564 /*
00565 ** The return value of the authorization function should be one of the
00566 ** following constants:
00567 */
00568 /* #define SQLITE_OK  0   // Allow access (This is actually defined above) */
00569 #define SQLITE_DENY   1   /* Abort the SQL statement with an error */
00570 #define SQLITE_IGNORE 2   /* Don't allow access, but don't generate an error */
00571 
00572 /*
00573 ** Register a function that is called at every invocation of sqlite_exec()
00574 ** or sqlite_compile().  This function can be used (for example) to generate
00575 ** a log file of all SQL executed against a database.
00576 */
00577 void *sqlite_trace(sqlite*, void(*xTrace)(void*,const char*), void*);
00578 
00579 /*** The Callback-Free API
00580 ** 
00581 ** The following routines implement a new way to access SQLite that does not
00582 ** involve the use of callbacks.
00583 **
00584 ** An sqlite_vm is an opaque object that represents a single SQL statement
00585 ** that is ready to be executed.
00586 */
00587 typedef struct sqlite_vm sqlite_vm;
00588 
00589 /*
00590 ** To execute an SQLite query without the use of callbacks, you first have
00591 ** to compile the SQL using this routine.  The 1st parameter "db" is a pointer
00592 ** to an sqlite object obtained from sqlite_open().  The 2nd parameter
00593 ** "zSql" is the text of the SQL to be compiled.   The remaining parameters
00594 ** are all outputs.
00595 **
00596 ** *pzTail is made to point to the first character past the end of the first
00597 ** SQL statement in zSql.  This routine only compiles the first statement
00598 ** in zSql, so *pzTail is left pointing to what remains uncompiled.
00599 **
00600 ** *ppVm is left pointing to a "virtual machine" that can be used to execute
00601 ** the compiled statement.  Or if there is an error, *ppVm may be set to NULL.
00602 ** If the input text contained no SQL (if the input is and empty string or
00603 ** a comment) then *ppVm is set to NULL.
00604 **
00605 ** If any errors are detected during compilation, an error message is written
00606 ** into space obtained from malloc() and *pzErrMsg is made to point to that
00607 ** error message.  The calling routine is responsible for freeing the text
00608 ** of this message when it has finished with it.  Use sqlite_freemem() to
00609 ** free the message.  pzErrMsg may be NULL in which case no error message
00610 ** will be generated.
00611 **
00612 ** On success, SQLITE_OK is returned.  Otherwise and error code is returned.
00613 */
00614 int sqlite_compile(
00615   sqlite *db,                   /* The open database */
00616   const char *zSql,             /* SQL statement to be compiled */
00617   const char **pzTail,          /* OUT: uncompiled tail of zSql */
00618   sqlite_vm **ppVm,             /* OUT: the virtual machine to execute zSql */
00619   char **pzErrmsg               /* OUT: Error message. */
00620 );
00621 
00622 /*
00623 ** After an SQL statement has been compiled, it is handed to this routine
00624 ** to be executed.  This routine executes the statement as far as it can
00625 ** go then returns.  The return value will be one of SQLITE_DONE,
00626 ** SQLITE_ERROR, SQLITE_BUSY, SQLITE_ROW, or SQLITE_MISUSE.
00627 **
00628 ** SQLITE_DONE means that the execute of the SQL statement is complete
00629 ** an no errors have occurred.  sqlite_step() should not be called again
00630 ** for the same virtual machine.  *pN is set to the number of columns in
00631 ** the result set and *pazColName is set to an array of strings that
00632 ** describe the column names and datatypes.  The name of the i-th column
00633 ** is (*pazColName)[i] and the datatype of the i-th column is
00634 ** (*pazColName)[i+*pN].  *pazValue is set to NULL.
00635 **
00636 ** SQLITE_ERROR means that the virtual machine encountered a run-time
00637 ** error.  sqlite_step() should not be called again for the same
00638 ** virtual machine.  *pN is set to 0 and *pazColName and *pazValue are set
00639 ** to NULL.  Use sqlite_finalize() to obtain the specific error code
00640 ** and the error message text for the error.
00641 **
00642 ** SQLITE_BUSY means that an attempt to open the database failed because
00643 ** another thread or process is holding a lock.  The calling routine
00644 ** can try again to open the database by calling sqlite_step() again.
00645 ** The return code will only be SQLITE_BUSY if no busy handler is registered
00646 ** using the sqlite_busy_handler() or sqlite_busy_timeout() routines.  If
00647 ** a busy handler callback has been registered but returns 0, then this
00648 ** routine will return SQLITE_ERROR and sqltie_finalize() will return
00649 ** SQLITE_BUSY when it is called.
00650 **
00651 ** SQLITE_ROW means that a single row of the result is now available.
00652 ** The data is contained in *pazValue.  The value of the i-th column is
00653 ** (*azValue)[i].  *pN and *pazColName are set as described in SQLITE_DONE.
00654 ** Invoke sqlite_step() again to advance to the next row.
00655 **
00656 ** SQLITE_MISUSE is returned if sqlite_step() is called incorrectly.
00657 ** For example, if you call sqlite_step() after the virtual machine
00658 ** has halted (after a prior call to sqlite_step() has returned SQLITE_DONE)
00659 ** or if you call sqlite_step() with an incorrectly initialized virtual
00660 ** machine or a virtual machine that has been deleted or that is associated
00661 ** with an sqlite structure that has been closed.
00662 */
00663 int sqlite_step(
00664   sqlite_vm *pVm,              /* The virtual machine to execute */
00665   int *pN,                     /* OUT: Number of columns in result */
00666   const char ***pazValue,      /* OUT: Column data */
00667   const char ***pazColName     /* OUT: Column names and datatypes */
00668 );
00669 
00670 /*
00671 ** This routine is called to delete a virtual machine after it has finished
00672 ** executing.  The return value is the result code.  SQLITE_OK is returned
00673 ** if the statement executed successfully and some other value is returned if
00674 ** there was any kind of error.  If an error occurred and pzErrMsg is not
00675 ** NULL, then an error message is written into memory obtained from malloc()
00676 ** and *pzErrMsg is made to point to that error message.  The calling routine
00677 ** should use sqlite_freemem() to delete this message when it has finished
00678 ** with it.
00679 **
00680 ** This routine can be called at any point during the execution of the
00681 ** virtual machine.  If the virtual machine has not completed execution
00682 ** when this routine is called, that is like encountering an error or
00683 ** an interrupt.  (See sqlite_interrupt().)  Incomplete updates may be
00684 ** rolled back and transactions cancelled,  depending on the circumstances,
00685 ** and the result code returned will be SQLITE_ABORT.
00686 */
00687 int sqlite_finalize(sqlite_vm*, char **pzErrMsg);
00688 
00689 /*
00690 ** This routine deletes the virtual machine, writes any error message to
00691 ** *pzErrMsg and returns an SQLite return code in the same way as the
00692 ** sqlite_finalize() function.
00693 **
00694 ** Additionally, if ppVm is not NULL, *ppVm is left pointing to a new virtual
00695 ** machine loaded with the compiled version of the original query ready for
00696 ** execution.
00697 **
00698 ** If sqlite_reset() returns SQLITE_SCHEMA, then *ppVm is set to NULL.
00699 **
00700 ******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
00701 */
00702 int sqlite_reset(sqlite_vm*, char **pzErrMsg);
00703 
00704 /*
00705 ** If the SQL that was handed to sqlite_compile contains variables that
00706 ** are represeted in the SQL text by a question mark ('?').  This routine
00707 ** is used to assign values to those variables.
00708 **
00709 ** The first parameter is a virtual machine obtained from sqlite_compile().
00710 ** The 2nd "idx" parameter determines which variable in the SQL statement
00711 ** to bind the value to.  The left most '?' is 1.  The 3rd parameter is
00712 ** the value to assign to that variable.  The 4th parameter is the number
00713 ** of bytes in the value, including the terminating \000 for strings.
00714 ** Finally, the 5th "copy" parameter is TRUE if SQLite should make its
00715 ** own private copy of this value, or false if the space that the 3rd
00716 ** parameter points to will be unchanging and can be used directly by
00717 ** SQLite.
00718 **
00719 ** Unbound variables are treated as having a value of NULL.  To explicitly
00720 ** set a variable to NULL, call this routine with the 3rd parameter as a
00721 ** NULL pointer.
00722 **
00723 ** If the 4th "len" parameter is -1, then strlen() is used to find the
00724 ** length.
00725 **
00726 ** This routine can only be called immediately after sqlite_compile()
00727 ** or sqlite_reset() and before any calls to sqlite_step().
00728 **
00729 ******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
00730 */
00731 int sqlite_bind(sqlite_vm*, int idx, const char *value, int len, int copy);
00732 
00733 /*
00734 ** This routine configures a callback function - the progress callback - that
00735 ** is invoked periodically during long running calls to sqlite_exec(),
00736 ** sqlite_step() and sqlite_get_table(). An example use for this API is to keep
00737 ** a GUI updated during a large query.
00738 **
00739 ** The progress callback is invoked once for every N virtual machine opcodes,
00740 ** where N is the second argument to this function. The progress callback
00741 ** itself is identified by the third argument to this function. The fourth
00742 ** argument to this function is a void pointer passed to the progress callback
00743 ** function each time it is invoked.
00744 **
00745 ** If a call to sqlite_exec(), sqlite_step() or sqlite_get_table() results 
00746 ** in less than N opcodes being executed, then the progress callback is not
00747 ** invoked.
00748 ** 
00749 ** Calling this routine overwrites any previously installed progress callback.
00750 ** To remove the progress callback altogether, pass NULL as the third
00751 ** argument to this function.
00752 **
00753 ** If the progress callback returns a result other than 0, then the current 
00754 ** query is immediately terminated and any database changes rolled back. If the
00755 ** query was part of a larger transaction, then the transaction is not rolled
00756 ** back and remains active. The sqlite_exec() call returns SQLITE_ABORT. 
00757 */
00758 void sqlite_progress_handler(sqlite*, int, int(*)(void*), void*);
00759 
00760 #ifdef __cplusplus
00761 }  /* End of the 'extern "C"' block */
00762 #endif
00763 
00764 #endif /* _SQLITE_H_ */