CamelStore

## CamelStore CamelStore |

## Synopsis

    struct              CamelStore;
                        CamelFolderInfo;
    #define             CAMEL_FOLDER_NOSELECT
    #define             CAMEL_FOLDER_NOINFERIORS
    #define             CAMEL_FOLDER_CHILDREN
    #define             CAMEL_FOLDER_NOCHILDREN
    #define             CAMEL_FOLDER_SUBSCRIBED
    #define             CAMEL_FOLDER_VIRTUAL
    #define             CAMEL_FOLDER_SYSTEM
    #define             CAMEL_FOLDER_VTRASH
    #define             CAMEL_FOLDER_SHARED_TO_ME
    #define             CAMEL_FOLDER_SHARED_BY_ME
    #define             CAMEL_FOLDER_TYPE_MASK
    #define             CAMEL_FOLDER_TYPE_BIT
    #define             CAMEL_FOLDER_TYPE_NORMAL
    #define             CAMEL_FOLDER_TYPE_INBOX
    #define             CAMEL_FOLDER_TYPE_OUTBOX
    #define             CAMEL_FOLDER_TYPE_TRASH
    #define             CAMEL_FOLDER_TYPE_JUNK
    #define             CAMEL_FOLDER_TYPE_SENT
    #define             CAMEL_STORE_READ
    #define             CAMEL_STORE_WRITE
                        CamelRenameInfo;
    #define             CAMEL_STORE_SUBSCRIPTIONS
    #define             CAMEL_STORE_VTRASH
    #define             CAMEL_STORE_FILTER_INBOX
    #define             CAMEL_STORE_VJUNK
    #define             CAMEL_STORE_PROXY
    #define             CAMEL_STORE_IS_MIGRATING
    #define             CAMEL_STORE_FOLDER_CREATE
    #define             CAMEL_STORE_FOLDER_EXCL
    #define             CAMEL_STORE_FOLDER_BODY_INDEX
    #define             CAMEL_STORE_FOLDER_PRIVATE
    #define             CAMEL_STORE_FOLDER_CREATE_EXCL
    #define             CAMEL_STORE_FOLDER_INFO_FAST
    #define             CAMEL_STORE_FOLDER_INFO_RECURSIVE
    #define             CAMEL_STORE_FOLDER_INFO_SUBSCRIBED
    #define             CAMEL_STORE_FOLDER_INFO_NO_VIRTUAL
    #define             CAMEL_STORE_FOLDER_INFO_SUBSCRIPTION_LIST
    CamelFolder *       camel_store_get_folder              (CamelStore *store,
                                                             const gchar *folder_name,
                                                             guint32 flags,
                                                             CamelException *ex);
    CamelFolder *       camel_store_get_inbox               (CamelStore *store,
                                                             CamelException *ex);
    CamelFolder *       camel_store_get_trash               (CamelStore *store,
                                                             CamelException *ex);
    CamelFolder *       camel_store_get_junk                (CamelStore *store,
                                                             CamelException *ex);
    CamelFolderInfo *   camel_store_create_folder           (CamelStore *store,
                                                             const gchar *parent_name,
                                                             const gchar *folder_name,
                                                             CamelException *ex);
    void                camel_store_delete_folder           (CamelStore *store,
                                                             const gchar *folder_name,
                                                             CamelException *ex);
    void                camel_store_rename_folder           (CamelStore *store,
                                                             const gchar *old_namein,
                                                             const gchar *new_name,
                                                             CamelException *ex);
    void                camel_store_sync                    (CamelStore *store,
                                                             gint expunge,
                                                             CamelException *ex);
    CamelFolderInfo *   camel_store_get_folder_info         (CamelStore *store,
                                                             const gchar *top,
                                                             guint32 flags,
                                                             CamelException *ex);
    void                camel_store_free_folder_info        (CamelStore *store,
                                                             CamelFolderInfo *fi);
    void                camel_store_free_folder_info_full   (CamelStore *store,
                                                             CamelFolderInfo *fi);
    void                camel_store_free_folder_info_nop    (CamelStore *store,
                                                             CamelFolderInfo *fi);
    CamelFolderInfo *   camel_folder_info_new               (void);
    void                camel_folder_info_free              (CamelFolderInfo *fi);
    CamelFolderInfo *   camel_folder_info_build             (GPtrArray *folders,
                                                             const gchar *namespace,
                                                             gchar separator,
                                                             gboolean short_names);
    CamelFolderInfo *   camel_folder_info_clone             (CamelFolderInfo *fi);
    gboolean            camel_store_supports_subscriptions  (CamelStore *store);
    gboolean            camel_store_folder_subscribed       (CamelStore *store,
                                                             const gchar *folder_name);
    void                camel_store_subscribe_folder        (CamelStore *store,
                                                             const gchar *folder_name,
                                                             CamelException *ex);
    void                camel_store_unsubscribe_folder      (CamelStore *store,
                                                             const gchar *folder_name,
                                                             CamelException *ex);
    void                camel_store_noop                    (CamelStore *store,
                                                             CamelException *ex);
    gint                camel_store_folder_uri_equal        (CamelStore *store,
                                                             const gchar *uri0,
                                                             const gchar *uri1);
    gboolean            camel_store_can_refresh_folder      (CamelStore *store,
                                                             CamelFolderInfo *info,
                                                             CamelException *ex);
                        CamelISubscribe;
    gboolean            camel_isubscribe_subscribed         (CamelStore *store,
                                                             const gchar *name);
    void                camel_isubscribe_subscribe          (CamelStore *store,
                                                             const gchar *folder_name,
                                                             CamelException *ex);
    void                camel_isubscribe_unsubscribe        (CamelStore *store,
                                                             const gchar *folder_name,
                                                             CamelException *ex);

