KIMAP

fetchjob.h
1 /*
2  SPDX-FileCopyrightText: 2009 Kevin Ottens <[email protected]>
3 
4  SPDX-License-Identifier: LGPL-2.0-or-later
5 */
6 
7 #pragma once
8 
9 #include "kimap_export.h"
10 
11 #include "imapset.h"
12 #include "job.h"
13 
14 #include <KMime/Content>
15 #include <KMime/KMimeMessage>
16 
17 #include <tuple>
18 
19 namespace KIMAP
20 {
21 class Session;
22 struct Response;
23 class FetchJobPrivate;
24 
25 using ContentPtr = QSharedPointer<KMime::Content>;
26 using MessageParts = QMap<QByteArray, ContentPtr>;
27 
28 using MessagePtr = QSharedPointer<KMime::Message>;
29 using MessageFlags = QList<QByteArray>;
30 
31 using MessageAttribute = QPair<QByteArray, QVariant>;
32 
33 struct Message {
34  inline bool operator==(const Message &other) const
35  {
36  return std::tie(uid, size, flags, attributes, parts, message)
37  == std::tie(other.uid, other.size, other.flags, other.attributes, other.parts, other.message);
38  }
39 
40  qint64 uid = -1;
41  qint64 size = 0;
42  MessageFlags flags;
43  QMap<QByteArray, QVariant> attributes;
44  MessageParts parts;
45  MessagePtr message;
46 };
47 
48 /**
49  * Fetch message data from the server
50  *
51  * All data is returned using the signals, so you need to connect to
52  * the relevant signal (or all of them) before starting the job.
53  *
54  * This job will always use BODY.PEEK rather than BODY to fetch message
55  * content, so it will not set the \Seen flag.
56  *
57  * This job can only be run when the session is in the selected state.
58  */
59 class KIMAP_EXPORT FetchJob : public Job
60 {
61  Q_OBJECT
62  Q_DECLARE_PRIVATE(FetchJob)
63 
64  friend class SessionPrivate;
65 
66 public:
67  /**
68  * Used to indicate what message data should be fetched.
69  *
70  * This doesn't provide the same fine-grained control over
71  * what is fetched that the IMAP FETCH command normally
72  * does, but the common cases are catered for.
73  */
74  class KIMAP_EXPORT FetchScope
75  {
76  public:
77  FetchScope();
78 
79  /**
80  * Used to indicate what part of the message should be fetched.
81  */
82  enum Mode {
83  /**
84  * Fetch RFC-2822 or MIME message headers.
85  *
86  * To fetch MIME headers for a MIME part, populate the @p parts field.
87  *
88  * If the RFC-2822 headers are requested (so @p parts is empty), the
89  * returned information is:
90  * - To, From, Message-id, References In-Reply-To, Subject and Date headers
91  * - The message size (in octets)
92  * - The internal date of the message
93  * - The message flags
94  * - The message UID
95  */
97  /**
98  * Fetch the message flags (the UID is also fetched)
99  */
101  /**
102  * Fetch the MIME message body structure (the UID is also fetched)
103  */
105  /**
106  * Fetch the message content (the UID is also fetched)
107  *
108  * To fetch only certain MIME parts (see Structure), populate the
109  * @p parts field.
110  */
112  /**
113  * Fetch the complete message.
114  */
116  /**
117  * Fetch the message MIME headers and the content of parts specified in the @p parts
118  * field.
119  *
120  * If @p parts is empty, this mode will return the full message, just like
121  * FetchScope::Content
122  *
123  * Use case:
124  * -# Start a FetchJob with the FetchScope::Structure mode to retrieve the structure
125  * of the message.
126  * -# Parse the structure to identify the parts that are interesting (ie: probably
127  * everything but attachments).
128  * -# Start another FetchJob with FetchScope::HeaderAndContent to fetch those parts.
129  * -# At the request of the user, you can repeat the step above to fetch the attachments.
130  *
131  * @since 4.7
132  */
134 
135  /**
136  * Fetch message size (in octets), internal date of the message, flags, UID
137  * and all RFC822 headers.
138  *
139  * The @p parts field is ignored when using this scope
140  *
141  * @since 4.12
142  */
143  FullHeaders
144  };
145 
146  /**
147  * Specify which message parts to operate on.
148  *
149  * This refers to multipart-MIME message parts or MIME-IMB encapsulated
150  * message parts.
151  *
152  * Note that this is ignored unless @p mode is Headers or Content.
153  *
154  * If @p mode is Headers, this sets the parts to get the MIME headers
155  * for. If this list is empty, the headers for the whole message
156  * (the RFC-2822 headers) are fetched.
157  *
158  * If @p mode is Content, this sets the parts to fetch. Parts are
159  * fetched wholesale. If this list is empty, the whole message body
160  * is fetched (all MIME parts together).
161  */
163  /**
164  * Specify what message data should be fetched.
165  */
166  Mode mode = Content;
167 
168  /**
169  * Specify to fetch only items with mod-sequence higher then @p changedSince.
170  *
171  * The server must have CONDSTORE capability (RFC4551).
172  *
173  * Default value is 0 (ignored).
174  *
175  * @since 4.12
176  */
177  quint64 changedSince = 0;
178 
179  /**
180  * Specify whether QRESYNC is supported and should be used.
181  *
182  * When enabled, the @p changedSince parameter must be specified as
183  * well. The server will then also return list of messages that have
184  * been deleted from the mailbox since the specified modification sequence.
185  *
186  * The server must have QRESYNC capability (RFC5162) and it must have
187  * explicitly been enabled via ENABLE command (see @EnableJob).
188  *
189  * QRESYNC can only be used in UID FETCH (@see setUidBased())
190  *
191  * @since 5.16
192  */
193  bool qresync = false;
194  };
195 
196  explicit FetchJob(Session *session);
197  ~FetchJob() override = default;
198 
199  /**
200  * Set which messages to fetch data for.
201  *
202  * If sequence numbers are given, isUidBased() should be false. If UIDs
203  * are given, isUidBased() should be true.
204  *
205  * @param set the sequence numbers or UIDs of the messages to fetch data for
206  */
207  void setSequenceSet(const ImapSet &set);
208  /**
209  * The messages that will be fetched.
210  */
211  ImapSet sequenceSet() const;
212 
213  /**
214  * Set how the sequence set should be interpreted.
215  *
216  * @param uidBased if @c true the argument to setSequenceSet will be
217  * interpreted as UIDs, if @c false it will be interpreted
218  * as sequence numbers
219  */
220  void setUidBased(bool uidBased);
221  /**
222  * How to interpret the sequence set.
223  *
224  * @return if @c true the result of sequenceSet() should be
225  * interpreted as UIDs, if @c false it should be interpreted
226  * as sequence numbers
227  */
228  [[nodiscard]] bool isUidBased() const;
229 
230  /**
231  * Sets what data should be fetched.
232  *
233  * The default scope is FetchScope::Content (all content parts).
234  *
235  * @param scope a FetchScope object describing what data
236  * should be fetched
237  */
238  void setScope(const FetchScope &scope);
239  /**
240  * Specifies what data will be fetched.
241  */
242  [[nodiscard]] FetchScope scope() const;
243 
244  // TODO: KF6: Move this to FetchScope
245  /**
246  * Enables retrieving of Gmail-specific extensions
247  *
248  * The FETCH response will contain X-GM-MSGID, X-GM-THRID and X-GM-LABELS
249  *
250  * Do NOT enable this, unless talking to Gmail servers, otherwise the
251  * request may fail.
252  *
253  * @param enabled Whether the Gmail support should be enabled
254  * @since 4.14
255  */
256  void setGmailExtensionsEnabled(bool enabled);
257 
258  /**
259  * Returns whether Gmail support is enabled
260  *
261  * @since 4.14
262  * @see setGmailExtensionsEnabled()
263  */
264  bool setGmailExtensionsEnabled() const;
265 
266  /**
267  * Returns the name of the mailbox the fetch job is executed on.
268  *
269  * Can only be accessed after the job is actually started, before that
270  * returns an empty string.
271  *
272  * @since 5.6
273  */
274  [[nodiscard]] QString mailBox() const;
275 
276 Q_SIGNALS:
277  /**
278  * Provides header and message results.
279  *
280  * This signal will be emitted if the requested scope mode
281  * was FetchScope::Full, FetchScope::Flags or
282  * FetchScope::Headers with no parts specified
283  *
284  * This signal may be emitted any number of times before
285  * the result() signal is emitted. The result() signal will
286  * only be emitted once all results have been reported via
287  * one of the signals.
288  *
289  * Note that, depending on the scope, some of the parameters
290  * of this signal may be empty maps.
291  *
292  * @param mailBox the name of the mailbox the fetch job was
293  * executed on
294  * @param uids a map from message sequence numbers to message UIDs;
295  * this will always be populated
296  * @param sizes a map from message sequence numbers to message sizes
297  * (sizes are in octets and refer to the transfer encoding of
298  * the message); populated if the scope is FetchScope::Full or
299  * FetchScope::Headers
300  * @param flags a map from message sequence numbers to message flags;
301  * populated if the scope is FetchScope::Flags, FetchScope::Full
302  * of FetchScope::Headers
303  * @param messages a map from message sequence numbers to message contents (including
304  * headers); populated if the scope is FetchScope::Full,
305  * FetchScope::Headers or FetchScope::Structure
306  *
307  * @deprecated Use messagesAvailable() instead.
308  */
309  KIMAP_DEPRECATED
310  void headersReceived(const QString &mailBox,
311  const QMap<qint64, qint64> &uids,
312  const QMap<qint64, qint64> &sizes,
314  const QMap<qint64, KIMAP::MessagePtr> &messages);
315 
316  /**
317  * An overloaded version of headersReceived(), which includes additional attribute
318  * specified in the FETCH response, but that don't belong to actual content of the
319  * message.
320  *
321  * @param mailBox the name of the mailbox the fetch job was
322  * executed on
323  * @param uids a map from message sequence numbers to message UIDs;
324  * this will always be populated
325  * @param attrs a map from message sequence numbers to a pair of attribute
326  * name and value
327  * @param sizes a map from message sequence numbers to message sizes
328  * (sizes are in octets and refer to the transfer encoding of
329  * the message); populated if the scope is FetchScope::Full or
330  * FetchScope::Headers
331  * @param flags a map from message sequence numbers to message flags;
332  * populated if the scope is FetchScope::Flags, FetchScope::Full
333  * of FetchScope::Headers
334  * @param messages a map from message sequence numbers to message contents (including
335  * headers); populated if the scope is FetchScope::Full,
336  * FetchScope::Headers or FetchScope::Structure
337  *
338  * @overload
339  * @since 4.14
340  * @deprecated Use messagesAvailable() instead.
341  */
342  KIMAP_DEPRECATED
343  void headersReceived(const QString &mailBox,
344  const QMap<qint64, qint64> &uids,
345  const QMap<qint64, qint64> &sizes,
348  const QMap<qint64, KIMAP::MessagePtr> &messages);
349 
350  /**
351  * Provides header and message results.
352  *
353  * This signal will be emitted if the requested scope mode
354  * was FetchScope::Content or FetchScope::Headers with no
355  * parts specified or FetchScope::Structure.
356  *
357  * This signal may be emitted any number of times before
358  * the result() signal is emitted. The result() signal will
359  * only be emitted once all results have been reported via
360  * one of the signals.
361  *
362  *
363  * @param mailBox the name of the mailbox the fetch job was
364  * executed on
365  * @param uids a map from message sequence numbers to message UIDs
366  * @param messages a map from message sequence numbers to message contents
367  *
368  * @deprecated Use messagesAvailable() instead.
369  */
370  KIMAP_DEPRECATED
371  void messagesReceived(const QString &mailBox, const QMap<qint64, qint64> &uids, const QMap<qint64, KIMAP::MessagePtr> &messages);
372 
373  /**
374  * An overloaded version of messagesReceived(), which includes additional attribute
375  * specified in the FETCH response, but that don't belong to actual content of the
376  * message.
377  *
378  * @param mailBox the name of the mailbox the fetch job was
379  * executed on
380  * @param uids a map from message sequence numbers to message UIDs
381  * @param attrs a map from message sequence numbers to pair of attribute
382  * name and it's value
383  * @param messages a map from message sequence numbers to message contents
384  *
385  * @overload
386  * @since 4.14
387  *
388  * @deprecated Use messagesAvailable() instead.
389  */
390  KIMAP_DEPRECATED
391  void messagesReceived(const QString &mailBox,
392  const QMap<qint64, qint64> &uids,
394  const QMap<qint64, KIMAP::MessagePtr> &messages);
395  /**
396  * Provides header and message results.
397  *
398  * This signal will be emitted if the requested scope mode
399  * was FetchScope::Content or FetchScope::Headers with
400  * specified parts.
401  *
402  * This signal may be emitted any number of times before
403  * the result() signal is emitted. The result() signal will
404  * only be emitted once all results have been reported via
405  * one of the signals.
406  *
407  * @param mailBox the name of the mailbox the fetch job was
408  * executed on
409  * @param uids a map from message sequence numbers to message UIDs
410  * @param parts a map from message sequence numbers to message part collections
411  *
412  * @deprecated Use messagesAvailable() instead.
413  */
414  KIMAP_DEPRECATED
415  void partsReceived(const QString &mailBox, const QMap<qint64, qint64> &uids, const QMap<qint64, KIMAP::MessageParts> &parts);
416 
417  /**
418  * An overloaded version of partsReceived(), which includes additional attribute
419  * specified in the FETCH response, but that don't belong to actual content of the
420  * message.
421  *
422  * @param mailBox the name of the mailbox the fetch job was
423  * executed on
424  * @param uids a map from message sequence numbers to message UIDs
425  * @param attrs a map from message sequence numbers to pair of attribute
426  * @param parts a map from message sequence numbers to message part collections
427  *
428  * @overload
429  * @since 4.14
430  *
431  * @deprecated Use messagesAvailable() instead.
432  */
433  KIMAP_DEPRECATED
434  void partsReceived(const QString &mailBox,
435  const QMap<qint64, qint64> &uids,
437  const QMap<qint64, KIMAP::MessageParts> &parts);
438 
439  /**
440  * Provides received messages.
441  *
442  * This signal is emitted when some data are received. The signal can be
443  * emitted multiple times as the messages are being received.
444  *
445  * @param messages A map from message sequence number to message. Not all
446  * fields may be populated, depending on the fetch scope.
447  *
448  * @since 5.6
449  */
450  void messagesAvailable(const QMap<qint64, KIMAP::Message> &messages);
451 
452  /**
453  * Provides vanished messages.
454  *
455  * This signal is emitted when QRESYNC capability (RFC5162) is available and has
456  * bee enabled on the server, and @p FetchScope::qresync has been set to @p true.
457  * It contains a list of messages that have vanished from the mailbox since the
458  * last modification sequence specified in @p FetchScope::changedSince.
459  *
460  * @param uids UIDs of messages that have been removed from the mailbox since
461  * the specified modification sequence.
462  *
463  * @since 5.16
464  */
465  void messagesVanished(const KIMAP::ImapSet &uids);
466 
467 protected:
468  void doStart() override;
469  void handleResponse(const Response &response) override;
470 
471 private:
472  Q_PRIVATE_SLOT(d_func(), void emitPendings())
473 };
474 
475 }
@ HeaderAndContent
Fetch the message MIME headers and the content of parts specified in the parts field.
Definition: fetchjob.h:133
Fetch message data from the server.
Definition: fetchjob.h:59
Used to indicate what message data should be fetched.
Definition: fetchjob.h:74
QList< QByteArray > parts
Specify which message parts to operate on.
Definition: fetchjob.h:162
bool operator==(const Qt3DRender::QGraphicsApiFilter &reference, const Qt3DRender::QGraphicsApiFilter &sample)
@ Content
Fetch the message content (the UID is also fetched)
Definition: fetchjob.h:111
Represents a set of natural numbers (1->∞) in a as compact as possible form.
Definition: imapset.h:126
@ Structure
Fetch the MIME message body structure (the UID is also fetched)
Definition: fetchjob.h:104
@ Headers
Fetch RFC-2822 or MIME message headers.
Definition: fetchjob.h:96
@ Flags
Fetch the message flags (the UID is also fetched)
Definition: fetchjob.h:100
Mode
Used to indicate what part of the message should be fetched.
Definition: fetchjob.h:82
@ Full
Fetch the complete message.
Definition: fetchjob.h:115
QString message
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sun Dec 3 2023 03:51:44 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.