## CamelDB

CamelDB

## Synopsis

    #define             CAMEL_DB_FILE
    #define             CAMEL_DB_IN_MEMORY_TABLE
    #define             CAMEL_DB_IN_MEMORY_DB
    #define             CAMEL_DB_IN_MEMORY_TABLE_LIMIT
    #define             CAMEL_DB_FREE_CACHE_SIZE
    #define             CAMEL_DB_SLEEP_INTERVAL
    #define             CAMEL_DB_RELEASE_SQLITE_MEMORY
    #define             CAMEL_DB_USE_SHARED_CACHE
    gint                (*CamelDBCollate)                   (gpointer Param1,
                                                             gint Param2,
                                                             gconstpointer Param3,
                                                             gint Param4,
                                                             gconstpointer Param5);
                        CamelDB;
                        CamelMIRecord;
                        CamelFIRecord;
    enum                CamelDBKnownColumnNames;
    CamelDBKnownColumnNames camel_db_get_column_ident       (GHashTable **hash,
                                                             gint index,
                                                             gint ncols,
                                                             gchar **col_names);
    gint                (*CamelDBSelectCB)                  (gpointer data,
                                                             gint ncol,
                                                             gchar **colvalues,
                                                             gchar **colnames);
    CamelDB *           camel_db_open                       (const gchar *path,
                                                             GError **error);
    CamelDB *           camel_db_clone                      (CamelDB *cdb,
                                                             GError **error);
    void                camel_db_close                      (CamelDB *cdb);
    gint                camel_db_command                    (CamelDB *cdb,
                                                             const gchar *stmt,
                                                             GError **error);
    gint                camel_db_transaction_command        (CamelDB *cdb,
                                                             GList *qry_list,
                                                             GError **error);
    gint                camel_db_begin_transaction          (CamelDB *cdb,
                                                             GError **error);
    gint                camel_db_add_to_transaction         (CamelDB *cdb,
                                                             const gchar *query,
                                                             GError **error);
    gint                camel_db_end_transaction            (CamelDB *cdb,
                                                             GError **error);
    gint                camel_db_abort_transaction          (CamelDB *cdb,
                                                             GError **error);
    gint                camel_db_clear_folder_summary       (CamelDB *cdb,
                                                             const gchar *folder,
                                                             GError **error);
    gint                camel_db_rename_folder              (CamelDB *cdb,
                                                             const gchar *old_folder,
                                                             const gchar *new_folder,
                                                             GError **error);
    gint                camel_db_delete_folder              (CamelDB *cdb,
                                                             const gchar *folder,
                                                             GError **error);
    gint                camel_db_delete_uid                 (CamelDB *cdb,
                                                             const gchar *folder,
                                                             const gchar *uid,
                                                             GError **error);
    gint                camel_db_delete_uids                (CamelDB *cdb,
                                                             const gchar *folder_name,
                                                             GList *uids,
                                                             GError **error);
    gint                camel_db_create_folders_table       (CamelDB *cdb,
                                                             GError **error);
    gint                camel_db_select                     (CamelDB *cdb,
                                                             const gchar *stmt,
                                                             CamelDBSelectCB callback,
                                                             gpointer data,
                                                             GError **error);
    gint                camel_db_write_folder_info_record   (CamelDB *cdb,
                                                             CamelFIRecord *record,
                                                             GError **error);
    gint                camel_db_read_folder_info_record    (CamelDB *cdb,
                                                             const gchar *folder_name,
                                                             CamelFIRecord *record,
                                                             GError **error);
    gint                camel_db_prepare_message_info_table (CamelDB *cdb,
                                                             const gchar *folder_name,
                                                             GError **error);
    gint                camel_db_write_message_info_record  (CamelDB *cdb,
                                                             const gchar *folder_name,
                                                             CamelMIRecord *record,
                                                             GError **error);
    gint                camel_db_write_fresh_message_info_record
                                                            (CamelDB *cdb,
                                                             const gchar *folder_name,
                                                             CamelMIRecord *record,
                                                             GError **error);
    gint                camel_db_read_message_info_records  (CamelDB *cdb,
                                                             const gchar *folder_name,
                                                             gpointer p,
                                                             CamelDBSelectCB read_mir_callback,
                                                             GError **error);
    gint                camel_db_read_message_info_record_with_uid
                                                            (CamelDB *cdb,
                                                             const gchar *folder_name,
                                                             const gchar *uid,
                                                             gpointer p,
                                                             CamelDBSelectCB read_mir_callback,
                                                             GError **error);
    gint                camel_db_count_junk_message_info    (CamelDB *cdb,
                                                             const gchar *table_name,
                                                             guint32 *count,
                                                             GError **error);
    gint                camel_db_count_unread_message_info  (CamelDB *cdb,
                                                             const gchar *table_name,
                                                             guint32 *count,
                                                             GError **error);
    gint                camel_db_count_deleted_message_info (CamelDB *cdb,
                                                             const gchar *table_name,
                                                             guint32 *count,
                                                             GError **error);
    gint                camel_db_count_total_message_info   (CamelDB *cdb,
                                                             const gchar *table_name,
                                                             guint32 *count,
                                                             GError **error);
    gint                camel_db_count_visible_message_info (CamelDB *cdb,
                                                             const gchar *table_name,
                                                             guint32 *count,
                                                             GError **error);
    gint                camel_db_count_visible_unread_message_info
                                                            (CamelDB *cdb,
                                                             const gchar *table_name,
                                                             guint32 *count,
                                                             GError **error);
    gint                camel_db_count_junk_not_deleted_message_info
                                                            (CamelDB *cdb,
                                                             const gchar *table_name,
                                                             guint32 *count,
                                                             GError **error);
    gint                camel_db_count_message_info         (CamelDB *cdb,
                                                             const gchar *query,
                                                             guint32 *count,
                                                             GError **error);
    void                camel_db_camel_mir_free             (CamelMIRecord *record);
    gint                camel_db_get_folder_uids            (CamelDB *db,
                                                             const gchar *folder_name,
                                                             const gchar *sort_by,
                                                             const gchar *collate,
                                                             GHashTable *hash,
                                                             GError **error);
    GPtrArray *         camel_db_get_folder_junk_uids       (CamelDB *db,
                                                             gchar *folder_name,
                                                             GError **error);
    GPtrArray *         camel_db_get_folder_deleted_uids    (CamelDB *db,
                                                             const gchar *folder_name,
                                                             GError **error);
    gchar *             camel_db_sqlize_string              (const gchar *string);
    void                camel_db_free_sqlized_string        (gchar *string);
    gchar *             camel_db_get_column_name            (const gchar *raw_name);
    gint                camel_db_set_collate                (CamelDB *cdb,
                                                             const gchar *col,
                                                             const gchar *collate,
                                                             CamelDBCollate func);
    gint                camel_db_start_in_memory_transactions
                                                            (CamelDB *cdb,
                                                             GError **error);
    gint                camel_db_flush_in_memory_transactions
                                                            (CamelDB *cdb,
                                                             const gchar *folder_name,
                                                             GError **error);
    GHashTable *        camel_db_get_folder_preview         (CamelDB *db,
                                                             const gchar *folder_name,
                                                             GError **error);
    gint                camel_db_write_preview_record       (CamelDB *db,
                                                             const gchar *folder_name,
                                                             const gchar *uid,
                                                             const gchar *msg,
                                                             GError **error);
    gint                camel_db_reset_folder_version       (CamelDB *cdb,
                                                             const gchar *folder_name,
                                                             gint reset_version,
                                                             GError **error);

## Description

## Details

### CAMEL_DB_FILE

    #define CAMEL_DB_FILE "folders.db"

Since 2.24

### CAMEL_DB_IN_MEMORY_TABLE

    #define CAMEL_DB_IN_MEMORY_TABLE "EVO_IN_meM_hAnDlE.temp"

Since 2.26

### CAMEL_DB_IN_MEMORY_DB

    #define CAMEL_DB_IN_MEMORY_DB "EVO_IN_meM_hAnDlE"

Since 2.26

### CAMEL_DB_IN_MEMORY_TABLE_LIMIT

    #define CAMEL_DB_IN_MEMORY_TABLE_LIMIT 100000

Since 2.26

### CAMEL_DB_FREE_CACHE_SIZE

    #define CAMEL_DB_FREE_CACHE_SIZE 2 * 1024 * 1024

Since 2.24

### CAMEL_DB_SLEEP_INTERVAL

    #define CAMEL_DB_SLEEP_INTERVAL 1*10*10

Since 2.24

### CAMEL_DB_RELEASE_SQLITE_MEMORY

    #define CAMEL_DB_RELEASE_SQLITE_MEMORY if(!g_getenv("CAMEL_SQLITE_FREE_CACHE")) sqlite3_release_memory(CAMEL_DB_FREE_CACHE_SIZE);

