1 files changed, 51 insertions, 0 deletions
diff --git a/doc/wiki/Design.Storage.Mailbox.Save.txt b/doc/wiki/Design.Storage.Mailbox.Save.txt
new file mode 100644
index 0000000..69ee754
--- /dev/null
+++ b/doc/wiki/Design.Storage.Mailbox.Save.txt
@@ -0,0 +1,51 @@
+Mailbox Saving
+==============
+
+Both saving and copying messages begins by calling 'mailbox_save_alloc()'.
+After that you can set message's metadata fields:
+
+ * 'mailbox_save_set_flags()' sets flags and keywords.
+ * 'mailbox_save_set_received_date()' sets message's received date (IMAP
+   INTERNALDATE). It also supports specifying timezone, but most backends don't
+   support saving it.
+ * 'mailbox_save_set_dest_mail()' specifies a mail that can be used to access
+   the partially saved mail after save/copy is finished (but not committed).
+   You should be able to do pretty much anything with the mail, but its UID is
+   usually 0 at this point.
+ * 'mailbox_save_set_from_envelope()' sets the envelope sender. Currently this
+   is only used by mbox format to specify the address in From_-line.
+
+When copying, most of the metadata fields are automatically copied from the
+source message. The only exception is message's flags and keywords. If you want
+to preserve them, the easiest way is to call 'mailbox_save_copy_flags()'.
+
+Some metadata fields are mainly useful when you're replicating or restoring an
+existing mailbox and want to preserve metadata:
+
+ * 'mailbox_save_set_min_modseq()' sets message's modseq to at least the
+   specified modseq. If the modseqs are already higher in the mailbox, the
+   resulting modseq is what it would have been without this call.
+ * 'mailbox_save_set_uid()' sets message's UID. If mailbox's next_uid is
+   already higher than the specified UID, the UID request is ignored.
+ * 'mailbox_save_set_guid()' sets message's globally unique ID. A new GUID is
+   generated by default, and if there already exists a message with the same
+   GUID a different one may or may not be given. For example with maildir the
+   GUID is same as the base filename, while dbox has an explicit GUID metadata
+   field.
+ * 'mailbox_save_set_pop3_uidl()' sets POP3 UIDL value. Not all backends
+   support this.
+ * 'mailbox_save_set_save_date()' sets "message saved" date, i.e. the date/time
+   when the message was saved to this mailbox. The default is the current time.
+
+Once you're done with setting the metadata fields, you can either copy an
+existing mail with 'mailbox_copy()' or provide message body with:
+
+ * 'mailbox_save_begin()' starts saving from given input stream.
+ * 'mailbox_save_continue()' saves all data from input stream. If input stream
+   is blocking, typically a single call to this function should be enough. If
+   input stream is non-blocking, you need to call this function until you're
+   done. In any case call this until 'i_stream_is_eof()' returns TRUE.
+ * 'mailbox_save_finish()' finishes saving the mail, or 'mailbox_save_cancel()'
+   aborts it.
+
+(This file was created from the wiki on 2019-06-19 12:42)