KMBox::MBox

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::MessagereadMessage (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[email protected]sema[email protected]@kde.[email protected]org
Since
4.6

Definition at line 37 of file mbox.h.

Member Enumeration Documentation

Describes the type of locking that will be used.

Definition at line 43 of file mbox.h.

Constructor & Destructor Documentation

MBox::MBox ( )

Creates a new mbox object.

public methods.

Definition at line 40 of file mbox.cpp.

MBox::~MBox ( )

Destroys the mbox object.

The file will be unlocked if it is still open.

Definition at line 51 of file mbox.cpp.

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
messageThe 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 66 of file mbox.cpp.

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
deletedEntrieslist of mbox entries that have been deleted and need not be retrieved Note: One must call load() before calling this method.

Definition at line 122 of file mbox.cpp.

QString MBox::fileName ( ) const

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

Definition at line 141 of file mbox.cpp.

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.

Since
4.14.5

Definition at line 708 of file mbox.cpp.

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
fileNamethe name of the mbox on disk.
Returns
true, if successful, false on error.
See also
save( const QString & )

Definition at line 146 of file mbox.cpp.

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

Definition at line 210 of file mbox.cpp.

bool MBox::locked ( ) const

Returns whether or not the mbox currently is locked.

Definition at line 304 of file mbox.cpp.

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

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
deletedEntriesThe mbox entries of the messages that should be removed from the file.
movedEntriesOptional 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 314 of file mbox.cpp.

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
entryThe 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 509 of file mbox.cpp.

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
entryThe entry in the mbox file.
Returns
QByteArray containing the raw message header data.
See also
lock(), unlock()

Definition at line 523 of file mbox.cpp.

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
entryThe entry in the mbox file.
Returns
QByteArray containing the raw message data.
See also
lock(), unlock()

Definition at line 421 of file mbox.cpp.

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.

Parameters
fileNamethe name of the file
Returns
true if the save was successful; false otherwise.
See also
load( const QString & )

Definition at line 567 of file mbox.cpp.

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
lockFilethe lockfile to set

Definition at line 646 of file mbox.cpp.

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
ltypethe 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 617 of file mbox.cpp.

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
rothe readOnly flag to use
See also
save( const QString & )
Since
4.14.5

Definition at line 703 of file mbox.cpp.

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
msecthe time out to set for file lock

Definition at line 651 of file mbox.cpp.

bool MBox::unlock ( )

Unlock the mbox file.

Returns
true if the unlock was successful, false otherwise.
See also
lock()

Definition at line 656 of file mbox.cpp.


The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Sun May 24 2020 22:40:23 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.