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

KDE's Doxygen guidelines are available online.