Camel-lite internals and documentation

The IMAP message cache

Two hashtables

CamelImapMessageCache (libtinymail-camel/camel-lite/camel/providers/imap/camel-imap-message-cache.c) are two hash tables "parts" and "cached":

• The parts hashtable has as key the filename of the cached message, and as value a file-stream to it.
• The cached hashtable as as key the file-stream to a cached message, and as value the filename of it.

The filename, after a message gets added, is formed using the cache path concatenated with the uid of the message on the IMAP service, a dot and a part_spec which usually is a blanco string.

Upon construction of the CamelImapMessageCache instance is the folder cleaned up (in case a cached message was not found in the summary, CamelFolderSummary or its specialized CamelImapSummary, of the folder).

When adding and removing messages to the cache, both hash tables are updated and the actual files are created and removed using a file stream (camel_stream_fs_new_with_fd in the insert_setup helper function of CamelImapMessageCache).

Being used by

Adding messages to the cache

The functions in CamelImapFolder (libtinymail-camel/camel-lite/camel/providers/imap/camel-imap-folder.c) that can cause a message to get appended to the cache are parse_fetch_response, imap_append_online and imap_append_offline. A cached message can also be copied, which of course also appends a new message (the copy) to the cache, using camel_imap_message_cache_copy.

Getting messages from the cache (if available) and else adding it

It's camel_imap_folder_fetch_data in CamelImapFolder who tries to first camel_imap_message_cache_get the message from the cache before falling back to getting it from the service, followed by a parse_fetch_response which will camel_imap_message_cache_insert it into the same cache. The file-stream of the cache is returned in the GData return value of parse_fetch_response as field "BODY_PART_STREAM".

Note that parse_fetch_response is also used for other purposes. A (ugly) hack in parse_fetch_response, by reading the result of the IMAP command, detects whether or not the message should indeed be cached.