MailCommon::SearchRule Class

class MailCommon::SearchRule

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. More...

Header: #include <MailCommon/SearchRule>
CMake: find_package(KPim6MailCommon REQUIRED)
target_link_libraries(mytarget PRIVATE KPim6::MailCommon)
Inherited By:

MailCommon::SearchRuleStatus

Public Types

enum Function { FuncNone, FuncContains, FuncContainsNot, FuncEquals, FuncNotEqual, …, FuncHasNoInvitation }
Ptr
enum RequiredPart { Envelope, Header, CompleteMessage }

Public Functions

SearchRule(const QByteArray &field = QByteArray(), MailCommon::SearchRule::Function function = FuncContains, const QString &contents = QString())
SearchRule(const MailCommon::SearchRule &other)
virtual ~SearchRule()
virtual void addQueryTerms(Akonadi::SearchTerm &groupTerm, bool &emptyIsNotAnError) const
const QString asString() const
QString contents() const
QByteArray field() const
MailCommon::SearchRule::Function function() const
void generateSieveScript(QStringList &requireModules, QString &code)
virtual QString informationAboutNotValidRules() const
virtual bool isEmpty() const = 0
virtual bool matches(const Akonadi::Item &item) const = 0
virtual MailCommon::SearchRule::RequiredPart requiredPart() const = 0
void setContents(const QString &contents)
void setField(const QByteArray &name)
void setFunction(MailCommon::SearchRule::Function function)
void writeConfig(KConfigGroup &group, int index) const
const MailCommon::SearchRule &operator=(const MailCommon::SearchRule &other)
QDataStream &operator>>(QDataStream &) const

Static Public Members

SearchRule::Ptr createInstance(QDataStream &stream)
SearchRule::Ptr createInstance(const MailCommon::SearchRule &other)
SearchRule::Ptr createInstance(const QByteArray &field = QByteArray(), MailCommon::SearchRule::Function function = FuncContains, const QString &contents = QString())
SearchRule::Ptr createInstance(const QByteArray &field, const char *function, const QString &contents)
SearchRule::Ptr createInstanceFromConfig(const KConfigGroup &group, int index)

Protected Functions

Akonadi::SearchTerm::Condition akonadiComparator() const
bool isNegated() const
void maybeLogMatchResult(bool result) const

Detailed Description

Member Type Documentation

enum SearchRule::Function

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.).

ConstantValueDescription
MailCommon::SearchRule::FuncNone-1No function
MailCommon::SearchRule::FuncContains0The field contains the contents
MailCommon::SearchRule::FuncContainsNot1The field does not contain the contents
MailCommon::SearchRule::FuncEquals2The field equals the contents
MailCommon::SearchRule::FuncNotEqual3The field does not equal the contents
MailCommon::SearchRule::FuncRegExp4The field matches the regular expression
MailCommon::SearchRule::FuncNotRegExp5The field does not match the regular expression
MailCommon::SearchRule::FuncIsGreater6The field is greater than the contents
MailCommon::SearchRule::FuncIsLessOrEqual7The field is less than or equal to the contents
MailCommon::SearchRule::FuncIsLess8The field is less than the contents
MailCommon::SearchRule::FuncIsGreaterOrEqual9The field is greater than or equal to the contents
MailCommon::SearchRule::FuncIsInAddressbook10The address is in the address book
MailCommon::SearchRule::FuncIsNotInAddressbook11The address is not in the address book
MailCommon::SearchRule::FuncIsInCategory12The address is in the category
MailCommon::SearchRule::FuncIsNotInCategory13The address is not in the category
MailCommon::SearchRule::FuncHasAttachment14The message has an attachment
MailCommon::SearchRule::FuncHasNoAttachment15The message has no attachment
MailCommon::SearchRule::FuncStartWith16The field starts with the contents
MailCommon::SearchRule::FuncNotStartWith17The field does not start with the contents
MailCommon::SearchRule::FuncEndWith18The field ends with the contents
MailCommon::SearchRule::FuncNotEndWith19The field does not end with the contents
MailCommon::SearchRule::FuncHasInvitation20The message has an invitation
MailCommon::SearchRule::FuncHasNoInvitation21The message has no invitation

[alias] SearchRule::Ptr

Defines a pointer to a search rule.

enum SearchRule::RequiredPart

Possible required parts.

ConstantValueDescription
MailCommon::SearchRule::Envelope0Envelope
MailCommon::SearchRule::Header1Header
MailCommon::SearchRule::CompleteMessage2Whole message

Member Function Documentation

