Collaboration diagram for Database Routines:

Data Structures
struct	switch_coredb_handle

Macros
#define	SWITCH_CORE_DB_STATIC ((switch_core_db_destructor_type_t)0)

#define	SWITCH_CORE_DB_TRANSIENT ((switch_core_db_destructor_type_t)-1)

#define	SWITCH_CORE_DB_OK 0 /* Successful result */

#define	SWITCH_CORE_DB_ERROR 1 /* SQL error or missing database */

#define	SWITCH_CORE_DB_INTERNAL 2 /* NOT USED. Internal logic error in SQLite */

#define	SWITCH_CORE_DB_PERM 3 /* Access permission denied */

#define	SWITCH_CORE_DB_ABORT 4 /* Callback routine requested an abort */

#define	SWITCH_CORE_DB_BUSY 5 /* The database file is locked */

#define	SWITCH_CORE_DB_LOCKED 6 /* A table in the database is locked */

#define	SWITCH_CORE_DB_NOMEM 7 /* A malloc() failed */

#define	SWITCH_CORE_DB_READONLY 8 /* Attempt to write a readonly database */

#define	SWITCH_CORE_DB_INTERRUPT 9 /* Operation terminated by switch_core_db_interrupt() */

#define	SWITCH_CORE_DB_IOERR 10 /* Some kind of disk I/O error occurred */

#define	SWITCH_CORE_DB_CORRUPT 11 /* The database disk image is malformed */

#define	SWITCH_CORE_DB_NOTFOUND 12 /* NOT USED. Table or record not found */

#define	SWITCH_CORE_DB_FULL 13 /* Insertion failed because database is full */

#define	SWITCH_CORE_DB_CANTOPEN 14 /* Unable to open the database file */

#define	SWITCH_CORE_DB_PROTOCOL 15 /* Database lock protocol error */

#define	SWITCH_CORE_DB_EMPTY 16 /* Database is empty */

#define	SWITCH_CORE_DB_SCHEMA 17 /* The database schema changed */

#define	SWITCH_CORE_DB_TOOBIG 18 /* NOT USED. Too much data for one row */

#define	SWITCH_CORE_DB_CONSTRAINT 19 /* Abort due to contraint violation */

#define	SWITCH_CORE_DB_MISMATCH 20 /* Data type mismatch */

#define	SWITCH_CORE_DB_MISUSE 21 /* Library used incorrectly */

#define	SWITCH_CORE_DB_NOLFS 22 /* Uses OS features not supported on host */

#define	SWITCH_CORE_DB_AUTH 23 /* Authorization denied */

#define	SWITCH_CORE_DB_FORMAT 24 /* Auxiliary database format error */

#define	SWITCH_CORE_DB_RANGE 25 /* 2nd parameter to switch_core_db_bind out of range */

#define	SWITCH_CORE_DB_NOTADB 26 /* File opened that is not a database file */

#define	SWITCH_CORE_DB_ROW 100 /* switch_core_db_step() has another row ready */

#define	SWITCH_CORE_DB_DONE 101 /* switch_core_db_step() has finished executing */

Typedefs
typedef struct sqlite3	switch_core_db_t

typedef struct sqlite3_stmt	switch_core_db_stmt_t

typedef int(*	switch_core_db_callback_func_t) (void pArg, int argc, char argv, char *columnNames)

typedef int(*	switch_core_db_err_callback_func_t) (void pArg, const char errmsg)

typedef void(*	switch_core_db_destructor_type_t) (void *)

Functions
int	switch_core_db_close (switch_core_db_t *db)

int	switch_core_db_open (const char filename, switch_core_db_t *ppDb)

int	switch_core_db_open_v2 (const char filename, switch_core_db_t *ppDb)

const unsigned char *	switch_core_db_column_text (switch_core_db_stmt_t *stmt, int iCol)

const char *	switch_core_db_column_name (switch_core_db_stmt_t *stmt, int N)

int	switch_core_db_column_count (switch_core_db_stmt_t *pStmt)

const char *	switch_core_db_errmsg (switch_core_db_t *db)

int	switch_core_db_exec (switch_core_db_t db, const char sql, switch_core_db_callback_func_t callback, void data, char *errmsg)

int	switch_core_db_finalize (switch_core_db_stmt_t *pStmt)

int	switch_core_db_prepare (switch_core_db_t db, const char zSql, int nBytes, switch_core_db_stmt_t ppStmt, const char pzTail)

int	switch_core_db_step (switch_core_db_stmt_t *stmt)

int	switch_core_db_reset (switch_core_db_stmt_t *pStmt)

int	switch_core_db_bind_int (switch_core_db_stmt_t *pStmt, int i, int iValue)