Since 2.24

### CAMEL_DB_USE_SHARED_CACHE

    #define CAMEL_DB_USE_SHARED_CACHE if(g_getenv("CAMEL_SQLITE_SHARED_CACHE")) sqlite3_enable_shared_cache(TRUE);

Since 2.24

### CamelDBCollate ()

    gint                (*CamelDBCollate)                   (gpointer Param1,
                                                             gint Param2,
                                                             gconstpointer Param3,
                                                             gint Param4,
                                                             gconstpointer Param5);

Since 2.24

### CamelDB

    typedef struct {
    	sqlite3 *db;
    	/* this lock has been replaced with a rw lock which sits inside priv.
    	 * This is currently unused. Keeping it, not to break the ABI */
    	GMutex *lock;
    	CamelDBPrivate *priv;
    } CamelDB;

Since 2.24

### CamelMIRecord

    typedef struct {
    	gchar *uid;
    	guint32 flags;
    	guint32 msg_type;
    	guint32 dirty;
    	gboolean read;
    	gboolean deleted;
    	gboolean replied;
    	gboolean important;
    	gboolean junk;
    	gboolean attachment;
    	guint32 size;
    	time_t dsent;
    	time_t dreceived;
    	gchar *subject;
    	gchar *from;
    	gchar *to;
    	gchar *cc;
    	gchar *mlist;
    	gchar *followup_flag;
    	gchar *followup_completed_on;
    	gchar *followup_due_by;
    	gchar *part;
    	gchar *labels;
    	gchar *usertags;
    	gchar *cinfo;
    	gchar *bdata;
    	gchar *bodystructure;
    } CamelMIRecord;

The extensive DB format, supporting basic searching and sorting.

gchar *`uid`; | Message UID
guint32 `flags`; | Camel Message info flags
guint32 `msg_type`; |
guint32 `dirty`; |
gboolean `read`; | boolean read status
gboolean `deleted`; | boolean deleted status
gboolean `replied`; | boolean replied status
gboolean `important`; | boolean important status
gboolean `junk`; | boolean junk status
gboolean `attachment`; | boolean attachment status
guint32 `size`; | size of the mail
time_t `dsent`; | date sent
time_t `dreceived`; | date received
gchar *`subject`; | subject of the mail
gchar *`from`; | sender
gchar *`to`; | recipient
gchar *`cc`; | CC members
gchar *`mlist`; | message list headers
gchar *`followup_flag`; | followup flag / also can be queried to see for followup or not
gchar *`followup_completed_on`; | completed date, can be used to see if completed
gchar *`followup_due_by`; | to see the due by date
gchar *`part`; | part / references / thread id
gchar *`labels`; | labels of mails also called as userflags
gchar *`usertags`; | composite string of user tags
gchar *`cinfo`; | content info string - composite string
gchar *`bdata`; | provider specific data
gchar *`bodystructure`; |

Since 2.24

