E-MailRelay
gprotocolmessage.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 gprotocolmessage.h
19 ///
20 
21 #ifndef G_SMTP_PROTOCOL_MESSAGE_H
22 #define G_SMTP_PROTOCOL_MESSAGE_H
23 
24 #include "gdef.h"
25 #include "gsmtp.h"
26 #include "gslot.h"
27 #include "gstrings.h"
28 #include "gverifier.h"
29 #include "gexception.h"
30 #include <string>
31 
32 namespace GSmtp
33 {
34  class ProtocolMessage ;
35 }
36 
37 /// \class GSmtp::ProtocolMessage
38 /// An interface used by the ServerProtocol class
39 /// to assemble and process an incoming message. It implements
40 /// the three 'buffers' mentioned in RFC-2821 (esp. section 4.1.1).
41 ///
42 /// This interface serves to decouple the protocol class from
43 /// the downstream message processing -- hence the name. Derived
44 /// classes implement different types of downstream processing.
45 /// For store-and-forward behaviour the ProtocolMessageStore
46 /// class uses GSmtp::MessageStore to store messages; for proxying
47 /// behaviour the ProtocolMessageForward class uses GSmtp::Client
48 /// to do immediate forwarding.
49 ///
50 /// The interface is used by the protocol class in the following
51 /// sequence:
52 /// - clear()
53 /// - setFrom()
54 /// - addTo() [1..n]
55 /// - addReceived() [0..n]
56 /// - addText() [0..n]
57 /// - process() -> doneSignal() [async]
58 ///
59 /// The process() method is asynchronous, but note that the
60 /// completion signal may be emitted before the initiating call
61 /// returns.
62 ///
64 {
65 public:
66  virtual ~ProtocolMessage() ;
67  ///< Destructor.
68 
70  ///< Returns a signal which is raised once process() has
71  ///< completed.
72  ///<
73  ///< The signal parameters are 'success', 'id', 'short-reason' and
74  ///< 'full-reason'. As a special case, if success is true and id
75  ///< is zero then the message processing was abandoned.
76 
77  virtual void reset() = 0 ;
78  ///< Resets the object state as if just constructed.
79 
80  virtual void clear() = 0 ;
81  ///< Clears the message state and terminates any asynchronous
82  ///< message processing.
83 
84  virtual bool setFrom( const std::string & from_user , const std::string & from_auth ) = 0 ;
85  ///< Sets the message envelope 'from'. Returns false if an
86  ///< invalid user.
87 
88  virtual bool addTo( const std::string & to_user , VerifierStatus to_status ) = 0 ;
89  ///< Adds an envelope 'to'. The 'to_status' parameter comes
90  ///< from GSmtp::Verifier.verify(). Returns false if an
91  ///< invalid user.
92  ///<
93  ///< Precondition: setFrom() called since clear() or process().
94 
95  virtual void addReceived( const std::string & ) = 0 ;
96  ///< Adds a 'received' line to the start of the content.
97  ///< Precondition: at least one successful addTo() call
98 
99  virtual bool addText( const char * , size_t ) = 0 ;
100  ///< Adds text. Returns false on error, typically because a size
101  ///< limit is reached.
102  ///<
103  ///< Precondition: at least one successful addTo() call
104 
105  bool addTextLine( const std::string & ) ;
106  ///< A convenience function that calls addText() taking
107  ///< a string parameter.
108 
109  virtual std::string from() const = 0 ;
110  ///< Returns the setFrom() string.
111 
112  virtual void process( const std::string & session_auth_id , const std::string & peer_socket_address ,
113  const std::string & peer_certificate ) = 0 ;
114  ///< Starts asynchronous processing of the message. Once processing
115  ///< is complete the message state is cleared and the doneSignal()
116  ///< is raised. The signal may be raised before process() returns.
117  ///<
118  ///< The session-auth-id parameter is used to propagate authentication
119  ///< information from the SMTP AUTH command into individual messages.
120  ///< It is the empty string for unauthenticated clients.
121  ///< See also GAuth::SaslServer::id().
122 
123 private:
124  void operator=( const ProtocolMessage & ) ; // not implemented
125 } ;
126 
127 #endif
SMTP and message-store classes.
Definition: gadminserver.h:39
virtual bool setFrom(const std::string &from_user, const std::string &from_auth)=0
Sets the message envelope 'from'.
virtual void clear()=0
Clears the message state and terminates any asynchronous message processing.
virtual G::Slot::Signal4< bool, unsigned long, std::string, std::string > & doneSignal()=0
Returns a signal which is raised once process() has completed.
virtual void process(const std::string &session_auth_id, const std::string &peer_socket_address, const std::string &peer_certificate)=0
Starts asynchronous processing of the message.
virtual bool addText(const char *, size_t)=0
Adds text.
virtual void addReceived(const std::string &)=0
Adds a 'received' line to the start of the content.
A structure returned by GSmtp::Verifier to describe the status of a 'rcpt-to' recipient.
An interface used by the ServerProtocol class to assemble and process an incoming message...
virtual void reset()=0
Resets the object state as if just constructed.
virtual bool addTo(const std::string &to_user, VerifierStatus to_status)=0
Adds an envelope 'to'.
virtual std::string from() const =0
Returns the setFrom() string.
bool addTextLine(const std::string &)
A convenience function that calls addText() taking a string parameter.
virtual ~ProtocolMessage()
Destructor.