CamelFolder

## CamelFolder CamelFolder |

## Synopsis

                        CamelFolder;
    #define             CAMEL_FOLDER_ERROR
    enum                CamelFolderError;
                        CamelFolderChangeInfo;
                        CamelFolderQuotaInfo;
    #define             CAMEL_FOLDER_HAS_SUMMARY_CAPABILITY
    #define             CAMEL_FOLDER_HAS_SEARCH_CAPABILITY
    #define             CAMEL_FOLDER_FILTER_RECENT
    #define             CAMEL_FOLDER_HAS_BEEN_DELETED
    #define             CAMEL_FOLDER_IS_TRASH
    #define             CAMEL_FOLDER_IS_JUNK
    #define             CAMEL_FOLDER_FILTER_JUNK
    gboolean            camel_folder_refresh_info           (CamelFolder *folder,
                                                             GError **error);
    gboolean            camel_folder_sync                   (CamelFolder *folder,
                                                             gboolean expunge,
                                                             GError **error);
    void                camel_folder_set_lock_async         (CamelFolder *folder,
                                                             gboolean skip_folder_lock);
    struct _CamelStore * camel_folder_get_parent_store      (CamelFolder *folder);
    gboolean            camel_folder_expunge                (CamelFolder *folder,
                                                             GError **error);
    const gchar *       camel_folder_get_name               (CamelFolder *folder);
    void                camel_folder_set_name               (CamelFolder *folder,
                                                             const gchar *name);
    const gchar *       camel_folder_get_full_name          (CamelFolder *folder);
    void                camel_folder_set_full_name          (CamelFolder *folder,
                                                             const gchar *full_name);
    const gchar *       camel_folder_get_description        (CamelFolder *folder);
    void                camel_folder_set_description        (CamelFolder *folder,
                                                             const gchar *description);
    guint32             camel_folder_get_permanent_flags    (CamelFolder *folder);
    guint32             camel_folder_get_message_flags      (CamelFolder *folder,
                                                             const gchar *uid);
    gboolean            camel_folder_set_message_flags      (CamelFolder *folder,
                                                             const gchar *uid,
                                                             guint32 flags,
                                                             guint32 set);
    gboolean            camel_folder_get_message_user_flag  (CamelFolder *folder,
                                                             const gchar *uid,
                                                             const gchar *name);
    void                camel_folder_set_message_user_flag  (CamelFolder *folder,
                                                             const gchar *uid,
                                                             const gchar *name,
                                                             gboolean value);
    const gchar *       camel_folder_get_message_user_tag   (CamelFolder *folder,
                                                             const gchar *uid,
                                                             const gchar *name);
    void                camel_folder_set_message_user_tag   (CamelFolder *folder,
                                                             const gchar *uid,
                                                             const gchar *name,
                                                             const gchar *value);
    gboolean            camel_folder_append_message         (CamelFolder *folder,
                                                             CamelMimeMessage *message,
                                                             const CamelMessageInfo *info,
                                                             gchar **appended_uid,
                                                             GError **error);
    gboolean            camel_folder_has_summary_capability (CamelFolder *folder);
    gint                camel_folder_get_message_count      (CamelFolder *folder);
    gint                camel_folder_get_unread_message_count
                                                            (CamelFolder *folder);
    gint                camel_folder_get_deleted_message_count
                                                            (CamelFolder *folder);
    GPtrArray *         camel_folder_get_summary            (CamelFolder *folder);
    void                camel_folder_free_summary           (CamelFolder *folder,
                                                             GPtrArray *array);
    CamelMimeMessage *  camel_folder_get_message            (CamelFolder *folder,
                                                             const gchar *uid,
                                                             GError **error);
    gboolean            camel_folder_sync_message           (CamelFolder *folder,
                                                             const gchar *uid,
                                                             GError **error);
    #define             camel_folder_delete_message         (folder,
                                                             uid)
    GPtrArray *         camel_folder_get_uids               (CamelFolder *folder);
    void                camel_folder_free_uids              (CamelFolder *folder,
                                                             GPtrArray *array);
    GPtrArray *         camel_folder_get_uncached_uids      (CamelFolder *folder,
                                                             GPtrArray *uids,
                                                             GError **error);
    gint                camel_folder_cmp_uids               (CamelFolder *folder,
                                                             const gchar *uid1,
                                                             const gchar *uid2);
    void                camel_folder_sort_uids              (CamelFolder *folder,
                                                             GPtrArray *uids);
    gboolean            camel_folder_has_search_capability  (CamelFolder *folder);
    GPtrArray *         camel_folder_search_by_expression   (CamelFolder *folder,
                                                             const gchar *expr,
                                                             GError **error);
    GPtrArray *         camel_folder_search_by_uids         (CamelFolder *folder,
                                                             const gchar *expr,
                                                             GPtrArray *uids,
                                                             GError **error);
    void                camel_folder_search_free            (CamelFolder *folder,
                                                             GPtrArray *result);
    guint32             camel_folder_count_by_expression    (CamelFolder *folder,
                                                             const gchar *expression,
                                                             GError **error);
    CamelMessageInfo *  camel_folder_get_message_info       (CamelFolder *folder,
                                                             const gchar *uid);
    void                camel_folder_free_message_info      (CamelFolder *folder,
                                                             CamelMessageInfo *info);
    void                camel_folder_ref_message_info       (CamelFolder *folder,
                                                             CamelMessageInfo *info);
    gboolean            camel_folder_transfer_messages_to   (CamelFolder *source,
                                                             GPtrArray *uids,
                                                             CamelFolder *dest,
                                                             GPtrArray **transferred_uids,
                                                             gboolean delete_originals,
                                                             GError **error);
    void                camel_folder_delete                 (CamelFolder *folder);
    void                camel_folder_rename                 (CamelFolder *folder,
                                                             const gchar *new);
    void                camel_folder_changed                (CamelFolder *folder,
                                                             CamelFolderChangeInfo *changes);
    void                camel_folder_freeze                 (CamelFolder *folder);
    void                camel_folder_thaw                   (CamelFolder *folder);
    gboolean            camel_folder_is_frozen              (CamelFolder *folder);
    gint                camel_folder_get_frozen_count       (CamelFolder *folder);
    CamelFolderQuotaInfo * camel_folder_get_quota_info      (CamelFolder *folder);
    CamelFolderQuotaInfo * camel_folder_quota_info_new      (const gchar *name,
                                                             guint64 used,
                                                             guint64 total);
    CamelFolderQuotaInfo * camel_folder_quota_info_clone    (const CamelFolderQuotaInfo *info);
    void                camel_folder_quota_info_free        (CamelFolderQuotaInfo *info);
    void                camel_folder_free_nop               (CamelFolder *folder,
                                                             GPtrArray *array);
    void                camel_folder_free_shallow           (CamelFolder *folder,
                                                             GPtrArray *array);
    void                camel_folder_free_deep              (CamelFolder *folder,
                                                             GPtrArray *array);
    gchar *             camel_folder_get_filename           (CamelFolder *folder,
                                                             const gchar *uid,
                                                             GError **error);
    CamelFolderChangeInfo * camel_folder_change_info_new    (void);
    void                camel_folder_change_info_clear      (CamelFolderChangeInfo *info);
    void                camel_folder_change_info_free       (CamelFolderChangeInfo *info);
    gboolean            camel_folder_change_info_changed    (CamelFolderChangeInfo *info);
    void                camel_folder_change_info_add_source (CamelFolderChangeInfo *info,
                                                             const gchar *uid);
    void                camel_folder_change_info_add_source_list
                                                            (CamelFolderChangeInfo *info,
                                                             const GPtrArray *list);
    void                camel_folder_change_info_add_update (CamelFolderChangeInfo *info,
                                                             const gchar *uid);
    void                camel_folder_change_info_add_update_list
                                                            (CamelFolderChangeInfo *info,
                                                             const GPtrArray *list);
    void                camel_folder_change_info_build_diff (CamelFolderChangeInfo *info);
    void                camel_folder_change_info_cat        (CamelFolderChangeInfo *info,
                                                             CamelFolderChangeInfo *src);
    void                camel_folder_change_info_add_uid    (CamelFolderChangeInfo *info,
                                                             const gchar *uid);
    void                camel_folder_change_info_remove_uid (CamelFolderChangeInfo *info,
                                                             const gchar *uid);
    void                camel_folder_change_info_change_uid (CamelFolderChangeInfo *info,
                                                             const gchar *uid);
    void                camel_folder_change_info_recent_uid (CamelFolderChangeInfo *info,
                                                             const gchar *uid);
    enum                CamelFolderLock;
    void                camel_folder_lock                   (CamelFolder *folder,
                                                             CamelFolderLock lock);
    void                camel_folder_unlock                 (CamelFolder *folder,
                                                             CamelFolderLock lock);

