KIMAP

fetchjob.h
1/*
2 SPDX-FileCopyrightText: 2009 Kevin Ottens <ervin@kde.org>
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
19namespace KIMAP
20{
21class Session;
22struct Response;
23class FetchJobPrivate;
24
25using ContentPtr = QSharedPointer<KMime::Content>;
26using MessageParts = QMap<QByteArray, ContentPtr>;
27
28using MessagePtr = QSharedPointer<KMime::Message>;
29using MessageFlags = QList<QByteArray>;
30
31using MessageAttribute = QPair<QByteArray, QVariant>;
32
33struct 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;
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 */
59class KIMAP_EXPORT FetchJob : public Job
60{
61 Q_OBJECT
62 Q_DECLARE_PRIVATE(FetchJob)
63
64 friend class SessionPrivate;
65
66public:
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 [[nodiscard]] 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 [[nodiscard]] 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
276Q_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,
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 */
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 */
466
467protected:
468 void doStart() override;
469 void handleResponse(const Response &response) override;
470
471private:
472 Q_PRIVATE_SLOT(d_func(), void emitPendings())
473};
474
475}
Used to indicate what message data should be fetched.
Definition fetchjob.h:75
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
@ Headers
Fetch RFC-2822 or MIME message headers.
Definition fetchjob.h:96
@ Structure
Fetch the MIME message body structure (the UID is also fetched)
Definition fetchjob.h:104
@ Content
Fetch the message content (the UID is also fetched)
Definition fetchjob.h:111
@ HeaderAndContent
Fetch the message MIME headers and the content of parts specified in the parts field.
Definition fetchjob.h:133
@ Flags
Fetch the message flags (the UID is also fetched)
Definition fetchjob.h:100
QList< QByteArray > parts
Specify which message parts to operate on.
Definition fetchjob.h:162
Fetch message data from the server.
Definition fetchjob.h:60
void messagesAvailable(const QMap< qint64, KIMAP::Message > &messages)
Provides received messages.
KIMAP_DEPRECATED void partsReceived(const QString &mailBox, const QMap< qint64, qint64 > &uids, const QMap< qint64, KIMAP::MessageAttribute > &attrs, const QMap< qint64, KIMAP::MessageParts > &parts)
An overloaded version of partsReceived(), which includes additional attribute specified in the FETCH ...
KIMAP_DEPRECATED void messagesReceived(const QString &mailBox, const QMap< qint64, qint64 > &uids, const QMap< qint64, KIMAP::MessagePtr > &messages)
Provides header and message results.
KIMAP_DEPRECATED void partsReceived(const QString &mailBox, const QMap< qint64, qint64 > &uids, const QMap< qint64, KIMAP::MessageParts > &parts)
Provides header and message results.
KIMAP_DEPRECATED void headersReceived(const QString &mailBox, const QMap< qint64, qint64 > &uids, const QMap< qint64, qint64 > &sizes, const QMap< qint64, KIMAP::MessageFlags > &flags, const QMap< qint64, KIMAP::MessagePtr > &messages)
Provides header and message results.
void messagesVanished(const KIMAP::ImapSet &uids)
Provides vanished messages.
KIMAP_DEPRECATED void headersReceived(const QString &mailBox, const QMap< qint64, qint64 > &uids, const QMap< qint64, qint64 > &sizes, const QMap< qint64, KIMAP::MessageAttribute > &attrs, const QMap< qint64, KIMAP::MessageFlags > &flags, const QMap< qint64, KIMAP::MessagePtr > &messages)
An overloaded version of headersReceived(), which includes additional attribute specified in the FETC...
KIMAP_DEPRECATED void messagesReceived(const QString &mailBox, const QMap< qint64, qint64 > &uids, const QMap< qint64, KIMAP::MessageAttribute > &attrs, const QMap< qint64, KIMAP::MessagePtr > &messages)
An overloaded version of messagesReceived(), which includes additional attribute specified in the FET...
Represents a set of natural numbers (1->∞) in a as compact as possible form.
Definition imapset.h:127
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Tue Mar 26 2024 11:14:37 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.