CamelStoreDB: Camel Reference Manual

## CamelStoreDB CamelStoreDB — a CamelStore database |

## Functions

void | camel_store_db_folder_record_clear ()
void | camel_store_db_message_record_clear ()
gboolean | (*CamelStoreDBReadMessagesFunc) ()
CamelStoreDB * | camel_store_db_new ()
gint | camel_store_db_get_int_key ()
gboolean | camel_store_db_set_int_key ()
gchar * | camel_store_db_dup_string_key ()
gboolean | camel_store_db_set_string_key ()
gboolean | camel_store_db_write_folder ()
gboolean | camel_store_db_read_folder ()
guint32 | camel_store_db_get_folder_id ()
gboolean | camel_store_db_rename_folder ()
gboolean | camel_store_db_delete_folder ()
gboolean | camel_store_db_clear_folder ()
gboolean | camel_store_db_write_message ()
gboolean | camel_store_db_read_message ()
gboolean | camel_store_db_read_messages ()
gboolean | camel_store_db_delete_message ()
gboolean | camel_store_db_delete_messages ()
gboolean | camel_store_db_count_messages ()
GPtrArray * | camel_store_db_dup_junk_uids ()
GPtrArray * | camel_store_db_dup_deleted_uids ()
const gchar * | camel_store_db_util_get_column_for_header_name ()

## Types and Values

| CamelStoreDBFolderRecord
| CamelStoreDBMessageRecord
#define | CAMEL_STORE_DB_FILE
struct | CamelStoreDB

## Object Hierarchy

        GObject
        ╰── CamelDB
            ╰── CamelStoreDB

## Includes

    #include <camel/camel.h>

## Description

The CamelStoreDB is a descendant of the CamelDB, which takes care of the save of the message information in an internal database.

## Functions

### camel_store_db_folder_record_clear ()

    void
    camel_store_db_folder_record_clear (CamelStoreDBFolderRecord *self);

Frees dynamically allocated data in the `self` , but not the `self` itself, and sets all members to zeros or equivalent. Does nothing when `self` is `NULL`. It can be called on the structure passed to the `camel_store_db_read_folder()`.

#### Parameters

self | a CamelStoreDBFolderRecord. | [nullable]

Since: 3.58

### camel_store_db_message_record_clear ()

    void
    camel_store_db_message_record_clear (CamelStoreDBMessageRecord *self);

Frees dynamically allocated data in the `self` , but not the `self` itself, and sets all members to zeros or equivalent. Does nothing when `self` is `NULL`. It can be called on the structure passed to the `camel_store_db_read_message()`.

#### Parameters

self | a CamelStoreDBFolderRecord |

Since: 3.58

### CamelStoreDBReadMessagesFunc ()

    gboolean
    (*CamelStoreDBReadMessagesFunc) (CamelStoreDB *storedb,
                                     const CamelStoreDBMessageRecord *record,
                                     gpointer user_data);

A callback called in the `camel_store_db_read_messages()` for each read message information. The members of the `record` are valid only in time of the callback being called.

#### Parameters

storedb | a CamelStoreDB |
record | a CamelStoreDBMessageRecord which had been read |
user_data | callback user data |

#### Returns

`TRUE` to continue, `FALSE` to stop further reading

Since: 3.58

### camel_store_db_new ()

    CamelStoreDB *
    camel_store_db_new (const gchar *filename,
                        GCancellable *cancellable,
                        GError **error);

Creates a new CamelStoreDB instance, which uses `filename` as its storage.

It also migrates existing data, if needed, providing feedback through the `cancellable` , if it's a CamelOperation instance.

#### Parameters

filename | a file name of the database to use |
cancellable | a GCancellable, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

a new CamelStoreDB, or `NULL` on error.

[transfer full]

Since: 3.58

### camel_store_db_get_int_key ()

    gint
    camel_store_db_get_int_key (CamelStoreDB *self,
                                const gchar *key,
                                gint def_value);

Reads an integer value for the `key` . If such does not exists, the `def_value` is returned.

#### Parameters

self | a CamelStoreDB |
key | a user key to read |
def_value | a default value to return, when the key not stored yet |

#### Returns

an integer value of the `key` , or `def_value` when does not exist or any other error occurred

See also `camel_store_db_set_int_key()`, `camel_store_db_dup_string_key()`

Since: 3.58

### camel_store_db_set_int_key ()

    gboolean
    camel_store_db_set_int_key (CamelStoreDB *self,
                                const gchar *key,
                                gint value,
                                GError **error);

Sets an integer value for the `key` to `value` .

#### Parameters

self | a CamelStoreDB |
key | a user key to set |
value | a value to set |
error | a return location for a GError, or `NULL` |

#### Returns

whether succeeded

See also `camel_store_db_get_int_key()`, `camel_store_db_set_string_key()`

Since: 3.58

### camel_store_db_dup_string_key ()

    gchar *
    camel_store_db_dup_string_key (CamelStoreDB *self,
                                   const gchar *key);

Reads a string value for the `key` . If such does not exists, the `NULL` is returned.

#### Parameters

self | a CamelStoreDB |
key | a user key to read |

#### Returns

a string value of the `key` , or `NULL` when does not exist or any other error occurred

See also `camel_store_db_set_string_key()`, `camel_store_db_get_int_key()`.

[transfer full][nullable]

Since: 3.58

### camel_store_db_set_string_key ()

    gboolean
    camel_store_db_set_string_key (CamelStoreDB *self,
                                   const gchar *key,
                                   const gchar *value,
                                   GError **error);

Sets a string value for the `key` to `value` .

#### Parameters

self | a CamelStoreDB |
key | a user key to set |
value | a value to set |
error | a return location for a GError, or `NULL` |

#### Returns

whether succeeded

See also `camel_store_db_dup_string_key()`, `camel_store_db_set_int_key()`

Since: 3.58

### camel_store_db_write_folder ()

    gboolean
    camel_store_db_write_folder (CamelStoreDB *self,
                                 const gchar *folder_name,
                                 const CamelStoreDBFolderRecord *record,
                                 GError **error);

Writes information about a folder as set in the `record` . The "folder_id" member of the `record` is ignored, the same as the "folder_name" member, the folder is identified by the `folder_name` argument.

#### Parameters

self | a CamelStoreDB |
folder_name | name of the folder to write the record to |
record | an CamelStoreDBFolderRecord |
error | a return location for a GError, or `NULL` |

#### Returns

whether succeeded

Since: 3.58

### camel_store_db_read_folder ()

    gboolean
    camel_store_db_read_folder (CamelStoreDB *self,
                                const gchar *folder_name,
                                CamelStoreDBFolderRecord *out_record,
                                GError **error);

Reads information about a folder named `folder_name` , previously stored by the `camel_store_db_write_folder()`. The data in the `out_record` should be cleared by the `camel_store_db_folder_record_clear()`, when no longer needed. The function returns success also when the folder information was not saved yet. It can be checked by the folder_id value, which is never zero for those existing tables.

#### Parameters

self | a CamelStoreDB |
folder_name | name of the folder to read the record for |
out_record | a CamelStoreDBFolderRecord to read the values to. | [out caller-allocates]
error | a return location for a GError, or `NULL` |

#### Returns

whether succeeded with the read, but check the non-zero-ness of the folder_id member of the `out_record` to recognize whether it was found

Since: 3.58

### camel_store_db_get_folder_id ()

    guint32
    camel_store_db_get_folder_id (CamelStoreDB *self,
                                  const gchar *folder_name);

Gets ID of a folder named `folder_name` .

#### Parameters

self | a CamelStoreDB |
folder_name | a folder name |

#### Returns

ID of a folder named `folder_name` , 0 when not found

Since: 3.58

### camel_store_db_rename_folder ()

    gboolean
    camel_store_db_rename_folder (CamelStoreDB *self,
                                  const gchar *old_folder_name,
                                  const gchar *new_folder_name,
                                  GError **error);

Renames folder `old_folder_name` to `new_folder_name` . Returns failure and sets `G_IO_ERROR_NOT_FOUND` error when the `old_folder_name` does not exist, and `G_IO_ERROR_EXISTS`, when the `new_folder_name` already exists.

#### Parameters

self | a CamelStoreDB |
old_folder_name | an existing folder name |
new_folder_name | a folder name to rename to |
error | a return location for a GError, or `NULL` |

#### Returns

whether succeeded

Since: 3.58

### camel_store_db_delete_folder ()

    gboolean
    camel_store_db_delete_folder (CamelStoreDB *self,
                                  const gchar *folder_name,
                                  GError **error);

Deletes all information about the `folder_name` . It does nothing when the folder does not exist.

#### Parameters

self | a CamelStoreDB |
folder_name | a folder name |
error | a return location for a GError, or `NULL` |

#### Returns

whether succeeded

Since: 3.58

### camel_store_db_clear_folder ()

    gboolean
    camel_store_db_clear_folder (CamelStoreDB *self,
                                 const gchar *folder_name,
                                 GError **error);

