KMFolderIndex Class Reference

A FolderStorage with an index for faster access to often used message properties. More...

#include <kmfolderindex.h>

Inheritance diagram for KMFolderIndex:

Public Types
enum	IndexStatus { IndexOk, IndexMissing, IndexTooOld }
enum	OpenInternalOption { NoOptions = 0x0, CheckIfIndexTooOld = 0x1, CreateIndexFromContentsWhenReadIndexFailed = 0x2 }
Public Slots
int	updateIndex (bool aboutToClose)
virtual int	updateIndex ()
Public Member Functions
	KMFolderIndex (KMFolder folder, const char name=0)
virtual	~KMFolderIndex ()
void	addToSerialCache () const
virtual void	clearIndex (bool autoDelete=true, bool syncDict=false)
virtual int	count (bool cache=false) const
int	find (const KMMessage *msg) const
virtual int	find (const KMMsgBase *msg) const
virtual KMMsgBase *	getMsgBase (int idx)
virtual const KMMsgBase *	getMsgBase (int idx) const
int	indexSizeOfLong ()
uchar *	indexStreamBasePtr ()
size_t	indexStreamLength () const
bool	indexSwapByteOrder ()
bool	recreateIndex ()
int	serialIndexId () const
virtual KMMsgInfo *	setIndexEntry (int idx, KMMessage *msg)
virtual KMMsgBase *	takeIndexEntry (int idx)
virtual void	truncateIndex ()
virtual int	writeIndex (bool createEmptyIndex=false)
Protected Member Functions
virtual int	createIndexFromContents ()=0
int	createInternal ()
virtual void	fillMessageDict ()
virtual IndexStatus	indexStatus ()=0
int	openInternal (OpenInternalOptions options)
bool	readIndex ()
bool	readIndexHeader (int *gv=0)
bool	updateIndexStreamPtr (bool just_close=false)
int	writeMessages (KMMsgBase msg, bool flush, FILE indexStream)
int	writeMessages (KMMsgBase *msg, bool flush=true)
Protected Attributes
off_t	mHeaderOffset
int	mIndexId
int	mIndexSizeOfLong
FILE *	mIndexStream
uchar *	mIndexStreamPtr
size_t	mIndexStreamPtrLength
bool	mIndexSwapByteOrder
KMMsgList	mMsgList

Detailed Description

A FolderStorage with an index for faster access to often used message properties.

This class represents a message store which has an index for providing fast access to often used message properties, namely those displayed in the list of messages (KMHeaders).

Author:: Don Sanders <sanders@kde.org>

Definition at line 43 of file kmfolderindex.h.

Member Enumeration Documentation

enum KMFolderIndex::IndexStatus

This enum indicates the status of the index file.

It's returned by indexStatus().

Enumerator:

IndexOk
IndexMissing
IndexTooOld

Definition at line 55 of file kmfolderindex.h.

enum KMFolderIndex::OpenInternalOption

options for openInternal()

Enumerator:

NoOptions
CheckIfIndexTooOld
CreateIndexFromContentsWhenReadIndexFailed

Definition at line 116 of file kmfolderindex.h.

Constructor & Destructor Documentation

KMFolderIndex::KMFolderIndex	(	KMFolder *	folder,
		const char *	name = `0`
	)			`[explicit]`

Usually a parent is given.

But in some cases there is no fitting parent object available. Then the name of the folder is used as the absolute path to the folder file.

Definition at line 29 of file kmfolderindex.cpp.

KMFolderIndex::~KMFolderIndex ( ) [virtual]

Definition at line 42 of file kmfolderindex.cpp.

Member Function Documentation

void KMFolderIndex::addToSerialCache ( ) const

Adds all messages of this folder to the serial number cache (by calling MessageProperty::setSerialCache for each message).

This makes subsequent calls to KMMsgBase::getMsgSerNum() much faster since the serial number is already in the cache.

The folder needs to be open for this.

Definition at line 199 of file kmfolderindex_common.cpp.

void KMFolderIndex::clearIndex	(	bool	autoDelete = `true`,
		bool	syncDict = `false`
	)			`[virtual]`

Implements FolderStorage.

