CamelFolderSummary

## CamelFolderSummary CamelFolderSummary |

## Synopsis

    struct              CamelFolderSummary;
                        CamelMessageInfo;
                        CamelMessageInfoBase;
                        CamelFolderMetaSummary;
    struct              CamelMessageContentInfo;
    enum                CamelMessageFlags;
    #define             CAMEL_MESSAGE_SYSTEM_MASK
                        CamelFlag;
                        CamelTag;
                        CamelSummaryMessageID;
                        CamelSummaryReferences;
    enum                CamelFolderSummaryFlags;
    CamelFolderSummary * camel_folder_summary_new           (struct _CamelFolder *folder);
    void                camel_folder_summary_set_filename   (CamelFolderSummary *summary,
                                                             const gchar *filename);
    void                camel_folder_summary_set_index      (CamelFolderSummary *summary,
                                                             CamelIndex *index);
    void                camel_folder_summary_set_build_content
                                                            (CamelFolderSummary *summary,
                                                             gboolean state);
    guint32             camel_folder_summary_next_uid       (CamelFolderSummary *summary);
    gchar *             camel_folder_summary_next_uid_string
                                                            (CamelFolderSummary *summary);
    void                camel_folder_summary_set_uid        (CamelFolderSummary *summary,
                                                             guint32 uid);
    gint                camel_folder_summary_load           (CamelFolderSummary *summary);
    gint                camel_folder_summary_save           (CamelFolderSummary *summary);
    gint                camel_folder_summary_save_to_db     (CamelFolderSummary *s,
                                                             CamelException *ex);
    gint                camel_folder_summary_load_from_db   (CamelFolderSummary *s,
                                                             CamelException *ex);
    gint                camel_folder_summary_header_load    (CamelFolderSummary *summary);
    gint                camel_folder_summary_header_load_from_db
                                                            (CamelFolderSummary *s,
                                                             CamelStore *store,
                                                             const gchar *folder_name,
                                                             CamelException *ex);
    gint                camel_folder_summary_header_save_to_db
                                                            (CamelFolderSummary *s,
                                                             CamelException *ex);
    void                camel_folder_summary_touch          (CamelFolderSummary *summary);
    void                camel_folder_summary_add            (CamelFolderSummary *summary,
                                                             CamelMessageInfo *info);
    CamelMessageInfo *  camel_folder_summary_peek_info      (CamelFolderSummary *s,
                                                             const gchar *uid);
    GPtrArray *         camel_folder_summary_get_changed    (CamelFolderSummary *s);
    gint                camel_folder_summary_cache_size     (CamelFolderSummary *s);
    gint                camel_folder_summary_reload_from_db (CamelFolderSummary *s,
                                                             CamelException *ex);
    void                camel_folder_summary_ensure_infos_loaded
                                                            (CamelFolderSummary *s,
                                                             gint at_least,
                                                             CamelException *ex);
    void                camel_folder_summary_insert         (CamelFolderSummary *s,
                                                             CamelMessageInfo *info,
                                                             gboolean load);
    void                camel_folder_summary_remove_index_fast
                                                            (CamelFolderSummary *s,
                                                             gint index);
    void                camel_folder_summary_remove_uid_fast
                                                            (CamelFolderSummary *s,
                                                             const gchar *uid);
    CamelMessageInfo *  camel_folder_summary_add_from_header
                                                            (CamelFolderSummary *summary,
                                                             struct _camel_header_raw *headers);
    CamelMessageInfo *  camel_folder_summary_add_from_parser
                                                            (CamelFolderSummary *summary,
                                                             CamelMimeParser *parser);
    CamelMessageInfo *  camel_folder_summary_add_from_message
                                                            (CamelFolderSummary *summary,
                                                             CamelMimeMessage *message);
    CamelMessageInfo *  camel_folder_summary_info_new_from_header
                                                            (CamelFolderSummary *summary,
                                                             struct _camel_header_raw *headers);
    CamelMessageInfo *  camel_folder_summary_info_new_from_parser
                                                            (CamelFolderSummary *summary,
                                                             CamelMimeParser *parser);
    CamelMessageInfo *  camel_folder_summary_info_new_from_message
                                                            (CamelFolderSummary *summary,
                                                             CamelMimeMessage *message);
    CamelMessageContentInfo * camel_folder_summary_content_info_new
                                                            (CamelFolderSummary *summary);
    void                camel_folder_summary_content_info_free
                                                            (CamelFolderSummary *summary,
                                                             CamelMessageContentInfo *ci);
    void                camel_folder_summary_remove         (CamelFolderSummary *summary,
                                                             CamelMessageInfo *info);
    void                camel_folder_summary_remove_uid     (CamelFolderSummary *summary,
                                                             const gchar *uid);
    void                camel_folder_summary_remove_index   (CamelFolderSummary *summary,
                                                             gint index);
    void                camel_folder_summary_remove_range   (CamelFolderSummary *summary,
                                                             gint start,
                                                             gint end);
    void                camel_folder_summary_clear          (CamelFolderSummary *summary);
    void                camel_folder_summary_clear_db       (CamelFolderSummary *s);
    guint               camel_folder_summary_count          (CamelFolderSummary *summary);
    CamelMessageInfo *  camel_folder_summary_index          (CamelFolderSummary *summary,
                                                             gint index);
    CamelMessageInfo *  camel_folder_summary_uid            (CamelFolderSummary *summary,
                                                             const gchar *uid);
    gchar *             camel_folder_summary_uid_from_index (CamelFolderSummary *s,
                                                             gint i);
    gboolean            camel_folder_summary_check_uid      (CamelFolderSummary *s,
                                                             const gchar *uid);
    GPtrArray *         camel_folder_summary_array          (CamelFolderSummary *summary);
    GHashTable *        camel_folder_summary_get_hashtable  (CamelFolderSummary *s);
    void                camel_folder_summary_free_hashtable (GHashTable *ht);
    GHashTable *        camel_folder_summary_get_flag_cache (CamelFolderSummary *summary);
    void                camel_folder_summary_update_flag_cache
                                                            (CamelFolderSummary *s,
                                                             const gchar *uid,
                                                             guint32 flag);
    gint                camel_folder_summary_encode_token   (FILE *out,
                                                             const gchar *str);
    gint                camel_folder_summary_decode_token   (FILE *in,
                                                             gchar **str);
    gboolean            camel_flag_get                      (CamelFlag **list,
                                                             const gchar *name);
    gboolean            camel_flag_set                      (CamelFlag **list,
                                                             const gchar *name,
                                                             gboolean value);
    gboolean            camel_flag_list_copy                (CamelFlag **to,
                                                             CamelFlag **from);
    gint                camel_flag_list_size                (CamelFlag **list);
    void                camel_flag_list_free                (CamelFlag **list);
    guint32             camel_system_flag                   (const gchar *name);
    gboolean            camel_system_flag_get               (guint32 flags,
                                                             const gchar *name);
    const gchar *       camel_tag_get                       (CamelTag **list,
                                                             const gchar *name);
    gboolean            camel_tag_set                       (CamelTag **list,
                                                             const gchar *name,
                                                             const gchar *value);
    gboolean            camel_tag_list_copy                 (CamelTag **to,
                                                             CamelTag **from);
    gint                camel_tag_list_size                 (CamelTag **list);
    void                camel_tag_list_free                 (CamelTag **list);
    gpointer            camel_message_info_new              (CamelFolderSummary *summary);
    void                camel_message_info_ref              (gpointer info);
    CamelMessageInfo *  camel_message_info_new_from_header  (CamelFolderSummary *summary,
                                                             struct _camel_header_raw *header);
    void                camel_message_info_free             (gpointer info);
    gpointer            camel_message_info_clone            (gconstpointer info);
    gconstpointer       camel_message_info_ptr              (const CamelMessageInfo *mi,
                                                             gint id);
    guint32             camel_message_info_uint32           (const CamelMessageInfo *mi,
                                                             gint id);
    time_t              camel_message_info_time             (const CamelMessageInfo *mi,
                                                             gint id);
    #define             camel_message_info_uid              (mi)
    #define             camel_message_info_subject          (mi)
    #define             camel_message_info_preview          (mi)
    #define             camel_message_info_from             (mi)
    #define             camel_message_info_to               (mi)
    #define             camel_message_info_cc               (mi)
    #define             camel_message_info_mlist            (mi)
    #define             camel_message_info_flags            (mi)
    #define             camel_message_info_size             (mi)
    #define             camel_message_info_date_sent        (mi)
    #define             camel_message_info_date_received    (mi)
    #define             camel_message_info_message_id       (mi)
    #define             camel_message_info_references       (mi)
    #define             camel_message_info_user_flags       (mi)
    #define             camel_message_info_user_tags        (mi)
    #define             camel_message_info_headers          (mi)
    gboolean            camel_message_info_user_flag        (const CamelMessageInfo *mi,
                                                             const gchar *id);
    const gchar *       camel_message_info_user_tag         (const CamelMessageInfo *mi,
                                                             const gchar *id);
    gboolean            camel_message_info_set_flags        (CamelMessageInfo *mi,
                                                             guint32 flags,
                                                             guint32 set);
    gboolean            camel_message_info_set_user_flag    (CamelMessageInfo *mi,
                                                             const gchar *id,
                                                             gboolean state);
    gboolean            camel_message_info_set_user_tag     (CamelMessageInfo *mi,
                                                             const gchar *id,
                                                             const gchar *val);
    void                camel_folder_summary_set_need_preview
                                                            (CamelFolderSummary *summary,
                                                             gboolean preview);
    void                camel_folder_summary_add_preview    (CamelFolderSummary *s,
                                                             CamelMessageInfo *info);
    gboolean            camel_folder_summary_get_need_preview
                                                            (CamelFolderSummary *summary);
    void                camel_content_info_dump             (CamelMessageContentInfo *ci,
                                                             gint depth);
    void                camel_message_info_dump             (CamelMessageInfo *mi);
    gint                camel_folder_summary_migrate_infos  (CamelFolderSummary *s);

