E-MailRelay

gfilter.h
Go to the documentation of this file.
1//
2// Copyright (C) 2001-2024 Graeme Walker <graeme_walker@users.sourceforge.net>
3//
4// This program is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8//
9// This program is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12// GNU General Public License for more details.
13//
14// You should have received a copy of the GNU General Public License
15// along with this program. If not, see <http://www.gnu.org/licenses/>.
16// ===
17///
18/// \file gfilter.h
19///
20
21#ifndef G_SMTP_FILTER_H
22#define G_SMTP_FILTER_H
23
24#include "gdef.h"
25#include "gslot.h"
26#include "gmessagestore.h"
27#include "gstringview.h"
28
29 namespace GSmtp
30{
31 class Filter ;
32}
33
34//| \class GSmtp::Filter
35/// An interface for processing a message file through a filter.
36/// The interface is asynchronous, using a slot/signal completion
37/// callback.
38///
39/// Filters return a tri-state value (ok, abandon, fail) and a
40/// 'special' flag which is interpreted as 're-scan' for server
41/// filters and 'stop-scanning' for client filters.
42///
43/// The abandon state is treated more like success on the server
44/// side but more like failure on the client side.
45///
46/// The fail state has an associated SMTP response string (eg.
47/// "rejected"), an override for the SMTP response code, and a
48/// more expansive reason string for logging.
49///
50 class GSmtp::Filter
51{
52 public:
53 enum class Result // Filter tri-state result value.
54 {
55 ok = 0 ,
56 abandon = 1 ,
57 fail = 2
58 } ;
59 enum class Type // Filter type enum.
60 {
61 server ,
62 client ,
63 routing
64 } ;
65 struct Config /// Configuration passed to filter constructors.
66 {
67 unsigned int timeout {60U} ;
68 std::string domain ; // postcondition: !domain.empty()
69 Config & set_timeout( unsigned int ) noexcept ;
70 Config & set_domain( const std::string & ) ;
71 } ;
72
73 virtual ~Filter() = default ;
74 ///< Destructor.
75
76 virtual std::string id() const = 0 ;
77 ///< Returns the id passed to the derived-class constructor.
78 ///< Used in logging.
79
80 virtual bool quiet() const = 0 ;
81 ///< Returns true if there is no need for logging.
82
83 virtual void start( const GStore::MessageId & ) = 0 ;
84 ///< Starts the filter for the given message. Any previous,
85 ///< incomplete filtering is cancel()ed. Asynchronous completion
86 ///< is indicated by a doneSignal().
87
88 virtual G::Slot::Signal<int> & doneSignal() noexcept = 0 ;
89 ///< Returns a signal which is raised once start() has completed
90 ///< or failed. The signal parameter is the integer value
91 ///< of result().
92
93 virtual void cancel() = 0 ;
94 ///< Aborts any incomplete filtering.
95
96 virtual Result result() const = 0 ;
97 ///< Returns the filter result, after the doneSignal() has been
98 ///< emitted.
99
100 virtual std::string response() const = 0 ;
101 ///< Returns a non-empty SMTP response string iff the filter
102 ///< failed, or an empty response if successful or abandoned.
103
104 virtual int responseCode() const = 0 ;
105 ///< An override for the SMTP response code for when the filter
106 ///< has failed. Many implementations should just return zero.
107
108 virtual std::string reason() const = 0 ;
109 ///< Returns a non-empty reason string iff the filter failed,
110 ///< or an empty reason if successful or abandoned.
111
112 virtual bool special() const = 0 ;
113 ///< Returns true if the filter indicated special handling is
114 ///< required.
115
116 std::string str( Type type ) const ;
117 ///< Returns a diagnostic string for logging, including the
118 ///< filter result.
119
120 static std::string_view strtype( Type type ) noexcept ;
121 ///< Returns a type string for logging: "filter",
122 ///< "client-filter" or "routing-filter".
123
124protected:
125 struct Exit /// Interprets an executable filter's exit code.
126 {
127 Exit( int exit_code , Type ) ;
128 bool ok() const ;
129 bool abandon() const ;
130 bool fail() const ;
131 Result result {Result::fail} ;
132 bool special {false} ;
133 } ;
134} ;
135
136 inline GSmtp::Filter::Config & GSmtp::Filter::Config::set_timeout( unsigned int n ) noexcept { timeout = n ; return *this ; }
137 inline GSmtp::Filter::Config & GSmtp::Filter::Config::set_domain( const std::string & s ) { domain = s ; return *this ; }
138
139#endif
GSmtp::Filter
An interface for processing a message file through a filter.
Definition: gfilter.h:51
GSmtp::Filter::id
virtual std::string id() const =0
Returns the id passed to the derived-class constructor.
GSmtp::Filter::result
virtual Result result() const =0
Returns the filter result, after the doneSignal() has been emitted.
GSmtp::Filter::special
virtual bool special() const =0
Returns true if the filter indicated special handling is required.
GSmtp::Filter::cancel
virtual void cancel()=0
Aborts any incomplete filtering.
GSmtp::Filter::~Filter
virtual ~Filter()=default
Destructor.
GSmtp::Filter::response
virtual std::string response() const =0
Returns a non-empty SMTP response string iff the filter failed, or an empty response if successful or...
GSmtp::Filter::doneSignal
virtual G::Slot::Signal< int > & doneSignal() noexcept=0
Returns a signal which is raised once start() has completed or failed.
GSmtp::Filter::reason
virtual std::string reason() const =0
Returns a non-empty reason string iff the filter failed, or an empty reason if successful or abandone...
GSmtp::Filter::str
std::string str(Type type) const
Returns a diagnostic string for logging, including the filter result.
Definition: gfilter.cpp:26
GSmtp::Filter::strtype
static std::string_view strtype(Type type) noexcept
Returns a type string for logging: "filter", "client-filter" or "routing-filter".
Definition: gfilter.cpp:49
GSmtp::Filter::start
virtual void start(const GStore::MessageId &)=0
Starts the filter for the given message.
GSmtp::Filter::responseCode
virtual int responseCode() const =0
An override for the SMTP response code for when the filter has failed.
GSmtp::Filter::quiet
virtual bool quiet() const =0
Returns true if there is no need for logging.
GStore::MessageId
A somewhat opaque identifer for a GStore::MessageStore message id.
Definition: gmessagestore.h:43
gmessagestore.h
gslot.h
gstringview.h
GSmtp
SMTP classes.
Definition: gadminserver.h:42
std
STL namespace.
GSmtp::Filter::Config
Configuration passed to filter constructors.
Definition: gfilter.h:66
GSmtp::Filter::Exit
Interprets an executable filter's exit code.
Definition: gfilter.h:126
G::Slot::Signal< int >