KIMAP2

fetchjob.h
1 /*
2  Copyright (c) 2009 Kevin Ottens <[email protected]>
3  Copyright (c) 2017 Christian Mollekopf <[email protected]>
4 
5  This library is free software; you can redistribute it and/or modify it
6  under the terms of the GNU Library General Public License as published by
7  the Free Software Foundation; either version 2 of the License, or (at your
8  option) any later version.
9 
10  This library is distributed in the hope that it will be useful, but WITHOUT
11  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12  FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13  License for more details.
14 
15  You should have received a copy of the GNU Library General Public License
16  along with this library; see the file COPYING.LIB. If not, write to the
17  Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
18  02110-1301, USA.
19 */
20 
21 #ifndef KIMAP2_FETCHJOB_H
22 #define KIMAP2_FETCHJOB_H
23 
24 #include "kimap2_export.h"
25 
26 #include "imapset.h"
27 #include "job.h"
28 
29 #include <kmime/kmime_content.h>
30 #include <kmime/kmime_message.h>
31 
32 namespace KIMAP2
33 {
34 
35 class Session;
36 struct Message;
37 class FetchJobPrivate;
38 
39 typedef QSharedPointer<KMime::Content> ContentPtr;
40 typedef QMap<QByteArray, ContentPtr> MessageParts;
41 
42 typedef QSharedPointer<KMime::Message> MessagePtr;
43 typedef QList<QByteArray> MessageFlags;
44 
45 typedef QPair<QByteArray, QVariant> MessageAttribute;
46 typedef QList<MessageAttribute> MessageAttributes;
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 KIMAP2_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 KIMAP2_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  */
132 
133  /**
134  * Fetch message size (in octets), internal date of the message, flags, UID
135  * and all RFC822 headers.
136  *
137  * The @p parts field is ignored when using this scope
138  */
139  FullHeaders
140  };
141 
142  /**
143  * Specify which message parts to operate on.
144  *
145  * This refers to multipart-MIME message parts or MIME-IMB encapsulated
146  * message parts.
147  *
148  * Note that this is ignored unless @p mode is Headers or Content.
149  *
150  * If @p mode is Headers, this sets the parts to get the MIME headers
151  * for. If this list is empty, the headers for the whole message
152  * (the RFC-2822 headers) are fetched.
153  *
154  * If @p mode is Content, this sets the parts to fetch. Parts are
155  * fetched wholesale. If this list is empty, the whole message body
156  * is fetched (all MIME parts together).
157  */
159 
160  /**
161  * Specify what message data should be fetched.
162  */
164 
165  /**
166  * Specify to fetch only items with mod-sequence higher then @p changedSince.
167  *
168  * The server must have CONDSTORE capability (RFC4551).
169  *
170  * Default value is 0 (ignored).
171  *
172  */
173  quint64 changedSince;
174 
175  /**
176  * Enables retrieving of Gmail-specific extensions
177  *
178  * The FETCH response will contain X-GM-MSGID, X-GM-THRID and X-GM-LABELS
179  *
180  * Do NOT enable this, unless talking to Gmail servers, otherwise the
181  * request may fail.
182  */
184  };
185 
186  class KIMAP2_EXPORT Result
187  {
188  public:
189  qint64 sequenceNumber;
190  qint64 uid;
191  qint64 size;
192  KIMAP2::MessageFlags flags;
193  KIMAP2::MessagePtr message;
194  KIMAP2::MessageParts parts;
195  KIMAP2::MessageAttributes attributes;
196  };
197 
198  explicit FetchJob(Session *session);
199  virtual ~FetchJob();
200 
201  /**
202  * Set which messages to fetch data for.
203  *
204  * If sequence numbers are given, isUidBased() should be false. If UIDs
205  * are given, isUidBased() should be true.
206  *
207  * @param set the sequence numbers or UIDs of the messages to fetch data for
208  */
209  void setSequenceSet(const ImapSet &set);
210  /**
211  * The messages that will be fetched.
212  */
213  ImapSet sequenceSet() const;
214 
215  /**
216  * Set how the sequence set should be interpreted.
217  *
218  * @param uidBased if @c true the argument to setSequenceSet will be
219  * interpreted as UIDs, if @c false it will be interpreted
220  * as sequence numbers
221  */
222  void setUidBased(bool uidBased);
223  /**
224  * How to interpret the sequence set.
225  *
226  * @return if @c true the result of sequenceSet() should be
227  * interpreted as UIDs, if @c false it should be interpreted
228  * as sequence numbers
229  */
230  bool isUidBased() const;
231 
232  /**
233  * Sets what data should be fetched.
234  *
235  * The default scope is FetchScope::Content (all content parts).
236  *
237  * @param scope a FetchScope object describing what data
238  * should be fetched
239  */
240  void setScope(const FetchScope &scope);
241  /**
242  * Specifies what data will be fetched.
243  */
244  FetchScope scope() const;
245 
246  /**
247  * Avoid calling parse() on returned KMime::Messages
248  */
249  void setAvoidParsing(bool);
250 
251 Q_SIGNALS:
252  void resultReceived(const Result &);
253 
254 protected:
255  void doStart() Q_DECL_OVERRIDE;
256  void handleResponse(const Message &response) Q_DECL_OVERRIDE;
257 };
258 
259 }
260 
261 #endif
bool gmailExtensionsEnabled
Enables retrieving of Gmail-specific extensions.
Definition: fetchjob.h:183
Mode
Used to indicate what part of the message should be fetched.
Definition: fetchjob.h:82
Fetch RFC-2822 or MIME message headers.
Definition: fetchjob.h:96
quint64 changedSince
Specify to fetch only items with mod-sequence higher then changedSince.
Definition: fetchjob.h:173
Mode mode
Specify what message data should be fetched.
Definition: fetchjob.h:163
Used to indicate what message data should be fetched.
Definition: fetchjob.h:74
Fetch the message MIME headers and the content of parts specified in the parts field.
Definition: fetchjob.h:131
Represents a set of natural numbers (1->∞) in a as compact as possible form.
Definition: imapset.h:141
QList< QByteArray > parts
Specify which message parts to operate on.
Definition: fetchjob.h:158
Definition: acl.cpp:25
Fetch message data from the server.
Definition: fetchjob.h:59
Fetch the MIME message body structure (the UID is also fetched)
Definition: fetchjob.h:104
Fetch the message flags (the UID is also fetched)
Definition: fetchjob.h:100
Fetch the message content (the UID is also fetched)
Definition: fetchjob.h:111
Fetch the complete message.
Definition: fetchjob.h:115
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Mon Dec 6 2021 23:00:24 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.