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

Search
Loading...
Searching...
No Matches
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:
[legend]
Collaboration diagram for dpp::https_client:
[legend]

## 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.
virtual | ~https_client () override
| Destroy the https client object.
virtual void | close () override
| Close HTTPS socket.
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.
const std::string | get_content () const
| Get the response content.
const std::string | get_header (std::string header_name) const
| Get a HTTP response header.
size_t | get_header_count (std::string header_name) const
| Get the number of headers with the same header name.
const std::list< std::string > | get_header_list (std::string header_name) const
| Get a set of HTTP response headers with a common name.
const std::multimap< std::string, std::string > | get_headers () const
| Get all HTTP response headers.
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.
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 data from the SSL socket input buffer.
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.
virtual void | one_second_timer () override
| Fires every second from the underlying socket I/O loop, used for timeouts.
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.

## 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.
static http_connect_info | get_host_info (std::string url)
| Break down a scheme, hostname and port into a http_connect_info.

## Public Attributes

https_client_completion_event | completed
| Function to call when HTTP request is completed.
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.
http_state | state
| Current connection state.
bool | timed_out
| If true the response timed out while waiting.

## Protected Member Functions

virtual void | connect () override
| Start the connection.
void | do_raw_trace (const std::string &message) const
| If raw_trace is set to true, log a debug message for this connection.
http_state | get_state ()
| Get request 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.
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 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

  hostname | Hostname to connect to
  port | Port number to connect to, usually 443 for SSL and 80 for plaintext
  urlpath | path part of URL, e.g. "/api"
  verb | Request verb, e.g. GET or POST
  req_body | Request body, use dpp::https_client::build_multipart() to build a multipart MIME body (e.g. for multiple file upload)
  extra_headers | Additional request headers, e.g. user-agent, authorization, etc
  plaintext_connection | Set to true to make the connection plaintext (turns off SSL)
  request_timeout | How many seconds before the connection is considered failed if not finished
  protocol | Request HTTP protocol (default: 1.1)
  done | Function to call when https_client request is completed

## ◆ ~https_client()

virtual dpp::https_client::~https_client | ( |  | ) |

override virtual

Destroy the https client object.

## Member Function Documentation

## ◆ build_multipart()

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

  json | The json content
  filenames | File names of files to send
  contents | Contents of each of the files to send
  mimetypes | MIME types of each of the files to send

Returns
  multipart mime content and headers

## ◆ close()

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

override virtual

Close HTTPS socket.

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

override protected virtual

Start the connection.

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.

## ◆ 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_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_name | Header 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()

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

  url | URL 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_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::https_client::handle_buffer | ( | std::string & | buffer | ) |

override virtual

Processes incoming data 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.

## ◆ 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_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::https_client::one_second_timer | ( |  | ) |

override virtual

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

Reimplemented from dpp::ssl_connection.

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

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

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

## ◆ completed

https_client_completion_event dpp::https_client::completed

Function to call when HTTP request is completed.

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

## ◆ state

http_state dpp::https_client::state

Current connection state.

## ◆ tcp_connect_done

bool dpp::ssl_connection::tcp_connect_done {false}

protected inherited

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_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