E-MailRelay

gmessagestore.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 gmessagestore.h
19///
20
21#ifndef G_SMTP_MESSAGE_STORE_H
22#define G_SMTP_MESSAGE_STORE_H
23
24#include "gdef.h"
25#include "gexception.h"
26#include "gslot.h"
27#include "gstringarray.h"
28#include "gpath.h"
29#include <memory>
30
31 namespace GStore
32{
33 class NewMessage ;
34 class StoredMessage ;
35 class MessageId ;
36 class MessageStore ;
37}
38
39//| \class GStore::MessageId
40/// A somewhat opaque identifer for a GStore::MessageStore message id.
41///
42 class GStore::MessageId
43{
44 public:
45 explicit MessageId( const std::string & ) ;
46 ///< Constructor.
47
48 static MessageId none() ;
49 ///< Returns an in-valid() id.
50
51 bool valid() const ;
52 ///< Returns true if valid.
53
54 std::string str() const ;
55 ///< Returns the id string.
56
57 public:
58 explicit MessageId( int ) = delete ;
59
60 private:
61 MessageId() = default ;
62
63 private:
64 std::string m_s ;
65} ;
66
67//| \class GStore::MessageStore
68/// A class which allows SMTP messages to be stored and retrieved.
69///
70/// \see GStore::NewMessage, GStore::StoredMessage, GStore::ProtocolMessage
71///
72 class GStore::MessageStore
73{
74 public:
75 enum class AddressStyle
76 {
77 Invalid , // control characters or invalid UTF-8 encoding or invalid IDN
78 Ascii , // printable ASCII mailbox and domain (RFC-5321 4.1.2)
79 Utf8Mailbox , // UTF-8 mailbox, ASCII domain
80 Utf8Domain , // ASCII mailbox, UTF-8 domain (and valid IDN)
81 Utf8Both // UTF-8 mailbox, UTF-8 domain (and valid IDN)
82 } ;
83 struct SmtpInfo /// Information on the SMTP options used when submitted.
84 {
85 std::string auth ; // AUTH=
86 std::string body ; // BODY=
87 AddressStyle address_style {AddressStyle::Ascii} ;
88 } ;
89 enum class BodyType
90 {
91 Unknown = -1 ,
92 SevenBit ,
93 EightBitMime , // RFC-1652
94 BinaryMime // RFC-3030
95 } ;
96 struct Iterator /// A base class for GStore::MessageStore iterators.
97 {
98 virtual std::unique_ptr<StoredMessage> next() = 0 ;
99 ///< Returns the next stored message or a null pointer.
100
101 virtual ~Iterator() = default ;
102 ///< Destructor.
103 } ;
104
105 virtual ~MessageStore() = default ;
106 ///< Destructor.
107
108 virtual std::unique_ptr<NewMessage> newMessage( const std::string & from ,
109 const SmtpInfo & smtp_info , const std::string & from_auth_out ) = 0 ;
110 ///< Creates a new message.
111
112 virtual bool empty() const = 0 ;
113 ///< Returns true if the message store is empty.
114
115 virtual std::string location( const MessageId & ) const = 0 ;
116 ///< Returns the location of the given message.
117
118 virtual std::unique_ptr<StoredMessage> get( const MessageId & id ) = 0 ;
119 ///< Pulls the specified message out of the store. Throws
120 ///< execptions on error.
121
122 virtual std::unique_ptr<Iterator> iterator( bool lock ) = 0 ;
123 ///< Returns an iterator for stored messages.
124 ///<
125 ///< If 'lock' is true then stored messages returned by the
126 ///< iterator are locked. They can then be deleted by
127 ///< StoredMessage::destroy() once they have been fully
128 ///< processed.
129
130 virtual std::vector<MessageId> ids() = 0 ;
131 ///< Returns a list of spooled message ids (excluding new or
132 ///< locked messages).
133
134 virtual std::vector<MessageId> failures() = 0 ;
135 ///< Returns a list of failed message ids.
136
137 virtual void unfailAll() = 0 ;
138 ///< Unfails all failed messages.
139
140 virtual void rescan() = 0 ;
141 ///< Requests that a messageStoreRescanSignal() is emitted.
142
143 virtual void updated() = 0 ;
144 ///< Called by associated classes to indicate that the
145 ///< store has changed. Implementations must cause the
146 ///< messageStoreUpdateSignal() signal to be emitted.
147
148 virtual G::Slot::Signal<> & messageStoreUpdateSignal() noexcept = 0 ;
149 ///< Provides a signal which is emitted when something might
150 ///< have changed in the store.
151
152 virtual G::Slot::Signal<> & messageStoreRescanSignal() noexcept = 0 ;
153 ///< Provides a signal which is emitted when rescan()
154 ///< is called.
155
156 static AddressStyle addressStyle( std::string_view address ) ;
157 ///< Parses an address to determine whether it has ASCII or
158 ///< UTF-8 parts. See also RFC-5198.
159} ;
160
161namespace GStore
162{
163 std::unique_ptr<StoredMessage> operator++( std::shared_ptr<MessageStore::Iterator> & iter ) ;
164}
165
166 inline GStore::MessageId::MessageId( const std::string & s ) : m_s(s) {}
167 inline GStore::MessageId GStore::MessageId::none() { return {} ; }
168 inline std::string GStore::MessageId::str() const { return m_s ; }
169 inline bool GStore::MessageId::valid() const { return !m_s.empty() ; }
170
171#endif
GStore::MessageId
A somewhat opaque identifer for a GStore::MessageStore message id.
Definition: gmessagestore.h:43
GStore::MessageId::none
static MessageId none()
Returns an in-valid() id.
Definition: gmessagestore.h:167
GStore::MessageId::valid
bool valid() const
Returns true if valid.
Definition: gmessagestore.h:169
GStore::MessageId::str
std::string str() const
Returns the id string.
Definition: gmessagestore.h:168
GStore::MessageId::MessageId
MessageId(const std::string &)
Constructor.
Definition: gmessagestore.h:166
GStore::MessageStore
A class which allows SMTP messages to be stored and retrieved.
Definition: gmessagestore.h:73
GStore::MessageStore::iterator
virtual std::unique_ptr< Iterator > iterator(bool lock)=0
Returns an iterator for stored messages.
GStore::MessageStore::unfailAll
virtual void unfailAll()=0
Unfails all failed messages.
GStore::MessageStore::rescan
virtual void rescan()=0
Requests that a messageStoreRescanSignal() is emitted.
GStore::MessageStore::newMessage
virtual std::unique_ptr< NewMessage > newMessage(const std::string &from, const SmtpInfo &smtp_info, const std::string &from_auth_out)=0
Creates a new message.
GStore::MessageStore::ids
virtual std::vector< MessageId > ids()=0
Returns a list of spooled message ids (excluding new or locked messages).
GStore::MessageStore::~MessageStore
virtual ~MessageStore()=default
Destructor.
GStore::MessageStore::failures
virtual std::vector< MessageId > failures()=0
Returns a list of failed message ids.
GStore::MessageStore::addressStyle
static AddressStyle addressStyle(std::string_view address)
Parses an address to determine whether it has ASCII or UTF-8 parts.
Definition: gmessagestore.cpp:33
GStore::MessageStore::messageStoreRescanSignal
virtual G::Slot::Signal & messageStoreRescanSignal() noexcept=0
Provides a signal which is emitted when rescan() is called.
GStore::MessageStore::messageStoreUpdateSignal
virtual G::Slot::Signal & messageStoreUpdateSignal() noexcept=0
Provides a signal which is emitted when something might have changed in the store.
GStore::MessageStore::get
virtual std::unique_ptr< StoredMessage > get(const MessageId &id)=0
Pulls the specified message out of the store.
GStore::MessageStore::empty
virtual bool empty() const =0
Returns true if the message store is empty.
GStore::MessageStore::updated
virtual void updated()=0
Called by associated classes to indicate that the store has changed.
GStore::MessageStore::location
virtual std::string location(const MessageId &) const =0
Returns the location of the given message.
gexception.h
gpath.h
gslot.h
gstringarray.h
GStore
Message store classes.
Definition: genvelope.cpp:30
G
Low-level classes.
Definition: garg.h:36
std
STL namespace.
GStore::MessageStore::Iterator
A base class for GStore::MessageStore iterators.
Definition: gmessagestore.h:97
GStore::MessageStore::Iterator::~Iterator
virtual ~Iterator()=default
Destructor.
GStore::MessageStore::Iterator::next
virtual std::unique_ptr< StoredMessage > next()=0
Returns the next stored message or a null pointer.
GStore::MessageStore::SmtpInfo
Information on the SMTP options used when submitted.
Definition: gmessagestore.h:84
G::Slot::Signal
A slot holder, with connect() and emit() methods.
Definition: gslot.h:184