1 files changed, 47 insertions, 0 deletions
diff --git a/doc/wiki/Design.Indexes.MailIndexApi.txt b/doc/wiki/Design.Indexes.MailIndexApi.txt
new file mode 100644
index 0000000..e7f597b
--- /dev/null
+++ b/doc/wiki/Design.Indexes.MailIndexApi.txt
@@ -0,0 +1,47 @@
+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 2019-06-19 12:42)