sqlite_functions.h File Reference

SQLite suppporting data structures and functions. More...

#include <sqlite3.h>
#include "str_functions.h"

Go to the source code of this file.

Data Structures

struct  SQL_Result
 Data structure that holds the result of SQL functions and command. More...

Defines

SQL file access flags.
These flags are for SQLite 3.3.X and earlier, as those versions do not have following definitions.

#define SQLITE_OPEN_READONLY   0x00000001
 The database is opened for reading only.
#define SQLITE_OPEN_READWRITE   0x00000002
 The database is opened for reading and writing.
#define SQLITE_OPEN_CREATE   0x00000004
 The database is created if it does not already exist.
SQL_Result initial parameters.
These parameters define the initial size of SQL_Result.

Change them by define -D<parameter>=<param_value> flag in CC.

#define SQL_RESULT_FIELD_CHUNK_SIZE   2048
 Chunk size for field names.
#define SQL_RESULT_FIELD_ELEMENT_COUNT   128
 Number of fields.
#define SQL_RESULT_FIELD_CONST_COUNT   0
 Number of constant fields.
#define SQL_RESULT_RESULT_CHUNK_SIZE   65536
 Chunk size for result names.
#define SQL_RESULT_RESULT_ELEMENT_COUNT   512
 Number of results.

Typedefs

typedef int(* sqlite_exec_callback )(gpointer user_option, gint col_num, gchar **results, gchar **col_names)
 Prototype of callback function for SQL execution (sqlite3_exec).
typedef void(* sqlite_error_callback )(sqlite3 *db, const gchar *sqlClause, gint error_code, const gchar *error_msg, gpointer error_option)
 Prototype of error handling callback function for sqlite_exec_handle_error().

Functions

int sqlite_open (const char *filename, sqlite3 **ppDb, int flags)
 Open a sqlite database.
SQL_Resultsql_result_new ()
 New a SQL_Result instance.
StringListsql_result_free (SQL_Result *sResult, gboolean freeResult)
 Free a SQL_Result instance.
int sqlite_count_matches (sqlite3 *db, const char *sqlClause, char **errMsg_ptr)
 Count the matches returned by SQL clause.
void sqlite_error_callback_hide_constraint_error (sqlite3 *db, const gchar *sqlClause, gint error_code, const gchar *error_msg, gpointer prompt)
 An sqlite error callback function that print all error message except constraint error.
void sqlite_error_callback_print_message (sqlite3 *db, const gchar *sqlClause, gint error_code, const gchar *error_msg, gpointer prompt)
 An sqlite error callback function that print error messages.
int sqlite_exec_handle_error (sqlite3 *db, const gchar *sqlClause, sqlite_exec_callback exec_func, gpointer exec_option, sqlite_error_callback error_func, gpointer error_option)
 Sqlite exec function with error handling.
SQL_Resultsqlite_get_sql_result (sqlite3 *db, const char *sqlClause)
 Get the results of SQL clause.
SQL_Resultsqlite_get_tableNames (sqlite3 *db)
 Get the list of table names in the database.
StringListsqlite_get_fieldNames (sqlite3 *db, const char *sqlClause, int *execResult_ptr, char **errMsg_ptr)
 Get the fields of result table of a SQL clause.
char * sqlite_value_signed_text (sqlite3_value *value)
 Return the value as signed string.
char * sqlite_value_signed_text_buffer (char *buf, sqlite3_value *value)
 Store the value as signed string to provided buffer.


Detailed Description

This header file lists supporting data structures and functions of SQLite.

Typedef Documentation

typedef void(* sqlite_error_callback)(sqlite3 *db, const gchar *sqlClause, gint error_code, const gchar *error_msg, gpointer error_option)

This function prototype abstracts the sqlite_exec_handle_error() error handling functions.

A implementing function will be called if an error occurs in sqlite_exec_handle_error().

Parameters:
db The db from from sqlite_exec_handle_error().
sqlClause The original sqlClause from from sqlite_exec_handle_error().
error_code Return value of sqlite3_exec().
error_msg Error message from sqlite3_exec().
error_option Other option that the callback function needs, come from error_option of sqlite_exec_handle_error() .


Function Documentation

StringList* sql_result_free ( SQL_Result sResult,
gboolean  freeResult 
)

Parameters:
sResult SQL_Result to be freed.
freeResult TRUE for free the whole SQL_Result; while FALSE keep the sResult->resultList but free everything else.
Returns:
NULL if freeResult is TRUE; sResult->resultList if freeResult is FALSE.

SQL_Result* sql_result_new (  ) 

Returns:
the newly allocated SQL_Result instance.

int sqlite_count_matches ( sqlite3 *  db,
const char *  sqlClause,
char **  errMsg_ptr 
)

The error message passed back through the errMsg is held in memory obtained from sqlite3_malloc(). To avoid a memory leak, the calling application should call sqlite3_free() on any error message returned through the errMsg parameter when it has finished using the error message.

