mirror of
https://bitbucket.org/smil3y/kde-playground.git
synced 2025-02-23 18:32:51 +00:00
243 lines
8.7 KiB
C++
243 lines
8.7 KiB
C++
/*
|
|
Copyright (c) 2009 Bertjan Broeksema <broeksema@kde.org>
|
|
|
|
This library is free software; you can redistribute it and/or modify it
|
|
under the terms of the GNU Library General Public License as published by
|
|
the Free Software Foundation; either version 2 of the License, or (at your
|
|
option) any later version.
|
|
|
|
This library is distributed in the hope that it will be useful, but WITHOUT
|
|
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
|
|
FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
|
|
License for more details.
|
|
|
|
You should have received a copy of the GNU Library General Public License
|
|
along with this library; see the file COPYING.LIB. If not, write to the
|
|
Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
|
|
02110-1301, USA.
|
|
*/
|
|
|
|
#ifndef KMBOX_MBOX_H
|
|
#define KMBOX_MBOX_H
|
|
|
|
#include "kmbox_export.h"
|
|
#include "mboxentry.h"
|
|
|
|
#include <kmime/kmime_message.h>
|
|
|
|
namespace KMBox {
|
|
|
|
class MBoxPrivate;
|
|
|
|
/**
|
|
* @short A class to access mail storages in MBox format.
|
|
*
|
|
* @author Bertjan Broeksema <broeksema@kde.org>
|
|
* @since 4.6
|
|
*/
|
|
class KMBOX_EXPORT MBox
|
|
{
|
|
public:
|
|
/**
|
|
* Describes the type of locking that will be used.
|
|
*/
|
|
enum LockType {
|
|
ProcmailLockfile,
|
|
MuttDotlock,
|
|
MuttDotlockPrivileged,
|
|
None
|
|
};
|
|
|
|
/**
|
|
* Creates a new mbox object.
|
|
*/
|
|
MBox();
|
|
|
|
/**
|
|
* Destroys the mbox object.
|
|
*
|
|
* The file will be unlocked if it is still open.
|
|
*/
|
|
~MBox();
|
|
|
|
/**
|
|
* Appends @p 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 <em>only</em> valid for that particular file.
|
|
*
|
|
* @param message The message to append to the mbox.
|
|
* @return the corresponding mbox entry for the message in the file or an invalid mbox entry
|
|
* if the message was not added.
|
|
*/
|
|
MBoxEntry appendMessage( const KMime::Message::Ptr &message );
|
|
|
|
/**
|
|
* Retrieve the mbox entry objects for all emails from the file except the
|
|
* @p deleteEntries.
|
|
* The @p deletedEntries should be a list of mbox entries with offsets of deleted messages.
|
|
* @param deletedEntries list of mbox entries that have been deleted and need not be retrieved
|
|
* Note: One <em>must</em> call load() before calling this method.
|
|
*/
|
|
MBoxEntry::List entries( const MBoxEntry::List &deletedEntries = MBoxEntry::List() ) const;
|
|
|
|
/**
|
|
* Returns the file name that was passed to the last call to load().
|
|
*/
|
|
QString fileName() const;
|
|
|
|
/**
|
|
* Loads the raw mbox data from disk into the current MBox object. Messages
|
|
* already present are <em>not</em> 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.
|
|
*
|
|
* @param fileName the name of the mbox on disk.
|
|
* @return true, if successful, false on error.
|
|
*
|
|
* @see save( const QString & )
|
|
*/
|
|
bool load( const QString &fileName );
|
|
|
|
/**
|
|
* 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().
|
|
*
|
|
* @return true if locked successful, false on error.
|
|
*
|
|
* @see setLockType( LockType ), unlock()
|
|
*/
|
|
bool lock();
|
|
|
|
/**
|
|
* Returns whether or not the mbox currently is locked.
|
|
*/
|
|
bool locked() const;
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @param deletedEntries The mbox entries of the messages that should be removed from
|
|
* the file.
|
|
* @param movedEntries Optional list for storing pairs of mbox entries that got moved
|
|
* within the file due to the deletions.
|
|
* The @c first member of the pair is the entry with the original offsets
|
|
* the @c second member is the entry with the new (current) offset
|
|
*
|
|
* @return 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.
|
|
*/
|
|
bool purge( const MBoxEntry::List &deletedEntries, QList<MBoxEntry::Pair> *movedEntries = 0 );
|
|
|
|
/**
|
|
* Reads the entire message from the file for the given mbox @p 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.
|
|
*
|
|
* @param entry The entry in the mbox file.
|
|
* @return Message for the given entry or 0 if the file could not be locked
|
|
* or the entry offset > fileSize.
|
|
*
|
|
* @see lock(), unlock()
|
|
*/
|
|
KMime::Message *readMessage( const MBoxEntry &entry );
|
|
|
|
/**
|
|
* Reads the headers of the message for the given mbox @p 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.
|
|
*
|
|
* @param entry The entry in the mbox file.
|
|
* @return QByteArray containing the raw message header data.
|
|
*
|
|
* @see lock(), unlock()
|
|
*/
|
|
QByteArray readMessageHeaders( const MBoxEntry &entry );
|
|
|
|
/**
|
|
* Reads the entire message from the file for the given mbox @p 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.
|
|
*
|
|
* @param entry The entry in the mbox file.
|
|
* @return QByteArray containing the raw message data.
|
|
*
|
|
* @see lock(), unlock()
|
|
*/
|
|
QByteArray readRawMessage( const MBoxEntry &entry );
|
|
|
|
/**
|
|
* 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
|
|
* @p fileName first.
|
|
*
|
|
* @param fileName the name of the file
|
|
* @return true if the save was successful; false otherwise.
|
|
*
|
|
* @see load( const QString & )
|
|
*/
|
|
bool save( const QString &fileName = QString() );
|
|
|
|
/**
|
|
* 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.
|
|
* @param ltype the locktype to set
|
|
* 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.
|
|
*/
|
|
bool setLockType( LockType ltype );
|
|
|
|
/**
|
|
* 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.
|
|
* @param lockFile the lockfile to set
|
|
*/
|
|
void setLockFile( const QString &lockFile );
|
|
|
|
/**
|
|
* 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.
|
|
* @param msec the time out to set for file lock
|
|
*/
|
|
void setUnlockTimeout( int msec );
|
|
|
|
/**
|
|
* Unlock the mbox file.
|
|
*
|
|
* @return true if the unlock was successful, false otherwise.
|
|
*
|
|
* @see lock()
|
|
*/
|
|
bool unlock();
|
|
|
|
private:
|
|
//@cond PRIVATE
|
|
friend class MBoxPrivate;
|
|
MBoxPrivate * const d;
|
|
//@endcond
|
|
};
|
|
|
|
}
|
|
|
|
#endif // KMBOX_MBOX_H
|