Clears content of the `folder_name` . It does nothing when the folder does not exist.

#### Parameters

self | a CamelStoreDB |
folder_name | a folder name |
error | a return location for a GError, or `NULL` |

#### Returns

whether succeeded

Since: 3.58

### camel_store_db_write_message ()

    gboolean
    camel_store_db_write_message (CamelStoreDB *self,
                                  const gchar *folder_name,
                                  const CamelStoreDBMessageRecord *record,
                                  GError **error);

Writes information about a single message into the `self` . The message in the `record` is identified by the `folder_name` argument and the "uid" member of the structure. The "folder_id" member of the `record` is ignored.

#### Parameters

self | a CamelStoreDB |
folder_name | a folder name |
record | a CamelStoreDBMessageRecord |
error | a return location for a GError, or `NULL` |

#### Returns

whether succeeded

Since: 3.58

### camel_store_db_read_message ()

    gboolean
    camel_store_db_read_message (CamelStoreDB *self,
                                 const gchar *folder_name,
                                 const gchar *uid,
                                 CamelStoreDBMessageRecord *out_record,
                                 GError **error);

Reads information about a single message stored in the `self` . The message in the `out_record` is identified by the folder ID and the UID members of the structure.

Call `camel_store_db_message_record_clear()` on the `out_record` structure to clear dynamically allocated memory in it.

See also `camel_store_db_read_messages()`.

#### Parameters

self | a CamelStoreDB |
folder_name | a folder name |
uid | message UID |
out_record | a CamelStoreDBMessageRecord to read the information to. | [out caller-allocates]
error | a return location for a GError, or `NULL` |

#### Returns

whether succeeded

Since: 3.58

### camel_store_db_read_messages ()

    gboolean
    camel_store_db_read_messages (CamelStoreDB *self,
                                  const gchar *folder_name,
                                  CamelStoreDBReadMessagesFunc func,
                                  gpointer user_data,
                                  GError **error);

Reads information about all messages for the folder `folder_name` and calls the `func` with its `user_data` for each such message information.

See also `camel_store_db_read_message()`.

#### Parameters

self | a CamelStoreDB |
folder_name | a folder name to read the data from |
func | a CamelStoreDBReadMessagesFunc to be called. | [scope call][closure user_data]
user_data | user data for the `func` |
error | a return location for a GError, or `NULL` |

#### Returns

whether succeeded

Since: 3.58

### camel_store_db_delete_message ()

    gboolean
    camel_store_db_delete_message (CamelStoreDB *self,
                                   const gchar *folder_name,
                                   const gchar *uid,
                                   GError **error);

Deletes single message with UID `uid` from folder `folder_name` . It's okay when such `uid` does not exist, but the folder is required to exist.

See also `camel_store_db_delete_messages()`.

#### Parameters

self | a CamelStoreDB |
folder_name | a folder name |
uid | message UID |
error | a return location for a GError, or `NULL` |

#### Returns

whether succeeded

Since: 3.58

### camel_store_db_delete_messages ()

    gboolean
    camel_store_db_delete_messages (CamelStoreDB *self,
                                    const gchar *folder_name,
                                    GPtrArray *uids,
                                    GError **error);

Deletes multiple messages with UID `uids` from folder `folder_name` . It's okay when such `uids` do not exist, but the folder is required to exist.

See also `camel_store_db_delete_message()`.

#### Parameters

self | a CamelStoreDB |
folder_name | a folder name |
uids | a GPtrArray of strings with message UID-s. | [element-type utf8]
error | a return location for a GError, or `NULL` |

#### Returns

whether succeeded

Since: 3.58

### camel_store_db_count_messages ()

    gboolean
    camel_store_db_count_messages (CamelStoreDB *self,
                                   const gchar *folder_name,
                                   CamelStoreDBCountKind kind,
                                   guint32 *out_count,
                                   GError **error);

Counts `kind` messages in folder `folder_name` .

#### Parameters

self | a CamelStoreDB |
folder_name | a folder name |
kind | a CamelStoreDBCountKind |
out_count | a return location to store the count to. | [out]
error | a return location for a GError, or `NULL` |

#### Returns

whether succeeded

Since: 3.58

### camel_store_db_dup_junk_uids ()

    GPtrArray *
    camel_store_db_dup_junk_uids (CamelStoreDB *self,
                                  const gchar *folder_name,
                                  GError **error);

Gets junk message UID-s in folder `folder_name` . Free the returned array with `g_ptr_array_unref()`, when no longer needed.

#### Parameters

self | a CamelStoreDB |
folder_name | a folder name |
error | a return location for a GError, or `NULL` |