int	switch_core_db_bind_int64 (switch_core_db_stmt_t *pStmt, int i, int64_t iValue)

int	switch_core_db_bind_text (switch_core_db_stmt_t pStmt, int i, const char zData, int nData, switch_core_db_destructor_type_t xDel)

int	switch_core_db_bind_double (switch_core_db_stmt_t *pStmt, int i, double dValue)

int64_t	switch_core_db_last_insert_rowid (switch_core_db_t *db)

int	switch_core_db_get_table (switch_core_db_t db, const char sql, char **resultp, int nrow, int ncolumn, char *errmsg)

void	switch_core_db_free_table (char **result)

void	switch_core_db_free (char *z)

int	switch_core_db_changes (switch_core_db_t *db)

int	switch_core_db_load_extension (switch_core_db_t db, const char extension)

Detailed Description

Macro Definition Documentation

◆ SWITCH_CORE_DB_ABORT

#define SWITCH_CORE_DB_ABORT 4 /* Callback routine requested an abort */

Definition at line 489 of file switch_core_db.h.

Referenced by switch_cache_db_execute_sql_callback(), switch_cache_db_execute_sql_callback_err(), switch_cache_db_execute_sql_event_callback(), and switch_cache_db_execute_sql_event_callback_err().

◆ SWITCH_CORE_DB_AUTH

#define SWITCH_CORE_DB_AUTH 23 /* Authorization denied */

Definition at line 508 of file switch_core_db.h.

◆ SWITCH_CORE_DB_BUSY

#define SWITCH_CORE_DB_BUSY 5 /* The database file is locked */

Definition at line 490 of file switch_core_db.h.

Referenced by switch_cache_db_execute_sql2str().

◆ SWITCH_CORE_DB_CANTOPEN

#define SWITCH_CORE_DB_CANTOPEN 14 /* Unable to open the database file */

Definition at line 499 of file switch_core_db.h.

◆ SWITCH_CORE_DB_CONSTRAINT

#define SWITCH_CORE_DB_CONSTRAINT 19 /* Abort due to contraint violation */

Definition at line 504 of file switch_core_db.h.

◆ SWITCH_CORE_DB_CORRUPT

#define SWITCH_CORE_DB_CORRUPT 11 /* The database disk image is malformed */

Definition at line 496 of file switch_core_db.h.

◆ SWITCH_CORE_DB_DONE

#define SWITCH_CORE_DB_DONE 101 /* switch_core_db_step() has finished executing */

Definition at line 513 of file switch_core_db.h.

◆ SWITCH_CORE_DB_EMPTY

#define SWITCH_CORE_DB_EMPTY 16 /* Database is empty */

Definition at line 501 of file switch_core_db.h.

◆ SWITCH_CORE_DB_ERROR

#define SWITCH_CORE_DB_ERROR 1 /* SQL error or missing database */

Definition at line 486 of file switch_core_db.h.

◆ SWITCH_CORE_DB_FORMAT

#define SWITCH_CORE_DB_FORMAT 24 /* Auxiliary database format error */

Definition at line 509 of file switch_core_db.h.

◆ SWITCH_CORE_DB_FULL

#define SWITCH_CORE_DB_FULL 13 /* Insertion failed because database is full */

Definition at line 498 of file switch_core_db.h.

◆ SWITCH_CORE_DB_INTERNAL

#define SWITCH_CORE_DB_INTERNAL 2 /* NOT USED. Internal logic error in SQLite */

Definition at line 487 of file switch_core_db.h.

◆ SWITCH_CORE_DB_INTERRUPT

#define SWITCH_CORE_DB_INTERRUPT 9 /* Operation terminated by switch_core_db_interrupt() */

Definition at line 494 of file switch_core_db.h.

◆ SWITCH_CORE_DB_IOERR

#define SWITCH_CORE_DB_IOERR 10 /* Some kind of disk I/O error occurred */

Definition at line 495 of file switch_core_db.h.

◆ SWITCH_CORE_DB_LOCKED

#define SWITCH_CORE_DB_LOCKED 6 /* A table in the database is locked */

Definition at line 491 of file switch_core_db.h.

◆ SWITCH_CORE_DB_MISMATCH

#define SWITCH_CORE_DB_MISMATCH 20 /* Data type mismatch */

Definition at line 505 of file switch_core_db.h.

◆ SWITCH_CORE_DB_MISUSE

#define SWITCH_CORE_DB_MISUSE 21 /* Library used incorrectly */

Definition at line 506 of file switch_core_db.h.

◆ SWITCH_CORE_DB_NOLFS

#define SWITCH_CORE_DB_NOLFS 22 /* Uses OS features not supported on host */

Definition at line 507 of file switch_core_db.h.

◆ SWITCH_CORE_DB_NOMEM

