E-MailRelay

gmessagestore.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 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 "gstrings.h"
28#include "gpath.h"
29#include <memory>
30
31 namespace GSmtp
32{
33 class NewMessage ;
34 class StoredMessage ;
35 class MessageId ;
36 class MessageStore ;
37}
38
39//| \class GSmtp::MessageId
40/// A somewhat opaque identifer for a MessageStore message.
41///
42 class GSmtp::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 GSmtp::MessageStore
68/// A class which allows SMTP messages to be stored and retrieved.
69///
70/// \see GSmtp::NewMessage, GSmtp::StoredMessage, GSmtp::ProtocolMessage
71///
72 class GSmtp::MessageStore
73{
74 public:
75 struct Iterator /// A base class for GSmtp::MessageStore iterators.
76 {
77 virtual std::unique_ptr<StoredMessage> next() = 0 ;
78 ///< Returns the next stored message or a null pointer.
79
80 virtual ~Iterator() = default ;
81 ///< Destructor.
82 } ;
83
84 static G::Path defaultDirectory() ;
85 ///< Returns a default spool directory, such as "/var/spool/emailrelay".
86 ///< (Typically with an os-specific implementation.)
87
88 virtual ~MessageStore() = default ;
89 ///< Destructor.
90
91 virtual std::unique_ptr<NewMessage> newMessage( const std::string & from ,
92 const std::string & from_auth_in , const std::string & from_auth_out ) = 0 ;
93 ///< Creates a new message.
94
95 virtual bool empty() const = 0 ;
96 ///< Returns true if the message store is empty.
97
98 virtual std::string location( const MessageId & ) const = 0 ;
99 ///< Returns the location of the given message.
100
101 virtual std::unique_ptr<StoredMessage> get( const MessageId & ) = 0 ;
102 ///< Pulls the specified message out of the store. Throws
103 ///< execptions on error.
104 ///<
105 ///< As a side effect some stored messages may be marked as bad,
106 ///< or deleted (if they have no recipients).
107
108 virtual std::shared_ptr<Iterator> iterator( bool lock ) = 0 ;
109 ///< Returns an iterator for stored messages.
110 ///<
111 ///< If 'lock' is true then stored messages returned by the
112 ///< iterator are locked. They can then be deleted by
113 ///< StoredMessage::destroy() once they have been fully
114 ///< processed.
115 ///<
116 ///< If 'lock' is true invalid messages having no receipients
117 ///< are not returned by the iterator.
118 ///<
119 ///< If 'lock' is true then as a side effect of iteration some
120 ///< stored messages may be marked as bad, or get deleted
121 ///< if they have no recipients.
122
123 virtual std::shared_ptr<Iterator> failures() = 0 ;
124 ///< Returns an iterator for failed messages.
125
126 virtual void unfailAll() = 0 ;
127 ///< Causes messages marked as failed to be unmarked.
128
129 virtual void rescan() = 0 ;
130 ///< Requests that a messageStoreRescanSignal() is emitted.
131
132 virtual void updated() = 0 ;
133 ///< Called by associated classes to indicate that the
134 ///< store has changed. Implementations must cause the
135 ///< messageStoreUpdateSignal() signal to be emitted.
136
137 virtual G::Slot::Signal<> & messageStoreUpdateSignal() = 0 ;
138 ///< Provides a signal which is when something might
139 ///< have changed in the store.
140
141 virtual G::Slot::Signal<> & messageStoreRescanSignal() = 0 ;
142 ///< Provides a signal which is emitted when rescan()
143 ///< is called.
144} ;
145
146 namespace GSmtp
147{
148 std::unique_ptr<StoredMessage> operator++( std::shared_ptr<MessageStore::Iterator> & iter ) ;
149}
150
151 inline GSmtp::MessageId::MessageId( const std::string & s ) : m_s(s) {}
152 inline GSmtp::MessageId GSmtp::MessageId::none() { return MessageId() ; }
153 inline std::string GSmtp::MessageId::str() const { return m_s ; }
154 inline bool GSmtp::MessageId::valid() const { return !m_s.empty() ; }
155
156#endif
GSmtp::MessageId
A somewhat opaque identifer for a MessageStore message.
Definition: gmessagestore.h:43
GSmtp::MessageId::none
static MessageId none()
Returns an in-valid() id.
Definition: gmessagestore.h:152
GSmtp::MessageId::valid
bool valid() const
Returns true if valid.
Definition: gmessagestore.h:154
GSmtp::MessageId::MessageId
MessageId(const std::string &)
Constructor.
Definition: gmessagestore.h:151
GSmtp::MessageId::str
std::string str() const
Returns the id string.
Definition: gmessagestore.h:153
GSmtp::MessageStore
A class which allows SMTP messages to be stored and retrieved.
Definition: gmessagestore.h:73
GSmtp::MessageStore::rescan
virtual void rescan()=0
Requests that a messageStoreRescanSignal() is emitted.
GSmtp::MessageStore::empty
virtual bool empty() const =0
Returns true if the message store is empty.
GSmtp::MessageStore::failures
virtual std::shared_ptr< Iterator > failures()=0
Returns an iterator for failed messages.
GSmtp::MessageStore::defaultDirectory
static G::Path defaultDirectory()
Returns a default spool directory, such as "/var/spool/emailrelay".
Definition: gmessagestore_unix.cpp:30
GSmtp::MessageStore::messageStoreUpdateSignal
virtual G::Slot::Signal & messageStoreUpdateSignal()=0
Provides a signal which is when something might have changed in the store.
GSmtp::MessageStore::updated
virtual void updated()=0
Called by associated classes to indicate that the store has changed.
GSmtp::MessageStore::get
virtual std::unique_ptr< StoredMessage > get(const MessageId &)=0
Pulls the specified message out of the store.
GSmtp::MessageStore::unfailAll
virtual void unfailAll()=0
Causes messages marked as failed to be unmarked.
GSmtp::MessageStore::location
virtual std::string location(const MessageId &) const =0
Returns the location of the given message.
GSmtp::MessageStore::messageStoreRescanSignal
virtual G::Slot::Signal & messageStoreRescanSignal()=0
Provides a signal which is emitted when rescan() is called.
GSmtp::MessageStore::newMessage
virtual std::unique_ptr< NewMessage > newMessage(const std::string &from, const std::string &from_auth_in, const std::string &from_auth_out)=0
Creates a new message.
GSmtp::MessageStore::iterator
virtual std::shared_ptr< Iterator > iterator(bool lock)=0
Returns an iterator for stored messages.
GSmtp::MessageStore::~MessageStore
virtual ~MessageStore()=default
Destructor.
G::Path
A Path object represents a file system path.
Definition: gpath.h:72
gexception.h
gpath.h
gslot.h
gstrings.h
GSmtp
SMTP and message-store classes.
Definition: gadminserver.h:39
GSmtp::MessageStore::Iterator
A base class for GSmtp::MessageStore iterators.
Definition: gmessagestore.h:76
GSmtp::MessageStore::Iterator::next
virtual std::unique_ptr< StoredMessage > next()=0
Returns the next stored message or a null pointer.
GSmtp::MessageStore::Iterator::~Iterator
virtual ~Iterator()=default
Destructor.
G::Slot::Signal
A slot holder, with connect() and emit() methods.
Definition: gslot.h:157