Mailcommon

mailfilter.h
1 /*
2  * kmail: KDE mail client
3  * SPDX-FileCopyrightText: 1996-1998 Stefan Taferner <[email protected]>
4  *
5  * SPDX-License-Identifier: GPL-2.0-or-later
6  *
7  */
8 #pragma once
9 
10 #include "mailcommon_export.h"
11 
12 #include "mailcommon/filteraction.h"
13 #include "mailcommon/searchpattern.h"
14 
15 #include <Akonadi/Collection>
16 #include <QKeySequence>
17 
18 #include <KMime/KMimeMessage>
19 
20 #include <QDataStream>
21 #include <QVector>
22 
23 class KConfigGroup;
24 
25 namespace MailCommon
26 {
27 /**
28  * @brief The MailFilter class
29  */
30 class MAILCOMMON_EXPORT MailFilter
31 {
32  friend MAILCOMMON_EXPORT QDataStream &operator<<(QDataStream &stream, const MailFilter &filter);
33  friend MAILCOMMON_EXPORT QDataStream &operator>>(QDataStream &stream, MailFilter &filter);
34 
35 public:
36  /** Result codes returned by process. They mean:
37 
38  @param GoOn Everything OK. You are still the owner of the
39  message and you should continue applying filter actions to this
40  message.
41 
42  @param CriticalError A critical error occurred (e.g. "disk full").
43 
44  @param NoResult For internal use only!
45 
46  */
47  enum ReturnCode { NoResult, GoOn, CriticalError };
48 
49  /** Account type codes used by setApplicability. They mean:
50 
51  @param All Apply to all accounts
52 
53  @param ButImap Apply to all but IMAP accounts
54 
55  @param Checked apply to all accounts specified by setApplyOnAccount
56 
57  */
58  enum AccountType {
59  All,
60  ButImap,
61  Checked,
62  };
63 
64  /** Constructor that initializes basic settings. */
65  MailFilter();
66 
67  /** Constructor that initializes from given config group.
68  * Filters are stored one by one in config groups, i.e.
69  * one filter, one group. */
70  explicit MailFilter(const KConfigGroup &aConfig, bool internal, bool &needUpdate);
71 
72  /** Copy constructor. Constructs a deep copy of @p aFilter. */
73  MailFilter(const MailFilter &other);
74 
75  /** Cleanup. */
76  ~MailFilter();
77 
78  static int filterActionsMaximumSize();
79  void generateRandomIdentifier();
80 
81  /**
82  * Returns the unique identifier of this filter.
83  */
84  Q_REQUIRED_RESULT QString identifier() const;
85 
86  /** Equivalent to @p pattern()->name(). @return name of the filter */
87  Q_REQUIRED_RESULT QString name() const;
88 
89  /** Execute the filter action(s) on the given message.
90  Returns:
91  @li 2 if a critical error occurred,
92  @li 1 if the caller is still
93  the owner of the message,
94  @li 0 if processed successfully.
95  @param context The context that contains the item to which the actions should be applied.
96  @param stopIt Contains @c true if the caller may apply other filters and @c false if he shall
97  stop the filtering of this message.
98  @param applyOnOutbound Defines whether to apply the rules on the outbound.
99  */
100  Q_REQUIRED_RESULT ReturnCode execActions(ItemContext &context, bool &stopIt, bool applyOnOutbound) const;
101 
102  /**
103  * Returns the required part from the item that is needed for the filter to
104  * operate. See @ref SearchRule::RequiredPart */
105  Q_REQUIRED_RESULT SearchRule::RequiredPart requiredPart(const QString &id) const;
106 
107  /** Write contents to given config group. */
108  void writeConfig(KConfigGroup &config, bool exportFilter) const;
109 
110  /** Initialize from given config group. */
111  Q_REQUIRED_RESULT bool readConfig(const KConfigGroup &config, bool interactive = false);
112 
113  /** Remove empty rules (and actions one day). */
114  QString purify(bool removeAction = true);
115 
116  /** Check for empty pattern and action list. */
117  bool isEmpty() const;
118 
119  /** Provides a reference to the internal action list. If your used
120  the @p setAction() and @p action() functions before, please
121  convert to using myFilter->actions()->at() and friends now. */
122  QVector<FilterAction *> *actions();
123 
124  /** Provides a reference to the internal action list. Const version. */
125  const QVector<FilterAction *> *actions() const;
126 
127  /** Provides a reference to the internal pattern. If you used the
128  @p matches() function before, please convert to using
129  myFilter->pattern()->matches() now. */
130  Q_REQUIRED_RESULT SearchPattern *pattern();
131 
132  /** Provides a reference to the internal pattern. If you used the
133  @p matches() function before, please convert to using
134  myFilter->pattern()->matches() now. */
135  const SearchPattern *pattern() const;
136 
137  /** Set whether this filter should be applied on
138  outbound messages (@p aApply == true) or not.
139  See applyOnOutbound applyOnInbound setApplyOnInbound
140  */
141  void setApplyOnOutbound(bool aApply);
142 
143  /** Set whether this filter should be applied on
144  outbound messages before sending (@p aApply == TRUE) or not.
145  See applyOnOutbound applyOnInbound setApplyOnInbound
146  */
147  void setApplyBeforeOutbound(bool aApply);
148 
149  /** @return true if this filter should be applied on
150  outbound messages, false otherwise.
151  @see setApplyOnOutbound applyOnInbound setApplyOnInbound
152  */
153  bool applyOnOutbound() const;
154 
155  /** @return TRUE if this filter should be applied on
156  outbound messages before they are sent, FALSE otherwise.
157  @see setApplyOnOutbound applyOnInbound setApplyOnInbound
158  */
159  bool applyBeforeOutbound() const;
160 
161  /** Set whether this filter should be applied on
162  inbound messages (@p aApply == true) or not.
163  @see setApplyOnOutbound applyOnInbound applyOnOutbound
164  */
165  void setApplyOnInbound(bool aApply);
166 
167  /** @return true if this filter should be applied on
168  inbound messages, false otherwise.
169  @see setApplyOnOutbound applyOnOutbound setApplyOnInbound
170  */
171  bool applyOnInbound() const;
172 
173  /** Set whether this filter should be applied on
174  explicit (CTRL-J) filtering (@p aApply == true) or not.
175  @see setApplyOnOutbound applyOnInbound applyOnOutbound
176  */
177  void setApplyOnExplicit(bool aApply);
178 
179  /** @return true if this filter should be applied on
180  explicit (CTRL-J) filtering, false otherwise.
181  @see setApplyOnOutbound applyOnOutbound setApplyOnInbound
182  */
183  bool applyOnExplicit() const;
184 
185  /** Set whether this filter should be applied on
186  inbound messages for all accounts (@p aApply == All) or
187  inbound messages for all but IMAP accounts (@p aApply == ButImap) or
188  for a specified set of accounts only.
189  Only applicable to filters that are applied on inbound messages.
190  @see setApplyOnInbound setApplyOnAccount
191  */
192  void setApplicability(AccountType aApply = All);
193 
194  /** Sets whether the filter should be applied on inbound emails in all
195  folders, not just Inbox.
196  */
197  void setApplyOnAllFoldersInbound(bool aApply);
198 
199  /** Returns whether the filter should be applied on inbound emails in all
200  folders, not just Inbox.
201  */
202  bool applyOnAllFoldersInbound() const;
203 
204  /** @return true if this filter should be applied on
205  inbound messages for all accounts, or false if this filter
206  is to be applied on a specified set of accounts only.
207  Only applicable to filters that are applied on inbound messages.
208  @see setApplicability
209  */
210  AccountType applicability() const;
211 
212  /** Set whether this filter should be applied on
213  inbound messages for the account with id (@p id).
214  Only applicable to filters that are only applied to a specified
215  set of accounts.
216  @see setApplicability applyOnAccount
217  */
218  void setApplyOnAccount(const QString &id, bool aApply = true);
219 
220  /** @return true if this filter should be applied on
221  inbound messages from the account with id (@p id), false otherwise.
222  @see setApplicability
223  */
224  bool applyOnAccount(const QString &id) const;
225 
226  void setStopProcessingHere(bool aStop);
227  bool stopProcessingHere() const;
228 
229  /** Set whether this filter should be plugged into the filter menu.
230  */
231  void setConfigureShortcut(bool aShort);
232 
233  /** @return true if this filter should be plugged into the filter menu,
234  false otherwise.
235  @see setConfigureShortcut
236  */
237  bool configureShortcut() const;
238 
239  /** Set whether this filter should be plugged into the toolbar.
240  This can be done only if a shortcut is defined.
241  @see setConfigureShortcut
242  */
243  void setConfigureToolbar(bool aTool);
244 
245  /** @return true if this filter should be plugged into the toolbar,
246  false otherwise.
247  @see setConfigureToolbar
248  */
249  bool configureToolbar() const;
250 
251  /** @return The toolbar name of this filter.
252  * @see setToolbarName
253  */
254  QString toolbarName() const;
255 
256  /** This sets the toolbar name for this filter.
257  * The toolbar name is the text to be displayed underneath the toolbar icon
258  * for this filter. This is usually the same as name(), expect when
259  * explicitly set by this function.
260  * This is useful if the normal filter mame is too long for the toolbar.
261  * @see toolbarName, name
262  */
263  void setToolbarName(const QString &toolbarName);
264 
265  /** Set the shortcut to be used if plugged into the filter menu
266  or toolbar. Default is no shortcut.
267  @see setConfigureShortcut setConfigureToolbar
268  */
269  void setShortcut(const QKeySequence &shortcut);
270 
271  /** @return The shortcut assigned to the filter.
272  @see setShortcut
273  */
274  const QKeySequence &shortcut() const;
275 
276  /** Set the icon to be used if plugged into the filter menu
277  or toolbar. Default is the gear icon.
278  @see setConfigureShortcut setConfigureToolbar
279  */
280  void setIcon(const QString &icon);
281 
282  /** @return The name of the icon to be used.
283  @see setIcon
284  */
285  QString icon() const;
286 
287  /**
288  * Called from the filter manager when a folder is moved.
289  * Tests if the folder aFolder is used in any action. Changes it
290  * to aNewFolder folder in this case.
291  * @return true if a change in some action occurred,
292  * false if no action was affected.
293  */
294  void folderRemoved(const Akonadi::Collection &aFolder, const Akonadi::Collection &aNewFolder);
295 
296  /** Returns the filter in a human-readable form. useful for
297  debugging but not much else. Don't use, as it may well go away
298  in the future... */
299  const QString asString() const;
300 
301  /** Set the mode for using automatic naming for the filter.
302  If the feature is enabled, the name is derived from the
303  first filter rule.
304  */
305  void setAutoNaming(bool useAutomaticNames);
306 
307  /** @return Tells, if an automatic name is used for the filter
308  */
309  bool isAutoNaming() const;
310 
311  /** Return if filter is enabled or not
312  */
313  bool isEnabled() const;
314  void setEnabled(bool);
315 
316  void generateSieveScript(QStringList &requiresModules, QString &code);
317 
318  void clearApplyOnAccount();
319  void agentRemoved(const QString &identifier);
320 
321 private:
322  QString mIdentifier;
323  SearchPattern mPattern;
324  QVector<FilterAction *> mActions;
325  QStringList mAccounts;
326  QString mIcon;
327  QString mToolbarName;
328  QKeySequence mShortcut;
329  bool bApplyOnInbound : 1;
330  bool bApplyBeforeOutbound : 1;
331  bool bApplyOnOutbound : 1;
332  bool bApplyOnExplicit : 1;
333  bool bApplyOnAllFolders : 1;
334  bool bStopProcessingHere : 1;
335  bool bConfigureShortcut : 1;
336  bool bConfigureToolbar : 1;
337  bool bAutoNaming : 1;
338  bool bEnabled : 1;
339  AccountType mApplicability;
340 };
341 
342 MAILCOMMON_EXPORT QDataStream &operator<<(QDataStream &stream, const MailFilter &filter);
343 MAILCOMMON_EXPORT QDataStream &operator>>(QDataStream &stream, MailFilter &filter);
344 }
QDataStream & operator<<(QDataStream &out, const KDateTime &dateTime)
The MailFilter class.
Definition: mailfilter.h:30
AccountType
Account type codes used by setApplicability.
Definition: mailfilter.h:58
RequiredPart
Possible required parts.
Definition: searchrule.h:68
ReturnCode
Result codes returned by process.
Definition: mailfilter.h:47
A helper class for the filtering process.
Definition: itemcontext.h:26
This class is an abstraction of a search over messages.
Definition: searchpattern.h:58
QDataStream & operator>>(QDataStream &in, KDateTime &dateTime)
The filter dialog.
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Sat Sep 24 2022 03:58:15 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.