unfinished...

Camel-lite internals and documentation

Retrieving messages with IMAP

Basics

This is actually very simple but you should also read how the cache works because this is strongly related.

Camel abstracts the get_message method and the CamelImapFolder obviously implements this (imap_get_message). The partial message retrieval functionality added a full boolean parameter to the method itself.

What will happen

The imap_get_message accepts the uid of the message. This is a little bit stupid in my opinion, because it gets immediately converted to the corresponding CamelMessageInfo. I can't really think of a lot situations where the programmer don't already has this instance. How on earth can, without the message-info instance, the developer know the uid that he's interested in? Well there are a few possibilities maybe. Anyway, this causes extra needless error checking (what if the uid doesn't exist in the folder).

The camel_imap_folder_fetch_data method is now called with the cache_only parameter set to TRUE. If that one returned a stream (this is going to be a file stream to the cached message), then get_message_simple is used on that stream instance to create a CamelMimeMessage out of that, and return it. This is the imap cache at work.

If it was NULL (the stream), it means that the message was not cached. The code will then proceed with or get_message or get_message_simple (depending on for example the IMAP capabilities, the get_message allows to fetch specific mime parts piece by piece, whereas the simple one fetches the entire messge). Both will in turn call camel_imap_folder_fetch_data which will retrieve the message and put it into the imap message cache, and return a stream created using that file. That stream is then used to create a CamelMimeMessage back in the get_message and get_message_simple methods.

They use the camel_data_wrapper_construct_from_stream API for that (CamelMimeMessage inherits CamelDataWrapper).