## Object Hierarchy

      GObject
       +----CamelObject
             +----CamelFolder
                   +----CamelDiscoFolder
                   +----CamelOfflineFolder
                   +----CamelVeeFolder

## Properties

      "description"              gchar*                : Read / Write / Construct
      "full-name"                gchar*                : Read / Write / Construct
      "name"                     gchar*                : Read / Write / Construct
      "parent-store"             CamelStore*           : Read / Write / Construct Only

## Signals

      "changed"                                        : Run First
      "deleted"                                        : Run First
      "renamed"                                        : Run First

## Description

## Details

### CamelFolder

    typedef struct _CamelFolder CamelFolder;

### CAMEL_FOLDER_ERROR

    #define             CAMEL_FOLDER_ERROR

Since 2.32

### enum CamelFolderError

    typedef enum {
    	CAMEL_FOLDER_ERROR_INVALID,
    	CAMEL_FOLDER_ERROR_INVALID_STATE,
    	CAMEL_FOLDER_ERROR_NON_EMPTY,
    	CAMEL_FOLDER_ERROR_NON_UID,
    	CAMEL_FOLDER_ERROR_INSUFFICIENT_PERMISSION,
    	CAMEL_FOLDER_ERROR_INVALID_PATH,
    	CAMEL_FOLDER_ERROR_INVALID_UID,
    	CAMEL_FOLDER_ERROR_SUMMARY_INVALID
    } CamelFolderError;

