mail-index.h revision 87712707722ef7d73acb065546e61afa4455cd9e
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen/* Number of custom flags in mail_index_record. */
b3254619187a08d0ecbdfaf4d251468158287c40Timo Sirainen#define INDEX_CUSTOM_FLAGS_BYTE_COUNT ((INDEX_CUSTOM_FLAGS_COUNT*7)/8)
b3254619187a08d0ecbdfaf4d251468158287c40Timo Sirainen /* Create index if it doesn't exist */
b3254619187a08d0ecbdfaf4d251468158287c40Timo Sirainen /* Open the index as fast as possible - do only minimal checks and
b3254619187a08d0ecbdfaf4d251468158287c40Timo Sirainen delay opening cache/log files unless they're needed. */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen /* Don't try to mmap() index files */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen /* Don't try to write() to mmap()ed index files. Required for the few
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen OSes that don't have unified buffer cache
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen (currently OpenBSD <= 3.5) */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen /* Don't use fcntl() locking */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen MAIL_INDEX_OPEN_FLAG_FCNTL_LOCKS_DISABLE= 0x10
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen /* Corrupted-flag should be set while anything dangerous is done to
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen index file, such as when expunging messages. Once the operation
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen is finished, the corrupted-flag is removed. If this flag is noticed
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen unexpectedly, the index must be assumed to be corrupted and must
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen not be used. */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen /* If binary flags are set, it's not checked whether mail is
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen missing CRs. So this flag may be set as an optimization for
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen regular non-binary mails as well if it's known that it contains
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen valid CR+LF line breaks. */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen /* Mail header or body is known to contain NUL characters. */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen /* Mail header or body is known to not contain NUL characters. */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen /* No errors */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen /* Internal error, see get_error_text() for more information. */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen /* We ran out of available disk space. */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen (MAIL_ANSWERED | MAIL_FLAGGED | MAIL_DELETED | MAIL_SEEN | MAIL_DRAFT)
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainentypedef unsigned char custom_flags_mask_t[INDEX_CUSTOM_FLAGS_BYTE_COUNT];
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen /* major version is increased only when you can't have backwards
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen compatibility. minor version is increased when header size is
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen increased to contain new non-critical fields. */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen 1 = sizeof(uoff_t)
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen 2 = sizeof(time_t)
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen 3 = reserved, 0 for now */
8a68b403f982d0f1b2d628ea826ea5385771a787Timo Sirainen /* these UIDs may not exist and may not even be unseen */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen uint8_t flags; /* mail_flags | mail_index_mail_flags */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen /* MAIL_INDEX_SYNC_TYPE_FLAGS: */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen /* MAIL_INDEX_SYNC_TYPE_APPEND: */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainenstruct mail_index *mail_index_alloc(const char *dir, const char *prefix);
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainenvoid mail_index_free(struct mail_index *index);
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainenint mail_index_open(struct mail_index *index, enum mail_index_open_flags flags);
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainenvoid mail_index_close(struct mail_index *index);
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainenstruct mail_cache *mail_index_get_cache(struct mail_index *index);
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen/* View can be used to look into index. Sequence numbers inside view change
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen only when you synchronize it. The view acquires required locks
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen automatically, but you'll have to drop them manually. Opening view
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen acquires a lock immediately. */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainenstruct mail_index_view *mail_index_view_open(struct mail_index *index);
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainenvoid mail_index_view_close(struct mail_index_view *view);
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen/* Returns the index for given view. */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainenstruct mail_index *mail_index_view_get_index(struct mail_index_view *view);
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen/* Call whenever you've done with requesting messages from view for a while. */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainenvoid mail_index_view_unlock(struct mail_index_view *view);
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen/* Returns number of mails in view. */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainenuint32_t mail_index_view_get_message_count(struct mail_index_view *view);
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen/* Returns TRUE if we lost track of changes for some reason. */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainenint mail_index_view_is_inconsistent(struct mail_index_view *view);
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen/* Transaction has to be opened to be able to modify index. You can have
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen multiple transactions open simultaneously. Note that committed transactions
8a68b403f982d0f1b2d628ea826ea5385771a787Timo Sirainen won't show up until you've synchronized mailbox (mail_index_sync_begin). */
b3254619187a08d0ecbdfaf4d251468158287c40Timo Sirainenmail_index_transaction_begin(struct mail_index_view *view, int hide);
b3254619187a08d0ecbdfaf4d251468158287c40Timo Sirainenint mail_index_transaction_commit(struct mail_index_transaction *t,
cbd6cad82e1c9ad60869ad71ae6c42e1af8b10a8Timo Sirainenvoid mail_index_transaction_rollback(struct mail_index_transaction *t);
cbd6cad82e1c9ad60869ad71ae6c42e1af8b10a8Timo Sirainen/* Begin synchronizing mailbox with index file. This call locks the index
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen exclusively against other modifications. Returns 1 if ok, -1 if error.
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen If log_file_seq is not (uint32_t)-1 and index is already synchronized up
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen to given log_file_offset, the synchronization isn't started and this
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen function returns 0. This should be done when you wish to sync your previous
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen transaction instead of doing a full mailbox synchronization.
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen mail_index_sync_next() returns all changes from previously committed
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen transactions which haven't yet been committed to the actual mailbox.
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen They're returned in ascending order. You must go through all of them and
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen update the mailbox accordingly.
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen None of the changes actually show up in index until at
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen mail_index_sync_end().
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen Note that there may be multiple overlapping flag changes. They're returned
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen sorted by their beginning sequence. They never overlap expunges however.
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen Returned sequence numbers describe the mailbox state at the beginning of
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen synchronization, ie. expunges don't affect them.
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen You may create a new transaction for the returned view. That transaction
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen acts as "external mailbox changes" transaction. Any changes done there are
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen expected to describe mailbox's current state. */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainenint mail_index_sync_begin(struct mail_index *index,
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen uint32_t log_file_seq, uoff_t log_file_offset);
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen/* Returns -1 if error, 0 if sync is finished, 1 if record was filled. */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainenint mail_index_sync_next(struct mail_index_sync_ctx *ctx,
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen/* Returns 1 if there's more to sync, 0 if not. */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainenint mail_index_sync_have_more(struct mail_index_sync_ctx *ctx);
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen/* End synchronization by unlocking the index and closing the view. */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainenint mail_index_sync_end(struct mail_index_sync_ctx *ctx);
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen/* Mark index file corrupted. Invalidates all views. */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainenvoid mail_index_mark_corrupted(struct mail_index *index);
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen/* Check and fix any found problems. If index is broken beyond repair, calls
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen mail_index_reset() and returns 0. Otherwise returns -1 if there was some
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen I/O error or 1 if everything went ok. */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen/* Synchronize changes in view. You have to go through all records, or view
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen will be marked inconsistent. Only sync_mask type records are
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen synchronized. */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainenint mail_index_view_sync_begin(struct mail_index_view *view,
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen/* Returns -1 if error, 0 if sync is finished, 1 if record was filled. */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainenint mail_index_view_sync_next(struct mail_index_view_sync_ctx *ctx,
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainenmail_index_view_sync_get_expunges(struct mail_index_view_sync_ctx *ctx,
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainenvoid mail_index_view_sync_end(struct mail_index_view_sync_ctx *ctx);
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen/* Returns the index header. */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainenint mail_index_get_header(struct mail_index_view *view,
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen/* Returns the given message. */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainenint mail_index_lookup(struct mail_index_view *view, uint32_t seq,
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen/* Returns the UID for given message. May be slightly faster than
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen mail_index_lookup()->uid */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainenint mail_index_lookup_uid(struct mail_index_view *view, uint32_t seq,
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen/* Convert UID range to sequence range. If no UIDs are found, sequences are
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen set to 0. Note that any of the returned sequences may have been expunged
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainenint mail_index_lookup_uid_range(struct mail_index_view *view,
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen/* Find first mail with (mail->flags & flags_mask) == flags. Useful mostly for
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen taking advantage of lowwater-fields in headers. */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainenint mail_index_lookup_first(struct mail_index_view *view, enum mail_flags flags,
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen/* Append a new record to index. */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainenvoid mail_index_append(struct mail_index_transaction *t, uint32_t uid,
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen/* Expunge record from index. Note that this doesn't affect sequence numbers
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen until transaction is committed and mailbox is synced. */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainenvoid mail_index_expunge(struct mail_index_transaction *t, uint32_t seq);
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen/* Update flags in index. */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainenvoid mail_index_update_flags(struct mail_index_transaction *t, uint32_t seq,
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen/* Returns the last error code. */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainenenum mail_index_error mail_index_get_last_error(struct mail_index *index);
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen/* Returns the full error message for last error. This message may
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen contain paths etc. so it shouldn't be shown to users. */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainenconst char *mail_index_get_error_message(struct mail_index *index);
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen/* Reset the error message. */
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainenvoid mail_index_reset_error(struct mail_index *index);
3d7590a656f4f746b2adc6e00fa607eba5d2412dTimo Sirainen/* Returns TRUE if index is currently only in memory. */
3d7590a656f4f746b2adc6e00fa607eba5d2412dTimo Sirainenint mail_index_is_in_memory(struct mail_index *index);
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen/* Apply changes in MAIL_INDEX_SYNC_TYPE_FLAGS typed sync records to given
fb15bb48cf8be41cd94738c868b64608b4fda1adTimo Sirainen flags variables. */