Malloy
Loading...
Searching...
No Matches
Public Types | Public Member Functions | Static Public Member Functions | List of all members
malloy::websocket::connection< isClient > Class Template Reference

Represents a connection via the WebSocket protocol. More...

#include <connection.hpp>

Inheritance diagram for malloy::websocket::connection< isClient >:
Inheritance graph
[legend]
Collaboration diagram for malloy::websocket::connection< isClient >:
Collaboration graph
[legend]

Public Types

enum class  state {
  handshaking , active , closing , closed ,
  inactive
}
 
using handler_t = std::function< void(const malloy::http::request<> &, const std::shared_ptr< connection > &)>
 

Public Member Functions

virtual ~connection () noexcept
 
std::shared_ptr< spdlog::logger > logger () const noexcept
 
void set_binary (const bool enabled)
 
bool binary ()
 
template<concepts::accept_handler Callback>
requires (isClient)
void connect (const boost::asio::ip::tcp::resolver::results_type &target, const std::string &resource, Callback &&done)
 Connect to a remote (websocket) endpoint.
 
template<class Body , class Fields , std::invocable<> Callback>
requires (!isClient)
void accept (const boost::beast::http::request< Body, Fields > &req, Callback &&done)
 Accept an incoming connection.
 
void disconnect (boost::beast::websocket::close_reason why=boost::beast::websocket::normal)
 Disconnect/stop/close the connection.
 
void force_disconnect (boost::beast::websocket::close_reason why=boost::beast::websocket::normal)
 Same as disconnect, but bypasses all queues and runs immediately.
 
void read (concepts::dynamic_buffer auto &buff, concepts::async_read_handler auto &&done)
 Read a complete message into a buffer.
 
template<concepts::async_read_handler Callback>
void send (const concepts::const_buffer_sequence auto &payload, Callback &&done)
 Send the contents of a buffer to the client.
 

Static Public Member Functions

static std::shared_ptr< connectionmake (const std::shared_ptr< spdlog::logger > logger, stream &&ws, const std::string &agent_string)
 Construct a new connection object.
 

Detailed Description

template<bool isClient>
class malloy::websocket::connection< isClient >

Represents a connection via the WebSocket protocol.

Template Parameters
isClientWhether it is the client end of a websocket connection

Provides basic management of a websocket connection. Will close the connection on destruction. The interface is entirely asynchronous and uses callback functions

Note
The functions: connect, accept, disconnect, send, and read are fully threadsafe. Calls to these functions will wait asynchronously until all other queued actions are completed.

Member Enumeration Documentation

◆ state

template<bool isClient>
enum class malloy::websocket::connection::state
strong

The connection state.

Constructor & Destructor Documentation

◆ ~connection()

template<bool isClient>
virtual malloy::websocket::connection< isClient >::~connection ( )
inlinevirtualnoexcept

Destructor.

Member Function Documentation

◆ accept()

template<bool isClient>
template<class Body , class Fields , std::invocable<> Callback>
requires (!isClient)
void malloy::websocket::connection< isClient >::accept ( const boost::beast::http::request< Body, Fields > &  req,
Callback &&  done 
)
inline

Accept an incoming connection.

Note
This is only available if isClient == false
Calling this function is only valid if make was passed a connected stream ready to be accepted (e.g. http stream that req was read from)
Warning
done is only invoked on successful connection
Parameters
reqThe request to accept. boost::beast::websocket::is_upgrade(req) must be true
doneCallback invoked on successful accepting of the request. NOT invoked on failure. Must be invocable without any parameters (i.e. f())

◆ binary()

template<bool isClient>
bool malloy::websocket::connection< isClient >::binary ( )
inline

See stream::binary()

Here is the call graph for this function:

◆ connect()

template<bool isClient>
template<concepts::accept_handler Callback>
requires (isClient)
void malloy::websocket::connection< isClient >::connect ( const boost::asio::ip::tcp::resolver::results_type &  target,
const std::string &  resource,
Callback &&  done 
)
inline

Connect to a remote (websocket) endpoint.

Note
Only available if isClient == true
Parameters
targetThe list of resolved endpoints to connect to
resourceA suburl to make the connection on (e.g. /api/websocket)
doneCallback invoked on accepting the handshake or an error occurring
Here is the call graph for this function:

◆ disconnect()

template<bool isClient>
void malloy::websocket::connection< isClient >::disconnect ( boost::beast::websocket::close_reason  why = boost::beast::websocket::normal)
inline

Disconnect/stop/close the connection.

Note
Attempting to send or receive after calling this will result in error(s).
Calling this function will have no effect if the connection state is closed or closing.
Parameters
whyReason why the connection is being closed.
See also
force_disconnect()
Here is the call graph for this function:

◆ force_disconnect()

template<bool isClient>
void malloy::websocket::connection< isClient >::force_disconnect ( boost::beast::websocket::close_reason  why = boost::beast::websocket::normal)
inline

Same as disconnect, but bypasses all queues and runs immediately.

Note
Attempting to send or receive after calling this will result in error(s).
Calling this function will have no effect if the connection state is closed or closing.
See also
disconnect()

◆ logger()

template<bool isClient>
std::shared_ptr< spdlog::logger > malloy::websocket::connection< isClient >::logger ( ) const
inlinenoexcept

Get the logger instance.

This allows different components to log to the connection specific logger.

Returns
The logger instance.

◆ make()

template<bool isClient>
static std::shared_ptr< connection > malloy::websocket::connection< isClient >::make ( const std::shared_ptr< spdlog::logger >  logger,
stream &&  ws,
const std::string &  agent_string 
)
inlinestatic

Construct a new connection object.

Parameters
loggerLogger to use. Must not be nullptr
wsStream to use. May be unopened/connected but in that case connect must be called before this connection can be used
Here is the call graph for this function:

◆ read()

template<bool isClient>
void malloy::websocket::connection< isClient >::read ( concepts::dynamic_buffer auto &  buff,
concepts::async_read_handler auto &&  done 
)
inline

Read a complete message into a buffer.

Warning
The caller is responsible for keeping the memory used by buff alive until done is called
Parameters
buffBuffer to put the message into. Must satisfy dynamic_buffer Core Concepts
doneCallback invoked on the message being read (successfully or otherwise). Must satisfy async_read_handler Core Concepts. Will NOT be invoked on the websocket being closed before the message could be fully or partially read
Here is the call graph for this function:

◆ send()

template<bool isClient>
template<concepts::async_read_handler Callback>
void malloy::websocket::connection< isClient >::send ( const concepts::const_buffer_sequence auto &  payload,
Callback &&  done 
)
inline

Send the contents of a buffer to the client.

Warning
The caller is responsible for keeping the memory of payload alive until done is invoked
Parameters
payloadThe payload to send. Must satisfy const_buffer_sequence Core Concepts
doneCallback invoked after the message is written (successfully or otherwise). Must satisfy async_read_handler Core Concepts
Here is the call graph for this function:

◆ set_binary()

template<bool isClient>
void malloy::websocket::connection< isClient >::set_binary ( const bool  enabled)
inline

See stream::set_binary(bool)

Here is the call graph for this function:

The documentation for this class was generated from the following file: