searchrule.h 7.92 KB
Newer Older
1
/*
2
  SPDX-FileCopyrightText: 2015-2020 Laurent Montel <montel@kde.org>
3

4
  SPDX-License-Identifier: GPL-2.0-or-later
5
6
7
8
9
10
11
12
13
14
*/
#ifndef SEARCHRULE_H
#define SEARCHRULE_H

#include "mailcommon_export.h"
#include <AkonadiCore/SearchQuery>

#include <AkonadiCore/Item>

class KConfigGroup;
Laurent Montel's avatar
Laurent Montel committed
15
namespace MailCommon {
16
17
18
19
20
21
22
23
24
25
26
27
28
/**
 * @short This class represents one search pattern rule.
 * Incoming mail is sent through the list of mail filter
 * rules before it is placed in the associated mail folder (usually "inbox").
 * This class represents one mail filter rule. It is also used to represent
 * a search rule as used by the search dialog and folders.
 */
class MAILCOMMON_EXPORT SearchRule
{
public:
    /**
     * Defines a pointer to a search rule.
     */
Laurent Montel's avatar
Laurent Montel committed
29
    typedef std::shared_ptr<SearchRule> Ptr;
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63

    /**
     * Describes operators for comparison of field and contents.
     *
     * If you change the order or contents of the enum: do not forget
     * to change funcConfigNames[], sFilterFuncList and matches()
     * in SearchRule, too.
     * Also, it is assumed that these functions come in pairs of logical
     * opposites (ie. "=" <-> "!=", ">" <-> "<=", etc.).
     */
    enum Function {
        FuncNone = -1,
        FuncContains = 0,
        FuncContainsNot,
        FuncEquals,
        FuncNotEqual,
        FuncRegExp,
        FuncNotRegExp,
        FuncIsGreater,
        FuncIsLessOrEqual,
        FuncIsLess,
        FuncIsGreaterOrEqual,
        FuncIsInAddressbook,
        FuncIsNotInAddressbook,
        FuncIsInCategory,
        FuncIsNotInCategory,
        FuncHasAttachment,
        FuncHasNoAttachment,
        FuncStartWith,
        FuncNotStartWith,
        FuncEndWith,
        FuncNotEndWith
    };

Yuri Chornoivan's avatar
Yuri Chornoivan committed
64
65
66
67
    /**
     * @enum RequiredPart
     * @brief Possible required parts.
     */
68
    enum RequiredPart {
Yuri Chornoivan's avatar
Yuri Chornoivan committed
69
70
71
        Envelope = 0,   ///< Envelope
        Header,         ///< Header
        CompleteMessage ///< Whole message
72
73
74
75
76
77
78
79
80
    };

    /**
     * Creates new new search rule.
     *
     * @param field The field to search in.
     * @param function The function to use for searching.
     * @param contents The contents to search for.
     */
Laurent Montel's avatar
Laurent Montel committed
81
    explicit SearchRule(const QByteArray &field = QByteArray(), Function function = FuncContains, const QString &contents = QString());
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100

    /**
     * Creates a new search rule from an @p other rule.
     */
    SearchRule(const SearchRule &other);

    /**
     * Initializes this rule with an @p other rule.
     */
    const SearchRule &operator=(const SearchRule &other);

    /**
     * Creates a new search rule of a certain type by instantiating the
     * appropriate subclass depending on the @p field.
     *
     * @param field The field to search in.
     * @param function The function to use for searching.
     * @param contents The contents to search for.
     */
Laurent Montel's avatar
Laurent Montel committed
101
    static SearchRule::Ptr createInstance(const QByteArray &field = QByteArray(), Function function = FuncContains, const QString &contents = QString());
102
103
104
105
106
107
108
109
110

    /**
     * Creates a new search rule of a certain type by instantiating the
     * appropriate subclass depending on the @p field.
     *
     * @param field The field to search in.
     * @param function The name of the function to use for searching.
     * @param contents The contents to search for.
     */
Laurent Montel's avatar
Laurent Montel committed
111
    static SearchRule::Ptr createInstance(const QByteArray &field, const char *function, const QString &contents);
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166

    /**
     * Creates a new search rule by cloning an @p other rule.
     */
    static SearchRule::Ptr createInstance(const SearchRule &other);

