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