Since 2.32

### CamelFolderChangeInfo

    typedef struct {
    	GPtrArray *uid_added;
    	GPtrArray *uid_removed;
    	GPtrArray *uid_changed;
    	GPtrArray *uid_recent;

    	CamelFolderChangeInfoPrivate *priv;
    } CamelFolderChangeInfo;

### CamelFolderQuotaInfo

    typedef struct {
    	gchar *name;
    	guint64 used;
    	guint64 total;

    	struct _CamelFolderQuotaInfo *next;
    } CamelFolderQuotaInfo;

Since 2.24

### CAMEL_FOLDER_HAS_SUMMARY_CAPABILITY

    #define CAMEL_FOLDER_HAS_SUMMARY_CAPABILITY (1<<0)

### CAMEL_FOLDER_HAS_SEARCH_CAPABILITY

    #define CAMEL_FOLDER_HAS_SEARCH_CAPABILITY  (1<<1)

### CAMEL_FOLDER_FILTER_RECENT

    #define CAMEL_FOLDER_FILTER_RECENT          (1<<2)

### CAMEL_FOLDER_HAS_BEEN_DELETED

    #define CAMEL_FOLDER_HAS_BEEN_DELETED       (1<<3)

### CAMEL_FOLDER_IS_TRASH

    #define CAMEL_FOLDER_IS_TRASH               (1<<4)

### CAMEL_FOLDER_IS_JUNK

    #define CAMEL_FOLDER_IS_JUNK                (1<<5)

### CAMEL_FOLDER_FILTER_JUNK

    #define CAMEL_FOLDER_FILTER_JUNK	    (1<<6)

### camel_folder_refresh_info ()

    gboolean            camel_folder_refresh_info           (CamelFolder *folder,
                                                             GError **error);

Updates a folder's summary to be in sync with its backing store.

`folder` : | a CamelFolder
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### camel_folder_sync ()

    gboolean            camel_folder_sync                   (CamelFolder *folder,
                                                             gboolean expunge,
                                                             GError **error);

Sync changes made to a folder to its backing store, possibly expunging deleted messages as well.

`folder` : | a CamelFolder
`expunge` : | whether or not to expunge deleted messages
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### camel_folder_set_lock_async ()

    void                camel_folder_set_lock_async         (CamelFolder *folder,
                                                             gboolean skip_folder_lock);

FIXME Document me!

`folder` : | a CamelFolder

Since 2.30

### camel_folder_get_parent_store ()

    struct _CamelStore * camel_folder_get_parent_store      (CamelFolder *folder);

`folder` : | a CamelFolder
Returns : | the parent CamelStore of the folder

### camel_folder_expunge ()

    gboolean            camel_folder_expunge                (CamelFolder *folder,
                                                             GError **error);

Delete messages which have been marked as "DELETED"

`folder` : | a CamelFolder
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### camel_folder_get_name ()

    const gchar *       camel_folder_get_name               (CamelFolder *folder);

Returns the short name of the folder. The fully qualified name can be obtained with `camel_folder_get_full_name()`.

`folder` : | a CamelFolder
Returns : | the short name of the folder

### camel_folder_set_name ()

    void                camel_folder_set_name               (CamelFolder *folder,
                                                             const gchar *name);

Sets the short name of the folder.

`folder` : | a CamelFolder
`name` : | a name for the folder

Since 2.32

### camel_folder_get_full_name ()

    const gchar *       camel_folder_get_full_name          (CamelFolder *folder);

Returns the fully qualified name of the folder.

`folder` : | a CamelFolder
Returns : | the fully qualified name of the folder

### camel_folder_set_full_name ()

    void                camel_folder_set_full_name          (CamelFolder *folder,
                                                             const gchar *full_name);

Sets the fully qualified name of the folder.

`folder` : | a CamelFolder
`full_name` : | a fully qualified name for the folder

Since 2.32

