mail-index.h revision abbe0657a4d6271740d41cf1de55e8686f5769fc
#ifndef __MAIL_INDEX_H
#define __MAIL_INDEX_H
#include "mail-types.h"
#define MAIL_INDEX_MAJOR_VERSION 6
#define MAIL_INDEX_MINOR_VERSION 0
#define MAIL_INDEX_HEADER_MIN_SIZE 120
/* 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) */
};
enum mail_index_lock_method {
};
};
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 = unused */
/* these UIDs may not exist and may not even be unseen */
/* We have internal and external sync offsets. External changes are
synced into index somewhat more often, so int_offset <= ext_offset */
/* daily first UIDs that have been added to index. */
};
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: */
};
struct mail_index;
struct mail_index_map;
struct mail_index_view;
struct mail_index_transaction;
struct mail_index_sync_ctx;
struct mail_index_view_sync_ctx;
/* 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. */
/* Open view to latest index locked. */
struct mail_index_view **view_r);
/* 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);
/* Returns a view to transaction. Currently this differs from normal view only
in that it contains newly appended messages in transaction. The view can
still be used after transaction has been committed. */
struct mail_index_view *
/* 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 and they never overlap (if we add more
sync types, then they might). You must go through all of them and update
the mailbox accordingly.
None of the changes actually show up in index until after successful
mail_index_sync_commit().
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,
int sync_recent, int sync_dirty);
/* 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. */
/* Commit synchronization by writing all changes to mail index file. */
/* Rollback synchronization - none of the changes listed by sync_next() are
actually written to index file. */
/* 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 *
/* Returns the given message. Returns -1 if error, 1 if ok, 0 if mail was
expunged but data was returned from some older index. */
const struct mail_index_record **rec_r);
struct mail_index_map **map_r,
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. */
/* Assigns UIDs for appended mails all at once. UID must have been given as 0
for mail_index_append(). Returns the next unused UID. */
void mail_index_append_assign_uids(struct mail_index_transaction *t,
/* 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. */
/* Apply changes in MAIL_INDEX_SYNC_TYPE_FLAGS typed sync records to given
flags variables. */
/* register index extension. name is a unique identifier for the extension.
returns unique identifier for the name. */
/* Get current extension sizes. Returns 1 if ok, 0 if extension doesn't exist
in view. */
/* Resize existing extension data. If size is grown, the new data will be
zero-filled. If size is shrinked, the data is simply dropped. */
/* Reset extension records and header. Any updates for this extension which
were issued before the writer had seen this reset are discarded. reset_id is
used to figure this out, so it must be different every time. */
/* Returns extension header. */
/* Returns the wanted extension record for given message. If it doesn't exist,
*data_r is set to NULL. Return values are same as for mail_index_lookup(). */
const void **data_r);
/* Update extension header field. */
void mail_index_update_header_ext(struct mail_index_transaction *t,
/* Update extension record. If old_data_r is non-NULL and the record extension
was already updated in this transaction, it's set to contain the data it's
now overwriting. */
#endif