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

KDE's Doxygen guidelines are available online.