## Description

## Details

### struct CamelFolderSummary

    struct CamelFolderSummary {
    	CamelObject parent;

    	struct _CamelFolderSummaryPrivate *priv;

    	/* header info */
    	guint32 version;	/* version of file loaded/loading */
    	guint32 flags;		/* flags */
    	guint32 nextuid;	/* next uid? */
    	time_t time;		/* timestamp for this summary (for implementors to use) */
    	guint32 saved_count;	/* how many were saved/loaded */
    	guint32 unread_count;	/* handy totals */
    	guint32 deleted_count;
    	guint32 junk_count;
    	guint32 junk_not_deleted_count;
    	guint32 visible_count;

    	/* sizes of memory objects */
    	guint32 message_info_size;
    	guint32 content_info_size;

    	/* memory allocators (setup automatically) */
    	struct _EMemChunk *message_info_chunks;
    	struct _EMemChunk *content_info_chunks;

    	gchar *summary_path;
    	gboolean build_content;	/* do we try and parse/index the content, or not? */

    #if 0  /* Deprecated */
    	GPtrArray *messages;	/* CamelMessageInfo's */
    	GHashTable *messages_uid; /* CamelMessageInfo's by uid */
    #endif

    	/* New members to replace the above depreacted members */
    	GPtrArray *uids;
    	GHashTable *loaded_infos;

    	struct _CamelFolder *folder; /* parent folder, for events */
    	struct _CamelFolderMetaSummary *meta_summary; /* Meta summary */
    	time_t cache_load_time;
    	guint timeout_handle;

    	const gchar *collate;
    	const gchar *sort_by;

    	/* Future ABI expansion */
    	gpointer later[4];
    };

