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
Definition: acl.cpp:25
Base class for jobs that operate on mailbox metadata.
Fetches mailbox metadata.
Depth
Used to specify the depth of the metadata heirachy to walk.
The requested entries and all their direct children.
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Mon Nov 29 2021 23:00:39 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.