CamelFolderSummary

CamelFolderSummary

Functions

CamelFolderSummary * camel_folder_summary_new ()
struct _CamelFolder * camel_folder_summary_get_folder ()
guint32 camel_folder_summary_get_flags ()
void camel_folder_summary_set_flags ()
gint64 camel_folder_summary_get_timestamp ()
void camel_folder_summary_set_timestamp ()
guint32 camel_folder_summary_get_version ()
void camel_folder_summary_set_version ()
guint32 camel_folder_summary_get_saved_count ()
guint32 camel_folder_summary_get_unread_count ()
guint32 camel_folder_summary_get_deleted_count ()
guint32 camel_folder_summary_get_junk_count ()
guint32 camel_folder_summary_get_junk_not_deleted_count ()
guint32 camel_folder_summary_get_visible_count ()
void camel_folder_summary_set_index ()
CamelIndex * camel_folder_summary_get_index ()
guint32 camel_folder_summary_next_uid ()
void camel_folder_summary_set_next_uid ()
guint32 camel_folder_summary_get_next_uid ()
gchar * camel_folder_summary_next_uid_string ()
gboolean camel_folder_summary_save ()
gboolean camel_folder_summary_load ()
gboolean camel_folder_summary_header_load ()
gboolean camel_folder_summary_header_save ()
void camel_folder_summary_touch ()
CamelMessageInfo * camel_folder_summary_info_new_from_headers ()
CamelMessageInfo * camel_folder_summary_info_new_from_parser ()
CamelMessageInfo * camel_folder_summary_info_new_from_message ()
void camel_folder_summary_add ()
gboolean camel_folder_summary_remove ()
gboolean camel_folder_summary_remove_uid ()
gboolean camel_folder_summary_remove_uids ()
gboolean camel_folder_summary_clear ()
guint camel_folder_summary_count ()
gboolean camel_folder_summary_check_uid ()
CamelMessageInfo * camel_folder_summary_get ()
guint32 camel_folder_summary_get_info_flags ()
GPtrArray * camel_folder_summary_get_array ()
void camel_folder_summary_free_array ()
GHashTable * camel_folder_summary_get_hash ()
gboolean camel_folder_summary_replace_flags ()
CamelMessageInfo * camel_folder_summary_peek_loaded ()
GPtrArray * camel_folder_summary_get_changed ()
void camel_folder_summary_prepare_fetch_all ()
void camel_folder_summary_lock ()
void camel_folder_summary_unlock ()
CamelMessageFlags camel_system_flag ()
gboolean camel_system_flag_get ()
CamelMessageInfo * camel_message_info_new_from_headers ()

Properties

guint deleted-count Read
CamelFolder * folder Read / Write / Construct Only
guint junk-count Read
guint junk-not-deleted-count Read
guint saved-count Read
guint unread-count Read
guint visible-count Read

Signals

void changed Run First

Types and Values

Object Hierarchy

    GObject
    ╰── CamelFolderSummary
        ├── CamelIMAPXSummary
        ├── CamelLocalSummary
        ├── CamelNNTPSummary
        ╰── CamelVeeSummary

Description

Functions

camel_folder_summary_new ()

CamelFolderSummary *
camel_folder_summary_new (struct _CamelFolder *folder);

Create a new CamelFolderSummary object.

Parameters

folder

parent CamelFolder object.

[type CamelFolder]

Returns

a new CamelFolderSummary object


camel_folder_summary_get_folder ()

struct _CamelFolder *
camel_folder_summary_get_folder (CamelFolderSummary *summary);

Parameters

summary

a CamelFolderSummary object

 

Returns

a CamelFolder to which the summary if associated.

[transfer none]

Since: 3.4


camel_folder_summary_get_flags ()

guint32
camel_folder_summary_get_flags (CamelFolderSummary *summary);

Parameters

summary

a CamelFolderSummary

 

Returns

flags of the summary , a bit-or of CamelFolderSummaryFlags

Since: 3.24


camel_folder_summary_set_flags ()

void
camel_folder_summary_set_flags (CamelFolderSummary *summary,
                                guint32 flags);

Sets flags of the summary , a bit-or of CamelFolderSummaryFlags.

Parameters

summary

a CamelFolderSummary

 

flags

flags to set

 

Since: 3.24


camel_folder_summary_get_timestamp ()

