KDE PIM / Developers / API Docs / kmail

FolderStorage Class Reference

Mail folder. More...

#include <folderstorage.h>

Inherits QObject.

Inherited by KMFolderIndex, and KMFolderSearch.

List of all members.

Public Types

Public Slots

Signals

Public Member Functions

Static Public Member Functions

Protected Types

Protected Slots

Protected Member Functions

Protected Attributes


Detailed Description

Mail folder.

(description will be here).


The accounts (of KMail) that are fed into the folder are represented as the children of the folder. They are only stored here during runtime to have a reference for which accounts point to a specific folder. Constructor & Destructor Documentation

FolderStorage::FolderStorage KMFolder folder,
const char *  name = 0
 

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.


Member Function Documentation

virtual KMFolderType FolderStorage::folderType  )  const [inline, virtual]
 

Returns the type of this folder.

QString FolderStorage::fileName  )  const [virtual]
 

Returns the filename of the folder (reimplemented in KMFolderImap).

QString FolderStorage::location  )  const
 

Returns full path to folder file.

virtual QString FolderStorage::indexLocation  )  const [pure virtual]
 

Returns full path to index file.

virtual bool FolderStorage::noContent  )  const [inline, virtual]
 

Returns, if the folder can't contain mails, but only subfolder.

virtual void FolderStorage::setNoContent bool  aNoContent  )  [inline, virtual]
 

Specify, that the folder can't contain mails.

virtual bool FolderStorage::noChildren  )  const [inline, virtual]
 

Returns, if the folder can't have children.

void FolderStorage::setNoChildren bool  aNoChildren  )  [virtual]
 

Specify, that the folder can't have children.

virtual ChildrenState FolderStorage::hasChildren  )  const [inline, virtual]
 

Returns if the folder has children, has no children or we don't know.

virtual void FolderStorage::setHasChildren ChildrenState  state  )  [inline, virtual]
 

Specify if the folder has children.

void FolderStorage::updateChildrenState  )  [virtual]
 

Updates the hasChildren() state.

KMMessage * FolderStorage::getMsg int  idx  )  [virtual]
 

Read message at given index.

Indexing starts at zero

KMMsgInfo * FolderStorage::unGetMsg int  idx  )  [virtual]
 

Replace KMMessage with KMMsgInfo and delete KMMessage.

bool FolderStorage::isMessage int  idx  )  [virtual]
 

Checks if the message is already "gotten" with getMsg.

KMMessage * FolderStorage::readTemporaryMsg int  idx  )  [virtual]
 

Load message from file and do NOT store it, only return it.

This is equivalent to, but faster than, getMsg+unGetMsg WARNING: the caller has to delete the returned value!

virtual QCString& FolderStorage::getMsgString int  idx,
QCString &  mDest
[pure virtual]
 

Read a message and return a referece to a string.

virtual DwString FolderStorage::getDwString int  idx  )  [pure virtual]
 

Read a message and returns a DwString.

void FolderStorage::ignoreJobsForMessage KMMessage *   )  [virtual]
 

Removes and deletes all jobs associated with the particular message.

FolderJob * FolderStorage::createJob KMMessage *  msg,
FolderJob::JobType  jt = FolderJob::tGetMessage,
KMFolder folder = 0,
QString  partSpecifier = QString::null,
const AttachmentStrategy *  as = 0
const [virtual]
 

These methods create respective FolderJob (You should derive FolderJob for each derived KMFolder).

virtual const KMMsgBase* FolderStorage::getMsgBase int  idx  )  const [pure 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.

virtual const KMMsgBase* FolderStorage::operator[] int  idx  )  const [inline, virtual]
 

Same as getMsgBase(int).

virtual KMMsgBase* FolderStorage::operator[] int  idx  )  [inline, virtual]
 

Same as getMsgBase(int).

This time non-const.

KMMessage * FolderStorage::take int  idx  )  [virtual]
 

Detach message from this folder.

Usable to call addMsg() afterwards. Loads the message if it is not loaded up to now.

virtual int FolderStorage::addMsg KMMessage *  msg,
int *  index_return = 0
[pure virtual]
 

Add the given message to the folder.

Usually the message is added at the end of the folder. Returns zero on success and an errno error code on failure. The index of the new message is stored in index_return if given. Please note that the message is added as is to the folder and the folder takes ownership of the message (deleting it in the destructor).

virtual int FolderStorage::addMsgKeepUID KMMessage *  msg,
int *  index_return = 0
[inline, virtual]
 

