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

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

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

Public Member Functions

 https_client (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")
 Connect to a specific HTTP(S) server and complete a request. More...
 
virtual ~https_client ()=default
 Destroy the https client object. More...
 
virtual bool handle_buffer (std::string &buffer)
 Processes incoming data from the SSL socket input buffer. More...
 
virtual void close ()
 Close HTTPS socket. More...
 
virtual void one_second_timer ()
 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...
 
uint64_t get_bytes_out ()
 Get the bytes out objectGet total bytes sent. More...
 
uint64_t get_bytes_in ()
 Get total bytes received. More...
 
std::string get_cipher ()
 Get SSL cipher name. More...
 
void read_loop ()
 Nonblocking I/O loop. More...
 
virtual void write (const std::string &data)
 Write to the output buffer. More...
 
virtual void log (dpp::loglevel severity, const std::string &msg) const
 Log a message. 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

socket_callback_t custom_readable_fd
 Attaching an additional file descriptor to this function will send notifications when there is data to read. More...
 
socket_callback_t custom_writeable_fd
 Attaching an additional file descriptor to this function will send notifications when you are able to write to the socket. More...
 
socket_notification_t custom_readable_ready
 This event will be called when you can read from the custom fd. More...
 
socket_notification_t custom_writeable_ready
 This event will be called when you can write to a custom fd. More...
 
bool keepalive
 True if we are keeping the connection alive after it has finished. More...
 

Protected Member Functions

virtual void connect ()
 Start the connection. More...
 
http_state get_state ()
 Get request state. More...
 

Protected Attributes

std::string buffer
 Input buffer received from socket. More...
 
std::string obuffer
 Output buffer for sending to socket. More...
 
bool nonblocking
 True if in nonblocking mode. The socket switches to nonblocking mode once ReadLoop is called. 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...
 
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 make_new
 True if we are establishing a new connection, false if otherwise. 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 ( 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" 
)

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
http_protocolRequest HTTP protocol

◆ ~https_client()

virtual dpp::https_client::~https_client ( )
virtualdefault

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

Close HTTPS socket.

Reimplemented from dpp::ssl_client.

◆ connect()

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

Start the connection.

Reimplemented from dpp::ssl_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_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

◆ handle_buffer()

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

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_voice_client, and dpp::discord_client.

◆ one_second_timer()

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

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

Nonblocking I/O loop.

Exceptions
std::exceptionAny std::exception (or derivative) thrown from read_loop() causes reconnection of the shard

◆ write()

virtual void dpp::ssl_client::write ( const std::string &  data)
virtualinherited

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.

Reimplemented in dpp::websocket_client.

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.

◆ custom_readable_fd

socket_callback_t dpp::ssl_client::custom_readable_fd
inherited

Attaching an additional file descriptor to this function will send notifications when there is data to read.

NOTE: Only hook this if you NEED it as it can increase CPU usage of the thread! Returning -1 means that you don't want to be notified.

◆ custom_readable_ready

socket_notification_t dpp::ssl_client::custom_readable_ready
inherited

This event will be called when you can read from the custom fd.

◆ custom_writeable_fd

socket_callback_t dpp::ssl_client::custom_writeable_fd
inherited

Attaching an additional file descriptor to this function will send notifications when you are able to write to the socket.

NOTE: Only hook this if you NEED it as it can increase CPU usage of the thread! You should toggle this to -1 when you do not have anything to write otherwise it'll keep triggering repeatedly (it is level triggered).

◆ custom_writeable_ready

socket_notification_t dpp::ssl_client::custom_writeable_ready
inherited

This event will be called when you can write to a custom fd.

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

◆ make_new

bool dpp::ssl_client::make_new
protectedinherited

True if we are establishing a new connection, false if otherwise.

◆ nonblocking

bool dpp::ssl_client::nonblocking
protectedinherited

True if in nonblocking mode. The socket switches to nonblocking mode once ReadLoop is called.

◆ obuffer

std::string dpp::ssl_client::obuffer
protectedinherited

Output buffer for sending to socket.

◆ plaintext

bool dpp::ssl_client::plaintext
protectedinherited

True for a plain text connection.

◆ port

std::string dpp::ssl_client::port
protectedinherited

Port connected to.

◆ sfd

dpp::socket dpp::ssl_client::sfd
protectedinherited

Raw file descriptor of connection.

◆ ssl

openssl_connection* dpp::ssl_client::ssl
protectedinherited

Openssl opaque contexts.

D++ 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