mail-index.h revision 9e6d83a3ef6abb393eeebca423cfd0d8cb08d430
/* daily first UIDs that have been added to index. */ uint8_t flags;
/* enum mail_flags | enum mail_index_mail_flags */ /* variable sized list of keyword indexes */ /* If transaction is marked as hidden, the changes are marked with hidden=TRUE when the view is synchronized. */ /* External transactions describe changes to mailbox that have already /* Don't add flag updates unless they actually change something. This is reliable only when syncing, otherwise someone else might have already committed a transaction that had changed the flags. */ /* fsync() this transaction (unless fsyncs are disabled) */ /* Sync transaction describes changes to mailbox that already happened to another mailbox with whom we're syncing with (dsync) */ /* Resync all dirty messages' flags. */ /* Drop recent flags from all messages */ /* Create the transaction with AVOID_FLAG_UPDATES flag */ /* If there are no new transactions and nothing else to do, return 0 in mail_index_sync_begin() */ /* Create the transaction with FSYNC flag */ /* If we see "delete index" request transaction, finish it. This flag also allows committing more changes to a deleted index. */ /* Same as MAIL_INDEX_SYNC_FLAG_DELETING_INDEX, but finish index deletion only once and fail the rest (= avoid race conditions when multiple processes try to mark the index deleted) */ /* Update header's tail_offset to head_offset, even if it's the only thing we do and there's no strict need for it. */ /* Don't sync expunges */ /* Make sure view isn't inconsistent after syncing. This also means that you don't care about view_sync_next()'s output, so it won't /* MAIL_INDEX_SYNC_TYPE_FLAGS: */ /* MAIL_INDEX_SYNC_TYPE_KEYWORD_ADD, .._REMOVE: */ /* MAIL_INDEX_SYNC_TYPE_EXPUNGE: */ /* Flags or keywords changed */ /* TRUE if this was a hidden transaction. */ /* seq/offset points to end of transaction */ /* number of bytes in the written transaction. all of it was written to the same file. */ /* Specify how often to do fsyncs. If mode is FSYNC_MODE_OPTIMIZED, the mask can be used to specify which transaction types to fsync. */ /* Set locking method and maximum time to wait for a lock /* When creating a new index file or reseting an existing one, add the given extension header data immediately to it. */ /* Open index. Returns 1 if ok, 0 if index doesn't exist and CREATE flags wasn't given, -1 if error. */ /* Open or create index. Returns 0 if ok, -1 if error. */ /* unlink() all the index files. */ /* Returns TRUE if index is currently in memory. */ /* Move the index into memory. Returns 0 if ok, -1 if error occurred. */ /* Refresh index so mail_index_lookup*() will return latest values. Note that immediately after this call there may already be changes, so if you need to rely on validity of the returned values, use some external locking for it. */ /* 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. */ /* Returns the index for given view. */ /* Returns number of mails in view. */ /* Returns TRUE if we lost track of changes for some reason. */ /* Returns number of transactions open for the view. */ /* Transaction has to be opened to be able to modify index. You can have multiple transactions open simultaneously. Committed transactions won't show up until you've synchronized the view. Expunges won't show up until you've synchronized the mailbox (mail_index_sync_begin). */ /* Discard all changes in the transaction. */ /* When committing transaction, drop flag/keyword updates for messages whose mdoseq is larger than max_modseq. Save those messages' sequences to the /* Returns the resulting highest-modseq after this commit. This can be called only if transaction log is locked, which normally means only during mail index syncing. If there are any appends, they all must have been assigned UIDs before calling this. */ /* Returns the view transaction was created for. */ /* Returns TRUE if the given sequence is being expunged in this transaction. */ /* Returns a view containing the mailbox state after changes in transaction are applied. The view can still be used after transaction has been /* Begin synchronizing mailbox with index file. Returns 1 if ok, 0 if MAIL_INDEX_SYNC_FLAG_REQUIRE_CHANGES is set and there's nothing to 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 Changes done to the returned transaction are expected to describe the The returned view already contains all the changes (except expunge requests). After applying sync records on top of backend flags they should match flags in the view. If they don't, there have been external changes. Returned expunges are treated as expunge requests. They're not really removed from the index until you mark them expunged to the returned transaction. If it's not possible to expunge the message (e.g. permission denied), simply don't mark them expunged. Returned sequence numbers describe the mailbox state at the beginning of synchronization, ie. expunges don't affect them. */ /* Like mail_index_sync_begin(), but returns 1 if OK and if index is already synchronized up to the given log_file_seq+offset, the synchronization isn't started and this function returns 0. This should be done when you wish to sync your committed transaction instead of doing a full mailbox /* Returns TRUE if it currently looks like syncing would return changes. */ /* Returns TRUE if it currently looks like syncing would return expunges. */ /* Returns the log file seq+offsets for the area which this sync is handling. */ /* Returns -1 if error, 0 if sync is finished, 1 if record was filled. */ /* Returns TRUE if there's more to sync. */ /* Returns TRUE if sync has any expunges to handle. */ /* Reset syncing to initial state after mail_index_sync_begin(), so you can go through all the sync records again with mail_index_sync_next(). */ /* Update result when refreshing index at the end of sync. */ /* Don't log a warning even if syncing took over MAIL_TRANSACTION_LOG_LOCK_WARN_SECS seconds. Usually this is called because the caller itself already logged a warning about it. */ /* If a warning is logged because syncing took over MAIL_TRANSACTION_LOG_LOCK_WARN_SECS seconds, log this as the reason for the /* 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. Returns -1 if we couldn't lock for sync, 0 if everything went ok. */ /* Returns TRUE if mail_index_fsck() has been called since the last mail_index_reset_fscked() call. */ /* Synchronize changes in view. You have to go through all records, or view will be marked inconsistent. Only sync_mask type records are /* Returns the index header. */ /* Returns the wanted message record. */ /* Returns TRUE if the given message has already been expunged from index. */ /* Note that returned keyword indexes aren't sorted. */ /* Return keywords from given map. */ /* mail_index_lookup[_keywords]() returns the latest flag changes. This function instead attempts to return the flags and keywords done by the /* 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, returns FALSE and 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. */ /* Assign UIDs for mails with uid=0 or uid<first_uid. All the assigned UIDs are higher than the highest unassigned UID (i.e. it doesn't try to fill UID gaps). Assumes that mailbox is locked in a way that UIDs can be safely assigned. Returns UIDs for all asigned messages, in their sequence order (so UIDs are not necessary ascending). */ /* Expunge record from index. Note that this doesn't affect sequence numbers until transaction is committed and mailbox is synced. */ /* Like mail_index_expunge(), but also write message GUID to transaction log. */ /* Update flags in index. */ /* Specified attribute's value was changed. This is just a notification so the change gets assigned its own modseq and any log readers can find out about /* Attribute was deleted. */ /* Update message's modseq to be at least min_modseq. */ /* Update highest modseq to be at least min_modseq. */ /* Reset the index before committing this transaction. This is usually done only when UIDVALIDITY changes. */ /* Mark index deleted. No further changes will be possible after the transaction has been committed. */ /* Mark a deleted index as undeleted. Afterwards index can be changed again. */ /* Returns TRUE if index has been set deleted. This gets set only after /* Returns the last time mailbox was modified. */ /* Lookup a keyword, returns TRUE if found, FALSE if not. */ /* Return a pointer to array of NULL-terminated list of keywords. Note that the array contents (and thus pointers inside it) may change after calling mail_index_keywords_create() or mail_index_sync_begin(). */ /* Create a keyword list structure. */ /* Update keywords for given message. */ /* Update field in header. If prepend is TRUE, the header change is visible before message syncing begins. */ /* 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 /* Apply changes in MAIL_INDEX_SYNC_TYPE_KEYWORD_* typed sync records to given keywords array. Returns TRUE If something was changed. */ /* register index extension. name is a unique identifier for the extension. returns unique identifier for the name. */ /* Change an already registered extension's default sizes. */ /* Returns TRUE and sets ext_id_r if extension with given name is registered. */ /* Resize existing extension data. If size is grown, the new data will be zero-filled. If size is shrinked, the data is simply dropped. */ /* Resize header, keeping the old record size. */ /* Reset extension. 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. If clear_data=TRUE, records and /* Like mail_index_ext_reset(), but increase extension's reset_id atomically when the transaction is being committed. If prev_reset_id doesn't match the latest reset_id, the reset_id isn't increased and all extension changes are /* Discard existing extension updates in this transaction and write new updates using the given reset_id. The difference to mail_index_ext_reset() is that this doesn't clear any existing record or header data. */ /* Get the current reset_id for given extension. Returns TRUE if it exists. */ /* Returns extension header. */ /* Returns the wanted extension record for given message. If it doesn't exist, *data_r is set to NULL. expunged_r is TRUE if the message has already been expunged from the index. */ /* Get current extension sizes. Returns 1 if ok, 0 if extension doesn't exist in view. Any of the _r parameters may be NULL. */ /* Update extension header field. */ /* 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