KDE PIM / Developers / API Docs / kmail

KMFolder Class Reference

Mail folder. More...

#include <kmfolder.h>

Inherits KMFolderNode.

Inherited by KMAcctFolder.

List of all members.

Public Types

Public Slots

Signals

Public Member Functions

Static Public Member Functions

Friends


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

KMFolder::KMFolder KMFolderDir parent,
const QString &  name,
KMFolderType  aFolderType
 

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

void KMFolder::readConfig KConfig *  config  ) 
 

This is used by the storage to read the folder specific configuration.

void KMFolder::writeConfig KConfig *  config  )  const
 

This is used by the storage to save the folder specific configuration.

const FolderStorage* KMFolder::storage  )  const [inline]
 

if the folder is const, the storage should be as well

KMFolderType KMFolder::folderType  )  const
 

Returns the type of this folder.

QString KMFolder::fileName  )  const
 

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

QString KMFolder::location  )  const
 

Returns full path to folder file.

QString KMFolder::indexLocation  )  const
 

Returns full path to index file.

QString KMFolder::subdirLocation  )  const
 

Returns full path to sub directory file.

KMFolderDir* KMFolder::child  )  const [inline]
 

Returns the folder directory associated with this node or 0 if no such directory exists.

KMFolderDir * KMFolder::createChildFolder  ) 
 

Create a child folder directory and associates it with this folder.

void KMFolder::setChild KMFolderDir aChild  ) 
 

Set the folder directory associated with this node.

bool KMFolder::noContent  )  const
 

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

void KMFolder::setNoContent bool  aNoContent  ) 
 

Specify, that the folder can't contain mails.

bool KMFolder::noChildren  )  const
 

Returns, if the folder can't have children.

void KMFolder::setNoChildren bool  aNoChildren  ) 
 

Specify, that the folder can't have children.

KMMessage * KMFolder::getMsg int  idx  ) 
 

Read message at given index.

Indexing starts at zero

KMMsgInfo * KMFolder::unGetMsg int  idx  ) 
 

Replace KMMessage with KMMsgInfo and delete KMMessage.

bool KMFolder::isMessage int  idx  ) 
 

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

QCString & KMFolder::getMsgString int  idx,
QCString &  mDest
 

Read a message and return a referece to a string.

DwString KMFolder::getDwString int  idx  ) 
 

Read a message and returns a DwString.

void KMFolder::ignoreJobsForMessage KMMessage *   ) 
 

Removes and deletes all jobs associated with the particular message.

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

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

const KMMsgBase * KMFolder::getMsgBase int  idx  )  const
 

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.

const KMMsgBase * KMFolder::operator[] int  idx  )  const
 

Same as getMsgBase(int).

KMMsgBase * KMFolder::operator[] int  idx  ) 
 

Same as getMsgBase(int).

This time non-const.

KMMessage * KMFolder::take int  idx  ) 
 

Detach message from this folder.

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

int KMFolder::addMsg KMMessage *  msg,
int *  index_return = 0
 

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).

int KMFolder::addMsgKeepUID KMMessage *  msg,
int *  index_return = 0
 

(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 KMFolder::addMsg QPtrList< KMMessage > &  ,
QValueList< int > &  index_return
 

Adds the given messages to the folder.

Behaviour is identical to addMsg(msg)

void KMFolder::emitMsgAddedSignals int  idx  ) 
 

Called by derived classes implementation of addMsg.

Emits msgAdded signals

void KMFolder::removeMsg int  i,
bool  imapQuiet = FALSE
 

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

int KMFolder::expungeOldMsg int  days  ) 
 

Delete messages in the folder that are older than days.

Return the number of deleted messages.

int KMFolder::moveMsg KMMessage *  msg,
int *  index_return = 0
 

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.

int KMFolder::find const KMMsgBase *  msg  )  const
 

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

int KMFolder::count bool  cache = false  )  const
 

Number of messages in this folder.

int KMFolder::countUnread  ) 
 

Number of new or unread messages in this folder.

int KMFolder::countUnreadRecursive  ) 
 

Number of new or unread messages in this folder and all folders contained by this folder.