### CamelFIRecord

    typedef struct {
    	gchar *folder_name;
    	guint32 version;
    	guint32 flags;
    	guint32 nextuid;
    	time_t time;
    	guint32 saved_count;
    	guint32 unread_count;
    	guint32 deleted_count;
    	guint32 junk_count;
    	guint32 visible_count;
    	guint32 jnd_count;  /* Junked not deleted */
    	gchar *bdata;
    } CamelFIRecord;

Since 2.24

### enum CamelDBKnownColumnNames

    typedef enum {
    	CAMEL_DB_COLUMN_UNKNOWN = -1,
    	CAMEL_DB_COLUMN_ATTACHMENT,
    	CAMEL_DB_COLUMN_BDATA,
    	CAMEL_DB_COLUMN_BODYSTRUCTURE,
    	CAMEL_DB_COLUMN_CINFO,
    	CAMEL_DB_COLUMN_DELETED,
    	CAMEL_DB_COLUMN_DELETED_COUNT,
    	CAMEL_DB_COLUMN_DRECEIVED,
    	CAMEL_DB_COLUMN_DSENT,
    	CAMEL_DB_COLUMN_FLAGS,
    	CAMEL_DB_COLUMN_FOLDER_NAME,
    	CAMEL_DB_COLUMN_FOLLOWUP_COMPLETED_ON,
    	CAMEL_DB_COLUMN_FOLLOWUP_DUE_BY,
    	CAMEL_DB_COLUMN_FOLLOWUP_FLAG,
    	CAMEL_DB_COLUMN_IMPORTANT,
    	CAMEL_DB_COLUMN_JND_COUNT,
    	CAMEL_DB_COLUMN_JUNK,
    	CAMEL_DB_COLUMN_JUNK_COUNT,
    	CAMEL_DB_COLUMN_LABELS,
    	CAMEL_DB_COLUMN_MAIL_CC,
    	CAMEL_DB_COLUMN_MAIL_FROM,
    	CAMEL_DB_COLUMN_MAIL_TO,
    	CAMEL_DB_COLUMN_MLIST,
    	CAMEL_DB_COLUMN_NEXTUID,
    	CAMEL_DB_COLUMN_PART,
    	CAMEL_DB_COLUMN_PREVIEW,
    	CAMEL_DB_COLUMN_READ,
    	CAMEL_DB_COLUMN_REPLIED,
    	CAMEL_DB_COLUMN_SAVED_COUNT,
    	CAMEL_DB_COLUMN_SIZE,
    	CAMEL_DB_COLUMN_SUBJECT,
    	CAMEL_DB_COLUMN_TIME,
    	CAMEL_DB_COLUMN_UID,
    	CAMEL_DB_COLUMN_UNREAD_COUNT,
    	CAMEL_DB_COLUMN_USERTAGS,
    	CAMEL_DB_COLUMN_VERSION,
    	CAMEL_DB_COLUMN_VISIBLE_COUNT,
    	CAMEL_DB_COLUMN_VUID
    } CamelDBKnownColumnNames;

Since 3.4

### camel_db_get_column_ident ()

    CamelDBKnownColumnNames camel_db_get_column_ident       (GHashTable **hash,
                                                             gint index,
                                                             gint ncols,
                                                             gchar **col_names);

Traverses column name from index `index` into an enum CamelDBKnownColumnNames value. The `col_names` contains `ncols` columns. First time this is called is created the `hash` from col_names indexes into the enum, and this is reused for every other call. The function expects that column names are returned always in the same order. When all rows are read the `hash` table can be freed with `g_hash_table_destroy()`.

Since 3.4

### CamelDBSelectCB ()

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

Since 2.24

### camel_db_open ()

    CamelDB *           camel_db_open                       (const gchar *path,
                                                             GError **error);

Since 2.24

### camel_db_clone ()

    CamelDB *           camel_db_clone                      (CamelDB *cdb,
                                                             GError **error);

Since 2.26

### camel_db_close ()

    void                camel_db_close                      (CamelDB *cdb);

Since 2.24

### camel_db_command ()

    gint                camel_db_command                    (CamelDB *cdb,
                                                             const gchar *stmt,
                                                             GError **error);