## Description

## Details

### struct CamelStore

    struct CamelStore {
    	CamelService parent_object;
    	struct _CamelStorePrivate *priv;

    	CamelObjectBag *folders;
    	struct _CamelDB *cdb_r;
    	struct _CamelDB *cdb_w;

    	guint32 flags;
    	guint32 mode;

    	/* Future ABI expansion */
    	gpointer later[4];
    };

### CamelFolderInfo

    typedef struct {
    	struct _CamelFolderInfo *next;
    	struct _CamelFolderInfo *parent;
    	struct _CamelFolderInfo *child;

    	gchar *uri;
    	gchar *name;
    	gchar *full_name;

    	guint32 flags;
    	gint32 unread;
    	gint32 total;
    } CamelFolderInfo;

### CAMEL_FOLDER_NOSELECT

    #define CAMEL_FOLDER_NOSELECT (1<<0)

### CAMEL_FOLDER_NOINFERIORS

    #define CAMEL_FOLDER_NOINFERIORS (1<<1)

### CAMEL_FOLDER_CHILDREN

    #define CAMEL_FOLDER_CHILDREN (1<<2)

### CAMEL_FOLDER_NOCHILDREN

    #define CAMEL_FOLDER_NOCHILDREN (1<<3)

### CAMEL_FOLDER_SUBSCRIBED

    #define CAMEL_FOLDER_SUBSCRIBED (1<<4)

### CAMEL_FOLDER_VIRTUAL

    #define CAMEL_FOLDER_VIRTUAL (1<<5)

### CAMEL_FOLDER_SYSTEM

    #define CAMEL_FOLDER_SYSTEM (1<<6)

### CAMEL_FOLDER_VTRASH

    #define CAMEL_FOLDER_VTRASH (1<<7)

### CAMEL_FOLDER_SHARED_TO_ME

    #define CAMEL_FOLDER_SHARED_TO_ME (1<<8)

### CAMEL_FOLDER_SHARED_BY_ME

    #define CAMEL_FOLDER_SHARED_BY_ME (1<<9)

### CAMEL_FOLDER_TYPE_MASK

    #define CAMEL_FOLDER_TYPE_MASK (7 << 10)

### CAMEL_FOLDER_TYPE_BIT

    #define CAMEL_FOLDER_TYPE_BIT (10)

### CAMEL_FOLDER_TYPE_NORMAL

    #define CAMEL_FOLDER_TYPE_NORMAL (0 << 10)

### CAMEL_FOLDER_TYPE_INBOX

    #define CAMEL_FOLDER_TYPE_INBOX (1 << 10)

### CAMEL_FOLDER_TYPE_OUTBOX

    #define CAMEL_FOLDER_TYPE_OUTBOX (2 << 10)

### CAMEL_FOLDER_TYPE_TRASH

    #define CAMEL_FOLDER_TYPE_TRASH (3 << 10)

### CAMEL_FOLDER_TYPE_JUNK

    #define CAMEL_FOLDER_TYPE_JUNK (4 << 10)

### CAMEL_FOLDER_TYPE_SENT

    #define CAMEL_FOLDER_TYPE_SENT (5 << 10)

### CAMEL_STORE_READ

    #define CAMEL_STORE_READ  (1 << 0)

### CAMEL_STORE_WRITE

    #define CAMEL_STORE_WRITE (1 << 1)

### CamelRenameInfo

    typedef struct {
    	gchar *old_base;
    	struct _CamelFolderInfo *new;
    } CamelRenameInfo;