Parameters:
db The database.
sqlClause SQL clause.
errMsg_ptr The error message will be written here. Free it with sqlite3_free().
Returns:
0 if no matches found. Positive number is number of matched founded. Negative number is sqlite3_exec result code multiplied by -1.

void sqlite_error_callback_hide_constraint_error ( sqlite3 *  db,
const gchar *  sqlClause,
gint  error_code,
const gchar *  error_msg,
gpointer  prompt 
)

This function is just like sqlite_error_callback_print_message(), except the constraint error messages are hidden. This is useful when the invalid records (which do not meet the constraint) are expected and skipped.

Parameters:
db The db from from sqlite_exec_handle_error().
sqlClause The original sqlClause from from sqlite_exec_handle_error().
error_code Return value of sqlite3_exec().
error_msg Error message from sqlite3_exec().
prompt Prompt of error message. From error_option of sqlite_exec_handle_error().
See also:
sqlite_error_callback

sqlite_exec_handle_error()

sqlite_error_callback_print_message()

void sqlite_error_callback_print_message ( sqlite3 *  db,
const gchar *  sqlClause,
gint  error_code,
const gchar *  error_msg,
gpointer  prompt 
)

This function is an implementation of sqlite_error_callback, which can be called by sqlite_exec_handle_error().

It outputs error message in following format:

prompt: Error on SQL statement: sqlClause. Error code: error_code message: error_msg.

Parameters:
db The db from from sqlite_exec_handle_error().
sqlClause The original sqlClause from from sqlite_exec_handle_error().
error_code Return value of sqlite3_exec().
error_msg Error message from sqlite3_exec().
prompt Prompt of error message. From error_option of sqlite_exec_handle_error().
See also:
sqlite_error_callback

sqlite_exec_handle_error()

sqlite_error_callback_hide_constraint_error()

int sqlite_exec_handle_error ( sqlite3 *  db,
const gchar *  sqlClause,
sqlite_exec_callback  exec_func,
gpointer  exec_option,
sqlite_error_callback  error_func,
gpointer  error_option 
)

This function adds error handle to sqlite3_exec().

It calls sqlite3_exec() for DB operations. When encounter error, error_func will be called for error handling. See sqlite_error_callback for the function prototype.

Parameters:
db Database for DB operation.
sqlClause SQL caluse
exec_func Callback function for sqlite3_exec().
exec_option Option for exec_func.
error_func Error handling callback function.
error_option Option for err_func
Returns:
SQLite result codes
See also:
sqlite3_exec()

sqlite_exec_callback

sqlite_error_callback

sqlite_error_callback_print_message()

sqlite_error_callback_hide_constraint_error()

StringList* sqlite_get_fieldNames ( sqlite3 *  db,
const char *  sqlClause,
int *  execResult_ptr,
char **  errMsg_ptr 
)

The result code is store in execResult_ptr, calling application should provide a int-type variable to store the result code.

The error message passed back through the errMsg is held in memory obtained from sqlite3_malloc(). To avoid a memory leak, the calling application should call sqlite3_free() on any error message returned through the errMsg parameter when it has finished using the error message.

Parameters:
db The database.
sqlClause SQL clause.
execResult_ptr The result code will be written here.
errMsg_ptr The error message will be written here.
Returns:
SQL_Result that stores the results.

SQL_Result* sqlite_get_sql_result ( sqlite3 *  db,
const char *  sqlClause 
)

Parameters:
db The database.
sqlClause SQL clause.
Returns:
SQL_Result that stores the results.

SQL_Result* sqlite_get_tableNames ( sqlite3 *  db  ) 

Parameters:
db The database.
Returns:
SQL_Result that stores the results. Specifically, in resultList.

int sqlite_open ( const char *  filename,
sqlite3 **  ppDb,
int  flags 
)

This function is very similar to sqlite3_open_v2(). Except:

  1. This function does not have argument zVfs.
  2. It provide SQL file access flags for SQLite 3.3.X and eariler.

Parameters:
filename The SQLite database to be opened.
ppDb Returned pointer to database connection handle.
flags SQL file access flags, see SQL_fileAccessFlags.
Returns:
SQLITE_OK if success; otherwise returns corresponding SQLite error code.
See also:
sqlite3_open()

sqlite3_open_v2()

SQL file access flags..

char* sqlite_value_signed_text ( sqlite3_value *  value  ) 

sqlite3_value_text() returns unsigned char array, unfortunately, this is not expected for most of string functions. This function return the value as a signed string.

Parameters:
value the value from SQLite.
Returns:
a newly allocated signed string that stores the value. Free it with sqlite3_free().
See also:
sqlite_value_signed_text_buffer()

char* sqlite_value_signed_text_buffer ( char *  buf,
sqlite3_value *  value 
)

It is similar with sqlite3_value_text(), except developers can provide their own buffer space to s

Note:
This function does not check the buffer overflow, it is developers' responsibility to ensure the provided buffer has enough space.
Parameters:
buf the provided buffer.
value the value from SQLite.
Returns:
same as buf.
See also:
sqlite_value_signed_text()


Generated on Tue Jan 13 10:49:25 2009 for libUnihan by  doxygen 1.5.7.1