E-MailRelay
gfilestore.h
Go to the documentation of this file.
1 //
2 // Copyright (C) 2001-2018 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 gfilestore.h
19 ///
20 
21 #ifndef G_SMTP_FILE_STORE_H
22 #define G_SMTP_FILE_STORE_H
23 
24 #include "gdef.h"
25 #include "gsmtp.h"
26 #include "gmessagestore.h"
27 #include "gdatetime.h"
28 #include "gexception.h"
29 #include "gprocess.h"
30 #include "gnoncopyable.h"
31 #include "gslot.h"
32 #include "groot.h"
33 #include "gpath.h"
34 #include <memory>
35 #include <string>
36 
37 namespace GSmtp
38 {
39  class FileStore ;
40  class FileReader ;
41  class FileWriter ;
42  class DirectoryReader ;
43 }
44 
45 /// \class GSmtp::FileStore
46 /// A concrete implementation of the MessageStore interface dealing
47 /// in paired flat files.
48 ///
49 /// The implementation puts separate envelope and content files
50 /// in the spool directory. The content file is written first.
51 /// The presence of a matching envelope file is used to indicate
52 /// that the content file is valid and that it has been commited
53 /// to the care of the SMTP system for delivery.
54 ///
55 /// Passes out unique sequence numbers, filesystem paths and
56 /// i/o streams to NewMessageImp.
57 ///
59 {
60 public:
61  G_EXCEPTION( InvalidDirectory , "invalid spool directory" ) ;
62  G_EXCEPTION( GetError , "error reading specific message" ) ;
63 
64  FileStore( const G::Path & dir , bool optimise = false , unsigned long max_size = 0UL ) ;
65  ///< Constructor. Throws an exception if the storage directory
66  ///< is invalid.
67  ///<
68  ///< If the optimise flag is set then the implementation of
69  ///< empty() will be efficient for an empty filestore
70  ///< (ignoring failed and local-delivery messages). This
71  ///< might be useful for applications in which the main
72  ///< event loop is used to check for pending jobs. The
73  ///< disadvantage is that this process will not be
74  ///< sensititive to messages deposited into its spool
75  ///< directory by other processes.
76 
77  unsigned long newSeq() ;
78  ///< Hands out a new non-zero sequence number.
79 
80  unique_ptr<std::ostream> stream( const G::Path & path ) ;
81  ///< Returns a stream to the given content.
82 
83  G::Path contentPath( unsigned long seq ) const ;
84  ///< Returns the path for a content file.
85 
86  G::Path envelopePath( unsigned long seq ) const ;
87  ///< Returns the path for an envelope file.
88 
89  G::Path envelopeWorkingPath( unsigned long seq ) const ;
90  ///< Returns the path for an envelope file
91  ///< which is in the process of being written.
92 
93  virtual bool empty() const override ;
94  ///< Override from GSmtp::MessageStore.
95 
96  virtual unique_ptr<StoredMessage> get( unsigned long id ) override ;
97  ///< Override from GSmtp::MessageStore.
98 
99  virtual MessageStore::Iterator iterator( bool lock ) override ;
100  ///< Override from GSmtp::MessageStore.
101 
102  virtual MessageStore::Iterator failures() override ;
103  ///< Override from GSmtp::MessageStore.
104 
105  virtual unique_ptr<NewMessage> newMessage( const std::string & from ,
106  const std::string & from_auth_in , const std::string & from_auth_out ) override ;
107  ///< Override from GSmtp::MessageStore.
108 
109  static std::string x() ;
110  ///< Returns the prefix for envelope header lines.
111 
112  static std::string format( int generation = 0 ) ;
113  ///< Returns an identifier for the storage format implemented
114  ///< by this class, or some older generation of it (eg. -1).
115 
116  static bool knownFormat( const std::string & format ) ;
117  ///< Returns true if the storage format string is
118  ///< recognised and supported for reading.
119 
120  virtual void rescan() override ;
121  ///< Override from GSmtp::MessageStore.
122 
123  virtual void unfailAll() override ;
124  ///< Override from GSmtp::MessageStore.
125 
126  virtual void updated() override ;
127  ///< Override from GSmtp::MessageStore.
128 
129  virtual G::Slot::Signal0 & messageStoreUpdateSignal() override ;
130  ///< Override from GSmtp::MessageStore.
131 
132  virtual G::Slot::Signal0 & messageStoreRescanSignal() override ;
133  ///< Override from GSmtp::MessageStore.
134 
135 private:
136  static void checkPath( const G::Path & dir ) ;
137  G::Path fullPath( const std::string & filename ) const ;
138  std::string filePrefix( unsigned long seq ) const ;
139  std::string getline( std::istream & ) const ;
140  std::string value( const std::string & ) const ;
141  static const std::string & crlf() ;
142  bool emptyCore() const ;
143  void createTestMessage() ;
144  void clearAll() ;
145 
146 private:
147  unsigned long m_seq ;
148  G::Path m_dir ;
149  bool m_optimise ;
150  bool m_empty ; // mutable
151  bool m_rescan ;
152  unsigned long m_max_size ;
153  unsigned long m_pid_modifier ;
154  G::Slot::Signal0 m_update_signal ;
155  G::Slot::Signal0 m_rescan_signal ;
156 } ;
157 
158 /// \class GSmtp::FileReader
159 /// Used by GSmtp::FileStore, GSmtp::NewFile and
160 /// GSmtp::StoredFile to claim read permissions for
161 /// reading a file.
162 /// \see G::Root
163 ///
164 class GSmtp::FileReader : private G::Root
165 {
166 public:
167  FileReader() ;
168  ///< Default constructor. Switches identity for
169  ///< reading a file.
170 
171  ~FileReader() ;
172  ///< Destructor. Switches identity back.
173 } ;
174 
175 /// \class GSmtp::DirectoryReader
176 /// Used by GSmtp::FileStore, GSmtp::NewFile and
177 /// GSmtp::StoredFile to claim read permissions for
178 /// reading a directory.
179 /// \see G::Root
180 ///
182 {
183 public:
184  DirectoryReader() ;
185  ///< Default constructor. Switches identity for
186  ///< reading a directory.
187 
188  ~DirectoryReader() ;
189  ///< Destructor. Switches identity back.
190 } ;
191 
192 /// \class GSmtp::FileWriter
193 /// Used by GSmtp::FileStore, GSmtp::NewFile and
194 /// GSmtp::StoredFile to claim write permissions.
195 /// \see G::Root
196 ///
197 class GSmtp::FileWriter : private G::Root , private G::Process::Umask
198 {
199 public:
200  FileWriter() ;
201  ///< Default constructor. Switches identity for
202  ///< writing a file.
203 
204  ~FileWriter() ;
205  ///< Destructor. Switches identity back.
206 } ;
207 
208 #endif
209 
G::Path contentPath(unsigned long seq) const
Returns the path for a content file.
Definition: gfilestore.cpp:182
static std::string format(int generation=0)
Returns an identifier for the storage format implemented by this class, or some older generation of i...
Definition: gfilestore.cpp:130
SMTP and message-store classes.
Definition: gadminserver.h:39
static std::string x()
Returns the prefix for envelope header lines.
Definition: gfilestore.cpp:125
FileWriter()
Default constructor.
Definition: gfilestore.cpp:366
virtual G::Slot::Signal0 & messageStoreUpdateSignal() override
Override from GSmtp::MessageStore.
Definition: gfilestore.cpp:288
Used by GSmtp::FileStore, GSmtp::NewFile and GSmtp::StoredFile to claim read permissions for reading ...
Definition: gfilestore.h:181
A class which acquires the process's special privileges on construction and releases them on destruct...
Definition: groot.h:49
virtual G::Slot::Signal0 & messageStoreRescanSignal() override
Override from GSmtp::MessageStore.
Definition: gfilestore.cpp:293
Used by GSmtp::FileStore, GSmtp::NewFile and GSmtp::StoredFile to claim write permissions.
Definition: gfilestore.h:197
~DirectoryReader()
Destructor. Switches identity back.
Definition: gfilestore.cpp:360
virtual MessageStore::Iterator failures() override
Override from GSmtp::MessageStore.
Definition: gfilestore.cpp:248
unique_ptr< std::ostream > stream(const G::Path &path)
Returns a stream to the given content.
Definition: gfilestore.cpp:175
virtual MessageStore::Iterator iterator(bool lock) override
Override from GSmtp::MessageStore.
Definition: gfilestore.cpp:243
A class which allows SMTP messages to be stored and retrieved.
Definition: gmessagestore.h:43
FileStore(const G::Path &dir, bool optimise=false, unsigned long max_size=0UL)
Constructor.
Definition: gfilestore.cpp:105
~FileReader()
Destructor. Switches identity back.
Definition: gfilestore.cpp:350
virtual void updated() override
Override from GSmtp::MessageStore.
Definition: gfilestore.cpp:282
virtual unique_ptr< NewMessage > newMessage(const std::string &from, const std::string &from_auth_in, const std::string &from_auth_out) override
Override from GSmtp::MessageStore.
Definition: gfilestore.cpp:275
A signal class for zero-parameter callbacks.
Definition: gslot.h:193
~FileWriter()
Destructor. Switches identity back.
Definition: gfilestore.cpp:372
A concrete implementation of the MessageStore interface dealing in paired flat files.
Definition: gfilestore.h:58
G::Path envelopePath(unsigned long seq) const
Returns the path for an envelope file.
Definition: gfilestore.cpp:187
DirectoryReader()
Default constructor.
Definition: gfilestore.cpp:356
virtual void unfailAll() override
Override from GSmtp::MessageStore.
Definition: gfilestore.cpp:303
static bool knownFormat(const std::string &format)
Returns true if the storage format string is recognised and supported for reading.
Definition: gfilestore.cpp:140
unsigned long newSeq()
Hands out a new non-zero sequence number.
Definition: gfilestore.cpp:212
Used by GSmtp::FileStore, GSmtp::NewFile and GSmtp::StoredFile to claim read permissions for reading ...
Definition: gfilestore.h:164
A Path object represents a file system path.
Definition: gpath.h:72
FileReader()
Default constructor.
Definition: gfilestore.cpp:346
G::Path envelopeWorkingPath(unsigned long seq) const
Returns the path for an envelope file which is in the process of being written.
Definition: gfilestore.cpp:192
virtual void rescan() override
Override from GSmtp::MessageStore.
Definition: gfilestore.cpp:298
virtual bool empty() const override
Override from GSmtp::MessageStore.
Definition: gfilestore.cpp:220
An iterator class for GSmtp::MessageStore.
Definition: gmessagestore.h:55