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