KIMAP2

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

KDE's Doxygen guidelines are available online.