File indexing completed on 2024-12-22 04:57:33
0001 /* 0002 SPDX-FileCopyrightText: 2007 Till Adam <adam@kde.org> 0003 0004 SPDX-License-Identifier: LGPL-2.0-or-later 0005 */ 0006 0007 #pragma once 0008 0009 #include "maildir_export.h" 0010 0011 #include <Akonadi/Item> 0012 #include <QString> 0013 #include <QStringList> 0014 0015 class QDateTime; 0016 0017 namespace KPIM 0018 { 0019 class MAILDIR_EXPORT Maildir 0020 { 0021 public: 0022 /** 0023 Create a new Maildir object. 0024 @param path The path to the maildir, if @p isRoot is @c false, that's the path 0025 to the folder containing the cur/new/tmp folders, if @p isRoot is @c true this 0026 is the path to a folder containing a number of maildirs. 0027 @param isRoot Indicate whether this is a maildir containing mails and various 0028 sub-folders or a container only containing maildirs. 0029 */ 0030 explicit Maildir(const QString &path = QString(), bool isRoot = false); 0031 /* Copy constructor */ 0032 Maildir(const Maildir &rhs); 0033 /* Copy operator */ 0034 Maildir &operator=(const Maildir &rhs); 0035 /** Equality comparison */ 0036 bool operator==(const Maildir &rhs) const; 0037 /* Destructor */ 0038 ~Maildir(); 0039 0040 /** Returns whether the maildir has all the necessary subdirectories, 0041 * that they are readable, etc. 0042 * @param createMissingFolders if true (the default), the cur/new/tmp folders are created if they are missing 0043 */ 0044 bool isValid(bool createMissingFolders = true) const; 0045 0046 /** 0047 * Returns whether this is a normal maildir or a container containing maildirs. 0048 */ 0049 bool isRoot() const; 0050 0051 /** 0052 * Make a valid maildir at the path of this Maildir object. This involves 0053 * creating the necessary subdirs, etc. Note that an empty Maildir is 0054 * not valid, unless it is given valid path, or until create( ) is 0055 * called on it. 0056 */ 0057 bool create(); 0058 0059 /** 0060 * Returns the path of this maildir. 0061 */ 0062 QString path() const; 0063 0064 /** 0065 * Returns the name of this maildir. 0066 */ 0067 QString name() const; 0068 0069 /** 0070 * Returns the list of items (mails) in the maildir. These are keys, which 0071 * map to filenames, internally, but that's an implementation detail, which 0072 * should not be relied on. 0073 */ 0074 QStringList entryList() const; 0075 0076 /** Returns the list of items (mails) in the maildirs "new" folder. These are keys, which 0077 * map to filenames, internally, but that's an implementation detail, which 0078 * should not be relied on. 0079 */ 0080 QStringList listNew() const; 0081 0082 /** Returns the list of items (mails) in the maildirs "cur" folder. These are keys, which 0083 * map to filenames, internally, but that's an implementation detail, which 0084 * should not be relied on. 0085 */ 0086 QStringList listCurrent() const; 0087 0088 /** Return the path to the "new" directory */ 0089 QString pathToNew() const; 0090 0091 /** Return the path to the "cur" directory */ 0092 QString pathToCurrent() const; 0093 0094 /** 0095 * Returns the full path to the subdir (the NAME.directory folder ). 0096 **/ 0097 QString subDirPath() const; 0098 0099 /** 0100 * Return the full path to the file identified by key (it can be either in the "new" or "cur" folder 0101 **/ 0102 QString findRealKey(const QString &key) const; 0103 0104 /** 0105 * Returns the list of subfolders, as names (relative paths). Use the 0106 * subFolder method to get Maildir objects representing them. 0107 */ 0108 QStringList subFolderList() const; 0109 0110 /** 0111 * Adds subfolder with the given @p folderName. 0112 * @return an empty string on failure or the full path of the new subfolder 0113 * on success 0114 */ 0115 QString addSubFolder(const QString &folderName); 0116 0117 /** 0118 * Removes subfolder with the given @p folderName. Returns success or failure. 0119 */ 0120 bool removeSubFolder(const QString &folderName); 0121 0122 /** 0123 * Returns a Maildir object for the given @p folderName. If such a folder 0124 * exists, the Maildir object will be valid, otherwise you can call create() 0125 * on it, to make a subfolder with that name. 0126 */ 0127 Maildir subFolder(const QString &folderName) const; 0128 0129 /** 0130 * Returns the parent Maildir object for this Maildir, if there is one (ie. this is not the root). 0131 */ 0132 Maildir parent() const; 0133 0134 /** 0135 * Returns the size of the file in the maildir with the given @p key or \c -1 if key is not valid. 0136 * @since 4.2 0137 */ 0138 qint64 size(const QString &key) const; 0139 0140 /** 0141 * Returns the modification time of the file in the maildir with the given @p key. 0142 * @since 4.7 0143 */ 0144 QDateTime lastModified(const QString &key) const; 0145 0146 /** 0147 * Return the contents of the file in the maildir with the given @p key. 0148 */ 0149 QByteArray readEntry(const QString &key) const; 0150 0151 /** 0152 * Return the flags encoded in the maildir file name for an entry 0153 **/ 0154 Akonadi::Item::Flags readEntryFlags(const QString &key) const; 0155 0156 /** 0157 * Return the contents of the headers section of the file the maildir with the given @p file, that 0158 * is a full path to the file. You can get it by using findRealKey(key) . 0159 */ 0160 QByteArray readEntryHeadersFromFile(const QString &file) const; 0161 0162 /** 0163 * Return the contents of the headers section of the file the maildir with the given @p key. 0164 */ 0165 QByteArray readEntryHeaders(const QString &key) const; 0166 0167 /** 0168 * Write the given @p data to a file in the maildir with the given @p key. 0169 * Returns true in case of success, false in case of any error. 0170 */ 0171 bool writeEntry(const QString &key, const QByteArray &data); 0172 0173 /** 0174 * Adds the given @p data to the maildir. Returns the key of the entry. 0175 */ 0176 QString addEntry(const QByteArray &data); 0177 0178 /** 0179 * Removes the entry with the given @p key. Returns success or failure. 0180 */ 0181 bool removeEntry(const QString &key); 0182 0183 /** 0184 * Change the flags for an entry specified by @p key. Returns the new key of the entry (the key might change because 0185 * flags are stored in the unique filename). 0186 */ 0187 QString changeEntryFlags(const QString &key, const Akonadi::Item::Flags &flags); 0188 0189 /** 0190 * Moves this maildir into @p destination. 0191 */ 0192 bool moveTo(const Maildir &destination); 0193 0194 /** 0195 * Renames this maildir to @p newName. 0196 */ 0197 bool rename(const QString &newName); 0198 0199 /** 0200 * Moves the file with the given @p key into the Maildir @p destination. 0201 * @returns The new file name inside @p destination. 0202 */ 0203 QString moveEntryTo(const QString &key, const KPIM::Maildir &destination); 0204 0205 /** 0206 * Creates the maildir tree structure specific directory path that the 0207 * given @p folderPath folder would have for its sub folders 0208 * @param folderPath a maildir folder path 0209 * @return the relative subDirPath for the given @p folderPath 0210 * 0211 * @see subDirNameForFolderName() 0212 */ 0213 static QString subDirPathForFolderPath(const QString &folderPath); 0214 0215 /** 0216 * Creates the maildir tree structure specific directory name that the 0217 * given @p folderName folder would have for its sub folders 0218 * @param folderName a maildir folder name 0219 * @return the relative subDirName for the given @p folderMame 0220 * 0221 * @see subDirPathForFolderPath() 0222 */ 0223 static QString subDirNameForFolderName(const QString &folderName); 0224 0225 /** Removes the listed keys from the key cache */ 0226 void removeCachedKeys(const QStringList &keys); 0227 0228 /** Reloads the keys associated with the maildir in the key cache*/ 0229 void refreshKeyCache(); 0230 0231 /** Return the last error message string. The error might not come from the last performed operation, 0232 if that was successful. The caller should always check the return value of the methods before 0233 querying the last error string. */ 0234 QString lastError() const; 0235 0236 private: 0237 void swap(const Maildir &); 0238 class Private; 0239 Private *d; 0240 }; 0241 }