void KMFolder::msgStatusChanged const KMMsgStatus  oldStatus,
const KMMsgStatus  newStatus,
int  idx
 

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

int KMFolder::open  ) 
 

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).

int KMFolder::canAccess  ) 
 

Check folder for permissions Returns zero if readable and writable.

void KMFolder::close bool  force = FALSE  ) 
 

Close folder.

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

void KMFolder::sync  ) 
 

fsync buffers to disk

bool KMFolder::isOpened  )  const
 

Test if folder is opened.

void KMFolder::markNewAsUnread  ) 
 

Mark all new messages as unread.

void KMFolder::markUnreadAsRead  ) 
 

Mark all new and unread messages as read.

int KMFolder::create bool  imap = FALSE  ) 
 

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 KMFolder::remove  ) 
 

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 KMFolder::expunge  ) 
 

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

void KMFolder::compact CompactOptions  options  ) 
 

Compact this folder.

Options: CompactLater: schedule it as a background task CompactNow: do it now, and inform the user of the result (manual compaction) CompactSilentlyNow: do it now, and keep silent about it (e.g. for outbox)

int KMFolder::rename const QString &  newName,
KMFolderDir aParent = 0
 

Physically rename the folder.

Returns zero on success and an errno on failure.

bool KMFolder::autoCreateIndex  )  const
 

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

void KMFolder::setAutoCreateIndex bool   ) 
 

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

Default is TRUE.

bool KMFolder::dirty  )  const
 

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 KMFolder::setDirty bool  f  ) 
 

Change the dirty flag.

bool KMFolder::needsCompacting  )  const
 

Returns TRUE if the folder contains deleted messages.

void KMFolder::quiet bool  beQuiet  ) 
 

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.

bool KMFolder::isReadOnly  )  const
 

Is the folder read-only?

bool KMFolder::isSystemFolder  )  const [inline]
 

Returns TRUE if the folder is a kmail system folder.

These are the folders 'outbox', 'sent', 'trash'. The name of these folders is nationalized in the folder display and they cannot have accounts associated. Deletion is also forbidden. Etc.

QString KMFolder::label  )  const [virtual]
 

Returns the label of the folder for visualization.

virtual QString KMFolder::systemLabel  )  const [inline, virtual]
 

Set the label that is used as a system default.

QString KMFolder::prettyURL  )  const [virtual]
 

URL of the node for visualization purposes.

const char * KMFolder::type  )  const
 

Type of the folder.

Inherited.

bool KMFolder::hasAccounts  )  const
 

Returns TRUE if accounts are associated with this folder.

void KMFolder::setMailingListEnabled bool  enabled  ) 
 

Returns TRUE if this folder is associated with a mailing-list.

QString KMFolder::whoField  )  const [inline]
 

Get / set the name of the field that is used for the Sender/Receiver column in the headers (From/To).

QString KMFolder::userWhoField void   )  [inline]
 

Get / set the user-settings for the WhoField (From/To/Empty).

void KMFolder::correctUnreadMsgsCount  ) 
 

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

QString KMFolder::idString  )  const
 

Returns a string that can be used to identify this folder.

void KMFolder::setAutoExpire bool  enabled  ) 
 

Set whether this folder automatically expires messages.

bool KMFolder::isAutoExpire  )  const [inline]
 

Does this folder automatically expire old messages?

void KMFolder::setUnreadExpireAge int  age  ) 
 

Set the maximum age for unread messages in this folder.

Age should not be negative. Units are set using setUnreadExpireUnits().

void KMFolder::setUnreadExpireUnits ExpireUnits  units  ) 
 

Set units to use for expiry of unread messages.

Values are 1 = days, 2 = weeks, 3 = months.

void KMFolder::setReadExpireAge int  age  ) 
 

Set the maximum age for read messages in this folder.

Age should not be negative. Units are set using setReadExpireUnits().

void KMFolder::setReadExpireUnits ExpireUnits  units  ) 
 

Set units to use for expiry of read messages.

Values are 1 = days, 2 = weeks, 3 = months.