### camel_folder_get_description ()

    const gchar *       camel_folder_get_description        (CamelFolder *folder);

Returns a description of the folder suitable for displaying to the user.

`folder` : | a CamelFolder
Returns : | a description of the folder

Since 2.32

### camel_folder_set_description ()

    void                camel_folder_set_description        (CamelFolder *folder,
                                                             const gchar *description);

Sets a description of the folder suitable for displaying to the user.

`folder` : | a CamelFolder
`description` : | a description of the folder

Since 2.32

### camel_folder_get_permanent_flags ()

    guint32             camel_folder_get_permanent_flags    (CamelFolder *folder);

`folder` : | a CamelFolder
Returns : | the set of CamelMessageFlags that can be permanently stored on a message between sessions. If it includes CAMEL_FLAG_USER, then user-defined flags will be remembered.

### camel_folder_get_message_flags ()

    guint32             camel_folder_get_message_flags      (CamelFolder *folder,
                                                             const gchar *uid);

### Warning

`camel_folder_get_message_flags` is deprecated and should not be used in newly-written code. Use camel_folder_get_message_info instead.

`folder` : | a CamelFolder
`uid` : | the UID of a message in `folder`
Returns : | the CamelMessageFlags that are set on the indicated message.

### camel_folder_set_message_flags ()

    gboolean            camel_folder_set_message_flags      (CamelFolder *folder,
                                                             const gchar *uid,
                                                             guint32 flags,
                                                             guint32 set);

### Warning

`camel_folder_set_message_flags` is deprecated and should not be used in newly-written code. Use camel_message_info_set_flags on the message info directly (when it works)

Sets those flags specified by `flags` to the values specified by `set` on the indicated message. (This may or may not persist after the folder or store is closed. See camel_folder_get_permanent_flags)

E.g. to set the deleted flag and clear the draft flag, use camel_folder_set_message_flags (folder, uid, CAMEL_MESSAGE_DELETED|CAMEL_MESSAGE_DRAFT, CAMEL_MESSAGE_DELETED);

`folder` : | a CamelFolder
`uid` : | the UID of a message in `folder`
`flags` : | a set of CamelMessageFlag values to set
`set` : | the mask of values in `flags` to use.
Returns : | `TRUE` if the flags were changed or `FALSE` otherwise

### camel_folder_get_message_user_flag ()

    gboolean            camel_folder_get_message_user_flag  (CamelFolder *folder,
                                                             const gchar *uid,
                                                             const gchar *name);

### Warning

`camel_folder_get_message_user_flag` is deprecated and should not be used in newly-written code. Use camel_message_info_get_user_flag on the message info directly

`folder` : | a CamelFolder
`uid` : | the UID of a message in `folder`
`name` : | the name of a user flag
Returns : | `TRUE` if the given user flag is set on the message or `FALSE` otherwise

### camel_folder_set_message_user_flag ()

    void                camel_folder_set_message_user_flag  (CamelFolder *folder,
                                                             const gchar *uid,
                                                             const gchar *name,
                                                             gboolean value);

### Warning

`camel_folder_set_message_user_flag` is deprecated and should not be used in newly-written code. Use camel_message_info_set_user_flag on the CamelMessageInfo directly (when it works)

Sets the user flag specified by `name` to the value specified by `value` on the indicated message. (This may or may not persist after the folder or store is closed. See camel_folder_get_permanent_flags)

`folder` : | a CamelFolder
`uid` : | the UID of a message in `folder`
`name` : | the name of the user flag to set
`value` : | the value to set it to

### camel_folder_get_message_user_tag ()

    const gchar *       camel_folder_get_message_user_tag   (CamelFolder *folder,
                                                             const gchar *uid,
                                                             const gchar *name);

### Warning

`camel_folder_get_message_user_tag` is deprecated and should not be used in newly-written code. Use camel_message_info_get_user_tag on the CamelMessageInfo directly.

`folder` : | a CamelFolder
`uid` : | the UID of a message in `folder`
`name` : | the name of a user tag
Returns : | the value of the user tag

### camel_folder_set_message_user_tag ()

    void                camel_folder_set_message_user_tag   (CamelFolder *folder,
                                                             const gchar *uid,
                                                             const gchar *name,
                                                             const gchar *value);

### Warning

`camel_folder_set_message_user_tag` is deprecated and should not be used in newly-written code. Use camel_message_info_set_user_tag on the CamelMessageInfo directly (when it works).

Sets the user tag specified by `name` to the value specified by `value` on the indicated message. (This may or may not persist after the folder or store is closed. See camel_folder_get_permanent_flags)

`folder` : | a CamelFolder
`uid` : | the UID of a message in `folder`
`name` : | the name of the user tag to set
`value` : | the value to set it to