### CAMEL_STORE_SUBSCRIPTIONS

    #define CAMEL_STORE_SUBSCRIPTIONS	(1 << 0)

### CAMEL_STORE_VTRASH

    #define CAMEL_STORE_VTRASH		(1 << 1)

### CAMEL_STORE_FILTER_INBOX

    #define CAMEL_STORE_FILTER_INBOX	(1 << 2)

### CAMEL_STORE_VJUNK

    #define CAMEL_STORE_VJUNK		(1 << 3)

### CAMEL_STORE_PROXY

    #define CAMEL_STORE_PROXY		(1 << 4)

### CAMEL_STORE_IS_MIGRATING

    #define CAMEL_STORE_IS_MIGRATING (1 << 5)

### CAMEL_STORE_FOLDER_CREATE

    #define CAMEL_STORE_FOLDER_CREATE (1<<0)

### CAMEL_STORE_FOLDER_EXCL

    #define CAMEL_STORE_FOLDER_EXCL (1<<1)

### CAMEL_STORE_FOLDER_BODY_INDEX

    #define CAMEL_STORE_FOLDER_BODY_INDEX (1<<2)

### CAMEL_STORE_FOLDER_PRIVATE

    #define CAMEL_STORE_FOLDER_PRIVATE (1<<3) /* a private folder, that shouldn't show up in unmatched/folder info's, etc */

### CAMEL_STORE_FOLDER_CREATE_EXCL

    #define CAMEL_STORE_FOLDER_CREATE_EXCL (CAMEL_STORE_FOLDER_CREATE | CAMEL_STORE_FOLDER_EXCL)

### CAMEL_STORE_FOLDER_INFO_FAST

    #define CAMEL_STORE_FOLDER_INFO_FAST       (1 << 0)

### Warning

`CAMEL_STORE_FOLDER_INFO_FAST` is deprecated and should not be used in newly-written code.

### CAMEL_STORE_FOLDER_INFO_RECURSIVE

    #define CAMEL_STORE_FOLDER_INFO_RECURSIVE  (1 << 1)

### CAMEL_STORE_FOLDER_INFO_SUBSCRIBED

    #define CAMEL_STORE_FOLDER_INFO_SUBSCRIBED (1 << 2)

### CAMEL_STORE_FOLDER_INFO_NO_VIRTUAL

    #define CAMEL_STORE_FOLDER_INFO_NO_VIRTUAL (1 << 3)  /* don't include vTrash/vJunk folders */

### CAMEL_STORE_FOLDER_INFO_SUBSCRIPTION_LIST

    #define CAMEL_STORE_FOLDER_INFO_SUBSCRIPTION_LIST (1 << 4)

### camel_store_get_folder ()

    CamelFolder *       camel_store_get_folder              (CamelStore *store,
                                                             const gchar *folder_name,
                                                             guint32 flags,
                                                             CamelException *ex);

Get a specific folder object from the store by name.

`store` : | a CamelStore object
`folder_name` : | name of the folder to get
`flags` : | folder flags (create, save body index, etc)
`ex` : | a CamelException
Returns : | the folder corresponding to the path `folder_name` or `NULL`.

### camel_store_get_inbox ()

    CamelFolder *       camel_store_get_inbox               (CamelStore *store,
                                                             CamelException *ex);

`store` : | a CamelStore object
`ex` : | a CamelException
Returns : | the folder in the store into which new mail is delivered, or `NULL` if no such folder exists.

### camel_store_get_trash ()

    CamelFolder *       camel_store_get_trash               (CamelStore *store,
                                                             CamelException *ex);

`store` : | a CamelStore object
`ex` : | a CamelException
Returns : | the folder in the store into which trash is delivered, or `NULL` if no such folder exists.

### camel_store_get_junk ()

    CamelFolder *       camel_store_get_junk                (CamelStore *store,
                                                             CamelException *ex);

`store` : | a CamelStore object
`ex` : | a CamelException
Returns : | the folder in the store into which junk is delivered, or `NULL` if no such folder exists.

### camel_store_create_folder ()

    CamelFolderInfo *   camel_store_create_folder           (CamelStore *store,
                                                             const gchar *parent_name,
                                                             const gchar *folder_name,
                                                             CamelException *ex);

Creates a new folder as a child of an existing folder. `parent_name` can be `NULL` to create a new top-level folder.

`store` : | a CamelStore object
`parent_name` : | name of the new folder's parent, or `NULL`
`folder_name` : | name of the folder to create
`ex` : | a CamelException
Returns : | info about the created folder, which the caller must free with camel_store_free_folder_info, or `NULL`.

