Edit File: Design.Storage.Mail.txt
Mail ==== Mail is first allocated with 'mail_alloc()'. Mails always belong to a <transaction> [Design.Storage.Mailbox.Transaction.txt]. Even if mail is treated read-only, Dovecot might write data to cache file, so whenever possible, mail transactions should be committed. When mail is allocated, you can specify a list of fields and headers that you're (most likely) going to need. This allows Dovecot to optimize the later 'mail_get_*()' lookups so that it doesn't need to parse the message multiple times. These fields are also added to cache file, so you shouldn't list fields unless you're fairly certain you need them. If you need to jump around in the mailbox based on already known sequences or UIDs, you can do this with 'mail_set_seq()' and 'mail_set_uid()'. This way you don't have to go through all the trouble of setting up a mailbox search. Getting data ------------ Some of the mail fields can be accessed directly: * 'box': Mail's mailbox, same as the transaction's. * 'transaction': Mail's transaction, the same that was given to 'mail_alloc()'. * 'seq': Currently selected message's sequence number. * 'uid': Currently selected message's UID. * 'expunged': We already detected that the message is expunged and can't be accessed. This may also be set (and looked up) later when some 'mail_get_*()' function fails. * 'has_nuls' and 'has_no_nuls': Message body is known to (not) have NUL characters. The final field is 'lookup_abort', which is write-only. Normally when doing a 'mail_get_*()' operation for a field that isn't in a cache, the field is generated and added to cache. If you don't want this, but instead have figured out some better optimized way to do non-cached lookups, you can change this field so that 'mail_get_*()' lookups fail instead. This is primarily used by searching code internally. * 'MAIL_LOOKUP_ABORT_NEVER': The default - do whatever it takes to return the value. * 'MAIL_LOOKUP_ABORT_READ_MAIL': If returning the value would require reading message headers/body, abort. * 'MAIL_LOOKUP_ABORT_NOT_IN_CACHE': If the value isn't already in cache, abort. For example if looking up message's physical size would require 'stat()'ing the file this wouldn't be done. Most of the 'mail_get_*()' should be fairly obvious in how they work. Only functions returning int can fail, others don't. * Keywords can be looked up either by getting an array of keyword strings or keyword indexes. The index lookups are slightly faster. Keyword indexes can be converted to strings by using the 'status.keywords' array returned by 'mailbox_get_status()'. * 'mail_get_first_header()' return 0 if header wasn't found, 1 if it was. * 'mail_get_special()' can return various special fields. If a special isn't implemented by some backend, the call returns success and sets the value to "". * 'mail_get_stream()' returns an input stream that can be used to access the mail. If this function is called multiple times, each call seeks the stream to beginning. Don't unreference the stream, it's destroyed automatically. * Typically the input contains the raw data in disk, lines may end with LF or CRLF depending on how they're on disk. * mbox drops Dovecot's internal headers from the stream (X-UID:, Status:, etc.). * Plugins (e.g. zlib) can also hook into this call and modify the input stream. Sometimes you might notice that some looked up field is actually corrupted. For example you might notice that input stream returns EOF earlier than previous 'mail_get_physical_size()' said. This might have been caused by various different things, but in any case all you can really do then is to just call 'mail_set_cache_corrupted()' and try again. Setting data ------------ Some of the messages' metadata can be updated: * 'mail_update_flags()' and 'mail_update_keywords()' changes flags/keywords. * Usually you should set 'modify_type' parameter to 'MODIFY_ADD' or 'MODIFY_REMOVE', instead of replacing all the flags. That allows concurrent flag updates not to overwrite each others changes. * 'mail_expunge()' expunges a message. Other functions are mainly intended for mailbox replication or restoring an existing mailbox (e.g. dsync): * 'mail_update_modseq()' can be used to increase message's modseq * 'mail_update_uid()' can be used to give a new (higher) UID for the message. If such UID can't be given, this call is just ignored. * 'mail_update_pop3_uidl()' can be used to give a specific POP3 UIDL for the message. This is used internally when 'pop3_save_uidl=yes'. Other metadata can't be changed. IMAP protocol requires that messages are immutable, so it's not possible to change message's received date, headers or body. If you wish to modify any of them, you need to create a new message and expunge the old one. (This file was created from the wiki on 2018-02-28 04:42)