### camel_folder_append_message ()

    gboolean            camel_folder_append_message         (CamelFolder *folder,
                                                             CamelMimeMessage *message,
                                                             const CamelMessageInfo *info,
                                                             gchar **appended_uid,
                                                             GError **error);

Append `message` to `folder`. Only the flag and tag data from `info` are used. If `info` is `NULL`, no flags or tags will be set.

`folder` : | a CamelFolder
`message` : | a CamelMimeMessage object
`info` : | a CamelMessageInfo with additional flags/etc to set on new message, or `NULL`
`appended_uid` : | if non-`NULL`, the UID of the appended message will be returned here, if it is known.
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### camel_folder_has_summary_capability ()

    gboolean            camel_folder_has_summary_capability (CamelFolder *folder);

Get whether or not the folder has a summary.

`folder` : | a CamelFolder
Returns : | `TRUE` if a summary is available or `FALSE` otherwise

### camel_folder_get_message_count ()

    gint                camel_folder_get_message_count      (CamelFolder *folder);

`folder` : | a CamelFolder
Returns : | the number of messages in the folder, or `-1` if unknown

### camel_folder_get_unread_message_count ()

    gint                camel_folder_get_unread_message_count
                                                            (CamelFolder *folder);

### Warning

`camel_folder_get_unread_message_count` is deprecated and should not be used in newly-written code. use camel_object_get instead.

`folder` : | a CamelFolder
Returns : | the number of unread messages in the folder, or `-1` if unknown

### camel_folder_get_deleted_message_count ()

    gint                camel_folder_get_deleted_message_count
                                                            (CamelFolder *folder);

`folder` : | a CamelFolder
Returns : | the number of deleted messages in the folder, or `-1` if unknown

### camel_folder_get_summary ()

    GPtrArray *         camel_folder_get_summary            (CamelFolder *folder);

This returns the summary information for the folder. This array should not be modified, and must be freed with camel_folder_free_summary.

`folder` : | a CamelFolder
Returns : | an array of CamelMessageInfo

### camel_folder_free_summary ()

    void                camel_folder_free_summary           (CamelFolder *folder,
                                                             GPtrArray *array);

Frees the summary array returned by camel_folder_get_summary.

`folder` : | a CamelFolder
`array` : | the summary array to free

### camel_folder_get_message ()

    CamelMimeMessage *  camel_folder_get_message            (CamelFolder *folder,
                                                             const gchar *uid,
                                                             GError **error);

Get a message from its UID in the folder.

`folder` : | a CamelFolder
`uid` : | the UID
`error` : | return location for a GError, or `NULL`
Returns : | a CamelMimeMessage corresponding to `uid`

### camel_folder_sync_message ()

    gboolean            camel_folder_sync_message           (CamelFolder *folder,
                                                             const gchar *uid,
                                                             GError **error);

Ensure that a message identified by UID has been synced in the folder (so that camel_folder_get_message on it later will work in offline mode).

`folder` : | a CamelFolder
`uid` : | the UID
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

Since 2.26

### camel_folder_delete_message()

    #define             camel_folder_delete_message(folder, uid)

`folder` : |
`uid` : |

### camel_folder_get_uids ()

    GPtrArray *         camel_folder_get_uids               (CamelFolder *folder);

Get the list of UIDs available in a folder. This routine is useful for finding what messages are available when the folder does not support summaries. The returned array should not be modified, and must be freed by passing it to camel_folder_free_uids.

`folder` : | a CamelFolder
Returns : | a GPtrArray of UIDs corresponding to the messages available in the folder

### camel_folder_free_uids ()

    void                camel_folder_free_uids              (CamelFolder *folder,
                                                             GPtrArray *array);

Frees the array of UIDs returned by camel_folder_get_uids.

`folder` : | a CamelFolder
`array` : | the array of uids to free

### camel_folder_get_uncached_uids ()

    GPtrArray *         camel_folder_get_uncached_uids      (CamelFolder *folder,
                                                             GPtrArray *uids,
                                                             GError **error);

`folder` : | a CamelFolder
`uids` : | the array of uids to filter down to uncached ones.
`error` : |
Returns : | the known-uncached uids from a list of uids. It may return uids which are locally cached but should never filter out a uid which is not locally cached. Free the result by called camel_folder_free_uids. Frees the array of UIDs returned by camel_folder_get_uids.

Since 2.26

### camel_folder_cmp_uids ()

    gint                camel_folder_cmp_uids               (CamelFolder *folder,
                                                             const gchar *uid1,
                                                             const gchar *uid2);

Compares two uids. The return value meaning is the same as in any other compare function.

Note that the default compare function expects a decimal number at the beginning of a uid, thus if provider uses different uid values, then it should subclass this function.

