• Skip to content
  • Skip to link menu
KDE 4.7 API Reference
  • KDE API Reference
  • KDE-PIM Libraries
  • KDE Home
  • Contact Us
 

KMBox Library

  • KMBox
  • MBox
Public Types | Public Member Functions
KMBox::MBox Class Reference

#include <mbox.h>

List of all members.

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 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 setUnlockTimeout (int msec)
bool unlock ()

Detailed Description

A class to access mail storages in MBox format.

Author:
Bertjan Broeksema <broeksema@kde.org>
Since:
4.6

Member Enumeration Documentation

enum KMBox::MBox::LockType

Describes the type of locking that will be used.

Definition at line 44 of file mbox.h.


Constructor & Destructor Documentation

MBox::MBox ( )

Creates a new mbox object.

public methods.

Definition at line 42 of file mbox.cpp.

MBox::~MBox ( )

Destroys the mbox object.

The file will be unlocked if it is still open.

Definition at line 53 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 68 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.

Note: One must call load() before calling this method.

Definition at line 124 of file mbox.cpp.

QString MBox::fileName ( ) const

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

Definition at line 137 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 142 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 203 of file mbox.cpp.

bool MBox::locked ( ) const

Returns whether or not the mbox currently is locked.

Definition at line 297 of file mbox.cpp.

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 (i.e.

the file that is loaded with load( const QString & ) or the file from the last save( const QString & ) call if that was not the same file). 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 otherewhise. In the latter the physical file has not changed.

Definition at line 307 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 the file could not be locked or the entry offset > fileSize.
See also:
lock(), unlock()

Definition at line 501 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 515 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 414 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 556 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.

Definition at line 628 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.

This method will not do anything if the mbox obeject 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 599 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.

Definition at line 633 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 638 of file mbox.cpp.


The documentation for this class was generated from the following files:
  • mbox.h
  • mbox.cpp

KMBox Library

Skip menu "KMBox Library"
  • Main Page
  • Alphabetical List
  • Class List
  • Class Members
  • File List
  • Related Pages

KDE-PIM Libraries

Skip menu "KDE-PIM Libraries"
  • akonadi
  •   contact
  •   kmime
  • kabc
  • kblog
  • kcal
  • kcalcore
  • kcalutils
  • kholidays
  • kimap
  • kioslave
  •   imap4
  •   mbox
  •   nntp
  • kldap
  • kmbox
  • kmime
  • kontactinterface
  • kpimidentities
  • kpimtextedit
  •   richtextbuilders
  • kpimutils
  • kresources
  • ktnef
  • kxmlrpcclient
  • mailtransport
  • microblog
  • qgpgme
  • syndication
  •   atom
  •   rdf
  •   rss2
Generated for KDE-PIM Libraries by doxygen 1.7.5
This website is maintained by Adriaan de Groot and Allen Winter.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal