CamelStore: Camel Reference Manual

## CamelStore CamelStore |

## Functions

GQuark | camel_store_error_quark ()
CamelDB * | camel_store_get_db ()
CamelObjectBag * | camel_store_get_folders_bag ()
GPtrArray * | camel_store_dup_opened_folders ()
guint32 | camel_store_get_flags ()
void | camel_store_set_flags ()
guint32 | camel_store_get_permissions ()
void | camel_store_set_permissions ()
void | camel_store_folder_created ()
void | camel_store_folder_deleted ()
void | camel_store_folder_opened ()
void | camel_store_folder_renamed ()
void | camel_store_folder_info_stale ()
CamelFolderInfo * | camel_folder_info_new ()
void | camel_folder_info_free ()
CamelFolderInfo * | camel_folder_info_build ()
CamelFolderInfo * | camel_folder_info_clone ()
gboolean | camel_store_can_refresh_folder ()
CamelFolder * | camel_store_get_folder_sync ()
void | camel_store_get_folder ()
CamelFolder * | camel_store_get_folder_finish ()
CamelFolderInfo * | camel_store_get_folder_info_sync ()
void | camel_store_get_folder_info ()
CamelFolderInfo * | camel_store_get_folder_info_finish ()
CamelFolder * | camel_store_get_inbox_folder_sync ()
void | camel_store_get_inbox_folder ()
CamelFolder * | camel_store_get_inbox_folder_finish ()
CamelFolder * | camel_store_get_junk_folder_sync ()
void | camel_store_get_junk_folder ()
CamelFolder * | camel_store_get_junk_folder_finish ()
CamelFolder * | camel_store_get_trash_folder_sync ()
void | camel_store_get_trash_folder ()
CamelFolder * | camel_store_get_trash_folder_finish ()
CamelFolderInfo * | camel_store_create_folder_sync ()
void | camel_store_create_folder ()
CamelFolderInfo * | camel_store_create_folder_finish ()
gboolean | camel_store_delete_folder_sync ()
void | camel_store_delete_folder ()
gboolean | camel_store_delete_folder_finish ()
gboolean | camel_store_rename_folder_sync ()
void | camel_store_rename_folder ()
gboolean | camel_store_rename_folder_finish ()
gboolean | camel_store_synchronize_sync ()
void | camel_store_synchronize ()
gboolean | camel_store_synchronize_finish ()
gboolean | camel_store_initial_setup_sync ()
void | camel_store_initial_setup ()
gboolean | camel_store_initial_setup_finish ()
gboolean | camel_store_maybe_run_db_maintenance ()
void | camel_store_delete_cached_folder ()
gboolean | camel_store_get_can_auto_save_changes ()

## Signals

void | folder-created | Run First
void | folder-deleted | Run First
void | folder-info-stale | Run First
void | folder-opened | Run First
void | folder-renamed | Run First

## Types and Values

#define | CAMEL_STORE_ERROR
#define | CAMEL_STORE_SETUP_ARCHIVE_FOLDER
#define | CAMEL_STORE_SETUP_DRAFTS_FOLDER
#define | CAMEL_STORE_SETUP_SENT_FOLDER
#define | CAMEL_STORE_SETUP_TEMPLATES_FOLDER
enum | CamelStoreError
enum | CamelStoreGetFolderFlags

## Object Hierarchy

        GBoxed
        ╰── CamelFolderInfo
        GObject
        ╰── CamelObject
            ╰── CamelService
                ╰── CamelStore
                    ├── CamelOfflineStore
                    ├── CamelLocalStore
                    ├── CamelPOP3Store
                    ╰── CamelVeeStore

## Description

## Functions

### camel_store_error_quark ()

    GQuark
    camel_store_error_quark (void);

### camel_store_get_db ()

    CamelDB *
    camel_store_get_db (CamelStore *store);

#### Parameters

store | a CamelStore |

#### Returns

A CamelDB instance associated with this `store` .

[transfer none]

Since: 3.24

### camel_store_get_folders_bag ()

    CamelObjectBag *
    camel_store_get_folders_bag (CamelStore *store);

#### Parameters

store | a CamelStore |

#### Returns

a CamelObjectBag of opened CamelFolders.

[transfer none]

Since: 3.24

### camel_store_dup_opened_folders ()

    GPtrArray *
    camel_store_dup_opened_folders (CamelStore *store);

Returns a GPtrArray of all the opened folders for the `store` . The caller owns both the array and the folder references, so to free the array use:

    1
    2
    g_ptr_array_foreach (array, (GFunc) g_object_unref, NULL);
    g_ptr_array_free (array, TRUE);

