Mailcommon

mailfilter.h
1/*
2 * kmail: KDE mail client
3 * SPDX-FileCopyrightText: 1996-1998 Stefan Taferner <taferner@kde.org>
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
21class KConfigGroup;
22
23namespace MailCommon
24{
25/**
26 * @brief The MailFilter class
27 */
28class 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
33public:
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 */
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. */
75
76 static int filterActionsMaximumSize();
77 void generateRandomIdentifier();
78
79 /**
80 * Returns the unique identifier of this filter.
81 */
82 [[nodiscard]] QString identifier() const;
83
84 /** Equivalent to @p pattern()->name(). @return name of the filter */
85 [[nodiscard]] 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 [[nodiscard]] 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 [[nodiscard]] 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 [[nodiscard]] 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 [[nodiscard]] 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 [[nodiscard]] 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 [[nodiscard]] 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 [[nodiscard]] 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 [[nodiscard]] 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 [[nodiscard]] 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 [[nodiscard]] 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 [[nodiscard]] 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 [[nodiscard]] 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 [[nodiscard]] 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 [[nodiscard]] 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 [[nodiscard]] bool isAutoNaming() const;
308
309 /** Return if filter is enabled or not
310 */
311 [[nodiscard]] 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
319private:
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
340MAILCOMMON_EXPORT QDataStream &operator<<(QDataStream &stream, const MailFilter &filter);
341MAILCOMMON_EXPORT QDataStream &operator>>(QDataStream &stream, MailFilter &filter);
342}
A helper class for the filtering process.
Definition itemcontext.h:27
The MailFilter class.
Definition mailfilter.h:29
ReturnCode
Result codes returned by process.
Definition mailfilter.h:45
AccountType
Account type codes used by setApplicability.
Definition mailfilter.h:56
This class is an abstraction of a search over messages.
RequiredPart
Possible required parts.
Definition searchrule.h:68
The filter dialog.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jul 12 2024 11:51:24 by doxygen 1.11.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.