(Note(bo): This needs to be fixed better at a later point.

) This is overridden by dIMAP because addMsg strips the X-UID header from the mail.

int FolderStorage::addMsg QPtrList< KMMessage > &  ,
QValueList< int > &  index_return
[virtual]
 

Adds the given messages to the folder.

Behaviour is identical to addMsg(msg)

void FolderStorage::emitMsgAddedSignals int  idx  ) 
 

Called by derived classes implementation of addMsg.

Emits msgAdded signals

bool FolderStorage::canAddMsgNow KMMessage *  aMsg,
int *  aIndex_ret
[virtual]
 

Returns FALSE, if the message has to be retrieved from an IMAP account first.

In this case this function does this and cares for the rest

void FolderStorage::removeMsg int  i,
bool  imapQuiet = FALSE
[virtual]
 

Remove (first occurrence of) given message from the folder.

int FolderStorage::expungeOldMsg int  days  )  [virtual]
 

Delete messages in the folder that are older than days.

Return the number of deleted messages.

int FolderStorage::moveMsg KMMessage *  msg,
int *  index_return = 0
[virtual]
 

Detaches the given message from it's current folder and adds it to this folder.

Returns zero on success and an errno error code on failure. The index of the new message is stored in index_return if given.

virtual int FolderStorage::find const KMMsgBase *  msg  )  const [pure virtual]
 

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

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

Number of messages in this folder.

int FolderStorage::countUnread  )  [virtual]
 

Number of new or unread messages in this folder.

void FolderStorage::msgStatusChanged const KMMsgStatus  oldStatus,
const KMMsgStatus  newStatus,
int  idx
[virtual]
 

Called by KMMsgBase::setStatus when status of a message has changed required to keep the number unread messages variable current.

virtual int FolderStorage::open  )  [pure virtual]
 

Open folder for access.

Does nothing if the folder is already opened. To reopen a folder call close() first. Returns zero on success and an error code equal to the c-library fopen call otherwise (errno).

virtual int FolderStorage::canAccess  )  [pure virtual]
 

Check folder for permissions Returns zero if readable and writable.

virtual void FolderStorage::close bool  force = FALSE  )  [pure virtual]
 

Close folder.

If force is TRUE the files are closed even if others still use it (e.g. other mail reader windows).

virtual void FolderStorage::tryReleasingFolder KMFolder  )  [inline, virtual]
 

Try releasing folder if possible, something is attempting an exclusive access to it.

Currently used for KMFolderSearch and the background tasks like expiry.

virtual void FolderStorage::sync  )  [pure virtual]
 

fsync buffers to disk

bool FolderStorage::isOpened  )  const [inline]
 

Test if folder is opened.

void FolderStorage::markNewAsUnread  )  [virtual]
 

Mark all new messages as unread.

void FolderStorage::markUnreadAsRead  )  [virtual]
 

Mark all new and unread messages as read.

virtual int FolderStorage::create bool  imap = FALSE  )  [pure virtual]
 

Create a new folder with the name of this object and open it.

Returns zero on success and an error code equal to the c-library fopen call otherwise.

void FolderStorage::remove  )  [virtual]
 

Removes the folder physically from disk and empties the contents of the folder in memory.

Note that the folder is closed during this process, whether there are others using it or not.

See also:
KMFolder::removeContents

int FolderStorage::expunge  )  [virtual]
 

Delete entire folder.

Forces a close *but* opens the folder again afterwards. Returns errno(3) error code or zero on success.

See also:
KMFolder::expungeContents

virtual int FolderStorage::compact bool  silent  )  [pure virtual]
 

Remove deleted messages from the folder.

Returns zero on success and an errno on failure. A statusbar message will inform the user that the compaction worked, unless silent is set.

int FolderStorage::rename const QString &  newName,
KMFolderDir aParent = 0
[virtual]
 

Physically rename the folder.

Returns zero on success and an errno on failure.

bool FolderStorage::autoCreateIndex  )  const [inline]
 

Returns TRUE if a table of contents file is automatically created.

void FolderStorage::setAutoCreateIndex bool   )  [virtual]
 

Allow/disallow automatic creation of a table of contents file.

Default is TRUE.

bool FolderStorage::dirty  )  const [inline]
 

Returns TRUE if the table of contents is dirty.

This happens when a message is deleted from the folder. The toc will then be re-created when the folder is closed.

void FolderStorage::setDirty bool  f  ) 
 

Change the dirty flag.

bool FolderStorage::needsCompacting  )  const [inline]
 

Returns TRUE if the folder contains deleted messages.

void FolderStorage::quiet bool  beQuiet  )  [virtual]
 

