File indexing completed on 2024-09-22 04:50:06

 /*
  * kmail: KDE mail client
  * SPDX-FileCopyrightText: 1996-1998 Stefan Taferner <taferner@kde.org>
  *
  * SPDX-License-Identifier: GPL-2.0-or-later
  *
  */
 #pragma once
 
 #include "mailcommon_export.h"
 
 #include "mailcommon/filteraction.h"
 #include "mailcommon/searchpattern.h"
 
 #include <Akonadi/Collection>
 #include <QKeySequence>
 
 #include <QDataStream>
 #include <QList>
 
 class KConfigGroup;
 
 namespace MailCommon
 {
 /**
  * @brief The MailFilter class
  */
 class MAILCOMMON_EXPORT MailFilter
 {
     friend MAILCOMMON_EXPORT QDataStream &operator<<(QDataStream &stream, const MailFilter &filter);
     friend MAILCOMMON_EXPORT QDataStream &operator>>(QDataStream &stream, MailFilter &filter);
 
 public:
     /** Result codes returned by process. They mean:
 
       @param GoOn Everything OK. You are still the owner of the
       message and you should continue applying filter actions to this
       message.
 
       @param CriticalError A critical error occurred (e.g. "disk full").
 
       @param NoResult For internal use only!
 
     */
     enum ReturnCode { NoResult, GoOn, CriticalError };
 
     /** Account type codes used by setApplicability. They mean:
 
       @param All Apply to all accounts
 
       @param ButImap Apply to all but IMAP accounts
 
       @param Checked apply to all accounts specified by setApplyOnAccount
 
     */
     enum AccountType {
         All,
         ButImap,
         Checked,
     };
 
     /** Constructor that initializes basic settings. */
     MailFilter();
 
     /** Constructor that initializes from given config group.
      * Filters are stored one by one in config groups, i.e.
      * one filter, one group. */
     explicit MailFilter(const KConfigGroup &aConfig, bool internal, bool &needUpdate);
 
     /** Copy constructor. Constructs a deep copy of @p aFilter. */
     MailFilter(const MailFilter &other);
 
     /** Cleanup. */
     ~MailFilter();
 
     static int filterActionsMaximumSize();
     void generateRandomIdentifier();
 
     /**
      * Returns the unique identifier of this filter.
      */
     [[nodiscard]] QString identifier() const;
 
     /** Equivalent to @p pattern()->name(). @return name of the filter */
     [[nodiscard]] QString name() const;
 
     /** Execute the filter action(s) on the given message.
       Returns:
       @li 2 if a critical error occurred,
       @li 1 if the caller is still
       the owner of the message,
       @li 0 if processed successfully.
       @param context The context that contains the item to which the actions should be applied.
       @param stopIt Contains @c true if the caller may apply other filters and @c false if he shall
       stop the filtering of this message.
       @param applyOnOutbound Defines whether to apply the rules on the outbound.
     */
     [[nodiscard]] ReturnCode execActions(ItemContext &context, bool &stopIt, bool applyOnOutbound) const;
 
     /**
      * Returns the required part from the item that is needed for the filter to
      * operate. See @ref SearchRule::RequiredPart */
     [[nodiscard]] SearchRule::RequiredPart requiredPart(const QString &id) const;
 
     /** Write contents to given config group. */
     void writeConfig(KConfigGroup &config, bool exportFilter) const;
 
     /** Initialize from given config group. */
     [[nodiscard]] bool readConfig(const KConfigGroup &config, bool interactive = false);
 
     /** Remove empty rules (and actions one day). */
     QString purify(bool removeAction = true);
 
     /** Check for empty pattern and action list. */
     bool isEmpty() const;
 
     /** Provides a reference to the internal action list. If your used
       the @p setAction() and @p action() functions before, please
       convert to using myFilter->actions()->at() and friends now. */
     QList<FilterAction *> *actions();
 
     /** Provides a reference to the internal action list. Const version. */
     const QList<FilterAction *> *actions() const;
 
     /** Provides a reference to the internal pattern. If you used the
       @p matches() function before, please convert to using
       myFilter->pattern()->matches() now. */
     [[nodiscard]] SearchPattern *pattern();
 
     /** Provides a reference to the internal pattern. If you used the
       @p matches() function before, please convert to using
       myFilter->pattern()->matches() now. */
     const SearchPattern *pattern() const;
 
     /** Set whether this filter should be applied on
       outbound messages (@p aApply == true) or not.
       See applyOnOutbound applyOnInbound setApplyOnInbound
     */
     void setApplyOnOutbound(bool aApply);
 
     /** Set whether this filter should be applied on
       outbound messages before sending (@p aApply == TRUE) or not.
       See applyOnOutbound applyOnInbound setApplyOnInbound
     */
     void setApplyBeforeOutbound(bool aApply);
 
     /** @return true if this filter should be applied on
       outbound messages, false otherwise.
       @see setApplyOnOutbound applyOnInbound setApplyOnInbound
     */
     [[nodiscard]] bool applyOnOutbound() const;
 
     /** @return TRUE if this filter should be applied on
       outbound messages before they are sent, FALSE otherwise.
       @see setApplyOnOutbound applyOnInbound setApplyOnInbound
     */
     [[nodiscard]] bool applyBeforeOutbound() const;
 
     /** Set whether this filter should be applied on
       inbound messages (@p aApply == true) or not.
       @see setApplyOnOutbound applyOnInbound applyOnOutbound
     */
     void setApplyOnInbound(bool aApply);
 
     /** @return true if this filter should be applied on
       inbound messages, false otherwise.
       @see setApplyOnOutbound applyOnOutbound setApplyOnInbound
     */
     [[nodiscard]] bool applyOnInbound() const;
 
     /** Set whether this filter should be applied on
       explicit (CTRL-J) filtering (@p aApply == true) or not.
       @see setApplyOnOutbound applyOnInbound applyOnOutbound
     */
     void setApplyOnExplicit(bool aApply);
 
     /** @return true if this filter should be applied on
       explicit (CTRL-J) filtering, false otherwise.
       @see setApplyOnOutbound applyOnOutbound setApplyOnInbound
     */
     [[nodiscard]] bool applyOnExplicit() const;
 
     /** Set whether this filter should be applied on
       inbound messages for all accounts (@p aApply == All) or
       inbound messages for all but IMAP accounts (@p aApply == ButImap) or
       for a specified set of accounts only.
       Only applicable to filters that are applied on inbound messages.
       @see setApplyOnInbound setApplyOnAccount
     */
     void setApplicability(AccountType aApply = All);
 
     /** Sets whether the filter should be applied on inbound emails in all
       folders, not just Inbox.
     */
     void setApplyOnAllFoldersInbound(bool aApply);
 
     /** Returns whether the filter should be applied on inbound emails in all
       folders, not just Inbox.
     */
     [[nodiscard]] bool applyOnAllFoldersInbound() const;
 
     /** @return true if this filter should be applied on
       inbound messages for all accounts, or false if this filter
       is to be applied on a specified set of accounts only.
       Only applicable to filters that are applied on inbound messages.
       @see setApplicability
     */
     [[nodiscard]] AccountType applicability() const;
 
     /** Set whether this filter should be applied on
       inbound messages for the account with id (@p id).
       Only applicable to filters that are only applied to a specified
       set of accounts.
       @see setApplicability applyOnAccount
     */
     void setApplyOnAccount(const QString &id, bool aApply = true);
 
     /** @return true if this filter should be applied on
       inbound messages from the account with id (@p id), false otherwise.
       @see setApplicability
     */
     [[nodiscard]] bool applyOnAccount(const QString &id) const;
 
     void setStopProcessingHere(bool aStop);
     bool stopProcessingHere() const;
 
     /** Set whether this filter should be plugged into the filter menu.
      */
     void setConfigureShortcut(bool aShort);
 
     /** @return true if this filter should be plugged into the filter menu,
       false otherwise.
       @see setConfigureShortcut
     */
     [[nodiscard]] bool configureShortcut() const;
 
     /** Set whether this filter should be plugged into the toolbar.
       This can be done only if a shortcut is defined.
       @see setConfigureShortcut
     */
     void setConfigureToolbar(bool aTool);
 
     /** @return true if this filter should be plugged into the toolbar,
       false otherwise.
       @see setConfigureToolbar
     */
     [[nodiscard]] bool configureToolbar() const;
 
     /** @return The toolbar name of this filter.
      *  @see setToolbarName
      */
     QString toolbarName() const;
 
     /** This sets the toolbar name for this filter.
      *  The toolbar name is the text to be displayed underneath the toolbar icon
      *  for this filter. This is usually the same as name(),  expect when
      *  explicitly set by this function.
      *  This is useful if the normal filter mame is too long for the toolbar.
      *  @see toolbarName, name
      */
     void setToolbarName(const QString &toolbarName);
 
     /** Set the shortcut to be used if plugged into the filter menu
       or toolbar. Default is no shortcut.
       @see setConfigureShortcut setConfigureToolbar
     */
     void setShortcut(const QKeySequence &shortcut);
 
     /** @return The shortcut assigned to the filter.
       @see setShortcut
     */
     const QKeySequence &shortcut() const;
 
     /** Set the icon to be used if plugged into the filter menu
       or toolbar. Default is the gear icon.
       @see setConfigureShortcut setConfigureToolbar
     */
     void setIcon(const QString &icon);
 
     /** @return The name of the icon to be used.
       @see setIcon
     */
     [[nodiscard]] QString icon() const;
 
     /**
      * Called from the filter manager when a folder is moved.
      * Tests if the folder aFolder is used in any action. Changes it
      * to aNewFolder folder in this case.
      * @return true if a change in some action occurred,
      * false if no action was affected.
      */
     void folderRemoved(const Akonadi::Collection &aFolder, const Akonadi::Collection &aNewFolder);
 
     /** Returns the filter in a human-readable form. useful for
       debugging but not much else. Don't use, as it may well go away
       in the future... */
     const QString asString() const;
 
     /** Set the mode for using automatic naming for the filter.
       If the feature is enabled, the name is derived from the
       first filter rule.
     */
     void setAutoNaming(bool useAutomaticNames);
 
     /** @return Tells, if an automatic name is used for the filter
      */
     [[nodiscard]] bool isAutoNaming() const;
 
     /** Return if filter is enabled or not
      */
     [[nodiscard]] bool isEnabled() const;
     void setEnabled(bool);
 
     void generateSieveScript(QStringList &requiresModules, QString &code);
 
     void clearApplyOnAccount();
     void agentRemoved(const QString &identifier);
 
 private:
     QString mIdentifier;
     SearchPattern mPattern;
     QList<FilterAction *> mActions;
     QStringList mAccounts;
     QString mIcon;
     QString mToolbarName;
     QKeySequence mShortcut;
     bool bApplyOnInbound : 1;
     bool bApplyBeforeOutbound : 1;
     bool bApplyOnOutbound : 1;
     bool bApplyOnExplicit : 1;
     bool bApplyOnAllFolders : 1;
     bool bStopProcessingHere : 1;
     bool bConfigureShortcut : 1;
     bool bConfigureToolbar : 1;
     bool bAutoNaming : 1;
     bool bEnabled : 1;
     AccountType mApplicability;
 };
 
 MAILCOMMON_EXPORT QDataStream &operator<<(QDataStream &stream, const MailFilter &filter);
 MAILCOMMON_EXPORT QDataStream &operator>>(QDataStream &stream, MailFilter &filter);
 }