E-MailRelay

- Main Page
- Namespaces
- Classes
- Files

- File List
- File Members

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 ///
53 class GNet::SocketProtocol
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
61 SocketProtocol( EventHandler & , ExceptionHandler & , Sink & ,
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 ///
134 class GNet::SocketProtocolSink
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
GNet::SocketProtocol::readEvent
void readEvent()
Called on receipt of a read event.
Definition: gsocketprotocol.cpp:750
GNet
Network classes.
Definition: gaddress.h:29
GNet::SocketProtocol::otherEvent
void otherEvent(EventHandler::Reason)
Called on receipt of an 'other' event.
Definition: gsocketprotocol.cpp:760
GNet::SocketProtocolSink::onData
virtual void onData(const char *, size_t)=0
Called when data is read from the socket.
GNet::SocketProtocolSink::~SocketProtocolSink
virtual ~SocketProtocolSink()
Destructor.
Definition: gsocketprotocol.cpp:807
GNet::SocketProtocolSink::onSecure
virtual void onSecure(const std::string &peer_certificate)=0
Called once the secure socket protocol has been successfully negotiated.
GNet::SocketProtocolImp
A pimple-pattern implementation class used by GNet::SocketProtocol.
Definition: gsocketprotocol.cpp:45
GNet::ExceptionHandler
An abstract interface for handling exceptions thrown out of event-loop callbacks (socket events...
Definition: gexceptionhandler.h:44
GNet::SocketProtocol::peerCertificate
std::string peerCertificate() const
Returns the peer's TLS/SSL certificate or the empty string.
Definition: gsocketprotocol.cpp:795
GNet::StreamSocket
A derivation of GNet::Socket for a stream socket.
Definition: gsocket.h:246
GNet::SocketProtocol::~SocketProtocol
~SocketProtocol()
Destructor.
Definition: gsocketprotocol.cpp:745
GNet::SocketProtocol::secureAccept
void secureAccept()
Waits for the TLS/SSL handshake protocol, acting as a server.
Definition: gsocketprotocol.cpp:790
GNet::SocketProtocol::send
bool send(const std::string &data, size_t offset=0U)
Sends data.
Definition: gsocketprotocol.cpp:765
GNet::EventHandler
A base class for classes that handle asynchronous events from the event loop.
Definition: geventhandler.h:47
gsocket.h
gexception.h
GNet::SocketProtocol::secureAcceptCapable
static bool secureAcceptCapable()
Returns true if the implementation supports TLS/SSL and a "server" profile has been configured...
Definition: gsocketprotocol.cpp:785
GNet::SocketProtocol::secureConnect
void secureConnect()
Initiates the TLS/SSL handshake, acting as a client.
Definition: gsocketprotocol.cpp:780
GNet::SocketProtocol::SocketProtocol
SocketProtocol(EventHandler &, ExceptionHandler &, Sink &, StreamSocket &, unsigned int secure_connection_timeout)
Constructor. The references are kept.
Definition: gsocketprotocol.cpp:739
GNet::SocketProtocol::secureConnectCapable
static bool secureConnectCapable()
Returns true if the implementation supports TLS/SSL and a "client" profile has been configured...
Definition: gsocketprotocol.cpp:775
GNet::SocketProtocolSink
An interface used by GNet::SocketProtocol to deliver data from a socket.
Definition: gsocketprotocol.h:134
GNet::SocketProtocol
An interface for implementing a low-level TLS/SSL protocol layer on top of a connected non-blocking s...
Definition: gsocketprotocol.h:53
GNet::SocketProtocol::setReadBufferSize
static void setReadBufferSize(size_t n)
Sets the read buffer size. Used in testing.
Definition: gsocketprotocol.cpp:800
GNet::SocketProtocol::writeEvent
bool writeEvent()
Called on receipt of a write event.
Definition: gsocketprotocol.cpp:755