CamelFolder

CamelFolder

Functions

GQuark camel_folder_error_quark ()
void camel_folder_set_lock_async ()
struct _CamelStore * camel_folder_get_parent_store ()
const gchar * camel_folder_get_full_name ()
gchar * camel_folder_dup_full_name ()
void camel_folder_set_full_name ()
const gchar * camel_folder_get_display_name ()
gchar * camel_folder_dup_display_name ()
void camel_folder_set_display_name ()
const gchar * camel_folder_get_description ()
gchar * camel_folder_dup_description ()
void camel_folder_set_description ()
CamelMessageFlags camel_folder_get_permanent_flags ()
CamelMessageFlags camel_folder_get_message_flags ()
gboolean camel_folder_set_message_flags ()
gboolean camel_folder_get_message_user_flag ()
void camel_folder_set_message_user_flag ()
const gchar * camel_folder_get_message_user_tag ()
void camel_folder_set_message_user_tag ()
gboolean camel_folder_has_summary_capability ()
gint camel_folder_get_message_count ()
gint camel_folder_get_unread_message_count ()
gint camel_folder_get_deleted_message_count ()
GPtrArray * camel_folder_get_summary ()
void camel_folder_free_summary ()
#define camel_folder_delete_message()
GPtrArray * camel_folder_get_uids ()
void camel_folder_free_uids ()
GPtrArray * camel_folder_get_uncached_uids ()
gint camel_folder_cmp_uids ()
void camel_folder_sort_uids ()
GPtrArray * camel_folder_search_by_expression ()
GPtrArray * camel_folder_search_by_uids ()
void camel_folder_search_free ()
guint32 camel_folder_count_by_expression ()
CamelMessageInfo * camel_folder_get_message_info ()
void camel_folder_delete ()
void camel_folder_rename ()
void camel_folder_changed ()
void camel_folder_freeze ()
void camel_folder_thaw ()
gboolean camel_folder_is_frozen ()
gint camel_folder_get_frozen_count ()
CamelFolderQuotaInfo * camel_folder_quota_info_new ()
CamelFolderQuotaInfo * camel_folder_quota_info_clone ()
void camel_folder_quota_info_free ()
void camel_folder_free_nop ()
void camel_folder_free_shallow ()
void camel_folder_free_deep ()
gchar * camel_folder_get_filename ()
void camel_folder_lock ()
void camel_folder_unlock ()
gboolean camel_folder_append_message_sync ()
void camel_folder_append_message ()
gboolean camel_folder_append_message_finish ()
gboolean camel_folder_expunge_sync ()
void camel_folder_expunge ()
gboolean camel_folder_expunge_finish ()
CamelMimeMessage * camel_folder_get_message_sync ()
void camel_folder_get_message ()
CamelMimeMessage * camel_folder_get_message_finish ()
CamelFolderQuotaInfo * camel_folder_get_quota_info_sync ()
void camel_folder_get_quota_info ()
CamelFolderQuotaInfo * camel_folder_get_quota_info_finish ()
gboolean camel_folder_purge_message_cache_sync ()
void camel_folder_purge_message_cache ()
gboolean camel_folder_purge_message_cache_finish ()
gboolean camel_folder_refresh_info_sync ()
void camel_folder_refresh_info ()
gboolean camel_folder_refresh_info_finish ()
gboolean camel_folder_synchronize_sync ()
void camel_folder_synchronize ()
gboolean camel_folder_synchronize_finish ()
gboolean camel_folder_synchronize_message_sync ()
void camel_folder_synchronize_message ()
gboolean camel_folder_synchronize_message_finish ()
gboolean camel_folder_transfer_messages_to_sync ()
void camel_folder_transfer_messages_to ()
gboolean camel_folder_transfer_messages_to_finish ()
void camel_folder_prepare_content_refresh ()
CamelFolderChangeInfo * camel_folder_change_info_new ()
void camel_folder_change_info_clear ()
void camel_folder_change_info_free ()
gboolean camel_folder_change_info_changed ()
void camel_folder_change_info_add_source ()
void camel_folder_change_info_add_source_list ()
void camel_folder_change_info_add_update ()
void camel_folder_change_info_add_update_list ()
void camel_folder_change_info_build_diff ()
void camel_folder_change_info_cat ()
void camel_folder_change_info_add_uid ()
void camel_folder_change_info_remove_uid ()
void camel_folder_change_info_change_uid ()
void camel_folder_change_info_recent_uid ()