Since 2.24

### camel_db_transaction_command ()

    gint                camel_db_transaction_command        (CamelDB *cdb,
                                                             GList *qry_list,
                                                             GError **error);

Since 2.24

### camel_db_begin_transaction ()

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

Since 2.24

### camel_db_add_to_transaction ()

    gint                camel_db_add_to_transaction         (CamelDB *cdb,
                                                             const gchar *query,
                                                             GError **error);

Since 2.24

### camel_db_end_transaction ()

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

Since 2.24

### camel_db_abort_transaction ()

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

Since 2.24

### camel_db_clear_folder_summary ()

    gint                camel_db_clear_folder_summary       (CamelDB *cdb,
                                                             const gchar *folder,
                                                             GError **error);

Since 2.24

### camel_db_rename_folder ()

    gint                camel_db_rename_folder              (CamelDB *cdb,
                                                             const gchar *old_folder,
                                                             const gchar *new_folder,
                                                             GError **error);

Since 2.24

### camel_db_delete_folder ()

    gint                camel_db_delete_folder              (CamelDB *cdb,
                                                             const gchar *folder,
                                                             GError **error);

Since 2.24

### camel_db_delete_uid ()

    gint                camel_db_delete_uid                 (CamelDB *cdb,
                                                             const gchar *folder,
                                                             const gchar *uid,
                                                             GError **error);

Since 2.24

### camel_db_delete_uids ()

    gint                camel_db_delete_uids                (CamelDB *cdb,
                                                             const gchar *folder_name,
                                                             GList *uids,
                                                             GError **error);

Since 2.24

### camel_db_create_folders_table ()

    gint                camel_db_create_folders_table       (CamelDB *cdb,
                                                             GError **error);

Since 2.24

### camel_db_select ()

    gint                camel_db_select                     (CamelDB *cdb,
                                                             const gchar *stmt,
                                                             CamelDBSelectCB callback,
                                                             gpointer data,
                                                             GError **error);

Since 2.24

### camel_db_write_folder_info_record ()

    gint                camel_db_write_folder_info_record   (CamelDB *cdb,
                                                             CamelFIRecord *record,
                                                             GError **error);

Since 2.24

### camel_db_read_folder_info_record ()

    gint                camel_db_read_folder_info_record    (CamelDB *cdb,
                                                             const gchar *folder_name,
                                                             CamelFIRecord *record,
                                                             GError **error);

Since 2.24

### camel_db_prepare_message_info_table ()

    gint                camel_db_prepare_message_info_table (CamelDB *cdb,
                                                             const gchar *folder_name,
                                                             GError **error);

Since 2.24

### camel_db_write_message_info_record ()

    gint                camel_db_write_message_info_record  (CamelDB *cdb,
                                                             const gchar *folder_name,
                                                             CamelMIRecord *record,
                                                             GError **error);

Since 2.24

### camel_db_write_fresh_message_info_record ()

    gint                camel_db_write_fresh_message_info_record
                                                            (CamelDB *cdb,
                                                             const gchar *folder_name,
                                                             CamelMIRecord *record,
                                                             GError **error);

Since 2.26

### camel_db_read_message_info_records ()

    gint                camel_db_read_message_info_records  (CamelDB *cdb,
                                                             const gchar *folder_name,
                                                             gpointer p,
                                                             CamelDBSelectCB read_mir_callback,
                                                             GError **error);

Since 2.24

### camel_db_read_message_info_record_with_uid ()

    gint                camel_db_read_message_info_record_with_uid
                                                            (CamelDB *cdb,
                                                             const gchar *folder_name,
                                                             const gchar *uid,
                                                             gpointer p,
                                                             CamelDBSelectCB read_mir_callback,
                                                             GError **error);

Since 2.24

### camel_db_count_junk_message_info ()

    gint                camel_db_count_junk_message_info    (CamelDB *cdb,
                                                             const gchar *table_name,
                                                             guint32 *count,
                                                             GError **error);

Since 2.24