If set to quiet the folder will not emit msgAdded(idx) signal.

This is necessary because adding the messages to the listview one by one as they come in ( as happens on msgAdded(idx) ) is very slow for large ( >10000 ) folders. For pop, where whole bodies are downloaded this is not an issue, but for imap, where we only download headers it becomes a bottleneck. We therefore set the folder quiet() and rebuild the listview completely once the complete folder has been checked.

virtual bool FolderStorage::isReadOnly  )  const [pure virtual]
 

Is the folder read-only?

QString FolderStorage::label  )  const
 

Returns the label of the folder for visualization.

const char * FolderStorage::type  )  const [virtual]
 

Type of the folder.

Inherited.

bool FolderStorage::hasAccounts  )  const [inline]
 

Returns TRUE if accounts are associated with this folder.

void FolderStorage::correctUnreadMsgsCount  )  [virtual]
 

A cludge to help make sure the count of unread messges is kept in sync.

virtual int FolderStorage::writeIndex bool  createEmptyIndex = false  )  [pure virtual]
 

Write index to index-file.

Returns 0 on success and errno error on failure.

void FolderStorage::fillMsgDict KMMsgDict *  dict  ) 
 

Inserts messages into the message dictionary.

Might be called during kernel initialization.

int FolderStorage::writeMsgDict KMMsgDict *  dict = 0  ) 
 

Writes the message serial number file.

int FolderStorage::touchMsgDict  ) 
 

Touches the message serial number file.

int FolderStorage::appendtoMsgDict int  idx = -1  ) 
 

Append message to end of message serial number file.

void FolderStorage::setRDict KMMsgDictREntry *  rentry  ) 
 

Sets the reverse-dictionary for this folder.

KMMsgDictREntry* FolderStorage::rDict  )  const [inline]
 

Returns the reverse-dictionary for this folder.

void FolderStorage::setStatus int  idx,
KMMsgStatus  status,
bool  toggle = false
[virtual]
 

Set the status of the message at index idx to status.

void FolderStorage::setStatus QValueList< int > &  ids,
KMMsgStatus  status,
bool  toggle = false
[virtual]
 

Set the status of the message(s) in the QValueList ids to status.

size_t FolderStorage::crlf2lf char *  str,
const size_t  strLen
[static]
 

Convert "\r\n" line endings in "\n" line endings.

The conversion happens in place. Returns the length of the resulting string.

QString FolderStorage::dotEscape const QString &   )  [static]
 

Escape a leading dot.

void FolderStorage::readConfig  )  [virtual]
 

Read the config file.

void FolderStorage::writeConfig  )  [virtual]
 

Write the config file.

virtual KMFolder* FolderStorage::trashFolder  )  const [inline, virtual]
 

If this folder has a special trash folder set, return it.

Otherwise return 0.

void FolderStorage::addJob FolderJob *   )  const
 

Add job for this folder.

This is done automatically by createJob. This method is public only for other kind of FolderJob like ExpireJob.

bool FolderStorage::compactable  )  const [inline]
 

false if index file is out of sync with mbox file

void FolderStorage::setContentsType KMail::FolderContentsType  type  )  [virtual]
 

Set the type of contents held in this folder (mail, calendar, etc.).

KMail::FolderContentsType FolderStorage::contentsType  )  const [inline]
 

Returns:
the type of contents held in this folder (mail, calendar, etc.)

void FolderStorage::search KMSearchPattern  )  [virtual]
 

Search for messages The end is signaled with searchDone().

void FolderStorage::search KMSearchPattern ,
Q_UINT32  serNum
[virtual]
 

Check if the message matches the search criteria The end is signaled with searchDone().

bool FolderStorage::isMoveable  )  const [virtual]
 

Returns true if this folder can be moved.

void FolderStorage::changed  )  [signal]
 

Emitted when the status, name, or associated accounts of this folder changed.

void FolderStorage::cleared  )  [signal]
 

Emitted when the contents of a folder have been cleared (new search in a search folder, for example).

void FolderStorage::expunged KMFolder  )  [signal]
 

Emitted after an expunge.

If not quiet, changed() will be emmitted first.

void FolderStorage::nameChanged  )  [signal]
 

Emitted when the name of the folder changes.

void FolderStorage::locationChanged const QString &  ,
const QString & 
[signal]
 

Emitted when the location on disk of the folder changes.

This is used by all code which uses the locatio on disk of the folder storage ( or the cache storage ) as an identifier for the folder.

void FolderStorage::contentsTypeChanged KMail::FolderContentsType  type  )  [signal]
 

