dpp::ssl_client Class Reference

Implements a simple non-blocking SSL stream client. More...

#include <sslclient.h>

Inheritance diagram for dpp::ssl_client:

Collaboration diagram for dpp::ssl_client:

Public Member Functions
void	enable_raw_tracing ()
	For low-level debugging, calling this function will enable low level I/O logging for this connection to the logger. This can be very loud, and output a lot of data, so only enable it selectively where you need it. More...
uint64_t	get_bytes_out ()
	Get the bytes out objectGet total bytes sent. More...
uint64_t	get_bytes_in ()
	Get total bytes received. More...
uint64_t	get_unique_id () const
	Every request made has a unique ID. This increments for every request, starting at 1. You can use this for statistics, or to associate requests and replies in external event loops. More...
std::string	get_cipher ()
	Get SSL cipher name. More...
	ssl_client (cluster *creator, const std::string &_hostname, const std::string &_port="443", bool plaintext_downgrade=false, bool reuse=false)
	Connect to a specified host and port. Throws std::runtime_error on fatal error. More...
void	read_loop ()
	Set up non blocking I/O and configure on_read, on_write and on_error. More...
virtual	~ssl_client ()
	Destroy the ssl_client object. More...
virtual bool	handle_buffer (std::string &buffer)
	Handle input from the input buffer. This function will be called until all data in the buffer has been processed and the buffer is empty. More...
void	socket_write (const std::string_view data)
	Write to the output buffer. More...
virtual void	close ()
	Close socket connection. More...
virtual void	log (dpp::loglevel severity, const std::string &msg) const
	Log a message. More...
void	complete_handshake (const struct socket_events *ev)
	Called while SSL handshake is in progress. If the handshake completes, the state of the socket is progressed to an established state. More...
void	on_read (dpp::socket fd, const struct dpp::socket_events &ev)
	Called when the TCP socket has data to read. More...
void	on_write (dpp::socket fd, const struct dpp::socket_events &e)
	Called when the TCP socket can be written to without blocking. More...
void	on_error (dpp::socket fd, const struct dpp::socket_events &, int error_code)
	Called when there is an error on the TCP socket. More...

Public Attributes
bool	keepalive
	True if we are keeping the connection alive after it has finished. More...
class cluster *	owner
	Owning cluster. More...

Protected Member Functions
virtual void	one_second_timer ()
	Called every second. More...
virtual void	connect ()
	Start SSL connection and connect to TCP endpoint. More...
void	do_raw_trace (const std::string &message) const
	If raw_trace is set to true, log a debug message for this connection. More...

Protected Attributes
std::string	buffer
	Input buffer received from socket. More...
std::string	obuffer
	Output buffer for sending to socket. More...
dpp::socket	sfd
	Raw file descriptor of connection. More...
openssl_connection *	ssl
	Openssl opaque contexts. More...
std::string	cipher
	SSL cipher in use. More...
time_t	last_tick
	For timers. More...
time_t	start
	Start time of connection. More...
uint8_t	connect_retries {0}
	How many times we retried connect() More...
std::string	hostname
	Hostname connected to. More...
std::string	port
	Port connected to. More...
uint64_t	bytes_out
	Bytes out. More...
uint64_t	bytes_in
	Bytes in. More...
bool	plaintext
	True for a plain text connection. More...
bool	connected {false}
	True if connection is completed. More...
bool	tcp_connect_done {false}
	True if tcp connect() succeeded. More...
timer	timer_handle
	Timer handle for one second timer. More...
uint64_t	unique_id
	Unique ID of socket used as a nonce You can use this to identify requests vs reply if you want. D++ itself only sets this, and does not use it in any logic. It starts at 1 and increments for each request made. More...
bool	raw_trace {false}
	Set this to true to log all IO to debug for this connection. This is an internal developer facility. Do not enable it unless you need to, as it will be very noisy. More...

Detailed Description

Implements a simple non-blocking SSL stream client.

Note

although the design is non-blocking the run() method will execute in an infinite loop until the socket disconnects. This is intended to be run within a std::thread.

Constructor & Destructor Documentation

ssl_client()

dpp::ssl_client::ssl_client	(	cluster *	creator,
		const std::string &	_hostname,
		const std::string &	_port = "443",
		bool	plaintext_downgrade = false,
		bool	reuse = false
	)

Connect to a specified host and port. Throws std::runtime_error on fatal error.

Parameters

creator	Creating cluster
_hostname	The hostname to connect to
_port	the Port number to connect to
plaintext_downgrade	Set to true to connect using plaintext only, without initialising SSL.
reuse	Attempt to reuse previous connections for this hostname and port, if available Note that no Discord endpoints will function when downgraded. This option is provided only for connection to non-Discord addresses such as within dpp::cluster::request().

Exceptions

dpp::exception

Failed to initialise connection

~ssl_client()

virtual dpp::ssl_client::~ssl_client ( )

virtual

Destroy the ssl_client object.

Member Function Documentation

close()

virtual void dpp::ssl_client::close ( )

virtual

Close socket connection.

Reimplemented in dpp::https_client, and dpp::websocket_client.

complete_handshake()

void dpp::ssl_client::complete_handshake

(

const struct socket_events *

ev

)

Called while SSL handshake is in progress. If the handshake completes, the state of the socket is progressed to an established state.

Parameters

ev	Socket events for the socket

connect()

virtual void dpp::ssl_client::connect ( )

protectedvirtual

Start SSL connection and connect to TCP endpoint.