### CamelMessageInfo

    typedef struct {
    	CamelFolderSummary *summary;

    	guint32 refcount;	/* ??? */
    	const gchar *uid;
    	/*FIXME: Make it work with the CAMEL_MESSADE_DB_DIRTY flag instead of another 4 bytes*/
    	gint dirty:1;
    } CamelMessageInfo;

### CamelMessageInfoBase

    typedef struct {
    	CamelFolderSummary *summary;

    	guint32 refcount;	/* ??? */
    	const gchar *uid;
    	/*FIXME: Make it work with the CAMEL_MESSADE_DB_DIRTY flag instead of another 4 bytes*/
    	gint dirty:1;

    	const gchar *subject;
    	const gchar *from;
    	const gchar *to;
    	const gchar *cc;
    	const gchar *mlist;

    	guint32 flags;
    	guint32 size;

    	time_t date_sent;
    	time_t date_received;

    	CamelSummaryMessageID message_id;
    	CamelSummaryReferences *references;/* from parent to root */

    	struct _CamelFlag *user_flags;
    	struct _CamelTag *user_tags;

    	/* tree of content description - NULL if it is not available */
    	CamelMessageContentInfo *content;
    	struct _camel_header_param *headers;
    	gchar *preview;
    } CamelMessageInfoBase;

### CamelFolderMetaSummary

    typedef struct {
    	guint32 major;		/* Major version of meta-summary */
    	guint32 minor;		/* Minor version of meta-summary */
    	guint32 uid_len;	/* Length of UID (for implementors to use) */
    	gboolean msg_expunged;	/* Whether any message is expunged or not */
    	gchar *path;		/* Path to meta-summary-file */
    } CamelFolderMetaSummary;

### struct CamelMessageContentInfo

    struct CamelMessageContentInfo {
    	struct _CamelMessageContentInfo *next;

    	struct _CamelMessageContentInfo *childs;
    	struct _CamelMessageContentInfo *parent;

    	CamelContentType *type;
    	gchar *id;
    	gchar *description;
    	gchar *encoding;		/* this should be an enum?? */
    	guint32 size;
    };

### enum CamelMessageFlags

    typedef enum _CamelMessageFlags {
    	CAMEL_MESSAGE_ANSWERED = 1<<0,
    	CAMEL_MESSAGE_DELETED = 1<<1,
    	CAMEL_MESSAGE_DRAFT = 1<<2,
    	CAMEL_MESSAGE_FLAGGED = 1<<3,
    	CAMEL_MESSAGE_SEEN = 1<<4,

    	/* these aren't really system flag bits, but are convenience flags */
    	CAMEL_MESSAGE_ATTACHMENTS = 1<<5,
    	CAMEL_MESSAGE_ANSWERED_ALL = 1<<6,
    	CAMEL_MESSAGE_JUNK = 1<<7,
    	CAMEL_MESSAGE_SECURE = 1<<8,
    	CAMEL_MESSAGE_USER_NOT_DELETABLE = 1<<9,
    	CAMEL_MESSAGE_HIDDEN = 1<<10,
    	CAMEL_MESSAGE_NOTJUNK = 1<<11,
    	CAMEL_MESSAGE_FORWARDED = 1<<12,

    	/* following flags are for the folder, and are not really permanent flags */
    	CAMEL_MESSAGE_FOLDER_FLAGGED = 1<<16, /* for use by the folder implementation */
    	/* flags after 1<<16 are used by camel providers,
               if adding non permanent flags, add them to the end  */

    	CAMEL_MESSAGE_JUNK_LEARN = 1<<30, /* used when setting CAMEL_MESSAGE_JUNK flag
    					     to say that we request junk plugin
    					     to learn that message as junk/non junk */
    	CAMEL_MESSAGE_USER = 1<<31 /* supports user flags */
    } CamelMessageFlags;