#define SWITCH_CORE_DB_NOMEM 7 /* A malloc() failed */

Definition at line 492 of file switch_core_db.h.

◆ SWITCH_CORE_DB_NOTADB

#define SWITCH_CORE_DB_NOTADB 26 /* File opened that is not a database file */

Definition at line 511 of file switch_core_db.h.

◆ SWITCH_CORE_DB_NOTFOUND

#define SWITCH_CORE_DB_NOTFOUND 12 /* NOT USED. Table or record not found */

Definition at line 497 of file switch_core_db.h.

◆ SWITCH_CORE_DB_OK

#define SWITCH_CORE_DB_OK 0 /* Successful result */

Return values for switch_core_db_exec() and switch_core_db_step()

Definition at line 484 of file switch_core_db.h.

Referenced by switch_cache_db_execute_sql_callback(), switch_cache_db_execute_sql_callback_err(), switch_cache_db_execute_sql_event_callback(), switch_cache_db_execute_sql_event_callback_err(), and switch_cache_db_execute_sql_real().

◆ SWITCH_CORE_DB_PERM

#define SWITCH_CORE_DB_PERM 3 /* Access permission denied */

Definition at line 488 of file switch_core_db.h.

◆ SWITCH_CORE_DB_PROTOCOL

#define SWITCH_CORE_DB_PROTOCOL 15 /* Database lock protocol error */

Definition at line 500 of file switch_core_db.h.

◆ SWITCH_CORE_DB_RANGE

#define SWITCH_CORE_DB_RANGE 25 /* 2nd parameter to switch_core_db_bind out of range */

Definition at line 510 of file switch_core_db.h.

◆ SWITCH_CORE_DB_READONLY

#define SWITCH_CORE_DB_READONLY 8 /* Attempt to write a readonly database */

Definition at line 493 of file switch_core_db.h.

◆ SWITCH_CORE_DB_ROW

#define SWITCH_CORE_DB_ROW 100 /* switch_core_db_step() has another row ready */

Definition at line 512 of file switch_core_db.h.

Referenced by switch_cache_db_execute_sql2str().

◆ SWITCH_CORE_DB_SCHEMA

#define SWITCH_CORE_DB_SCHEMA 17 /* The database schema changed */

Definition at line 502 of file switch_core_db.h.

◆ SWITCH_CORE_DB_STATIC

#define SWITCH_CORE_DB_STATIC ((switch_core_db_destructor_type_t)0)

Definition at line 78 of file switch_core_db.h.

◆ SWITCH_CORE_DB_TOOBIG

#define SWITCH_CORE_DB_TOOBIG 18 /* NOT USED. Too much data for one row */

Definition at line 503 of file switch_core_db.h.

◆ SWITCH_CORE_DB_TRANSIENT

#define SWITCH_CORE_DB_TRANSIENT ((switch_core_db_destructor_type_t)-1)

Definition at line 79 of file switch_core_db.h.

Typedef Documentation

◆ switch_core_db_callback_func_t

typedef int(* switch_core_db_callback_func_t) (void *pArg, int argc, char **argv, char **columnNames)

Definition at line 62 of file switch_core_db.h.

◆ switch_core_db_destructor_type_t

typedef void(* switch_core_db_destructor_type_t) (void *)

Definition at line 77 of file switch_core_db.h.

◆ switch_core_db_err_callback_func_t

typedef int(* switch_core_db_err_callback_func_t) (void *pArg, const char *errmsg)

Definition at line 63 of file switch_core_db.h.

◆ switch_core_db_stmt_t

typedef struct sqlite3_stmt switch_core_db_stmt_t

Definition at line 60 of file switch_core_db.h.

◆ switch_core_db_t

typedef struct sqlite3 switch_core_db_t

Each open database is represented by an instance of the following opaque structure.

Definition at line 53 of file switch_core_db.h.

Function Documentation

◆ switch_core_db_bind_double()

int switch_core_db_bind_double	(	switch_core_db_stmt_t *	pStmt,
		int	i,
		double	dValue
	)

In the SQL strings input to switch_core_db_prepare(), one or more literals can be replace by parameters "?" or ":AAA" or "$VVV" where AAA is an identifer and VVV is a variable name according to the syntax rules of the TCL programming language. The value of these parameters (also called "host parameter names") can be set using the routines listed below.

In every case, the first parameter is a pointer to the sqlite3_stmt structure returned from switch_core_db_prepare(). The second parameter is the index of the parameter. The first parameter as an index of 1. For named parameters (":AAA" or "$VVV") you can use sqlite3_bind_parameter_index() to get the correct index value given the parameters name. If the same named parameter occurs more than once, it is assigned the same index each time.

