## CamelStoreSummary

CamelStoreSummary

## Synopsis

                        CamelStoreInfo;
    enum                CamelStoreInfoFlags;
                        CamelStoreSummary;
    #define             CAMEL_STORE_INFO_FOLDER_UNKNOWN
    enum                CamelStoreSummaryFlags;
    CamelStoreSummary*  camel_store_summary_new             (void);
    void                camel_store_summary_set_filename    (CamelStoreSummary *summary,
                                                             const char *filename);
    void                camel_store_summary_set_uri_base    (CamelStoreSummary *summary,
                                                             CamelURL *base);
    int                 camel_store_summary_load            (CamelStoreSummary *summary);
    int                 camel_store_summary_save            (CamelStoreSummary *summary);
    int                 camel_store_summary_header_load     (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 char *path);
    CamelStoreInfo*     camel_store_summary_info_new        (CamelStoreSummary *summary);
    CamelStoreInfo*     camel_store_summary_info_new_from_path
                                                            (CamelStoreSummary *summary,
                                                             const char *path);
    void                camel_store_summary_info_ref        (CamelStoreSummary *summary,
                                                             CamelStoreInfo *info);
    void                camel_store_summary_info_free       (CamelStoreSummary *summary,
                                                             CamelStoreInfo *info);
    void                camel_store_summary_remove          (CamelStoreSummary *summary,
                                                             CamelStoreInfo *info);
    void                camel_store_summary_remove_path     (CamelStoreSummary *summary,
                                                             const char *path);
    void                camel_store_summary_remove_index    (CamelStoreSummary *summary,
                                                             int index);
    void                camel_store_summary_clear           (CamelStoreSummary *summary);
    int                 camel_store_summary_count           (CamelStoreSummary *summary);
    CamelStoreInfo*     camel_store_summary_index           (CamelStoreSummary *summary,
                                                             int index);
    CamelStoreInfo*     camel_store_summary_path            (CamelStoreSummary *summary,
                                                             const char *path);
    GPtrArray*          camel_store_summary_array           (CamelStoreSummary *summary);
    void                camel_store_summary_array_free      (CamelStoreSummary *summary,
                                                             GPtrArray *array);
    const char*         camel_store_info_string             (CamelStoreSummary *summary,
                                                             const CamelStoreInfo *info,
                                                             int type);
    void                camel_store_info_set_string         (CamelStoreSummary *summary,
                                                             CamelStoreInfo *info,
                                                             int type,
                                                             const char *value);
    #define             camel_store_info_path               (s, i)
    #define             camel_store_info_uri                (s, i)
    #define             camel_store_info_name               (s, i)

## Description

## Details

### CamelStoreInfo

    typedef struct {
    	guint32 refcount;
    	char *uri;
    	char *path;
    	guint32 flags;
    	guint32 unread;
    	guint32 total;
    } CamelStoreInfo;

### enum CamelStoreInfoFlags

    typedef enum _CamelStoreInfoFlags {
    	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_BY_ME = 1<<8,
    	CAMEL_STORE_INFO_FOLDER_SHARED_TO_ME = 1<<9,

    	/* not in camle-store.h yet */
    	CAMEL_STORE_INFO_FOLDER_READONLY = 1<<13,

    	CAMEL_STORE_INFO_FOLDER_FLAGGED = 1<<31
    } CamelStoreInfoFlags;

### CamelStoreSummary

    typedef struct {
    	CamelObject parent;

    	struct _CamelStoreSummaryPrivate *priv;

    	/* header info */
    	guint32 version;	/* version of base part of file */
    	guint32 flags;		/* flags */
    	guint32 count;		/* how many were saved/loaded */
    	time_t time;		/* timestamp for this summary (for implementors to use) */
    	struct _CamelURL *uri_base;	/* url of base part of summary */

    	/* sizes of memory objects */
    	guint32 store_info_size;

    	/* memory allocators (setup automatically) */
    	struct _EMemChunk *store_info_chunks;

    	char *summary_path;

    	GPtrArray *folders;	/* CamelStoreInfo's */
    	GHashTable *folders_path; /* CamelStoreInfo's by path name */
    } CamelStoreSummary;