`folder` : | a CamelFolder
`uid1` : | The first uid.
`uid2` : | the second uid.
Returns : |

Since 2.28

### camel_folder_sort_uids ()

    void                camel_folder_sort_uids              (CamelFolder *folder,
                                                             GPtrArray *uids);

Sorts the array of UIDs.

`folder` : | a CamelFolder
`uids` : | array of uids

Since 2.24

### camel_folder_has_search_capability ()

    gboolean            camel_folder_has_search_capability  (CamelFolder *folder);

Checks if a folder supports searching.

`folder` : | a CamelFolder
Returns : | `TRUE` if the folder supports searching or `FALSE` otherwise

### camel_folder_search_by_expression ()

    GPtrArray *         camel_folder_search_by_expression   (CamelFolder *folder,
                                                             const gchar *expr,
                                                             GError **error);

Searches the folder for messages matching the given search expression.

`folder` : | a CamelFolder
`expr` : | a search expression
`error` : | return location for a GError, or `NULL`
Returns : | a GPtrArray of uids of matching messages. The caller must free the list and each of the elements when it is done.

### camel_folder_search_by_uids ()

    GPtrArray *         camel_folder_search_by_uids         (CamelFolder *folder,
                                                             const gchar *expr,
                                                             GPtrArray *uids,
                                                             GError **error);

Search a subset of uid's for an expression match.

`folder` : | a CamelFolder
`expr` : | search expression
`uids` : | array of uid's to match against.
`error` : | return location for a GError, or `NULL`
Returns : | a GPtrArray of uids of matching messages. The caller must free the list and each of the elements when it is done.

### camel_folder_search_free ()

    void                camel_folder_search_free            (CamelFolder *folder,
                                                             GPtrArray *result);

Free the result of a search as gotten by camel_folder_search or camel_folder_search_by_uids.

`folder` : | a CamelFolder
`result` : | search results to free

### camel_folder_count_by_expression ()

    guint32             camel_folder_count_by_expression    (CamelFolder *folder,
                                                             const gchar *expression,
                                                             GError **error);

Searches the folder for count of messages matching the given search expression.

`folder` : | a CamelFolder
`expression` : |
`error` : | return location for a GError, or `NULL`
Returns : | an interger

Since 2.26

### camel_folder_get_message_info ()

    CamelMessageInfo *  camel_folder_get_message_info       (CamelFolder *folder,
                                                             const gchar *uid);

Retrieve the CamelMessageInfo for the specified `uid`. This return must be freed using camel_folder_free_message_info.

`folder` : | a CamelFolder
`uid` : | the uid of a message
Returns : | the summary information for the indicated message, or `NULL` if the uid does not exist

### camel_folder_free_message_info ()

    void                camel_folder_free_message_info      (CamelFolder *folder,
                                                             CamelMessageInfo *info);

Free (unref) a CamelMessageInfo, previously obtained with camel_folder_get_message_info.

`folder` : | a CamelFolder
`info` : | a CamelMessageInfo

### camel_folder_ref_message_info ()

    void                camel_folder_ref_message_info       (CamelFolder *folder,
                                                             CamelMessageInfo *info);

### Warning

`camel_folder_ref_message_info` is deprecated and should not be used in newly-written code. Use camel_message_info_ref directly.

Ref a CamelMessageInfo, previously obtained with camel_folder_get_message_info.

`folder` : | a CamelFolder
`info` : | a CamelMessageInfo

### camel_folder_transfer_messages_to ()

    gboolean            camel_folder_transfer_messages_to   (CamelFolder *source,
                                                             GPtrArray *uids,
                                                             CamelFolder *dest,
                                                             GPtrArray **transferred_uids,
                                                             gboolean delete_originals,
                                                             GError **error);

This copies or moves messages from one folder to another. If the `source` and `dest` folders have the same parent_store, this may be more efficient than using camel_folder_append_message.

`source` : | the source CamelFolder object
`uids` : | message UIDs in `source`
`dest` : | the destination CamelFolder object
`transferred_uids` : | if non-`NULL`, the UIDs of the resulting messages in `dest` will be stored here, if known.
`delete_originals` : | whether or not to delete the original messages
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### camel_folder_delete ()

    void                camel_folder_delete                 (CamelFolder *folder);

Marks a folder object as deleted and performs any required cleanup.

`folder` : | a CamelFolder

### camel_folder_rename ()

    void                camel_folder_rename                 (CamelFolder *folder,
                                                             const gchar *new);

Mark an active folder object as renamed.

NOTE: This is an internal function used by camel stores, no locking is performed on the folder.

`folder` : | a CamelFolder
`new` : | new name for the folder

### camel_folder_changed ()

    void                camel_folder_changed                (CamelFolder *folder,
                                                             CamelFolderChangeInfo *changes);

