KMBox::MBox Class Reference

#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=nullptr)
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

A class to access mail storages in MBox format.

Author

Bertjan Broeksema broek.nosp@m.sema.nosp@m.@kde..nosp@m.org

Since

4.6

Definition at line 25 of file mbox.h.

Member Enumeration Documentation

LockType

enum KMBox::MBox::LockType

Describes the type of locking that will be used.

Definition at line 31 of file mbox.h.

Constructor & Destructor Documentation

MBox()

MBox::MBox

(

)

Creates a new mbox object.

public methods.

Definition at line 27 of file mbox.cpp.

~MBox()

MBox::~MBox

(

)

Destroys the mbox object.

The file will be unlocked if it is still open.

Definition at line 38 of file mbox.cpp.

Member Function Documentation

appendMessage()

MBoxEntry MBox::appendMessage ( const KMime::Message::Ptr & message )

nodiscard

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.

Definition at line 51 of file mbox.cpp.

entries()

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

nodiscard

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.

Definition at line 106 of file mbox.cpp.

fileName()

QString MBox::fileName ( ) const

nodiscard

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

Definition at line 125 of file mbox.cpp.

isReadOnly()

bool MBox::isReadOnly ( ) const

nodiscard

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.

Since

4.14.5

Definition at line 682 of file mbox.cpp.

load()

bool MBox::load ( const QString & fileName )

nodiscard

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

Definition at line 130 of file mbox.cpp.

lock()

bool MBox::lock ( )

nodiscard

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

Definition at line 193 of file mbox.cpp.

locked()

bool MBox::locked ( ) const

nodiscard

Returns whether or not the mbox currently is locked.

Definition at line 283 of file mbox.cpp.

purge()

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

nodiscard

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

Definition at line 293 of file mbox.cpp.

readMessage()

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.

See also

lock(), unlock()

Definition at line 485 of file mbox.cpp.

readMessageHeaders()

QByteArray MBox::readMessageHeaders ( const MBoxEntry & entry )

nodiscard

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.

See also

lock(), unlock()

Definition at line 499 of file mbox.cpp.

readRawMessage()

QByteArray MBox::readRawMessage ( const MBoxEntry & entry )

nodiscard

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.

See also

lock(), unlock()

Definition at line 397 of file mbox.cpp.

save()

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

nodiscard

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

Definition at line 543 of file mbox.cpp.

setLockFile()

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

Definition at line 622 of file mbox.cpp.

setLockType()

bool MBox::setLockType ( LockType ltype )

nodiscard

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.

Definition at line 593 of file mbox.cpp.

setReadOnly()

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

Definition at line 677 of file mbox.cpp.

setUnlockTimeout()

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

Definition at line 627 of file mbox.cpp.

unlock()

bool MBox::unlock ( )

nodiscard

Unlock the mbox file.

Returns

true if the unlock was successful, false otherwise.

See also

lock()

Definition at line 632 of file mbox.cpp.

---

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

• mbox.h
• mbox.cpp