E-MailRelay
Public Types | Public Member Functions | Static Public Member Functions | List of all members
GNet::SocketProtocol Class Reference

An interface for implementing a low-level TLS/SSL protocol layer on top of a connected non-blocking socket. More...

#include <gsocketprotocol.h>

Public Types

using Sink = SocketProtocolSink
 

Public Member Functions

 SocketProtocol (EventHandler &, ExceptionSink, Sink &, StreamSocket &, unsigned int secure_connection_timeout)
 Constructor. The references are kept. More...
 
 ~SocketProtocol ()
 Destructor.
 
void readEvent ()
 Called on receipt of a read event. More...
 
bool writeEvent ()
 Called on receipt of a write event. More...
 
void otherEvent (EventHandler::Reason)
 Called on receipt of an 'other' event. More...
 
bool send (const std::string &data, std::size_t offset=0U)
 Sends data. More...
 
bool send (const std::vector< G::string_view > &data, std::size_t offset=0U)
 Overload to send data using scatter-gather segments. More...
 
void shutdown ()
 Initiates a TLS-close if secure, together with a Socket::shutdown(1). More...
 
void secureConnect ()
 Initiates the TLS/SSL handshake, acting as a client. More...
 
void secureAccept ()
 Waits for the TLS/SSL handshake protocol, acting as a server. More...
 
bool secure () const
 Returns true if the connection is currently secure, ie. More...
 
std::string peerCertificate () const
 Returns the peer's TLS/SSL certificate or the empty string. More...
 
 SocketProtocol (const SocketProtocol &)=delete
 
 SocketProtocol (SocketProtocol &&)=delete
 
void operator= (const SocketProtocol &)=delete
 
void operator= (SocketProtocol &&)=delete
 

Static Public Member Functions

static bool secureConnectCapable ()
 Returns true if the implementation supports TLS/SSL and a "client" profile has been configured. More...
 
static bool secureAcceptCapable ()
 Returns true if the implementation supports TLS/SSL and a "server" profile has been configured. More...
 
static void setReadBufferSize (std::size_t n)
 Sets the read buffer size. Used in testing. More...
 

Detailed Description

An interface for implementing a low-level TLS/SSL protocol layer on top of a connected non-blocking socket.

Provides send() to send data, and onData() in a callback interface to receive data. The TLS/SSL socket protocol session is negotiated with the peer by calling secureConnect() or secureAccept(), and thereafter the interface is half-duplex. If no TLS/SSL session is in effect ('raw') then the protocol layer is transparent down to the socket.

The interface has read-event and write-event handlers that should be called when events are detected on the socket file descriptor. In raw mode the read handler delivers data via the onData() callback interface and the write handler is used to flush the output pipeline.

Definition at line 55 of file gsocketprotocol.h.

Member Typedef Documentation

◆ Sink

Definition at line 58 of file gsocketprotocol.h.

Constructor & Destructor Documentation

◆ SocketProtocol()

GNet::SocketProtocol::SocketProtocol ( EventHandler handler,
ExceptionSink  es,
Sink sink,
StreamSocket socket,
unsigned int  secure_connection_timeout 
)

Constructor. The references are kept.

Definition at line 755 of file gsocketprotocol.cpp.

Member Function Documentation

◆ otherEvent()

void GNet::SocketProtocol::otherEvent ( EventHandler::Reason  reason)

Called on receipt of an 'other' event.

Throws an exception. For simple socket-close events (on Windows) the read queue is processed (see SocketProtocolSink::onData()) and the socket is shutdown() before the exception is thrown.

Definition at line 774 of file gsocketprotocol.cpp.

◆ peerCertificate()

std::string GNet::SocketProtocol::peerCertificate ( ) const

Returns the peer's TLS/SSL certificate or the empty string.

Definition at line 814 of file gsocketprotocol.cpp.

◆ readEvent()

void GNet::SocketProtocol::readEvent ( )

Called on receipt of a read event.

Delivers data via the sink interface. Throws ReadError on error.

Definition at line 764 of file gsocketprotocol.cpp.

◆ secure()

bool GNet::SocketProtocol::secure ( ) const

Returns true if the connection is currently secure, ie.

after onSecure().

◆ secureAccept()

void GNet::SocketProtocol::secureAccept ( )

Waits for the TLS/SSL handshake protocol, acting as a server.

Definition at line 809 of file gsocketprotocol.cpp.

◆ secureAcceptCapable()

bool GNet::SocketProtocol::secureAcceptCapable ( )
static

Returns true if the implementation supports TLS/SSL and a "server" profile has been configured.

See also GSsl::enabledAs().

Definition at line 804 of file gsocketprotocol.cpp.

◆ secureConnect()

void GNet::SocketProtocol::secureConnect ( )

Initiates the TLS/SSL handshake, acting as a client.

Definition at line 799 of file gsocketprotocol.cpp.

◆ secureConnectCapable()

bool GNet::SocketProtocol::secureConnectCapable ( )
static

Returns true if the implementation supports TLS/SSL and a "client" profile has been configured.

See also GSsl::enabledAs().

Definition at line 794 of file gsocketprotocol.cpp.

◆ send() [1/2]

bool GNet::SocketProtocol::send ( const std::string &  data,
std::size_t  offset = 0U 
)

Sends data.

Returns false if flow control asserted before all the data is sent. Returns true if all the data was sent, or if the data passed in (taking the offset into account) is empty. Throws SendError on error.

If flow control is asserted then the socket write-event handler is installed and send() returns false. Unsent portions of the data string are copied internally. When the subsequent write-event is triggered the user should call writeEvent(). There should be no new calls to send() until writeEvent() returns true.

Definition at line 779 of file gsocketprotocol.cpp.

◆ send() [2/2]

bool GNet::SocketProtocol::send ( const std::vector< G::string_view > &  data,
std::size_t  offset = 0U 
)

Overload to send data using scatter-gather segments.

In this overload any unsent residue is not copied and the segment pointers must stay valid until writeEvent() returns true.

Definition at line 784 of file gsocketprotocol.cpp.

◆ setReadBufferSize()

void GNet::SocketProtocol::setReadBufferSize ( std::size_t  n)
static

Sets the read buffer size. Used in testing.

Definition at line 819 of file gsocketprotocol.cpp.

◆ shutdown()

void GNet::SocketProtocol::shutdown ( )

Initiates a TLS-close if secure, together with a Socket::shutdown(1).

Definition at line 789 of file gsocketprotocol.cpp.

◆ writeEvent()

bool GNet::SocketProtocol::writeEvent ( )

Called on receipt of a write event.

Sends more pending data down the connection. Returns true if all pending data was sent. Throws SendError on error.

Definition at line 769 of file gsocketprotocol.cpp.


The documentation for this class was generated from the following files: