mail-index.h revision e4b09b008ab544eb8994beecbfffefa21d855e43
#ifndef __MAIL_INDEX_H
#define __MAIL_INDEX_H
#include "mail-types.h"
#define MAIL_INDEX_MAJOR_VERSION 4
#define MAIL_INDEX_MINOR_VERSION 0
#define MAIL_INDEX_HEADER_MIN_SIZE 72
/* Number of keywords in mail_index_record. */
enum mail_index_open_flags {
/* Create index if it doesn't exist */
MAIL_INDEX_OPEN_FLAG_CREATE = 0x01,
/* Open the index as fast as possible - do only minimal checks and
MAIL_INDEX_OPEN_FLAG_FAST = 0x02,
/* Don't try to mmap() index files */
/* Don't try to write() to mmap()ed index files. Required for the few
OSes that don't have unified buffer cache
(currently OpenBSD <= 3.5) */
/* Don't use fcntl() locking */
};
};
enum mail_index_header_flag {
/* Index file is corrupted, reopen or recreate it. */
MAIL_INDEX_HDR_FLAG_CORRUPTED = 0x0001,
MAIL_INDEX_HDR_FLAG_HAVE_DIRTY = 0x0002
};
enum mail_index_mail_flags {
MAIL_INDEX_MAIL_FLAG_DIRTY = 0x80
};
enum mail_index_error {
/* No errors */
/* Internal error, see get_error_text() for more information. */
/* We ran out of available disk space. */
};
#define MAIL_INDEX_FLAGS_MASK \
typedef unsigned char keywords_mask_t[INDEX_KEYWORDS_BYTE_COUNT];
struct mail_index_header {
/* major version is increased only when you can't have backwards
compatibility. minor version is increased when header size is
increased to contain new non-critical fields. */
/* 0 = flags
1 = sizeof(uoff_t)
2 = sizeof(time_t)
3 = sizeof(keywords_mask_t) */
/* these UIDs may not exist and may not even be unseen */
};
struct mail_index_record {
};
enum mail_index_sync_type {
MAIL_INDEX_SYNC_TYPE_APPEND = 0x01,
MAIL_INDEX_SYNC_TYPE_EXPUNGE = 0x02,
MAIL_INDEX_SYNC_TYPE_FLAGS = 0x04
};
#define MAIL_INDEX_SYNC_MASK_ALL 0xff
struct mail_index_sync_rec {
enum mail_index_sync_type type;
/* MAIL_INDEX_SYNC_TYPE_FLAGS: */
/* MAIL_INDEX_SYNC_TYPE_APPEND: */
const struct mail_index_record *appends;
};
struct mail_index;
struct mail_index_view;
struct mail_index_transaction;
struct mail_index_sync_ctx;
struct mail_index_view_sync_ctx;
/* Force checking if index can be refreshed. */
/* View can be used to look into index. Sequence numbers inside view change
only when you synchronize it. The view acquires required locks
automatically, but you'll have to drop them manually. Opening view
acquires a lock immediately. */
/* Returns the index for given view. */
/* Call whenever you've done with requesting messages from view for a while. */
/* Returns number of mails in view. */
/* Returns TRUE if we lost track of changes for some reason. */
/* Transaction has to be opened to be able to modify index. You can have
multiple transactions open simultaneously. Note that committed transactions
won't show up until you've synchronized mailbox (mail_index_sync_begin). */
struct mail_index_transaction *
int mail_index_transaction_commit(struct mail_index_transaction *t,
void mail_index_transaction_rollback(struct mail_index_transaction *t);
/* Begin synchronizing mailbox with index file. This call locks the index
exclusively against other modifications. Returns 1 if ok, -1 if error.
If log_file_seq is not (uint32_t)-1 and index is already synchronized up
to given log_file_offset, the synchronization isn't started and this
function returns 0. This should be done when you wish to sync your previous
transaction instead of doing a full mailbox synchronization.
mail_index_sync_next() returns all changes from previously committed
transactions which haven't yet been committed to the actual mailbox.
They're returned in ascending order. You must go through all of them and
update the mailbox accordingly.
None of the changes actually show up in index until at
mail_index_sync_end().
Note that there may be multiple overlapping flag changes. They're returned
sorted by their beginning sequence. They never overlap expunges however.
Returned sequence numbers describe the mailbox state at the beginning of
synchronization, ie. expunges don't affect them.
You may create a new transaction for the returned view. That transaction
acts as "external mailbox changes" transaction. Any changes done there are
expected to describe mailbox's current state. */
struct mail_index_sync_ctx **ctx_r,
struct mail_index_view **view_r,
/* Returns -1 if error, 0 if sync is finished, 1 if record was filled. */
struct mail_index_sync_rec *sync_rec);
/* Returns 1 if there's more to sync, 0 if not. */
/* End synchronization by unlocking the index and closing the view. */
/* Mark index file corrupted. Invalidates all views. */
/* Check and fix any found problems. If index is broken beyond repair, it's
marked corrupted and 0 is returned. Otherwise returns -1 if there was some
I/O error or 1 if everything went ok. */
/* Synchronize changes in view. You have to go through all records, or view
will be marked inconsistent. Only sync_mask type records are
synchronized. */
struct mail_index_view_sync_ctx **ctx_r);
/* Returns -1 if error, 0 if sync is finished, 1 if record was filled. */
struct mail_index_sync_rec *sync_rec);
const uint32_t *
/* Returns the index header. */
const struct mail_index_header **hdr_r);
/* Returns the given message. */
const struct mail_index_record **rec_r);
/* Returns the UID for given message. May be slightly faster than
mail_index_lookup()->uid */
/* Convert UID range to sequence range. If no UIDs are found, sequences are
set to 0. Note that any of the returned sequences may have been expunged
already. */
/* Find first mail with (mail->flags & flags_mask) == flags. Useful mostly for
taking advantage of lowwater-fields in headers. */
/* Append a new record to index. */
/* Expunge record from index. Note that this doesn't affect sequence numbers
until transaction is committed and mailbox is synced. */
/* Update flags in index. */
enum modify_type modify_type,
/* Update field in header. */
void mail_index_update_header(struct mail_index_transaction *t,
/* Returns the last error code. */
/* Returns the full error message for last error. This message may
contain paths etc. so it shouldn't be shown to users. */
/* Reset the error message. */
/* Returns TRUE if index is currently only in memory. */
/* Apply changes in MAIL_INDEX_SYNC_TYPE_FLAGS typed sync records to given
flags variables. */
#endif