## CamelStoreSummary

CamelStoreSummary

## Synopsis

    struct              CamelStoreInfo;
    enum                CamelStoreInfoFlags;
    struct              CamelStoreSummary;
    #define             CAMEL_STORE_INFO_FOLDER_UNKNOWN
    CamelStoreSummary * camel_store_summary_new             (void);
    void                camel_store_summary_set_filename    (CamelStoreSummary *summary,
                                                             const gchar *filename);
    gint                camel_store_summary_load            (CamelStoreSummary *summary);
    gint                camel_store_summary_save            (CamelStoreSummary *summary);
    void                camel_store_summary_touch           (CamelStoreSummary *summary);
    void                camel_store_summary_add             (CamelStoreSummary *summary,
                                                             CamelStoreInfo *info);
    CamelStoreInfo *    camel_store_summary_add_from_path   (CamelStoreSummary *summary,
                                                             const gchar *path);
    CamelStoreInfo *    camel_store_summary_info_new        (CamelStoreSummary *summary);
    CamelStoreInfo *    camel_store_summary_info_ref        (CamelStoreSummary *summary,
                                                             CamelStoreInfo *info);
    void                camel_store_summary_info_unref      (CamelStoreSummary *summary,
                                                             CamelStoreInfo *info);
    #define             camel_store_summary_info_free
    void                camel_store_summary_remove          (CamelStoreSummary *summary,
                                                             CamelStoreInfo *info);
    void                camel_store_summary_remove_path     (CamelStoreSummary *summary,
                                                             const gchar *path);
    gint                camel_store_summary_count           (CamelStoreSummary *summary);
    CamelStoreInfo *    camel_store_summary_path            (CamelStoreSummary *summary,
                                                             const gchar *path);
    GPtrArray *         camel_store_summary_array           (CamelStoreSummary *summary);
    void                camel_store_summary_array_free      (CamelStoreSummary *summary,
                                                             GPtrArray *array);
    void                camel_store_info_set_string         (CamelStoreSummary *summary,
                                                             CamelStoreInfo *info,
                                                             gint type,
                                                             const gchar *value);
    const gchar *       camel_store_info_path               (CamelStoreSummary *summary,
                                                             CamelStoreInfo *info);
    const gchar *       camel_store_info_name               (CamelStoreSummary *summary,
                                                             CamelStoreInfo *info);
    gboolean            camel_store_summary_connect_folder_summary
                                                            (CamelStoreSummary *summary,
                                                             const gchar *path,
                                                             struct _CamelFolderSummary *folder_summary);
    gboolean            camel_store_summary_disconnect_folder_summary
                                                            (CamelStoreSummary *summary,
                                                             struct _CamelFolderSummary *folder_summary);

## Object Hierarchy

      GObject
       +----CamelObject
             +----CamelStoreSummary
                   +----CamelIMAPXStoreSummary

## Description

## Details

### struct CamelStoreInfo

    struct CamelStoreInfo {
    	volatile gint refcount;
    	gchar *path;
    	guint32 flags;
    	guint32 unread;
    	guint32 total;
    };

### enum CamelStoreInfoFlags

    typedef enum {
     /*< flags >*/
    	CAMEL_STORE_INFO_FOLDER_NOSELECT = 1 << 0,
    	CAMEL_STORE_INFO_FOLDER_NOINFERIORS = 1 << 1,
    	CAMEL_STORE_INFO_FOLDER_CHILDREN = 1 << 2,
    	CAMEL_STORE_INFO_FOLDER_NOCHILDREN = 1 << 3,
    	CAMEL_STORE_INFO_FOLDER_SUBSCRIBED = 1 << 4,
    	CAMEL_STORE_INFO_FOLDER_VIRTUAL = 1 << 5,
    	CAMEL_STORE_INFO_FOLDER_SYSTEM = 1 << 6,
    	CAMEL_STORE_INFO_FOLDER_VTRASH = 1 << 7,
    	CAMEL_STORE_INFO_FOLDER_SHARED_TO_ME = 1 << 8,
    	CAMEL_STORE_INFO_FOLDER_SHARED_BY_ME = 1 << 9,
    	CAMEL_STORE_INFO_FOLDER_READONLY = 1 << 16,
    	/* empty gap from unused flag removal */
    	CAMEL_STORE_INFO_FOLDER_FLAGGED = 1 << 18,

    	CAMEL_STORE_INFO_FOLDER_LAST          = 1 << 24  /*< skip >*/
    } CamelStoreInfoFlags;

