E-MailRelay
gprotocolmessage.h
Go to the documentation of this file.
1//
2// Copyright (C) 2001-2023 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 "gnewmessage.h"
27#include "gslot.h"
28#include "gstringarray.h"
29#include "gverifier.h"
30#include "gexception.h"
31#include <string>
32
33namespace GSmtp
34{
35 class ProtocolMessage ;
36}
37
38//| \class GSmtp::ProtocolMessage
39/// An interface used by the ServerProtocol class to assemble and
40/// process an incoming message. It implements the three 'buffers'
41/// mentioned in RFC-2821 (esp. section 4.1.1).
42///
43/// This interface serves to decouple the protocol class from
44/// the downstream message processing -- hence the name. Derived
45/// classes implement different types of downstream processing.
46/// For store-and-forward behaviour the ProtocolMessageStore
47/// class uses GSmtp::MessageStore to store messages; for proxying
48/// behaviour the ProtocolMessageForward class uses GSmtp::Client
49/// to do immediate forwarding.
50///
51/// The interface is used by the protocol class in the following
52/// sequence:
53/// - clear()
54/// - setFrom()
55/// - addTo() [1..n]
56/// - addReceived() [0..n]
57/// - addContent() [0..n]
58/// - process() -> processedSignal() [async]
59///
60/// The process() method is asynchronous, but note that the
61/// completion signal may be emitted before the initiating call
62/// returns.
63///
65{
66public:
67 struct ProcessedInfo /// Parameters for GSmtp::ProtocolMessage::processedSignal()
68 {
69 bool success ;
70 GStore::MessageId id ; // message id, not valid() with 'success' true if abandoned
71 int response_code ; // response code (400..599) to send to remote client if not 'success', or zero to default
72 std::string response ; // response to send to remote client (no tabs), empty if 'success'
73 std::string reason ; // log string typically from filter output
74 } ;
76 struct FromInfo /// Extra information from the SMTP MAIL-FROM command passed to GSmtp::ProtocolMessage::setFrom().
77 {
78 std::string auth ; // RFC-2554 MAIL-FROM with AUTH= ie. 'auth-in' (xtext or "<>")
79 std::string body ; // RFC-1652 MAIL-FROM with BODY={7BIT|8BITMIME|BINARYMIME}
80 bool smtputf8 {true} ; // RFC-6531 MAIL-FROM with SMTPUTF8
81 bool utf8address {false} ; // GSmtp::ServerParser::MailboxStyle
82 } ;
83 struct ToInfo /// Extra information passed to GSmtp::ProtocolMessage::addTo().
84 {
85 explicit ToInfo( const VerifierStatus & ) ;
86 VerifierStatus status ;
87 bool utf8address ; // GSmtp::ServerParser::MailboxStyle
88 } ;
89
90 virtual ~ProtocolMessage() = default ;
91 ///< Destructor.
92
94 ///< Returns a signal which is raised once process() has completed.
95
96 virtual void reset() = 0 ;
97 ///< Clears the message state, terminates any asynchronous message
98 ///< processing and resets the object as if just constructed.
99 ///< (In practice this is clear() plus the disconnection of any
100 ///< forwarding client).
101
102 virtual void clear() = 0 ;
103 ///< Clears the message state and terminates any asynchronous
104 ///< message processing.
105
106 virtual GStore::MessageId setFrom( const std::string & from_user , const FromInfo & ) = 0 ;
107 ///< Sets the message envelope 'from' address etc. Returns a unique
108 ///< message id.
109
110 virtual bool addTo( const ToInfo & to ) = 0 ;
111 ///< Adds an envelope 'to'. See also GSmtp::Verifier::verify().
112 ///< Returns false if an invalid user.
113 ///<
114 ///< Precondition: setFrom() called since clear() or process().
115
116 virtual void addReceived( const std::string & ) = 0 ;
117 ///< Adds a 'received' line to the start of the content.
118 ///< Precondition: at least one successful addTo() call
119
120 virtual GStore::NewMessage::Status addContent( const char * , std::size_t ) = 0 ;
121 ///< Adds content. The text should normally end in CR-LF. Returns
122 ///< an error enum, but error processing can be deferred
123 ///< until a final addContent(0) or until process().
124 ///<
125 ///< Precondition: at least one successful addTo() call
126
127 void addContentLine( const std::string & ) ;
128 ///< A convenience function that calls addContent() taking
129 ///< a string parameter and adding CR-LF.
130
131 virtual std::size_t contentSize() const = 0 ;
132 ///< Returns the current content size. Returns the maximum
133 ///< std::size_t value on overflow.
134
135 virtual std::string from() const = 0 ;
136 ///< Returns the setFrom() user string.
137
138 virtual FromInfo fromInfo() const = 0 ;
139 ///< Returns the setFrom() extra info.
140
141 virtual std::string bodyType() const = 0 ;
142 ///< Returns the setFrom() body type, fromInfo().body.
143
144 virtual void process( const std::string & session_auth_id , const std::string & peer_socket_address ,
145 const std::string & peer_certificate ) = 0 ;
146 ///< Starts asynchronous processing of the message. Once processing
147 ///< is complete the message state is cleared and the processedSignal()
148 ///< is raised. All errors are also signalled via the processedSignal().
149 ///< The processedSignal() may be emitted before process() returns.
150 ///<
151 ///< The session-auth-id parameter is used to propagate authentication
152 ///< information from the SMTP AUTH command into individual messages.
153 ///< It is the empty string for unauthenticated clients.
154 ///< See also GAuth::SaslServer::id().
155} ;
156
157#endif
An interface used by the ServerProtocol class to assemble and process an incoming message.
virtual bool addTo(const ToInfo &to)=0
Adds an envelope 'to'.
virtual void clear()=0
Clears the message state and terminates any asynchronous message processing.
virtual ProcessedSignal & processedSignal()=0
Returns a signal which is raised once process() has completed.
virtual ~ProtocolMessage()=default
Destructor.
virtual void reset()=0
Clears the message state, terminates any asynchronous message processing and resets the object as if ...
virtual GStore::MessageId setFrom(const std::string &from_user, const FromInfo &)=0
Sets the message envelope 'from' address etc.
virtual std::size_t contentSize() const =0
Returns the current content size.
virtual std::string from() const =0
Returns the setFrom() user string.
virtual GStore::NewMessage::Status addContent(const char *, std::size_t)=0
Adds content.
virtual void addReceived(const std::string &)=0
Adds a 'received' line to the start of the content.
void addContentLine(const std::string &)
A convenience function that calls addContent() taking a string parameter and adding CR-LF.
virtual std::string bodyType() const =0
Returns the setFrom() body type, fromInfo().body.
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 FromInfo fromInfo() const =0
Returns the setFrom() extra info.
A structure returned by GSmtp::Verifier to describe the status of a 'rcpt-to' or 'vrfy' recipient.
A somewhat opaque identifer for a GStore::MessageStore message id.
Definition: gmessagestore.h:43
SMTP classes.
Definition: gadminserver.h:42
Extra information from the SMTP MAIL-FROM command passed to GSmtp::ProtocolMessage::setFrom().
Parameters for GSmtp::ProtocolMessage::processedSignal()
Extra information passed to GSmtp::ProtocolMessage::addTo().