Mailcommon

filteraction.h
1 /*
2  * SPDX-FileCopyrightText: 1996-1998 Stefan Taferner <[email protected]>
3  *
4  * SPDX-License-Identifier: GPL-2.0-or-later
5  *
6  */
7 
8 #pragma once
9 
10 #include "mailcommon_export.h"
11 #include "searchpattern.h"
12 
13 #include "mailcommon/itemcontext.h"
14 
15 #include <Akonadi/Collection>
16 #include <Akonadi/Item>
17 
18 #include <KMime/KMimeMessage>
19 #include <KMime/MDN>
20 
21 #include <QObject>
22 
23 class QWidget;
24 
25 namespace MailCommon
26 {
27 /**
28  * @short Abstract base class for mail filter actions.
29  *
30  * Abstract base class for mail filter actions. All it can do is
31  * hold a name (ie. type-string). There are several sub-classes that
32  * inherit form this and are capable of providing parameter handling
33  * (import/export as string, a widget to allow editing, etc.)
34  *
35  * @author Marc Mutz <[email protected]>, based on work by Stefan Taferner <[email protected]>.
36  * @see Filter FilterMgr
37  */
38 class MAILCOMMON_EXPORT FilterAction : public QObject
39 {
40  Q_OBJECT
41 public:
42  /**
43  * Describes the possible return codes of filter processing:
44  */
45  enum ReturnCode {
46  ErrorNeedComplete = 0x1, ///< Could not process because a complete message is needed.
47  GoOn = 0x2, ///< Go on with applying filter actions.
48  ErrorButGoOn = 0x4, ///< A non-critical error occurred
49  /// (e.g. an invalid address in the 'forward' action),
50  /// but processing should continue.
51  CriticalError = 0x8 ///< A critical error occurred during processing
52  /// (e.g. "disk full").
53  };
54 
55  /**
56  * Creates a new filter action.
57  *
58  * The action is initialized with an identifier @p name and
59  * an i18n'd @p label.
60  */
61  FilterAction(const QString &name, const QString &label, QObject *parent = nullptr);
62 
63  /**
64  * Destroys the filter action.
65  */
66  ~FilterAction() override;
67 
68  /**
69  * Returns i18n'd label, ie. the one which is presented in
70  * the filter dialog.
71  */
72  Q_REQUIRED_RESULT QString label() const;
73 
74  /**
75  * Returns identifier name, ie. the one under which it is
76  * known in the config.
77  */
78  Q_REQUIRED_RESULT QString name() const;
79 
80  Q_REQUIRED_RESULT virtual QStringList sieveRequires() const;
81 
82  Q_REQUIRED_RESULT virtual QString sieveCode() const;
83 
84  /**
85  * Execute action on given message (inside the item context).
86  * Returns @p CriticalError if a
87  * critical error has occurred (eg. disk full), @p ErrorButGoOn if
88  * there was a non-critical error (e.g. invalid address in
89  * 'forward' action), @p ErrorNeedComplete if a complete message
90  * is required, @p GoOn if the message shall be processed by
91  * further filters and @p Ok otherwise.
92  */
93  Q_REQUIRED_RESULT virtual ReturnCode process(ItemContext &context, bool applyOnOutbound) const = 0;
94 
95  /**
96  * Returns the required part from the item that is needed for the action to
97  * operate. See @ref MailCommon::SearchRule::RequiredPart */
98  Q_REQUIRED_RESULT virtual SearchRule::RequiredPart requiredPart() const = 0;
99  /**
100  * Determines whether this action is valid. But this is just a
101  * quick test. Eg., actions that have a mail address as parameter
102  * shouldn't try real address validation, but only check if the
103  * string representation is empty.
104  */
105  Q_REQUIRED_RESULT virtual bool isEmpty() const;
106 
107  Q_REQUIRED_RESULT virtual QString informationAboutNotValidAction() const;
108 
109  /**
110  * Creates a widget for setting the filter action parameter. Also
111  * sets the value of the widget.
112  */
113  Q_REQUIRED_RESULT virtual QWidget *createParamWidget(QWidget *parent) const;
114 
115  /**
116  * The filter action shall set it's parameter from the widget's
117  * contents. It is allowed that the value is read by the action
118  * before this function is called.
119  */
120  virtual void applyParamWidgetValue(QWidget *paramWidget);
121 
122  /**
123  * The filter action shall set it's widget's contents from it's
124  * parameter.
125  */
126  virtual void setParamWidgetValue(QWidget *paramWidget) const;
127 
128  /**
129  * The filter action shall clear it's parameter widget's
130  * contents.
131  */
132  virtual void clearParamWidget(QWidget *paramWidget) const;
133 
134  /**
135  * Read extra arguments from given string.
136  */
137  virtual void argsFromString(const QString &argsStr) = 0;
138 
139  /**
140  * Read extra arguments from given string.
141  * Return true if we need to update config file
142  */
143  Q_REQUIRED_RESULT virtual bool argsFromStringInteractive(const QString &argsStr, const QString &filterName);
144 
145  Q_REQUIRED_RESULT virtual QString argsAsStringReal() const;
146 
147  /**
148  * Return extra arguments as string. Must not contain newlines.
149  */
150  Q_REQUIRED_RESULT virtual QString argsAsString() const = 0;
151 
152  /**
153  * Returns a translated string describing this filter for visualization
154  * purposes, e.g. in the filter log.
155  */
156  Q_REQUIRED_RESULT virtual QString displayString() const = 0;
157 
158  /**
159  * Called from the filter when a folder is removed. Tests if the
160  * folder @p aFolder is used and changes to @p aNewFolder in this
161  * case. Returns true if a change was made.
162  */
163  Q_REQUIRED_RESULT virtual bool folderRemoved(const Akonadi::Collection &aFolder, const Akonadi::Collection &aNewFolder);
164 
165  /**
166  * Static function that creates a filter action of this type.
167  */
168  static FilterAction *newAction();
169 
170  /**
171  * Automates the sending of MDNs from filter actions.
172  */
173  static void sendMDN(const Akonadi::Item &item,
174  KMime::MDN::DispositionType d,
176 
177 Q_SIGNALS:
178  /**
179  * Called to notify that the current FilterAction has had some
180  * value modification
181  */
182  void filterActionModified();
183 
184 private:
185  const QString mName;
186  const QString mLabel;
187 };
188 }
Abstract base class for mail filter actions.
Definition: filteraction.h:38
RequiredPart
Possible required parts.
Definition: searchrule.h:68
A helper class for the filtering process.
Definition: itemcontext.h:26
ReturnCode
Describes the possible return codes of filter processing:
Definition: filteraction.h:45
The filter dialog.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Fri Jun 9 2023 04:00:23 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.