### camel_store_delete_folder ()

    void                camel_store_delete_folder           (CamelStore *store,
                                                             const gchar *folder_name,
                                                             CamelException *ex);

Deletes the named folder. The folder must be empty.

`store` : | a CamelStore object
`folder_name` : | name of the folder to delete
`ex` : | a CamelException

### camel_store_rename_folder ()

    void                camel_store_rename_folder           (CamelStore *store,
                                                             const gchar *old_namein,
                                                             const gchar *new_name,
                                                             CamelException *ex);

Rename a named folder to a new name.

`store` : | a CamelStore object
`old_namein` : | the current name of the folder
`new_name` : | the new name of the folder
`ex` : | a CamelException

### camel_store_sync ()

    void                camel_store_sync                    (CamelStore *store,
                                                             gint expunge,
                                                             CamelException *ex);

Syncs any changes that have been made to the store object and its folders with the real store.

`store` : | a CamelStore object
`expunge` : | `TRUE` if an expunge should be done after sync or `FALSE` otherwise
`ex` : | a CamelException

### camel_store_get_folder_info ()

    CamelFolderInfo *   camel_store_get_folder_info         (CamelStore *store,
                                                             const gchar *top,
                                                             guint32 flags,
                                                             CamelException *ex);

This fetches information about the folder structure of `store`, starting with `top`, and returns a tree of CamelFolderInfo structures. If `flags` includes CAMEL_STORE_FOLDER_INFO_SUBSCRIBED, only subscribed folders will be listed. If the store doesn't support subscriptions, then it will list all folders. If `flags` includes CAMEL_STORE_FOLDER_INFO_RECURSIVE, the returned tree will include all levels of hierarchy below `top`. If not, it will only include the immediate subfolders of `top`. If `flags` includes CAMEL_STORE_FOLDER_INFO_FAST, the unread_message_count fields of some or all of the structures may be set to `-1`, if the store cannot determine that information quickly. If `flags` includes CAMEL_STORE_FOLDER_INFO_NO_VIRTUAL, don't include special virtual folders (such as vTrash or vJunk).

The CAMEL_STORE_FOLDER_INFO_FAST flag should be considered deprecated; most backends will behave the same whether it is supplied or not. The only guaranteed way to get updated folder counts is to both open the folder and invoke `refresh_info()` it.

`store` : | a CamelStore object
`top` : | the name of the folder to start from
`flags` : | various CAMEL_STORE_FOLDER_INFO_* flags to control behavior
`ex` : | a CamelException
Returns : | a CamelFolderInfo tree, which must be freed with camel_store_free_folder_info, or `NULL`.

### camel_store_free_folder_info ()

    void                camel_store_free_folder_info        (CamelStore *store,
                                                             CamelFolderInfo *fi);

Frees the data returned by camel_store_get_folder_info. If `fi` is `NULL`, nothing is done, the routine simply returns.

`store` : | a CamelStore object
`fi` : | a CamelFolderInfo as gotten via camel_store_get_folder_info

### camel_store_free_folder_info_full ()

    void                camel_store_free_folder_info_full   (CamelStore *store,
                                                             CamelFolderInfo *fi);

An implementation for "free_folder_info". Frees all of the data.

`store` : | a CamelStore object
`fi` : | a CamelFolderInfo as gotten via camel_store_get_folder_info

### camel_store_free_folder_info_nop ()

    void                camel_store_free_folder_info_nop    (CamelStore *store,
                                                             CamelFolderInfo *fi);

An implementation for "free_folder_info". Does nothing.

`store` : | a CamelStore object
`fi` : | a CamelFolderInfo as gotten via camel_store_get_folder_info

### camel_folder_info_new ()

    CamelFolderInfo *   camel_folder_info_new               (void);

Returns : | a new empty CamelFolderInfo instance

### camel_folder_info_free ()

    void                camel_folder_info_free              (CamelFolderInfo *fi);

Frees `fi`.

`fi` : | a CamelFolderInfo

### camel_folder_info_build ()

    CamelFolderInfo *   camel_folder_info_build             (GPtrArray *folders,
                                                             const gchar *namespace,
                                                             gchar separator,
                                                             gboolean short_names);

### Warning

`camel_folder_info_build` is deprecated and should not be used in newly-written code.

This takes an array of folders and attaches them together according to the hierarchy described by their full_names and `separator`. If `namespace` is non-`NULL`, then it will be ignored as a full_name prefix, for purposes of comparison. If necessary, camel_folder_info_build will create additional CamelFolderInfo with `NULL` urls to fill in gaps in the tree. The value of `short_names` is used in constructing the names of these intermediate folders.

