CamelStoreDB

CamelStoreDB — a CamelStore database

Functions

Types and Values

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

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

 

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

 

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