#### Returns

a GPtrArray of message UID-s in folder `folder_name` , which are marked as junk, or `NULL` on error.

[transfer container][element-type utf8]

Since: 3.58

### camel_store_db_dup_deleted_uids ()

    GPtrArray *
    camel_store_db_dup_deleted_uids (CamelStoreDB *self,
                                     const gchar *folder_name,
                                     GError **error);

Gets deleted message UID-s in folder `folder_name` . Free the returned array with `g_ptr_array_unref()`, when no longer needed.

#### Parameters

self | a CamelStoreDB |
folder_name | a folder name |
error | a return location for a GError, or `NULL` |

#### Returns

a GPtrArray of message UID-s in folder `folder_name` , which are marked as deleted, or `NULL` on error.

[transfer container][element-type utf8]

Since: 3.58

### camel_store_db_util_get_column_for_header_name ()

    const gchar *
    camel_store_db_util_get_column_for_header_name
                                   (const gchar *header_name);

Gets a corresponding messages table column name for the `header_name` .

#### Parameters

header_name | name of a header to get a column for |

#### Returns

corresponding messages table column name for the `header_name` , or `NULL`, when the `header_name` does not have a corresponding column name in the messages table.

[nullable]

Since: 3.58

## Types and Values

### CamelStoreDBFolderRecord

    typedef struct {
    	gchar *folder_name;
    	guint32 version;
    	guint32 flags;
    	guint32 nextuid;
    	gint64 timestamp;
    	guint32 saved_count;
    	guint32 unread_count;
    	guint32 deleted_count;
    	guint32 junk_count;
    	guint32 visible_count;
    	guint32 jnd_count;  /* Junked not deleted */
    	gchar *bdata;
    	guint32 folder_id;
    } CamelStoreDBFolderRecord;

A folder record, with values stored in a CamelStoreDB.

#### Members

gchar *`folder_name`; | name of the folder |
guint32 `version`; | version of the saved information |
guint32 `flags`; | folder flags |
guint32 `nextuid`; | next free uid |
gint64 `timestamp`; | timestamp of the summary |
guint32 `saved_count`; | count of all messages |
guint32 `unread_count`; | count of unread messages |
guint32 `deleted_count`; | count of deleted messages |
guint32 `junk_count`; | count of junk messages |
guint32 `visible_count`; | count of visible (not deleted and not junk) messages |
guint32 `jnd_count`; | count of junk and not deleted messages |
gchar *`bdata`; | custom data of the CamelFolderSummary descendants |
guint32 `folder_id`; | ID of the folder |

Since: 3.58

### CamelStoreDBMessageRecord

    typedef struct {
    	guint32 folder_id;
    	const gchar *uid; /* stored in the string pool */
    	guint32 flags;
    	guint32 msg_type;
    	guint32 dirty;
    	guint32 size;
    	gint64 dsent; /* time_t */
    	gint64 dreceived; /* time_t */
    	const gchar *subject; /* stored in the string pool */
    	const gchar *from; /* stored in the string pool */
    	const gchar *to; /* stored in the string pool */
    	const gchar *cc; /* stored in the string pool */
    	const gchar *mlist; /* stored in the string pool */
    	gchar *part;
    	gchar *labels;
    	gchar *usertags;
    	gchar *cinfo;
    	gchar *bdata;
    	gchar *userheaders;
    	gchar *preview;
    } CamelStoreDBMessageRecord;

A message record, with values stored in a CamelStoreDB.

#### Members

guint32 `folder_id`; | ID of the folder the message belongs to |
const gchar *`uid`; | Message UID |
guint32 `flags`; | Camel Message info flags |
guint32 `msg_type`; | unused |
guint32 `dirty`; | whether the message info requires upload to the server; it corresponds to CAMEL_MESSAGE_FOLDER_FLAGGED |
guint32 `size`; | size of the mail |
gint64 `dsent`; | date sent |
gint64 `dreceived`; | date received |
const gchar *`subject`; | subject of the mail |
const gchar *`from`; | sender |
const gchar *`to`; | recipient |
const gchar *`cc`; | CC members |
const gchar *`mlist`; | message list headers |
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 *`userheaders`; | value for user-defined message headers |
gchar *`preview`; | message body preview |

Since: 3.58

### CAMEL_STORE_DB_FILE

    #define CAMEL_STORE_DB_FILE "folders.db"

File name used by the CamelStore for the CamelStoreDB.

Since: 3.58

### struct CamelStoreDB

    struct CamelStoreDB;

Since: 3.58