A UDP datagram socket. More...

Inheritance diagram for idfxx::net::datagram_socket:

Classes
struct	config
	Datagram socket configuration. More...

Public Member Functions
	datagram_socket ()
	Creates a new UDP socket with default configuration (IPv4, blocking).

	datagram_socket (address_family fam)
	Creates a new UDP socket of the given address family.

	datagram_socket (const config &cfg)
	Creates a new UDP socket with the given configuration.

size_t	send (std::span< const std::byte > buf)
	Sends a datagram on a connected socket (after `connect`).

result< size_t >	try_send (std::span< const std::byte > buf)
	Sends a datagram on a connected socket (after `try_connect`).

void	set_broadcast (bool on) noexcept
	Toggles permission to send datagrams to broadcast addresses.

void	join_multicast_v4 (ipv4_addr group, ipv4_addr interface={})
	Joins an IPv4 multicast group so that the socket receives datagrams sent to that group.

result< void >	try_join_multicast_v4 (ipv4_addr group, ipv4_addr interface={})
	Joins an IPv4 multicast group so that the socket receives datagrams sent to that group.

void	leave_multicast_v4 (ipv4_addr group, ipv4_addr interface={})
	Leaves an IPv4 multicast group.

result< void >	try_leave_multicast_v4 (ipv4_addr group, ipv4_addr interface={})
	Leaves an IPv4 multicast group.

void	set_multicast_loopback (bool on) noexcept
	Toggles whether outgoing multicast packets are also delivered to local sockets that have joined the group.

void	set_multicast_hops (uint8_t hops) noexcept
	Sets the hop limit (IPv6) / TTL (IPv4) for outgoing multicast packets.

void	set_multicast_interface_v4 (ipv4_addr addr)
	Selects the local interface used for outgoing IPv4 multicast.

result< void >	try_set_multicast_interface_v4 (ipv4_addr addr)
	Selects the local interface used for outgoing IPv4 multicast.

Static Public Member Functions
static result< datagram_socket >	make ()
	Creates a new UDP socket with default configuration (IPv4, blocking).

static result< datagram_socket >	make (address_family fam)
	Creates a new UDP socket of the given address family.

static result< datagram_socket >	make (const config &cfg)
	Creates a new UDP socket with the given configuration.

Detailed Description

A UDP datagram socket.

Datagram sockets are connectionless. Use send_to / recv_from for explicit per-message addressing, or call connect() to set a default peer for send / recv.

Neither receive path silently truncates: recv_from reports an oversized datagram via datagram::truncated, while the connected-mode recv(span) returns errc::message_too_long. Either way the datagram is consumed whole, so size the buffer for the largest expected datagram (e.g. 1500 bytes). On a connectionless socket an empty recv span is a received zero-length datagram, never an end-of-stream signal.

Ownership is exclusive: the socket is non-copyable and move-only. A moved-from socket may only be destroyed, move-assigned, or queried via is_open() (→ false) and idf_handle() (→ -1); calling any other method on it is undefined behavior. The destructor closes the socket if open.

idfxx::net::datagram_socket sock(idfxx::net::address_family::ipv4);
sock.bind({idfxx::net::ipv4_addr::any(), 5005});
std::array<std::byte, 1500> buf;
auto dg = sock.recv_from(buf);
sock.send_to(dg.data, dg.from);

Definition at line 60 of file datagram_socket.hpp.

Constructor & Destructor Documentation

◆ datagram_socket() [1/3]

idfxx::net::datagram_socket::datagram_socket ( )

Creates a new UDP socket with default configuration (IPv4, blocking).

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

◆ datagram_socket() [2/3]

idfxx::net::datagram_socket::datagram_socket ( address_family fam )

explicit

Creates a new UDP socket of the given address family.

Parameters

fam	Address family.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

◆ datagram_socket() [3/3]

idfxx::net::datagram_socket::datagram_socket ( const config & cfg )

explicit

Creates a new UDP socket with the given configuration.

Parameters

cfg	Socket configuration.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Member Function Documentation

◆ join_multicast_v4()

void idfxx::net::datagram_socket::join_multicast_v4	(	ipv4_addr	group,
		ipv4_addr	interface = `{}`
	)

inline

Joins an IPv4 multicast group so that the socket receives datagrams sent to that group.

Equivalent to the POSIX IP_ADD_MEMBERSHIP operation.

Parameters

group	Multicast group address to join.
interface	Local interface address (`{}` for default).

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure (including errc::wrong_protocol_type if the socket family is not IPv4).

Definition at line 203 of file datagram_socket.hpp.

◆ leave_multicast_v4()

void idfxx::net::datagram_socket::leave_multicast_v4	(	ipv4_addr	group,
		ipv4_addr	interface = `{}`
	)

inline

Leaves an IPv4 multicast group.

Equivalent to the POSIX IP_DROP_MEMBERSHIP operation.

Parameters

group	Multicast group address to leave.
interface	Local interface address (`{}` for default).

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Definition at line 231 of file datagram_socket.hpp.

◆ make() [1/3]

static result< datagram_socket > idfxx::net::datagram_socket::make ( )

static

Creates a new UDP socket with default configuration (IPv4, blocking).