gint64
camel_folder_summary_get_timestamp (CamelFolderSummary *summary);

Parameters

summary

a CamelFolderSummary

 

Returns

timestamp of the summary , as set by the descendants

Since: 3.24


camel_folder_summary_set_timestamp ()

void
camel_folder_summary_set_timestamp (CamelFolderSummary *summary,
                                    gint64 timestamp);

Sets timestamp of the summary , provided by the descendants. This doesn't change the 'dirty' flag of the summary .

Parameters

summary

a CamelFolderSummary

 

timestamp

a timestamp to set

 

Since: 3.24


camel_folder_summary_get_version ()

guint32
camel_folder_summary_get_version (CamelFolderSummary *summary);

Parameters

summary

a CamelFolderSummary

 

Returns

version of the summary

Since: 3.24


camel_folder_summary_set_version ()

void
camel_folder_summary_set_version (CamelFolderSummary *summary,
                                  guint32 version);

Sets version of the summary .

Parameters

summary

a CamelFolderSummary

 

version

version to set

 

Since: 3.24


camel_folder_summary_get_saved_count ()

guint32
camel_folder_summary_get_saved_count (CamelFolderSummary *summary);

Parameters

summary

a CamelFolderSummary object

 

Returns

Count of saved infos.

Since: 3.4


camel_folder_summary_get_unread_count ()

guint32
camel_folder_summary_get_unread_count (CamelFolderSummary *summary);

Parameters

summary

a CamelFolderSummary object

 

Returns

Count of unread infos.

Since: 3.4


camel_folder_summary_get_deleted_count ()

guint32
camel_folder_summary_get_deleted_count
                               (CamelFolderSummary *summary);

Parameters

summary

a CamelFolderSummary object

 

Returns

Count of deleted infos.

Since: 3.4


camel_folder_summary_get_junk_count ()

guint32
camel_folder_summary_get_junk_count (CamelFolderSummary *summary);

Parameters

summary

a CamelFolderSummary object

 

Returns

Count of junk infos.

Since: 3.4


camel_folder_summary_get_junk_not_deleted_count ()

guint32
camel_folder_summary_get_junk_not_deleted_count
                               (CamelFolderSummary *summary);

Parameters

summary

a CamelFolderSummary object

 

Returns

Count of junk and not deleted infos.

Since: 3.4


camel_folder_summary_get_visible_count ()

guint32
camel_folder_summary_get_visible_count
                               (CamelFolderSummary *summary);

Parameters

summary

a CamelFolderSummary object

 

Returns

Count of visible (not junk and not deleted) infos.

Since: 3.4


camel_folder_summary_set_index ()

void
camel_folder_summary_set_index (CamelFolderSummary *summary,
                                CamelIndex *index);

Set the index used to index body content. If the index is NULL, or not set (the default), no indexing of body content will take place.

Parameters

summary

a CamelFolderSummary object

 

index

a CamelIndex

 

camel_folder_summary_get_index ()

CamelIndex *
camel_folder_summary_get_index (CamelFolderSummary *summary);

Parameters

summary

a CamelFolderSummary object

 

Returns

a CamelIndex used to index body content.

[transfer none]

Since: 3.4


camel_folder_summary_next_uid ()

guint32
camel_folder_summary_next_uid (CamelFolderSummary *summary);

Generate a new unique uid value as an integer. This may be used to create a unique sequence of numbers.

Parameters

summary

a CamelFolderSummary object

 

Returns

the next unique uid value


camel_folder_summary_set_next_uid ()

void
camel_folder_summary_set_next_uid (CamelFolderSummary *summary,
                                   guint32 uid);

Set the next minimum uid available. This can be used to ensure new uid's do not clash with existing uid's.

Parameters

summary

a CamelFolderSummary object

 

uid

The next minimum uid to assign. To avoid clashing uid's, set this to the uid of a given messages + 1.

 

camel_folder_summary_get_next_uid ()

guint32
camel_folder_summary_get_next_uid (CamelFolderSummary *summary);

Parameters

summary

a CamelFolderSummary object

 

Returns

Next uid currently awaiting for assignment. The difference from camel_folder_summary_next_uid() is that this function returns actual value and doesn't increment it before returning.

Since: 3.4


camel_folder_summary_next_uid_string ()

gchar *
camel_folder_summary_next_uid_string (CamelFolderSummary *summary);