The sqlite3_bind_* routine must be called before switch_core_db_step() after an switch_core_db_prepare() or switch_core_db_reset(). Unbound parameterss are interpreted as NULL.

Definition at line 149 of file switch_core_db.c.

 {
         return sqlite3_bind_double(pStmt, i, dValue);
 }

◆ switch_core_db_bind_int()

int switch_core_db_bind_int	(	switch_core_db_stmt_t *	pStmt,
		int	i,
		int	iValue
	)

In the SQL strings input to switch_core_db_prepare(), one or more literals can be replace by parameters "?" or ":AAA" or "$VVV" where AAA is an identifer and VVV is a variable name according to the syntax rules of the TCL programming language. The value of these parameters (also called "host parameter names") can be set using the routines listed below.

In every case, the first parameter is a pointer to the sqlite3_stmt structure returned from switch_core_db_prepare(). The second parameter is the index of the parameter. The first parameter as an index of 1. For named parameters (":AAA" or "$VVV") you can use switch_core_db_bind_parameter_index() to get the correct index value given the parameters name. If the same named parameter occurs more than once, it is assigned the same index each time.

The switch_core_db_bind_* routine must be called before switch_core_db_step() after an switch_core_db_prepare() or sqlite3_reset(). Unbound parameterss are interpreted as NULL.

Definition at line 134 of file switch_core_db.c.

 {
         return sqlite3_bind_int(pStmt, i, iValue);
 }

◆ switch_core_db_bind_int64()

int switch_core_db_bind_int64	(	switch_core_db_stmt_t *	pStmt,
		int	i,
		int64_t	iValue
	)

In the SQL strings input to switch_core_db_prepare(), one or more literals can be replace by parameters "?" or ":AAA" or "$VVV" where AAA is an identifer and VVV is a variable name according to the syntax rules of the TCL programming language. The value of these parameters (also called "host parameter names") can be set using the routines listed below.

In every case, the first parameter is a pointer to the sqlite3_stmt structure returned from switch_core_db_prepare(). The second parameter is the index of the parameter. The first parameter as an index of 1. For named parameters (":AAA" or "$VVV") you can use switch_core_db_bind_parameter_index() to get the correct index value given the parameters name. If the same named parameter occurs more than once, it is assigned the same index each time.

The switch_core_db_bind_* routine must be called before switch_core_db_step() after an switch_core_db_prepare() or sqlite3_reset(). Unbound parameterss are interpreted as NULL.

Definition at line 139 of file switch_core_db.c.

 {
         return sqlite3_bind_int64(pStmt, i, iValue);
 }

◆ switch_core_db_bind_text()

int switch_core_db_bind_text	(	switch_core_db_stmt_t *	pStmt,
		int	i,
		const char *	zData,
		int	nData,
		switch_core_db_destructor_type_t	xDel
	)

In the SQL strings input to switch_core_db_prepare(), one or more literals can be replace by parameters "?" or ":AAA" or "$VVV" where AAA is an identifer and VVV is a variable name according to the syntax rules of the TCL programming language. The value of these parameters (also called "host parameter names") can be set using the routines listed below.

In every case, the first parameter is a pointer to the sqlite3_stmt structure returned from switch_core_db_prepare(). The second parameter is the index of the parameter. The first parameter as an index of 1. For named parameters (":AAA" or "$VVV") you can use switch_core_db_bind_parameter_index() to get the correct index value given the parameters name. If the same named parameter occurs more than once, it is assigned the same index each time.

The fifth parameter to switch_core_db_bind_blob(), switch_core_db_bind_text(), and switch_core_db_bind_text16() is a destructor used to dispose of the BLOB or text after SQLite has finished with it. If the fifth argument is the special value SQLITE_STATIC, then the library assumes that the information is in static, unmanaged space and does not need to be freed. If the fifth argument has the value SQLITE_TRANSIENT, then SQLite makes its own private copy of the data.

The switch_core_db_bind_* routine must be called before switch_core_db_step() after an switch_core_db_prepare() or sqlite3_reset(). Unbound parameterss are interpreted as NULL.

Definition at line 144 of file switch_core_db.c.

 {
         return sqlite3_bind_text(pStmt, i, zData, nData, xDel);
 }

◆ switch_core_db_changes()

int switch_core_db_changes ( switch_core_db_t * db )

Call this routine to find the number of rows changed by the last statement.

Definition at line 174 of file switch_core_db.c.

Referenced by switch_cache_db_affected_rows().

 {
         return sqlite3_changes(db);
 }

◆ switch_core_db_close()

int switch_core_db_close ( switch_core_db_t * db )

A function to close the database.

Call this function with a pointer to a structure that was previously returned from switch_core_db_open() and the corresponding database will by closed.

