KMBox::MBox Class

Member Function Documentation

MBox::MBox()

Creates a new mbox object.

[noexcept] MBox::~MBox()

Destroys the mbox object.

The file will be unlocked if it is still open.

KMBox::MBoxEntry MBox::appendMessage(const std::shared_ptr<KMime::Message> &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.

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.

KMBox::MBoxEntry::List MBox::entries(const KMBox::MBoxEntry::List &deletedEntries = MBoxEntry::List()) const

Retrieve the mbox entry objects for all emails from the file except the deletedEntries.

The deletedEntries should be a list of mbox entries with offsets of deleted messages.

deletedEntries list of mbox entries that have been deleted and need not be retrieved

QString MBox::fileName() const

Returns the file name that was passed to the last call to load().

bool MBox::isReadOnly() const

Returns if the current access mode is set to readOnly.

The access mode can either be set explicitly with setReadOnly() or implicitly by calling load() on a readOnly file.

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.

fileName the name of the mbox on disk.

Returns true, if successful, false on error.

See also save().

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.

Returns true if locked successful, false on error.

See also setLockType() and unlock().

bool MBox::locked() const

Returns whether or not the mbox currently is locked.

bool MBox::purge(const KMBox::MBoxEntry::List &deletedEntries, QList<KMBox::MBoxEntry::Pair> *movedEntries = nullptr)

Removes all messages for the given mbox entries from the current reference file (the file that is loaded with load().

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.

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 first member of the pair is the entry with the original offsets the second member 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.

std::unique_ptr<KMime::Message> MBox::readMessage(const KMBox::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.

entry The entry in the mbox file.

Returns the message for the given entry or 0 if the file could not be locked or the entry offset > fileSize.

See also lock() and unlock().

QByteArray MBox::readMessageHeaders(const KMBox::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.

entry The entry in the mbox file.

Returns QByteArray containing the raw message header data.

See also lock() and unlock().

QByteArray MBox::readRawMessage(const KMBox::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.

entry The entry in the mbox file.

Returns QByteArray containing the raw message data.

See also lock() and unlock().

bool MBox::save(const QString &fileName = QString())

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.

fileName the name of the file

Returns true if the save was successful; false otherwise.

See also load().

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.

lockFile the lockfile to set

bool MBox::setLockType(KMBox::MBox::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.

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

ro the readOnly flag to use

See also isReadOnly() and save().

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.

msec the time out to set for file lock

bool MBox::unlock()

Unlock the mbox file.

Returns true if the unlock was successful, false otherwise.

See also lock().