File indexing completed on 2024-05-12 05:17:22
0001 /* 0002 Copyright (c) 2009 Andras Mantia <amantia@kde.org> 0003 0004 This library is free software; you can redistribute it and/or modify it 0005 under the terms of the GNU Library General Public License as published by 0006 the Free Software Foundation; either version 2 of the License, or (at your 0007 option) any later version. 0008 0009 This library is distributed in the hope that it will be useful, but WITHOUT 0010 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0011 FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public 0012 License for more details. 0013 0014 You should have received a copy of the GNU Library General Public License 0015 along with this library; see the file COPYING.LIB. If not, write to the 0016 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 0017 02110-1301, USA. 0018 */ 0019 0020 #ifndef KIMAP2_GETMETADATAJOB_H 0021 #define KIMAP2_GETMETADATAJOB_H 0022 0023 #include "kimap2_export.h" 0024 0025 #include "metadatajobbase.h" 0026 0027 namespace KIMAP2 0028 { 0029 0030 class Session; 0031 struct Message; 0032 class GetMetaDataJobPrivate; 0033 0034 /** 0035 * Fetches mailbox metadata. 0036 * 0037 * Provides support for the IMAP METADATA extension; both the 0038 * final RFC version 0039 * (<a href="http://tools.ietf.org/html/rfc5464">RFC 5464</a>) 0040 * and the older, incompatible draft version (known as ANNOTATEMORE) 0041 * (<a 0042 * href="http://tools.ietf.org/html/draft-daboo-imap-annotatemore-07" 0043 * >draft-daboo-imap-annotatemore-07</a>). See setServerCompatibility(). 0044 * 0045 * This job can only be run when the session is in the 0046 * authenticated (or selected) state. 0047 * 0048 * If the server supports ACLs, the user will need the 0049 * Acl::Lookup right on the mailbox, as well as one of 0050 * - Acl::Read 0051 * - Acl::KeepSeen 0052 * - Acl::Write 0053 * - Acl::Insert 0054 * - Acl::Post 0055 * Otherwise, the user must be able to list the mailbox 0056 * and either read or write the message content. 0057 * 0058 * Note also that on servers that implement the Annotatemore 0059 * version of the extension, only Acl::Lookup rights are 0060 * required (ie: the user must be able to list the mailbox). 0061 */ 0062 class KIMAP2_EXPORT GetMetaDataJob : public MetaDataJobBase 0063 { 0064 Q_OBJECT 0065 Q_DECLARE_PRIVATE(GetMetaDataJob) 0066 0067 friend class SessionPrivate; 0068 0069 public: 0070 explicit GetMetaDataJob(Session *session); 0071 virtual ~GetMetaDataJob(); 0072 0073 /** 0074 * Used to specify the depth of the metadata heirachy to walk. 0075 */ 0076 enum Depth { 0077 NoDepth = 0, /**< Only the requested entries */ 0078 OneLevel, /**< The requested entries and all their direct children */ 0079 AllLevels /**< The requested entries and all their descendants */ 0080 }; 0081 0082 Q_DECLARE_FLAGS(Depths, Depth) 0083 0084 /** 0085 * Add an entry to the query list. 0086 * 0087 * See SetMetaDataJob for a description of metadata entry names. 0088 * 0089 * When operating in Annotatemore mode, you should provide an attribute 0090 * name. Typically this will be "value", "value.priv" or "value.shared", 0091 * although you might want to fetch the "content-type" or 0092 * "content-language" attributes as well. 0093 * 0094 * @param entry the metadata entry name 0095 * @param attribute the attribute name, in Annotatemore mode 0096 * 0097 * @deprecated use addRequestedEntry(QByteArray) instead 0098 */ 0099 KIMAP2_DEPRECATED void addEntry(const QByteArray &entry, const QByteArray &attribute = QByteArray()); 0100 0101 /** 0102 * Add an entry to the query list. 0103 * 0104 * See SetMetaDataJob for a description of metadata entry names. 0105 * 0106 * Note that this expects METADATA style entries (with a /shared or /private prefix typically). 0107 * In ANNOTATEMORE mode, this prefix is automatically replaced with an appropriate attribute. 0108 * 0109 * @param entry the metadata entry name 0110 */ 0111 void addRequestedEntry(const QByteArray &entry); 0112 0113 /** 0114 * Limits the size of returned metadata entries. 0115 * 0116 * In order to save time or bandwidth, it is possible to prevent the 0117 * server from returning metadata entries that are larger than a 0118 * certain size. These entries will simply not appear in the 0119 * list returned by allMetaData(), and will not be accessible using 0120 * metaData(). 0121 * 0122 * Note that this is only used when the server capability mode is 0123 * Metadata. 0124 * 0125 * The default is no limit (-1). A value of less than -1 will cause 0126 * the job to fail. 0127 * 0128 * @param size the entry size limit, in octets, or -1 for no limit 0129 */ 0130 void setMaximumSize(qint64 size); 0131 0132 /** 0133 * Sets whether to retrieve children or descendants of the requested entries. 0134 * 0135 * Metadata entry names are heirachical, much like UNIX path names. 0136 * It therefore makes sense to ask for an entry and all its children 0137 * (OneLevel) or an entry and all its descendants (AllLevels). 0138 * 0139 * For example, /shared/foo/bar/baz is a child of /shared/foo/bar and a 0140 * descendent of /shared/foo. So if you request the entry "/shared/foo" 0141 * with depth NoDepth, you will only get the "/shared/foo" entry. If 0142 * you set the depth to OneLevel, you will also get "/shared/foo/bar". 0143 * If you set the depth to AllLevels, you will also get 0144 * "/shared/foo/bar/baz", and every other metadata entry that starts 0145 * with "/shared/foo/". 0146 * 0147 * Note that this is only used when the server capability mode is 0148 * Metadata. 0149 * 0150 * @param depth the depth of the metadata tree to return 0151 */ 0152 void setDepth(Depth depth); 0153 0154 /** 0155 * Get a single metadata entry. 0156 * 0157 * The metadata must have been requested using addEntry(), and 0158 * the job must have completed successfully, or this method 0159 * will not return anything. 0160 * 0161 * Note that if setMaximumSize() was used to limit the size of 0162 * returned metadata, this method may return an empty QByteArray 0163 * even if the metadata entry was requested and exists on the 0164 * server. This will happen when the metadata entry is larger 0165 * than the size limit given to setMaximumSize(). 0166 * 0167 * @param mailBox the mailbox the metadata is attached to, or 0168 * an empty string for server metadata 0169 * @param entry the entry to get 0170 * @param attribute (only in Annotatemore mode) the attribute to get 0171 * @return the metadata entry value 0172 * 0173 * @deprecated use metaData(QByteArray entry) instead 0174 */ 0175 // XXX: what's with the mailBox argument in a class that has setMailBox()? 0176 // KJobs are not intended to be run more than once 0177 KIMAP2_DEPRECATED QByteArray metaData(const QString &mailBox, const QByteArray &entry, 0178 const QByteArray &attribute = QByteArray()) const; 0179 0180 /** 0181 * Get a single metadata entry. 0182 * 0183 * The metadata must have been requested using addEntry(), and 0184 * the job must have completed successfully, or this method 0185 * will not return anything. 0186 * 0187 * Note that if setMaximumSize() was used to limit the size of 0188 * returned metadata, this method may return an empty QByteArray 0189 * even if the metadata entry was requested and exists on the 0190 * server. This will happen when the metadata entry is larger 0191 * than the size limit given to setMaximumSize(). 0192 * 0193 * Note that this expects METADATA style entries (with a /shared or /private prefix typically). 0194 * In ANNOTATEMORE mode, this prefix is automatically replaced with an appropriate attribute. 0195 * 0196 * @param entry the entry to get 0197 * @return the metadata entry value 0198 */ 0199 QByteArray metaData(const QByteArray &entry) const; 0200 0201 /** 0202 * Get all the metadata for a given mailbox. 0203 * 0204 * The returned map is from metadata entry names to attributes or values. 0205 * 0206 * If operating in Metadata mode, the metadata value is stored against the 0207 * empty QByteArray: 0208 * @code 0209 * map = job.allMetaData( "INBOX" ); 0210 * QByteArray value = map[ "/shared/comment" ].value( QByteArray() ); 0211 * @endcode 0212 * 0213 * The equivalent in Annotatemore mode would be: 0214 * @code 0215 * map = job.allMetaData( "INBOX" ); 0216 * QByteArray value = map[ "/comment" ].value( "value.shared" ); 0217 * @endcode 0218 * 0219 * @param mailBox a mailbox name or an empty string for server metadata 0220 * @return a map from metadata entry names to attributes or values 0221 */ 0222 // XXX: what's with the mailBox argument in a class that has setMailBox()? 0223 // KJobs are not intended to be run more than once 0224 QMap<QByteArray, QMap<QByteArray, QByteArray> > allMetaData(const QString &mailBox) const; 0225 0226 /** 0227 * Get all the metadata for the mailbox set with setMailBox(). 0228 * 0229 * Note that the returned map uses METADATA style entries (with a /shared or /private prefix typically), 0230 * also in ANNOTATEMORE mode. 0231 * 0232 * @return a map from metadata entry names to values 0233 */ 0234 QMap<QByteArray, QByteArray> allMetaData() const; 0235 0236 /** 0237 * Get all the metadata for the mailbox. 0238 * 0239 * Note that the returned map uses METADATA style entries (with a /shared or /private prefix typically), 0240 * also in ANNOTATEMORE mode. 0241 * 0242 * @return a map from metadata entry names to values 0243 */ 0244 QMap<QByteArray, QByteArray> allMetaDataForMailbox(const QString &mailbox) const; 0245 0246 /** 0247 * Get all the metadata for for all mailboxes. 0248 * 0249 * Note that the returned map uses METADATA style entries (with a /shared or /private prefix typically), 0250 * also in ANNOTATEMORE mode. 0251 * 0252 * @return a map in the form (mailbox, (entry, value)) 0253 */ 0254 QHash<QString, QMap<QByteArray, QByteArray> > allMetaDataForMailboxes() const; 0255 0256 protected: 0257 void doStart() Q_DECL_OVERRIDE; 0258 void handleResponse(const Message &response) Q_DECL_OVERRIDE; 0259 0260 }; 0261 0262 } 0263 0264 #endif