### CAMEL_MESSAGE_SYSTEM_MASK

    #define CAMEL_MESSAGE_SYSTEM_MASK (0xffff << 16)

### CamelFlag

    typedef struct {
    	struct _CamelFlag *next;
    	gchar name[1];		/* name allocated as part of the structure */
    } CamelFlag;

### CamelTag

    typedef struct {
    	struct _CamelTag *next;
    	gchar *value;
    	gchar name[1];		/* name allocated as part of the structure */
    } CamelTag;

### CamelSummaryMessageID

    typedef struct {
    	union {
    		guint64 id;
    		guchar hash[8];
    		struct {
    			guint32 hi;
    			guint32 lo;
    		} part;
    	} id;
    } CamelSummaryMessageID;

### CamelSummaryReferences

    typedef struct {
    	gint size;
    	CamelSummaryMessageID references[1];
    } CamelSummaryReferences;

### enum CamelFolderSummaryFlags

    typedef enum _CamelFolderSummaryFlags {
    	CAMEL_SUMMARY_DIRTY = 1<<0
    } CamelFolderSummaryFlags;

### camel_folder_summary_new ()

    CamelFolderSummary * camel_folder_summary_new           (struct _CamelFolder *folder);

Create a new CamelFolderSummary object.

`folder` : | parent CamelFolder object
Returns : | a new CamelFolderSummary object

### camel_folder_summary_set_filename ()

    void                camel_folder_summary_set_filename   (CamelFolderSummary *summary,
                                                             const gchar *filename);

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

`summary` : | a CamelFolderSummary object
`filename` : | a filename

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

Unlike earlier behaviour, build_content need not be set to perform indexing.

`summary` : | a CamelFolderSummary object
`index` : | a CamelIndex

### camel_folder_summary_set_build_content ()

    void                camel_folder_summary_set_build_content
                                                            (CamelFolderSummary *summary,
                                                             gboolean state);

Set a flag to tell the summary to build the content info summary (CamelMessageInfo.content). The default is not to build content info summaries.

`summary` : | a CamelFolderSummary object
`state` : | to build or not to build the content

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

`summary` : | a CamelFolderSummary object
Returns : | the next unique uid value

### camel_folder_summary_next_uid_string ()

    gchar *             camel_folder_summary_next_uid_string
                                                            (CamelFolderSummary *summary);

Retrieve the next uid, but as a formatted string.

`summary` : | a CamelFolderSummary object
Returns : | the next uid as an unsigned integer string. This string must be freed by the caller.

### camel_folder_summary_set_uid ()

    void                camel_folder_summary_set_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.

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

    gint                camel_folder_summary_load           (CamelFolderSummary *summary);

Load the summary from disk.

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

### camel_folder_summary_save ()

    gint                camel_folder_summary_save           (CamelFolderSummary *summary);

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

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

### camel_folder_summary_save_to_db ()

    gint                camel_folder_summary_save_to_db     (CamelFolderSummary *s,
                                                             CamelException *ex);

`s` : |
`ex` : |
Returns : |

### camel_folder_summary_load_from_db ()

    gint                camel_folder_summary_load_from_db   (CamelFolderSummary *s,
                                                             CamelException *ex);

`s` : |
`ex` : |
Returns : |

