1 files changed, 34 insertions, 0 deletions
diff --git a/doc/wiki/Design.Storage.Mailbox.txt b/doc/wiki/Design.Storage.Mailbox.txt
new file mode 100644
index 0000000..5af8263
--- /dev/null
+++ b/doc/wiki/Design.Storage.Mailbox.txt
@@ -0,0 +1,34 @@
+Mailbox
+=======
+
+'src/lib-storage/mail-storage.h' and 'mail-storage-private.h' describes mailbox
+API, among others. Mailbox life cycle often goes like:
+
+ * 'mailbox_alloc()' allocates memory for the mailbox and initializes some
+   internal settings, but doesn't actually try to open it.
+ * 'mailbox_open()' opens the mailbox. Instead of opening a mailbox, you can
+   also create it with 'mailbox_create()'.
+    * If you're immediately syncing the mailbox, you don't need to open it,
+      because it's done implicitly. This reduces your code and error handling a
+      bit.
+ * 'mailbox_close()' closes the mailbox, so that it needs to be opened again if
+   it's wanted to be accessed. This is rarely needed.
+ * 'mailbox_free()' closes and frees the mailbox.
+
+There are a lot of functions to deal with mailboxes. The most important ones
+are:
+
+ * 'mailbox_get_status()' to get a summary of mailbox, such as number of
+   messages in it.
+ * <Syncing> [Design.Storage.Mailbox.Sync.txt]: 'mailbox_sync_*()' to
+   synchronize changes from the backend to memory.
+ * <Transactions> [Design.Storage.Mailbox.Transaction.txt]:
+   'mailbox_transaction_*()' for transaction handling. All message reads and
+   writes are done in a transaction.
+ * <Searching> [Design.Storage.Mailbox.Search.txt]: 'mailbox_search_*()' is
+   used for searching messages. Even simple operations like "get all messages"
+   go through this API, it'll then simply do "search all".
+ * <Saving> [Design.Storage.Mailbox.Save.txt]: 'mailbox_save_*()' and
+   'mailbox_copy()' is used for saving/copying new messages to mailbox.
+
+(This file was created from the wiki on 2019-06-19 12:42)