E-MailRelay
gprotocolmessage.h
Go to the documentation of this file.
1//
2// Copyright (C) 2001-2024 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 using AddressStyle = GStore::MessageStore::AddressStyle ;
77 struct FromInfo /// Extra information from the SMTP MAIL-FROM command passed to GSmtp::ProtocolMessage::setFrom().
78 {
79 std::string auth ; // RFC-2554 MAIL-FROM with AUTH= ie. 'auth-in' (xtext or "<>")
80 std::string body ; // RFC-1652 MAIL-FROM with BODY={7BIT|8BITMIME|BINARYMIME}
81 bool smtputf8 {true} ; // RFC-6531 MAIL-FROM with SMTPUTF8
82 AddressStyle address_style {AddressStyle::Ascii} ;
83 } ;
84 struct ToInfo /// Extra information passed to GSmtp::ProtocolMessage::addTo().
85 {
86 explicit ToInfo( const VerifierStatus & ) ;
87 VerifierStatus status ;
88 AddressStyle address_style ;
89 } ;
90
91 virtual ~ProtocolMessage() = default ;
92 ///< Destructor.
93
95 ///< Returns a signal which is raised once process() has completed.
96
97 virtual void reset() = 0 ;
98 ///< Clears the message state, terminates any asynchronous message
99 ///< processing and resets the object as if just constructed.
100 ///< (In practice this is clear() plus the disconnection of any
101 ///< forwarding client).
102
103 virtual void clear() = 0 ;
104 ///< Clears the message state and terminates any asynchronous
105 ///< message processing.
106
107 virtual GStore::MessageId setFrom( const std::string & from_user , const FromInfo & ) = 0 ;
108 ///< Sets the message envelope 'from' address etc. Returns a unique
109 ///< message id.
110
111 virtual bool addTo( const ToInfo & to ) = 0 ;
112 ///< Adds an envelope 'to'. See also GSmtp::Verifier::verify().
113 ///< Returns false if an invalid user.
114 ///<
115 ///< Precondition: setFrom() called since clear() or process().
116
117 virtual void addReceived( const std::string & ) = 0 ;
118 ///< Adds a 'received' line to the start of the content.
119 ///< Precondition: at least one successful addTo() call
120
121 virtual GStore::NewMessage::Status addContent( const char * , std::size_t ) = 0 ;
122 ///< Adds content. The text should normally end in CR-LF. Returns
123 ///< an error enum, but error processing can be deferred
124 ///< until a final addContent(0) or until process().
125 ///<
126 ///< Precondition: at least one successful addTo() call
127
128 void addContentLine( const std::string & ) ;
129 ///< A convenience function that calls addContent() taking
130 ///< a string parameter and adding CR-LF.
131
132 virtual std::size_t contentSize() const = 0 ;
133 ///< Returns the current content size. Returns the maximum
134 ///< std::size_t value on overflow.
135
136 virtual std::string from() const = 0 ;
137 ///< Returns the setFrom() user string.
138
139 virtual FromInfo fromInfo() const = 0 ;
140 ///< Returns the setFrom() extra info.
141
142 virtual std::string bodyType() const = 0 ;
143 ///< Returns the setFrom() body type, fromInfo().body.
144
145 virtual void process( const std::string & session_auth_id , const std::string & peer_socket_address ,
146 const std::string & peer_certificate ) = 0 ;
147 ///< Starts asynchronous processing of the message. Once processing
148 ///< is complete the message state is cleared and the processedSignal()
149 ///< is raised. All errors are also signalled via the processedSignal().
150 ///< The processedSignal() may be emitted before process() returns.
151 ///<
152 ///< The session-auth-id parameter is used to propagate authentication
153 ///< information from the SMTP AUTH command into individual messages.
154 ///< It is the empty string for unauthenticated clients.
155 ///< See also GAuth::SaslServer::id().
156} ;
157
158#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().