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_Result * sql_result_new ()

New a SQL_Result instance.

StringList * sql_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_Result * sqlite_get_sql_result (sqlite3 *db, const char *sqlClause)

Get the results of SQL clause.

SQL_Result * sqlite_get_tableNames (sqlite3 *db)

Get the list of table names in the database.

StringList * sqlite_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:

This function does not have argument zVfs.
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()


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_Result *	sql_result_new ()
	New a SQL_Result instance.
StringList *	sql_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_Result *	sqlite_get_sql_result (sqlite3 db, const char sqlClause)
	Get the results of SQL clause.
SQL_Result *	sqlite_get_tableNames (sqlite3 *db)
	Get the list of table names in the database.
StringList *	sqlite_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.