Exceptions

dpp::exception

Failed to initialise connection

Reimplemented in dpp::https_client, and dpp::websocket_client.

do_raw_trace()

void dpp::ssl_client::do_raw_trace ( const std::string &  message ) const

protected

If raw_trace is set to true, log a debug message for this connection.

Parameters

message

debug message

enable_raw_tracing()

void dpp::ssl_client::enable_raw_tracing

(

)

For low-level debugging, calling this function will enable low level I/O logging for this connection to the logger. This can be very loud, and output a lot of data, so only enable it selectively where you need it.

Generally, you won't need this, it is a library development utility.

get_bytes_in()

uint64_t dpp::ssl_client::get_bytes_in

(

)

Get total bytes received.

Returns

uint64_t bytes received

get_bytes_out()

uint64_t dpp::ssl_client::get_bytes_out

(

)

Get the bytes out objectGet total bytes sent.

Returns

uint64_t bytes sent

get_cipher()

std::string dpp::ssl_client::get_cipher

(

)

Get SSL cipher name.

Returns

std::string ssl cipher name

get_unique_id()

uint64_t dpp::ssl_client::get_unique_id

(

)

const

Every request made has a unique ID. This increments for every request, starting at 1. You can use this for statistics, or to associate requests and replies in external event loops.

Returns

Unique ID

handle_buffer()

virtual bool dpp::ssl_client::handle_buffer ( std::string &  buffer )

virtual

Handle input from the input buffer. This function will be called until all data in the buffer has been processed and the buffer is empty.

Parameters

buffer

the buffer content. Will be modified removing any processed front elements

Returns

bool True if the socket should remain connected

Reimplemented in dpp::https_client, and dpp::websocket_client.

log()

virtual void dpp::ssl_client::log ( dpp::loglevel  severity, const std::string &  msg  ) const

virtual

Log a message.

Parameters

severity	severity of log message
msg	Log message to send

Reimplemented in dpp::discord_client, and dpp::discord_voice_client.

on_error()

void dpp::ssl_client::on_error	(	dpp::socket	fd,
		const struct dpp::socket_events &	,
		int	error_code
	)

Called when there is an error on the TCP socket.

Parameters

fd	File descriptor
error_code	Error code

on_read()

void dpp::ssl_client::on_read	(	dpp::socket	fd,
		const struct dpp::socket_events &	ev
	)

Called when the TCP socket has data to read.

Parameters

fd	File descriptor
ev	Socket events

on_write()

void dpp::ssl_client::on_write	(	dpp::socket	fd,
		const struct dpp::socket_events &	e
	)

Called when the TCP socket can be written to without blocking.

Parameters

fd	File descriptor
e	Socket events

one_second_timer()

virtual void dpp::ssl_client::one_second_timer ( )

protectedvirtual

Called every second.

Reimplemented in dpp::discord_client, dpp::discord_voice_client, dpp::https_client, and dpp::websocket_client.

read_loop()

void dpp::ssl_client::read_loop

(

)

Set up non blocking I/O and configure on_read, on_write and on_error.

Exceptions

std::exception

Any std::exception (or derivative) thrown from read_loop() indicates setup failed

socket_write()

void dpp::ssl_client::socket_write

(

const std::string_view

data

)

Write to the output buffer.

Parameters

data	Data to be written to the buffer.

Note

The data may not be written immediately and may be written at a later time to the socket.

Member Data Documentation

buffer

std::string dpp::ssl_client::buffer

protected

Input buffer received from socket.

bytes_in

uint64_t dpp::ssl_client::bytes_in

protected

Bytes in.

bytes_out

uint64_t dpp::ssl_client::bytes_out

protected

Bytes out.

cipher

std::string dpp::ssl_client::cipher

protected

SSL cipher in use.

connect_retries

uint8_t dpp::ssl_client::connect_retries {0}

protected

How many times we retried connect()

connected

bool dpp::ssl_client::connected {false}

protected

True if connection is completed.

hostname

std::string dpp::ssl_client::hostname

protected

Hostname connected to.

keepalive

bool dpp::ssl_client::keepalive

True if we are keeping the connection alive after it has finished.

last_tick

time_t dpp::ssl_client::last_tick

protected

For timers.

obuffer

std::string dpp::ssl_client::obuffer

protected

Output buffer for sending to socket.

owner

class cluster* dpp::ssl_client::owner

Owning cluster.

plaintext

bool dpp::ssl_client::plaintext

protected

True for a plain text connection.

port

std::string dpp::ssl_client::port

protected

Port connected to.

raw_trace

bool dpp::ssl_client::raw_trace {false}

protected

Set this to true to log all IO to debug for this connection. This is an internal developer facility. Do not enable it unless you need to, as it will be very noisy.

sfd

dpp::socket dpp::ssl_client::sfd

protected

Raw file descriptor of connection.

ssl

openssl_connection* dpp::ssl_client::ssl

protected

Openssl opaque contexts.

start

time_t dpp::ssl_client::start

protected

Start time of connection.

tcp_connect_done

bool dpp::ssl_client::tcp_connect_done {false}

protected

True if tcp connect() succeeded.

timer_handle

timer dpp::ssl_client::timer_handle

protected

Timer handle for one second timer.

unique_id

uint64_t dpp::ssl_client::unique_id

protected

Unique ID of socket used as a nonce You can use this to identify requests vs reply if you want. D++ itself only sets this, and does not use it in any logic. It starts at 1 and increments for each request made.