E-MailRelay

gfilter.h
Go to the documentation of this file.
1//
2// Copyright (C) 2001-2021 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 "gmessagestore.h"
26#include "gslot.h"
27
28 namespace GSmtp
29{
30 class Filter ;
31}
32
33//| \class GSmtp::Filter
34/// An interface for processing a message file through a filter.
35/// The interface is asynchronous, using a slot/signal completion
36/// callback.
37///
38/// Filters return a tri-state value (ok, abandon, fail) and
39/// a 'special' flag which is interpreted as 're-scan' for
40/// server filters and 'stop-scanning' for client filters.
41///
42/// The abandon state is treated more like success on the
43/// server side but more like failure on the client side.
44///
45/// The fail state has an associated public response (eg.
46/// "rejected") and a more expansive private reason.
47///
48 class GSmtp::Filter
49{
50 public:
51 virtual ~Filter() = default ;
52 ///< Destructor.
53
54 virtual std::string id() const = 0 ;
55 ///< Returns the id passed to the derived-class constructor.
56 ///< Used in logging.
57
58 virtual bool simple() const = 0 ;
59 ///< Returns true if the concrete filter class is one that can
60 ///< never change the file (eg. a do-nothing filter class).
61
62 virtual void start( const MessageId & ) = 0 ;
63 ///< Starts the filter for the given message. Any previous,
64 ///< incomplete filtering is cancel()ed. Asynchronous completion
65 ///< is indicated by a doneSignal().
66
67 virtual G::Slot::Signal<int> & doneSignal() = 0 ;
68 ///< Returns a signal which is raised once start() has completed
69 ///< or failed. The signal parameter is ok=0, abandon=1, fail=2.
70
71 virtual void cancel() = 0 ;
72 ///< Aborts any incomplete filtering.
73
74 virtual bool abandoned() const = 0 ;
75 ///< Returns true if the filter result was 'abandoned'.
76
77 virtual std::string response() const = 0 ;
78 ///< Returns a non-empty response string iff the filter failed,
79 ///< or an empty response if successful or abandoned.
80
81 virtual std::string reason() const = 0 ;
82 ///< Returns a non-empty reason string iff the filter failed,
83 ///< or an empty reason if successful or abandoned.
84
85 virtual bool special() const = 0 ;
86 ///< Returns true if the filter indicated special handling is
87 ///< required.
88
89 std::string str( bool server_side ) const ;
90 ///< Returns a diagnostic string for logging.
91
92 public:
93 enum class Result // Filter tri-state result value.
94 {
95 f_ok = 0 ,
96 f_abandon = 1 ,
97 f_fail = 2
98 } ;
99
100 protected:
101 struct Exit /// Interprets an executable filter's exit code.
102 {
103 Exit( int exit_code , bool server_side ) ;
104 bool ok() const ;
105 bool abandon() const ;
106 bool fail() const ;
107 Result result ;
108 bool special ;
109 } ;
110} ;
111
112#endif
GSmtp::Filter
An interface for processing a message file through a filter.
Definition: gfilter.h:49
GSmtp::Filter::id
virtual std::string id() const =0
Returns the id passed to the derived-class constructor.
GSmtp::Filter::special
virtual bool special() const =0
Returns true if the filter indicated special handling is required.
GSmtp::Filter::doneSignal
virtual G::Slot::Signal< int > & doneSignal()=0
Returns a signal which is raised once start() has completed or failed.
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 response string iff the filter failed, or an empty response if successful or aban...
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(bool server_side) const
Returns a diagnostic string for logging.
Definition: gfilter.cpp:25
GSmtp::Filter::abandoned
virtual bool abandoned() const =0
Returns true if the filter result was 'abandoned'.
GSmtp::Filter::start
virtual void start(const MessageId &)=0
Starts the filter for the given message.
GSmtp::Filter::simple
virtual bool simple() const =0
Returns true if the concrete filter class is one that can never change the file (eg.
GSmtp::MessageId
A somewhat opaque identifer for a MessageStore message.
Definition: gmessagestore.h:43
gmessagestore.h
gslot.h
GSmtp
SMTP and message-store classes.
Definition: gadminserver.h:39
GSmtp::Filter::Exit
Interprets an executable filter's exit code.
Definition: gfilter.h:102
G::Slot::Signal< int >