Mail Index API
==============

'lib-index/mail-index.h' contains the functions to access the index files.
'mail-cache.h' contains the functions to access the cache file.

The purpose of the main structures are:

 * 'struct mail_index': Global state of the index.
 * 'struct mail_index_view': You can have multiple views to the index. The
   views see new messages come and expunged messages go only when it's being
   explicitly synchronized. With mmaped indexes you can't really trust the
   record data (flags, keywords, extensions) not to change. This doesn't matter
   with IMAP.
 * 'struct mail_index_map': Index file is accessed via maps. Views can point to
   one or more maps. Maps can be shared by different views. Maps can contain
   either mmap()ed memory areas pointing to the index file, or a in-memory copy
   of it.
 * 'struct mail_index_transaction': In-memory list of changes to be written to
   the transaction log. The writing is done only when the transaction is
   committed.

Views and maps
--------------

In general you access all the data in the index files via views. The mails are
accessed using sequence numbers, which change only when the view is
synchronized.

For accessing messages with their UIDs, you'll first need to convert them to
sequences with either 'mail_index_lookup_uid()' or
'mail_index_lookup_uid_range()'.

'mail_index_lookup()' can be used to look up a single record's UID and flags.
The returned record points to the latest map, so that it contains the latest
flag changes. If the message was already expunged from the latest map, it
returns 0.

'mail_index_lookup_full()' can be used to get also the map where the message
was found. This can be important with extensions. If extension record's state
depends on the extension header, they must be looked up from the same map. For
this reason there exists 'mail_index_map_get_header_ext()' and
'mail_index_lookup_ext_full()' functions which take the map as parameter. The
non-map versions return the data from the latest map if the message hasn't been
expunged.

(This file was created from the wiki on 2017-10-10 04:42)