#### Parameters

store | a CamelStore |

#### Returns

an array with all currently opened folders for the `store` .

[element-type CamelFolder][transfer full]

Since: 3.24

### camel_store_get_flags ()

    guint32
    camel_store_get_flags (CamelStore *store);

#### Parameters

store | a CamelStore |

#### Returns

bit-or of CamelStoreFlags set for the `store`

Since: 3.24

### camel_store_set_flags ()

    void
    camel_store_set_flags (CamelStore *store,
                           guint32 flags);

Sets flags for the `store` , a bit-or of CamelStoreFlags.

#### Parameters

store | a CamelStore |
flags | bit-or of CamelStoreFlags |

Since: 3.24

### camel_store_get_permissions ()

    guint32
    camel_store_get_permissions (CamelStore *store);

#### Parameters

store | a CamelStore |

#### Returns

Permissions of the `store` , a bit-or of CamelStorePermissionFlags

Since: 3.24

### camel_store_set_permissions ()

    void
    camel_store_set_permissions (CamelStore *store,
                                 guint32 permissions);

Sets permissions for the `store` , a bit-or of CamelStorePermissionFlags

#### Parameters

store | a CamelStore |
permissions | permissions of the `store` , a bit-or of CamelStorePermissionFlags |

Since: 3.24

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

store | a CamelStore |

Since: 3.10

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

#### Parameters

fi | a CamelFolderInfo |

### camel_folder_info_build ()

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

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.

#### Parameters