    /**
     * Creates a new search rule by deseralizing its structure from a data @p stream.
     */
    static SearchRule::Ptr createInstance(QDataStream &stream);

    /**
     * Creates a new search rule from a given config @p group.
     *
     * @param group The config group to read the structure from.
     * @param index The identifier that is used to distinguish
     *              rules within a single config group.
     *
     * @note This function does no validation of the data obtained
     *       from the config file. You should call isEmpty yourself
     *       if you need valid rules.
     */
    static SearchRule::Ptr createInstanceFromConfig(const KConfigGroup &group, int index);

    /**
     * Destroys the search rule.
     */
    virtual ~SearchRule();

    /**
     * Tries to match the rule against the KMime::Message in the
     * given @p item.
     *
     * @return true if the rule matched, false otherwise.
     *
     * @note Must be implemented by subclasses.
     */
    virtual bool matches(const Akonadi::Item &item) const = 0;

    /**
     * Determines whether the rule is worth considering.
     * It isn't if either the field is not set or the contents is empty.
     * The calling code should make sure that it's rule list contains
     * only non-empty rules, as matches doesn't check this.
     */
    virtual bool isEmpty() const = 0;

    /**
     * Returns the required part from the item that is needed for the search to
     * operate. See @ref RequiredPart */
    virtual SearchRule::RequiredPart requiredPart() const = 0;

    /**
     * Saves the object into a given config @p group.
     *
Yuri Chornoivan's avatar
Yuri Chornoivan committed
167
     * @param group The config group.
168
169
170
171
172
173
174
175
     * @param index The identifier that is used to distinguish
     *              rules within a single config group.
     *
     * @note This function will happily write itself even when it's
     *       not valid, assuming higher layers to Do The Right Thing(TM).
     */
    void writeConfig(KConfigGroup &group, int index) const;

Laurent Montel's avatar
Laurent Montel committed
176
    void generateSieveScript(QStringList &requireModules, QString &code);
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232

    /**
     * Sets the filter @p function of the rule.
     */
    void setFunction(Function function);

    /**
     * Returns the filter function of the rule.
     */
    Function function() const;

    /**
     * Sets the message header field @p name.
     *
     * @note Make sure the name contains no trailing ':'.
     */
    void setField(const QByteArray &name);

    /**
     * Returns the message header field name (without the trailing ':').
     *
     * There are also six pseudo-headers:
     * @li \<message\>: Try to match against the whole message.
     * @li \<body\>: Try to match against the body of the message.
     * @li \<any header\>: Try to match against any header field.
     * @li \<recipients\>: Try to match against both To: and Cc: header fields.
     * @li \<size\>: Try to match against size of message (numerical).
     * @li \<age in days\>: Try to match against age of message (numerical).
     * @li \<status\>: Try to match against status of message (status).
     * @li \<tag\>: Try to match against message tags.
     */
    QByteArray field() const;

    /**
     * Set the @p contents of the rule.
     *
     * This can be either a substring to search for in
     * or a regexp pattern to match against the header.
     */
    void setContents(const QString &contents);

    /**
     * Returns the contents of the rule.
     */
    QString contents() const;

    /**
     * Returns the rule as string for debugging purpose
     */
    const QString asString() const;

    /**
     * Adds query terms to the given term group.
     */
    virtual void addQueryTerms(Akonadi::SearchTerm &groupTerm, bool &emptyIsNotAnError) const
    {
Laurent Montel's avatar
Laurent Montel committed
233
234
        Q_UNUSED(groupTerm)
        Q_UNUSED(emptyIsNotAnError)
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
    }

    QDataStream &operator>>(QDataStream &) const;
    virtual QString informationAboutNotValidRules() const
    {
        return QString();
    }

protected:
    /**
     * Helper that returns whether the rule has a negated function.
     */
    bool isNegated() const;

    /**
     * Converts the rule function into the corresponding Akonadi query operator.
     */
    Akonadi::SearchTerm::Condition akonadiComparator() const;

private:
    static Function configValueToFunc(const char *);
    static QString functionToString(Function);
    QString conditionToString(Function function);

    QByteArray mField;
    Function mFunction;
Laurent Montel's avatar
Laurent Montel committed
261
    QString mContents;
262
263
264
265
};
}

#endif // SEARCHRULE_H