Sockets

The socket provides the base abstraction around the socket file descriptor and includes some initialization, cleanup, and conversion utilities.

The socket class is subclassed into UdpSocket and TcpSocket.

API Reference

Header File

components/socket/include/socket.hpp

Type Definitions

typedef int sock_type_t

Classes

class Socket : public espp::BaseComponent 

Class for a generic socket with some helper functions for configuring the socket.

Subclassed by espp::TcpSocket, espp::UdpSocket

Public Types

std::function< std::optional< std::vector< uint8_t > >std::vector< uint8_t > &data, const Info &sender_info)> receive_callback_fn

Callback function to be called when receiving data from a client.

Param data: Byte array of data received from client
Param sender_info: Sender information (address, port)
Return: std::optional<std::vector<uint8_t>> optional data to return to sender.

typedef std::function<void(std::vector<uint8_t> &data)> response_callback_fn

Callback function to be called with data returned after transmitting data to a server.

Param data: The data that the server responded with

Public Functions

explicit Socket(sock_type_t socket_fd, const espp::Logger::Config &logger_config)

Construct the socket, setting its internal socket file descriptor.

Note

This constructor does not check the validity of the socket file descriptor.

Parameters

socket_fd – Socket file descriptor.
logger_config – configuration for the logger associated with the socket.

explicit Socket(Type type, const espp::Logger::Config &logger_config)

Initialize the socket (calling init()).

Parameters

type – The Socket::Type of the socket to make.
logger_config – configuration for the logger associated with the socket.

~Socket(): Tear down any resources associted with the socket.

bool is_valid() const

Is the socket valid.

Returns: true if the socket file descriptor is >= 0.

std::optional<Info> get_ipv4_info()

Get the Socket::Info for the socket.

This will call getsockname() on the socket to get the sockaddr_storage structure, and then fill out the Socket::Info structure.

Returns: Socket::Info for the socket.

bool set_receive_timeout(const std::chrono::duration<float> &timeout)

Set the receive timeout on the provided socket.

Parameters: timeout – requested timeout, must be > 0.
Returns: true if SO_RECVTIMEO was successfully set.

bool enable_reuse()

Allow others to use this address/port combination after we’re done with it.

Returns: true if SO_REUSEADDR and SO_REUSEPORT were successfully set.

bool make_multicast(uint8_t time_to_live = 1, uint8_t loopback_enabled = true)

Configure the socket to be multicast (if time_to_live > 0). Sets the IP_MULTICAST_TTL (number of multicast hops allowed) and optionally configures whether this node should receive its own multicast packets (IP_MULTICAST_LOOP).

Parameters

time_to_live – number of multicast hops allowed (TTL).
loopback_enabled – Whether to receive our own multicast packets.

Returns

true if IP_MULTICAST_TTL and IP_MULTICAST_LOOP were set.

bool add_multicast_group(const std::string &multicast_group)

If this is a server socket, add it to the provided the multicast group.

See https://en.wikipedia.org/wiki/Multicast_address for more information.

Note

Multicast groups must be Class D addresses (224.0.0.0 to 239.255.255.255)

Parameters: multicast_group – multicast group to join.
Returns: true if IP_ADD_MEMBERSHIP was successfully set.

int select(const std::chrono::microseconds &timeout)

Select on the socket for read events.

Parameters: timeout – how long to wait for an event.
Returns: number of events that occurred.

inline const std::string &get_name() const

Get the name of the component

Note

This is the tag of the logger

Returns: A const reference to the name of the component

inline void set_log_tag(const std::string_view &tag)

Set the tag for the logger

Parameters: tag – The tag to use for the logger

inline espp::Logger::Verbosity get_log_level() const

Get the log level for the logger

See also

Logger::Verbosity

See also

Logger::set_verbosity

Returns: The verbosity level of the logger

inline void set_log_level(espp::Logger::Verbosity level)

Set the log level for the logger

See also

Logger::Verbosity

See also

Logger::set_verbosity

Parameters: level – The verbosity level to use for the logger

inline void set_log_verbosity(espp::Logger::Verbosity level)

Set the log verbosity for the logger

See also

set_log_level

See also

Logger::Verbosity

See also

Logger::set_verbosity

Note

This is a convenience method that calls set_log_level

Parameters: level – The verbosity level to use for the logger

inline espp::Logger::Verbosity get_log_verbosity() const

Get the log verbosity for the logger

See also

get_log_level

See also

Logger::Verbosity

See also

Logger::get_verbosity

Note

This is a convenience method that calls get_log_level

Returns: The verbosity level of the logger

inline void set_log_rate_limit(std::chrono::duration<float> rate_limit)

Set the rate limit for the logger

See also

Logger::set_rate_limit

Note

Only calls to the logger that have _rate_limit suffix will be rate limited

Parameters: rate_limit – The rate limit to use for the logger

Public Static Functions

static bool is_valid_fd(sock_type_t socket_fd)

Is the socket valid.

Parameters: socket_fd – Socket file descriptor.
Returns: true if the socket file descriptor is >= 0.

struct Info

Storage for socket information (address, port) with convenience functions to convert to/from POSIX structures.

Public Functions

void init_ipv4(const std::string &addr, size_t prt)

Initialize the struct as an ipv4 address/port combo.

Parameters

addr – IPv4 address string
prt – port number

struct sockaddr_in *ipv4_ptr()

Gives access to IPv4 sockaddr structure (sockaddr_in) for use with low level socket calls like sendto / recvfrom.

Returns: *sockaddr_in pointer to ipv4 data structure

struct sockaddr_in6 *ipv6_ptr()

Gives access to IPv6 sockaddr structure (sockaddr_in6) for use with low level socket calls like sendto / recvfrom.

Returns: *sockaddr_in6 pointer to ipv6 data structure

void update(): Will update address and port based on the curent data in raw.

void from_sockaddr(const struct sockaddr_storage &source_address)

Fill this Info from the provided sockaddr struct.

Parameters: &source_address – sockaddr info filled out by recvfrom.

void from_sockaddr(const struct sockaddr_in &source_address)

Fill this Info from the provided sockaddr struct.

Parameters: &source_address – sockaddr info filled out by recvfrom.

void from_sockaddr(const struct sockaddr_in6 &source_address)

Fill this Info from the provided sockaddr struct.

Parameters: &source_address – sockaddr info filled out by recvfrom.

Public Members

std::string address: IP address of the endpoint as a string.

size_t port: Port of the endpoint as an integer.