Properties

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

Object Hierarchy

    GBoxed
    ╰── CamelFolderQuotaInfo
    GObject
    ╰── CamelObject
        ╰── CamelFolder
            ├── CamelOfflineFolder
            ├── CamelLocalFolder
            ├── CamelPOP3Folder
            ╰── CamelVeeFolder

Description

Functions

camel_folder_error_quark ()

GQuark
camel_folder_error_quark (void);

camel_folder_set_lock_async ()

void
camel_folder_set_lock_async (CamelFolder *folder,
                             gboolean skip_folder_lock);

FIXME Document me!

Parameters

folder

a CamelFolder

 

Since: 2.30


camel_folder_get_parent_store ()

struct _CamelStore *
camel_folder_get_parent_store (CamelFolder *folder);

Parameters

folder

a CamelFolder

 

Returns

the parent CamelStore of the folder.

[transfer none]


camel_folder_get_full_name ()

const gchar *
camel_folder_get_full_name (CamelFolder *folder);

Returns the fully qualified name of the folder.

Parameters

folder

a CamelFolder

 

Returns

the fully qualified name of the folder


camel_folder_dup_full_name ()

gchar *
camel_folder_dup_full_name (CamelFolder *folder);

Thread-safe variation of camel_folder_get_full_name(). Use this function when accessing folder from multiple threads.

The returned string should be freed with g_free() when no longer needed.

Parameters

folder

a CamelFolder

 

Returns

a newly-allocated copy of “full-name”

Since: 3.8


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.

Parameters

folder

a CamelFolder

 

full_name

a fully qualified name for the folder

 

Since: 2.32


camel_folder_get_display_name ()

const gchar *
camel_folder_get_display_name (CamelFolder *folder);

Returns the display name for the folder. The fully qualified name can be obtained with camel_folder_get_full_name().

Parameters

folder

a CamelFolder

 

Returns

the display name of the folder

Since: 3.2


camel_folder_dup_display_name ()

gchar *
camel_folder_dup_display_name (CamelFolder *folder);

Thread-safe variation of camel_folder_get_display_name(). Use this function when accessing folder from multiple threads.

The returned string should be freed with g_free() when no longer needed.

Parameters

folder

a CamelFolder

 

Returns

a newly-allocated copy of “display-name”

Since: 3.8


camel_folder_set_display_name ()

void
camel_folder_set_display_name (CamelFolder *folder,
                               const gchar *display_name);

Sets the display name for the folder.

Parameters

folder

a CamelFolder

 

display_name

a display name for the folder

 

Since: 3.2


camel_folder_get_description ()

const gchar *
camel_folder_get_description (CamelFolder *folder);

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

Parameters

folder

a CamelFolder

 

Returns

a description of the folder

Since: 2.32


camel_folder_dup_description ()

gchar *
camel_folder_dup_description (CamelFolder *folder);

Thread-safe variation of camel_folder_get_description(). Use this function when accessing folder from multiple threads.

The returned string should be freed with g_free() when no longer needed.

Parameters

folder

a CamelFolder

 

Returns

a newly-allocated copy of “description”

Since: 3.8


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.

Parameters

folder

a CamelFolder

 

description

a description of the folder

 

Since: 2.32


camel_folder_get_permanent_flags ()

CamelMessageFlags
camel_folder_get_permanent_flags (CamelFolder *folder);

Parameters

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

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

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

