E-MailRelay
gheapclient.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 gheapclient.h
19 ///
20 
21 #ifndef G_NET_HEAP_CLIENT__H
22 #define G_NET_HEAP_CLIENT__H
23 
24 #include "gdef.h"
25 #include "gsimpleclient.h"
26 #include "gtimer.h"
27 
28 namespace GNet
29 {
30  class HeapClient ;
31 }
32 
33 /// \class GNet::HeapClient
34 /// A SimpleClient class for client objects that manage their own lifetime on
35 /// the heap.
36 ///
37 /// HeapClients are instantiated on the heap and should be deleted by calling
38 /// their doDelete() method. The doDelete() implementation starts a zero-length
39 /// timer which does "delete this" when it expires, so it is safe to call
40 /// doDelete() from within event callbacks.
41 ///
42 /// This class automatically starts connecting after construction using a
43 /// zero-length timer, so there is no need to call the base class's connect()
44 /// method.
45 ///
46 /// When the event loop delivers an event callback to a HeapClient and the
47 /// HeapClient throws a std::exception back up to the event loop the event loop
48 /// calls the HeapClient again via onException(). The implementation of
49 /// onException() in HeapClient causes the HeapClient to self-destruct.
50 /// As a result, the client code can just throw an exception to terminate
51 /// the connection and delete itself.
52 ///
54 {
55 public:
56  explicit HeapClient( const Location & remote_info ,
57  bool bind_local_address = false ,
58  const Address & local_address = Address::defaultAddress() ,
59  bool sync_dns = synchronousDnsDefault() ,
60  unsigned int secure_connection_timeout = 0U ) ;
61  ///< Constructor. All instances must be on the heap.
62  ///< Initiates the connection via a zero-length timer.
63 
64  void doDelete( const std::string & reason ) ;
65  ///< Calls onDelete() and then does a delayed "delete this".
66 
67 protected:
68  virtual ~HeapClient() ;
69  ///< Destructor.
70 
71  void finish() ;
72  ///< Indicates that the last data has been sent and the client
73  ///< is expecting a peer disconnect. The subsequent onDelete()
74  ///< callback will have an empty reason string. The caller
75  ///< should also consider using Socket::shutdown().
76 
77  virtual void onDelete( const std::string & reason ) = 0 ;
78  ///< Called just before deletion.
79 
80  virtual void onDeleteImp( const std::string & reason ) ;
81  ///< An alternative to onDelete() for derived classes in the
82  ///< GNet namespace (in practice GNet::Client). Gets called
83  ///< before onDelete(). The default implementation does nothing.
84 
85  virtual void onConnecting() ;
86  ///< Called just before the connection is initiated.
87  ///< Overridable. The default implementation does nothing.
88 
89  virtual void onException( std::exception & ) g__final override ;
90  ///< Override from GNet::ExceptionHandler.
91  ///< Calls doDelete(). Note that the exception
92  ///< text is available via onDelete().
93 
94 private:
95  HeapClient( const HeapClient & ) ;
96  void operator=( const HeapClient & ) ;
97  void onConnectionTimeout() ;
98  void onDeletionTimeout() ;
99  void doDeleteThis() ;
100 
101 private:
102  GNet::Timer<HeapClient> m_connect_timer ;
103  GNet::Timer<HeapClient> m_delete_timer ;
104  bool m_finished ;
105 } ;
106 
107 #endif
virtual ~HeapClient()
Destructor.
Definition: gheapclient.cpp:36
void finish()
Indicates that the last data has been sent and the client is expecting a peer disconnect.
Definition: gheapclient.cpp:87
A class for making an outgoing connection to a remote server, with support for socket-level protocols...
Definition: gsimpleclient.h:61
Network classes.
Definition: gaddress.h:29
virtual void onDeleteImp(const std::string &reason)
An alternative to onDelete() for derived classes in the GNet namespace (in practice GNet::Client)...
Definition: gheapclient.cpp:79
HeapClient(const Location &remote_info, bool bind_local_address=false, const Address &local_address=Address::defaultAddress(), bool sync_dns=synchronousDnsDefault(), unsigned int secure_connection_timeout=0U)
Constructor.
Definition: gheapclient.cpp:25
The GNet::Address class encapsulates a TCP/UDP transport address.
Definition: gaddress.h:54
virtual void onException(std::exception &) g__final override
Override from GNet::ExceptionHandler.
Definition: gheapclient.cpp:71
void doDelete(const std::string &reason)
Calls onDelete() and then does a delayed "delete this".
Definition: gheapclient.cpp:58
An abstract interface for handling exceptions thrown out of event-loop callbacks (socket events...
A class that holds a host/service name pair and the preferred address family (if any), and also the results of a name-to-address lookup, ie.
Definition: glocation.h:50
virtual void onDelete(const std::string &reason)=0
Called just before deletion.
static Address defaultAddress()
Returns a default address, being the IPv4 wildcard address with a zero port number.
A SimpleClient class for client objects that manage their own lifetime on the heap.
Definition: gheapclient.h:53
static bool synchronousDnsDefault()
Returns true if DNS queries should normally be synchronous on this platform.
A timer class template in which the timeout is delivered to the specified method. ...
Definition: gtimer.h:115
virtual void onConnecting()
Called just before the connection is initiated.
Definition: gheapclient.cpp:83