The Non-Callback API

The Extended API

The extended API provides a range of non- core functions to assist with development of software that uses an embedded SQLite database.

Finding Information About the SQLite Library

const char sqlite_version[];

Contains the current library version number.

const char sqlite_encoding[];

Contains the current library encoding version.

Finding Information About Changes to the Database

Several functions can return information about changes that have been made to the database.

int sqlite_last_insert_rowid(sqlite *db);

Returns the most recently assigned autoincrementing value of an INTEGER PRIMARY KEY field.

int sqlite_changes(sqlite *db);

Returns the number of rows affected by an UPDATE or DELETE statement.

Checking SQL Statements

int sqlite_complete(const char *sql);

Returns trUE if a complete SQL statement is provided, that is, the statement ends with a semicolon. Returns FALSE if more characters are required.

Interrupting an SQL Statement

void sqlite_interrupt(sqlite *db);

Causes the current database operation to exist at the first opportunity, returning SQLITE_INTERRUPT to the calling function.

Convenience Functions

The following function fetches the entire result of a database query with a single function call:

int sqlite_get_table(
  sqlite *db,
  char *sql,
  char ***result,
  int *nrow,
  int *ncolumn,
  char **errmsg
);

The result will be an array of string pointers containing one element for each column of each row in the result. The first ncolumn elements contain the column names returned. Use nrow and ncolumn to determine which elements of the array correspond to which values.

The return code from sqlite_get_table() is the same as if sqlite_exec() had executed the query.

void sqlite_free_table(char **azResult);

Frees memory allocated by sqlite_get_table() when it is no longer required.

The _printf() Wrapper Functions

char *sqlite_mprintf(const char *zFormat, ...);

Works like sprintf() but also allows the format strings %q and %Q to manipulate strings for database storage. %q escapes any single quotes by doubling the quote character; %Q additionally encloses the result string within single quotes.

int sqlite_exec_printf(
  sqlite *db,
  char *sqlFormat,
  int (*)(void *, int, char **, char **),
  void *pArg,
  char **errmsg,
  ...
);

Combines sqlite_exec() with sqlite_mprintf() . The format string references items from the sixth argument onwards.

int sqlite_get_table_printf(
  sqlite *db,
  char *sql,
  char ***result,
  int *nrow,
  int *ncolumn,
  char **errmsg,
  ...
);

Combines sqlite_get_table() with sqlite_mprintf() . The format string references items from the seventh argument onwards.

Memory Management

void sqlite_freemem(void *p);

Where the library allocates memory using malloc() and returns a pointer to that data, such as errmsg or the result of sqlite_mprintf() , it is the responsibility of the calling program to free that memory.

Dealing with Locked Database Files

void sqlite_busy_timeout(
  sqlite *db,
  int ms
);

Specifies an amount of time in milliseconds for which SQLite will wait for a file lock to clear before returning SQLITE_BUSY .

void sqlite_busy_handler(
  sqlite *db,
  int (*xBusy)(void *, const char *, int),
  void *pArg
);

Specifies an alternative busy handler function xBusy . A non-zero response from the handler will cause SQLite to retry ; a zero response causes SQLITE_BUSY to be returned.

Performing Background Jobs During Large Queries

void sqlite_progress_handler(
  sqlite *db,
  int nOps,
  int (*xProgress)(void *),
  void *pArg
);

Registers a callback routine xProgress to be invoked every nOps virtual machine operations during long-running query execution.