KDE API ReferenceKMBox Library
#include <mbox.h>
Public Types | |
| enum | LockType { ProcmailLockfile, MuttDotlock, MuttDotlockPrivileged, None } |
Public Member Functions | |
| MBox () | |
| ~MBox () | |
| MBoxEntry | appendMessage (const KMime::Message::Ptr &message) |
| MBoxEntry::List | entries (const MBoxEntry::List &deletedEntries=MBoxEntry::List()) const |
| QString | fileName () const |
| bool | isReadOnly () const |
| bool | load (const QString &fileName) |
| bool | lock () |
| bool | locked () const |
| bool | purge (const MBoxEntry::List &deletedEntries, QList< MBoxEntry::Pair > *movedEntries=0) |
| KMime::Message * | readMessage (const MBoxEntry &entry) |
| QByteArray | readMessageHeaders (const MBoxEntry &entry) |
| QByteArray | readRawMessage (const MBoxEntry &entry) |
| bool | save (const QString &fileName=QString()) |
| void | setLockFile (const QString &lockFile) |
| bool | setLockType (LockType ltype) |
| void | setReadOnly (bool ro=true) |
| void | setUnlockTimeout (int msec) |
| bool | unlock () |
Detailed Description
Member Enumeration Documentation
Constructor & Destructor Documentation
| MBox::~MBox | ( | ) |
Member Function Documentation
| MBoxEntry MBox::appendMessage | ( | const KMime::Message::Ptr & | message | ) |
Appends message to the MBox and returns the corresponding mbox entry for it.
You must load a mbox file by making a call to load( const QString& ) before appending entries. The returned mbox entry is only valid for that particular file.
- Parameters
-
message The message to append to the mbox.
- Returns
- the corresponding mbox entry for the message in the file or an invalid mbox entry if the message was not added.
| MBoxEntry::List MBox::entries | ( | const MBoxEntry::List & | deletedEntries = MBoxEntry::List() | ) | const |
Retrieve the mbox entry objects for all emails from the file except the deleteEntries.
The deletedEntries should be a list of mbox entries with offsets of deleted messages.
- Parameters
-
deletedEntries list of mbox entries that have been deleted and need not be retrieved Note: One must call load() before calling this method.
| QString MBox::fileName | ( | ) | const |
| bool MBox::isReadOnly | ( | ) | const |
Returns if the current access mode is set to readOnly.
The access mode can either be set explicitely with setReadOnly() or implicitely by calling load() on a readOnly file.
- Since
- 4.14.5
| bool MBox::load | ( | const QString & | fileName | ) |
Loads the raw mbox data from disk into the current MBox object.
Messages already present are not preserved. This method does not load the full messages into memory but only the offsets of the messages and their sizes. If the file currently is locked this method will do nothing and return false. Appended messages that are not written yet will get lost.
- Parameters
-
fileName the name of the mbox on disk.
- Returns
- true, if successful, false on error.
- See also
- save( const QString & )
| bool MBox::lock | ( | ) |
Locks the mbox file using the configured lock method.
This can be used for consecutive calls to readMessage and readMessageHeaders. Calling lock() before these calls prevents the mbox file being locked for every call.
NOTE: Even when the lock method is None the mbox is internally marked as locked. This means that it must be unlocked before calling load().
- Returns
- true if locked successful, false on error.
- See also
- setLockType( LockType ), unlock()
| bool MBox::locked | ( | ) | const |
| bool MBox::purge | ( | const MBoxEntry::List & | deletedEntries, |
| QList< MBoxEntry::Pair > * | movedEntries = 0 |
||
| ) |
Removes all messages for the given mbox entries from the current reference file (the file that is loaded with load( const QString & ).
This method will first check if all lines at the offsets are actually separator lines if this is not then no message will be deleted to prevent corruption.
- Parameters
-
deletedEntries The mbox entries of the messages that should be removed from the file. movedEntries Optional list for storing pairs of mbox entries that got moved within the file due to the deletions. The firstmember of the pair is the entry with the original offsets thesecondmember is the entry with the new (current) offset
- Returns
- true if all offsets refer to a mbox separator line and a file was loaded, false otherwise. If the latter, the physical file has not changed.
| KMime::Message * MBox::readMessage | ( | const MBoxEntry & | entry | ) |
Reads the entire message from the file for the given mbox entry.
If the mbox file is not locked this method will lock the file before reading and unlock it after reading. If the file already is locked, it will not unlock the file after reading the entry.
- Parameters
-
entry The entry in the mbox file.
- Returns
- Message for the given entry or 0 if the file could not be locked or the entry offset > fileSize.
| QByteArray MBox::readMessageHeaders | ( | const MBoxEntry & | entry | ) |
Reads the headers of the message for the given mbox entry.
If the mbox file is not locked this method will lock the file before reading and unlock it after reading. If the file already is locked, it will not unlock the file after reading the entry.
- Parameters
-
entry The entry in the mbox file.
- Returns
- QByteArray containing the raw message header data.
| QByteArray MBox::readRawMessage | ( | const MBoxEntry & | entry | ) |
Reads the entire message from the file for the given mbox entry.
If the mbox file is not locked this method will lock the file before reading and unlock it after reading. If the file already is locked, it will not unlock the file after reading the entry.
- Parameters
-
entry The entry in the mbox file.
- Returns
- QByteArray containing the raw message data.
Writes the mbox to disk.
If the fileName is empty only appended messages will be written to the file that was passed to load( const QString & ). Otherwise the contents of the file that was loaded with load is copied to fileName first.
- Parameters
-
fileName the name of the file
- Returns
- true if the save was successful; false otherwise.
- See also
- load( const QString & )
| void MBox::setLockFile | ( | const QString & | lockFile | ) |
Sets the lockfile that should be used by the procmail or the KDE lock file method.
If this method is not called and one of the before mentioned lock methods is used the name of the lock file will be equal to MBOXFILENAME.lock.
- Parameters
-
lockFile the lockfile to set
| bool MBox::setLockType | ( | LockType | ltype | ) |
Sets the locktype that should be used for locking the mbox file.
If the new LockType cannot be used (e.g. the lockfile executable could not be found) the LockType will not be changed.
- Parameters
-
ltype the locktype to set This method will not do anything if the mbox object is currently locked to make sure that it doesn't leave a locked file for one of the lockfile / mutt_dotlock methods.
| void MBox::setReadOnly | ( | bool | ro = true | ) |
Set the access mode of the mbox file to read only.
If this is set to true, the mbox file can only be read from disk. When the mbox file given in load() can not be opened in readWrite mode, but can be opened in readOnly mode, this flag is automatically set to true. You can still append messages, which are stored in memory until save() is called, but the mbox can not be saved/purged to itself. However it is possible to save it to a different file.
- Parameters
-
ro the readOnly flag to use
- See also
- save( const QString & )
- Since
- 4.14.5
| void MBox::setUnlockTimeout | ( | int | msec | ) |
By default the unlock method will directly unlock the file.
However this is expensive in case of many consecutive calls to readEntry. Setting the time out to a non zero value will keep the lock open until the timeout has passed. On each read the timer will be reset.
- Parameters
-
msec the time out to set for file lock
| bool MBox::unlock | ( | ) |
The documentation for this class was generated from the following files:
Documentation copyright © 1996-2020 The KDE developers.
Generated on Mon Jun 22 2020 13:37:15 by doxygen 1.8.7 written by Dimitri van Heesch, © 1997-2006
KDE's Doxygen guidelines are available online.