folders | an array of CamelFolderInfo. | [element-type 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.

#### Parameters

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.

#### Parameters

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

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

#### Parameters

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.

[transfer full][nullable]

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.

#### Parameters

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()`.

#### Parameters

store | a CamelStore |
result | a GAsyncResult |
error | return location for a GError, or `NULL` |

#### Returns

the requested CamelFolder object, or `NULL` on error.

[transfer full][nullable]

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_folder_info_free()`.

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 `camel_folder_refresh_info()` it.

#### Parameters

store | a CamelStore |
top | the name of the folder to start from. | [nullable]
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.

[nullable]

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.

#### Parameters

store | a CamelStore |
top | the name of the folder to start from. | [nullable]
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_folder_info_free()`.

#### Parameters

store | a CamelStore |
result | a GAsyncResult |
error | return location for a GError, or `NULL`. | [nullable]

#### Returns

a CamelFolderInfo tree, or `NULL` on error.

[nullable]

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.

#### Parameters

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.

[transfer full][nullable]

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.

#### Parameters

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()`.

#### Parameters

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.

[transfer full][nullable]

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.

#### Parameters

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.

[transfer full][nullable]

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.

#### Parameters

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()`.

#### Parameters

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.

[transfer full][nullable]

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.

#### Parameters

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.

[transfer full][nullable]

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.

#### Parameters

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()`.

#### Parameters

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.

[transfer full][nullable]

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_folder_info_free()`.

#### Parameters

store | a CamelStore |
parent_name | name of the new folder's parent, or `NULL`. | [nullable]
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.

[nullable]

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.

#### Parameters

store | a CamelStore |
parent_name | name of the new folder's parent, or `NULL`. | [nullable]
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_folder_info_free()`.

#### Parameters

store | a CamelStore |
result | a GAsyncResult |
error | return location for a GError, or `NULL` |

#### Returns

info about the created folder, or `NULL` on error.

[nullable]

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.

#### Parameters

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.

#### Parameters

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()`.

#### Parameters

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

#### Parameters

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.

#### Parameters

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()`.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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()`.

#### Parameters

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_initial_setup_sync ()

    gboolean
    camel_store_initial_setup_sync (CamelStore *store,
                                    GHashTable **out_save_setup,
                                    GCancellable *cancellable,
                                    GError **error);

Runs initial setup for the `store` . It's meant to preset some values the first time the account connects to the server after it had been created. The function should return `TRUE` even if it didn't populate anything. The default implementation does just that.

The save_setup result, if not `NULL`, should be freed using `g_hash_table_destroy()`. It's not an error to have it `NULL`, it only means the `store` doesn't have anything to save. Both the key and the value in the hash are newly allocated UTF-8 strings, owned by the hash table.

The `store` advertises support of this function by including CAMEL_STORE_SUPPORTS_INITIAL_SETUP in CamelStore::flags.

#### Parameters

store | a CamelStore |
out_save_setup | setup values to save. | [out][transfer container][element-type utf8 utf8]
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` on success, `FALSE` on error

Since: 3.20

### camel_store_initial_setup ()

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

Runs initial setup for the `store` asynchronously.

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

The `store` advertises support of this function by including CAMEL_STORE_SUPPORTS_INITIAL_SETUP in CamelStore::flags.

#### Parameters

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.20

### camel_store_initial_setup_finish ()

    gboolean
    camel_store_initial_setup_finish (CamelStore *store,
                                      GAsyncResult *result,
                                      GHashTable **out_save_setup,
                                      GError **error);

Finishes the operation started with `camel_store_initial_setup()`.

The save_setup result, if not `NULL`, should be freed using `g_hash_table_destroy()`. It's not an error to have it `NULL`, it only means the `store` doesn't have anything to save.

#### Parameters

store | a CamelStore |
result | a GAsyncResult |
out_save_setup | setup values to save. | [out][transfer container][element-type utf8 utf8]
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` on success, `FALSE` on error

Since: 3.20

### camel_store_maybe_run_db_maintenance ()

    gboolean
    camel_store_maybe_run_db_maintenance (CamelStore *store,
                                          GError **error);

Checks the state of the current CamelDB used for the `store` and eventually runs maintenance routines on it.

#### Parameters

store | a CamelStore instance |
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded.

Since: 3.16

### camel_store_delete_cached_folder ()

    void
    camel_store_delete_cached_folder (CamelStore *store,
                                      const gchar *folder_name);

Deletes local data for the given `folder_name` . The folder should be part of the opened folders.

It doesn't delete the folder in the store (server) as such. Use `camel_store_delete_folder()`, or its synchronous variant, if you want to do that instead.

#### Parameters

store | a CamelStore |
folder_name | a folder full name to delete from the cache |

Since: 3.24

### camel_store_get_can_auto_save_changes ()

    gboolean
    camel_store_get_can_auto_save_changes (CamelStore *store);

Returns whether there can be done automatic save of folder changes. Default is TRUE. The descendants can overwrite it with CamelStoreClass::`get_can_auto_save_changes()`.

Return: Whether there can be done automatic save of folder changes.

#### Parameters

store | a CamelStore |

Since: 3.40

## Types and Values

### CAMEL_STORE_ERROR

    #define             CAMEL_STORE_ERROR

Since: 2.32

### CAMEL_STORE_SETUP_ARCHIVE_FOLDER

    #define CAMEL_STORE_SETUP_ARCHIVE_FOLDER "Account:Mail Account:archive-folder:f"

### CAMEL_STORE_SETUP_DRAFTS_FOLDER

    #define CAMEL_STORE_SETUP_DRAFTS_FOLDER		"Submission:Mail Composition:drafts-folder:f"

### CAMEL_STORE_SETUP_SENT_FOLDER

    #define CAMEL_STORE_SETUP_SENT_FOLDER		"Submission:Mail Submission:sent-folder:f"

### CAMEL_STORE_SETUP_TEMPLATES_FOLDER

    #define CAMEL_STORE_SETUP_TEMPLATES_FOLDER "Submission:Mail Composition:templates-folder:f"

### enum CamelStoreError

#### Members

CAMEL_STORE_ERROR_INVALID | an invalid store operation had been requested |
CAMEL_STORE_ERROR_NO_FOLDER | requested operation cannot be performed with the given folder |

Since: 2.32

### enum CamelStoreGetFolderFlags

Open mode for folder.

#### Members

CAMEL_STORE_FOLDER_NONE | no flags |
CAMEL_STORE_FOLDER_CREATE | create the folder |
CAMEL_STORE_FOLDER_EXCL | deprecated, not honored |
CAMEL_STORE_FOLDER_BODY_INDEX | save the body index |
CAMEL_STORE_FOLDER_PRIVATE | a private folder that should not show up in unmatched, folder info's, etc. |

## Signal Details

### The `“folder-created”` signal

    void
    user_function (CamelStore      *camelstore,
                   CamelFolderInfo *arg1,
                   gpointer         user_data)

Flags: Run First

### The `“folder-deleted”` signal

    void
    user_function (CamelStore      *camelstore,
                   CamelFolderInfo *arg1,
                   gpointer         user_data)

Flags: Run First

### The `“folder-info-stale”` signal

    void
    user_function (CamelStore *store,
                   gpointer    user_data)

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.

#### Parameters

store | the CamelStore that received the signal |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“folder-opened”` signal

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

Flags: Run First

### The `“folder-renamed”` signal

    void
    user_function (CamelStore      *camelstore,
                   char            *arg1,
                   CamelFolderInfo *arg2,
                   gpointer         user_data)

Flags: Run First