### CAMEL_STORE_INFO_FOLDER_UNKNOWN

    #define CAMEL_STORE_INFO_FOLDER_UNKNOWN (~0)

### enum CamelStoreSummaryFlags

    typedef enum _CamelStoreSummaryFlags {
    	CAMEL_STORE_SUMMARY_DIRTY = 1<<0,
    	CAMEL_STORE_SUMMARY_FRAGMENT = 1<<1 /* path name is stored in fragment rather than path */
    } CamelStoreSummaryFlags;

### 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 char *filename);

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

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

### camel_store_summary_set_uri_base ()

    void                camel_store_summary_set_uri_base    (CamelStoreSummary *summary,
                                                             CamelURL *base);

Sets the base URI for the summary.

`summary` : | a CamelStoreSummary object
`base` : | a CamelURL

### camel_store_summary_load ()

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

    int                 camel_store_summary_save            (CamelStoreSummary *summary);

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

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

### camel_store_summary_header_load ()

    int                 camel_store_summary_header_load     (CamelStoreSummary *summary);

Only load the header information from the summary, keep the rest on disk. This should only be done on a fresh summary object.

`summary` : | a CamelStoreSummary object
Returns : | %0 on success 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 char *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_new_from_path ()

    CamelStoreInfo*     camel_store_summary_info_new_from_path
                                                            (CamelStoreSummary *summary,
                                                             const char *path);

Create a new info record from a name.

This info record MUST be freed using camel_store_summary_info_free, camel_store_info_free will not work.

`summary` : | a CamelStoreSummary object
`path` : | item path
Returns : | the CamelStoreInfo associated with `path`

### camel_store_summary_info_ref ()

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

Add an extra reference to `info`.

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

### camel_store_summary_info_free ()

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

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

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

### 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 char *path);

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

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

### camel_store_summary_remove_index ()

    void                camel_store_summary_remove_index    (CamelStoreSummary *summary,
                                                             int index);

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

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

### camel_store_summary_clear ()

    void                camel_store_summary_clear           (CamelStoreSummary *summary);

Empty the summary contents.

`summary` : | a CamelStoreSummary object

### camel_store_summary_count ()

    int                 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 int he summary.

### camel_store_summary_index ()

    CamelStoreInfo*     camel_store_summary_index           (CamelStoreSummary *summary,
                                                             int index);

Retrieve a summary item by index number.

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

It must be freed using camel_store_summary_info_free.

`summary` : | a CamelStoreSummary object
`index` : | record index
Returns : | the summary item, or `NULL` if `index` is out of range

### camel_store_summary_path ()

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

Retrieve a summary item by path name.

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

It must be freed using camel_store_summary_info_free.

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

    const char*         camel_store_info_string             (CamelStoreSummary *summary,
                                                             const CamelStoreInfo *info,
                                                             int type);

Get a specific string from the `info`.

`summary` : | a CamelStoreSummary object
`info` : | a CamelStoreInfo
`type` : | specific string being requested
Returns : | the string value

### camel_store_info_set_string ()

    void                camel_store_info_set_string         (CamelStoreSummary *summary,
                                                             CamelStoreInfo *info,
                                                             int type,
                                                             const char *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()

    #define camel_store_info_path(s, i) (camel_store_info_string((CamelStoreSummary *)s, (const CamelStoreInfo *)i, CAMEL_STORE_INFO_PATH))

`s` : |
`i` : |

### camel_store_info_uri()

    #define camel_store_info_uri(s, i) (camel_store_info_string((CamelStoreSummary *)s, (const CamelStoreInfo *)i, CAMEL_STORE_INFO_URI))

`s` : |
`i` : |

### camel_store_info_name()

    #define camel_store_info_name(s, i) (camel_store_info_string((CamelStoreSummary *)s, (const CamelStoreInfo *)i, CAMEL_STORE_INFO_NAME))

`s` : |
`i` : |