D++ (DPP)
C++ Discord API Bot Library
dpp::https_client Class Reference

Implements a HTTPS socket client based on the SSL client. More...

#include <httpsclient.h>

+ Inheritance diagram for dpp::https_client:
+ Collaboration diagram for dpp::https_client:

Public Member Functions

 https_client (cluster *creator, const std::string &hostname, uint16_t port=443, const std::string &urlpath="/", const std::string &verb="GET", const std::string &req_body="", const http_headers &extra_headers={}, bool plaintext_connection=false, uint16_t request_timeout=5, const std::string &protocol="1.1", https_client_completion_event done={})
 Connect to a specific HTTP(S) server and complete a request. More...
 
virtual ~https_client () override
 Destroy the https client object. More...
 
virtual bool handle_buffer (std::string &buffer) override
 Processes incoming data from the SSL socket input buffer. More...
 
virtual void close () override
 Close HTTPS socket. More...
 
virtual void one_second_timer () override
 Fires every second from the underlying socket I/O loop, used for timeouts. More...
 
const std::string get_header (std::string header_name) const
 Get a HTTP response header. More...
 
size_t get_header_count (std::string header_name) const
 Get the number of headers with the same header name. More...
 
const std::list< std::string > get_header_list (std::string header_name) const
 Get a set of HTTP response headers with a common name. More...
 
const std::multimap< std::string, std::string > get_headers () const
 Get all HTTP response headers. More...
 
const std::string get_content () const
 Get the response content. More...
 
uint16_t get_status () const
 Get the response HTTP status, e.g. 200 for OK, 404 for not found, 429 for rate limited. A value of 0 indicates the request was not completed. 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...
 

Static Public Member Functions

static multipart_content build_multipart (const std::string &json, const std::vector< std::string > &filenames={}, const std::vector< std::string > &contents={}, const std::vector< std::string > &mimetypes={})
 Build a multipart content from a set of files and some json. More...
 
static http_connect_info get_host_info (std::string url)
 Break down a scheme, hostname and port into a http_connect_info. More...
 

Public Attributes

bool timed_out
 If true the response timed out while waiting. More...
 
https_client_completion_event completed
 Function to call when HTTP request is completed. More...
 
http_state state
 Current connection state. More...
 
bool keepalive
 True if we are keeping the connection alive after it has finished. More...
 
class clusterowner
 Owning cluster. More...
 

Protected Member Functions

virtual void connect () override
 Start the connection. More...
 
http_state get_state ()
 Get request 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

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 HTTPS socket client based on the SSL client.

Note
plaintext HTTP without SSL is also supported via a "downgrade" setting

Constructor & Destructor Documentation

◆ https_client()

dpp::https_client::https_client ( cluster creator,
const std::string &  hostname,
uint16_t  port = 443,
const std::string &  urlpath = "/",
const std::string &  verb = "GET",
const std::string &  req_body = "",
const http_headers extra_headers = {},
bool  plaintext_connection = false,
uint16_t  request_timeout = 5,
const std::string &  protocol = "1.1",
https_client_completion_event  done = {} 
)

Connect to a specific HTTP(S) server and complete a request.

The constructor will attempt the connection, and return the content. By the time the constructor completes, the HTTP request will be stored in the object.

Note
This is a blocking call. It starts a loop which runs non-blocking functions within it, but does not return until the request completes. See queues.cpp for how to make this asynchronous.
Parameters
hostnameHostname to connect to
portPort number to connect to, usually 443 for SSL and 80 for plaintext
urlpathpath part of URL, e.g. "/api"
verbRequest verb, e.g. GET or POST
req_bodyRequest body, use dpp::https_client::build_multipart() to build a multipart MIME body (e.g. for multiple file upload)
extra_headersAdditional request headers, e.g. user-agent, authorization, etc
plaintext_connectionSet to true to make the connection plaintext (turns off SSL)
request_timeoutHow many seconds before the connection is considered failed if not finished
protocolRequest HTTP protocol (default: 1.1)
doneFunction to call when https_client request is completed

◆ ~https_client()

virtual dpp::https_client::~https_client ( )
overridevirtual

Destroy the https client object.

Member Function Documentation

◆ build_multipart()

static multipart_content dpp::https_client::build_multipart ( const std::string &  json,
const std::vector< std::string > &  filenames = {},
const std::vector< std::string > &  contents = {},
const std::vector< std::string > &  mimetypes = {} 
)
static

Build a multipart content from a set of files and some json.

Parameters
jsonThe json content
filenamesFile names of files to send
contentsContents of each of the files to send
mimetypesMIME types of each of the files to send
Returns
multipart mime content and headers

◆ close()

virtual void dpp::https_client::close ( )
overridevirtual

Close HTTPS socket.

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
evSocket events for the socket

◆ connect()

virtual void dpp::https_client::connect ( )
overrideprotectedvirtual

Start the connection.

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

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

const std::string dpp::https_client::get_content ( ) const

Get the response content.

Returns
response content

◆ get_header()

const std::string dpp::https_client::get_header ( std::string  header_name) const

Get a HTTP response header.

Parameters
header_nameHeader name to find, case insensitive
Returns
Header content or empty string if not found. If multiple values have the same header_name, this will return one of them.
See also
get_header_count to determine if multiple are present
get_header_list to retrieve all entries of the same header_name

◆ get_header_count()

size_t dpp::https_client::get_header_count ( std::string  header_name) const

Get the number of headers with the same header name.

Parameters
header_name
Returns
the number of headers with this count

◆ get_header_list()

const std::list< std::string > dpp::https_client::get_header_list ( std::string  header_name) const

Get a set of HTTP response headers with a common name.

Parameters
header_name
Returns
A list of headers with the same name, or an empty list if not found

◆ get_headers()

const std::multimap< std::string, std::string > dpp::https_client::get_headers ( ) const

Get all HTTP response headers.

Returns
headers as a map

◆ get_host_info()

static http_connect_info dpp::https_client::get_host_info ( std::string  url)
static

Break down a scheme, hostname and port into a http_connect_info.

All but the hostname portion are optional. The path component should not be passed to this function.

Parameters
urlURL to break down
Returns
Split URL

◆ get_state()

http_state dpp::https_client::get_state ( )
protected

Get request state.

Returns
request state

◆ get_status()

uint16_t dpp::https_client::get_status ( ) const

Get the response HTTP status, e.g. 200 for OK, 404 for not found, 429 for rate limited. A value of 0 indicates the request was not completed.

Returns
uint16_t HTTP status

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

Processes incoming data from the SSL socket input buffer.

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

Reimplemented from dpp::ssl_client.

◆ log()

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

Log a message.

Parameters
severityseverity of log message
msgLog 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 
)
inherited

Called when there is an error on the TCP socket.

Parameters
fdFile descriptor
error_codeError 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
fdFile descriptor
evSocket 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
fdFile descriptor
eSocket events

◆ one_second_timer()

virtual void dpp::https_client::one_second_timer ( )
overridevirtual

Fires every second from the underlying socket I/O loop, used for timeouts.

Reimplemented from dpp::ssl_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::exceptionAny std::exception (or derivative) thrown from read_loop() indicates setup failed

◆ socket_write()

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

Write to the output buffer.

Parameters
dataData 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
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.

◆ completed

https_client_completion_event dpp::https_client::completed

Function to call when HTTP request is completed.

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

◆ state

http_state dpp::https_client::state

Current connection state.

◆ tcp_connect_done

bool dpp::ssl_client::tcp_connect_done {false}
protectedinherited

True if tcp connect() succeeded.

◆ timed_out

bool dpp::https_client::timed_out

If true the response timed out while waiting.

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

D++ Library version 10.0.35D++ Library version 10.0.34D++ Library version 10.0.33D++ Library version 10.0.32D++ Library version 10.0.31D++ Library version 10.0.30D++ Library version 10.0.29D++ Library version 10.0.28D++ Library version 10.0.27D++ Library version 10.0.26D++ Library version 10.0.25D++ Library version 10.0.24D++ Library version 10.0.23D++ Library version 10.0.22D++ Library version 10.0.21D++ Library version 10.0.20D++ Library version 10.0.19D++ Library version 10.0.18D++ Library version 10.0.17D++ Library version 10.0.16D++ Library version 10.0.15D++ Library version 10.0.14D++ Library version 10.0.13D++ Library version 10.0.12D++ Library version 10.0.11D++ Library version 10.0.10D++ Library version 10.0.9D++ Library version 10.0.8D++ Library version 10.0.7D++ Library version 10.0.6D++ Library version 10.0.5D++ Library version 10.0.4D++ Library version 10.0.3D++ Library version 10.0.2D++ Library version 10.0.1D++ Library version 10.0.0D++ Library version 9.0.19D++ Library version 9.0.18D++ Library version 9.0.17D++ Library version 9.0.16D++ Library version 9.0.15D++ Library version 9.0.14D++ Library version 9.0.13D++ Library version 9.0.12D++ Library version 9.0.11D++ Library version 9.0.10D++ Library version 9.0.9D++ Library version 9.0.8D++ Library version 9.0.7D++ Library version 9.0.6D++ Library version 9.0.5D++ Library version 9.0.4D++ Library version 9.0.3D++ Library version 9.0.2D++ Library version 9.0.1D++ Library version 9.0.0D++ Library version 1.0.2D++ Library version 1.0.1D++ Library version 1.0.0