Definition at line 449 of file kmfolderindex.cpp.

int KMFolderIndex::count ( bool cache = false ) const [virtual]

Number of messages in this folder.

Reimplemented from FolderStorage.

Definition at line 281 of file kmfolderindex.cpp.

virtual int KMFolderIndex::createIndexFromContents ( ) [protected, pure virtual]

Create index file from messages file and fill the message-info list mMsgList.

Returns 0 on success and an errno value (see fopen) on failure.

Implemented in KMFolderCachedImap, KMFolderMaildir, and KMFolderMbox.

int KMFolderIndex::createInternal ( ) [protected]

Creates index stream (or database).

Called by KMFolderMaildir::create() and KMFolderMbox::create().

Definition at line 163 of file kmfolderindex_common.cpp.

void KMFolderIndex::fillMessageDict ( ) [protected, virtual]

Inserts messages into the message dictionary by iterating over the message list.

The messages will get new serial numbers. This is only used on newly appeared folders, where there is no .ids file yet, or when that has been invalidated.

Reimplemented from FolderStorage.

Definition at line 465 of file kmfolderindex.cpp.

int KMFolderIndex::find ( const KMMessage * msg ) const [inline]

Reimplemented from FolderStorage.

Definition at line 79 of file kmfolderindex.h.

virtual int KMFolderIndex::find ( const KMMsgBase * msg ) const [inline, virtual]

Returns the index of the given message or -1 if not found.

Implements FolderStorage.

Definition at line 75 of file kmfolderindex.h.

virtual KMMsgBase* KMFolderIndex::getMsgBase ( int idx ) [inline, virtual]

Implements FolderStorage.

Definition at line 73 of file kmfolderindex.h.

virtual const KMMsgBase* KMFolderIndex::getMsgBase ( int idx ) const [inline, virtual]

Provides access to the basic message fields that are also stored in the index.

Whenever you only need subject, from, date, status you should use this method instead of getMsg() because getMsg() will load the message if necessary and this method does not.

Implements FolderStorage.

Definition at line 72 of file kmfolderindex.h.

int KMFolderIndex::indexSizeOfLong ( ) [inline]

Definition at line 108 of file kmfolderindex.h.

KMFolderIndex::IndexStatus KMFolderIndex::indexStatus ( ) [protected, pure virtual]

Tests whether the contents of this folder is newer than the index.

Should return IndexTooOld if the index is older than the contents. Should return IndexMissing if there is contents but no index. Should return IndexOk if the folder doesn't exist anymore "physically" or if the index is not older than the contents.

Implemented in KMFolderMbox.

Definition at line 436 of file kmfolderindex.cpp.

uchar* KMFolderIndex::indexStreamBasePtr ( ) [inline]

If we have mmap(2), then we have a pointer to the mmap()ed index file; return a pointer to the memory region containing the file.

Definition at line 100 of file kmfolderindex.h.

size_t KMFolderIndex::indexStreamLength ( ) const [inline]

If we have mmap(2), then we know the size of the index file.

Return it. 0 if we don't have mmap(2).

Definition at line 105 of file kmfolderindex.h.

bool KMFolderIndex::indexSwapByteOrder ( ) [inline]

Definition at line 107 of file kmfolderindex.h.

int KMFolderIndex::openInternal ( OpenInternalOptions options ) [protected]

Opens index stream (or database) without creating it.

If checkIfIndexTooOld is true, message "The index of folder .. seems to be out of date" is displayed. Called by KMFolderMaildir::open() and KMFolderMbox::open().

Definition at line 77 of file kmfolderindex_common.cpp.

bool KMFolderIndex::readIndex ( ) [protected, virtual]

Read index file and fill the message-info list mMsgList.

Implements FolderStorage.

Definition at line 195 of file kmfolderindex.cpp.

bool KMFolderIndex::readIndexHeader ( int * gv = 0 ) [protected]

Read index header.

Called from within readIndex().

Definition at line 290 of file kmfolderindex.cpp.

bool KMFolderIndex::recreateIndex ( )

Definition at line 486 of file kmfolderindex.cpp.

int KMFolderIndex::serialIndexId ( ) const [inline]