E-MailRelay

Classes | Public Types | 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>`

## Classes
struct | Config
| A configuration structure for GNet::SocketProtocol. More...

## Public Types
using | Sink = SocketProtocolSink

## Public Member Functions
| SocketProtocol (EventHandler &, EventState, Sink &, StreamSocket &, const Config &)
| Constructor. More...
| ~SocketProtocol ()
| Destructor.
bool | readEvent (bool no_throw_on_peer_disconnect=false)
| Called on receipt of a read event. More...
bool | writeEvent ()
| Called on receipt of a write event. More...
void | otherEvent (EventHandler::Reason, bool no_throw_on_peer_disconnect=false)
| Called on receipt of an 'other' event. More...
bool | send (const std::string &data, std::size_t offset)
| Sends data. More...
bool | send (std::string_view data)
| Overload for string_view. More...
bool | send (const std::vector< std::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...
bool | secureConnectCapable () const
| Returns true if the implementation supports TLS/SSL and a "client" profile has been configured. More...
void | secureConnect ()
| Initiates the TLS/SSL handshake, acting as a client. More...
bool | secureAcceptCapable () const
| Returns true if the implementation supports TLS/SSL and a "server" profile has been configured. 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...
bool | raw () const
| Returns true if no TLS/SSL. More...
std::string | peerCertificate () const
| Returns the peer's TLS/SSL certificate or the empty string. More...
| SocketProtocol (const SocketProtocol &)=delete
| SocketProtocol (SocketProtocol &&)=delete
SocketProtocol & | operator= (const SocketProtocol &)=delete
SocketProtocol & | operator= (SocketProtocol &&)=delete

## 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 57 of file gsocketprotocol.h.

## Member Typedef Documentation

## ◆ Sink

using GNet::SocketProtocol::Sink = SocketProtocolSink

Definition at line 60 of file gsocketprotocol.h.

## Constructor & Destructor Documentation

## ◆ SocketProtocol()

GNet::SocketProtocol::SocketProtocol | ( | EventHandler & | handler,
|  | EventState | es,
|  | Sink & | sink,
|  | StreamSocket & | socket,
|  | const Config & | config
| ) |  |

Constructor.

Definition at line 817 of file gsocketprotocol.cpp.

## Member Function Documentation

## ◆ otherEvent()

void GNet::SocketProtocol::otherEvent | ( | EventHandler::Reason | reason,
|  | bool | no_throw_on_peer_disconnect = `false`
| ) |  |

Called on receipt of an 'other' event.

Any pending read data is delivered via onData() and if this is a peer disconnect event on a raw() socket (Windows) and the 'no_throw_on_peer_disconnect' parameter is true the onPeerDisconnect() is called and the method returns normally, otherwise an exception is thrown.

Definition at line 836 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 895 of file gsocketprotocol.cpp.

## ◆ raw()

bool GNet::SocketProtocol::raw | ( |  | ) | const

Returns true if no TLS/SSL.

Definition at line 889 of file gsocketprotocol.cpp.

## ◆ readEvent()

bool GNet::SocketProtocol::readEvent | ( | bool | no_throw_on_peer_disconnect = `false` | ) |

Called on receipt of a read event.

Delivers data via the sink interface onData(). By default throws ReadError on disconnection, or uses the onPeerDisconnect() callback otherwise. Returns true iff an incomplete send() over TLS has now completed.

Definition at line 826 of file gsocketprotocol.cpp.

## ◆ secure()

bool GNet::SocketProtocol::secure | ( |  | ) | const

Returns true if the connection is currently secure ie.

after onSecure(). Returns false if busy with the TLS/SSL handshake.

Definition at line 882 of file gsocketprotocol.cpp.

## ◆ secureAccept()

void GNet::SocketProtocol::secureAccept | ( |  | ) |

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

Any send() data blocked by flow control is discarded.

Definition at line 876 of file gsocketprotocol.cpp.

## ◆ secureAcceptCapable()

bool GNet::SocketProtocol::secureAcceptCapable | ( |  | ) | const

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

See also GSsl::enabledAs().

Definition at line 871 of file gsocketprotocol.cpp.

## ◆ secureConnect()

void GNet::SocketProtocol::secureConnect | ( |  | ) |

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

Any send() data blocked by flow control is discarded.

Definition at line 866 of file gsocketprotocol.cpp.

## ◆ secureConnectCapable()

bool GNet::SocketProtocol::secureConnectCapable | ( |  | ) | const

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

See also GSsl::enabledAs().

Definition at line 861 of file gsocketprotocol.cpp.

## ◆ send() [1/3]

bool GNet::SocketProtocol::send | ( | const std::string & | data,
|  | std::size_t | offset
| ) |  |

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() or readEvent() returns true.

Definition at line 841 of file gsocketprotocol.cpp.

## ◆ send() [2/3]

bool GNet::SocketProtocol::send | ( | const std::vector< std::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 851 of file gsocketprotocol.cpp.

## ◆ send() [3/3]

bool GNet::SocketProtocol::send | ( | std::string_view | data | ) |

Overload for string_view.

Definition at line 846 of file gsocketprotocol.cpp.

## ◆ shutdown()

void GNet::SocketProtocol::shutdown | ( |  | ) |

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

Definition at line 856 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 an incomplete send() has now completed. Throws SendError on error.

Definition at line 831 of file gsocketprotocol.cpp.

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

- /tmp/slackdce/slackrepo.HKsbdz/build_emailrelay/emailrelay-2.6/src/gnet/gsocketprotocol.h
- /tmp/slackdce/slackrepo.HKsbdz/build_emailrelay/emailrelay-2.6/src/gnet/gsocketprotocol.cpp