### camel_db_count_unread_message_info ()

    gint                camel_db_count_unread_message_info  (CamelDB *cdb,
                                                             const gchar *table_name,
                                                             guint32 *count,
                                                             GError **error);

Since 2.24

### camel_db_count_deleted_message_info ()

    gint                camel_db_count_deleted_message_info (CamelDB *cdb,
                                                             const gchar *table_name,
                                                             guint32 *count,
                                                             GError **error);

Since 2.24

### camel_db_count_total_message_info ()

    gint                camel_db_count_total_message_info   (CamelDB *cdb,
                                                             const gchar *table_name,
                                                             guint32 *count,
                                                             GError **error);

Since 2.24

### camel_db_count_visible_message_info ()

    gint                camel_db_count_visible_message_info (CamelDB *cdb,
                                                             const gchar *table_name,
                                                             guint32 *count,
                                                             GError **error);

Since 2.24

### camel_db_count_visible_unread_message_info ()

    gint                camel_db_count_visible_unread_message_info
                                                            (CamelDB *cdb,
                                                             const gchar *table_name,
                                                             guint32 *count,
                                                             GError **error);

Since 2.24

### camel_db_count_junk_not_deleted_message_info ()

    gint                camel_db_count_junk_not_deleted_message_info
                                                            (CamelDB *cdb,
                                                             const gchar *table_name,
                                                             guint32 *count,
                                                             GError **error);

### camel_db_count_message_info ()

    gint                camel_db_count_message_info         (CamelDB *cdb,
                                                             const gchar *query,
                                                             guint32 *count,
                                                             GError **error);

Since 2.26

### camel_db_camel_mir_free ()

    void                camel_db_camel_mir_free             (CamelMIRecord *record);

Since 2.24

### camel_db_get_folder_uids ()

    gint                camel_db_get_folder_uids            (CamelDB *db,
                                                             const gchar *folder_name,
                                                             const gchar *sort_by,
                                                             const gchar *collate,
                                                             GHashTable *hash,
                                                             GError **error);

Fills hash with uid->GUINT_TO_POINTER (flag)

Since 2.24

### camel_db_get_folder_junk_uids ()

    GPtrArray *         camel_db_get_folder_junk_uids       (CamelDB *db,
                                                             gchar *folder_name,
                                                             GError **error);

Since 2.24

### camel_db_get_folder_deleted_uids ()

    GPtrArray *         camel_db_get_folder_deleted_uids    (CamelDB *db,
                                                             const gchar *folder_name,
                                                             GError **error);

Since 2.24

### camel_db_sqlize_string ()

    gchar *             camel_db_sqlize_string              (const gchar *string);

Since 2.24

### camel_db_free_sqlized_string ()

    void                camel_db_free_sqlized_string        (gchar *string);

Since 2.24

### camel_db_get_column_name ()

    gchar *             camel_db_get_column_name            (const gchar *raw_name);

Since 2.24

### camel_db_set_collate ()

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

Since 2.24

### camel_db_start_in_memory_transactions ()

    gint                camel_db_start_in_memory_transactions
                                                            (CamelDB *cdb,
                                                             GError **error);

Since 2.26

### camel_db_flush_in_memory_transactions ()

    gint                camel_db_flush_in_memory_transactions
                                                            (CamelDB *cdb,
                                                             const gchar *folder_name,
                                                             GError **error);

Since 2.26

### camel_db_get_folder_preview ()

    GHashTable *        camel_db_get_folder_preview         (CamelDB *db,
                                                             const gchar *folder_name,
                                                             GError **error);

Since 2.28

### camel_db_write_preview_record ()

    gint                camel_db_write_preview_record       (CamelDB *db,
                                                             const gchar *folder_name,
                                                             const gchar *uid,
                                                             const gchar *msg,
                                                             GError **error);

Since 2.28

### camel_db_reset_folder_version ()

    gint                camel_db_reset_folder_version       (CamelDB *cdb,
                                                             const gchar *folder_name,
                                                             gint reset_version,
                                                             GError **error);

Since 2.28