int KMFolder::getUnreadExpireAge  )  const [inline]
 

Get the age at which unread messages are expired.

Units are determined by getUnreadExpireUnits().

int KMFolder::getReadExpireAge  )  const [inline]
 

Get the age at which read messages are expired.

Units are determined by getReadExpireUnits().

ExpireUnits KMFolder::getUnreadExpireUnits  )  const [inline]
 

Units getUnreadExpireAge() is returned in.

1 = days, 2 = weeks, 3 = months.

ExpireUnits KMFolder::getReadExpireUnits  )  const [inline]
 

Units getReadExpireAge() is returned in.

1 = days, 2 = weeks, 3 = months.

ExpireAction KMFolder::expireAction  )  const [inline]
 

What should expiry do? Delete or move to another folder?

QString KMFolder::expireToFolderId  )  const [inline]
 

If expiry should move to folder, return the ID of that folder.

void KMFolder::expireOldMessages bool  immediate  ) 
 

Expire old messages in this folder.

If immediate is true, do it immediately; otherwise schedule it for later

int KMFolder::writeIndex bool  createEmptyIndex = false  ) 
 

Write index to index-file.

Returns 0 on success and errno error on failure.

void KMFolder::fillMsgDict KMMsgDict *  dict  ) 
 

Inserts messages into the message dictionary.

Might be called during kernel initialization.

int KMFolder::writeMsgDict KMMsgDict *  dict = 0  ) 
 

Writes the message serial number file.

int KMFolder::touchMsgDict  ) 
 

Touches the message serial number file.

int KMFolder::appendtoMsgDict int  idx = -1  ) 
 

Append message to end of message serial number file.

void KMFolder::setRDict KMMsgDictREntry *  rentry  ) 
 

Sets the reverse-dictionary for this folder.

KMMsgDictREntry * KMFolder::rDict  )  const
 

Returns the reverse-dictionary for this folder.

void KMFolder::setStatus int  idx,
KMMsgStatus  status,
bool  toggle = false
 

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

void KMFolder::setStatus QValueList< int > &  ids,
KMMsgStatus  status,
bool  toggle = false
 

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

bool KMFolder::useCustomIcons  )  const [inline]
 

Icon related methods.

size_t KMFolder::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.

KMFolder * KMFolder::trashFolder  )  const
 

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

Otherwise return 0.

bool KMFolder::putRepliesInSameFolder  )  const [inline]
 

Returns true if the replies to mails from this folder should be put in the same folder.

bool KMFolder::ignoreNewMail  )  const [inline]
 

Returns true if the user doesn't want to get notified about new mail in this folder.

bool KMFolder::isMoveable  )  const
 

Returns true if this folder can be moved.

void KMFolder::changed  )  [signal]
 

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

void KMFolder::cleared  )  [signal]
 

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

void KMFolder::expunged KMFolder  )  [signal]
 

Emitted after an expunge.

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

void KMFolder::iconsChanged  )  [signal]
 

Emitted when the icon paths are set.

void KMFolder::nameChanged  )  [signal]
 

Emitted when the name of the folder changes.

void KMFolder::shortcutChanged KMFolder  )  [signal]
 

Emitted when the shortcut associated with this folder changes.

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

Emitted before a message is removed from the folder.

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

Emitted after a message is removed from the folder.

void KMFolder::msgAdded int  idx  )  [signal]
 

Emitted when a message is added from the folder.

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

Emitted, when the status of a message is changed.

void KMFolder::msgHeaderChanged KMFolder ,
int 
[signal]
 

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

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

Emmited to display a message somewhere in a status line.

void KMFolder::numUnreadMsgsChanged KMFolder  )  [signal]
 

Emitted when number of unread messages has changed.

void KMFolder::removed KMFolder ,
bool 
[signal]
 

Emitted when a folder was removed.

int KMFolder::updateIndex  )  [slot]
 

Incrementally update the index if possible else call writeIndex.

void KMFolder::reallyAddMsg KMMessage *  aMsg  )  [slot]
 

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

void KMFolder::reallyAddCopyOfMsg KMMessage *  aMsg  )  [slot]
 

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


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