| D++ (DPP) C++ Discord API Bot Library

Search
Loading...
Searching...
No Matches
dpp::ssl_connection Class Reference

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

`#include <sslconnection.h>`

Inheritance diagram for dpp::ssl_connection:
[legend]
Collaboration diagram for dpp::ssl_connection:
[legend]

## Public Member Functions

| ssl_connection (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.
| ssl_connection (cluster *creator, socket fd, uint16_t port, bool plaintext_downgrade=false, const std::string &private_key="", const std::string &public_key="")
| Accept a new connection from listen()/accept() socket.
virtual | ~ssl_connection ()
| Destroy the ssl_connection object.
virtual void | close ()
| Close socket connection.
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.
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.
uint64_t | get_bytes_in ()
| Get total bytes received.
uint64_t | get_bytes_out ()
| Get the bytes out objectGet total bytes sent.
std::string | get_cipher ()
| Get SSL cipher name.
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.
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.
virtual void | log (dpp::loglevel severity, const std::string &msg) const
| Log a message.
void | on_error (dpp::socket fd, const struct dpp::socket_events &, int error_code)
| Called when there is an error on the TCP socket.
void | on_read (dpp::socket fd, const struct dpp::socket_events &ev)
| Called when the TCP socket has data to read.
void | on_write (dpp::socket fd, const struct dpp::socket_events &e)
| Called when the TCP socket can be written to without blocking.
void | read_loop ()
| Set up non blocking I/O and configure on_read, on_write and on_error.
void | socket_write (const std::string_view data)
| Write to the output buffer.

## Public Attributes

bool | keepalive
| True if we are keeping the connection alive after it has finished.
class cluster * | owner
| Owning cluster.
std::string | private_key_file
| Private key PEM file path for inbound SSL connections.
std::string | public_key_file
| Public key PEM file path for inbound SSL connections.

## Protected Member Functions

virtual void | connect ()
| Start SSL connection and connect to TCP endpoint.
void | do_raw_trace (const std::string &message) const
| If raw_trace is set to true, log a debug message for this connection.
virtual void | on_buffer_drained ()
virtual void | one_second_timer ()
| Called every second.
int | start_connecting (dpp::socket sockfd, const struct sockaddr *addr, socklen_t addrlen)
| Start connecting to a TCP socket. This simply calls connect() and checks for error return, as the timeout is now handled in the main IO events for the ssl_connection class.

## Protected Attributes

std::string | buffer
| Input buffer received from socket.
uint64_t | bytes_in
| Bytes in.
uint64_t | bytes_out
| Bytes out.
std::string | cipher
| SSL cipher in use.
uint8_t | connect_retries {0}
| How many times we retried connect().
bool | connected {false}
| True if connection is completed.
std::string | hostname
| Hostname connected to.
time_t | last_tick
| For timers.
std::string | obuffer
| Output buffer for sending to socket.
bool | plaintext
| True for a plain text connection.
std::string | port
| Port connected to.
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.
dpp::socket | sfd
| Raw file descriptor of connection.
openssl_connection * | ssl
| Openssl opaque contexts.
time_t | start
| Start time of connection.
bool | tcp_connect_done {false}
| True if tcp connect() succeeded.
timer | timer_handle
| Timer handle for one second timer.
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.

## Detailed Description

Implements a simple non-blocking SSL stream connection.

## Constructor & Destructor Documentation

## ◆ ssl_connection() [1/2]

dpp::ssl_connection::ssl_connection | ( | 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_connection() [2/2]

dpp::ssl_connection::ssl_connection | ( | cluster * | creator,
|  | socket | fd,
|  | uint16_t | port,
|  | bool | plaintext_downgrade = false,
|  | const std::string & | private_key = "",
|  | const std::string & | public_key = "" )

Accept a new connection from listen()/accept() socket.

Parameters

  creator | Creating cluster
  fd | Socket file descriptor assigned by accept()
  port | Port the new fd came from
  plaintext_downgrade | Set to true to connect using plaintext only, without initialising SSL.
  private_key | if plaintext_downgrade is set to false, a private key PEM file for SSL connections
  public_key | if plaintext_downgrade is set to false, a public key PEM file for SSL connections

## ◆ ~ssl_connection()

virtual dpp::ssl_connection::~ssl_connection | ( |  | ) |

virtual

Destroy the ssl_connection object.

## Member Function Documentation

## ◆ close()

virtual void dpp::ssl_connection::close | ( |  | ) |

virtual

Close socket connection.

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

## ◆ complete_handshake()

void dpp::ssl_connection::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_connection::connect | ( |  | ) |

protected virtual

Start SSL connection and connect to TCP endpoint.

Exceptions

  dpp::exception | Failed to initialise connection

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

## ◆ do_raw_trace()

void dpp::ssl_connection::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_connection::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_connection::get_bytes_in | ( |  | ) |

Get total bytes received.

Returns
  uint64_t bytes received

## ◆ get_bytes_out()

uint64_t dpp::ssl_connection::get_bytes_out | ( |  | ) |

Get the bytes out objectGet total bytes sent.

Returns
  uint64_t bytes sent

## ◆ get_cipher()

std::string dpp::ssl_connection::get_cipher | ( |  | ) |

Get SSL cipher name.

Returns
  std::string ssl cipher name

## ◆ get_unique_id()

uint64_t dpp::ssl_connection::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_connection::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::http_server_request, dpp::https_client, and dpp::websocket_client.

## ◆ log()

virtual void dpp::ssl_connection::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_buffer_drained()

virtual void dpp::ssl_connection::on_buffer_drained | ( |  | ) |

protected virtual

Reimplemented in dpp::http_server_request.

## ◆ on_error()

void dpp::ssl_connection::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_connection::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_connection::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_connection::one_second_timer | ( |  | ) |

protected virtual

Called every second.

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

## ◆ read_loop()

void dpp::ssl_connection::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_connection::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.

## ◆ start_connecting()

int dpp::ssl_connection::start_connecting | ( | dpp::socket | sockfd,
|  | const struct sockaddr * | addr,
|  | socklen_t | addrlen )

protected

Start connecting to a TCP socket. This simply calls connect() and checks for error return, as the timeout is now handled in the main IO events for the ssl_connection class.

Parameters

  sockfd | socket descriptor
  addr | address to connect to
  addrlen | address length
  timeout_ms | timeout in milliseconds

Returns
  int -1 on error, 0 on success just like POSIX connect()

Exceptions

  dpp::connection_exception | on failure

## Member Data Documentation

## ◆ buffer

std::string dpp::ssl_connection::buffer

protected

Input buffer received from socket.

## ◆ bytes_in

uint64_t dpp::ssl_connection::bytes_in

protected

Bytes in.

## ◆ bytes_out

uint64_t dpp::ssl_connection::bytes_out

protected

Bytes out.

## ◆ cipher

std::string dpp::ssl_connection::cipher

protected

SSL cipher in use.

## ◆ connect_retries

uint8_t dpp::ssl_connection::connect_retries {0}

protected

How many times we retried connect().

## ◆ connected

bool dpp::ssl_connection::connected {false}

protected

True if connection is completed.

## ◆ hostname

std::string dpp::ssl_connection::hostname

protected

Hostname connected to.

## ◆ keepalive

bool dpp::ssl_connection::keepalive

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

## ◆ last_tick

time_t dpp::ssl_connection::last_tick

protected

For timers.

## ◆ obuffer

std::string dpp::ssl_connection::obuffer

protected

Output buffer for sending to socket.

## ◆ owner

class cluster* dpp::ssl_connection::owner

Owning cluster.

## ◆ plaintext

bool dpp::ssl_connection::plaintext

protected

True for a plain text connection.

## ◆ port

std::string dpp::ssl_connection::port

protected

Port connected to.

## ◆ private_key_file

std::string dpp::ssl_connection::private_key_file

Private key PEM file path for inbound SSL connections.

## ◆ public_key_file

std::string dpp::ssl_connection::public_key_file

Public key PEM file path for inbound SSL connections.

## ◆ raw_trace

bool dpp::ssl_connection::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_connection::sfd

protected

Raw file descriptor of connection.

## ◆ ssl

openssl_connection* dpp::ssl_connection::ssl

protected

Openssl opaque contexts.

## ◆ start

time_t dpp::ssl_connection::start

protected

Start time of connection.

## ◆ tcp_connect_done

bool dpp::ssl_connection::tcp_connect_done {false}

protected

True if tcp connect() succeeded.

## ◆ timer_handle

timer dpp::ssl_connection::timer_handle

protected

Timer handle for one second timer.

## ◆ unique_id

uint64_t dpp::ssl_connection::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.

D++ Library version 9.0.13 D++ Library version 9.0.12 D++ Library version 9.0.11 D++ Library version 9.0.10 D++ Library version 9.0.9 D++ Library version 9.0.8 D++ Library version 9.0.7 D++ Library version 9.0.6 D++ Library version 9.0.5 D++ Library version 9.0.4 D++ Library version 9.0.3 D++ Library version 9.0.2 D++ Library version 9.0.1 D++ Library version 9.0.0 D++ Library version 1.0.2 D++ Library version 1.0.1 D++ Library version 1.0.0