Retrieve the next uid, but as a formatted string.

Parameters

summary

a CamelFolderSummary object

 

Returns

the next uid as an unsigned integer string. This string must be freed by the caller.


camel_folder_summary_save ()

gboolean
camel_folder_summary_save (CamelFolderSummary *summary,
                           GError **error);

Saves the content of the summary to disk. It does nothing, when the summary is not changed or when it doesn't support permanent save.

Parameters

summary

a CamelFolderSummary

 

error

return location for a GError, or NULL

 

Returns

whether succeeded

Since: 3.24


camel_folder_summary_load ()

gboolean
camel_folder_summary_load (CamelFolderSummary *summary,
                           GError **error);

Loads the summary from the disk. It also saves any pending changes first.

Parameters

summary

a CamelFolderSummary

 

error

return location for a GError, or NULL

 

Returns

whether succeeded

Since: 3.24


camel_folder_summary_header_load ()

gboolean
camel_folder_summary_header_load (CamelFolderSummary *summary,
                                  struct _CamelStore *store,
                                  const gchar *folder_name,
                                  GError **error);

Loads a summary header for the summary , which corresponds to folder_name provided by store .

Parameters

summary

a CamelFolderSummary

 

store

a CamelStore

 

folder_name

a folder name corresponding to summary

 

error

return location for a GError, or NULL

 

Returns

whether succeeded

Since: 3.24


camel_folder_summary_header_save ()

gboolean
camel_folder_summary_header_save (CamelFolderSummary *summary,
                                  GError **error);

Saves summary header information into the disk. The function does nothing, if the summary doesn't support save to disk.

Parameters

summary

a CamelFolderSummary

 

error

return location for a GError, or NULL

 

Returns

whether succeeded

Since: 3.24


camel_folder_summary_touch ()

void
camel_folder_summary_touch (CamelFolderSummary *summary);

Mark the summary as changed, so that a save will force it to be written back to disk.

Parameters

summary

a CamelFolderSummary object

 

camel_folder_summary_info_new_from_headers ()

CamelMessageInfo *
camel_folder_summary_info_new_from_headers
                               (CamelFolderSummary *summary,
                                const CamelNameValueArray *headers);

Create a new info record from a header.

Parameters

summary

a CamelFolderSummary object

 

headers

rfc822 headers as CamelNameValueArray

 

Returns

a newly created CamelMessageInfo. Unref it with g_object_unref(), when done with it.

[transfer full]

Since: 3.24


camel_folder_summary_info_new_from_parser ()

CamelMessageInfo *
camel_folder_summary_info_new_from_parser
                               (CamelFolderSummary *summary,
                                CamelMimeParser *parser);

Create a new info record from a parser. If the parser cannot determine a uid, then none will be assigned.

If indexing is enabled, and the parser cannot determine a new uid, then one is automatically assigned.

If indexing is enabled, then the content will be indexed based on this new uid. In this case, the message info MUST be added using :add().

Once complete, the parser will be positioned at the end of the message.

Parameters

summary

a CamelFolderSummary object

 

parser

a CamelMimeParser object

 

Returns

a newly created CamelMessageInfo. Unref it with g_object_unref(), when done with it.

[transfer full]


camel_folder_summary_info_new_from_message ()

CamelMessageInfo *
camel_folder_summary_info_new_from_message
                               (CamelFolderSummary *summary,
                                CamelMimeMessage *message);

Create a summary item from a message.

Parameters

summary

a CamelFolderSummary object

 

message

a CamelMimeMessage object

 

Returns

a newly created CamelMessageInfo. Unref it with g_object_unref(), when done with it.

[transfer full]


camel_folder_summary_add ()

void
camel_folder_summary_add (CamelFolderSummary *summary,
                          CamelMessageInfo *info,
                          gboolean force_keep_uid);

Adds a new info record to the summary. If the force_keep_uid is FALSE, then a new uid is automatically re-assigned by calling camel_folder_summary_next_uid_string(). It's an error to use force_keep_uid when the info has none set.

The summary adds its own reference to info , if needed, and any previously loaded info is replaced with the new one.

Parameters

summary

a CamelFolderSummary object

 

info

a CamelMessageInfo

 

force_keep_uid

whether to keep set UID of the info

 

camel_folder_summary_remove ()

