1 /*
2   SPDX-FileCopyrightText: 2003 Andreas Gungl <a.gungl@gmx.de>
3 
4   SPDX-License-Identifier: GPL-2.0-only
5 */
6 
7 #pragma once
8 
9 #include "mailcommon_export.h"
10 
11 #include <QObject>
12 #include <QStringList>
13 #include <memory>
14 namespace MailCommon
15 {
16 /**
17  * @short KMail Filter Log Collector.
18  *
19  * The filter log helps to collect log information about the
20  * filter process in KMail. It's implemented as singleton,
21  * so it's easy to direct pieces of information to a unique
22  * instance.
23  * It's possible to activate / deactivate logging. All
24  * collected log information can get thrown away, the
25  * next added log entry is the first one until another
26  * clearing.
27  * A signal is emitted whenever a new logentry is added,
28  * when the log was cleared or any log state was changed.
29  *
30  * @author Andreas Gungl <a.gungl@gmx.de>
31  */
32 class MAILCOMMON_EXPORT FilterLog : public QObject
33 {
34     Q_OBJECT
35 
36 public:
37     /**
38      * Destroys the filter log.
39      */
40     ~FilterLog() override;
41 
42     /**
43      * Returns the single global instance of the filter log.
44      */
45     static FilterLog *instance();
46 
47     /**
48      * Describes the type of content that will be logged.
49      */
50     enum ContentType {
51         Meta = 1, ///< Log all meta data.
52         PatternDescription = 2, ///< Log all pattern description.
53         RuleResult = 4, ///< Log all rule matching results.
54         PatternResult = 8, ///< Log all pattern matching results.
55         AppliedAction = 16 ///< Log all applied actions.
56     };
57 
58     /**
59      * Sets whether the filter log is currently @p active.
60      */
61     void setLogging(bool active);
62 
63     /**
64      * Returns whether the filter log is currently active.
65      */
66     bool isLogging() const;
67 
68     /**
69      * Sets the maximum @p size of the log in bytes.
70      */
71     void setMaxLogSize(long size = -1);
72 
73     /**
74      * Returns the maximum size of the log in bytes.
75      */
76     long maxLogSize() const;
77 
78     /**
79      * Sets whether a given content @p type will be @p enabled for logging.
80      */
81     void setContentTypeEnabled(ContentType type, bool enabled);
82 
83     /**
84      * Returns whether the given content @p type is enabled for logging.
85      */
86     bool isContentTypeEnabled(ContentType type) const;
87 
88     /**
89      * Adds the given log @p entry under the given content @p type to the log.
90      */
91     void add(const QString &entry, ContentType type);
92 
93     /**
94      * Adds a separator line to the log.
95      */
96     void addSeparator();
97 
98     /**
99      * Clears the log.
100      */
101     void clear();
102 
103     /**
104      * Returns the list of log entries.
105      */
106     QStringList logEntries() const;
107 
108     /**
109      * Saves the log to the file with the given @p fileName.
110      *
111      * @return @c true on success or @c false on failure.
112      */
113     bool saveToFile(const QString &fileName) const;
114 
115     /**
116      * Returns an escaped version of the log which can be used
117      * in a HTML document.
118      */
119     static QString recode(const QString &plain);
120 
121     /**
122      * Dumps the log to console. Used for debugging.
123      */
124     void dump();
125 
126 Q_SIGNALS:
127     /**
128      * This signal is emitted whenever a new @p entry has been added to the log.
129      */
130     void logEntryAdded(const QString &entry);
131 
132     /**
133      * This signal is emitted whenever the log has shrunk.
134      */
135     void logShrinked();
136 
137     /**
138      * This signal is emitted whenever the activity of the filter log has been changed.
139      */
140     void logStateChanged();
141 
142 private:
143     //@cond PRIVATE
144     FilterLog();
145 
146     class FilterLogPrivate;
147     std::unique_ptr<FilterLogPrivate> const d;
148     //@endcond
149 };
150 }
151 
152