diff --git a/src/mbox.h b/src/mbox.h index fbc5093..be71be7 100644 --- a/src/mbox.h +++ b/src/mbox.h @@ -1,267 +1,267 @@ /* 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); + Q_REQUIRED_RESULT 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; + Q_REQUIRED_RESULT 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; + Q_REQUIRED_RESULT 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); + Q_REQUIRED_RESULT 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(); + Q_REQUIRED_RESULT bool lock(); /** * Returns whether or not the mbox currently is locked. */ - bool locked() const; + Q_REQUIRED_RESULT bool locked() const; /** * 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. * * @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 otherwise. If the latter, the physical file has * not changed. */ - bool purge(const MBoxEntry::List &deletedEntries, QList *movedEntries = nullptr); + Q_REQUIRED_RESULT bool purge(const MBoxEntry::List &deletedEntries, QList *movedEntries = nullptr); /** * 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); + Q_REQUIRED_RESULT 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); + Q_REQUIRED_RESULT 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()); + Q_REQUIRED_RESULT 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 object 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); + Q_REQUIRED_RESULT 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(); + Q_REQUIRED_RESULT bool unlock(); /** * 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. * @param ro the readOnly flag to use * * @see save( const QString & ) * * @since 4.14.5 */ void setReadOnly(bool ro = true); /** * Returns if the current access mode is set to readOnly. * * The access mode can either be set explicitely with setReadOnly() or * implicitely by calling load() on a readOnly file. * * @since 4.14.5 */ - bool isReadOnly() const; + Q_REQUIRED_RESULT bool isReadOnly() const; private: //@cond PRIVATE Q_DISABLE_COPY(MBox) friend class MBoxPrivate; MBoxPrivate *const d; //@endcond }; } #endif // KMBOX_MBOX_H diff --git a/src/mbox_p.h b/src/mbox_p.h index 420b5c1..885afa4 100644 --- a/src/mbox_p.h +++ b/src/mbox_p.h @@ -1,80 +1,80 @@ /* 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_P_H #define KMBOX_MBOX_P_H #include "mbox.h" #include #include #include namespace KMBox { class MBoxPrivate : public QObject { Q_OBJECT public: MBoxPrivate(MBox *mbox); ~MBoxPrivate() override; void close(); void initLoad(const QString &fileName); - bool open(); + Q_REQUIRED_RESULT bool open(); - bool startTimerIfNeeded(); + Q_REQUIRED_RESULT bool startTimerIfNeeded(); - bool isMBoxSeparator(const QByteArray &line) const; + Q_REQUIRED_RESULT bool isMBoxSeparator(const QByteArray &line) const; public Q_SLOTS: void unlockMBox(); public: QByteArray mAppendedEntries; MBoxEntry::List mEntries; quint64 mInitialMboxFileSize = 0; QString mLockFileName; MBox *mMBox = nullptr; QFile mMboxFile; QTimer mUnlockTimer; QRegExp mSeparatorMatcher; MBox::LockType mLockType; bool mFileLocked = false; bool mReadOnly = false; public: /// Static helper methods static QByteArray escapeFrom(const QByteArray &msg); /** * Generates a mbox message sperator line for given message. */ static QByteArray mboxMessageSeparator(const QByteArray &msg); /** * Unescapes the raw message read from the file. */ static void unescapeFrom(char *msg, size_t size); }; } #endif // KMBOX_MBOX_P_H diff --git a/src/mboxentry.h b/src/mboxentry.h index d516191..7d2aa87 100644 --- a/src/mboxentry.h +++ b/src/mboxentry.h @@ -1,122 +1,122 @@ /* Copyright (c) 2010 Tobias Koenig 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_MBOXENTRY_H #define KMBOX_MBOXENTRY_H #include "kmbox_export.h" #include #include #include #include namespace KMBox { class MBoxEntryPrivate; /** * @short A class that encapsulates an entry of a MBox. * * @author Tobias Koenig * @since 4.6 */ class KMBOX_EXPORT MBoxEntry { public: /** * Describes a list of mbox entry objects. */ typedef QVector List; /** * Describes a pair of mbox entry objects. */ typedef QPair Pair; /** * Creates an invalid mbox entry object. */ MBoxEntry(); /** * Creates an mbox entry object. * * @param offset The offset of the message the object references. */ explicit MBoxEntry(quint64 offset); /** * Creates an mbox entry object from an @p other object. */ MBoxEntry(const MBoxEntry &other); /** * Destroys the mbox entry object. */ ~MBoxEntry(); /** * Replaces this mbox entry object with an @p other object. */ MBoxEntry &operator=(const MBoxEntry &other); /** * Returns whether this mbox entry object is equal to an @p other. */ bool operator==(const MBoxEntry &other) const; /** * Returns whether this mbox entry object is not equal to an @p other. */ bool operator!=(const MBoxEntry &other) const; /** * Returns whether this is a valid mbox entry object. */ - bool isValid() const; + Q_REQUIRED_RESULT bool isValid() const; /** * Returns the offset of the message that is referenced by this * mbox entry object. */ - quint64 messageOffset() const; + Q_REQUIRED_RESULT quint64 messageOffset() const; /** * Returns the size of the message that is referenced by this * mbox entry object. */ - quint64 messageSize() const; + Q_REQUIRED_RESULT quint64 messageSize() const; /** * Returns the separator size of the message that is referenced by this * mbox entry object. */ - quint64 separatorSize() const; + Q_REQUIRED_RESULT quint64 separatorSize() const; private: //@cond PRIVATE friend class MBox; QSharedDataPointer d; //@endcond }; } Q_DECLARE_TYPEINFO(KMBox::MBoxEntry, Q_MOVABLE_TYPE); #endif // KMBOX_MBOXENTRY_H