NOTE: This is deprected, do not use this. FIXME: remove this/move it to imap, which is the only user of it now.

`folders` : | an array of CamelFolderInfo
`namespace` : | an ignorable prefix on the folder names
`separator` : | the hieararchy separator character
`short_names` : | `TRUE` if the (short) name of a folder is the part after the last `separator` in the full name. `FALSE` if it is the full name.
Returns : | the top level of the tree of linked folder info.

### camel_folder_info_clone ()

    CamelFolderInfo *   camel_folder_info_clone             (CamelFolderInfo *fi);

Clones `fi` recursively.

`fi` : | a CamelFolderInfo
Returns : | the cloned CamelFolderInfo tree.

### camel_store_supports_subscriptions ()

    gboolean            camel_store_supports_subscriptions  (CamelStore *store);

Get whether or not `store` supports subscriptions to folders.

`store` : | a CamelStore object
Returns : | `TRUE` if folder subscriptions are supported or `FALSE` otherwise

### camel_store_folder_subscribed ()

    gboolean            camel_store_folder_subscribed       (CamelStore *store,
                                                             const gchar *folder_name);

Find out if a folder has been subscribed to.

`store` : | a CamelStore object
`folder_name` : | full path of the folder
Returns : | `TRUE` if the folder has been subscribed to or `FALSE` otherwise

### camel_store_subscribe_folder ()

    void                camel_store_subscribe_folder        (CamelStore *store,
                                                             const gchar *folder_name,
                                                             CamelException *ex);

Subscribe to the folder described by `folder_name`.

`store` : | a CamelStore object
`folder_name` : | full path of the folder
`ex` : | a CamelException

### camel_store_unsubscribe_folder ()

    void                camel_store_unsubscribe_folder      (CamelStore *store,
                                                             const gchar *folder_name,
                                                             CamelException *ex);

Unsubscribe from the folder described by `folder_name`.

`store` : | a CamelStore object
`folder_name` : | full path of the folder
`ex` : | a CamelException

### camel_store_noop ()

    void                camel_store_noop                    (CamelStore *store,
                                                             CamelException *ex);

Pings `store` so that its connection doesn't timeout.

`store` : | a CamelStore object
`ex` : | a CamelException

### camel_store_folder_uri_equal ()

    gint                camel_store_folder_uri_equal        (CamelStore *store,
                                                             const gchar *uri0,
                                                             const gchar *uri1);

Compares 2 folder uris to check that they are equal.

`store` : | a CamelStore object
`uri0` : | a folder uri
`uri1` : | another folder uri
Returns : | `TRUE` if they are equal or `FALSE` otherwise

### camel_store_can_refresh_folder ()

    gboolean            camel_store_can_refresh_folder      (CamelStore *store,
                                                             CamelFolderInfo *info,
                                                             CamelException *ex);

Returns if this folder (param info) should be checked for new mail or not. It should not look into sub infos (info->child) or next infos, it should return value only for the actual folder info. Default behavior is that all Inbox folders are intended to be refreshed.

`store` : | a CamelStore
`info` : | a CamelFolderInfo
`ex` : | a CamelException
Returns : | whether folder should be checked for new mails

### CamelISubscribe

    typedef struct {
    	CamelInterface iface;

    	gboolean (*subscribed)(CamelStore *store, const gchar *folder_name);
    	void (*subscribe)(CamelStore *store, const gchar *folder_name, CamelException *ex);
    	void (*unsubscribe)(CamelStore *store, const gchar *folder_name, CamelException *ex);
    } CamelISubscribe;

### Warning

`CamelISubscribe` is deprecated and should not be used in newly-written code.

### camel_isubscribe_subscribed ()

    gboolean            camel_isubscribe_subscribed         (CamelStore *store,
                                                             const gchar *name);

### Warning

`camel_isubscribe_subscribed` is deprecated and should not be used in newly-written code.

`store` : |
`name` : |
Returns : |

### camel_isubscribe_subscribe ()

    void                camel_isubscribe_subscribe          (CamelStore *store,
                                                             const gchar *folder_name,
                                                             CamelException *ex);

### Warning

`camel_isubscribe_subscribe` is deprecated and should not be used in newly-written code.

`store` : |
`folder_name` : |
`ex` : |

### camel_isubscribe_unsubscribe ()

    void                camel_isubscribe_unsubscribe        (CamelStore *store,
                                                             const gchar *folder_name,
                                                             CamelException *ex);

### Warning

`camel_isubscribe_unsubscribe` is deprecated and should not be used in newly-written code.

`store` : |
`folder_name` : |
`ex` : |