mail-index.h revision 893e5bbd5184ec5c21f47c67c8ea6efbea41f7d0
7384b4e78eaab44693c985192276e31322155e32Stephan Bosch /* Create index if it doesn't exist */
7384b4e78eaab44693c985192276e31322155e32Stephan Bosch /* Don't try to mmap() index files */
7384b4e78eaab44693c985192276e31322155e32Stephan Bosch /* Rely on O_EXCL when creating dotlocks */
7384b4e78eaab44693c985192276e31322155e32Stephan Bosch /* Don't fsync() or fdatasync() */
de96afeeaa5242cffe89f1966457e935806b5746Stephan Bosch /* Index file is corrupted, reopen or recreate it. */
de96afeeaa5242cffe89f1966457e935806b5746Stephan Bosch /* fsck the index next time when opening */
de96afeeaa5242cffe89f1966457e935806b5746Stephan Bosch (MAIL_ANSWERED | MAIL_FLAGGED | MAIL_DELETED | MAIL_SEEN | MAIL_DRAFT)
de96afeeaa5242cffe89f1966457e935806b5746Stephan Bosch /* major version is increased only when you can't have backwards
de96afeeaa5242cffe89f1966457e935806b5746Stephan Bosch compatibility. minor version is increased when header size is
de96afeeaa5242cffe89f1966457e935806b5746Stephan Bosch increased to contain new non-critical fields. */
de96afeeaa5242cffe89f1966457e935806b5746Stephan Bosch uint32_t header_size; /* base + extended header size */
de96afeeaa5242cffe89f1966457e935806b5746Stephan Bosch uint8_t compat_flags; /* enum mail_index_header_compat_flags */
7384b4e78eaab44693c985192276e31322155e32Stephan Bosch /* these UIDs may not exist and may not even be unseen */
7384b4e78eaab44693c985192276e31322155e32Stephan Bosch /* non-external records between tail..head haven't been committed to
7384b4e78eaab44693c985192276e31322155e32Stephan Bosch mailbox yet. */
7384b4e78eaab44693c985192276e31322155e32Stephan Bosch /* daily first UIDs that have been added to index. */
7384b4e78eaab44693c985192276e31322155e32Stephan Bosch uint8_t flags; /* enum mail_flags | enum mail_index_mail_flags */
b99130e4cf4af4e6b103b949456222f3a2dff424Timo Sirainen /* variable sized list of keyword indexes */
4c4c4a740bbb1b674d4b0dae009d1919f8ad96b7Stephan Bosch /* Resync all dirty messages' flags. */
4c4c4a740bbb1b674d4b0dae009d1919f8ad96b7Stephan Bosch /* Drop recent flags from all messages */
4c4c4a740bbb1b674d4b0dae009d1919f8ad96b7Stephan Bosch /* Don't sync expunges */
9d746c6785d17e421c3f3c74cf29d059ae2ab233Stephan Bosch /* MAIL_INDEX_SYNC_TYPE_FLAGS: */
fe2b0e3de834dd40b698bb579adc5357d5789ec9Stephan Bosch /* MAIL_INDEX_SYNC_TYPE_KEYWORD_ADD, .._REMOVE: */
486c7c8d9e725e0227c7723aa43b7fce724eb9eeStephan Bosch /* keyword appends and removes are packed into one and same
e47c2f17d8136c4d972d1074a3f84ba2ecef4fdcStephan Bosch MAIL_INDEX_SYNC_TYPE_KEYWORD_ADD */
b66def5dadd3e7c250313a938d26ad113663f86bStephan BoschARRAY_DEFINE_TYPE(keyword_indexes, unsigned int);
c972eaa3565e849df71b44cf0cd45d38c5567d07Stephan Boschstruct mail_index *mail_index_alloc(const char *dir, const char *prefix);
7384b4e78eaab44693c985192276e31322155e32Stephan Boschvoid mail_index_free(struct mail_index **index);
fca68889b287d8eed4babe72a231bd6079da012dStephan Boschvoid mail_index_set_permissions(struct mail_index *index,
7384b4e78eaab44693c985192276e31322155e32Stephan Boschint mail_index_open(struct mail_index *index, enum mail_index_open_flags flags,
7384b4e78eaab44693c985192276e31322155e32Stephan Boschvoid mail_index_close(struct mail_index *index);
7384b4e78eaab44693c985192276e31322155e32Stephan Bosch/* Move the index into memory. Returns 0 if ok, -1 if error occurred. */
7384b4e78eaab44693c985192276e31322155e32Stephan Boschint mail_index_move_to_memory(struct mail_index *index);
7384b4e78eaab44693c985192276e31322155e32Stephan Boschstruct mail_cache *mail_index_get_cache(struct mail_index *index);
7384b4e78eaab44693c985192276e31322155e32Stephan Bosch/* Refresh index so mail_index_lookup*() will return latest values. Note that
7384b4e78eaab44693c985192276e31322155e32Stephan Bosch immediately after this call there may already be changes, so if you need to
6ab81c81be13f33486746deeffe02a1ef2bcc821Stephan Bosch rely on validity of the returned values, use some external locking for it. */
7384b4e78eaab44693c985192276e31322155e32Stephan Boschint mail_index_refresh(struct mail_index *index);
7384b4e78eaab44693c985192276e31322155e32Stephan Bosch/* View can be used to look into index. Sequence numbers inside view change
f9d2a1f21ad65262bc630f0834d7eead06a1bac3Timo Sirainen only when you synchronize it. The view acquires required locks
f9d2a1f21ad65262bc630f0834d7eead06a1bac3Timo Sirainen automatically, but you'll have to drop them manually. */
6ab81c81be13f33486746deeffe02a1ef2bcc821Stephan Boschstruct mail_index_view *mail_index_view_open(struct mail_index *index);
6ab81c81be13f33486746deeffe02a1ef2bcc821Stephan Boschvoid mail_index_view_close(struct mail_index_view **view);
6ab81c81be13f33486746deeffe02a1ef2bcc821Stephan Bosch/* Returns the index for given view. */
6ab81c81be13f33486746deeffe02a1ef2bcc821Stephan Boschstruct mail_index *mail_index_view_get_index(struct mail_index_view *view);
6ab81c81be13f33486746deeffe02a1ef2bcc821Stephan Bosch/* Call whenever you've done with requesting messages from view for a while. */
fca68889b287d8eed4babe72a231bd6079da012dStephan Boschvoid mail_index_view_unlock(struct mail_index_view *view);
6ab81c81be13f33486746deeffe02a1ef2bcc821Stephan Bosch/* Returns number of mails in view. */
fca68889b287d8eed4babe72a231bd6079da012dStephan Boschuint32_t mail_index_view_get_messages_count(struct mail_index_view *view);
7384b4e78eaab44693c985192276e31322155e32Stephan Bosch/* Returns TRUE if we lost track of changes for some reason. */
9dc01e0d10a61cab14867b26bf0d2d1dcf8ad978Timo Sirainenbool mail_index_view_is_inconsistent(struct mail_index_view *view);
ebe0f5e387744621b73c4db79d5891ccbe0a1321Stephan Bosch/* Transaction has to be opened to be able to modify index. You can have
7384b4e78eaab44693c985192276e31322155e32Stephan Bosch multiple transactions open simultaneously. Committed transactions won't
7384b4e78eaab44693c985192276e31322155e32Stephan Bosch show up until you've synchronized the view. Expunges won't show up until
7384b4e78eaab44693c985192276e31322155e32Stephan Bosch you've synchronized the mailbox (mail_index_sync_begin).
aacf2a69acc59e9382578d6f4e030788abc79706Timo Sirainen If transaction is marked as hidden, the changes won't be listed when the
aacf2a69acc59e9382578d6f4e030788abc79706Timo Sirainen view is synchronized. Expunges can't be hidden.
7384b4e78eaab44693c985192276e31322155e32Stephan Bosch External transactions describe changes to mailbox that have already
6ab81c81be13f33486746deeffe02a1ef2bcc821Stephan Boschmail_index_transaction_begin(struct mail_index_view *view,
6ab81c81be13f33486746deeffe02a1ef2bcc821Stephan Boschint mail_index_transaction_commit(struct mail_index_transaction **t,
415e16c3dc185578695b7d88e561a52de6c8b1b1Timo Sirainenvoid mail_index_transaction_rollback(struct mail_index_transaction **t);
415e16c3dc185578695b7d88e561a52de6c8b1b1Timo Sirainen/* Discard all changes in the transaction. */
415e16c3dc185578695b7d88e561a52de6c8b1b1Timo Sirainenvoid mail_index_transaction_reset(struct mail_index_transaction *t);
7384b4e78eaab44693c985192276e31322155e32Stephan Bosch/* Returns the view transaction was created for. */
7384b4e78eaab44693c985192276e31322155e32Stephan Boschmail_index_transaction_get_view(struct mail_index_transaction *t);
7384b4e78eaab44693c985192276e31322155e32Stephan Bosch/* Returns TRUE if the given sequence is being expunged in this transaction. */
7384b4e78eaab44693c985192276e31322155e32Stephan Boschbool mail_index_transaction_is_expunged(struct mail_index_transaction *t,
7384b4e78eaab44693c985192276e31322155e32Stephan Bosch/* Returns a view to transaction. Currently this differs from normal view only
7384b4e78eaab44693c985192276e31322155e32Stephan Bosch in that it contains newly appended messages in transaction. The view can
7384b4e78eaab44693c985192276e31322155e32Stephan Bosch still be used after transaction has been committed. */
7384b4e78eaab44693c985192276e31322155e32Stephan Boschmail_index_transaction_open_updated_view(struct mail_index_transaction *t);
7384b4e78eaab44693c985192276e31322155e32Stephan Bosch/* Begin synchronizing mailbox with index file. Returns 1 if ok, -1 if error.
7384b4e78eaab44693c985192276e31322155e32Stephan Bosch If log_file_seq is not (uint32_t)-1 and index is already synchronized up
7384b4e78eaab44693c985192276e31322155e32Stephan Bosch to the given log_file_offset, the synchronization isn't started and this
7384b4e78eaab44693c985192276e31322155e32Stephan Bosch function returns 0. This should be done when you wish to sync your committed
7384b4e78eaab44693c985192276e31322155e32Stephan Bosch transaction instead of doing a full mailbox synchronization.
fc94140acba51adafedafbc8491a3223a51db7a8Stephan Bosch mail_index_sync_next() returns all changes from previously committed
fc94140acba51adafedafbc8491a3223a51db7a8Stephan Bosch transactions which haven't yet been committed to the actual mailbox.
fc94140acba51adafedafbc8491a3223a51db7a8Stephan Bosch They're returned in ascending order and they never overlap (if we add more
636d0f43138468f8efe685a681326b123f660e49Timo Sirainen sync types, then they might). You must go through all of them and update
636d0f43138468f8efe685a681326b123f660e49Timo Sirainen the mailbox accordingly.
fca68889b287d8eed4babe72a231bd6079da012dStephan Bosch None of the changes actually show up in the index until after a successful
fca68889b287d8eed4babe72a231bd6079da012dStephan Bosch mail_index_sync_commit().
fca68889b287d8eed4babe72a231bd6079da012dStephan Bosch Returned sequence numbers describe the mailbox state at the beginning of
fca68889b287d8eed4babe72a231bd6079da012dStephan Bosch synchronization, ie. expunges don't affect them.
7384b4e78eaab44693c985192276e31322155e32Stephan Bosch Changes done to the returned transaction are expected to describe the
7384b4e78eaab44693c985192276e31322155e32Stephan Bosch mailbox's current state. */
7384b4e78eaab44693c985192276e31322155e32Stephan Boschint mail_index_sync_begin(struct mail_index *index,
7384b4e78eaab44693c985192276e31322155e32Stephan Bosch uint32_t log_file_seq, uoff_t log_file_offset,
a991cfe2157e58ee43bc580f517ce9ef0dfb7acfStephan Bosch/* Returns -1 if error, 0 if sync is finished, 1 if record was filled. */
fb1be3de0159d6a10e916ad992e2bc53be64c6d5Timo Sirainenint mail_index_sync_next(struct mail_index_sync_ctx *ctx,
7384b4e78eaab44693c985192276e31322155e32Stephan Bosch/* Returns TRUE if there's more to sync. */
7384b4e78eaab44693c985192276e31322155e32Stephan Boschbool mail_index_sync_have_more(struct mail_index_sync_ctx *ctx);
856ae2ad98cee79b2719911a3cc131d7f4ec8a90Timo Sirainen/* Reset syncing to initial state after mail_index_sync_begin(), so you can
856ae2ad98cee79b2719911a3cc131d7f4ec8a90Timo Sirainen go through all the sync records again with mail_index_sync_next(). */
1a9a35a6b307f8d5b25345af55e40a99162b4072Timo Sirainenvoid mail_index_sync_reset(struct mail_index_sync_ctx *ctx);
1a9a35a6b307f8d5b25345af55e40a99162b4072Timo Sirainen/* Commit synchronization by writing all changes to mail index file. */
1a9a35a6b307f8d5b25345af55e40a99162b4072Timo Sirainenint mail_index_sync_commit(struct mail_index_sync_ctx **ctx);
1a9a35a6b307f8d5b25345af55e40a99162b4072Timo Sirainen/* Rollback synchronization - none of the changes listed by sync_next() are
7384b4e78eaab44693c985192276e31322155e32Stephan Bosch actually written to index file. */
7384b4e78eaab44693c985192276e31322155e32Stephan Boschvoid mail_index_sync_rollback(struct mail_index_sync_ctx **ctx);
a991cfe2157e58ee43bc580f517ce9ef0dfb7acfStephan Bosch/* Mark index file corrupted. Invalidates all views. */
7384b4e78eaab44693c985192276e31322155e32Stephan Boschvoid mail_index_mark_corrupted(struct mail_index *index);
a991cfe2157e58ee43bc580f517ce9ef0dfb7acfStephan Bosch/* Check and fix any found problems. If index is broken beyond repair, it's
7384b4e78eaab44693c985192276e31322155e32Stephan Bosch marked corrupted and 0 is returned. Otherwise returns -1 if there was some
7384b4e78eaab44693c985192276e31322155e32Stephan Bosch I/O error or 1 if everything went ok. */
7384b4e78eaab44693c985192276e31322155e32Stephan Bosch/* Synchronize changes in view. You have to go through all records, or view
856ae2ad98cee79b2719911a3cc131d7f4ec8a90Timo Sirainen will be marked inconsistent. Only sync_mask type records are
856ae2ad98cee79b2719911a3cc131d7f4ec8a90Timo Sirainen synchronized. */
35f3b7e05afecacd0332c210c6e253911c2813d8Timo Sirainenint mail_index_view_sync_begin(struct mail_index_view *view,
7384b4e78eaab44693c985192276e31322155e32Stephan Bosch/* Returns -1 if error, 0 if sync is finished, 1 if record was filled. */
17cd0e0963f2fb0e66d49703e8cd0bda1b842468Timo Sirainenint mail_index_view_sync_next(struct mail_index_view_sync_ctx *ctx,
17cd0e0963f2fb0e66d49703e8cd0bda1b842468Timo Sirainenmail_index_view_sync_get_expunges(struct mail_index_view_sync_ctx *ctx,
415e16c3dc185578695b7d88e561a52de6c8b1b1Timo Sirainenvoid mail_index_view_sync_end(struct mail_index_view_sync_ctx **ctx);
ba1c847d0af4afe4787ed470d0c818e948e184e2Timo Sirainen/* Returns the index header. */
415e16c3dc185578695b7d88e561a52de6c8b1b1Timo Sirainenmail_index_get_header(struct mail_index_view *view);
415e16c3dc185578695b7d88e561a52de6c8b1b1Timo Sirainen/* Returns the given message. Returns -1 if error, 1 if ok, 0 if mail was
415e16c3dc185578695b7d88e561a52de6c8b1b1Timo Sirainen expunged but data was returned from some older index. */
5d31e4b38ef03b002e2ab245a7f8a4c0da3dd03dTimo Sirainenint mail_index_lookup(struct mail_index_view *view, uint32_t seq,
5d31e4b38ef03b002e2ab245a7f8a4c0da3dd03dTimo Sirainenint mail_index_lookup_full(struct mail_index_view *view, uint32_t seq,
c275cef636c79e1d08b3a82462c4abdca6f8cef3Martti Rannanjärvi const struct mail_index_record **rec_r);
ba1c847d0af4afe4787ed470d0c818e948e184e2Timo Sirainen/* Note that returned keyword indexes aren't sorted. */
ba1c847d0af4afe4787ed470d0c818e948e184e2Timo Sirainenint mail_index_lookup_keywords(struct mail_index_view *view, uint32_t seq,
415e16c3dc185578695b7d88e561a52de6c8b1b1Timo Sirainen/* Returns the UID for given message. May be slightly faster than
415e16c3dc185578695b7d88e561a52de6c8b1b1Timo Sirainen mail_index_lookup()->uid. */
415e16c3dc185578695b7d88e561a52de6c8b1b1Timo Sirainenint mail_index_lookup_uid(struct mail_index_view *view, uint32_t seq,
fca68889b287d8eed4babe72a231bd6079da012dStephan Bosch/* Convert UID range to sequence range. If no UIDs are found, sequences are
fca68889b287d8eed4babe72a231bd6079da012dStephan Bosch set to 0. Note that any of the returned sequences may have been expunged
fca68889b287d8eed4babe72a231bd6079da012dStephan Boschint mail_index_lookup_uid_range(struct mail_index_view *view,
fca68889b287d8eed4babe72a231bd6079da012dStephan Bosch/* Find first mail with (mail->flags & flags_mask) == flags. Useful mostly for
fca68889b287d8eed4babe72a231bd6079da012dStephan Bosch taking advantage of lowwater-fields in headers. */
fca68889b287d8eed4babe72a231bd6079da012dStephan Boschint mail_index_lookup_first(struct mail_index_view *view, enum mail_flags flags,
fca68889b287d8eed4babe72a231bd6079da012dStephan Bosch/* Append a new record to index. */
fca68889b287d8eed4babe72a231bd6079da012dStephan Boschvoid mail_index_append(struct mail_index_transaction *t, uint32_t uid,
fca68889b287d8eed4babe72a231bd6079da012dStephan Bosch/* Assigns UIDs for appended mails all at once. UID must have been given as 0
fca68889b287d8eed4babe72a231bd6079da012dStephan Bosch for mail_index_append(). Returns the next unused UID. */
fca68889b287d8eed4babe72a231bd6079da012dStephan Boschvoid mail_index_append_assign_uids(struct mail_index_transaction *t,
fca68889b287d8eed4babe72a231bd6079da012dStephan Bosch/* Expunge record from index. Note that this doesn't affect sequence numbers
fca68889b287d8eed4babe72a231bd6079da012dStephan Bosch until transaction is committed and mailbox is synced. */
fca68889b287d8eed4babe72a231bd6079da012dStephan Boschvoid mail_index_expunge(struct mail_index_transaction *t, uint32_t seq);
fca68889b287d8eed4babe72a231bd6079da012dStephan Bosch/* Update flags in index. */
fca68889b287d8eed4babe72a231bd6079da012dStephan Boschvoid mail_index_update_flags(struct mail_index_transaction *t, uint32_t seq,
fca68889b287d8eed4babe72a231bd6079da012dStephan Boschvoid mail_index_update_flags_range(struct mail_index_transaction *t,
fca68889b287d8eed4babe72a231bd6079da012dStephan Bosch/* Reset the index before committing this transaction. This is usually done
fca68889b287d8eed4babe72a231bd6079da012dStephan Bosch only when UIDVALIDITY changes. */
fca68889b287d8eed4babe72a231bd6079da012dStephan Boschvoid mail_index_reset(struct mail_index_transaction *t);
fca68889b287d8eed4babe72a231bd6079da012dStephan Bosch/* Lookup a keyword, returns TRUE if found, FALSE if not. If autocreate is
fca68889b287d8eed4babe72a231bd6079da012dStephan Bosch TRUE, the keyword is automatically created and TRUE is always returned. */
fca68889b287d8eed4babe72a231bd6079da012dStephan Boschbool mail_index_keyword_lookup(struct mail_index *index,
fca68889b287d8eed4babe72a231bd6079da012dStephan Bosch unsigned int *idx_r);
fca68889b287d8eed4babe72a231bd6079da012dStephan Bosch/* Return a pointer to array of NULL-terminated list of keywords. Note that
fca68889b287d8eed4babe72a231bd6079da012dStephan Bosch the array contents (and thus pointers inside it) may change after calling
fca68889b287d8eed4babe72a231bd6079da012dStephan Bosch mail_index_keywords_create() or mail_index_sync_begin(). */
fca68889b287d8eed4babe72a231bd6079da012dStephan Boschconst ARRAY_TYPE(keywords) *mail_index_get_keywords(struct mail_index *index);
fca68889b287d8eed4babe72a231bd6079da012dStephan Bosch/* Create a keyword list structure. It's freed automatically at the end of
struct mail_keywords *
const char *const keywords[]);
struct mail_keywords *
bool prepend);
const void **data_r);