All SQL statements prepared using switch_core_db_prepare() must be deallocated using switch_core_db_finalize() before this routine is called. Otherwise, SWITCH_CORE_DB_BUSY is returned and the database connection remains open.

Definition at line 58 of file switch_core_db.c.

Referenced by _switch_cache_db_get_db_handle(), sql_close(), switch_core_db_open_file(), and switch_core_db_open_in_memory().

 {
         return sqlite3_close(db);
 }

◆ switch_core_db_column_count()

int switch_core_db_column_count ( switch_core_db_stmt_t * pStmt )

Return the number of columns in the result set returned by the compiled SQL statement. This routine returns 0 if pStmt is an SQL statement that does not return data (for example an UPDATE).

Definition at line 73 of file switch_core_db.c.

Referenced by switch_cache_db_execute_sql2str().

 {
         return sqlite3_column_count(pStmt);
 }

◆ switch_core_db_column_name()

const char* switch_core_db_column_name	(	switch_core_db_stmt_t *	stmt,
		int	N
	)

The first parameter is a compiled SQL statement. This function returns the column heading for the Nth column of that statement, where N is the second function parameter. The string returned is UTF-8.

Definition at line 68 of file switch_core_db.c.

 {
         return sqlite3_column_name(stmt, N);
 }

◆ switch_core_db_column_text()

const unsigned char* switch_core_db_column_text	(	switch_core_db_stmt_t *	stmt,
		int	iCol
	)

^Strings returned by sqlite3_column_text() and sqlite3_column_text16(), even empty strings, are always zero-terminated. ^The return value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer.

^The object returned by [sqlite3_column_value()] is an [unprotected sqlite3_value] object. An unprotected sqlite3_value object may only be used with [sqlite3_bind_value()] and [sqlite3_result_value()]. If the [unprotected sqlite3_value] object returned by [sqlite3_column_value()] is used in any other way, including calls to routines like [sqlite3_value_int()], [sqlite3_value_text()], or [sqlite3_value_bytes()], then the behavior is undefined.

