CamelDB: Camel Reference Manual

## CamelDB CamelDB |

## Functions

gint | (*CamelDBCollate) ()
gboolean | (*CamelDBSelectCB) ()
GQuark | camel_db_error_quark ()
CamelDB * | camel_db_new ()
gboolean | camel_db_open ()
const gchar * | camel_db_get_filename ()
void | camel_db_writer_lock ()
void | camel_db_writer_unlock ()
void | camel_db_reader_lock ()
void | camel_db_reader_unlock ()
gboolean | camel_db_has_table ()
gboolean | camel_db_has_table_with_column ()
gboolean | camel_db_exec_select ()
gboolean | camel_db_exec_statement ()
gboolean | camel_db_begin_transaction ()
gboolean | camel_db_end_transaction ()
gboolean | camel_db_abort_transaction ()
gboolean | camel_db_set_collate ()
gboolean | camel_db_maybe_run_maintenance ()
void | camel_db_release_cache_memory ()
gchar * | camel_db_sqlize_string ()
void | camel_db_free_sqlized_string ()
void | camel_db_sqlize_to_statement ()

## 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