Adding upstream version 1:2.3.21+dfsg1.upstream/1%2.3.21+dfsg1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 41 insertions, 0 deletions

diff --git a/doc/wiki/Design.Storage.MailStorage.txt b/doc/wiki/Design.Storage.MailStorage.txt
new file mode 100644
index 0000000..3052d8f
--- /dev/null
+++ b/doc/wiki/Design.Storage.MailStorage.txt
@@ -0,0 +1,41 @@
+Mail Storage
+============
+
+'src/lib-storage/mail-storage.h' and 'mail-storage-private.h' describes mail
+storage. Mail storage is mainly about being a common container for its
+mailboxes. For example with <multi-dbox> [MailboxFormat.dbox.txt] each storage
+has one directory where all the message bodies are written to, while the
+per-mailbox directories only contain index files. With other mailbox formats
+mail storage doesn't do much else than allow allocating <mailboxes>
+[Design.Storage.Mailbox.txt].
+
+The only public functions for mail storage are:
+
+ * 'mail_storage_purge()' frees disk space used by expunged messages. Currently
+   the only mailbox format that uses this is multi-dbox.
+ * 'mail_storage_get_settings()' returns mail storage settings.
+ * 'mail_storage_set_callbacks()' can be used to specify "OK" and "NO"
+   callbacks, which are called when a long running operation wants to send a
+   status update. For example "OK Stale mailbox lock file detected, will
+   override in n seconds" or "NO Mailbox is locked, will abort in n seconds".
+
+Methods that mail storage backends need to implement are:
+
+ * 'get_setting_parser_info()': Returns storage-specific settings parser
+   information.
+ * 'alloc()': Allocate memory for a storage and set its virtual functions.
+ * 'create(ns)': Initialize the storage based on given namespace settings. The
+   same storage can be used by other namespaces, but they don't call 'create()'
+   again. This function typically shouldn't fail, except when storage can't
+   handle the wanted namespace settings.
+ * 'destroy()': Destroys the storage.
+ * 'add_list(list)': Called every time the storage is attached to a new
+   namespace / mailbox list.
+ * 'get_list_settings(ns, set)': Used to get storage's default settings.
+ * 'autodetect(ns, set)': Returns TRUE if based on the given settings it looks
+   like this storage should be handling the namespace. This is done when
+   mail_location doesn't explicitly specify the mailbox format.
+ * 'mailbox_alloc()': Allocate memory for <mailbox>
+   [Design.Storage.Mailbox.txt].
+
+(This file was created from the wiki on 2019-06-19 12:42)