CamelDB

CamelDB

Functions

Types and Values

#define CAMEL_DB_ERROR
enum CamelDBError
struct CamelDB

Object Hierarchy

    GObject
    ╰── CamelDB
        ╰── CamelStoreDB

Description

Functions

CamelDBCollate ()

gint
(*CamelDBCollate) (gpointer enc,
                   gint length1,
                   gconstpointer data1,
                   gint length2,
                   gconstpointer data2);

A collation callback function.

Parameters

enc

a used encoding (SQLITE_UTF8)

 

length1

length of the data1

 

data1

the first value, of lenth length1

 

length2

length of the data2

 

data2

the second value, of lenth length2

 

Returns

less than zero, zero, or greater than zero value, the same as for example strcmp() does.

Since: 2.24


CamelDBSelectCB ()

gboolean
(*CamelDBSelectCB) (gpointer user_data,
                    gint ncol,
                    gchar **colvalues,
                    gchar **colnames);

A callback called for the SELECT statements. The items at the same index of colvalues and colnames correspond to each other.

Parameters

user_data

a callback user data

 

ncol

how many columns is provided

 

colvalues

array of column values, as UTF-8 strings.

[array length=ncol]

colnames

array of column names.

[array length=ncol]

Returns

TRUE to continue, FALSE to abort the execution.

Since: 3.58


camel_db_error_quark ()

GQuark
camel_db_error_quark (void);

camel_db_new ()

CamelDB *
camel_db_new (const gchar *filename,
              GError **error);

Creates a new CamelDB instance and calls camel_db_open() to open a database file. Free the returned object with g_object_unref(), when no longer needed.

Parameters

filename

A file name with the database to open/create

 

error

return location for a GError, or NULL

 

Returns

A new CamelDB instance, or NULL on error.

[transfer full][nullable]

Since: 3.58


camel_db_open ()

gboolean
camel_db_open (CamelDB *cdb,
               const gchar *filename,
               GError **error);

Opens the database stored as filename . The function can be called only once, all following calls will result into failures.

Parameters

cdb

a CamelDB

 

filename

A file name with the database to open/create

 

error

return location for a GError, or NULL

 

Returns

whether succeeded

Since: 3.58


camel_db_get_filename ()

const gchar *
camel_db_get_filename (CamelDB *cdb);

Parameters

cdb

a CamelDB

 

Returns

A filename associated with cdb .

[transfer none]

Since: 3.24


camel_db_writer_lock ()

void
camel_db_writer_lock (CamelDB *cdb);

Acquires a writer lock on the cdb . It can be called multiple times. Call pair function camel_db_writer_unlock() to release it.

Note: This adds a transaction on the DB. Not all statements can be executed in the transaction.

Parameters

cdb

a CamelDB

 

Since: 3.58


camel_db_writer_unlock ()

void
camel_db_writer_unlock (CamelDB *cdb);

Releases a write lock on the cdb previously acquired by calling camel_db_writer_lock().

Parameters

cdb

a CamelDB

 

Since: 3.58


camel_db_reader_lock ()

void
camel_db_reader_lock (CamelDB *cdb);

Acquires a reader lock on the cdb . It can be called multiple times. Call pair function camel_db_reader_unlock() to release it. it's okay to call this function when a writer lock is already acquired by the calling thread.

Parameters

cdb

a CamelDB

 

Since: 3.58


camel_db_reader_unlock ()

void
camel_db_reader_unlock (CamelDB *cdb);

Releases a reader lock on the cdb previously acquired by calling camel_db_reader_lock().

Parameters

cdb

a CamelDB

 

Since: 3.58


camel_db_has_table ()

gboolean
camel_db_has_table (CamelDB *cdb,
                    const gchar *table_name);

Checks whether the table_name exists in the cdb .

Parameters

cdb

a CamelDB

 

table_name

a table name

 

Returns

TRUE, when the table_name exists, FALSE when not or when any other error occurred

Since: 3.58


camel_db_has_table_with_column ()

gboolean
camel_db_has_table_with_column (CamelDB *cdb,
                                const gchar *table_name,
                                const gchar *column_name);

Checks whether the table_name exists in the cdb and contains column named column_name .

Parameters

cdb

a CamelDB

 

table_name

a table name

 

column_name

a table name

 

Returns

TRUE, when the table_name exists and contains column_name column, FALSE when not or when any other error occurred