gboolean
camel_folder_summary_remove (CamelFolderSummary *summary,
                             CamelMessageInfo *info);

Remove a specific info record from the summary.

Parameters

summary

a CamelFolderSummary object

 

info

a CamelMessageInfo

 

Returns

Whether the info was found and removed from the summary .


camel_folder_summary_remove_uid ()

gboolean
camel_folder_summary_remove_uid (CamelFolderSummary *summary,
                                 const gchar *uid);

Remove a specific info record from the summary, by uid .

Parameters

summary

a CamelFolderSummary object

 

uid

a uid

 

Returns

Whether the uid was found and removed from the summary .


camel_folder_summary_remove_uids ()

gboolean
camel_folder_summary_remove_uids (CamelFolderSummary *summary,
                                  GList *uids);

Remove a specific info record from the summary, by uid .

Parameters

summary

a CamelFolderSummary object

 

uids

a GList of uids.

[element-type utf8]

Returns

Whether the uid was found and removed from the summary .

Since: 3.6


camel_folder_summary_clear ()

gboolean
camel_folder_summary_clear (CamelFolderSummary *summary,
                            GError **error);

Empty the summary contents.

Parameters

summary

a CamelFolderSummary object

 

error

return location for a GError, or NULL

 

Returns

whether succeeded


camel_folder_summary_count ()

guint
camel_folder_summary_count (CamelFolderSummary *summary);

Get the number of summary items stored in this summary.

Parameters

summary

a CamelFolderSummary object

 

Returns

the number of items in the summary


camel_folder_summary_check_uid ()

gboolean
camel_folder_summary_check_uid (CamelFolderSummary *summary,
                                const gchar *uid);

Check if the uid is valid. This isn't very efficient, so it shouldn't be called iteratively.

Parameters

summary

a CamelFolderSummary object

 

uid

a uid

 

Returns

if the uid is present in the summary or not (TRUE or FALSE)

Since: 2.24


camel_folder_summary_get ()

CamelMessageInfo *
camel_folder_summary_get (CamelFolderSummary *summary,
                          const gchar *uid);

Retrieve a summary item by uid.

A referenced to the summary item is returned, which may be ref'd or free'd as appropriate.

Parameters

summary

a CamelFolderSummary object

 

uid

a uid

 

Returns

the summary item, or NULL if the uid uid is not available

See camel_folder_summary_get_info_flags().

[nullable][transfer full]

Since: 3.4


camel_folder_summary_get_info_flags ()

guint32
camel_folder_summary_get_info_flags (CamelFolderSummary *summary,
                                     const gchar *uid);

Retrieve CamelMessageInfo::flags for a message info with UID uid . This is much quicker than camel_folder_summary_get(), because it doesn't require reading the message info from a disk.

Parameters

summary

a CamelFolderSummary object

 

uid

a uid

 

Returns

the flags currently stored for message info with UID uid , or (~0) on error

Since: 3.12


camel_folder_summary_get_array ()

GPtrArray *
camel_folder_summary_get_array (CamelFolderSummary *summary);

Obtain a copy of the summary array. This is done atomically, so cannot contain empty entries.

Free with camel_folder_summary_free_array()

Parameters

summary

a CamelFolderSummary object

 

Returns

a GPtrArray of uids.

[element-type utf8][transfer full]

Since: 3.4


camel_folder_summary_free_array ()

void
camel_folder_summary_free_array (GPtrArray *array);

Free's array and its elements returned from camel_folder_summary_get_array().

Parameters

array

a GPtrArray returned from camel_folder_summary_get_array().

[element-type utf8]

Since: 3.4


camel_folder_summary_get_hash ()

GHashTable *
camel_folder_summary_get_hash (CamelFolderSummary *summary);

Returns hash of current stored 'uids' in summary, where key is 'uid' from the string pool, and value is 1. The returned pointer should be freed with g_hash_table_destroy().

Note: When searching for values always use uids from the string pool.

Parameters

summary

a CamelFolderSummary object

 

Returns

.

[element-type utf8 gint][transfer container]

Since: 3.6


camel_folder_summary_replace_flags ()

gboolean
camel_folder_summary_replace_flags (CamelFolderSummary *summary,
                                    CamelMessageInfo *info);

Updates internal counts based on the flags in info .

Parameters

summary

a CamelFolderSummary

 

info

a CamelMessageInfo

 

Returns