Use camel_folder_get_message_info() instead.

Parameters

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,
                                CamelMessageFlags flags,
                                CamelMessageFlags set);

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

Parameters

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

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

Parameters

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

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

Parameters

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

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.

Parameters

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

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

Parameters

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

gboolean
camel_folder_has_summary_capability (CamelFolder *folder);

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

Get whether or not the folder has a summary.

Parameters

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

Parameters

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

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

use camel_object_get() instead.

Parameters

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

Parameters

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

Parameters

folder

a CamelFolder

 

Returns

an array of CamelMessageInfo.

[element-type CamelMessageInfo][transfer none]


camel_folder_free_summary ()

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

Frees the summary array returned by camel_folder_get_summary().

Parameters

folder

a CamelFolder

 

array

the summary array to free.

[element-type CamelMessageInfo]

camel_folder_delete_message()

#define             camel_folder_delete_message(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().

Parameters

folder

a CamelFolder

 

Returns

a GPtrArray of UIDs corresponding to the messages available in the folder.

[element-type utf8][transfer none]


camel_folder_free_uids ()

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

Frees the array of UIDs returned by camel_folder_get_uids().

Parameters

folder

a CamelFolder

 

array

the array of uids to free.

[element-type utf8]

camel_folder_get_uncached_uids ()

