1 | /* |
2 | Copyright (c) 2009 Andras Mantia <amantia@kde.org> |
3 | |
4 | This library is free software; you can redistribute it and/or modify it |
5 | under the terms of the GNU Library General Public License as published by |
6 | the Free Software Foundation; either version 2 of the License, or (at your |
7 | option) any later version. |
8 | |
9 | This library is distributed in the hope that it will be useful, but WITHOUT |
10 | ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
11 | FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public |
12 | License for more details. |
13 | |
14 | You should have received a copy of the GNU Library General Public License |
15 | along with this library; see the file COPYING.LIB. If not, write to the |
16 | Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA |
17 | 02110-1301, USA. |
18 | */ |
19 | |
20 | #ifndef KIMAP_GETMETADATAJOB_H |
21 | #define KIMAP_GETMETADATAJOB_H |
22 | |
23 | #include "kimap_export.h" |
24 | |
25 | #include "metadatajobbase.h" |
26 | |
27 | namespace KIMAP { |
28 | |
29 | class Session; |
30 | struct Message; |
31 | class GetMetaDataJobPrivate; |
32 | |
33 | /** |
34 | * Fetches mailbox metadata. |
35 | * |
36 | * Provides support for the IMAP METADATA extension; both the |
37 | * final RFC version |
38 | * (<a href="http://tools.ietf.org/html/rfc5464">RFC 5464</a>) |
39 | * and the older, incompatible draft version (known as ANNOTATEMORE) |
40 | * (<a |
41 | * href="http://tools.ietf.org/html/draft-daboo-imap-annotatemore-07" |
42 | * >draft-daboo-imap-annotatemore-07</a>). See setServerCompatibility(). |
43 | * |
44 | * This job can only be run when the session is in the |
45 | * authenticated (or selected) state. |
46 | * |
47 | * If the server supports ACLs, the user will need the |
48 | * Acl::Lookup right on the mailbox, as well as one of |
49 | * - Acl::Read |
50 | * - Acl::KeepSeen |
51 | * - Acl::Write |
52 | * - Acl::Insert |
53 | * - Acl::Post |
54 | * Otherwise, the user must be able to list the mailbox |
55 | * and either read or write the message content. |
56 | * |
57 | * Note also that on servers that implement the Annotatemore |
58 | * version of the extension, only Acl::Lookup rights are |
59 | * required (ie: the user must be able to list the mailbox). |
60 | */ |
61 | class KIMAP_EXPORT GetMetaDataJob : public MetaDataJobBase |
62 | { |
63 | Q_OBJECT |
64 | Q_DECLARE_PRIVATE( GetMetaDataJob ) |
65 | |
66 | friend class SessionPrivate; |
67 | |
68 | public: |
69 | explicit GetMetaDataJob( Session *session ); |
70 | virtual ~GetMetaDataJob(); |
71 | |
72 | /** |
73 | * Used to specify the depth of the metadata heirachy to walk. |
74 | */ |
75 | enum Depth { |
76 | NoDepth = 0, /**< Only the requested entries */ |
77 | OneLevel, /**< The requested entries and all their direct children */ |
78 | AllLevels /**< The requested entries and all their descendants */ |
79 | }; |
80 | |
81 | Q_DECLARE_FLAGS( Depths, Depth ) |
82 | |
83 | /** |
84 | * Add an entry to the query list. |
85 | * |
86 | * See SetMetaDataJob for a description of metadata entry names. |
87 | * |
88 | * When operating in Annotatemore mode, you should provide an attribute |
89 | * name. Typically this will be "value", "value.priv" or "value.shared", |
90 | * although you might want to fetch the "content-type" or |
91 | * "content-language" attributes as well. |
92 | * |
93 | * @param entry the metadata entry name |
94 | * @param attribute the attribute name, in Annotatemore mode |
95 | * |
96 | * @deprecated use addRequestedEntry(QByteArray) instead |
97 | */ |
98 | KIMAP_DEPRECATED void addEntry( const QByteArray &entry, const QByteArray &attribute = QByteArray() ); |
99 | |
100 | /** |
101 | * Add an entry to the query list. |
102 | * |
103 | * See SetMetaDataJob for a description of metadata entry names. |
104 | * |
105 | * Note that this expects METADATA style entries (with a /shared or /private prefix typically). |
106 | * In ANNOTATEMORE mode, this prefix is automatically replaced with an appropriate attribute. |
107 | * |
108 | * @param entry the metadata entry name |
109 | */ |
110 | void addRequestedEntry( const QByteArray &entry ); |
111 | |
112 | /** |
113 | * Limits the size of returned metadata entries. |
114 | * |
115 | * In order to save time or bandwidth, it is possible to prevent the |
116 | * server from returning metadata entries that are larger than a |
117 | * certain size. These entries will simply not appear in the |
118 | * list returned by allMetaData(), and will not be accessible using |
119 | * metaData(). |
120 | * |
121 | * Note that this is only used when the server capability mode is |
122 | * Metadata. |
123 | * |
124 | * The default is no limit (-1). A value of less than -1 will cause |
125 | * the job to fail. |
126 | * |
127 | * @param size the entry size limit, in octets, or -1 for no limit |
128 | */ |
129 | void setMaximumSize( qint64 size ); |
130 | |
131 | /** |
132 | * Sets whether to retrieve children or descendants of the requested entries. |
133 | * |
134 | * Metadata entry names are heirachical, much like UNIX path names. |
135 | * It therefore makes sense to ask for an entry and all its children |
136 | * (OneLevel) or an entry and all its descendants (AllLevels). |
137 | * |
138 | * For example, /shared/foo/bar/baz is a child of /shared/foo/bar and a |
139 | * descendent of /shared/foo. So if you request the entry "/shared/foo" |
140 | * with depth NoDepth, you will only get the "/shared/foo" entry. If |
141 | * you set the depth to OneLevel, you will also get "/shared/foo/bar". |
142 | * If you set the depth to AllLevels, you will also get |
143 | * "/shared/foo/bar/baz", and every other metadata entry that starts |
144 | * with "/shared/foo/". |
145 | * |
146 | * Note that this is only used when the server capability mode is |
147 | * Metadata. |
148 | * |
149 | * @param depth the depth of the metadata tree to return |
150 | */ |
151 | void setDepth( Depth depth ); |
152 | |
153 | /** |
154 | * Get a single metadata entry. |
155 | * |
156 | * The metadata must have been requested using addEntry(), and |
157 | * the job must have completed successfully, or this method |
158 | * will not return anything. |
159 | * |
160 | * Note that if setMaximumSize() was used to limit the size of |
161 | * returned metadata, this method may return an empty QByteArray |
162 | * even if the metadata entry was requested and exists on the |
163 | * server. This will happen when the metadata entry is larger |
164 | * than the size limit given to setMaximumSize(). |
165 | * |
166 | * @param mailBox the mailbox the metadata is attached to, or |
167 | * an empty string for server metadata |
168 | * @param entry the entry to get |
169 | * @param attribute (only in Annotatemore mode) the attribute to get |
170 | * @return the metadata entry value |
171 | * |
172 | * @deprecated use metaData(QByteArray entry) instead |
173 | */ |
174 | // XXX: what's with the mailBox argument in a class that has setMailBox()? |
175 | // KJobs are not intended to be run more than once |
176 | KIMAP_DEPRECATED QByteArray metaData( const QString &mailBox, const QByteArray &entry, |
177 | const QByteArray &attribute = QByteArray() ) const; |
178 | |
179 | /** |
180 | * Get a single metadata entry. |
181 | * |
182 | * The metadata must have been requested using addEntry(), and |
183 | * the job must have completed successfully, or this method |
184 | * will not return anything. |
185 | * |
186 | * Note that if setMaximumSize() was used to limit the size of |
187 | * returned metadata, this method may return an empty QByteArray |
188 | * even if the metadata entry was requested and exists on the |
189 | * server. This will happen when the metadata entry is larger |
190 | * than the size limit given to setMaximumSize(). |
191 | * |
192 | * Note that this expects METADATA style entries (with a /shared or /private prefix typically). |
193 | * In ANNOTATEMORE mode, this prefix is automatically replaced with an appropriate attribute. |
194 | * |
195 | * @param entry the entry to get |
196 | * @return the metadata entry value |
197 | */ |
198 | QByteArray metaData( const QByteArray &entry ) const; |
199 | |
200 | /** |
201 | * Get all the metadata for a given mailbox. |
202 | * |
203 | * The returned map is from metadata entry names to attributes or values. |
204 | * |
205 | * If operating in Metadata mode, the metadata value is stored against the |
206 | * empty QByteArray: |
207 | * @code |
208 | * map = job.allMetaData( "INBOX" ); |
209 | * QByteArray value = map[ "/shared/comment" ].value( QByteArray() ); |
210 | * @endcode |
211 | * |
212 | * The equivalent in Annotatemore mode would be: |
213 | * @code |
214 | * map = job.allMetaData( "INBOX" ); |
215 | * QByteArray value = map[ "/comment" ].value( "value.shared" ); |
216 | * @endcode |
217 | * |
218 | * @param mailBox a mailbox name or an empty string for server metadata |
219 | * @return a map from metadata entry names to attributes or values |
220 | */ |
221 | // XXX: what's with the mailBox argument in a class that has setMailBox()? |
222 | // KJobs are not intended to be run more than once |
223 | QMap<QByteArray, QMap<QByteArray, QByteArray> > allMetaData( const QString &mailBox ) const; |
224 | |
225 | /** |
226 | * Get all the metadata. |
227 | * |
228 | * Note that the returned map uses METADATA style entries (with a /shared or /private prefix typically), |
229 | * also in ANNOTATEMORE mode. |
230 | * |
231 | * @return a map from metadata entry names to values |
232 | */ |
233 | QMap<QByteArray, QByteArray> allMetaData() const; |
234 | |
235 | protected: |
236 | virtual void doStart(); |
237 | virtual void handleResponse( const Message &response ); |
238 | |
239 | }; |
240 | |
241 | } |
242 | |
243 | #endif |
244 | |