E-MailRelay

gprotocolmessage.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 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 "gmessagestore.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 to assemble and
39/// process an incoming message. It implements the three 'buffers'
40/// 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 using DoneSignal = G::Slot::Signal<bool,const MessageId&,const std::string&,const std::string&> ;
67
68 virtual ~ProtocolMessage() = default ;
69 ///< Destructor.
70
71 virtual DoneSignal & doneSignal() = 0 ;
72 ///< Returns a signal which is raised once process() has
73 ///< completed.
74 ///<
75 ///< The signal parameters are 'success', 'id', 'short-response' and
76 ///< 'full-reason'. As a special case, if success is true and id
77 ///< is invalid then the message processing was either abandoned
78 ///< or it only had local-mailbox recipients.
79
80 virtual void reset() = 0 ;
81 ///< Resets the object state as if just constructed.
82
83 virtual void clear() = 0 ;
84 ///< Clears the message state and terminates any asynchronous
85 ///< message processing.
86
87 virtual MessageId setFrom( const std::string & from_user , const std::string & from_auth ) = 0 ;
88 ///< Sets the message envelope 'from'.
89
90 virtual bool addTo( VerifierStatus to_status ) = 0 ;
91 ///< Adds an envelope 'to'. See also GSmtp::Verifier::verify().
92 ///< Returns false if an invalid user.
93 ///<
94 ///< Precondition: setFrom() called since clear() or process().
95
96 virtual void addReceived( const std::string & ) = 0 ;
97 ///< Adds a 'received' line to the start of the content.
98 ///< Precondition: at least one successful addTo() call
99
100 virtual bool addText( const char * , std::size_t ) = 0 ;
101 ///< Adds text. The text should normally end in CR-LF. Returns
102 ///< false on error, typically because a size limit is reached.
103 ///<
104 ///< Precondition: at least one successful addTo() call
105
106 bool addTextLine( const std::string & ) ;
107 ///< A convenience function that calls addText() taking
108 ///< a string parameter and adding CR-LF.
109
110 virtual std::string from() const = 0 ;
111 ///< Returns the setFrom() string.
112
113 virtual void process( const std::string & session_auth_id , const std::string & peer_socket_address ,
114 const std::string & peer_certificate ) = 0 ;
115 ///< Starts asynchronous processing of the message. Once processing
116 ///< is complete the message state is cleared and the doneSignal()
117 ///< is raised. The signal may be raised before process() returns.
118 ///<
119 ///< The session-auth-id parameter is used to propagate authentication
120 ///< information from the SMTP AUTH command into individual messages.
121 ///< It is the empty string for unauthenticated clients.
122 ///< See also GAuth::SaslServer::id().
123} ;
124
125#endif
GSmtp::MessageId
A somewhat opaque identifer for a MessageStore message.
Definition: gmessagestore.h:43
GSmtp::ProtocolMessage
An interface used by the ServerProtocol class to assemble and process an incoming message.
Definition: gprotocolmessage.h:64
GSmtp::ProtocolMessage::clear
virtual void clear()=0
Clears the message state and terminates any asynchronous message processing.
GSmtp::ProtocolMessage::~ProtocolMessage
virtual ~ProtocolMessage()=default
Destructor.
GSmtp::ProtocolMessage::reset
virtual void reset()=0
Resets the object state as if just constructed.
GSmtp::ProtocolMessage::addTo
virtual bool addTo(VerifierStatus to_status)=0
Adds an envelope 'to'.
GSmtp::ProtocolMessage::addTextLine
bool addTextLine(const std::string &)
A convenience function that calls addText() taking a string parameter and adding CR-LF.
Definition: gprotocolmessage.cpp:24
GSmtp::ProtocolMessage::doneSignal
virtual DoneSignal & doneSignal()=0
Returns a signal which is raised once process() has completed.
GSmtp::ProtocolMessage::from
virtual std::string from() const =0
Returns the setFrom() string.
GSmtp::ProtocolMessage::setFrom
virtual MessageId setFrom(const std::string &from_user, const std::string &from_auth)=0
Sets the message envelope 'from'.
GSmtp::ProtocolMessage::addReceived
virtual void addReceived(const std::string &)=0
Adds a 'received' line to the start of the content.
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 *, std::size_t)=0
Adds text.
GSmtp::VerifierStatus
A structure returned by GSmtp::Verifier to describe the status of a 'rcpt-to' or 'vrfy' recipient.
Definition: gverifierstatus.h:52
gexception.h
gmessagestore.h
gslot.h
gstrings.h
gverifier.h
GSmtp
SMTP and message-store classes.
Definition: gadminserver.h:39
G::Slot::Signal< bool, const MessageId &, const std::string &, const std::string & >