dpp::websocket_client Class Reference

Implements a websocket client based on the SSL client. More...

#include <wsclient.h>

Inheritance diagram for dpp::websocket_client:

Collaboration diagram for dpp::websocket_client:

Public Member Functions
	websocket_client (cluster *creator, const std::string &hostname, const std::string &port="443", const std::string &urlpath="", ws_opcode opcode=OP_BINARY)
	Connect to a specific websocket server. More...
virtual	~websocket_client ()=default
	Destroy the websocket client object. More...
virtual void	write (const std::string_view data, ws_opcode _opcode=OP_AUTO)
	Write to websocket. Encapsulates data in frames if the status is CONNECTED. More...
virtual bool	handle_buffer (std::string &buffer) override
	Processes incoming frames from the SSL socket input buffer. More...
virtual void	close () override
	Close websocket. More...
virtual bool	handle_frame (const std::string &buffer, ws_opcode opcode)
	Receives raw frame content only without headers. More...
virtual void	error (uint32_t errorcode)
	Called upon error frame. More...
virtual void	one_second_timer () override
	Fires every second from the underlying socket I/O loop, used for sending websocket pings. More...
void	send_close_packet ()
	Send OP_CLOSE error code 1000 to the other side of the connection. This indicates graceful close. More...
virtual void	on_disconnect ()
	Called on HTTP socket closure. More...
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...
void	read_loop ()
	Set up non blocking I/O and configure on_read, on_write and on_error. More...
void	socket_write (const std::string_view data)
	Write to the output buffer. 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	connect () override
	Connect to websocket server. More...
ws_state	get_state () const
	Get websocket state. 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
bool	timed_out
	If true the connection timed out while waiting, when waiting for SSL negotiation, TCP connect(), or HTTP. More...
time_t	timeout
	Time at which the connection should be abandoned, if we are still connecting or negotiating with a HTTP server. More...
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 websocket client based on the SSL client.

Constructor & Destructor Documentation

websocket_client()

dpp::websocket_client::websocket_client	(	cluster *	creator,
		const std::string &	hostname,
		const std::string &	port = "443",
		const std::string &	urlpath = "",
		ws_opcode	opcode = OP_BINARY
	)

Connect to a specific websocket server.

Parameters

creator	Creating cluster
hostname	Hostname to connect to
port	Port to connect to
urlpath	The URL path components of the HTTP request to send
opcode	The encoding type to use, either OP_BINARY or OP_TEXT

Note

This just indicates the default for frames sent. Certain sockets, such as voice websockets, may send a combination of OP_TEXT and OP_BINARY frames, whereas shard websockets will only ever send OP_BINARY for ETF and OP_TEXT for JSON.

~websocket_client()

virtual dpp::websocket_client::~websocket_client ( )

virtualdefault

Destroy the websocket client object.

Member Function Documentation

close()

virtual void dpp::websocket_client::close ( )

overridevirtual

Close websocket.

Reimplemented from dpp::ssl_client.

complete_handshake()

void dpp::ssl_client::complete_handshake ( const struct socket_events *  ev )

inherited

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::websocket_client::connect ( )

overrideprotectedvirtual

Connect to websocket server.

Reimplemented from dpp::ssl_client.

do_raw_trace()

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

protectedinherited

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 ( )

inherited

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.

error()

virtual void dpp::websocket_client::error ( uint32_t  errorcode )

virtual

Called upon error frame.

Parameters

errorcode

The error code from the websocket server

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

get_bytes_in()

uint64_t dpp::ssl_client::get_bytes_in ( )

inherited

Get total bytes received.

Returns

uint64_t bytes received

get_bytes_out()

uint64_t dpp::ssl_client::get_bytes_out ( )

inherited

Get the bytes out objectGet total bytes sent.

Returns

uint64_t bytes sent

get_cipher()

std::string dpp::ssl_client::get_cipher ( )

inherited

Get SSL cipher name.

Returns

std::string ssl cipher name

get_state()

ws_state dpp::websocket_client::get_state ( ) const

protected

Get websocket state.

Returns

websocket state

get_unique_id()

uint64_t dpp::ssl_client::get_unique_id ( ) const

