the string. For example, so some string variable contains text as follows: <blockquote><pre>  char *zText = "It's a happy day!"; </pre></blockquote> One can use this text in an SQL statement as follows: <blockquote><pre>  sqlite3_exec_printf(db, "INSERT INTO table VALUES('%q')",       callback1, 0, 0, zText);  </pre></blockquote> Because the %q format string is used, the '\\'' character in zText is escaped and the SQL generated is as follows: <blockquote><pre>  INSERT INTO table1 VALUES('It''s a happy day!') </pre></blockquote> This is correct.  Had we used %s instead of %q, the generated SQL would have looked like this:  <blockquote><pre>  INSERT INTO table1 VALUES('It's a happy day!');  </pre></blockquote> This second example is an SQL syntax error.  As a general rule you should always use %q instead of %s when inserting text into a string  literal.} {}api {} {int sqlite3_open(  const char *filename,   /* Database filename (UTF-8) */  sqlite3 **ppDb          /* OUT: SQLite db handle */);int sqlite3_open16(  const void *filename,   /* Database filename (UTF-16) */  sqlite3 **ppDb          /* OUT: SQLite db handle */);} { Open the sqlite database file "filename".  The "filename" is UTF-8 encoded for sqlite3_open() and UTF-16 encoded in the native byte order for sqlite3_open16().  An sqlite3* handle is returned in *ppDb, even if an error occurs. If the database is opened (or created) successfully, then SQLITE_OK is returned. Otherwise an error code is returned. The sqlite3_errmsg() or sqlite3_errmsg16()  routines can be used to obtain an English language description of the error. If the database file does not exist, then a new database will be created as needed. The encoding for the database will be UTF-8 if sqlite3_open() is called and UTF-16 if sqlite3_open16 is used. Whether or not an error occurs when it is opened, resources associated with the sqlite3* handle should be released by passing it to sqlite3_close() when it is no longer required. The returned sqlite3* can only be used in the same thread in which it was created.  It is an error to call sqlite3_open() in one thread then pass the resulting database handle off to another thread to use.  This restriction is due to goofy design decisions (bugs?) in the way some threading implementations interact with file locks. Note to windows users:  The encoding used for the filename argument of sqlite3_open() must be UTF-8, not whatever codepage is currently defined.  Filenames containing international characters must be converted to UTF-8 prior to passing them into sqlite3_open().}api {} {int sqlite3_prepare(  sqlite3 *db,            /* Database handle */  const char *zSql,       /* SQL statement, UTF-8 encoded */  int nBytes,             /* Length of zSql in bytes. */  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */  const char **pzTail     /* OUT: Pointer to unused portion of zSql */);int sqlite3_prepare16(  sqlite3 *db,            /* Database handle */  const void *zSql,       /* SQL statement, UTF-16 encoded */  int nBytes,             /* Length of zSql in bytes. */  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */  const void **pzTail     /* OUT: Pointer to unused portion of zSql */);} { To execute an SQL query, it must first be compiled into a byte-code program using one of the following routines. The only difference between them is that the second argument, specifying the SQL statement to compile, is assumed to be encoded in UTF-8 for the sqlite3_prepare() function and UTF-16 for sqlite3_prepare16(). The first argument "db" is an SQLite database handle. The second argument "zSql" is the statement to be compiled, encoded as either UTF-8 or UTF-16 (see above). If the next argument, "nBytes", is less than zero, then zSql is read up to the first nul terminator.  If "nBytes" is not less than zero, then it is the length of the string zSql in bytes (not characters). *pzTail is made to point to the first byte past the end of the first SQL statement in zSql.  This routine only compiles the first statement in zSql, so *pzTail is left pointing to what remains uncompiled. *ppStmt is left pointing to a compiled SQL statement that can be executed using sqlite3_step().  Or if there is an error, *ppStmt may be set to NULL.  If the input text contained no SQL (if the input is and empty string or a comment) then *ppStmt is set to NULL.  The calling procedure is responsible for deleting this compiled SQL statement using sqlite3_finalize() after it has finished with it. On success, SQLITE_OK is returned.  Otherwise an error code is returned.}api {} {void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);} { <i>Experimental</i> This routine configures a callback function - the progress callback - that is invoked periodically during long running calls to sqlite3_exec(), sqlite3_step() and sqlite3_get_table(). An example use for this API is to keep a GUI updated during a large query. The progress callback is invoked once for every N virtual machine opcodes, where N is the second argument to this function. The progress callback itself is identified by the third argument to this function. The fourth argument to this function is a void pointer passed to the progress callback function each time it is invoked. If a call to sqlite3_exec(), sqlite3_step() or sqlite3_get_table() results  in less than N opcodes being executed, then the progress callback is not invoked.  To remove the progress callback altogether, pass NULL as the third argument to this function. If the progress callback returns a result other than 0, then the current  query is immediately terminated and any database changes rolled back. If the query was part of a larger transaction, then the transaction is not rolled back and remains active. The sqlite3_exec() call returns SQLITE_ABORT. }api {} {int sqlite3_reset(sqlite3_stmt *pStmt);} { The sqlite3_reset() function is called to reset a prepared SQL statement obtained by a previous call to sqlite3_prepare() or sqlite3_prepare16() back to it's initial state, ready to be re-executed. Any SQL statement variables that had values bound to them using the sqlite3_bind_*() API retain their values.}api {} {void sqlite3_result_blob(sqlite3_context*, const void*, int n, void(*)(void*));void sqlite3_result_double(sqlite3_context*, double);void sqlite3_result_error(sqlite3_context*, const char*, int);void sqlite3_result_error16(sqlite3_context*, const void*, int);void sqlite3_result_int(sqlite3_context*, int);void sqlite3_result_int64(sqlite3_context*, long long int);void sqlite3_result_null(sqlite3_context*);void sqlite3_result_text(sqlite3_context*, const char*, int n, void(*)(void*));void sqlite3_result_text16(sqlite3_context*, const void*, int n, void(*)(void*));void sqlite3_result_text16be(sqlite3_context*, const void*, int n, void(*)(void*));void sqlite3_result_text16le(sqlite3_context*, const void*, int n, void(*)(void*));void sqlite3_result_value(sqlite3_context*, sqlite3_value*);} { User-defined functions invoke these routines in order to set their return value.  The sqlite3_result_value() routine is used to return an exact copy of one of the arguments to the function. The operation of these routines is very similar to the operation of sqlite3_bind_blob() and its cousins.  Refer to the documentation there for additional information.}api {} {int sqlite3_set_authorizer(  sqlite3*,  int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),  void *pUserData);#define SQLITE_CREATE_INDEX          1   /* Index Name      Table Name      */#define SQLITE_CREATE_TABLE          2   /* Table Name      NULL            */#define SQLITE_CREATE_TEMP_INDEX     3   /* Index Name      Table Name      */#define SQLITE_CREATE_TEMP_TABLE     4   /* Table Name      NULL            */#define SQLITE_CREATE_TEMP_TRIGGER   5   /* Trigger Name    Table Name      */#define SQLITE_CREATE_TEMP_VIEW      6   /* View Name       NULL            */#define SQLITE_CREATE_TRIGGER        7   /* Trigger Name    Table Name      */#define SQLITE_CREATE_VIEW           8   /* View Name       NULL            */#define SQLITE_DELETE                9   /* Table Name      NULL            */#define SQLITE_DROP_INDEX           10   /* Index Name      Table Name      */#define SQLITE_DROP_TABLE           11   /* Table Name      NULL            */#define SQLITE_DROP_TEMP_INDEX      12   /* Index Name      Table Name      */#define SQLITE_DROP_TEMP_TABLE      13   /* Table Name      NULL            */#define SQLITE_DROP_TEMP_TRIGGER    14   /* Trigger Name    Table Name      */#define SQLITE_DROP_TEMP_VIEW       15   /* View Name       NULL            */#define SQLITE_DROP_TRIGGER         16   /* Trigger Name    Table Name      */#define SQLITE_DROP_VIEW            17   /* View Name       NULL            */#define SQLITE_INSERT               18   /* Table Name      NULL            */#define SQLITE_PRAGMA               19   /* Pragma Name     1st arg or NULL */#define SQLITE_READ                 20   /* Table Name      Column Name     */#define SQLITE_SELECT               21   /* NULL            NULL            */#define SQLITE_TRANSACTION          22   /* NULL            NULL            */#define SQLITE_UPDATE               23   /* Table Name      Column Name     */#define SQLITE_ATTACH               24   /* Filename        NULL            */#define SQLITE_DETACH               25   /* Database Name   NULL            */#define SQLITE_ALTER_TABLE          26   /* Database Name   Table Name      */#define SQLITE_REINDEX              27   /* Index Name      NULL            */#define SQLITE_ANALYZE              28   /* Table Name      NULL            */#define SQLITE_DENY   1   /* Abort the SQL statement with an error */#define SQLITE_IGNORE 2   /* Don't allow access, but don't generate an error */} { This routine registers a callback with the SQLite library.  The callback is invoked (at compile-time, not at run-time) for each attempt to access a column of a table in the database.  The callback should return SQLITE_OK if access is allowed, SQLITE_DENY if the entire SQL statement should be aborted with an error and SQLITE_IGNORE if the column should be treated as a NULL value. The second argument to the access authorization function will be one of the defined constants shown.  These values signify what kind of operation is to be authorized.  The 3rd and 4th arguments to the authorization function will be arguments or NULL depending on which of the following codes is used as the second argument.  The 5th argument is the name of the database ("main", "temp", etc.) if applicable.  The 6th argument is the name of the inner-most trigger or view that is responsible for the access attempt or NULL if this access attempt is directly from  input SQL code. The return value of the authorization function should be one of the constants SQLITE_OK, SQLITE_DENY, or SQLITE_IGNORE. The intent of this routine is to allow applications to safely execute user-entered SQL.  An appropriate callback can deny the user-entered SQL access certain operations (ex: anything that changes the database) or to deny access to certain tables or columns within the database.}api {} {int sqlite3_step(sqlite3_stmt*);} { After an SQL query has been prepared with a call to either sqlite3_prepare() or sqlite3_prepare16(), then this function must be called one or more times to execute the statement. The return value will be either SQLITE_BUSY, SQLITE_DONE,  SQLITE_ROW, SQLITE_ERROR, or SQLITE_MISUSE. SQLITE_BUSY means that the database engine attempted to open a locked database and there is no busy callback registered. Call sqlite3_step() again to retry the open. SQLITE_DONE means that the statement has finished executing successfully.  sqlite3_step() should not be called again on this virtual machine without first calling sqlite3_reset() to reset the virtual machine back to its initial state. If the SQL statement being executed returns any data, then  SQLITE_ROW is returned each time a new row of data is ready for processing by the caller. The values may be accessed using the sqlite3_column_*() functions. sqlite3_step() is called again to retrieve the next row of data.  SQLITE_ERROR means that a run-time error (such as a constraint violation) has occurred.  sqlite3_step() should not be called again on the VM. More information may be found by calling sqlite3_errmsg(). SQLITE_MISUSE means that the this routine was called inappropriately. Perhaps it was called on a virtual machine that had already been finalized or on one that had previously returned SQLITE_ERROR or SQLITE_DONE.  Or it could be the case that a database connection is being used by a different thread than the one it was created it.}api {} {void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);} { Register a function that is called each time an SQL statement is evaluated. The callback function is invoked on the first call to sqlite3_step() after calls to sqlite3_prepare() or sqlite3_reset(). This function can be used (for example) to generate a log file of all SQL executed against a database.  This can be useful when debugging an application that uses SQLite.}api {} {void *sqlite3_user_data(sqlite3_context*);} { The pUserData argument to the sqlite3_create_function() and sqlite3_create_function16() routines used to register user functions is available to the implementation of the function using this call.}api {} {const void *sqlite3_value_blob(sqlite3_value*);int sqlite3_value_bytes(sqlite3_value*);int sqlite3_value_bytes16(sqlite3_value*);double sqlite3_value_double(sqlite3_value*);int sqlite3_value_int(sqlite3_value*);long long int sqlite3_value_int64(sqlite3_value*);const unsigned char *sqlite3_value_text(sqlite3_value*);