/* Copyright (c) 2009 Bertjan Broeksema 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 namespace KMBox { class MBoxPrivate; /** * @short A class to access mail storages in MBox format. * * @author Bertjan Broeksema * @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 only 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 must 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 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. * * @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 *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