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

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

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

`#include <wsclient.h>`

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

## 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.
virtual | ~websocket_client ()=default
| Destroy the websocket client object.
virtual void | close () override
| Close websocket.
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.
virtual void | error (uint32_t errorcode)
| Called upon error frame.
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) override
| Processes incoming frames from the SSL socket input buffer.
virtual bool | handle_frame (const std::string &buffer, ws_opcode opcode)
| Receives raw frame content only without headers.
virtual void | log (dpp::loglevel severity, const std::string &msg) const
| Log a message.
virtual void | on_disconnect ()
| Called on HTTP socket closure.
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.
virtual void | one_second_timer () override
| Fires every second from the underlying socket I/O loop, used for sending websocket pings.
void | read_loop ()
| Set up non blocking I/O and configure on_read, on_write and on_error.
void | send_close_packet ()
| Send OP_CLOSE error code 1000 to the other side of the connection. This indicates graceful close.
void | socket_write (const std::string_view data)
| Write to the output buffer.
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.

## 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 () override
| Connect to websocket server.
void | do_raw_trace (const std::string &message) const
| If raw_trace is set to true, log a debug message for this connection.
ws_state | get_state () const
| Get websocket state.
virtual void | on_buffer_drained ()
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.
bool | timed_out
| If true the connection timed out while waiting, when waiting for SSL negotiation, TCP connect(), or HTTP.
time_t | timeout
| Time at which the connection should be abandoned, if we are still connecting or negotiating with a HTTP server.
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 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 | ( |  | ) |

virtual default

Destroy the websocket client object.

## Member Function Documentation

## ◆ close()

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

override virtual

Close websocket.

Reimplemented from dpp::ssl_connection.

## ◆ complete_handshake()

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

override protected virtual

Connect to websocket server.

Reimplemented from dpp::ssl_connection.

## ◆ do_raw_trace()

void dpp::ssl_connection::do_raw_trace | ( | const std::string & | message | ) | const

protected inherited

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

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

inherited

Get total bytes received.

Returns
  uint64_t bytes received

## ◆ get_bytes_out()

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

inherited

Get the bytes out objectGet total bytes sent.

Returns
  uint64_t bytes sent

## ◆ get_cipher()

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

inherited

Get SSL cipher name.

Returns
  std::string ssl cipher name

## ◆ get_state()

ws_state dpp::websocket_client::get_state | ( |  | ) | const

nodiscard protected

Get websocket state.

Returns
  websocket state

## ◆ get_unique_id()

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

override virtual

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_connection.

## ◆ 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_connection::log | ( | dpp::loglevel | severity,
|  | const std::string & | msg ) const

virtual inherited

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 inherited

Reimplemented in dpp::http_server_request.

## ◆ 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_connection::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_connection::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_connection::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 | ( |  | ) |

override virtual

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

Reimplemented from dpp::ssl_connection.

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

## ◆ read_loop()

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

## ◆ start_connecting()

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

protected inherited

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

## ◆ 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_connection::buffer

protected inherited

Input buffer received from socket.

## ◆ bytes_in

uint64_t dpp::ssl_connection::bytes_in

protected inherited

Bytes in.

## ◆ bytes_out

uint64_t dpp::ssl_connection::bytes_out

protected inherited

Bytes out.

## ◆ cipher

std::string dpp::ssl_connection::cipher

protected inherited

SSL cipher in use.

## ◆ connect_retries

uint8_t dpp::ssl_connection::connect_retries {0}

protected inherited

How many times we retried connect().

## ◆ connected

bool dpp::ssl_connection::connected {false}

protected inherited

True if connection is completed.

## ◆ hostname

std::string dpp::ssl_connection::hostname

protected inherited

Hostname connected to.

## ◆ keepalive

bool dpp::ssl_connection::keepalive

inherited

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

## ◆ last_tick

time_t dpp::ssl_connection::last_tick

protected inherited

For timers.

## ◆ obuffer

std::string dpp::ssl_connection::obuffer

protected inherited

Output buffer for sending to socket.

## ◆ owner

class cluster* dpp::ssl_connection::owner

inherited

Owning cluster.

## ◆ plaintext

bool dpp::ssl_connection::plaintext

protected inherited

True for a plain text connection.

## ◆ port

std::string dpp::ssl_connection::port

protected inherited

Port connected to.

## ◆ private_key_file

std::string dpp::ssl_connection::private_key_file

inherited

Private key PEM file path for inbound SSL connections.

## ◆ public_key_file

std::string dpp::ssl_connection::public_key_file

inherited

Public key PEM file path for inbound SSL connections.

## ◆ raw_trace

bool dpp::ssl_connection::raw_trace {false}

protected inherited

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 inherited

Raw file descriptor of connection.

## ◆ ssl

openssl_connection* dpp::ssl_connection::ssl

protected inherited

Openssl opaque contexts.

## ◆ start

time_t dpp::ssl_connection::start

protected inherited

Start time of connection.

## ◆ tcp_connect_done

bool dpp::ssl_connection::tcp_connect_done {false}

protected inherited

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_connection::timer_handle

protected inherited

Timer handle for one second timer.

## ◆ unique_id

uint64_t dpp::ssl_connection::unique_id

protected inherited

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