inherited

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::websocket_client::handle_buffer ( std::string &  buffer )

overridevirtual

Processes incoming frames from the SSL socket input buffer.

Parameters

buffer

The buffer contents. Can modify this value removing the head elements when processed.

Reimplemented from dpp::ssl_client.

handle_frame()

virtual bool dpp::websocket_client::handle_frame ( const std::string &  buffer, ws_opcode  opcode  )

virtual

Receives raw frame content only without headers.

Parameters

buffer	The buffer contents
opcode	Frame type, e.g. OP_TEXT, OP_BINARY

Returns

True if the frame was successfully handled. False if no valid frame is in the buffer.

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

log()

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

virtualinherited

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_disconnect()

virtual void dpp::websocket_client::on_disconnect ( )

virtual

Called on HTTP socket closure.

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  )

inherited

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  )

inherited

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  )

inherited

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

Parameters

fd	File descriptor
e	Socket events

one_second_timer()

virtual void dpp::websocket_client::one_second_timer ( )

overridevirtual

Fires every second from the underlying socket I/O loop, used for sending websocket pings.

Reimplemented from dpp::ssl_client.

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

read_loop()

void dpp::ssl_client::read_loop ( )

inherited

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

send_close_packet()

void dpp::websocket_client::send_close_packet

(

)

Send OP_CLOSE error code 1000 to the other side of the connection. This indicates graceful close.

Note

This informs Discord to invalidate the session, you cannot resume if you send this

socket_write()

void dpp::ssl_client::socket_write ( const std::string_view  data )

inherited

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.

write()

virtual void dpp::websocket_client::write ( const std::string_view  data, ws_opcode  _opcode = OP_AUTO  )

virtual

Write to websocket. Encapsulates data in frames if the status is CONNECTED.

Parameters

data	The data to send.
_opcode	The opcode of the data to send, either binary or text. The default is to use the socket's opcode as set in the constructor.

Member Data Documentation

buffer

std::string dpp::ssl_client::buffer

protectedinherited

Input buffer received from socket.

bytes_in

uint64_t dpp::ssl_client::bytes_in

protectedinherited

Bytes in.

bytes_out

uint64_t dpp::ssl_client::bytes_out

protectedinherited

Bytes out.

cipher

std::string dpp::ssl_client::cipher

protectedinherited

SSL cipher in use.

connect_retries

uint8_t dpp::ssl_client::connect_retries {0}

protectedinherited

How many times we retried connect()

connected

bool dpp::ssl_client::connected {false}

protectedinherited

True if connection is completed.

hostname

std::string dpp::ssl_client::hostname

protectedinherited

Hostname connected to.

keepalive

bool dpp::ssl_client::keepalive

inherited

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

last_tick

time_t dpp::ssl_client::last_tick

protectedinherited

For timers.

obuffer

std::string dpp::ssl_client::obuffer

protectedinherited

Output buffer for sending to socket.

owner

class cluster* dpp::ssl_client::owner

inherited

Owning cluster.

plaintext

bool dpp::ssl_client::plaintext

protectedinherited

True for a plain text connection.

port

std::string dpp::ssl_client::port

protectedinherited

Port connected to.

raw_trace

bool dpp::ssl_client::raw_trace {false}

protectedinherited

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

protectedinherited

Raw file descriptor of connection.

ssl

openssl_connection* dpp::ssl_client::ssl

protectedinherited

Openssl opaque contexts.

start

time_t dpp::ssl_client::start

protectedinherited

Start time of connection.

tcp_connect_done

bool dpp::ssl_client::tcp_connect_done {false}

protectedinherited

True if tcp connect() succeeded.

timed_out

bool dpp::websocket_client::timed_out

protected

If true the connection timed out while waiting, when waiting for SSL negotiation, TCP connect(), or HTTP.

timeout

time_t dpp::websocket_client::timeout

protected

Time at which the connection should be abandoned, if we are still connecting or negotiating with a HTTP server.

timer_handle

timer dpp::ssl_client::timer_handle

protectedinherited

Timer handle for one second timer.

unique_id

uint64_t dpp::ssl_client::unique_id

protectedinherited

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.