Emitted when the contents type (calendar, mail, tasks, .

.) of the folderstorage changes.

void FolderStorage::readOnlyChanged KMFolder  )  [signal]
 

Emitted when the readonly status of the folder changes.

void FolderStorage::msgRemoved KMFolder ,
Q_UINT32  sernum
[signal]
 

Emitted before a message is removed from the folder.

void FolderStorage::msgRemoved int  idx,
QString  msgIdMD5
[signal]
 

Emitted after a message is removed from the folder.

void FolderStorage::msgAdded int  idx  )  [signal]
 

Emitted when a message is added from the folder.

void FolderStorage::msgChanged KMFolder ,
Q_UINT32  sernum,
int  delta
[signal]
 

Emitted, when the status of a message is changed.

void FolderStorage::msgHeaderChanged KMFolder ,
int 
[signal]
 

Emitted when a field of the header of a specific message changed.

void FolderStorage::statusMsg const QString &   )  [signal]
 

Emmited to display a message somewhere in a status line.

void FolderStorage::numUnreadMsgsChanged KMFolder  )  [signal]
 

Emitted when number of unread messages has changed.

void FolderStorage::removed KMFolder ,
bool 
[signal]
 

Emitted when a folder was removed.

void FolderStorage::searchResult KMFolder ,
QValueList< Q_UINT32 >  ,
KMSearchPattern ,
bool  complete
[signal]
 

Emitted when a search delivers results The matching serial numbers are included If complete is true the search is done.

void FolderStorage::searchDone KMFolder ,
Q_UINT32  ,
KMSearchPattern
[signal]
 

Emitted when a search for a single message is completed The matching serial number is included.

virtual int FolderStorage::updateIndex  )  [pure virtual, slot]
 

Incrementally update the index if possible else call writeIndex.

void FolderStorage::reallyAddMsg KMMessage *  aMsg  )  [virtual, slot]
 

Add the message to the folder after it has been retrieved from an IMAP server.

void FolderStorage::reallyAddCopyOfMsg KMMessage *  aMsg  )  [virtual, slot]
 

Add a copy of the message to the folder after it has been retrieved from an IMAP server.

void FolderStorage::slotProcessNextSearchBatch  )  [protected, slot]
 

Process the next search batch.

virtual FolderJob* FolderStorage::doCreateJob KMMessage *  msg,
FolderJob::JobType  jt,
KMFolder folder,
QString  partSpecifier,
const AttachmentStrategy *  as
const [protected, pure virtual]
 

These two methods actually create the jobs.

They have to be implemented in all folders.

See also:
createJob

void FolderStorage::headerOfMsgChanged const KMMsgBase *  ,
int  idx
[protected]
 

Tell the folder that a header field that is usually used for the index (subject, from, .

..) has changed of given message. This method is usually called from within KMMessage::setSubject/set...

virtual KMMessage* FolderStorage::readMsg int  idx  )  [protected, pure virtual]
 

Load message from file and store it at given index.

Returns 0 on failure.

virtual bool FolderStorage::readIndex  )  [protected, pure virtual]
 

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

virtual int FolderStorage::removeContents  )  [protected, pure virtual]
 

Called by KMFolder::remove() to delete the actual contents.

At the time of the call the folder has already been closed, and the various index files deleted. Returns 0 on success.

virtual int FolderStorage::expungeContents  )  [protected, pure virtual]
 

Called by KMFolder::expunge() to delete the actual contents.

At the time of the call the folder has already been closed, and the various index files deleted. Returns 0 on success.


Member Data Documentation

bool FolderStorage::mAutoCreateIndex [protected]
 

is the automatic creation of a index file allowed ?

bool FolderStorage::mDirty [protected]
 

if the index is dirty it will be recreated upon close()

bool FolderStorage::mFilesLocked [protected]
 

TRUE if the files of the folder are locked (writable).

int FolderStorage::mUnreadMsgs [protected]
 

number of unread messages, -1 if not yet set

bool FolderStorage::needsCompact [protected]
 

sven: true if on destruct folder needs to be compacted.

bool FolderStorage::mCompactable [protected]
 

false if index file is out of sync with mbox file

KMMsgDictREntry* FolderStorage::mRDict [protected]
 

Points at the reverse dictionary for this folder.

QPtrList<FolderJob> FolderStorage::mJobList [mutable, protected]
 

List of jobs created by this folder.

KMail::FolderContentsType FolderStorage::mContentsType [protected]
 

Type of contents in this folder.


The documentation for this class was generated from the following files: