CamelStore

## CamelStore CamelStore |

## Synopsis

    struct              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_info_stale       (CamelStore *store);
    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_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_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

## Known Derived Interfaces

CamelStore is required by CamelSubscribable.

## Implemented Interfaces

CamelStore implements GInitable.

## Signals

      "folder-created"                                 : Run First
      "folder-deleted"                                 : Run First
      "folder-info-stale"                              : Run First
      "folder-opened"                                  : Run First
      "folder-renamed"                                 : Run First

## Description

## Details

### struct CamelStore

    struct 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;

`CAMEL_STORE_ERROR_INVALID` |
`CAMEL_STORE_ERROR_NO_FOLDER` |

Since 2.32

### CAMEL_FOLDER_TYPE_MASK

    #define CAMEL_FOLDER_TYPE_MASK (63 << CAMEL_FOLDER_TYPE_BIT)

### CAMEL_FOLDER_TYPE_BIT

    #define CAMEL_FOLDER_TYPE_BIT (10)

### enum CamelFolderInfoFlags

    typedef enum {
     /*< flags >*/
    	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,
    	CAMEL_FOLDER_TYPE_CONTACTS = 6 << CAMEL_FOLDER_TYPE_BIT,
    	CAMEL_FOLDER_TYPE_EVENTS = 7 << CAMEL_FOLDER_TYPE_BIT,
    	CAMEL_FOLDER_TYPE_MEMOS = 8 << CAMEL_FOLDER_TYPE_BIT,
    	CAMEL_FOLDER_TYPE_TASKS = 9 << CAMEL_FOLDER_TYPE_BIT,
    	CAMEL_FOLDER_READONLY = 1 << 16,
    	/* empty gap from unused flag removal */
    	CAMEL_FOLDER_FLAGGED = 1 << 18,

    	CAMEL_FOLDER_FLAGS_LAST    = 1 << 24  /*< skip >*/
    } 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.
`CAMEL_FOLDER_TYPE_CONTACTS` | The folder contains contacts, instead of mail messages.
`CAMEL_FOLDER_TYPE_EVENTS` | The folder contains calendar events, instead of mail messages.
`CAMEL_FOLDER_TYPE_MEMOS` | The folder contains memos, instead of mail messages.
`CAMEL_FOLDER_TYPE_TASKS` | The folder contains tasks, instead of mail messages.
`CAMEL_FOLDER_READONLY` |
`CAMEL_FOLDER_FLAGGED` |
`CAMEL_FOLDER_FLAGS_LAST` |

### CamelFolderInfo

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

    	gchar *full_name;
    	gchar *display_name;

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

### enum CamelStoreFlags

    typedef enum {
     /*< flags >*/
    	CAMEL_STORE_VTRASH = 1 << 0,
    	CAMEL_STORE_VJUNK = 1 << 1,
    	CAMEL_STORE_PROXY = 1 << 2,
    	CAMEL_STORE_IS_MIGRATING = 1 << 3,
    	CAMEL_STORE_REAL_JUNK_FOLDER = 1 << 4,
    	CAMEL_STORE_CAN_EDIT_FOLDERS = 1 << 5,
    	CAMEL_STORE_USE_CACHE_DIR = 1 << 6
    } CamelStoreFlags;

`CAMEL_STORE_VTRASH` |
`CAMEL_STORE_VJUNK` |
`CAMEL_STORE_PROXY` |
`CAMEL_STORE_IS_MIGRATING` |
`CAMEL_STORE_REAL_JUNK_FOLDER` |
`CAMEL_STORE_CAN_EDIT_FOLDERS` |
`CAMEL_STORE_USE_CACHE_DIR` |

### enum CamelStorePermissionFlags

    typedef enum {
     /*< flags >*/
    	CAMEL_STORE_READ = 1 << 0,
    	CAMEL_STORE_WRITE = 1 << 1
    } CamelStorePermissionFlags;

`CAMEL_STORE_READ` |
`CAMEL_STORE_WRITE` |

### 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` |
`CAMEL_STORE_FOLDER_EXCL` |
`CAMEL_STORE_FOLDER_BODY_INDEX` |
`CAMEL_STORE_FOLDER_PRIVATE` |

### CAMEL_STORE_FOLDER_CREATE_EXCL

    #define             CAMEL_STORE_FOLDER_CREATE_EXCL

### enum CamelStoreGetFolderInfoFlags

    typedef enum {
     /*< flags >*/
    	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_HIGH_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_HIGH_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_HIGH_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_HIGH_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_info_stale ()

    void                camel_store_folder_info_stale       (CamelStore *store);

Emits the "folder-info-stale" signal from an idle source on the main loop. The idle source's priority is G_PRIORITY_LOW.

See the "folder-info-stale" documentation for details on when to use this signal.

This function is only intended for Camel providers.

`store` : | a CamelStore

Since 3.10

### 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);

Allocates a new CamelFolderInfo instance. Free it with `camel_folder_info_free()`.

Returns : | a new 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_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;

`CAMEL_STORE_FOLDER_LOCK` |

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 3.0

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

## Signal Details

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

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

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

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

### The `"folder-info-stale"` signal

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

This signal indicates significant changes have occurred to the folder hierarchy of `store`, and that previously fetched CamelFolderInfo data should be considered stale.

Applications should handle this signal by replacing cached CamelFolderInfo data for `store` with fresh data by way of `camel_store_get_folder_info()`.

More often than not this signal will be emitted as a result of user preference changes rather than actual server-side changes. For example, a user may change a preference that reveals a set of folders previously hidden from view, or that alters whether to augment the `store` with virtual Junk and Trash folders.

`store` : | the CamelStore that received the signal
`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

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

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