### camel_folder_summary_header_load ()

    gint                camel_folder_summary_header_load    (CamelFolderSummary *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 CamelFolderSummary object
Returns : | `0` on success or `-1` on fail

### camel_folder_summary_header_load_from_db ()

    gint                camel_folder_summary_header_load_from_db
                                                            (CamelFolderSummary *s,
                                                             CamelStore *store,
                                                             const gchar *folder_name,
                                                             CamelException *ex);

`s` : |
`store` : |
`folder_name` : |
`ex` : |
Returns : |

### camel_folder_summary_header_save_to_db ()

    gint                camel_folder_summary_header_save_to_db
                                                            (CamelFolderSummary *s,
                                                             CamelException *ex);

`s` : |
`ex` : |
Returns : |

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

`summary` : | a CamelFolderSummary object

### camel_folder_summary_add ()

    void                camel_folder_summary_add            (CamelFolderSummary *summary,
                                                             CamelMessageInfo *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_folder_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 CamelFolderSummary object
`info` : | a CamelMessageInfo

### camel_folder_summary_peek_info ()

    CamelMessageInfo *  camel_folder_summary_peek_info      (CamelFolderSummary *s,
                                                             const gchar *uid);

`s` : |
`uid` : |
Returns : |

### camel_folder_summary_get_changed ()

    GPtrArray *         camel_folder_summary_get_changed    (CamelFolderSummary *s);

`s` : |
Returns : |

### camel_folder_summary_cache_size ()

    gint                camel_folder_summary_cache_size     (CamelFolderSummary *s);

`s` : |
Returns : |

### camel_folder_summary_reload_from_db ()

    gint                camel_folder_summary_reload_from_db (CamelFolderSummary *s,
                                                             CamelException *ex);

`s` : |
`ex` : |
Returns : |

### camel_folder_summary_ensure_infos_loaded ()

    void                camel_folder_summary_ensure_infos_loaded
                                                            (CamelFolderSummary *s,
                                                             gint at_least,
                                                             CamelException *ex);

Loads all infos into memory, if they are not yet.

`s` : | CamelFolderSummary object
`at_least` : | How many infos already loaded are considered fine to not reload all of them. Use -1 to force reload of all of them if not in memory yet.
`ex` : | CamelException object.

### camel_folder_summary_insert ()

    void                camel_folder_summary_insert         (CamelFolderSummary *s,
                                                             CamelMessageInfo *info,
                                                             gboolean load);

`s` : |
`info` : |
`load` : |

### camel_folder_summary_remove_index_fast ()

    void                camel_folder_summary_remove_index_fast
                                                            (CamelFolderSummary *s,
                                                             gint index);

`s` : |
`index` : |

### camel_folder_summary_remove_uid_fast ()

    void                camel_folder_summary_remove_uid_fast
                                                            (CamelFolderSummary *s,
                                                             const gchar *uid);

`s` : |
`uid` : |

### camel_folder_summary_add_from_header ()

    CamelMessageInfo *  camel_folder_summary_add_from_header
                                                            (CamelFolderSummary *summary,
                                                             struct _camel_header_raw *headers);

Build a new info record based on a set of headers, and add it to the summary.

Note that this function should not be used if build_content_info has been specified for this summary.

`summary` : | a CamelFolderSummary object
`headers` : | rfc822 headers
Returns : | the newly added record

### camel_folder_summary_add_from_parser ()

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

Build a new info record based on the current position of a CamelMimeParser.

The parser should be positioned before the start of the message to summarise. This function may be used if build_contnet_info or an index has been specified for the summary.

`summary` : | a CamelFolderSummary object
`parser` : | a CamelMimeParser object
Returns : | the newly added record

### camel_folder_summary_add_from_message ()

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

Add a summary item from an existing message.

`summary` : | a CamelFolderSummary object
`message` : | a CamelMimeMessage object
Returns : | the newly added record

### camel_folder_summary_info_new_from_header ()

    CamelMessageInfo *  camel_folder_summary_info_new_from_header
                                                            (CamelFolderSummary *summary,
                                                             struct _camel_header_raw *headers);

Create a new info record from a header.

`summary` : | a CamelFolderSummary object
`headers` : | rfc822 headers
Returns : | the newly allocated record which must be freed with camel_message_info_free

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

`summary` : | a CamelFolderSummary object
`parser` : | a CamelMimeParser object
Returns : | the newly allocated record which must be freed with camel_message_info_free

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

`summary` : | a CamelFodlerSummary object
`message` : | a CamelMimeMessage object
Returns : | the newly allocated record which must be freed using camel_message_info_free

### camel_folder_summary_content_info_new ()

    CamelMessageContentInfo * camel_folder_summary_content_info_new
                                                            (CamelFolderSummary *summary);

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

`summary` : | a CamelFolderSummary object
Returns : | a newly allocated CamelMessageContentInfo

### camel_folder_summary_content_info_free ()

    void                camel_folder_summary_content_info_free
                                                            (CamelFolderSummary *summary,
                                                             CamelMessageContentInfo *ci);

Free the content info `ci`, and all associated memory.

`summary` : | a CamelFolderSummary object
`ci` : | a CamelMessageContentInfo

### camel_folder_summary_remove ()

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

Remove a specific `info` record from the summary.

`summary` : | a CamelFolderSummary object
`info` : | a CamelMessageInfo

### camel_folder_summary_remove_uid ()

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

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

`summary` : | a CamelFolderSummary object
`uid` : | a uid

### camel_folder_summary_remove_index ()

    void                camel_folder_summary_remove_index   (CamelFolderSummary *summary,
                                                             gint index);

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

`summary` : | a CamelFolderSummary object
`index` : | record index

### camel_folder_summary_remove_range ()

    void                camel_folder_summary_remove_range   (CamelFolderSummary *summary,
                                                             gint start,
                                                             gint end);

Removes an indexed range of info records.

`summary` : | a CamelFolderSummary object
`start` : | initial index
`end` : | last index to remove

### camel_folder_summary_clear ()

    void                camel_folder_summary_clear          (CamelFolderSummary *summary);

Empty the summary contents.

`summary` : | a CamelFolderSummary object

### camel_folder_summary_clear_db ()

    void                camel_folder_summary_clear_db       (CamelFolderSummary *s);

`s` : |

### camel_folder_summary_count ()

    guint               camel_folder_summary_count          (CamelFolderSummary *summary);

Get the number of summary items stored in this summary.

`summary` : | a CamelFolderSummary object
Returns : | the number of items in the summary

### camel_folder_summary_index ()

    CamelMessageInfo *  camel_folder_summary_index          (CamelFolderSummary *summary,
                                                             gint 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.

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

### camel_folder_summary_uid ()

    CamelMessageInfo *  camel_folder_summary_uid            (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.

`summary` : | a CamelFolderSummary object
`uid` : | a uid
Returns : | the summary item, or `NULL` if the uid `uid` is not available

### camel_folder_summary_uid_from_index ()

    gchar *             camel_folder_summary_uid_from_index (CamelFolderSummary *s,
                                                             gint i);

Retrieve a summary item's uid by index number.

A newly allocated uid is returned, which must be free'd as appropriate.

`s` : | a CamelFolderSummary object
`i` : | item index
Returns : | the summary item's uid , or `NULL` if `index` is out of range

### camel_folder_summary_check_uid ()

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

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

`s` : | a CamelFolderSummary object
`uid` : | a uid
Returns : | if the uid is present in the summary or not (`TRUE` or `FALSE`)

### camel_folder_summary_array ()

    GPtrArray *         camel_folder_summary_array          (CamelFolderSummary *summary);

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

It must be freed using g_ptr_array_free

`summary` : | a CamelFolderSummary object
Returns : | a GPtrArray of uids

### camel_folder_summary_get_hashtable ()

    GHashTable *        camel_folder_summary_get_hashtable  (CamelFolderSummary *s);

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

It must be freed using camel_folder_summary_free_hashtable

`s` : |
Returns : | a GHashTable of uids

### camel_folder_summary_free_hashtable ()

    void                camel_folder_summary_free_hashtable (GHashTable *ht);

`ht` : |

### camel_folder_summary_get_flag_cache ()

    GHashTable *        camel_folder_summary_get_flag_cache (CamelFolderSummary *summary);

`summary` : |
Returns : |

### camel_folder_summary_update_flag_cache ()

    void                camel_folder_summary_update_flag_cache
                                                            (CamelFolderSummary *s,
                                                             const gchar *uid,
                                                             guint32 flag);

`s` : |
`uid` : |
`flag` : |

### camel_folder_summary_encode_token ()

    gint                camel_folder_summary_encode_token   (FILE *out,
                                                             const gchar *str);

Encode a string value, but use tokenisation and compression to reduce the size taken for common mailer words. This can still be used to encode normal strings as well.

`out` : | output FILE pointer
`str` : | string token to encode
Returns : | `0` on success or `-1` on fail

### camel_folder_summary_decode_token ()

    gint                camel_folder_summary_decode_token   (FILE *in,
                                                             gchar **str);

Decode a token value.

`in` : | input FILE pointer
`str` : | string pointer to hold the decoded result
Returns : | `0` on success or `-1` on fail

### camel_flag_get ()

    gboolean            camel_flag_get                      (CamelFlag **list,
                                                             const gchar *name);

Find the state of the flag `name` in `list`.

`list` : | the address of a CamelFlag list
`name` : | name of the flag to get
Returns : | the state of the flag (`TRUE` or `FALSE`)

### camel_flag_set ()

    gboolean            camel_flag_set                      (CamelFlag **list,
                                                             const gchar *name,
                                                             gboolean value);

Set the state of a flag `name` in the list `list` to `value`.

`list` : | the address of a CamelFlag list
`name` : | name of the flag to set or change
`value` : | the value to set on the flag
Returns : | `TRUE` if the value of the flag has been changed or `FALSE` otherwise

### camel_flag_list_copy ()

    gboolean            camel_flag_list_copy                (CamelFlag **to,
                                                             CamelFlag **from);

Copy a flag list.

`to` : | the address of the CamelFlag list to copy to
`from` : | the address of the CamelFlag list to copy from
Returns : | `TRUE` if `to` is changed or `FALSE` otherwise

### camel_flag_list_size ()

    gint                camel_flag_list_size                (CamelFlag **list);

Get the length of the flag list.

`list` : | the address of a CamelFlag list
Returns : | the number of flags in the list

### camel_flag_list_free ()

    void                camel_flag_list_free                (CamelFlag **list);

Free the memory associated with the flag list `list`.

`list` : | the address of a CamelFlag list

### camel_system_flag ()

    guint32             camel_system_flag                   (const gchar *name);

`name` : | name of a system flag
Returns : | the integer value of the system flag string

### camel_system_flag_get ()

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

Find the state of the flag `name` in `flags`.

`flags` : | bitwise system flags
`name` : | name of the flag to check for
Returns : | `TRUE` if the named flag is set or `FALSE` otherwise

### camel_tag_get ()

    const gchar *       camel_tag_get                       (CamelTag **list,
                                                             const gchar *name);

Find the flag `name` in `list` and get the value.

`list` : | the address of a CamelTag list
`name` : | name of the tag to get
Returns : | the value of the flag or `NULL` if unset

### camel_tag_set ()

    gboolean            camel_tag_set                       (CamelTag **list,
                                                             const gchar *name,
                                                             const gchar *value);

Set the tag `name` in the tag list `list` to `value`.

`list` : | the address of a CamelTag list
`name` : | name of the tag to set
`value` : | value to set on the tag
Returns : | `TRUE` if the value on the tag changed or `FALSE` otherwise

### camel_tag_list_copy ()

    gboolean            camel_tag_list_copy                 (CamelTag **to,
                                                             CamelTag **from);

Copy a tag list.

`to` : | the address of the CamelTag list to copy to
`from` : | the address of the CamelTag list to copy from
Returns : | `TRUE` if `to` is changed or `FALSE` otherwise

### camel_tag_list_size ()

    gint                camel_tag_list_size                 (CamelTag **list);

Get the number of tags present in the tag list `list`.

`list` : | the address of a CamelTag list
Returns : | the number of tags

### camel_tag_list_free ()

    void                camel_tag_list_free                 (CamelTag **list);

Free the tag list `list`.

`list` : | the address of a CamelTag list

### camel_message_info_new ()

    gpointer            camel_message_info_new              (CamelFolderSummary *summary);

Create a new CamelMessageInfo.

`summary` : | a CamelFolderSummary object or `NULL`
Returns : | a new CamelMessageInfo

### camel_message_info_ref ()

    void                camel_message_info_ref              (gpointer info);

Reference an info.

`info` : | a CamelMessageInfo

### camel_message_info_new_from_header ()

    CamelMessageInfo *  camel_message_info_new_from_header  (CamelFolderSummary *summary,
                                                             struct _camel_header_raw *header);

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

`summary` : | a CamelFolderSummary object or `NULL`
`header` : | raw header
Returns : | a new CamelMessageInfo

### camel_message_info_free ()

    void                camel_message_info_free             (gpointer info);

Unref's and potentially frees a CamelMessageInfo and its contents.

`info` : | a CamelMessageInfo

### camel_message_info_clone ()

    gpointer            camel_message_info_clone            (gconstpointer info);

Duplicate a CamelMessageInfo.

`info` : | a CamelMessageInfo
Returns : | the duplicated CamelMessageInfo

### camel_message_info_ptr ()

    gconstpointer       camel_message_info_ptr              (const CamelMessageInfo *mi,
                                                             gint id);

Generic accessor method for getting pointer data.

`mi` : | a CamelMessageInfo
`id` : | info to get
Returns : | the pointer data

### camel_message_info_uint32 ()

    guint32             camel_message_info_uint32           (const CamelMessageInfo *mi,
                                                             gint id);

Generic accessor method for getting 32bit gint data.

`mi` : | a CamelMessageInfo
`id` : | info to get
Returns : | the gint data

### camel_message_info_time ()

    time_t              camel_message_info_time             (const CamelMessageInfo *mi,
                                                             gint id);

Generic accessor method for getting time_t data.

`mi` : | a CamelMessageInfo
`id` : | info to get
Returns : | the time_t data

### camel_message_info_uid()

    #define camel_message_info_uid(mi) ((const gchar *)((const CamelMessageInfo *)mi)->uid)

`mi` : |

### camel_message_info_subject()

    #define camel_message_info_subject(mi) ((const gchar *)camel_message_info_ptr((const CamelMessageInfo *)mi, CAMEL_MESSAGE_INFO_SUBJECT))

`mi` : |

### camel_message_info_preview()

    #define camel_message_info_preview(mi) ((const gchar *)camel_message_info_ptr((const CamelMessageInfo *)mi, CAMEL_MESSAGE_INFO_PREVIEW))

`mi` : |

### camel_message_info_from()

    #define camel_message_info_from(mi) ((const gchar *)camel_message_info_ptr((const CamelMessageInfo *)mi, CAMEL_MESSAGE_INFO_FROM))

`mi` : |

### camel_message_info_to()

    #define camel_message_info_to(mi) ((const gchar *)camel_message_info_ptr((const CamelMessageInfo *)mi, CAMEL_MESSAGE_INFO_TO))

`mi` : |

### camel_message_info_cc()

    #define camel_message_info_cc(mi) ((const gchar *)camel_message_info_ptr((const CamelMessageInfo *)mi, CAMEL_MESSAGE_INFO_CC))

`mi` : |

### camel_message_info_mlist()

    #define camel_message_info_mlist(mi) ((const gchar *)camel_message_info_ptr((const CamelMessageInfo *)mi, CAMEL_MESSAGE_INFO_MLIST))

`mi` : |

### camel_message_info_flags()

    #define camel_message_info_flags(mi) camel_message_info_uint32((const CamelMessageInfo *)mi, CAMEL_MESSAGE_INFO_FLAGS)

`mi` : |

### camel_message_info_size()

    #define camel_message_info_size(mi) camel_message_info_uint32((const CamelMessageInfo *)mi, CAMEL_MESSAGE_INFO_SIZE)

`mi` : |

### camel_message_info_date_sent()

    #define camel_message_info_date_sent(mi) camel_message_info_time((const CamelMessageInfo *)mi, CAMEL_MESSAGE_INFO_DATE_SENT)

`mi` : |

### camel_message_info_date_received()

    #define camel_message_info_date_received(mi) camel_message_info_time((const CamelMessageInfo *)mi, CAMEL_MESSAGE_INFO_DATE_RECEIVED)

`mi` : |

### camel_message_info_message_id()

    #define camel_message_info_message_id(mi) ((const CamelSummaryMessageID *)camel_message_info_ptr((const CamelMessageInfo *)mi, CAMEL_MESSAGE_INFO_MESSAGE_ID))

`mi` : |

### camel_message_info_references()

    #define camel_message_info_references(mi) ((const CamelSummaryReferences *)camel_message_info_ptr((const CamelMessageInfo *)mi, CAMEL_MESSAGE_INFO_REFERENCES))

`mi` : |

### camel_message_info_user_flags()

    #define camel_message_info_user_flags(mi) ((const CamelFlag *)camel_message_info_ptr((const CamelMessageInfo *)mi, CAMEL_MESSAGE_INFO_USER_FLAGS))

`mi` : |

### camel_message_info_user_tags()

    #define camel_message_info_user_tags(mi) ((const CamelTag *)camel_message_info_ptr((const CamelMessageInfo *)mi, CAMEL_MESSAGE_INFO_USER_TAGS))

`mi` : |

### camel_message_info_headers()

    #define camel_message_info_headers(mi) ((const struct _camel_header_param *)camel_message_info_ptr((const CamelMessageInfo *)mi, CAMEL_MESSAGE_INFO_HEADERS))

`mi` : |

### camel_message_info_user_flag ()

    gboolean            camel_message_info_user_flag        (const CamelMessageInfo *mi,
                                                             const gchar *id);

Get the state of a user flag named `id`.

`mi` : | a CamelMessageInfo
`id` : | user flag to get
Returns : | the state of the user flag

### camel_message_info_user_tag ()

    const gchar *       camel_message_info_user_tag         (const CamelMessageInfo *mi,
                                                             const gchar *id);

Get the value of a user tag named `id`.

`mi` : | a CamelMessageInfo
`id` : | user tag to get
Returns : | the value of the user tag

### camel_message_info_set_flags ()

    gboolean            camel_message_info_set_flags        (CamelMessageInfo *mi,
                                                             guint32 flags,
                                                             guint32 set);

Change the state of the system flags on the CamelMessageInfo

`mi` : | a CamelMessageInfo
`flags` : | mask of flags to change
`set` : | state the flags should be changed to
Returns : | `TRUE` if any of the flags changed or `FALSE` otherwise

### camel_message_info_set_user_flag ()

    gboolean            camel_message_info_set_user_flag    (CamelMessageInfo *mi,
                                                             const gchar *id,
                                                             gboolean state);

Set the state of a user flag on a CamelMessageInfo.

`mi` : | a CamelMessageInfo
`id` : | name of the user flag to set
`state` : | state to set the flag to
Returns : | `TRUE` if the state changed or `FALSE` otherwise

### camel_message_info_set_user_tag ()

    gboolean            camel_message_info_set_user_tag     (CamelMessageInfo *mi,
                                                             const gchar *id,
                                                             const gchar *val);

Set the value of a user tag on a CamelMessageInfo.

`mi` : | a CamelMessageInfo
`id` : | name of the user tag to set
`val` : | value to set
Returns : | `TRUE` if the value changed or `FALSE` otherwise

### camel_folder_summary_set_need_preview ()

    void                camel_folder_summary_set_need_preview
                                                            (CamelFolderSummary *summary,
                                                             gboolean preview);

`summary` : |
`preview` : |

### camel_folder_summary_add_preview ()

    void                camel_folder_summary_add_preview    (CamelFolderSummary *s,
                                                             CamelMessageInfo *info);

`s` : |
`info` : |

### camel_folder_summary_get_need_preview ()

    gboolean            camel_folder_summary_get_need_preview
                                                            (CamelFolderSummary *summary);

`summary` : |
Returns : |

### camel_content_info_dump ()

    void                camel_content_info_dump             (CamelMessageContentInfo *ci,
                                                             gint depth);

`ci` : |
`depth` : |

### camel_message_info_dump ()

    void                camel_message_info_dump             (CamelMessageInfo *mi);

`mi` : |

### camel_folder_summary_migrate_infos ()

    gint                camel_folder_summary_migrate_infos  (CamelFolderSummary *s);

`s` : |
Returns : |