Since: 3.58


camel_db_exec_select ()

gboolean
camel_db_exec_select (CamelDB *cdb,
                      const gchar *stmt,
                      CamelDBSelectCB callback,
                      gpointer user_data,
                      GError **error);

Executes a SELECT statement and calls the callback for each selected row.

Parameters

cdb

a CamelDB

 

stmt

a SELECT statement to execute

 

callback

a callback to call for each row.

[scope call][closure user_data]

user_data

user data for the callback

 

error

return location for a GError, or NULL

 

Returns

whether succeeded

Since: 3.58


camel_db_exec_statement ()

gboolean
camel_db_exec_statement (CamelDB *cdb,
                         const gchar *stmt,
                         GError **error);

Executes an SQLite statement.

Parameters

cdb

a CamelDB

 

stmt

an SQL (SQLite) statement to execute

 

error

return location for a GError, or NULL

 

Returns

whether succeeded

Since: 3.58


camel_db_begin_transaction ()

gboolean
camel_db_begin_transaction (CamelDB *cdb,
                            GError **error);

Begins transaction. End it with camel_db_end_transaction() or camel_db_abort_transaction().

Parameters

cdb

a CamelDB

 

error

return location for a GError, or NULL

 

Returns

whether succeeded

Since: 3.58


camel_db_end_transaction ()

gboolean
camel_db_end_transaction (CamelDB *cdb,
                          GError **error);

Ends an ongoing transaction by committing the changes.

Parameters

cdb

a CamelDB

 

error

return location for a GError, or NULL

 

Returns

whether succeeded

Since: 3.58


camel_db_abort_transaction ()

gboolean
camel_db_abort_transaction (CamelDB *cdb,
                            GError **error);

Ends an ongoing transaction by ignoring the changes.

Parameters

cdb

a CamelDB

 

error

return location for a GError, or NULL

 

Returns

whether succeeded

Since: 3.58


camel_db_set_collate ()

gboolean
camel_db_set_collate (CamelDB *cdb,
                      const gchar *col,
                      const gchar *collate,
                      CamelDBCollate func);

Defines a collation collate , which can be used in SQL (SQLite) statement as a collation function. The func is called when colation is used.

Parameters

cdb

a CamelDB

 

col

a column name; currently unused

 

collate

collation name

 

func

a CamelDBCollate collation function.

[scope call]

Returns

whether succeeded

Since: 2.24


camel_db_maybe_run_maintenance ()

gboolean
camel_db_maybe_run_maintenance (CamelDB *cdb,
                                GError **error);

Runs a cdb maintenance, which includes vacuum, if necessary.

Parameters

cdb

a CamelDB

 

error

a GError or NULL

 

Returns

Whether succeeded.

Since: 3.16


camel_db_release_cache_memory ()

void
camel_db_release_cache_memory (void);

Instructs sqlite to release its memory, if possible. This can be avoided when CAMEL_SQLITE_FREE_CACHE environment variable is set.

Since: 3.24


camel_db_sqlize_string ()

gchar *
camel_db_sqlize_string (const gchar *string);

Converts the string to be usable in the SQLite statements.

Parameters

string

a string to "sqlize"

 

Returns

A newly allocated sqlized string . The returned value should be freed with camel_db_sqlize_string(), when no longer needed.

[transfer full]

Since: 2.24


camel_db_free_sqlized_string ()

void
camel_db_free_sqlized_string (gchar *string);

Frees a string previously returned by camel_db_sqlize_string().

Parameters

string

a string to free.

[nullable]

Since: 2.24


camel_db_sqlize_to_statement ()

void
camel_db_sqlize_to_statement (GString *stmt,
                              const gchar *str,
                              CamelDBSqlizeFlags flags);

Encodes the str to be safe to use as a string in an SQL statement and appends it to the stmt . When str is NULL, a NULL word is appended.

Parameters

stmt

a GString with an SQL statement

 

str

a string to sqlize.

[nullable]

flags

bit-or of CamelDBSqlizeFlags

 

Since: 3.58

Types and Values

CAMEL_DB_ERROR

#define             CAMEL_DB_ERROR

Since: 3.44


enum CamelDBError

Members

CAMEL_DB_ERROR_CORRUPT

database is corrupt

 

Since: 3.44


struct CamelDB

struct CamelDB;

Since: 2.24