## CamelStore

CamelStore

## Synopsis

                        CamelStore;
    #define             CAMEL_STORE_ERROR
    enum                CamelStoreError;
    #define             CAMEL_FOLDER_TYPE_MASK
    #define             CAMEL_FOLDER_TYPE_BIT
    enum                CamelFolderInfoFlags;
                        CamelFolderInfo;
    enum                CamelStoreFlags;
    enum                CamelStorePermissionFlags;
    enum                CamelStoreGetFolderFlags;
    #define             CAMEL_STORE_FOLDER_CREATE_EXCL
    enum                CamelStoreGetFolderInfoFlags;
    void                camel_store_folder_created          (CamelStore *store,
                                                             CamelFolderInfo *folder_info);
    void                camel_store_folder_deleted          (CamelStore *store,
                                                             CamelFolderInfo *folder_info);
    void                camel_store_folder_opened           (CamelStore *store,
                                                             CamelFolder *folder);
    void                camel_store_folder_renamed          (CamelStore *store,
                                                             const gchar *old_name,
                                                             CamelFolderInfo *folder_info);
    void                camel_store_folder_subscribed       (CamelStore *store,
                                                             CamelFolderInfo *folder_info);
    void                camel_store_folder_unsubscribed     (CamelStore *store,
                                                             CamelFolderInfo *folder_info);
    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_is_subscribed    (CamelStore *store,
                                                             const gchar *folder_name);
    gint                camel_store_folder_uri_equal        (CamelStore *store,
                                                             const gchar *uri0,
                                                             const gchar *uri1);
    gboolean            camel_store_can_refresh_folder      (CamelStore *store,
                                                             CamelFolderInfo *info,
                                                             GError **error);
    enum                CamelStoreLock;
    void                camel_store_lock                    (CamelStore *store,
                                                             CamelStoreLock lock);
    void                camel_store_unlock                  (CamelStore *store,
                                                             CamelStoreLock lock);
    CamelFolder *       camel_store_get_folder_sync         (CamelStore *store,
                                                             const gchar *folder_name,
                                                             CamelStoreGetFolderFlags flags,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                camel_store_get_folder              (CamelStore *store,
                                                             const gchar *folder_name,
                                                             CamelStoreGetFolderFlags flags,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    CamelFolder *       camel_store_get_folder_finish       (CamelStore *store,
                                                             GAsyncResult *result,
                                                             GError **error);
    CamelFolderInfo *   camel_store_get_folder_info_sync    (CamelStore *store,
                                                             const gchar *top,
                                                             CamelStoreGetFolderInfoFlags flags,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                camel_store_get_folder_info         (CamelStore *store,
                                                             const gchar *top,
                                                             CamelStoreGetFolderInfoFlags flags,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    CamelFolderInfo *   camel_store_get_folder_info_finish  (CamelStore *store,
                                                             GAsyncResult *result,
                                                             GError **error);
    CamelFolder *       camel_store_get_inbox_folder_sync   (CamelStore *store,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                camel_store_get_inbox_folder        (CamelStore *store,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    CamelFolder *       camel_store_get_inbox_folder_finish (CamelStore *store,
                                                             GAsyncResult *result,
                                                             GError **error);
    CamelFolder *       camel_store_get_junk_folder_sync    (CamelStore *store,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                camel_store_get_junk_folder         (CamelStore *store,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    CamelFolder *       camel_store_get_junk_folder_finish  (CamelStore *store,
                                                             GAsyncResult *result,
                                                             GError **error);
    CamelFolder *       camel_store_get_trash_folder_sync   (CamelStore *store,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                camel_store_get_trash_folder        (CamelStore *store,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    CamelFolder *       camel_store_get_trash_folder_finish (CamelStore *store,
                                                             GAsyncResult *result,
                                                             GError **error);
    CamelFolderInfo *   camel_store_create_folder_sync      (CamelStore *store,
                                                             const gchar *parent_name,
                                                             const gchar *folder_name,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                camel_store_create_folder           (CamelStore *store,
                                                             const gchar *parent_name,
                                                             const gchar *folder_name,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    CamelFolderInfo *   camel_store_create_folder_finish    (CamelStore *store,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            camel_store_delete_folder_sync      (CamelStore *store,
                                                             const gchar *folder_name,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                camel_store_delete_folder           (CamelStore *store,
                                                             const gchar *folder_name,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            camel_store_delete_folder_finish    (CamelStore *store,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            camel_store_rename_folder_sync      (CamelStore *store,
                                                             const gchar *old_name,
                                                             const gchar *new_name,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                camel_store_rename_folder           (CamelStore *store,
                                                             const gchar *old_name,
                                                             const gchar *new_name,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            camel_store_rename_folder_finish    (CamelStore *store,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            camel_store_subscribe_folder_sync   (CamelStore *store,
                                                             const gchar *folder_name,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                camel_store_subscribe_folder        (CamelStore *store,
                                                             const gchar *folder_name,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            camel_store_subscribe_folder_finish (CamelStore *store,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            camel_store_unsubscribe_folder_sync (CamelStore *store,
                                                             const gchar *folder_name,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                camel_store_unsubscribe_folder      (CamelStore *store,
                                                             const gchar *folder_name,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            camel_store_unsubscribe_folder_finish
                                                            (CamelStore *store,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            camel_store_synchronize_sync        (CamelStore *store,
                                                             gboolean expunge,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                camel_store_synchronize             (CamelStore *store,
                                                             gboolean expunge,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            camel_store_synchronize_finish      (CamelStore *store,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            camel_store_noop_sync               (CamelStore *store,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                camel_store_noop                    (CamelStore *store,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            camel_store_noop_finish             (CamelStore *store,
                                                             GAsyncResult *result,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----CamelObject
             +----CamelService
                   +----CamelStore
                         +----CamelDiscoStore
                         +----CamelOfflineStore
                         +----CamelVeeStore

## Signals

      "folder-created"                                 : Run First
      "folder-deleted"                                 : Run First
      "folder-opened"                                  : Run First
      "folder-renamed"                                 : Run First
      "folder-subscribed"                              : Run First
      "folder-unsubscribed"                            : Run First

## Description

## Details

### CamelStore

    typedef struct _CamelStore CamelStore;

### CAMEL_STORE_ERROR

    #define             CAMEL_STORE_ERROR

Since 2.32

### enum CamelStoreError

    typedef enum {
    	CAMEL_STORE_ERROR_INVALID,
    	CAMEL_STORE_ERROR_NO_FOLDER
    } CamelStoreError;

Since 2.32

### CAMEL_FOLDER_TYPE_MASK

    #define CAMEL_FOLDER_TYPE_MASK (7 << 10)

### CAMEL_FOLDER_TYPE_BIT

    #define CAMEL_FOLDER_TYPE_BIT (10)

### enum CamelFolderInfoFlags

    typedef enum {
    	CAMEL_FOLDER_NOSELECT     = 1 << 0,
    	CAMEL_FOLDER_NOINFERIORS  = 1 << 1,
    	CAMEL_FOLDER_CHILDREN     = 1 << 2,
    	CAMEL_FOLDER_NOCHILDREN   = 1 << 3,
    	CAMEL_FOLDER_SUBSCRIBED   = 1 << 4,
    	CAMEL_FOLDER_VIRTUAL      = 1 << 5,
    	CAMEL_FOLDER_SYSTEM       = 1 << 6,
    	CAMEL_FOLDER_VTRASH       = 1 << 7,
    	CAMEL_FOLDER_SHARED_TO_ME = 1 << 8,
    	CAMEL_FOLDER_SHARED_BY_ME = 1 << 9,
    	CAMEL_FOLDER_TYPE_NORMAL  = 0 << CAMEL_FOLDER_TYPE_BIT,
    	CAMEL_FOLDER_TYPE_INBOX   = 1 << CAMEL_FOLDER_TYPE_BIT,
    	CAMEL_FOLDER_TYPE_OUTBOX  = 2 << CAMEL_FOLDER_TYPE_BIT,
    	CAMEL_FOLDER_TYPE_TRASH   = 3 << CAMEL_FOLDER_TYPE_BIT,
    	CAMEL_FOLDER_TYPE_JUNK    = 4 << CAMEL_FOLDER_TYPE_BIT,
    	CAMEL_FOLDER_TYPE_SENT    = 5 << CAMEL_FOLDER_TYPE_BIT
    } CamelFolderInfoFlags;

These flags are abstractions. It's up to the CamelProvider to give them suitable interpretations. Use CAMEL_FOLDER_TYPE_MASK to isolate the folder's type.

`CAMEL_FOLDER_NOSELECT` | The folder cannot contain messages.
`CAMEL_FOLDER_NOINFERIORS` | The folder cannot have child folders.
`CAMEL_FOLDER_CHILDREN` | The folder has children (not yet fully implemented).
`CAMEL_FOLDER_NOCHILDREN` | The folder does not have children (not yet fully implemented).
`CAMEL_FOLDER_SUBSCRIBED` | The folder is subscribed.
`CAMEL_FOLDER_VIRTUAL` | The folder is virtual. Messages cannot be copied or moved to virtual folders since they are only queries of other folders.
`CAMEL_FOLDER_SYSTEM` | The folder is a built-in "system" folder. System folders cannot be renamed or deleted.
`CAMEL_FOLDER_VTRASH` | The folder is a virtual trash folder. It cannot be copied to, and can only be moved to if in an existing folder.
`CAMEL_FOLDER_SHARED_TO_ME` | A folder being shared by someone else.
`CAMEL_FOLDER_SHARED_BY_ME` | A folder being shared by the user.
`CAMEL_FOLDER_TYPE_NORMAL` | The folder is a normal folder.
`CAMEL_FOLDER_TYPE_INBOX` | The folder is an inbox folder.
`CAMEL_FOLDER_TYPE_OUTBOX` | The folder is an outbox folder.
`CAMEL_FOLDER_TYPE_TRASH` | The folder shows deleted messages.
`CAMEL_FOLDER_TYPE_JUNK` | The folder shows junk messages.
`CAMEL_FOLDER_TYPE_SENT` | The folder shows sent messages.

### CamelFolderInfo

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

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

    	CamelFolderInfoFlags flags;
    	gint32 unread;
    	gint32 total;
    } CamelFolderInfo;

### enum CamelStoreFlags

    typedef enum {
    	CAMEL_STORE_SUBSCRIPTIONS    = 1 << 0,
    	CAMEL_STORE_VTRASH           = 1 << 1,
    	CAMEL_STORE_FILTER_INBOX     = 1 << 2,
    	CAMEL_STORE_VJUNK            = 1 << 3,
    	CAMEL_STORE_PROXY            = 1 << 4,
    	CAMEL_STORE_IS_MIGRATING     = 1 << 5,
    	CAMEL_STORE_ASYNC            = 1 << 6,
    	CAMEL_STORE_REAL_JUNK_FOLDER = 1 << 7,
    } CamelStoreFlags;

### enum CamelStorePermissionFlags

    typedef enum {
    	CAMEL_STORE_READ  = 1 << 0,
    	CAMEL_STORE_WRITE = 1 << 1
    } CamelStorePermissionFlags;

### enum CamelStoreGetFolderFlags

    typedef enum {
    	CAMEL_STORE_FOLDER_CREATE     = 1 << 0,
    	CAMEL_STORE_FOLDER_EXCL       = 1 << 1,
    	CAMEL_STORE_FOLDER_BODY_INDEX = 1 << 2,
    	CAMEL_STORE_FOLDER_PRIVATE    = 1 << 3  /* a private folder that
                                                       should not show up in
                                                       unmatched, folder
                                                       info's, etc. */
    } CamelStoreGetFolderFlags;

### CAMEL_STORE_FOLDER_CREATE_EXCL

    #define             CAMEL_STORE_FOLDER_CREATE_EXCL

### enum CamelStoreGetFolderInfoFlags

    typedef enum {
    	CAMEL_STORE_FOLDER_INFO_FAST              = 1 << 0,
    	CAMEL_STORE_FOLDER_INFO_RECURSIVE         = 1 << 1,
    	CAMEL_STORE_FOLDER_INFO_SUBSCRIBED        = 1 << 2,
    	CAMEL_STORE_FOLDER_INFO_NO_VIRTUAL        = 1 << 3,
    	CAMEL_STORE_FOLDER_INFO_SUBSCRIPTION_LIST = 1 << 4
    } CamelStoreGetFolderInfoFlags;

`CAMEL_STORE_FOLDER_INFO_FAST` |
`CAMEL_STORE_FOLDER_INFO_RECURSIVE` |
`CAMEL_STORE_FOLDER_INFO_SUBSCRIBED` |
`CAMEL_STORE_FOLDER_INFO_NO_VIRTUAL` | Do not include virtual trash or junk folders.
`CAMEL_STORE_FOLDER_INFO_SUBSCRIPTION_LIST` | Fetch only the subscription list. Clients should use this flag for requesting the list of folders available for subscription. Used in Exchange / IMAP connectors for public folder fetching.

### camel_store_folder_created ()

    void                camel_store_folder_created          (CamelStore *store,
                                                             CamelFolderInfo *folder_info);

Emits the "folder-created" signal from an idle source on the main loop. The idle source's priority is G_PRIORITY_DEFAULT_IDLE.

This function is only intended for Camel providers.

`store` : | a CamelStore
`folder_info` : | information about the created folder

Since 2.32

### camel_store_folder_deleted ()

    void                camel_store_folder_deleted          (CamelStore *store,
                                                             CamelFolderInfo *folder_info);

Emits the "folder-deleted" signal from an idle source on the main loop. The idle source's priority is G_PRIORITY_DEFAULT_IDLE.

This function is only intended for Camel providers.

`store` : | a CamelStore
`folder_info` : | information about the deleted folder

Since 2.32

### camel_store_folder_opened ()

    void                camel_store_folder_opened           (CamelStore *store,
                                                             CamelFolder *folder);

Emits the "folder-opened" signal from an idle source on the main loop. The idle source's priority is G_PRIORITY_DEFAULT_IDLE.

This function is only intended for Camel providers.

`store` : | a CamelStore
`folder` : | the CamelFolder that was opened

Since 3.0

### camel_store_folder_renamed ()

    void                camel_store_folder_renamed          (CamelStore *store,
                                                             const gchar *old_name,
                                                             CamelFolderInfo *folder_info);

Emits the "folder-renamed" signal from an idle source on the main loop. The idle source's priority is G_PRIORITY_DEFAULT_IDLE.

This function is only intended for Camel providers.

`store` : | a CamelStore
`old_name` : | the old name of the folder
`folder_info` : | information about the renamed folder

Since 2.32

### camel_store_folder_subscribed ()

    void                camel_store_folder_subscribed       (CamelStore *store,
                                                             CamelFolderInfo *folder_info);

Emits the "folder-subscribed" signal from an idle source on the main loop. The idle source's priority is G_PRIORITY_DEFAULT_IDLE.

This function is only intended for Camel providers.

`store` : | a CamelStore
`folder_info` : | information about the subscribed folder

Since 2.32

### camel_store_folder_unsubscribed ()

    void                camel_store_folder_unsubscribed     (CamelStore *store,
                                                             CamelFolderInfo *folder_info);

Emits the "folder-unsubscribed" signal from an idle source on the main loop. The idle source's priority is G_PRIORITY_DEFAULT_IDLE.

This function is only intended for Camel providers.

`store` : | a CamelStore
`folder_info` : | information about the unsubscribed folder

Since 2.32

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

Since 2.22

### 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
Returns : | `TRUE` if folder subscriptions are supported or `FALSE` otherwise

### camel_store_folder_is_subscribed ()

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

Find out if a folder has been subscribed to.

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

### camel_store_folder_uri_equal ()

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

Compares two folder uris to check that they are equal.

`store` : | a CamelStore
`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,
                                                             GError **error);

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
`error` : | return location for a GError, or `NULL`
Returns : | whether folder should be checked for new mails

Since 2.22

### enum CamelStoreLock

    typedef enum {
    	CAMEL_STORE_FOLDER_LOCK
    } CamelStoreLock;

Since 2.32

### camel_store_lock ()

    void                camel_store_lock                    (CamelStore *store,
                                                             CamelStoreLock lock);

Locks store's lock. Unlock it with `camel_store_unlock()`.

`store` : | a CamelStore
`lock` : | lock type to lock

Since 2.32

### camel_store_unlock ()

    void                camel_store_unlock                  (CamelStore *store,
                                                             CamelStoreLock lock);

Unlocks store's lock, previously locked with `camel_store_lock()`.

`store` : | a CamelStore
`lock` : | lock type to unlock

Since 2.32

### camel_store_get_folder_sync ()

    CamelFolder *       camel_store_get_folder_sync         (CamelStore *store,
                                                             const gchar *folder_name,
                                                             CamelStoreGetFolderFlags flags,
                                                             GCancellable *cancellable,
                                                             GError **error);

Gets a specific folder object from `store` by name.

`store` : | a CamelStore
`folder_name` : | name of the folder to get
`flags` : | folder flags (create, save body index, etc)
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | the requested CamelFolder object, or `NULL` on error

Since 2.34

### camel_store_get_folder ()

    void                camel_store_get_folder              (CamelStore *store,
                                                             const gchar *folder_name,
                                                             CamelStoreGetFolderFlags flags,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously gets a specific folder object from `store` by name.

When the operation is finished, `callback` will be called. You can then call `camel_store_get_folder_finish()` to get the result of the operation.

`store` : | a CamelStore
`folder_name` : | name of the folder to get
`flags` : | folder flags (create, save body index, etc)
`io_priority` : | the I/O priority of the request
`cancellable` : | optional GCancellable object, or `NULL`
`callback` : | a GAsyncReadyCallback to call when the request is satisfied
`user_data` : | data to pass to the callback function

Since 2.34

### camel_store_get_folder_finish ()

    CamelFolder *       camel_store_get_folder_finish       (CamelStore *store,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes the operation started with `camel_store_get_folder()`.

`store` : | a CamelStore
`result` : | a GAsyncResult
`error` : | return location for a GError, or `NULL`
Returns : | the requested CamelFolder object, or `NULL` on error

Since 2.34

### camel_store_get_folder_info_sync ()

    CamelFolderInfo *   camel_store_get_folder_info_sync    (CamelStore *store,
                                                             const gchar *top,
                                                             CamelStoreGetFolderInfoFlags flags,
                                                             GCancellable *cancellable,
                                                             GError **error);

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 returned CamelFolderInfo tree should be freed with `camel_store_free_folder_info()`.

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
`top` : | the name of the folder to start from
`flags` : | various CAMEL_STORE_FOLDER_INFO_* flags to control behavior
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | a CamelFolderInfo tree, or `NULL` on error

Since 2.34

### camel_store_get_folder_info ()

    void                camel_store_get_folder_info         (CamelStore *store,
                                                             const gchar *top,
                                                             CamelStoreGetFolderInfoFlags flags,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously fetches information about the folder structure of `store`, starting with `top`. For details of the behavior, see `camel_store_get_folder_info_sync()`.

When the operation is finished, `callback` will be called. You can then call `camel_store_get_folder_info_finish()` to get the result of the operation.

`store` : | a CamelStore
`top` : | the name of the folder to start from
`flags` : | various CAMEL_STORE_FOLDER_INFO_* flags to control behavior
`io_priority` : | the I/O priority of the request
`cancellable` : | optional GCancellable object, or `NULL`
`callback` : | a GAsyncReadyCallback to call when the request is satisfied
`user_data` : | data to pass to the callback function

Since 2.34

### camel_store_get_folder_info_finish ()

    CamelFolderInfo *   camel_store_get_folder_info_finish  (CamelStore *store,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes the operation started with `camel_store_get_folder_info()`. The returned CamelFolderInfo tree should be freed with `camel_store_free_folder_info()`.

`store` : | a CamelStore
`result` : | a GAsyncResult
`error` : | return location for a GError, or `NULL`
Returns : | a CamelFolderInfo tree, or `NULL` on error

Since 2.34

### camel_store_get_inbox_folder_sync ()

    CamelFolder *       camel_store_get_inbox_folder_sync   (CamelStore *store,
                                                             GCancellable *cancellable,
                                                             GError **error);

Gets the folder in `store` into which new mail is delivered.

`store` : | a CamelStore
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | the inbox folder for `store`, or `NULL` on error or if no such folder exists

Since 2.34

### camel_store_get_inbox_folder ()

    void                camel_store_get_inbox_folder        (CamelStore *store,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously gets the folder in `store` into which new mail is delivered.

When the operation is finished, `callback` will be called. You can then call `camel_store_get_inbox_folder_finish()` to get the result of the operation.

`store` : | a CamelStore
`io_priority` : | the I/O priority of the request
`cancellable` : | optional GCancellable object, or `NULL`
`callback` : | a GAsyncReadyCallback to call when the request is satisfied
`user_data` : | data to pass to the callback function

Since 2.34

### camel_store_get_inbox_folder_finish ()

    CamelFolder *       camel_store_get_inbox_folder_finish (CamelStore *store,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes the operation started with `camel_store_get_inbox_folder()`.

`store` : | a CamelStore
`result` : | a GAsyncResult
`error` : | return location for a GError, or `NULL`
Returns : | the inbox folder for `store`, or `NULL` on error or if no such folder exists

Since 2.34

### camel_store_get_junk_folder_sync ()

    CamelFolder *       camel_store_get_junk_folder_sync    (CamelStore *store,
                                                             GCancellable *cancellable,
                                                             GError **error);

Gets the folder in `store` into which junk is delivered.

`store` : | a CamelStore
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | the junk folder for `store`, or `NULL` on error or if no such folder exists

Since 2.34

### camel_store_get_junk_folder ()

    void                camel_store_get_junk_folder         (CamelStore *store,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously gets the folder in `store` into which junk is delivered.

When the operation is finished, `callback` will be called. You can then call `camel_store_get_junk_folder_finish()` to get the result of the operation.

`store` : | a CamelStore
`io_priority` : | the I/O priority of the request
`cancellable` : | optional GCancellable object, or `NULL`
`callback` : | a GAsyncReadyCallback to call when the request is satisfied
`user_data` : | data to pass to the callback function

Since 2.34

### camel_store_get_junk_folder_finish ()

    CamelFolder *       camel_store_get_junk_folder_finish  (CamelStore *store,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes the operation started with `camel_store_get_junk_folder()`.

`store` : | a CamelStore
`result` : | a GAsyncResult
`error` : | return location for a GError, or `NULL`
Returns : | the junk folder for `store`, or `NULL` on error or if no such folder exists

Since 2.34

### camel_store_get_trash_folder_sync ()

    CamelFolder *       camel_store_get_trash_folder_sync   (CamelStore *store,
                                                             GCancellable *cancellable,
                                                             GError **error);

Gets the folder in `store` into which trash is delivered.

`store` : | a CamelStore
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | the trash folder for `store`, or `NULL` on error or if no such folder exists

Since 2.34

### camel_store_get_trash_folder ()

    void                camel_store_get_trash_folder        (CamelStore *store,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously gets the folder in `store` into which trash is delivered.

When the operation is finished, `callback` will be called. You can then call `camel_store_get_trash_folder_finish()` to get the result of the operation.

`store` : | a CamelStore
`io_priority` : | the I/O priority of the request
`cancellable` : | optional GCancellable object, or `NULL`
`callback` : | a GAsyncReadyCallback to call when the request is satisfied
`user_data` : | data to pass to the callback function

Since 2.34

### camel_store_get_trash_folder_finish ()

    CamelFolder *       camel_store_get_trash_folder_finish (CamelStore *store,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes the operation started with `camel_store_get_trash_folder()`.

`store` : | a CamelStore
`result` : | a GAsyncResult
`error` : | return location for a GError, or `NULL`
Returns : | the trash folder for `store`, or `NULL` on error or if no such folder exists

Since 2.34

### camel_store_create_folder_sync ()

    CamelFolderInfo *   camel_store_create_folder_sync      (CamelStore *store,
                                                             const gchar *parent_name,
                                                             const gchar *folder_name,
                                                             GCancellable *cancellable,
                                                             GError **error);

Creates a new folder as a child of an existing folder. `parent_name` can be `NULL` to create a new top-level folder. The returned CamelFolderInfo struct should be freed with `camel_store_free_folder_info()`.

`store` : | a CamelStore
`parent_name` : | name of the new folder's parent, or `NULL`
`folder_name` : | name of the folder to create
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | info about the created folder, or `NULL` on error

Since 2.34

### camel_store_create_folder ()

    void                camel_store_create_folder           (CamelStore *store,
                                                             const gchar *parent_name,
                                                             const gchar *folder_name,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

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

When the operation is finished, `callback` will be called. You can then call `camel_store_create_folder_finish()` to get the result of the operation.

`store` : | a CamelStore
`parent_name` : | name of the new folder's parent, or `NULL`
`folder_name` : | name of the folder to create
`io_priority` : | the I/O priority of the request
`cancellable` : | optional GCancellable object, or `NULL`
`callback` : | a GAsyncReadyCallback to call when the request is satisfied
`user_data` : | data to pass to the callback function

Since 2.34

### camel_store_create_folder_finish ()

    CamelFolderInfo *   camel_store_create_folder_finish    (CamelStore *store,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes the operation started with `camel_store_create_folder()`. The returned CamelFolderInfo struct should be freed with `camel_store_free_folder_info()`.

`store` : | a CamelStore
`result` : | a GAsyncResult
`error` : | return location for a GError, or `NULL`
Returns : | info about the created folder, or `NULL` on error

Since 2.34

### camel_store_delete_folder_sync ()

    gboolean            camel_store_delete_folder_sync      (CamelStore *store,
                                                             const gchar *folder_name,
                                                             GCancellable *cancellable,
                                                             GError **error);

Deletes the folder described by `folder_name`. The folder must be empty.

`store` : | a CamelStore
`folder_name` : | name of the folder to delete
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

Since 2.34

### camel_store_delete_folder ()

    void                camel_store_delete_folder           (CamelStore *store,
                                                             const gchar *folder_name,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously deletes the folder described by `folder_name`. The folder must be empty.

When the operation is finished, `callback` will be called. You can then call `camel_store_delete_folder_finish()` to get the result of the operation.

`store` : | a CamelStore
`folder_name` : | name of the folder to delete
`io_priority` : | the I/O priority of the request
`cancellable` : | optional GCancellable object, or `NULL`
`callback` : | a GAsyncReadyCallback to call when the request is satisfied
`user_data` : | data to pass to the callback function

Since 2.34

### camel_store_delete_folder_finish ()

    gboolean            camel_store_delete_folder_finish    (CamelStore *store,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes the operation started with `camel_store_delete_folder()`.

`store` : | a CamelStore
`result` : | a GAsyncResult
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on error

Since 2.34

### camel_store_rename_folder_sync ()

    gboolean            camel_store_rename_folder_sync      (CamelStore *store,
                                                             const gchar *old_name,
                                                             const gchar *new_name,
                                                             GCancellable *cancellable,
                                                             GError **error);

Renames the folder described by `old_name` to `new_name`.

`store` : | a CamelStore
`old_name` : | the current name of the folder
`new_name` : | the new name of the folder
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on error

Since 2.34

### camel_store_rename_folder ()

    void                camel_store_rename_folder           (CamelStore *store,
                                                             const gchar *old_name,
                                                             const gchar *new_name,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously renames the folder described by `old_name` to `new_name`.

When the operation is finished, `callback` will be called. You can then call `camel_store_rename_folder_finish()` to get the result of the operation.

`store` : | a CamelStore
`old_name` : | the current name of the folder
`new_name` : | the new name of the folder
`io_priority` : | the I/O priority of the request
`cancellable` : | optional GCancellable object, or `NULL`
`callback` : | a GAsyncReadyCallback to call when the request is satisfied
`user_data` : | data to pass to the callback function

Since 2.34

### camel_store_rename_folder_finish ()

    gboolean            camel_store_rename_folder_finish    (CamelStore *store,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes the operation started with `camel_store_rename_folder()`.

`store` : | a CamelStore
`result` : | a GAsyncResult
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on error

Since 2.34

### camel_store_subscribe_folder_sync ()

    gboolean            camel_store_subscribe_folder_sync   (CamelStore *store,
                                                             const gchar *folder_name,
                                                             GCancellable *cancellable,
                                                             GError **error);

Subscribes to the folder described by `folder_name`.

`store` : | a CamelStore
`folder_name` : | full path of the folder
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on error

Since 2.34

### camel_store_subscribe_folder ()

    void                camel_store_subscribe_folder        (CamelStore *store,
                                                             const gchar *folder_name,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously subscribes to the folder described by `folder_name`.

When the operation is finished, `callback` will be called. You can then call `camel_store_subscribe_folder_finish()` to get the result of the operation.

`store` : | a CamelStore
`folder_name` : | full path of the folder
`io_priority` : | the I/O priority of the request
`cancellable` : | optional GCancellable object, or `NULL`
`callback` : | a GAsyncReadyCallback to call when the request is satisfied
`user_data` : | data to pass to the callback function

Since 2.34

### camel_store_subscribe_folder_finish ()

    gboolean            camel_store_subscribe_folder_finish (CamelStore *store,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes the operation started with `camel_store_subscribe_folder()`.

`store` : | a CamelStore
`result` : | a GAsyncResult
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on error

Since 2.34

### camel_store_unsubscribe_folder_sync ()

    gboolean            camel_store_unsubscribe_folder_sync (CamelStore *store,
                                                             const gchar *folder_name,
                                                             GCancellable *cancellable,
                                                             GError **error);

Unsubscribes from the folder described by `folder_name`.

`store` : | a CamelStore
`folder_name` : | full path of the folder
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on error

Since 2.34

### camel_store_unsubscribe_folder ()

    void                camel_store_unsubscribe_folder      (CamelStore *store,
                                                             const gchar *folder_name,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously unsubscribes from the folder described by `folder_name`.

When the operation is finished, `callback` will be called. You can then call `camel_store_unsubscribe_folder_finish()` to get the result of the operation.

`store` : | a CamelStore
`folder_name` : | full path of the folder
`io_priority` : | the I/O priority of the request
`cancellable` : | optional GCancellable object, or `NULL`
`callback` : | a GAsyncReadyCallback to call when the request is satisfied
`user_data` : | data to pass to the callback function

Since 2.34

### camel_store_unsubscribe_folder_finish ()

    gboolean            camel_store_unsubscribe_folder_finish
                                                            (CamelStore *store,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes the operation started with `camel_store_unsubscribe_folder()`.

`store` : | a CamelStore
`result` : | a GAsyncResult
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on error

Since 2.34

### camel_store_synchronize_sync ()

    gboolean            camel_store_synchronize_sync        (CamelStore *store,
                                                             gboolean expunge,
                                                             GCancellable *cancellable,
                                                             GError **error);

Synchronizes any changes that have been made to `store` and its folders with the real store.

`store` : | a CamelStore
`expunge` : | whether to expunge after synchronizing
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on error

Since 2.34

### camel_store_synchronize ()

    void                camel_store_synchronize             (CamelStore *store,
                                                             gboolean expunge,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Synchronizes any changes that have been made to `store` and its folders with the real store asynchronously.

When the operation is finished, `callback` will be called. You can then call `camel_store_synchronize_finish()` to get the result of the operation.

`store` : | a CamelStore
`expunge` : | whether to expunge after synchronizing
`io_priority` : | the I/O priority of the request
`cancellable` : | optional GCancellable object, or `NULL`
`callback` : | a GAsyncReadyCallback to call when the request is satisfied
`user_data` : | data to pass to the callback function

Since 2.34

### camel_store_synchronize_finish ()

    gboolean            camel_store_synchronize_finish      (CamelStore *store,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes the operation started with `camel_store_synchronize()`.

`store` : | a CamelStore
`result` : | a GAsyncResult
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on error

Since 2.34

### camel_store_noop_sync ()

    gboolean            camel_store_noop_sync               (CamelStore *store,
                                                             GCancellable *cancellable,
                                                             GError **error);

Pings `store` so its connection doesn't time out.

`store` : | a CamelStore
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on error

Since 2.34

### camel_store_noop ()

    void                camel_store_noop                    (CamelStore *store,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Pings `store` asynchronously so its connection doesn't time out.

When the operation is finished, `callback` will be called. You can then call `camel_store_noop_finish()` to get the result of the operation.

`store` : | a CamelStore
`io_priority` : | the I/O priority of the request
`cancellable` : | optional GCancellable object, or `NULL`
`callback` : | a GAsyncReadyCallback to call when the request is satisfied
`user_data` : | data to pass to the callback function

Since 2.34

### camel_store_noop_finish ()

    gboolean            camel_store_noop_finish             (CamelStore *store,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes the operation started with `camel_store_noop()`.

`store` : | a CamelStore
`result` : | a GAsyncResult
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on error

Since 2.34

## Signal Details

### The `"folder-created"` signal

    void                user_function                      (CamelStore *camelstore,
                                                            gpointer    arg1,
                                                            gpointer    user_data)       : Run First

`camelstore` : | the object which received the signal.
`Param2` : |
`user_data` : | user data set when the signal handler was connected.

### The `"folder-deleted"` signal

    void                user_function                      (CamelStore *camelstore,
                                                            gpointer    arg1,
                                                            gpointer    user_data)       : Run First

`camelstore` : | the object which received the signal.
`Param2` : |
`user_data` : | user data set when the signal handler was connected.

### The `"folder-opened"` signal

    void                user_function                      (CamelStore  *camelstore,
                                                            CamelFolder *arg1,
                                                            gpointer     user_data)       : Run First

`camelstore` : | the object which received the signal.
`Param2` : |
`user_data` : | user data set when the signal handler was connected.

### The `"folder-renamed"` signal

    void                user_function                      (CamelStore *camelstore,
                                                            gchar      *arg1,
                                                            gpointer    arg2,
                                                            gpointer    user_data)       : Run First

`camelstore` : | the object which received the signal.
`arg1` : |
`arg2` : |
`user_data` : | user data set when the signal handler was connected.

### The `"folder-subscribed"` signal

    void                user_function                      (CamelStore *camelstore,
                                                            gpointer    arg1,
                                                            gpointer    user_data)       : Run First

`camelstore` : | the object which received the signal.
`Param2` : |
`user_data` : | user data set when the signal handler was connected.

### The `"folder-unsubscribed"` signal

    void                user_function                      (CamelStore *camelstore,
                                                            gpointer    arg1,
                                                            gpointer    user_data)       : Run First

`camelstore` : | the object which received the signal.
`Param2` : |
`user_data` : | user data set when the signal handler was connected.