CamelFolderSummary: Camel Reference Manual

## 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 ()
CamelMessageInfo * | camel_message_info_new_from_message ()

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

enum | CamelFolderSummaryFlags

## 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. | [nullable]

### 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][nullable]

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.

[virtual message_info_new_from_headers]

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

[virtual message_info_new_from_parser]

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

[virtual message_info_new_from_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.

[virtual message_info_from_uid]

#### 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`. | [nullable]
headers | a CamelNameValueArray |

#### Returns

a new CamelMessageInfo.

[transfer full]

Since: 3.24

### camel_message_info_new_from_message ()

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

Create a new CamelMessageInfo pre-populated with info from `message` .

#### Parameters

summary | a CamelFolderSummary or `NULL`. | [nullable]
message | a CamelMimeMessage |

#### Returns

a new CamelMessageInfo.

[transfer full]

Since: 3.54

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

Owner: CamelFolderSummary

Flags: Read

Default value: 0

### The `“folder”` property

      “folder”                   CamelFolder *

The CamelFolder to which the folder summary belongs.

Owner: CamelFolderSummary

Flags: Read / Write / Construct Only

### The `“junk-count”` property

      “junk-count”               guint

How many junk infos is saved in a summary.

Owner: CamelFolderSummary

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.

Owner: CamelFolderSummary

Flags: Read

Default value: 0

### The `“saved-count”` property

      “saved-count”              guint

How many infos is saved in a summary.

Owner: CamelFolderSummary

Flags: Read

Default value: 0

### The `“unread-count”` property

      “unread-count”             guint

How many unread infos is saved in a summary.

Owner: CamelFolderSummary

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.

Owner: CamelFolderSummary

Flags: Read

Default value: 0

## Signal Details

### The `“changed”` signal

    void
    user_function (CamelFolderSummary *camelfoldersummary,
                   gpointer            user_data)

Flags: Run First