E-MailRelay
gfilter.h
Go to the documentation of this file.
1 //
2 // Copyright (C) 2001-2018 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 "gsmtp.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 ///
49 {
50 public:
51  virtual ~Filter() ;
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 std::string & path ) = 0 ;
63  ///< Starts the filter for the given message file. Any previous,
64  ///< incomplete filtering is cancel()ed. Asynchronous completion
65  ///< is indicated by a doneSignal().
66 
67  virtual G::Slot::Signal1<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 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  int result ; // enum
108  bool special ;
109  } ;
110 
111 private:
112  void operator=( const Filter & ) ; // not implemented
113 } ;
114 
115 #endif
SMTP and message-store classes.
Definition: gadminserver.h:39
virtual std::string id() const =0
Returns the id passed to the derived-class constructor.
virtual void start(const std::string &path)=0
Starts the filter for the given message file.
virtual G::Slot::Signal1< int > & doneSignal()=0
Returns a signal which is raised once start() has completed or failed.
std::string str(bool server_side) const
Returns a diagnostic string for logging.
Definition: gfilter.cpp:26
virtual ~Filter()
Destructor.
Definition: gfilter.cpp:42
virtual std::string response() const =0
Returns a non-empty response string iff the filter failed, or an empty response if successful or aban...
virtual std::string reason() const =0
Returns a non-empty reason string iff the filter failed, or an empty reason if successful or abandone...
virtual void cancel()=0
Aborts any incomplete filtering.
An interface for processing a message file through a filter.
Definition: gfilter.h:48
virtual bool simple() const =0
Returns true if the concrete filter class is one that can never change the file (eg.
virtual bool special() const =0
Returns true if the filter indicated special handling is required.
virtual bool abandoned() const =0
Returns true if the filter result was 'abandoned'.
Interprets an executable filter's exit code.
Definition: gfilter.h:101