E-MailRelay
gsocketprotocol.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 gsocketprotocol.h
19 ///
20 
21 #ifndef G_NET_SOCKET_PROTOCOL__H
22 #define G_NET_SOCKET_PROTOCOL__H
23 
24 #include "gdef.h"
25 #include "gsocket.h"
26 #include "gexception.h"
27 #include <string>
28 #include <vector>
29 #include <utility>
30 
31 namespace GNet
32 {
33  class SocketProtocol ;
34  class SocketProtocolImp ;
35  class SocketProtocolSink ;
36 }
37 
38 /// \class GNet::SocketProtocol
39 /// An interface for implementing a low-level TLS/SSL protocol layer on top
40 /// of a connected non-blocking socket.
41 ///
42 /// Provides send() to send data, and onData() in a callback interface to
43 /// receive data. The TLS/SSL socket protocol session is negotiated with the
44 /// peer by calling secureConnect() or secureAccept(), and thereafter the
45 /// interface is half-duplex. If no TLS/SSL session is in effect ('raw') then
46 /// the protocol layer is transparent down to the socket.
47 ///
48 /// The interface has read-event and write-event handlers that should be
49 /// called when events are detected on the socket file descriptor. In raw
50 /// mode the read handler delivers data via the onData() callback interface
51 /// and the write handler is used to flush the output pipeline.
52 ///
54 {
55 public:
56  typedef SocketProtocolSink Sink ;
57  G_EXCEPTION_CLASS( ReadError , "peer disconnected" ) ;
58  G_EXCEPTION( SendError , "peer disconnected" ) ;
59  G_EXCEPTION( SecureConnectionTimeout , "secure connection timeout" ) ;
60 
62  StreamSocket & , unsigned int secure_connection_timeout ) ;
63  ///< Constructor. The references are kept.
64 
65  ~SocketProtocol() ;
66  ///< Destructor.
67 
68  void readEvent() ;
69  ///< Called on receipt of a read event. Delivers data via the sink
70  ///< interface. Throws ReadError on error.
71 
72  bool writeEvent() ;
73  ///< Called on receipt of a write event. Sends more pending data
74  ///< down the connection. Returns true if all pending data was
75  ///< sent. Throws SendError on error.
76 
77  void otherEvent( EventHandler::Reason ) ;
78  ///< Called on receipt of an 'other' event. Throws an exception.
79  ///< For simple socket-close events (on Windows) the read queue
80  ///< is processed (see SocketProtocolSink::onData()) and the
81  ///< socket is shutdown() before the exception is thrown.
82 
83  bool send( const std::string & data , size_t offset = 0U ) ;
84  ///< Sends data. Returns false if flow control asserted before
85  ///< all the data is sent. Returns true if all the data was sent,
86  ///< or if the data passed in (taking the offset into account)
87  ///< is empty. Throws SendError on error.
88  ///<
89  ///< If flow control is asserted then the socket write-event
90  ///< handler is installed and send() returns false. Unsent
91  ///< portions of the data string are copied internally. When
92  ///< the subsequent write-event is triggered the user should
93  ///< call writeEvent(). There should be no new calls to send()
94  ///< until writeEvent() returns true.
95 
96  bool send( const std::vector<std::pair<const char *,size_t> > & data ) ;
97  ///< Overload to send data using scatter-gather segments.
98  ///< If false is returned then segment data pointers must
99  ///< stay valid until writeEvent() returns true.
100 
101  static bool secureConnectCapable() ;
102  ///< Returns true if the implementation supports TLS/SSL and a
103  ///< "client" profile has been configured. See also GSsl::enabledAs().
104 
105  void secureConnect() ;
106  ///< Initiates the TLS/SSL handshake, acting as a client.
107 
108  static bool secureAcceptCapable() ;
109  ///< Returns true if the implementation supports TLS/SSL and a
110  ///< "server" profile has been configured. See also GSsl::enabledAs().
111 
112  void secureAccept() ;
113  ///< Waits for the TLS/SSL handshake protocol, acting as a server.
114 
115  std::string peerCertificate() const ;
116  ///< Returns the peer's TLS/SSL certificate or the empty
117  ///< string.
118 
119  static void setReadBufferSize( size_t n ) ;
120  ///< Sets the read buffer size. Used in testing.
121 
122 private:
123  SocketProtocol( const SocketProtocol & ) ;
124  void operator=( const SocketProtocol & ) ;
125 
126 private:
127  SocketProtocolImp * m_imp ;
128 } ;
129 
130 /// \class GNet::SocketProtocolSink
131 /// An interface used by GNet::SocketProtocol
132 /// to deliver data from a socket.
133 ///
135 {
136 public:
137  virtual ~SocketProtocolSink() ;
138  ///< Destructor.
139 
140 protected:
141  friend class SocketProtocolImp ;
142 
143  virtual void onData( const char * , size_t ) = 0 ;
144  ///< Called when data is read from the socket.
145 
146  virtual void onSecure( const std::string & peer_certificate ) = 0 ;
147  ///< Called once the secure socket protocol has
148  ///< been successfully negotiated.
149 } ;
150 
151 #endif
void readEvent()
Called on receipt of a read event.
Network classes.
Definition: gaddress.h:29
void otherEvent(EventHandler::Reason)
Called on receipt of an 'other' event.
virtual void onData(const char *, size_t)=0
Called when data is read from the socket.
virtual ~SocketProtocolSink()
Destructor.
virtual void onSecure(const std::string &peer_certificate)=0
Called once the secure socket protocol has been successfully negotiated.
A pimple-pattern implementation class used by GNet::SocketProtocol.
An abstract interface for handling exceptions thrown out of event-loop callbacks (socket events...
std::string peerCertificate() const
Returns the peer's TLS/SSL certificate or the empty string.
A derivation of GNet::Socket for a stream socket.
Definition: gsocket.h:246
~SocketProtocol()
Destructor.
void secureAccept()
Waits for the TLS/SSL handshake protocol, acting as a server.
bool send(const std::string &data, size_t offset=0U)
Sends data.
A base class for classes that handle asynchronous events from the event loop.
Definition: geventhandler.h:47
static bool secureAcceptCapable()
Returns true if the implementation supports TLS/SSL and a "server" profile has been configured...
void secureConnect()
Initiates the TLS/SSL handshake, acting as a client.
SocketProtocol(EventHandler &, ExceptionHandler &, Sink &, StreamSocket &, unsigned int secure_connection_timeout)
Constructor. The references are kept.
static bool secureConnectCapable()
Returns true if the implementation supports TLS/SSL and a "client" profile has been configured...
An interface used by GNet::SocketProtocol to deliver data from a socket.
An interface for implementing a low-level TLS/SSL protocol layer on top of a connected non-blocking s...
static void setReadBufferSize(size_t n)
Sets the read buffer size. Used in testing.
bool writeEvent()
Called on receipt of a write event.