Emits the "changed" signal.

`folder` : | a CamelFolder
`changes` : | change information for `folder`

Since 2.32

### camel_folder_freeze ()

    void                camel_folder_freeze                 (CamelFolder *folder);

Freezes the folder so that a series of operation can be performed without "folder_changed" signals being emitted. When the folder is later thawed with camel_folder_thaw, the suppressed signals will be emitted.

`folder` : | a CamelFolder

### camel_folder_thaw ()

    void                camel_folder_thaw                   (CamelFolder *folder);

Thaws the folder and emits any pending folder_changed signals.

`folder` : | a CamelFolder

### camel_folder_is_frozen ()

    gboolean            camel_folder_is_frozen              (CamelFolder *folder);

`folder` : | a CamelFolder
Returns : | whether or not the folder is frozen

### camel_folder_get_frozen_count ()

    gint                camel_folder_get_frozen_count       (CamelFolder *folder);

`folder` : | a CamelFolder
Returns : |

Since 2.32

### camel_folder_get_quota_info ()

    CamelFolderQuotaInfo * camel_folder_get_quota_info      (CamelFolder *folder);

`folder` : | a CamelFolder
Returns : | list of known quota(s) for the folder.

Since 2.24

### camel_folder_quota_info_new ()

    CamelFolderQuotaInfo * camel_folder_quota_info_new      (const gchar *name,
                                                             guint64 used,
                                                             guint64 total);

`name` : | Name of the quota.
`used` : | Current usage of the quota.
`total` : | Total available size of the quota.
Returns : | newly allocated CamelFolderQuotaInfo structure with initialized values based on the parameters, with next member set to NULL.

Since 2.24

### camel_folder_quota_info_clone ()

    CamelFolderQuotaInfo * camel_folder_quota_info_clone    (const CamelFolderQuotaInfo *info);

Makes a copy of the given info and all next-s.

`info` : | a CamelFolderQuotaInfo object to clone.
Returns : |

Since 2.24

### camel_folder_quota_info_free ()

    void                camel_folder_quota_info_free        (CamelFolderQuotaInfo *info);

Frees this and all next objects.

`info` : | a CamelFolderQuotaInfo object to free.

Since 2.24

### camel_folder_free_nop ()

    void                camel_folder_free_nop               (CamelFolder *folder,
                                                             GPtrArray *array);

"Frees" the provided array by doing nothing. Used by CamelFolder subclasses as an implementation for free_uids, or free_summary when the returned array is "static" information and should not be freed.

`folder` : | a CamelFolder
`array` : | an array of uids or CamelMessageInfo

### camel_folder_free_shallow ()

    void                camel_folder_free_shallow           (CamelFolder *folder,
                                                             GPtrArray *array);

Frees the provided array but not its contents. Used by CamelFolder subclasses as an implementation for free_uids or free_summary when the returned array needs to be freed but its contents come from "static" information.

`folder` : | a CamelFolder
`array` : | an array of uids or CamelMessageInfo

### camel_folder_free_deep ()

    void                camel_folder_free_deep              (CamelFolder *folder,
                                                             GPtrArray *array);

Frees the provided array and its contents. Used by CamelFolder subclasses as an implementation for free_uids when the provided information was created explicitly by the corresponding get_ call.

`folder` : | a CamelFolder
`array` : | an array of uids

### camel_folder_get_filename ()

    gchar *             camel_folder_get_filename           (CamelFolder *folder,
                                                             const gchar *uid,
                                                             GError **error);

`folder` : |
`uid` : |
`error` : |
Returns : |

Since 2.26

### camel_folder_change_info_new ()

    CamelFolderChangeInfo * camel_folder_change_info_new    (void);

Create a new folder change info structure.

Change info structures are not MT-SAFE and must be locked for exclusive access externally.

Returns : | a new CamelFolderChangeInfo

### camel_folder_change_info_clear ()

    void                camel_folder_change_info_clear      (CamelFolderChangeInfo *info);

Empty out the change info; called after changes have been processed.

`info` : | a CamelFolderChangeInfo

### camel_folder_change_info_free ()

    void                camel_folder_change_info_free       (CamelFolderChangeInfo *info);

Free memory associated with the folder change info lists.

`info` : | a CamelFolderChangeInfo

### camel_folder_change_info_changed ()

    gboolean            camel_folder_change_info_changed    (CamelFolderChangeInfo *info);

Gets whether or not there have been any changes.

`info` : | a CamelFolderChangeInfo
Returns : | `TRUE` if the changeset contains any changes or `FALSE` otherwise

### camel_folder_change_info_add_source ()

    void                camel_folder_change_info_add_source (CamelFolderChangeInfo *info,
                                                             const gchar *uid);

Add a source uid for generating a changeset.

