From df6e1cf2ba317c0ad43315582f9c6399e6ed4ff1 Mon Sep 17 00:00:00 2001 From: Michael Jerris Date: Fri, 6 Jan 2006 16:12:33 +0000 Subject: [PATCH] First bit of sqlite docs... still needs quite a bit o work.. git-svn-id: http://svn.freeswitch.org/svn/freeswitch/trunk@298 d0543943-73ff-0310-b7d9-9358b9ac24b2 --- src/include/switch_sqlite.h | 325 +++++++++++++++++++++++++++++++++++- 1 file changed, 316 insertions(+), 9 deletions(-) diff --git a/src/include/switch_sqlite.h b/src/include/switch_sqlite.h index d257ed6950..aaff4e1132 100644 --- a/src/include/switch_sqlite.h +++ b/src/include/switch_sqlite.h @@ -58,39 +58,346 @@ extern "C" { */ typedef sqlite3 switch_core_db; +/** +** Aggregate functions use the following routine to allocate +** a structure for storing their state. The first time this routine +** is called for a particular aggregate, a new structure of size nBytes +** is allocated, zeroed, and returned. On subsequent calls (for the +** same aggregate instance) the same buffer is returned. The implementation +** of the aggregate can use the returned buffer to accumulate data. +** +** The buffer allocated is freed automatically by SQLite. +*/ +DoxyDefine(void *switch_core_db_aggregate_context(sqlite3_context*, int nBytes);) #define switch_core_db_aggregate_context sqlite3_aggregate_context + +/** +** /return the number of calls to xStep for a particular +** aggregate function instance. The current call to xStep counts so this +** routine always returns at least 1. +*/ +DoxyDefine(int switch_core_db_aggregate_count(sqlite3_context*);) #define switch_core_db_aggregate_count sqlite3_aggregate_count + +/** +** In the SQL strings input to sqlite3_prepare() and sqlite3_prepare16(), +** 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 sqlite3_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 fifth parameter to sqlite3_bind_blob(), sqlite3_bind_text(), and +** sqlite3_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 sqlite3_bind_* routine must be called before sqlite3_step() after +** an sqlite3_prepare() or sqlite3_reset(). Unbound parameterss are +** interpreted as NULL. +*/ + +DoxyDefine(int switch_core_db_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));) #define switch_core_db_bind_blob sqlite3_bind_blob +DoxyDefine(int switch_core_db_bind_double(sqlite3_stmt*, int, double);) #define switch_core_db_bind_double sqlite3_bind_double +DoxyDefine(int switch_core_db_bind_int(sqlite3_stmt*, int, int);) #define switch_core_db_bind_int sqlite3_bind_int +DoxyDefine(int switch_core_db_bind_int64(sqlite3_stmt*, int, sqlite_int64);) #define switch_core_db_bind_int64 sqlite3_bind_int64 +DoxyDefine(int switch_core_db_bind_null(sqlite3_stmt*, int);) #define switch_core_db_bind_null sqlite3_bind_null -#define switch_core_db_bind_parameter_count sqlite3_bind_parameter_count -#define switch_core_db_bind_parameter_index sqlite3_bind_parameter_index -#define switch_core_db_bind_parameter_name sqlite3_bind_parameter_name +DoxyDefine(int switch_core_db_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));) #define switch_core_db_bind_text sqlite3_bind_text +DoxyDefine(int switch_core_db_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));) #define switch_core_db_bind_text16 sqlite3_bind_text16 -#define switch_core_db_btree_trace sqlite3_btree_trace +DoxyDefine(int switch_core_db_bind_value(sqlite3_stmt*, int, const sqlite3_value*);) +#define switch_core_db_bind_value sqlite3_bind_value + +/** +** Return the number of parameters in a compiled SQL statement. This +** routine was added to support DBD::SQLite. +*/ +DoxyDefine(int switch_core_db_bind_parameter_count(sqlite3_stmt*);) +#define switch_core_db_bind_parameter_count sqlite3_bind_parameter_count + +/** +** Return the index of a parameter with the given name. The name +** must match exactly. If no parameter with the given name is found, +** return 0. +*/ +DoxyDefine(int switch_core_db_bind_parameter_index(sqlite3_stmt*, const char *zName);) +#define switch_core_db_bind_parameter_index sqlite3_bind_parameter_index + +/** +** Return the name of the i-th parameter. Ordinary parameters "?" are +** nameless and a NULL is returned. For parameters of the form :AAA or +** $VVV the complete text of the parameter name is returned, including +** the initial ":" or "$". NULL is returned if the index is out of range. +*/ +DoxyDefine(const char *switch_core_db_bind_parameter_name(sqlite3_stmt*, int);) +#define switch_core_db_bind_parameter_name sqlite3_bind_parameter_name + +/** +** This routine identifies a callback function that is invoked +** whenever an attempt is made to open a database table that is +** currently locked by another process or thread. If the busy callback +** is NULL, then sqlite3_exec() returns SQLITE_BUSY immediately if +** it finds a locked table. If the busy callback is not NULL, then +** sqlite3_exec() invokes the callback with three arguments. The +** second argument is the name of the locked table and the third +** argument is the number of times the table has been busy. If the +** busy callback returns 0, then sqlite3_exec() immediately returns +** SQLITE_BUSY. If the callback returns non-zero, then sqlite3_exec() +** tries to open the table again and the cycle repeats. +** +** The default busy callback is NULL. +** +** Sqlite is re-entrant, so the busy handler may start a new query. +** (It is not clear why anyone would every want to do this, but it +** is allowed, in theory.) But the busy handler may not close the +** database. Closing the database from a busy handler will delete +** data structures out from under the executing query and will +** probably result in a coredump. +*/ +DoxyDefine(int switch_core_db_busy_handler(switch_core_db*, int(*)(void*,int), void*);) #define switch_core_db_busy_handler sqlite3_busy_handler + +/** +** This routine sets a busy handler that sleeps for a while when a +** table is locked. The handler will sleep multiple times until +** at least "ms" milleseconds of sleeping have been done. After +** "ms" milleseconds of sleeping, the handler returns 0 which +** causes sqlite3_exec() to return SQLITE_BUSY. +** +** Calling this routine with an argument less than or equal to zero +** turns off all busy handlers. +*/ +DoxyDefine(int switch_core_db_busy_timeout(switch_core_db*, int ms);) #define switch_core_db_busy_timeout sqlite3_busy_timeout + +/** +** This function returns the number of database rows that were changed +** (or inserted or deleted) by the most recent called sqlite3_exec(). +** +** All changes are counted, even if they were later undone by a +** ROLLBACK or ABORT. Except, changes associated with creating and +** dropping tables are not counted. +** +** If a callback invokes sqlite3_exec() recursively, then the changes +** in the inner, recursive call are counted together with the changes +** in the outer call. +** +** SQLite implements the command "DELETE FROM table" without a WHERE clause +** by dropping and recreating the table. (This is much faster than going +** through and deleting individual elements form the table.) Because of +** this optimization, the change count for "DELETE FROM table" will be +** zero regardless of the number of elements that were originally in the +** table. To get an accurate count of the number of rows deleted, use +** "DELETE FROM table WHERE 1" instead. +*/ +DoxyDefine(int switch_core_db_changes(switch_core_db*);) #define switch_core_db_changes sqlite3_changes + +/** +** A function to close the database. +** +** Call this function with a pointer to a structure that was previously +** returned from sqlite3_open() and the corresponding database will by closed. +** +** All SQL statements prepared using sqlite3_prepare() or +** sqlite3_prepare16() must be deallocated using sqlite3_finalize() before +** this routine is called. Otherwise, SQLITE_BUSY is returned and the +** database connection remains open. +*/ +DoxyDefine(int switch_core_db_close(switch_core_db *);) #define switch_core_db_close sqlite3_close + +/** +** To avoid having to register all collation sequences before a database +** can be used, a single callback function may be registered with the +** database handle to be called whenever an undefined collation sequence is +** required. +** +** If the function is registered using the sqlite3_collation_needed() API, +** then it is passed the names of undefined collation sequences as strings +** encoded in UTF-8. If sqlite3_collation_needed16() is used, the names +** are passed as UTF-16 in machine native byte order. A call to either +** function replaces any existing callback. +** +** When the user-function is invoked, the first argument passed is a copy +** of the second argument to sqlite3_collation_needed() or +** sqlite3_collation_needed16(). The second argument is the database +** handle. The third argument is one of SQLITE_UTF8, SQLITE_UTF16BE or +** SQLITE_UTF16LE, indicating the most desirable form of the collation +** sequence function required. The fourth parameter is the name of the +** required collation sequence. +** +** The collation sequence is returned to SQLite by a collation-needed +** callback using the sqlite3_create_collation() or +** sqlite3_create_collation16() APIs, described above. +*/ +DoxyDefine(int switch_core_db_collation_needed( + switch_core_db*, + void*, + void(*)(void*,switch_core_db*,int eTextRep,const char*) +);) #define switch_core_db_collation_needed sqlite3_collation_needed +DoxyDefine(int switch_core_db_collation_needed16( + switch_core_db*, + void*, + void(*)(void*,switch_core_db*,int eTextRep,const void*) +);) #define switch_core_db_collation_needed16 sqlite3_collation_needed16 + +/** +** The next group of routines returns information about the information +** in a single column of the current result row of a query. In every +** case the first parameter is a pointer to the SQL statement that is being +** executed (the sqlite_stmt* that was returned from sqlite3_prepare()) and +** the second argument is the index of the column for which information +** should be returned. iCol is zero-indexed. The left-most column as an +** index of 0. +** +** If the SQL statement is not currently point to a valid row, or if the +** the colulmn index is out of range, the result 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, sprintf() is used internally to do 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 an empty string +** NULL BLOB Result is a zero-length BLOB +** INTEGER FLOAT Convert from integer to float +** INTEGER TEXT ASCII rendering of the integer +** INTEGER BLOB Same as for INTEGER->TEXT +** FLOAT INTEGER Convert from float to integer +** FLOAT TEXT ASCII rendering of the float +** FLOAT BLOB Same as FLOAT->TEXT +** TEXT INTEGER Use atoi() +** TEXT FLOAT Use atof() +** TEXT BLOB No change +** BLOB INTEGER Convert to TEXT then use atoi() +** BLOB FLOAT Convert to TEXT then use atof() +** BLOB TEXT Add a \000 terminator if needed +** +** The following access routines are provided: +** +** _type() Return the datatype of the result. This is one of +** SQLITE_INTEGER, SQLITE_FLOAT, SQLITE_TEXT, SQLITE_BLOB, +** or SQLITE_NULL. +** _blob() Return the value of a BLOB. +** _bytes() Return the number of bytes in a BLOB value or the number +** of bytes in a TEXT value represented as UTF-8. The \000 +** terminator is included in the byte count for TEXT values. +** _bytes16() Return the number of bytes in a BLOB value or the number +** of bytes in a TEXT value represented as UTF-16. The \u0000 +** terminator is included in the byte count for TEXT values. +** _double() Return a FLOAT value. +** _int() Return an INTEGER value in the host computer's native +** integer representation. This might be either a 32- or 64-bit +** integer depending on the host. +** _int64() Return an INTEGER value as a 64-bit signed integer. +** _text() Return the value as UTF-8 text. +** _text16() Return the value as UTF-16 text. +*/ +DoxyDefine(const void *switch_core_db_column_blob(sqlite3_stmt*, int iCol);) #define switch_core_db_column_blob sqlite3_column_blob +DoxyDefine(int switch_core_db_column_bytes(sqlite3_stmt*, int iCol);) #define switch_core_db_column_bytes sqlite3_column_bytes +DoxyDefine(int switch_core_db_column_bytes16(sqlite3_stmt*, int iCol);) #define switch_core_db_column_bytes16 sqlite3_column_bytes16 -#define switch_core_db_column_count sqlite3_column_count -#define switch_core_db_column_decltype sqlite3_column_decltype -#define switch_core_db_column_decltype16 sqlite3_column_decltype16 +DoxyDefine(double switch_core_db_column_double(sqlite3_stmt*, int iCol);) #define switch_core_db_column_double sqlite3_column_double +DoxyDefine(int switch_core_db_column_int(sqlite3_stmt*, int iCol);) #define switch_core_db_column_int sqlite3_column_int +DoxyDefine(sqlite_int64 switch_core_db_column_int64(sqlite3_stmt*, int iCol);) #define switch_core_db_column_int64 sqlite3_column_int64 -#define switch_core_db_column_name sqlite3_column_name -#define switch_core_db_column_name16 sqlite3_column_name16 +DoxyDefine(const unsigned char *switch_core_db_column_text(sqlite3_stmt*, int iCol);) #define switch_core_db_column_text sqlite3_column_text +DoxyDefine(const void *switch_core_db_column_text16(sqlite3_stmt*, int iCol);) #define switch_core_db_column_text16 sqlite3_column_text16 +DoxyDefine(int switch_core_db_column_type(sqlite3_stmt*, int iCol);) #define switch_core_db_column_type sqlite3_column_type + +/** +** 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 for +** sqlite3_column_name() and UTF-16 for sqlite3_column_name16(). +*/ +DoxyDefine(const char *switch_core_db_column_name(sqlite3_stmt*,int);) +#define switch_core_db_column_name sqlite3_column_name +DoxyDefine(const void *switch_core_db_column_name16(sqlite3_stmt*,int);) +#define switch_core_db_column_name16 sqlite3_column_name16 + +/** +** 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). +*/ +DoxyDefine(int switch_core_db_column_count(sqlite3_stmt *pStmt);) +#define switch_core_db_column_count sqlite3_column_count + +/** +** The first parameter is a compiled SQL statement. If this statement +** is a SELECT statement, the Nth column of the returned result set +** of the SELECT is a table column then the declared type of the table +** column is returned. If the Nth column of the result set is not at table +** column, then a NULL pointer is returned. The returned string is always +** UTF-8 encoded. For example, in the database schema: +** +** CREATE TABLE t1(c1 VARIANT); +** +** And the following statement compiled: +** +** SELECT c1 + 1, 0 FROM t1; +** +** Then this routine would return the string "VARIANT" for the second +** result column (i==1), and a NULL pointer for the first result column +** (i==0). +*/ +DoxyDefine(const char *switch_core_db_column_decltype(sqlite3_stmt *, int i);) +#define switch_core_db_column_decltype sqlite3_column_decltype + +/** +** The first parameter is a compiled SQL statement. If this statement +** is a SELECT statement, the Nth column of the returned result set +** of the SELECT is a table column then the declared type of the table +** column is returned. If the Nth column of the result set is not at table +** column, then a NULL pointer is returned. The returned string is always +** UTF-16 encoded. For example, in the database schema: +** +** CREATE TABLE t1(c1 INTEGER); +** +** And the following statement compiled: +** +** SELECT c1 + 1, 0 FROM t1; +** +** Then this routine would return the string "INTEGER" for the second +** result column (i==1), and a NULL pointer for the first result column +** (i==0). +*/ +DoxyDefine(const void *switch_core_db_column_decltype16(sqlite3_stmt*,int);) +#define switch_core_db_column_decltype16 sqlite3_column_decltype16 + #define switch_core_db_commit_hook sqlite3_commit_hook #define switch_core_db_complete sqlite3_complete #define switch_core_db_complete16 sqlite3_complete16