Returns: The new socket, or an error.

◆ make() [2/3]

static result< datagram_socket > idfxx::net::datagram_socket::make ( address_family fam )

static

Creates a new UDP socket of the given address family.

Parameters

fam	Address family.

Returns: The new socket, or an error.

◆ make() [3/3]

static result< datagram_socket > idfxx::net::datagram_socket::make ( const config & cfg )

static

Creates a new UDP socket with the given configuration.

Parameters

cfg	Socket configuration.

Returns: The new socket, or an error.

◆ send()

size_t idfxx::net::datagram_socket::send ( std::span< const std::byte > buf )

inline

Sends a datagram on a connected socket (after connect).

Parameters

buf	Data to send.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Returns: The number of bytes sent — always buf.size() on success, since a datagram is sent in full or not at all.

Definition at line 167 of file datagram_socket.hpp.

References idfxx::unwrap().

◆ set_broadcast()

void idfxx::net::datagram_socket::set_broadcast ( bool on )

noexcept

Toggles permission to send datagrams to broadcast addresses.

Equivalent to the POSIX SO_BROADCAST socket option.

Parameters

on	Whether to permit broadcast sends.

◆ set_multicast_hops()

void idfxx::net::datagram_socket::set_multicast_hops ( uint8_t hops )

noexcept

Sets the hop limit (IPv6) / TTL (IPv4) for outgoing multicast packets.

Equivalent to the POSIX IPV6_MULTICAST_HOPS / IP_MULTICAST_TTL option (depending on the socket's family).

Parameters

hops	Hop limit for multicast packets.

◆ set_multicast_interface_v4()

void idfxx::net::datagram_socket::set_multicast_interface_v4 ( ipv4_addr addr )

inline

Selects the local interface used for outgoing IPv4 multicast.

Equivalent to the POSIX IP_MULTICAST_IF option.

The address is not validated against the host's interface list — an address that does not correspond to a local interface is stored and causes subsequent multicast sends to misroute rather than failing here.

Parameters

addr	Local interface address.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error with errc::wrong_protocol_type if the socket family is not IPv4, or errc::invalid_state if the socket has been moved from.

Definition at line 281 of file datagram_socket.hpp.

References idfxx::unwrap().

◆ set_multicast_loopback()

void idfxx::net::datagram_socket::set_multicast_loopback ( bool on )

noexcept

Toggles whether outgoing multicast packets are also delivered to local sockets that have joined the group.

Equivalent to the POSIX IP_MULTICAST_LOOP / IPV6_MULTICAST_LOOP option (the correct level is chosen automatically based on the socket family).

Parameters

on	Whether to enable multicast loopback.

◆ try_join_multicast_v4()

result< void > idfxx::net::datagram_socket::try_join_multicast_v4	(	ipv4_addr	group,
		ipv4_addr	interface = `{}`
	)

Joins an IPv4 multicast group so that the socket receives datagrams sent to that group.

Equivalent to the POSIX IP_ADD_MEMBERSHIP operation.

Parameters

group	Multicast group address to join.
interface	Local interface address (`{}` for default).

Returns: Success, or an error code on failure (including errc::wrong_protocol_type if the socket family is not IPv4).

◆ try_leave_multicast_v4()

result< void > idfxx::net::datagram_socket::try_leave_multicast_v4	(	ipv4_addr	group,
		ipv4_addr	interface = `{}`
	)

Leaves an IPv4 multicast group.

Equivalent to the POSIX IP_DROP_MEMBERSHIP operation.

Parameters

group	Multicast group address to leave.
interface	Local interface address (`{}` for default).

Returns: Success, or an error code on failure.

◆ try_send()

result< size_t > idfxx::net::datagram_socket::try_send ( std::span< const std::byte > buf )

Sends a datagram on a connected socket (after try_connect).

Parameters

buf	Data to send.

Returns: The number of bytes sent — always buf.size() on success, since a datagram is sent in full or not at all — or an error.

◆ try_set_multicast_interface_v4()

result< void > idfxx::net::datagram_socket::try_set_multicast_interface_v4 ( ipv4_addr addr )

Selects the local interface used for outgoing IPv4 multicast.

Equivalent to the POSIX IP_MULTICAST_IF option.

The address is not validated against the host's interface list — an address that does not correspond to a local interface is stored and causes subsequent multicast sends to misroute rather than failing here.

Parameters

addr	Local interface address.

Return values

errc::wrong_protocol_type	the socket family is not IPv4
errc::invalid_state	the socket has been moved from

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

idfxx_net/include/idfxx/net/datagram_socket.hpp

Classes

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ datagram_socket() [1/3]

◆ datagram_socket() [2/3]

◆ datagram_socket() [3/3]

Member Function Documentation

◆ join_multicast_v4()

◆ leave_multicast_v4()

◆ make() [1/3]

◆ make() [2/3]

◆ make() [3/3]

◆ send()

◆ set_broadcast()

◆ set_multicast_hops()

◆ set_multicast_interface_v4()

◆ set_multicast_loopback()

◆ try_join_multicast_v4()

◆ try_leave_multicast_v4()

◆ try_send()

◆ try_set_multicast_interface_v4()