Whether any count changed

Since: 3.6


camel_folder_summary_peek_loaded ()

CamelMessageInfo *
camel_folder_summary_peek_loaded (CamelFolderSummary *summary,
                                  const gchar *uid);

Parameters

summary

a CamelFolderSummary

 

uid

a message UID to look for

 

Returns

a CamelMessageInfo for the given uid , if it's currently loaded in memory, or NULL otherwise. Unref the non-NULL info with g_object_unref() when done with it.

[nullable][transfer full]

Since: 2.26


camel_folder_summary_get_changed ()

GPtrArray *
camel_folder_summary_get_changed (CamelFolderSummary *summary);

Returns an array of changed UID-s. A UID is considered changed when its corresponding CamelMesageInfo is 'dirty' or when it has set the CAMEL_MESSAGE_FOLDER_FLAGGED flag.

Parameters

summary

a CamelFolderSummary

 

Returns

a GPtrArray with changed UID-s. Free it with camel_folder_summary_free_array() when no longer needed.

[element-type utf8][transfer full]

Since: 2.24


camel_folder_summary_prepare_fetch_all ()

void
camel_folder_summary_prepare_fetch_all
                               (CamelFolderSummary *summary,
                                GError **error);

Loads all infos into memory, if they are not yet and ensures they will not be freed in next couple minutes. Call this function before any mass operation or when all message infos will be needed, for better performance.

Parameters

summary

CamelFolderSummary object

 

error

return location for a GError, or NULL

 

Since: 2.32


camel_folder_summary_lock ()

void
camel_folder_summary_lock (CamelFolderSummary *summary);

Locks summary . Unlock it with camel_folder_summary_unlock().

Parameters

summary

a CamelFolderSummary

 

Since: 2.32


camel_folder_summary_unlock ()

void
camel_folder_summary_unlock (CamelFolderSummary *summary);

Unlocks summary , previously locked with camel_folder_summary_lock().

Parameters

summary

a CamelFolderSummary

 

Since: 2.32


camel_system_flag ()

CamelMessageFlags
camel_system_flag (const gchar *name);

Parameters

name

name of a system flag

 

Returns

the integer value of the system flag string


camel_system_flag_get ()

gboolean
camel_system_flag_get (CamelMessageFlags flags,
                       const gchar *name);

Find the state of the flag name in flags .

Parameters

flags

bitwise system flags

 

name

name of the flag to check for

 

Returns

TRUE if the named flag is set or FALSE otherwise


camel_message_info_new_from_headers ()

CamelMessageInfo *
camel_message_info_new_from_headers (CamelFolderSummary *summary,
                                     const CamelNameValueArray *headers);

Create a new CamelMessageInfo pre-populated with info from headers .

Parameters

summary

a CamelFolderSummary object or NULL

 

headers

a CamelNameValueArray

 

Returns

a new CamelMessageInfo.

[transfer full]

Since: 3.24

Types and Values

enum CamelFolderSummaryFlags

Members

CAMEL_FOLDER_SUMMARY_DIRTY

There are changes in summary, which should be saved.

 

CAMEL_FOLDER_SUMMARY_IN_MEMORY_ONLY

Summary with this flag doesn't use DB for storing its content, it is always created on the fly.

 

Property Details

The “deleted-count” property

  “deleted-count”            guint

How many deleted infos is saved in a summary.

Flags: Read

Default value: 0


The “folder” property

  “folder”                   CamelFolder *

The CamelFolder to which the folder summary belongs.

Flags: Read / Write / Construct Only


The “junk-count” property

  “junk-count”               guint

How many junk infos is saved in a summary.

Flags: Read

Default value: 0


The “junk-not-deleted-count” property

  “junk-not-deleted-count”   guint

How many junk and not deleted infos is saved in a summary.

Flags: Read

Default value: 0


The “saved-count” property

  “saved-count”              guint

How many infos is saved in a summary.

Flags: Read

Default value: 0


The “unread-count” property

  “unread-count”             guint

How many unread infos is saved in a summary.

Flags: Read

Default value: 0


The “visible-count” property

  “visible-count”            guint

How many visible (not deleted and not junk) infos is saved in a summary.

Flags: Read

Default value: 0

Signal Details

The “changed” signal

void
user_function (CamelFolderSummary *camelfoldersummary,
               gpointer            user_data)

Flags: Run First