`CAMEL_STORE_INFO_FOLDER_NOSELECT` |
`CAMEL_STORE_INFO_FOLDER_NOINFERIORS` |
`CAMEL_STORE_INFO_FOLDER_CHILDREN` |
`CAMEL_STORE_INFO_FOLDER_NOCHILDREN` |
`CAMEL_STORE_INFO_FOLDER_SUBSCRIBED` |
`CAMEL_STORE_INFO_FOLDER_VIRTUAL` |
`CAMEL_STORE_INFO_FOLDER_SYSTEM` |
`CAMEL_STORE_INFO_FOLDER_VTRASH` |
`CAMEL_STORE_INFO_FOLDER_SHARED_TO_ME` |
`CAMEL_STORE_INFO_FOLDER_SHARED_BY_ME` |
`CAMEL_STORE_INFO_FOLDER_READONLY` |
`CAMEL_STORE_INFO_FOLDER_FLAGGED` |
`CAMEL_STORE_INFO_FOLDER_LAST` |

### struct CamelStoreSummary

    struct CamelStoreSummary;

### CAMEL_STORE_INFO_FOLDER_UNKNOWN

    #define CAMEL_STORE_INFO_FOLDER_UNKNOWN (~0)

### camel_store_summary_new ()

    CamelStoreSummary * camel_store_summary_new             (void);

Create a new CamelStoreSummary object.

Returns : | a new CamelStoreSummary object

### camel_store_summary_set_filename ()

    void                camel_store_summary_set_filename    (CamelStoreSummary *summary,
                                                             const gchar *filename);

Set the filename where the summary will be loaded to/saved from.

`summary` : | a CamelStoreSummary
`filename` : | a filename

### camel_store_summary_load ()

    gint                camel_store_summary_load            (CamelStoreSummary *summary);

Load the summary off disk.

`summary` : | a CamelStoreSummary object
Returns : | `0` on success or `-1` on fail

### camel_store_summary_save ()

    gint                camel_store_summary_save            (CamelStoreSummary *summary);

Writes the summary to disk. The summary is only written if changes have occurred.

`summary` : | a CamelStoreSummary object
Returns : | `0` on succes or `-1` on fail

### camel_store_summary_touch ()

    void                camel_store_summary_touch           (CamelStoreSummary *summary);

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

`summary` : | a CamelStoreSummary object

### camel_store_summary_add ()

    void                camel_store_summary_add             (CamelStoreSummary *summary,
                                                             CamelStoreInfo *info);

Adds a new `info` record to the summary. If `info->uid` is `NULL`, then a new uid is automatically re-assigned by calling `camel_store_summary_next_uid_string()`.

The `info` record should have been generated by calling one of the info_new_*() functions, as it will be free'd based on the summary class. And MUST NOT be allocated directly using malloc.

`summary` : | a CamelStoreSummary object
`info` : | a CamelStoreInfo

### camel_store_summary_add_from_path ()

    CamelStoreInfo *    camel_store_summary_add_from_path   (CamelStoreSummary *summary,
                                                             const gchar *path);

Build a new info record based on the name, and add it to the summary.

`summary` : | a CamelStoreSummary object
`path` : | item path
Returns : | the newly added record

### camel_store_summary_info_new ()

    CamelStoreInfo *    camel_store_summary_info_new        (CamelStoreSummary *summary);

Allocate a new CamelStoreInfo, suitable for adding to this summary.

`summary` : | a CamelStoreSummary object
Returns : | the newly allocated CamelStoreInfo

### camel_store_summary_info_ref ()

    CamelStoreInfo *    camel_store_summary_info_ref        (CamelStoreSummary *summary,
                                                             CamelStoreInfo *info);

Add an extra reference to `info`.

`summary` : | a CamelStoreSummary object
`info` : | a CamelStoreInfo
Returns : | the `info` argument

### camel_store_summary_info_unref ()

    void                camel_store_summary_info_unref      (CamelStoreSummary *summary,
                                                             CamelStoreInfo *info);