`info` : | a CamelFolderChangeInfo
`uid` : | a uid

### camel_folder_change_info_add_source_list ()

    void                camel_folder_change_info_add_source_list
                                                            (CamelFolderChangeInfo *info,
                                                             const GPtrArray *list);

Add a list of source uid's for generating a changeset.

`info` : | a CamelFolderChangeInfo
`list` : | a list of uids

### camel_folder_change_info_add_update ()

    void                camel_folder_change_info_add_update (CamelFolderChangeInfo *info,
                                                             const gchar *uid);

Add a uid from the updated list, used to generate a changeset diff.

`info` : | a CamelFolderChangeInfo
`uid` : | a uid

### camel_folder_change_info_add_update_list ()

    void                camel_folder_change_info_add_update_list
                                                            (CamelFolderChangeInfo *info,
                                                             const GPtrArray *list);

Add a list of uid's from the updated list.

`info` : | a CamelFolderChangeInfo
`list` : | a list of uids

### camel_folder_change_info_build_diff ()

    void                camel_folder_change_info_build_diff (CamelFolderChangeInfo *info);

Compare the source uid set to the updated uid set and generate the differences into the added and removed lists.

`info` : | a CamelFolderChangeInfo

### camel_folder_change_info_cat ()

    void                camel_folder_change_info_cat        (CamelFolderChangeInfo *info,
                                                             CamelFolderChangeInfo *src);

Concatenate one change info onto antoher. Can be used to copy them too.

`info` : | a CamelFolderChangeInfo to append to
`src` : | a CamelFolderChangeInfo to append from

### camel_folder_change_info_add_uid ()

    void                camel_folder_change_info_add_uid    (CamelFolderChangeInfo *info,
                                                             const gchar *uid);

Add a new uid to the changeinfo.

`info` : | a CamelFolderChangeInfo
`uid` : | a uid

### camel_folder_change_info_remove_uid ()

    void                camel_folder_change_info_remove_uid (CamelFolderChangeInfo *info,
                                                             const gchar *uid);

Add a uid to the removed uid list.

`info` : | a CamelFolderChangeInfo
`uid` : | a uid

### camel_folder_change_info_change_uid ()

    void                camel_folder_change_info_change_uid (CamelFolderChangeInfo *info,
                                                             const gchar *uid);

Add a uid to the changed uid list.

`info` : | a CamelFolderChangeInfo
`uid` : | a uid

### camel_folder_change_info_recent_uid ()

    void                camel_folder_change_info_recent_uid (CamelFolderChangeInfo *info,
                                                             const gchar *uid);

Add a recent uid to the changedinfo. This will also add the uid to the uid_filter array for potential filtering

`info` : | a CamelFolderChangeInfo
`uid` : | a uid

### enum CamelFolderLock

    typedef enum {
    	CAMEL_FOLDER_CHANGE_LOCK,
    	CAMEL_FOLDER_REC_LOCK
    } CamelFolderLock;

Since 2.32

### camel_folder_lock ()

    void                camel_folder_lock                   (CamelFolder *folder,
                                                             CamelFolderLock lock);

Locks folder's lock. Unlock it with `camel_folder_unlock()`.

`folder` : | a CamelFolder
`lock` : | lock type to lock

Since 2.32

### camel_folder_unlock ()

    void                camel_folder_unlock                 (CamelFolder *folder,
                                                             CamelFolderLock lock);

Unlocks folder's lock, previously locked with `camel_folder_lock()`.

`folder` : | a CamelFolder
`lock` : | lock type to unlock

Since 2.32

## Property Details

### The `"description"` property

      "description"              gchar*                : Read / Write / Construct

The folder's description.

Default value: NULL

### The `"full-name"` property

      "full-name"                gchar*                : Read / Write / Construct

The folder's fully qualified name.

Default value: NULL

### The `"name"` property

      "name"                     gchar*                : Read / Write / Construct

The folder's short name.

Default value: NULL

### The `"parent-store"` property

      "parent-store"             CamelStore*           : Read / Write / Construct Only

The CamelStore to which the folder belongs.

## Signal Details

### The `"changed"` signal

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

`folder` : | the CamelFolder which emitted the signal
`user_data` : | user data set when the signal handler was connected.

### The `"deleted"` signal

    void                user_function                      (CamelFolder *folder,
                                                            gpointer     user_data)      : Run First

`folder` : | the CamelFolder which emitted the signal
`user_data` : | user data set when the signal handler was connected.

### The `"renamed"` signal

    void                user_function                      (CamelFolder *folder,
                                                            gchar       *old_name,
                                                            gpointer     user_data)      : Run First

`folder` : | the CamelFolder which emitted the signal
`old_name` : | the previous folder name
`user_data` : | user data set when the signal handler was connected.