Camel.StoreSummary

CamelStoreSummary is a helper class that Evolution/Camel.Store objects can used to keep track of their folder lists. It is designed to have a similar API to Evolution/Camel.FolderInfo.

It is used by NNTP and IMAP to manage the subscription lists as well as keep track of the list of folders for offline operation.

It also serves another purpose in those implementations, that of mapping camel's canonical folder names, which must be / separated and in UTF-8 into the raw names that an implementation might use. For example although IMAP names have a defined canonical mapping for non-ASCII data, many servers or other clients do not properly implement it. As such there is no algorithmic method for converting a / separated path name to the physical name, and a lookup table must be maintained instead.

Base class

The base class contains some control data and information, but of main interest is the header information stored in the summary file, and the url_base, which is used to algorithmically generate URI's internally.

 struct _CamelStoreSummary {
        CamelObject parent;
        struct _CamelStoreSummaryPrivate *priv;
 
        guint32 version;
        guint32 flags;
        guint32 count;
        time_t time;
        struct _CamelURL *uri_base;
 
        guint32 store_info_size;
 
        struct _EMemChunk *store_info_chunks;
 
        char *summary_path;
 
        GPtrArray *folders;
        GHashTable *folders_path;
 };

For more information see the source-code.

Note that this is just a helper class for CamelStores, it is not directly publically accessible, and CamelStore implementations need not use it. For example the local backends do not track their folder lists separately from the folder files and summaries.

Camel.StoreInfo

CamelStoreInfo is the record used to load/save folder information by the store. Implementations may subclass this using the virtual methods in the same way that they might with Evolution/Camel.FolderSummary#Camel.FolderInfo.

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

The fields and bits are intentionally the same as the CamelFolderInfo ones, although they also have their own named defines as well. This is the base data stored in each record.

Notes

Originally, CamelStoreInfo was intended to replace CamelFolderInfo entirely. In reality they're not quite the same and not interchangeable, so the utility of this class being public is limited.

Again, if the CamelFolderInfo interface went away, so would this; it is yet another level of data duplication which is difficult to keep in sync with the actual folders.