These routines attempt to convert the value where appropriate. ^For example, if the internal representation is FLOAT and a text result is requested, [sqlite3_snprintf()] is used internally to perform the conversion automatically. ^(The following table details the conversions that are applied:

Internal Type Requested Type Conversion

NULL INTEGER Result is 0 NULL FLOAT Result is 0.0 NULL TEXT Result is a NULL pointer NULL BLOB Result is a NULL pointer INTEGER FLOAT Convert from integer to float INTEGER TEXT ASCII rendering of the integer INTEGER BLOB Same as INTEGER->TEXT FLOAT INTEGER [CAST] to INTEGER FLOAT TEXT ASCII rendering of the float FLOAT BLOB [CAST] to BLOB TEXT INTEGER [CAST] to INTEGER TEXT FLOAT [CAST] to REAL TEXT BLOB No change BLOB INTEGER [CAST] to INTEGER BLOB FLOAT [CAST] to REAL BLOB TEXT Add a zero terminator if needed

Return the value as UTF-8 text.

Definition at line 63 of file switch_core_db.c.

Referenced by switch_cache_db_execute_sql2str().

 {
         return sqlite3_column_text(stmt, iCol);
 }

◆ switch_core_db_errmsg()

const char* switch_core_db_errmsg ( switch_core_db_t * db )

Return a pointer to a UTF-8 encoded string describing in english the error condition for the most recent switch_core_db_* API call. The returned string is always terminated by an 0x00 byte.

The string "not an error" is returned when the most recent API call was successful.

Definition at line 78 of file switch_core_db.c.

Referenced by switch_core_db_open_file(), and switch_core_db_open_in_memory().

 {
         return sqlite3_errmsg(db);
 }

◆ switch_core_db_exec()

int switch_core_db_exec	(	switch_core_db_t *	db,
		const char *	sql,
		switch_core_db_callback_func_t	callback,
		void *	data,
		char **	errmsg
	)

A function to executes one or more statements of SQL.

If one or more of the SQL statements are queries, then the callback function specified by the 3rd parameter is invoked once for each row of the query result. This callback should normally return 0. If the callback returns a non-zero value then the query is aborted, all subsequent SQL statements are skipped and the switch_core_db_exec() function returns the SWITCH_CORE_DB_ABORT.

The 4th parameter is an arbitrary pointer that is passed to the callback function as its first parameter.

The 2nd parameter to the callback function is the number of columns in the query result. The 3rd parameter to the callback is an array of strings holding the values for each column. The 4th parameter to the callback is an array of strings holding the names of each column.

The callback function may be NULL, even for queries. A NULL callback is not an error. It just means that no callback will be invoked.

If an error occurs while parsing or evaluating the SQL (but not while executing the callback) then an appropriate error message is written into memory obtained from malloc() and *errmsg is made to point to that message. The calling function is responsible for freeing the memory that holds the error message. Use switch_core_db_free() for this. If errmsg==NULL, then no error message is ever written.

The return value is is SWITCH_CORE_DB_OK if there are no errors and some other return code if there is an error. The particular return value depends on the type of error.

If the query could not be executed because a database file is locked or busy, then this function returns SWITCH_CORE_DB_BUSY. (This behavior can be modified somewhat using the sswitch_core_db_busy_handler() and switch_core_db_busy_timeout() functions below.)

Definition at line 83 of file switch_core_db.c.

References SWITCH_CHANNEL_LOG, switch_core_db_free(), SWITCH_LOG_ERROR, switch_log_printf(), SWITCH_LOG_WARNING, and switch_yield.

Referenced by switch_cache_db_execute_sql_callback(), switch_cache_db_execute_sql_callback_err(), switch_cache_db_execute_sql_event_callback(), switch_cache_db_execute_sql_event_callback_err(), switch_cache_db_execute_sql_real(), switch_cache_db_test_reactive_ex(), switch_core_db_connection_setup(), switch_core_db_persistant_execute(), switch_core_db_persistant_execute_trans(), and switch_core_db_test_reactive().

 {
         int ret = 0;
         int sane = 300;
         char *err = NULL;
 
         while (--sane > 0) {
                 ret = sqlite3_exec(db, sql, callback, data, &err);
                 if (ret == SQLITE_BUSY || ret == SQLITE_LOCKED) {
                         switch_log_printf(SWITCH_CHANNEL_LOG, SWITCH_LOG_WARNING, "SQLite is %s, sane=%d [%s]\n", (ret == SQLITE_BUSY ? "BUSY" : "LOCKED"), sane, sql);
                         if (sane > 1) {
                                 switch_core_db_free(err);
                                 switch_yield(100000);
                                 continue;
                         }
                 } else {
                         break;
                 }
         }
 
         if (errmsg) {
                 *errmsg = err;
         } else if (err) {
                 switch_log_printf(SWITCH_CHANNEL_LOG, SWITCH_LOG_ERROR, "SQL ERR [%s]\n", err);
                 switch_core_db_free(err);
                 err = NULL;
         }
 
         return ret;
 }

◆ switch_core_db_finalize()

int switch_core_db_finalize ( switch_core_db_stmt_t * pStmt )

This function is called to delete a compiled SQL statement obtained by a previous call to switch_core_db_prepare(). If the statement was executed successfully, or not executed at all, then SWITCH_CORE_DB_OK is returned. If execution of the statement failed then an error code is returned.

This routine can be called at any point during the execution of the virtual machine. If the virtual machine has not completed execution when this routine is called, that is like encountering an error or an interrupt. (See switch_core_db_interrupt().) Incomplete updates may be rolled back and transactions cancelled, depending on the circumstances, and the result code returned will be SWITCH_CORE_DB_ABORT.

Definition at line 114 of file switch_core_db.c.

Referenced by switch_cache_db_execute_sql2str().

 {
         return sqlite3_finalize(pStmt);
 }

◆ switch_core_db_free()

void switch_core_db_free ( char * z )

Call this routine to free the memory that switch_core_db_get_table() allocated.

Definition at line 169 of file switch_core_db.c.

Referenced by switch_cache_db_execute_sql_callback(), switch_cache_db_execute_sql_callback_err(), switch_cache_db_execute_sql_event_callback(), switch_cache_db_execute_sql_event_callback_err(), switch_cache_db_execute_sql_real(), switch_cache_db_test_reactive_ex(), switch_core_db_exec(), switch_core_db_load_extension(), switch_core_db_persistant_execute(), switch_core_db_persistant_execute_trans(), and switch_core_db_test_reactive().

 {
         sqlite3_free(z);
 }

◆ switch_core_db_free_table()

void switch_core_db_free_table ( char ** result )

Call this routine to free the memory that sqlite3_get_table() allocated.

Definition at line 164 of file switch_core_db.c.

 {
         sqlite3_free_table(result);
 }

◆ switch_core_db_get_table()

int switch_core_db_get_table	(	switch_core_db_t *	db,
		const char *	sql,
		char ***	resultp,
		int *	nrow,
		int *	ncolumn,
		char **	errmsg
	)

This next routine is really just a wrapper around switch_core_db_exec(). Instead of invoking a user-supplied callback for each row of the result, this routine remembers each row of the result in memory obtained from malloc(), then returns all of the result after the query has finished.

As an example, suppose the query result where this table:

   Name        | Age
   -----------------------
   Alice       | 43
   Bob         | 28
   Cindy       | 21

If the 3rd argument were &azResult then after the function returns azResult will contain the following data:

   azResult[0] = "Name";
   azResult[1] = "Age";
   azResult[2] = "Alice";
   azResult[3] = "43";
   azResult[4] = "Bob";
   azResult[5] = "28";
   azResult[6] = "Cindy";
   azResult[7] = "21";

Notice that there is an extra row of data containing the column headers. But the nrow return value is still 3. *ncolumn is set to 2. In general, the number of values inserted into azResult will be ((*nrow) + 1)(*ncolumn).

After the calling function has finished using the result, it should pass the result data pointer to switch_core_db_free_table() in order to release the memory that was malloc-ed. Because of the way the malloc() happens, the calling function must not try to call free() directly. Only switch_core_db_free_table() is able to release the memory properly and safely.

The return value of this routine is the same as from switch_core_db_exec().

Definition at line 159 of file switch_core_db.c.

 {
         return sqlite3_get_table(db, sql, resultp, nrow, ncolumn, errmsg);
 }

◆ switch_core_db_last_insert_rowid()

int64_t switch_core_db_last_insert_rowid ( switch_core_db_t * db )

Each entry in a table has a unique integer key. (The key is the value of the INTEGER PRIMARY KEY column if there is such a column, otherwise the key is generated at random. The unique key is always available as the ROWID, OID, or ROWID column.) The following routine returns the integer key of the most recent insert in the database.

This function is similar to the mysql_insert_id() function from MySQL.

Definition at line 154 of file switch_core_db.c.

 {
         return sqlite3_last_insert_rowid(db);
 }

◆ switch_core_db_load_extension()

int switch_core_db_load_extension	(	switch_core_db_t *	db,
		const char *	extension
	)

Call this routine to load an external extension

Definition at line 179 of file switch_core_db.c.

References SWITCH_CHANNEL_LOG, switch_core_db_free(), SWITCH_LOG_ERROR, and switch_log_printf().

Referenced by switch_cache_db_load_extension().

 {
         int ret = 0;
         char *err = NULL;
 
 #ifdef SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION
         sqlite3_db_config(db, SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION, 1, 0);
         ret = sqlite3_load_extension(db, extension, 0, &err);
 #else
         sqlite3_enable_load_extension(db, 1);
         ret = sqlite3_load_extension(db, extension, 0, &err);
         sqlite3_enable_load_extension(db, 0);
 #endif
 
         if (err) {
                 switch_log_printf(SWITCH_CHANNEL_LOG, SWITCH_LOG_ERROR, "LOAD EXTENSION ERR [%s]\n", err);
                 switch_core_db_free(err);
                 err = NULL;
         }
         return ret;
 }

◆ switch_core_db_open()

int switch_core_db_open	(	const char *	filename,
		switch_core_db_t **	ppDb
	)

Open the database file "filename". The "filename" is UTF-8 encoded. A switch_core_db_t* handle is returned in *Db, even if an error occurs. If the database is opened (or created) successfully, then SWITCH_CORE_DB_OK is returned. Otherwise an error code is returned. The switch_core_db_errmsg() routine can be used to obtain an English language description of the error.

If the database file does not exist, then a new database is created. The encoding for the database is UTF-8.

Whether or not an error occurs when it is opened, resources associated with the switch_core_db_t* handle should be released by passing it to switch_core_db_close() when it is no longer required.

Definition at line 48 of file switch_core_db.c.

Referenced by switch_core_db_open_file().

 {
         return sqlite3_open(filename, ppDb);
 }

◆ switch_core_db_open_v2()

int switch_core_db_open_v2	(	const char *	filename,
		switch_core_db_t **	ppDb
	)

Same as switch_core_db_open() but additionally allows SQLITE_OPEN_URI

Definition at line 53 of file switch_core_db.c.

Referenced by switch_core_db_open_in_memory().

 {
         return sqlite3_open_v2(filename, ppDb, SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE | SQLITE_OPEN_URI, NULL);
 }

◆ switch_core_db_prepare()

int switch_core_db_prepare	(	switch_core_db_t *	db,
		const char *	zSql,
		int	nBytes,
		switch_core_db_stmt_t **	ppStmt,
		const char **	pzTail
	)

To execute an SQL query, it must first be compiled into a byte-code program using the following routine.

The first parameter "db" is an SQLite database handle. The second parameter "zSql" is the statement to be compiled, encoded as UTF-8. If the next parameter, "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 switch_core_db_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.

On success, SWITCH_CORE_DB_OK is returned. Otherwise an error code is returned.

Definition at line 119 of file switch_core_db.c.

Referenced by switch_cache_db_execute_sql2str().

 {
         return sqlite3_prepare(db, zSql, nBytes, ppStmt, pzTail);
 }

◆ switch_core_db_reset()

int switch_core_db_reset ( switch_core_db_stmt_t * pStmt )

The switch_core_db_reset() function is called to reset a compiled SQL statement obtained by a previous call to switch_core_db_prepare() back to it's initial state, ready to be re-executed. Any SQL statement variables that had values bound to them using the switch_core_db_bind_*() API retain their values.

Definition at line 129 of file switch_core_db.c.

 {
         return sqlite3_reset(pStmt);
 }

◆ switch_core_db_step()

int switch_core_db_step ( switch_core_db_stmt_t * stmt )

After an SQL query has been compiled with a call to either switch_core_db_prepare(), then this function must be called one or more times to execute the statement.

The return value will be either SWITCH_CORE_DB_BUSY, SWITCH_CORE_DB_DONE, SWITCH_CORE_DB_ROW, SWITCH_CORE_DB_ERROR, or SWITCH_CORE_DB_MISUSE.

SWITCH_CORE_DB_BUSY means that the database engine attempted to open a locked database and there is no busy callback registered. Call switch_core_db_step() again to retry the open.

SWITCH_CORE_DB_DONE means that the statement has finished executing successfully. switch_core_db_step() should not be called again on this virtual machine.

If the SQL statement being executed returns any data, then SWITCH_CORE_DB_ROW is returned each time a new row of data is ready for processing by the caller. The values may be accessed using the switch_core_db_column_*() functions described below. switch_core_db_step() is called again to retrieve the next row of data.

SWITCH_CORE_DB_ERROR means that a run-time error (such as a constraint violation) has occurred. switch_core_db_step() should not be called again on the VM. More information may be found by calling switch_core_db_errmsg().

SWITCH_CORE_DB_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 SWITCH_CORE_DB_ERROR or SWITCH_CORE_DB_DONE. Or it could be the case the the same database connection is being used simulataneously by two or more threads.

Definition at line 124 of file switch_core_db.c.

Referenced by switch_cache_db_execute_sql2str().

 {
         return sqlite3_step(stmt);
 }

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ SWITCH_CORE_DB_ABORT

◆ SWITCH_CORE_DB_AUTH

◆ SWITCH_CORE_DB_BUSY

◆ SWITCH_CORE_DB_CANTOPEN

◆ SWITCH_CORE_DB_CONSTRAINT

◆ SWITCH_CORE_DB_CORRUPT

◆ SWITCH_CORE_DB_DONE

◆ SWITCH_CORE_DB_EMPTY

◆ SWITCH_CORE_DB_ERROR

◆ SWITCH_CORE_DB_FORMAT

◆ SWITCH_CORE_DB_FULL

◆ SWITCH_CORE_DB_INTERNAL

◆ SWITCH_CORE_DB_INTERRUPT

◆ SWITCH_CORE_DB_IOERR

◆ SWITCH_CORE_DB_LOCKED

◆ SWITCH_CORE_DB_MISMATCH

◆ SWITCH_CORE_DB_MISUSE

◆ SWITCH_CORE_DB_NOLFS

◆ SWITCH_CORE_DB_NOMEM

◆ SWITCH_CORE_DB_NOTADB

◆ SWITCH_CORE_DB_NOTFOUND

◆ SWITCH_CORE_DB_OK

◆ SWITCH_CORE_DB_PERM

◆ SWITCH_CORE_DB_PROTOCOL

◆ SWITCH_CORE_DB_RANGE

◆ SWITCH_CORE_DB_READONLY

◆ SWITCH_CORE_DB_ROW

◆ SWITCH_CORE_DB_SCHEMA

◆ SWITCH_CORE_DB_STATIC

◆ SWITCH_CORE_DB_TOOBIG

◆ SWITCH_CORE_DB_TRANSIENT

Typedef Documentation

◆ switch_core_db_callback_func_t

◆ switch_core_db_destructor_type_t

◆ switch_core_db_err_callback_func_t

◆ switch_core_db_stmt_t

◆ switch_core_db_t

Function Documentation

◆ switch_core_db_bind_double()

◆ switch_core_db_bind_int()

◆ switch_core_db_bind_int64()

◆ switch_core_db_bind_text()

◆ switch_core_db_changes()

◆ switch_core_db_close()

◆ switch_core_db_column_count()

◆ switch_core_db_column_name()

◆ switch_core_db_column_text()

◆ switch_core_db_errmsg()

◆ switch_core_db_exec()

◆ switch_core_db_finalize()

◆ switch_core_db_free()

◆ switch_core_db_free_table()

◆ switch_core_db_get_table()

◆ switch_core_db_last_insert_rowid()

◆ switch_core_db_load_extension()

◆ switch_core_db_open()

◆ switch_core_db_open_v2()

◆ switch_core_db_prepare()

◆ switch_core_db_reset()

◆ switch_core_db_step()