Eneboo - Documentación para desarrolladores
src/sqlite/sqlite.h
Ir a la documentación de este archivo.
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 ** @(#)
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.13"
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_UTF8 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 /*
00208 ** This function returns the number of database rows that were changed
00209 ** by the last INSERT, UPDATE, or DELETE statment executed by sqlite_exec(),
00210 ** or by the last VM to run to completion. The change count is not updated
00211 ** by SQL statements other than INSERT, UPDATE or DELETE.
00212 **
00213 ** Changes are counted, even if they are later undone by a ROLLBACK or
00214 ** ABORT. Changes associated with trigger programs that execute as a
00215 ** result of the INSERT, UPDATE, or DELETE statement are not counted.
00216 **
00217 ** If a callback invokes sqlite_exec() recursively, then the changes
00218 ** in the inner, recursive call are counted together with the changes
00219 ** in the outer call.
00220 **
00221 ** SQLite implements the command "DELETE FROM table" without a WHERE clause
00222 ** by dropping and recreating the table.  (This is much faster than going
00223 ** through and deleting individual elements form the table.)  Because of
00224 ** this optimization, the change count for "DELETE FROM table" will be
00225 ** zero regardless of the number of elements that were originally in the
00226 ** table. To get an accurate count of the number of rows deleted, use
00227 ** "DELETE FROM table WHERE 1" instead.
00228 **
00229 ******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
00230 */
00231 int sqlite_last_statement_changes(sqlite*);
00232 
00233 /* If the parameter to this routine is one of the return value constants
00234 ** defined above, then this routine returns a constant text string which
00235 ** descripts (in English) the meaning of the return value.
00236 */
00237 const char *sqlite_error_string(int);
00238 #define sqliteErrStr sqlite_error_string  /* Legacy. Do not use in new code. */
00239 
00240 /* This function causes any pending database operation to abort and
00241 ** return at its earliest opportunity.  This routine is typically
00242 ** called in response to a user action such as pressing "Cancel"
00243 ** or Ctrl-C where the user wants a long query operation to halt
00244 ** immediately.
00245 */
00246 void sqlite_interrupt(sqlite*);
00247 
00248 
00249 /* This function returns true if the given input string comprises
00250 ** one or more complete SQL statements.
00251 **
00252 ** The algorithm is simple.  If the last token other than spaces
00253 ** and comments is a semicolon, then return true.  otherwise return
00254 ** false.
00255 */
00256 int sqlite_complete(const char *sql);
00257 
00258 /*
00259 ** This routine identifies a callback function that is invoked
00260 ** whenever an attempt is made to open a database table that is
00261 ** currently locked by another process or thread.  If the busy callback
00262 ** is NULL, then sqlite_exec() returns SQLITE_BUSY immediately if
00263 ** it finds a locked table.  If the busy callback is not NULL, then
00264 ** sqlite_exec() invokes the callback with three arguments.  The
00265 ** second argument is the name of the locked table and the third
00266 ** argument is the number of times the table has been busy.  If the
00267 ** busy callback returns 0, then sqlite_exec() immediately returns
00268 ** SQLITE_BUSY.  If the callback returns non-zero, then sqlite_exec()
00269 ** tries to open the table again and the cycle repeats.
00270 **
00271 ** The default busy callback is NULL.
00272 **
00273 ** Sqlite is re-entrant, so the busy handler may start a new query. 
00274 ** (It is not clear why anyone would every want to do this, but it
00275 ** is allowed, in theory.)  But the busy handler may not close the
00276 ** database.  Closing the database from a busy handler will delete 
00277 ** data structures out from under the executing query and will 
00278 ** probably result in a coredump.
00279 */
00280 void sqlite_busy_handler(sqlite*, int(*)(void*,const char*,int), void*);
00281 
00282 /*
00283 ** This routine sets a busy handler that sleeps for a while when a
00284 ** table is locked.  The handler will sleep multiple times until 
00285 ** at least "ms" milleseconds of sleeping have been done.  After
00286 ** "ms" milleseconds of sleeping, the handler returns 0 which
00287 ** causes sqlite_exec() to return SQLITE_BUSY.
00288 **
00289 ** Calling this routine with an argument less than or equal to zero
00290 ** turns off all busy handlers.
00291 */
00292 void sqlite_busy_timeout(sqlite*, int ms);
00293 
00294 /*
00295 ** This next routine is really just a wrapper around sqlite_exec().
00296 ** Instead of invoking a user-supplied callback for each row of the
00297 ** result, this routine remembers each row of the result in memory
00298 ** obtained from malloc(), then returns all of the result after the
00299 ** query has finished. 
00300 **
00301 ** As an example, suppose the query result where this table:
00302 **
00303 **        Name        | Age
00304 **        -----------------------
00305 **        Alice       | 43
00306 **        Bob         | 28
00307 **        Cindy       | 21
00308 **
00309 ** If the 3rd argument were &azResult then after the function returns
00310 ** azResult will contain the following data:
00311 **
00312 **        azResult[0] = "Name";
00313 **        azResult[1] = "Age";
00314 **        azResult[2] = "Alice";
00315 **        azResult[3] = "43";
00316 **        azResult[4] = "Bob";
00317 **        azResult[5] = "28";
00318 **        azResult[6] = "Cindy";
00319 **        azResult[7] = "21";
00320 **
00321 ** Notice that there is an extra row of data containing the column
00322 ** headers.  But the *nrow return value is still 3.  *ncolumn is
00323 ** set to 2.  In general, the number of values inserted into azResult
00324 ** will be ((*nrow) + 1)*(*ncolumn).
00325 **
00326 ** After the calling function has finished using the result, it should 
00327 ** pass the result data pointer to sqlite_free_table() in order to 
00328 ** release the memory that was malloc-ed.  Because of the way the 
00329 ** malloc() happens, the calling function must not try to call 
00330 ** malloc() directly.  Only sqlite_free_table() is able to release 
00331 ** the memory properly and safely.
00332 **
00333 ** The return value of this routine is the same as from sqlite_exec().
00334 */
00335 int sqlite_get_table(
00336   sqlite*,               /* An open database */
00337   const char *sql,       /* SQL to be executed */
00338   char ***resultp,       /* Result written to a char *[]  that this points to */
00339   int *nrow,             /* Number of result rows written here */
00340   int *ncolumn,          /* Number of result columns written here */
00341   char **errmsg          /* Error msg written here */
00342 );
00343 
00344 /*
00345 ** Call this routine to free the memory that sqlite_get_table() allocated.
00346 */
00347 void sqlite_free_table(char **result);
00348 
00349 /*
00350 ** The following routines are wrappers around sqlite_exec() and
00351 ** sqlite_get_table().  The only difference between the routines that
00352 ** follow and the originals is that the second argument to the 
00353 ** routines that follow is really a printf()-style format
00354 ** string describing the SQL to be executed.  Arguments to the format
00355 ** string appear at the end of the argument list.
00356 **
00357 ** All of the usual printf formatting options apply.  In addition, there
00358 ** is a "%q" option.  %q works like %s in that it substitutes a null-terminated
00359 ** string from the argument list.  But %q also doubles every '\'' character.
00360 ** %q is designed for use inside a string literal.  By doubling each '\''
00361 ** character it escapes that character and allows it to be inserted into
00362 ** the string.
00363 **
00364 ** For example, so some string variable contains text as follows:
00365 **
00366 **      char *zText = "It's a happy day!";
00367 **
00368 ** We can use this text in an SQL statement as follows:
00369 **
00370 **      sqlite_exec_printf(db, "INSERT INTO table VALUES('%q')",
00371 **          callback1, 0, 0, zText);
00372 **
00373 ** Because the %q format string is used, the '\'' character in zText
00374 ** is escaped and the SQL generated is as follows:
00375 **
00376 **      INSERT INTO table1 VALUES('It''s a happy day!')
00377 **
00378 ** This is correct.  Had we used %s instead of %q, the generated SQL
00379 ** would have looked like this:
00380 **
00381 **      INSERT INTO table1 VALUES('It's a happy day!');
00382 **
00383 ** This second example is an SQL syntax error.  As a general rule you
00384 ** should always use %q instead of %s when inserting text into a string 
00385 ** literal.
00386 */
00387 int sqlite_exec_printf(
00388   sqlite*,                      /* An open database */
00389   const char *sqlFormat,        /* printf-style format string for the SQL */
00390   sqlite_callback,              /* Callback function */
00391   void *,                       /* 1st argument to callback function */
00392   char **errmsg,                /* Error msg written here */
00393   ...                           /* Arguments to the format string. */
00394 );
00395 int sqlite_exec_vprintf(
00396   sqlite*,                      /* An open database */
00397   const char *sqlFormat,        /* printf-style format string for the SQL */
00398   sqlite_callback,              /* Callback function */
00399   void *,                       /* 1st argument to callback function */
00400   char **errmsg,                /* Error msg written here */
00401   va_list ap                    /* Arguments to the format string. */
00402 );
00403 int sqlite_get_table_printf(
00404   sqlite*,               /* An open database */
00405   const char *sqlFormat, /* printf-style format string for the SQL */
00406   char ***resultp,       /* Result written to a char *[]  that this points to */
00407   int *nrow,             /* Number of result rows written here */
00408   int *ncolumn,          /* Number of result columns written here */
00409   char **errmsg,         /* Error msg written here */
00410   ...                    /* Arguments to the format string */
00411 );
00412 int sqlite_get_table_vprintf(
00413   sqlite*,               /* An open database */
00414   const char *sqlFormat, /* printf-style format string for the SQL */
00415   char ***resultp,       /* Result written to a char *[]  that this points to */
00416   int *nrow,             /* Number of result rows written here */
00417   int *ncolumn,          /* Number of result columns written here */
00418   char **errmsg,         /* Error msg written here */
00419   va_list ap             /* Arguments to the format string */
00420 );
00421 char *sqlite_mprintf(const char*,...);
00422 char *sqlite_vmprintf(const char*, va_list);
00423 
00424 /*
00425 ** Windows systems should call this routine to free memory that
00426 ** is returned in the in the errmsg parameter of sqlite_open() when
00427 ** SQLite is a DLL.  For some reason, it does not work to call free()
00428 ** directly.
00429 */
00430 void sqlite_freemem(void *p);
00431 
00432 /*
00433 ** Windows systems need functions to call to return the sqlite_version
00434 ** and sqlite_encoding strings.
00435 */
00436 const char *sqlite_libversion(void);
00437 const char *sqlite_libencoding(void);
00438 
00439 /*
00440 ** A pointer to the following structure is used to communicate with
00441 ** the implementations of user-defined functions.
00442 */
00443 typedef struct sqlite_func sqlite_func;
00444 
00445 /*
00446 ** Use the following routines to create new user-defined functions.  See
00447 ** the documentation for details.
00448 */
00449 int sqlite_create_function(
00450   sqlite*,                  /* Database where the new function is registered */
00451   const char *zName,        /* Name of the new function */
00452   int nArg,                 /* Number of arguments.  -1 means any number */
00453   void (*xFunc)(sqlite_func*,int,const char**),  /* C code to implement */
00454   void *pUserData           /* Available via the sqlite_user_data() call */
00455 );
00456 int sqlite_create_aggregate(
00457   sqlite*,                  /* Database where the new function is registered */
00458   const char *zName,        /* Name of the function */
00459   int nArg,                 /* Number of arguments */
00460   void (*xStep)(sqlite_func*,int,const char**), /* Called for each row */
00461   void (*xFinalize)(sqlite_func*),       /* Called once to get final result */
00462   void *pUserData           /* Available via the sqlite_user_data() call */
00463 );
00464 
00465 /*
00466 ** Use the following routine to define the datatype returned by a
00467 ** user-defined function.  The second argument can be one of the
00468 ** constants SQLITE_NUMERIC, SQLITE_TEXT, or SQLITE_ARGS or it
00469 ** can be an integer greater than or equal to zero.  When the datatype
00470 ** parameter is non-negative, the type of the result will be the
00471 ** same as the datatype-th argument.  If datatype==SQLITE_NUMERIC
00472 ** then the result is always numeric.  If datatype==SQLITE_TEXT then
00473 ** the result is always text.  If datatype==SQLITE_ARGS then the result
00474 ** is numeric if any argument is numeric and is text otherwise.
00475 */
00476 int sqlite_function_type(
00477   sqlite *db,               /* The database there the function is registered */
00478   const char *zName,        /* Name of the function */
00479   int datatype              /* The datatype for this function */
00480 );
00481 #define SQLITE_NUMERIC     (-1)
00482 #define SQLITE_TEXT        (-2)
00483 #define SQLITE_ARGS        (-3)
00484 
00485 /*
00486 ** The user function implementations call one of the following four routines
00487 ** in order to return their results.  The first parameter to each of these
00488 ** routines is a copy of the first argument to xFunc() or xFinialize().
00489 ** The second parameter to these routines is the result to be returned.
00490 ** A NULL can be passed as the second parameter to sqlite_set_result_string()
00491 ** in order to return a NULL result.
00492 **
00493 ** The 3rd argument to _string and _error is the number of characters to
00494 ** take from the string.  If this argument is negative, then all characters
00495 ** up to and including the first '\000' are used.
00496 **
00497 ** The sqlite_set_result_string() function allocates a buffer to hold the
00498 ** result and returns a pointer to this buffer.  The calling routine
00499 ** (that is, the implmentation of a user function) can alter the content
00500 ** of this buffer if desired.
00501 */
00502 char *sqlite_set_result_string(sqlite_func*,const char*,int);
00503 void sqlite_set_result_int(sqlite_func*,int);
00504 void sqlite_set_result_double(sqlite_func*,double);
00505 void sqlite_set_result_error(sqlite_func*,const char*,int);
00506 
00507 /*
00508 ** The pUserData parameter to the sqlite_create_function() and
00509 ** sqlite_create_aggregate() routines used to register user functions
00510 ** is available to the implementation of the function using this
00511 ** call.
00512 */
00513 void *sqlite_user_data(sqlite_func*);
00514 
00515 /*
00516 ** Aggregate functions use the following routine to allocate
00517 ** a structure for storing their state.  The first time this routine
00518 ** is called for a particular aggregate, a new structure of size nBytes
00519 ** is allocated, zeroed, and returned.  On subsequent calls (for the
00520 ** same aggregate instance) the same buffer is returned.  The implementation
00521 ** of the aggregate can use the returned buffer to accumulate data.
00522 **
00523 ** The buffer allocated is freed automatically be SQLite.
00524 */
00525 void *sqlite_aggregate_context(sqlite_func*, int nBytes);
00526 
00527 /*
00528 ** The next routine returns the number of calls to xStep for a particular
00529 ** aggregate function instance.  The current call to xStep counts so this
00530 ** routine always returns at least 1.
00531 */
00532 int sqlite_aggregate_count(sqlite_func*);
00533 
00534 /*
00535 ** This routine registers a callback with the SQLite library.  The
00536 ** callback is invoked (at compile-time, not at run-time) for each
00537 ** attempt to access a column of a table in the database.  The callback
00538 ** returns SQLITE_OK if access is allowed, SQLITE_DENY if the entire
00539 ** SQL statement should be aborted with an error and SQLITE_IGNORE
00540 ** if the column should be treated as a NULL value.
00541 */
00542 int sqlite_set_authorizer(
00543   sqlite*,
00544   int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
00545   void *pUserData
00546 );
00547 
00548 /*
00549 ** The second parameter to the access authorization function above will
00550 ** be one of the values below.  These values signify what kind of operation
00551 ** is to be authorized.  The 3rd and 4th parameters to the authorization
00552 ** function will be parameters or NULL depending on which of the following
00553 ** codes is used as the second parameter.  The 5th parameter is the name
00554 ** of the database ("main", "temp", etc.) if applicable.  The 6th parameter
00555 ** is the name of the inner-most trigger or view that is responsible for
00556 ** the access attempt or NULL if this access attempt is directly from 
00557 ** input SQL code.
00558 **
00559 **                                          Arg-3           Arg-4
00560 */
00561 #define SQLITE_COPY                  0   /* Table Name      File Name       */
00562 #define SQLITE_CREATE_INDEX          1   /* Index Name      Table Name      */
00563 #define SQLITE_CREATE_TABLE          2   /* Table Name      NULL            */
00564 #define SQLITE_CREATE_TEMP_INDEX     3   /* Index Name      Table Name      */
00565 #define SQLITE_CREATE_TEMP_TABLE     4   /* Table Name      NULL            */
00566 #define SQLITE_CREATE_TEMP_TRIGGER   5   /* Trigger Name    Table Name      */
00567 #define SQLITE_CREATE_TEMP_VIEW      6   /* View Name       NULL            */
00568 #define SQLITE_CREATE_TRIGGER        7   /* Trigger Name    Table Name      */
00569 #define SQLITE_CREATE_VIEW           8   /* View Name       NULL            */
00570 #define SQLITE_DELETE                9   /* Table Name      NULL            */
00571 #define SQLITE_DROP_INDEX           10   /* Index Name      Table Name      */
00572 #define SQLITE_DROP_TABLE           11   /* Table Name      NULL            */
00573 #define SQLITE_DROP_TEMP_INDEX      12   /* Index Name      Table Name      */
00574 #define SQLITE_DROP_TEMP_TABLE      13   /* Table Name      NULL            */
00575 #define SQLITE_DROP_TEMP_TRIGGER    14   /* Trigger Name    Table Name      */
00576 #define SQLITE_DROP_TEMP_VIEW       15   /* View Name       NULL            */
00577 #define SQLITE_DROP_TRIGGER         16   /* Trigger Name    Table Name      */
00578 #define SQLITE_DROP_VIEW            17   /* View Name       NULL            */
00579 #define SQLITE_INSERT               18   /* Table Name      NULL            */
00580 #define SQLITE_PRAGMA               19   /* Pragma Name     1st arg or NULL */
00581 #define SQLITE_READ                 20   /* Table Name      Column Name     */
00582 #define SQLITE_SELECT               21   /* NULL            NULL            */
00583 #define SQLITE_TRANSACTION          22   /* NULL            NULL            */
00584 #define SQLITE_UPDATE               23   /* Table Name      Column Name     */
00585 #define SQLITE_ATTACH               24   /* Filename        NULL            */
00586 #define SQLITE_DETACH               25   /* Database Name   NULL            */
00587 
00588 
00589 /*
00590 ** The return value of the authorization function should be one of the
00591 ** following constants:
00592 */
00593 /* #define SQLITE_OK  0   // Allow access (This is actually defined above) */
00594 #define SQLITE_DENY   1   /* Abort the SQL statement with an error */
00595 #define SQLITE_IGNORE 2   /* Don't allow access, but don't generate an error */
00596 
00597 /*
00598 ** Register a function that is called at every invocation of sqlite_exec()
00599 ** or sqlite_compile().  This function can be used (for example) to generate
00600 ** a log file of all SQL executed against a database.
00601 */
00602 void *sqlite_trace(sqlite*, void(*xTrace)(void*,const char*), void*);
00603 
00604 /*** The Callback-Free API
00605 ** 
00606 ** The following routines implement a new way to access SQLite that does not
00607 ** involve the use of callbacks.
00608 **
00609 ** An sqlite_vm is an opaque object that represents a single SQL statement
00610 ** that is ready to be executed.
00611 */
00612 typedef struct sqlite_vm sqlite_vm;
00613 
00614 /*
00615 ** To execute an SQLite query without the use of callbacks, you first have
00616 ** to compile the SQL using this routine.  The 1st parameter "db" is a pointer
00617 ** to an sqlite object obtained from sqlite_open().  The 2nd parameter
00618 ** "zSql" is the text of the SQL to be compiled.   The remaining parameters
00619 ** are all outputs.
00620 **
00621 ** *pzTail is made to point to the first character past the end of the first
00622 ** SQL statement in zSql.  This routine only compiles the first statement
00623 ** in zSql, so *pzTail is left pointing to what remains uncompiled.
00624 **
00625 ** *ppVm is left pointing to a "virtual machine" that can be used to execute
00626 ** the compiled statement.  Or if there is an error, *ppVm may be set to NULL.
00627 ** If the input text contained no SQL (if the input is and empty string or
00628 ** a comment) then *ppVm is set to NULL.
00629 **
00630 ** If any errors are detected during compilation, an error message is written
00631 ** into space obtained from malloc() and *pzErrMsg is made to point to that
00632 ** error message.  The calling routine is responsible for freeing the text
00633 ** of this message when it has finished with it.  Use sqlite_freemem() to
00634 ** free the message.  pzErrMsg may be NULL in which case no error message
00635 ** will be generated.
00636 **
00637 ** On success, SQLITE_OK is returned.  Otherwise and error code is returned.
00638 */
00639 int sqlite_compile(
00640   sqlite *db,                   /* The open database */
00641   const char *zSql,             /* SQL statement to be compiled */
00642   const char **pzTail,          /* OUT: uncompiled tail of zSql */
00643   sqlite_vm **ppVm,             /* OUT: the virtual machine to execute zSql */
00644   char **pzErrmsg               /* OUT: Error message. */
00645 );
00646 
00647 /*
00648 ** After an SQL statement has been compiled, it is handed to this routine
00649 ** to be executed.  This routine executes the statement as far as it can
00650 ** go then returns.  The return value will be one of SQLITE_DONE,
00651 ** SQLITE_ERROR, SQLITE_BUSY, SQLITE_ROW, or SQLITE_MISUSE.
00652 **
00653 ** SQLITE_DONE means that the execute of the SQL statement is complete
00654 ** an no errors have occurred.  sqlite_step() should not be called again
00655 ** for the same virtual machine.  *pN is set to the number of columns in
00656 ** the result set and *pazColName is set to an array of strings that
00657 ** describe the column names and datatypes.  The name of the i-th column
00658 ** is (*pazColName)[i] and the datatype of the i-th column is
00659 ** (*pazColName)[i+*pN].  *pazValue is set to NULL.
00660 **
00661 ** SQLITE_ERROR means that the virtual machine encountered a run-time
00662 ** error.  sqlite_step() should not be called again for the same
00663 ** virtual machine.  *pN is set to 0 and *pazColName and *pazValue are set
00664 ** to NULL.  Use sqlite_finalize() to obtain the specific error code
00665 ** and the error message text for the error.
00666 **
00667 ** SQLITE_BUSY means that an attempt to open the database failed because
00668 ** another thread or process is holding a lock.  The calling routine
00669 ** can try again to open the database by calling sqlite_step() again.
00670 ** The return code will only be SQLITE_BUSY if no busy handler is registered
00671 ** using the sqlite_busy_handler() or sqlite_busy_timeout() routines.  If
00672 ** a busy handler callback has been registered but returns 0, then this
00673 ** routine will return SQLITE_ERROR and sqltie_finalize() will return
00674 ** SQLITE_BUSY when it is called.
00675 **
00676 ** SQLITE_ROW means that a single row of the result is now available.
00677 ** The data is contained in *pazValue.  The value of the i-th column is
00678 ** (*azValue)[i].  *pN and *pazColName are set as described in SQLITE_DONE.
00679 ** Invoke sqlite_step() again to advance to the next row.
00680 **
00681 ** SQLITE_MISUSE is returned if sqlite_step() is called incorrectly.
00682 ** For example, if you call sqlite_step() after the virtual machine
00683 ** has halted (after a prior call to sqlite_step() has returned SQLITE_DONE)
00684 ** or if you call sqlite_step() with an incorrectly initialized virtual
00685 ** machine or a virtual machine that has been deleted or that is associated
00686 ** with an sqlite structure that has been closed.
00687 */
00688 int sqlite_step(
00689   sqlite_vm *pVm,              /* The virtual machine to execute */
00690   int *pN,                     /* OUT: Number of columns in result */
00691   const char ***pazValue,      /* OUT: Column data */
00692   const char ***pazColName     /* OUT: Column names and datatypes */
00693 );
00694 
00695 /*
00696 ** This routine is called to delete a virtual machine after it has finished
00697 ** executing.  The return value is the result code.  SQLITE_OK is returned
00698 ** if the statement executed successfully and some other value is returned if
00699 ** there was any kind of error.  If an error occurred and pzErrMsg is not
00700 ** NULL, then an error message is written into memory obtained from malloc()
00701 ** and *pzErrMsg is made to point to that error message.  The calling routine
00702 ** should use sqlite_freemem() to delete this message when it has finished
00703 ** with it.
00704 **
00705 ** This routine can be called at any point during the execution of the
00706 ** virtual machine.  If the virtual machine has not completed execution
00707 ** when this routine is called, that is like encountering an error or
00708 ** an interrupt.  (See sqlite_interrupt().)  Incomplete updates may be
00709 ** rolled back and transactions cancelled,  depending on the circumstances,
00710 ** and the result code returned will be SQLITE_ABORT.
00711 */
00712 int sqlite_finalize(sqlite_vm*, char **pzErrMsg);
00713 
00714 /*
00715 ** This routine deletes the virtual machine, writes any error message to
00716 ** *pzErrMsg and returns an SQLite return code in the same way as the
00717 ** sqlite_finalize() function.
00718 **
00719 ** Additionally, if ppVm is not NULL, *ppVm is left pointing to a new virtual
00720 ** machine loaded with the compiled version of the original query ready for
00721 ** execution.
00722 **
00723 ** If sqlite_reset() returns SQLITE_SCHEMA, then *ppVm is set to NULL.
00724 **
00725 ******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
00726 */
00727 int sqlite_reset(sqlite_vm*, char **pzErrMsg);
00728 
00729 /*
00730 ** If the SQL that was handed to sqlite_compile contains variables that
00731 ** are represeted in the SQL text by a question mark ('?').  This routine
00732 ** is used to assign values to those variables.
00733 **
00734 ** The first parameter is a virtual machine obtained from sqlite_compile().
00735 ** The 2nd "idx" parameter determines which variable in the SQL statement
00736 ** to bind the value to.  The left most '?' is 1.  The 3rd parameter is
00737 ** the value to assign to that variable.  The 4th parameter is the number
00738 ** of bytes in the value, including the terminating \000 for strings.
00739 ** Finally, the 5th "copy" parameter is TRUE if SQLite should make its
00740 ** own private copy of this value, or false if the space that the 3rd
00741 ** parameter points to will be unchanging and can be used directly by
00742 ** SQLite.
00743 **
00744 ** Unbound variables are treated as having a value of NULL.  To explicitly
00745 ** set a variable to NULL, call this routine with the 3rd parameter as a
00746 ** NULL pointer.
00747 **
00748 ** If the 4th "len" parameter is -1, then strlen() is used to find the
00749 ** length.
00750 **
00751 ** This routine can only be called immediately after sqlite_compile()
00752 ** or sqlite_reset() and before any calls to sqlite_step().
00753 **
00754 ******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
00755 */
00756 int sqlite_bind(sqlite_vm*, int idx, const char *value, int len, int copy);
00757 
00758 /*
00759 ** This routine configures a callback function - the progress callback - that
00760 ** is invoked periodically during long running calls to sqlite_exec(),
00761 ** sqlite_step() and sqlite_get_table(). An example use for this API is to keep
00762 ** a GUI updated during a large query.
00763 **
00764 ** The progress callback is invoked once for every N virtual machine opcodes,
00765 ** where N is the second argument to this function. The progress callback
00766 ** itself is identified by the third argument to this function. The fourth
00767 ** argument to this function is a void pointer passed to the progress callback
00768 ** function each time it is invoked.
00769 **
00770 ** If a call to sqlite_exec(), sqlite_step() or sqlite_get_table() results 
00771 ** in less than N opcodes being executed, then the progress callback is not
00772 ** invoked.
00773 ** 
00774 ** Calling this routine overwrites any previously installed progress callback.
00775 ** To remove the progress callback altogether, pass NULL as the third
00776 ** argument to this function.
00777 **
00778 ** If the progress callback returns a result other than 0, then the current 
00779 ** query is immediately terminated and any database changes rolled back. If the
00780 ** query was part of a larger transaction, then the transaction is not rolled
00781 ** back and remains active. The sqlite_exec() call returns SQLITE_ABORT. 
00782 **
00783 ******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
00784 */
00785 void sqlite_progress_handler(sqlite*, int, int(*)(void*), void*);
00786 
00787 /*
00788 ** Register a callback function to be invoked whenever a new transaction
00789 ** is committed.  The pArg argument is passed through to the callback.
00790 ** callback.  If the callback function returns non-zero, then the commit
00791 ** is converted into a rollback.
00792 **
00793 ** If another function was previously registered, its pArg value is returned.
00794 ** Otherwise NULL is returned.
00795 **
00796 ** Registering a NULL function disables the callback.
00797 **
00798 ******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
00799 */
00800 void *sqlite_commit_hook(sqlite*, int(*)(void*), void*);
00801 
00802 /*
00803 ** Open an encrypted SQLite database.  If pKey==0 or nKey==0, this routine
00804 ** is the same as sqlite_open().
00805 **
00806 ** The code to implement this API is not available in the public release
00807 ** of SQLite.
00808 */
00809 sqlite *sqlite_open_encrypted(
00810   const char *zFilename,   /* Name of the encrypted database */
00811   const void *pKey,        /* Pointer to the key */
00812   int nKey,                /* Number of bytes in the key */
00813   int *pErrcode,           /* Write error code here */
00814   char **pzErrmsg          /* Write error message here */
00815 );
00816 
00817 /*
00818 ** Change the key on an open database.  If the current database is not
00819 ** encrypted, this routine will encrypt it.  If pNew==0 or nNew==0, the
00820 ** database is decrypted.
00821 **
00822 ** The code to implement this API is not available in the public release
00823 ** of SQLite.
00824 */
00825 int sqlite_rekey(
00826   sqlite *db,                    /* Database to be rekeyed */
00827   const void *pKey, int nKey     /* The new key */
00828 );
00829 
00830 #ifdef __cplusplus
00831 }  /* End of the 'extern "C"' block */
00832 #endif
00833 
00834 #endif /* _SQLITE_H_ */
 Todo Clases Namespaces Archivos Funciones Variables 'typedefs' Enumeraciones Valores de enumeraciones Propiedades Amigas 'defines'