[explicit] SearchRule::SearchRule(const QByteArray &field = QByteArray(), MailCommon::SearchRule::Function function = FuncContains, const QString &contents = QString())

Creates new new search rule.

field The field to search in. function The function to use for searching. contents The contents to search for.

SearchRule::SearchRule(const MailCommon::SearchRule &other)

Creates a new search rule from an other rule.

[virtual noexcept] SearchRule::~SearchRule()

Destroys the search rule.

[virtual] void SearchRule::addQueryTerms(Akonadi::SearchTerm &groupTerm, bool &emptyIsNotAnError) const

Adds query terms to the given term group.

groupTerm The search term group to add query terms to emptyIsNotAnError Whether empty values should be considered an error

[protected] Akonadi::SearchTerm::Condition SearchRule::akonadiComparator() const

Converts the rule function into the corresponding Akonadi query operator.

Returns The Akonadi search term condition

const QString SearchRule::asString() const

Returns the rule as string for debugging purpose

Returns A string representation of the rule

QString SearchRule::contents() const

Returns the contents of the rule.

Returns The search contents

See also setContents().

[static] SearchRule::Ptr SearchRule::createInstance(QDataStream &stream)

Creates a new search rule by deserializing its structure from a data stream.

[static] SearchRule::Ptr SearchRule::createInstance(const MailCommon::SearchRule &other)

Creates a new search rule by cloning an other rule.

[static] SearchRule::Ptr SearchRule::createInstance(const QByteArray &field = QByteArray(), MailCommon::SearchRule::Function function = FuncContains, const QString &contents = QString())

Creates a new search rule of a certain type by instantiating the appropriate subclass depending on the field.

field The field to search in. function The function to use for searching. contents The contents to search for.

[static] SearchRule::Ptr SearchRule::createInstance(const QByteArray &field, const char *function, const QString &contents)

Creates a new search rule of a certain type by instantiating the appropriate subclass depending on the field.

field The field to search in. function The name of the function to use for searching. contents The contents to search for.

[static] SearchRule::Ptr SearchRule::createInstanceFromConfig(const KConfigGroup &group, int index)

* Creates a new search rule from a given config group. * * group The config group to read the structure from. * index The identifier that is used to distinguish * rules within a single config group. * * ote This function does no validation of the data obtained * from the config file. You should call isEmpty yourself * if you need valid rules.

QByteArray SearchRule::field() const

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.

Returns The header field name

See also setField().

MailCommon::SearchRule::Function SearchRule::function() const

Returns the filter function of the rule.

Returns The current filter function

See also setFunction().

void SearchRule::generateSieveScript(QStringList &requireModules, QString &code)

Generates a Sieve script representation of this rule.

requireModules The list of Sieve modules required by the script code The generated Sieve script code

[virtual] QString SearchRule::informationAboutNotValidRules() const

Returns information about validation errors in this rule.

Returns A string describing validation errors, or empty if valid

[pure virtual] bool SearchRule::isEmpty() const

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.

Returns True if the rule is empty, false otherwise

[protected] bool SearchRule::isNegated() const

Helper that returns whether the rule has a negated function.

Returns True if the function is negated, false otherwise

[pure virtual] bool SearchRule::matches(const Akonadi::Item &item) const

Tries to match the rule against the KMime::Message in the given item.

Returns true if the rule matched, false otherwise.

Note: Must be implemented by subclasses.

item The Akonadi item to match against Returns True if the rule matches, false otherwise

[protected] void SearchRule::maybeLogMatchResult(bool result) const

Logs the result of a match operation for debugging purposes.

result The result of the match operation

[pure virtual] MailCommon::SearchRule::RequiredPart SearchRule::requiredPart() const

Returns the required part from the item that is needed for the search to operate. See

Returns The required part for this rule

See also RequiredPart.

void SearchRule::setContents(const QString &contents)

Set the contents of the rule.

This can be either a substring to search for in or a regexp pattern to match against the header.

contents The contents to search for

See also contents().

void SearchRule::setField(const QByteArray &name)

Sets the message header field name.

Note: Make sure the name contains no trailing ':'.

name The header field name

See also field().

void SearchRule::setFunction(MailCommon::SearchRule::Function function)

Sets the filter function of the rule.

function The filter function to set

See also function().

void SearchRule::writeConfig(KConfigGroup &group, int index) const

Saves the object into a given config group.

group The config group. 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).

const MailCommon::SearchRule &SearchRule::operator=(const MailCommon::SearchRule &other)

Initializes this rule with an other rule.

QDataStream &SearchRule::operator>>(QDataStream &) const

Stream operator for serialization.