GPtrArray *
camel_folder_get_uncached_uids (CamelFolder *folder,
                                GPtrArray *uids,
                                GError **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().

Parameters

folder

a CamelFolder

 

uids

the array of uids to filter down to uncached ones.

[element-type utf8]

Returns

.

[element-type utf8][transfer none]

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.

Parameters

folder

a CamelFolder

 

uid1

The first uid.

 

uid2

the second uid.

 

Since: 2.28


camel_folder_sort_uids ()

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

Sorts the array of UIDs.

Parameters

folder

a CamelFolder

 

uids

array of uids.

[element-type utf8]

Since: 2.24


camel_folder_search_by_expression ()

GPtrArray *
camel_folder_search_by_expression (CamelFolder *folder,
                                   const gchar *expression,
                                   GCancellable *cancellable,
                                   GError **error);

Searches the folder for messages matching the given search expression.

Parameters

folder

a CamelFolder

 

expression

a search expression

 

cancellable

a GCancellable

 

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.

[element-type utf8][transfer full]


camel_folder_search_by_uids ()

GPtrArray *
camel_folder_search_by_uids (CamelFolder *folder,
                             const gchar *expression,
                             GPtrArray *uids,
                             GCancellable *cancellable,
                             GError **error);

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

Parameters

folder

a CamelFolder

 

expression

search expression

 

uids

array of uid's to match against.

[element-type utf8]

cancellable

a GCancellable

 

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.

[element-type utf8][transfer full]


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

Parameters

folder

a CamelFolder

 

result

search results to free.

[element-type utf8]

camel_folder_count_by_expression ()

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

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

Parameters

folder

a CamelFolder

 

expression

a search expression

 

cancellable

a GCancellable

 

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

Parameters

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

void
camel_folder_delete (CamelFolder *folder);

Marks folder as deleted and performs any required cleanup.

This also emits the “deleted” signal from an idle source on the main loop. The idle source's priority is G_PRIORITY_HIGH_IDLE.

Parameters

folder

a CamelFolder

 

camel_folder_rename ()

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

Marks folder as renamed.

This also emits the “renamed” signal from an idle source on the main loop. The idle source's priority is G_PRIORITY_HIGH_IDLE.

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

Parameters

folder

a CamelFolder

 

new_name

new name for the folder

 

camel_folder_changed ()

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

Emits the “changed” signal from an idle source on the main loop. The idle source's priority is G_PRIORITY_LOW.

Parameters

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.

Parameters

folder

a CamelFolder

 

camel_folder_thaw ()

void
camel_folder_thaw (CamelFolder *folder);

Thaws the folder and emits any pending folder_changed signals.

Parameters

folder

a CamelFolder

 

camel_folder_is_frozen ()

gboolean
camel_folder_is_frozen (CamelFolder *folder);

Parameters

folder

a CamelFolder

 

Returns

whether or not the folder is frozen


camel_folder_get_frozen_count ()

gint
camel_folder_get_frozen_count (CamelFolder *folder);

Parameters

folder

a CamelFolder

 

Since: 2.32


camel_folder_quota_info_new ()

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

Parameters

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.

Parameters

info

a CamelFolderQuotaInfo object to clone.

 

Since: 2.24


camel_folder_quota_info_free ()

void
camel_folder_quota_info_free (CamelFolderQuotaInfo *info);

Frees this and all next objects.

Parameters

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.

Parameters

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.

Parameters

folder

a CamelFolder

 

array

an array of uids or CamelMessageInfo.

[element-type utf8]

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.

Parameters

folder

a CamelFolder

 

array

an array of uids.

[element-type utf8]

camel_folder_get_filename ()

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

Since: 2.26


camel_folder_lock ()

void
camel_folder_lock (CamelFolder *folder);

Locks folder . Unlock it with camel_folder_unlock().

Parameters

folder

a CamelFolder

 

Since: 2.32


camel_folder_unlock ()

void
camel_folder_unlock (CamelFolder *folder);

Unlocks folder , previously locked with camel_folder_lock().

Parameters

folder

a CamelFolder

 

Since: 2.32


camel_folder_append_message_sync ()

gboolean
camel_folder_append_message_sync (CamelFolder *folder,
                                  CamelMimeMessage *message,
                                  CamelMessageInfo *info,
                                  gchar **appended_uid,
                                  GCancellable *cancellable,
                                  GError **error);

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

Parameters

folder

a CamelFolder

 

message

a CamelMimeMessage

 

info

a CamelMessageInfo with additional flags/etc to set on the new message, or NULL

 

appended_uid

if non-NULL, the UID of the appended message will be returned here, if it is known

 

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

void
camel_folder_append_message (CamelFolder *folder,
                             CamelMimeMessage *message,
                             CamelMessageInfo *info,
                             gint io_priority,
                             GCancellable *cancellable,
                             GAsyncReadyCallback callback,
                             gpointer user_data);

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

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

Parameters

folder

a CamelFolder

 

message

a CamelMimeMessage

 

info

a CamelMessageInfo with additional flags/etc to set on the new message, or NULL

 

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

gboolean
camel_folder_append_message_finish (CamelFolder *folder,
                                    GAsyncResult *result,
                                    gchar **appended_uid,
                                    GError **error);

Finishes the operation started with camel_folder_append_message_finish().

Parameters

folder

a CamelFolder

 

result

a GAsyncResult

 

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 error

Since: 3.0


camel_folder_expunge_sync ()

gboolean
camel_folder_expunge_sync (CamelFolder *folder,
                           GCancellable *cancellable,
                           GError **error);

Deletes messages which have been marked as "DELETED".

Parameters

folder

a CamelFolder

 

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

void
camel_folder_expunge (CamelFolder *folder,
                      gint io_priority,
                      GCancellable *cancellable,
                      GAsyncReadyCallback callback,
                      gpointer user_data);

Asynchronously deletes messages which have been marked as "DELETED".

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

Parameters

folder

a CamelFolder

 

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

gboolean
camel_folder_expunge_finish (CamelFolder *folder,
                             GAsyncResult *result,
                             GError **error);

Finishes the operation started with camel_folder_expunge().

Parameters

folder

a CamelFolder

 

result

a GAsyncResult

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on error

Since: 3.0


camel_folder_get_message_sync ()

CamelMimeMessage *
camel_folder_get_message_sync (CamelFolder *folder,
                               const gchar *message_uid,
                               GCancellable *cancellable,
                               GError **error);

Gets the message corresponding to message_uid from folder .

Parameters

folder

a CamelFolder

 

message_uid

the message UID

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

a CamelMimeMessage corresponding to the requested UID.

[transfer none]

Since: 3.0


camel_folder_get_message ()

void
camel_folder_get_message (CamelFolder *folder,
                          const gchar *message_uid,
                          gint io_priority,
                          GCancellable *cancellable,
                          GAsyncReadyCallback callback,
                          gpointer user_data);

Asynchronously gets the message corresponding to message_uid from folder .

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

Parameters

folder

a CamelFolder

 

message_uid

the message UID

 

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

CamelMimeMessage *
camel_folder_get_message_finish (CamelFolder *folder,
                                 GAsyncResult *result,
                                 GError **error);

Finishes the operation started with camel_folder_get_message().

Parameters

folder

a CamelFolder

 

result

a GAsyncResult

 

error

return location for a GError or NULL

 

Returns

a CamelMimeMessage corresponding to the requested UID.

[transfer none]

Since: 3.0


camel_folder_get_quota_info_sync ()

CamelFolderQuotaInfo *
camel_folder_get_quota_info_sync (CamelFolder *folder,
                                  GCancellable *cancellable,
                                  GError **error);

Gets a list of known quotas for folder . Free the returned CamelFolderQuotaInfo struct with camel_folder_quota_info_free().

If quotas are not supported for folder , the function returns NULL and sets error to G_IO_ERROR_NOT_SUPPORTED.

Parameters

folder

a CamelFolder

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

a CamelFolderQuotaInfo, or NULL

Since: 3.2


camel_folder_get_quota_info ()

void
camel_folder_get_quota_info (CamelFolder *folder,
                             gint io_priority,
                             GCancellable *cancellable,
                             GAsyncReadyCallback callback,
                             gpointer user_data);

Asynchronously gets a list of known quotas for folder .

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

Parameters

folder

a CamelFolder

 

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


camel_folder_get_quota_info_finish ()

CamelFolderQuotaInfo *
camel_folder_get_quota_info_finish (CamelFolder *folder,
                                    GAsyncResult *result,
                                    GError **error);

Finishes the operation started with camel_folder_get_quota_info(). Free the returned CamelFolderQuotaInfo struct with camel_folder_quota_info_free().

If quotas are not supported for folder , the function returns NULL and sets error to G_IO_ERROR_NOT_SUPPORTED.

Parameters

folder

a CamelFolder

 

result

a GAsyncResult

 

error

return location for a GError or NULL

 

Returns

a CamelFolderQuotaInfo, or NULL

Since: 3.2


camel_folder_purge_message_cache_sync ()

gboolean
camel_folder_purge_message_cache_sync (CamelFolder *folder,
                                       gchar *start_uid,
                                       gchar *end_uid,
                                       GCancellable *cancellable,
                                       GError **error);

Delete the local cache of all messages between these uids.

Parameters

folder

a CamelFolder

 

start_uid

the start message UID

 

end_uid

the end message UID

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on failure

Since: 3.4


camel_folder_purge_message_cache ()

void
camel_folder_purge_message_cache (CamelFolder *folder,
                                  gchar *start_uid,
                                  gchar *end_uid,
                                  gint io_priority,
                                  GCancellable *cancellable,
                                  GAsyncReadyCallback callback,
                                  gpointer user_data);

Delete the local cache of all messages between these uids.

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

Parameters

folder

a CamelFolder

 

start_uid

the start message UID

 

end_uid

the end message UID

 

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


camel_folder_purge_message_cache_finish ()

gboolean
camel_folder_purge_message_cache_finish
                               (CamelFolder *folder,
                                GAsyncResult *result,
                                GError **error);

Finishes the operation started with camel_folder_purge_message_cache().

Parameters

folder

a CamelFolder

 

result

a GAsyncResult

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on failure

Since: 3.4


camel_folder_refresh_info_sync ()

gboolean
camel_folder_refresh_info_sync (CamelFolder *folder,
                                GCancellable *cancellable,
                                GError **error);

Synchronizes a folder's summary with its backing store.

Parameters

folder

a CamelFolder

 

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

void
camel_folder_refresh_info (CamelFolder *folder,
                           gint io_priority,
                           GCancellable *cancellable,
                           GAsyncReadyCallback callback,
                           gpointer user_data);

Asynchronously synchronizes a folder's summary with its backing store.

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

Parameters

folder

a CamelFolder

 

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


camel_folder_refresh_info_finish ()

gboolean
camel_folder_refresh_info_finish (CamelFolder *folder,
                                  GAsyncResult *result,
                                  GError **error);

Finishes the operation started with camel_folder_refresh_info().

Parameters

folder

a CamelFolder

 

result

a GAsyncResult

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on error

Since: 3.2


camel_folder_synchronize_sync ()

gboolean
camel_folder_synchronize_sync (CamelFolder *folder,
                               gboolean expunge,
                               GCancellable *cancellable,
                               GError **error);

Synchronizes any changes that have been made to folder to its backing store, optionally expunging deleted messages as well.

Parameters

folder

a CamelFolder

 

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

void
camel_folder_synchronize (CamelFolder *folder,
                          gboolean expunge,
                          gint io_priority,
                          GCancellable *cancellable,
                          GAsyncReadyCallback callback,
                          gpointer user_data);

Synchronizes any changes that have been made to folder to its backing store asynchronously, optionally expunging deleted messages as well.

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

Parameters

folder

a CamelFolder

 

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

gboolean
camel_folder_synchronize_finish (CamelFolder *folder,
                                 GAsyncResult *result,
                                 GError **error);

Finishes the operation started with camel_folder_synchronize().

Parameters

folder

a CamelFolder

 

result

a GAsyncResult

 

error

return location for a GError, or NULL

 

Returns

TRUE on sucess, FALSE on error

Since: 3.0


camel_folder_synchronize_message_sync ()

gboolean
camel_folder_synchronize_message_sync (CamelFolder *folder,
                                       const gchar *message_uid,
                                       GCancellable *cancellable,
                                       GError **error);

Ensure that a message identified by message_uid has been synchronized in folder so that calling camel_folder_get_message() on it later will work in offline mode.

Parameters

folder

a CamelFolder

 

message_uid

a message UID

 

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

void
camel_folder_synchronize_message (CamelFolder *folder,
                                  const gchar *message_uid,
                                  gint io_priority,
                                  GCancellable *cancellable,
                                  GAsyncReadyCallback callback,
                                  gpointer user_data);

Asynchronously ensure that a message identified by message_uid has been synchronized in folder so that calling camel_folder_get_message() on it later will work in offline mode.

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

Parameters

folder

a CamelFolder

 

message_uid

a message UID

 

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

gboolean
camel_folder_synchronize_message_finish
                               (CamelFolder *folder,
                                GAsyncResult *result,
                                GError **error);

Finishes the operation started with camel_folder_synchronize_message().

Parameters

folder

a CamelFolder

 

result

a GAsyncResult

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on error

Since: 3.0


camel_folder_transfer_messages_to_sync ()

gboolean
camel_folder_transfer_messages_to_sync
                               (CamelFolder *source,
                                GPtrArray *message_uids,
                                CamelFolder *destination,
                                gboolean delete_originals,
                                GPtrArray **transferred_uids,
                                GCancellable *cancellable,
                                GError **error);

Copies or moves messages from one folder to another. If the source and destination folders have the same parent_store, this may be more efficient than using camel_folder_append_message_sync().

Parameters

source

the source CamelFolder

 

message_uids

message UIDs in source .

[element-type utf8]

destination

the destination CamelFolder

 

delete_originals

whether or not to delete the original messages

 

transferred_uids

if non-NULL, the UIDs of the resulting messages in destination will be stored here, if known.

[element-type utf8][out]

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

void
camel_folder_transfer_messages_to (CamelFolder *source,
                                   GPtrArray *message_uids,
                                   CamelFolder *destination,
                                   gboolean delete_originals,
                                   gint io_priority,
                                   GCancellable *cancellable,
                                   GAsyncReadyCallback callback,
                                   gpointer user_data);

Asynchronously copies or moves messages from one folder to another. If the source or destination folders have the same parent store, this may be more efficient than using camel_folder_append_message().

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

Parameters

source

the source CamelFolder

 

message_uids

message UIDs in source .

[element-type utf8]

destination

the destination CamelFolder

 

delete_originals

whether or not to delete the original messages

 

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

gboolean
camel_folder_transfer_messages_to_finish
                               (CamelFolder *source,
                                GAsyncResult *result,
                                GPtrArray **transferred_uids,
                                GError **error);

Finishes the operation started with camel_folder_transfer_messages_to().

Parameters

source

a CamelFolder

 

result

a GAsyncResult

 

transferred_uids

if non-NULL, the UIDs of the resulting messages in destination will be stored here, if known.

[element-type utf8][out]

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on error

Since: 3.0


camel_folder_prepare_content_refresh ()

void
camel_folder_prepare_content_refresh (CamelFolder *folder);

Lets the folder know that it should refresh its content the next time from fresh. This is useful for remote accounts, to fully re-check the folder content against the server.

Parameters

folder

a CamelFolder

 

Since: 3.22


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.

Parameters


camel_folder_change_info_free ()

void
camel_folder_change_info_free (CamelFolderChangeInfo *info);

Free memory associated with the folder change info lists.

Parameters


camel_folder_change_info_changed ()

gboolean
camel_folder_change_info_changed (CamelFolderChangeInfo *info);

Gets whether or not there have been any changes.

Parameters

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.

Parameters

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.

Parameters

info

a CamelFolderChangeInfo

 

list

a list of uids.

[element-type utf8][transfer container]

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.

Parameters

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.

Parameters

info

a CamelFolderChangeInfo

 

list

a list of uids.

[element-type utf8][transfer container]

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.

Parameters


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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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

Parameters

info

a CamelFolderChangeInfo

 

uid

a uid

 

Types and Values

CAMEL_FOLDER_ERROR

#define             CAMEL_FOLDER_ERROR

Since: 2.32


enum CamelFolderError

Members

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

   

Since: 2.32


enum CamelFetchType

Members

CAMEL_FETCH_OLD_MESSAGES

   

CAMEL_FETCH_NEW_MESSAGES

   

Since: 3.4


struct CamelFolderChangeInfo

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

	CamelFolderChangeInfoPrivate *priv;
};

struct CamelFolderQuotaInfo

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

	struct _CamelFolderQuotaInfo *next;
};

Since: 2.24


CamelFolderChangeInfoPrivate

typedef struct _CamelFolderChangeInfoPrivate CamelFolderChangeInfoPrivate;

Property Details

The “description” property

  “description”              gchar *

The folder's description.

Flags: Read / Write / Construct

Default value: NULL


The “display-name” property

  “display-name”             gchar *

The folder's display name.

Flags: Read / Write / Construct

Default value: NULL


The “full-name” property

  “full-name”                gchar *

The folder's fully qualified name.

Flags: Read / Write / Construct

Default value: NULL


The “parent-store” property

  “parent-store”             CamelStore *

The CamelStore to which the folder belongs.

Flags: Read / Write / Construct Only

Signal Details

The “changed” signal

void
user_function (CamelFolder *folder,
               gpointer     arg1,
               gpointer     user_data)

Parameters

folder

the CamelFolder which emitted the signal

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “deleted” signal

void
user_function (CamelFolder *folder,
               gpointer     user_data)

Parameters

folder

the CamelFolder which emitted the signal

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “renamed” signal

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

Parameters

folder

the CamelFolder which emitted the signal

 

old_name

the previous folder name

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First