E-MailRelay

- Main Page
- Namespaces
- Classes
- Files

- File List
- File Members

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 ///
63 class GSmtp::ProtocolMessage
64 {
65 public:
66 virtual ~ProtocolMessage() ;
67 ///< Destructor.
68
69 virtual G::Slot::Signal4<bool,unsigned long,std::string,std::string> & doneSignal() = 0 ;
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
gstrings.h
GSmtp
SMTP and message-store classes.
Definition: gadminserver.h:39
G::Slot::Signal4< bool, unsigned long, std::string, std::string >
GSmtp::ProtocolMessage::setFrom
virtual bool setFrom(const std::string &from_user, const std::string &from_auth)=0
Sets the message envelope 'from'.
GSmtp::ProtocolMessage::clear
virtual void clear()=0
Clears the message state and terminates any asynchronous message processing.
GSmtp::ProtocolMessage::doneSignal
virtual G::Slot::Signal4< bool, unsigned long, std::string, std::string > & doneSignal()=0
Returns a signal which is raised once process() has completed.
gslot.h
gverifier.h
GSmtp::ProtocolMessage::process
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.
GSmtp::ProtocolMessage::addText
virtual bool addText(const char *, size_t)=0
Adds text.
gexception.h
GSmtp::ProtocolMessage::addReceived
virtual void addReceived(const std::string &)=0
Adds a 'received' line to the start of the content.
GSmtp::VerifierStatus
A structure returned by GSmtp::Verifier to describe the status of a 'rcpt-to' recipient.
Definition: gverifierstatus.h:51
GSmtp::ProtocolMessage
An interface used by the ServerProtocol class to assemble and process an incoming message...
Definition: gprotocolmessage.h:63
GSmtp::ProtocolMessage::reset
virtual void reset()=0
Resets the object state as if just constructed.
GSmtp::ProtocolMessage::addTo
virtual bool addTo(const std::string &to_user, VerifierStatus to_status)=0
Adds an envelope 'to'.
gsmtp.h
GSmtp::ProtocolMessage::from
virtual std::string from() const =0
Returns the setFrom() string.
GSmtp::ProtocolMessage::addTextLine
bool addTextLine(const std::string &)
A convenience function that calls addText() taking a string parameter.
Definition: gprotocolmessage.cpp:29
GSmtp::ProtocolMessage::~ProtocolMessage
virtual ~ProtocolMessage()
Destructor.
Definition: gprotocolmessage.cpp:25