File indexing completed on 2024-09-22 04:49:59

 /*
  * SPDX-FileCopyrightText: 1996-1998 Stefan Taferner <taferner@kde.org>
  *
  * SPDX-License-Identifier: GPL-2.0-or-later
  *
  */
 
 #pragma once
 
 #include "mailcommon_export.h"
 #include "searchpattern.h"
 
 #include "mailcommon/itemcontext.h"
 
 #include <Akonadi/Collection>
 #include <Akonadi/Item>
 
 #include <KMime/KMimeMessage>
 #include <KMime/MDN>
 
 #include <QObject>
 
 class QWidget;
 
 namespace MailCommon
 {
 /**
  * @short Abstract base class for mail filter actions.
  *
  * Abstract base class for mail filter actions. All it can do is
  * hold a name (ie. type-string). There are several sub-classes that
  * inherit form this and are capable of providing parameter handling
  * (import/export as string, a widget to allow editing, etc.)
  *
  * @author Marc Mutz <mutz@kde.org>, based on work by Stefan Taferner <taferner@kde.org>.
  * @see Filter FilterMgr
  */
 class MAILCOMMON_EXPORT FilterAction : public QObject
 {
     Q_OBJECT
 public:
     /**
      * Describes the possible return codes of filter processing:
      */
     enum ReturnCode {
         ErrorNeedComplete = 0x1, ///< Could not process because a complete message is needed.
         GoOn = 0x2, ///< Go on with applying filter actions.
         ErrorButGoOn = 0x4, ///< A non-critical error occurred
         ///  (e.g. an invalid address in the 'forward' action),
         ///   but processing should continue.
         CriticalError = 0x8 ///< A critical error occurred during processing
                             ///  (e.g. "disk full").
     };
 
     /**
      * Creates a new filter action.
      *
      * The action is initialized with an identifier @p name and
      * an i18n'd @p label.
      */
     FilterAction(const QString &name, const QString &label, QObject *parent = nullptr);
 
     /**
      * Destroys the filter action.
      */
     ~FilterAction() override;
 
     /**
      * Returns i18n'd label, ie. the one which is presented in
      * the filter dialog.
      */
     [[nodiscard]] QString label() const;
 
     /**
      * Returns identifier name, ie. the one under which it is
      * known in the config.
      */
     [[nodiscard]] QString name() const;
 
     [[nodiscard]] virtual QStringList sieveRequires() const;
 
     [[nodiscard]] virtual QString sieveCode() const;
 
     /**
      * Execute action on given message (inside the item context).
      * Returns @p CriticalError if a
      * critical error has occurred (eg. disk full), @p ErrorButGoOn if
      * there was a non-critical error (e.g. invalid address in
      * 'forward' action), @p ErrorNeedComplete if a complete message
      * is required, @p GoOn if the message shall be processed by
      * further filters and @p Ok otherwise.
      */
     [[nodiscard]] virtual ReturnCode process(ItemContext &context, bool applyOnOutbound) const = 0;
 
     /**
      * Returns the required part from the item that is needed for the action to
      * operate. See @ref MailCommon::SearchRule::RequiredPart */
     [[nodiscard]] virtual SearchRule::RequiredPart requiredPart() const = 0;
     /**
      * Determines whether this action is valid. But this is just a
      * quick test. Eg., actions that have a mail address as parameter
      * shouldn't try real address validation, but only check if the
      * string representation is empty.
      */
     [[nodiscard]] virtual bool isEmpty() const;
 
     [[nodiscard]] virtual QString informationAboutNotValidAction() const;
 
     /**
      * Creates a widget for setting the filter action parameter. Also
      * sets the value of the widget.
      */
     [[nodiscard]] virtual QWidget *createParamWidget(QWidget *parent) const;
 
     /**
      * The filter action shall set it's parameter from the widget's
      * contents. It is allowed that the value is read by the action
      * before this function is called.
      */
     virtual void applyParamWidgetValue(QWidget *paramWidget);
 
     /**
      * The filter action shall set it's widget's contents from it's
      * parameter.
      */
     virtual void setParamWidgetValue(QWidget *paramWidget) const;
 
     /**
      * The filter action shall clear it's parameter widget's
      * contents.
      */
     virtual void clearParamWidget(QWidget *paramWidget) const;
 
     /**
      * Read extra arguments from given string.
      */
     virtual void argsFromString(const QString &argsStr) = 0;
 
     /**
      * Read extra arguments from given string.
      * Return true if we need to update config file
      */
     [[nodiscard]] virtual bool argsFromStringInteractive(const QString &argsStr, const QString &filterName);
 
     [[nodiscard]] virtual QString argsAsStringReal() const;
 
     /**
      * Return extra arguments as string. Must not contain newlines.
      */
     [[nodiscard]] virtual QString argsAsString() const = 0;
 
     /**
      * Returns a translated string describing this filter for visualization
      * purposes, e.g. in the filter log.
      */
     [[nodiscard]] virtual QString displayString() const = 0;
 
     /**
      * Called from the filter when a folder is removed. Tests if the
      * folder @p aFolder is used and changes to @p aNewFolder in this
      * case. Returns true if a change was made.
      */
     [[nodiscard]] virtual bool folderRemoved(const Akonadi::Collection &aFolder, const Akonadi::Collection &aNewFolder);
 
     /**
      * Static function that creates a filter action of this type.
      */
     static FilterAction *newAction();
 
     /**
      * Automates the sending of MDNs from filter actions.
      */
     static void sendMDN(const Akonadi::Item &item,
                         KMime::MDN::DispositionType d,
                         const QList<KMime::MDN::DispositionModifier> &m = QList<KMime::MDN::DispositionModifier>());
 
 Q_SIGNALS:
     /**
      * Called to notify that the current FilterAction has had some
      * value modification
      */
     void filterActionModified();
 
 private:
     const QString mName;
     const QString mLabel;
 };
 }