Unref and potentially free `info`, and all associated memory.

`summary` : | a CamelStoreSummary object
`info` : | a CamelStoreInfo

### camel_store_summary_info_free

    #define camel_store_summary_info_free camel_store_summary_info_unref

### Warning

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

### camel_store_summary_remove ()

    void                camel_store_summary_remove          (CamelStoreSummary *summary,
                                                             CamelStoreInfo *info);

Remove a specific `info` record from the summary.

`summary` : | a CamelStoreSummary object
`info` : | a CamelStoreInfo

### camel_store_summary_remove_path ()

    void                camel_store_summary_remove_path     (CamelStoreSummary *summary,
                                                             const gchar *path);

Remove a specific info record from the summary, by `path`.

`summary` : | a CamelStoreSummary object
`path` : | item path

### camel_store_summary_count ()

    gint                camel_store_summary_count           (CamelStoreSummary *summary);

Get the number of summary items stored in this summary.

`summary` : | a CamelStoreSummary object
Returns : | the number of items gint he summary.

### camel_store_summary_path ()

    CamelStoreInfo *    camel_store_summary_path            (CamelStoreSummary *summary,
                                                             const gchar *path);

Retrieve a summary item by path name.

The returned CamelStoreInfo is referenced for thread-safety and should be unreferenced with `camel_store_summary_info_unref()` when finished with it.

`summary` : | a CamelStoreSummary object
`path` : | path to the item
Returns : | the summary item, or `NULL` if the `path` name is not available

### camel_store_summary_array ()

    GPtrArray *         camel_store_summary_array           (CamelStoreSummary *summary);

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

It must be freed using `camel_store_summary_array_free()`.

`summary` : | a CamelStoreSummary object
Returns : | the summary array

### camel_store_summary_array_free ()

    void                camel_store_summary_array_free      (CamelStoreSummary *summary,
                                                             GPtrArray *array);

Free the folder summary array.

`summary` : | a CamelStoreSummary object
`array` : | the summary array as gotten from `camel_store_summary_array()`

### camel_store_info_set_string ()

    void                camel_store_info_set_string         (CamelStoreSummary *summary,
                                                             CamelStoreInfo *info,
                                                             gint type,
                                                             const gchar *value);

Set a specific string on the `info`.

`summary` : | a CamelStoreSummary object
`info` : | a CamelStoreInfo
`type` : | specific string being set
`value` : | string value to set

### camel_store_info_path ()

    const gchar *       camel_store_info_path               (CamelStoreSummary *summary,
                                                             CamelStoreInfo *info);

Returns the path string from `info`.

`summary` : | a CamelStoreSummary
`info` : | a CamelStoreInfo
Returns : | the path string from `info`

### camel_store_info_name ()

    const gchar *       camel_store_info_name               (CamelStoreSummary *summary,
                                                             CamelStoreInfo *info);

Returns the last segment of the path string from `info`.

`summary` : | a CamelStoreSummary
`info` : | a CamelStoreInfo
Returns : | the last segment of the path string from `info`

### camel_store_summary_connect_folder_summary ()

    gboolean            camel_store_summary_connect_folder_summary
                                                            (CamelStoreSummary *summary,
                                                             const gchar *path,
                                                             struct _CamelFolderSummary *folder_summary);

Connects listeners for count changes on `folder_summary` to keep CamelStoreInfo.total and CamelStoreInfo.unread in sync transparently. The `folder_summary` is stored in `summary` as `path`. Use `camel_store_summary_disconnect_folder_summary()` to disconnect from listening.

`summary` : | a CamelStoreSummary object
`path` : | used path for `folder_summary`
`folder_summary` : | a CamelFolderSummary object
Returns : | Whether successfully connect callbacks for count change notifications.

Since 3.4

### camel_store_summary_disconnect_folder_summary ()

    gboolean            camel_store_summary_disconnect_folder_summary
                                                            (CamelStoreSummary *summary,
                                                             struct _CamelFolderSummary *folder_summary);

Diconnects count change listeners previously connected by `camel_store_summary_connect_folder_summary()`.

`summary` : | a CamelStoreSummary object
`folder_summary` : | a CamelFolderSummary object
Returns : | Whether such connection existed and whether was successfully removed.

Since 3.4