idfxx::net Namespace Reference

Namespaces
namespace	netconn

Classes
struct	datagram
	A datagram received together with the sender's endpoint. More...
class	datagram_socket
	A UDP datagram socket. More...
class	endpoint
	Address/port pair identifying a transport endpoint. More...
class	error_category
	Error category for idfxx_net errors. More...
class	ipv4_addr
	IPv4 address value type. More...
struct	ipv4_info
	IPv4 network interface information. More...
class	ipv6_addr
	IPv6 address value type. More...
struct	ipv6_info
	IPv6 network interface information. More...
class	listener
	A TCP listening socket. More...
class	raw_socket
	A raw IP socket. More...
struct	resolver_options
	Resolver hints used by the resolution functions. More...
class	stream_socket
	A TCP stream socket. More...

Concepts
concept	ip_address
	Concept matching either ipv4_addr or ipv6_addr.

Typedefs
using	port_number = uint16_t
	Port number type for transport endpoints.

Enumerations
enum class	address_family : int {   ipv4 = 2 ,   ipv6 = 10 }
	Address family. More...
enum class	ip_protocol : uint8_t {   icmp = 1 ,   igmp = 2 ,   tcp = 6 ,   udp = 17 ,   icmpv6 = 58 ,   udp_lite = 136 }
	IP-layer protocol number, per IANA assigned protocol numbers. More...
enum class	direction : int {   receive ,   send }
	One direction of a bidirectional transport. More...
enum class	dscp : uint8_t {   default_ = 0 ,   cs1 = 8 ,   cs2 = 16 ,   cs3 = 24 ,   cs4 = 32 ,   cs5 = 40 ,   cs6 = 48 ,   cs7 = 56 ,   af11 = 10 ,   af12 = 12 ,   af13 = 14 ,   af21 = 18 ,   af22 = 20 ,   af23 = 22 ,   af31 = 26 ,   af32 = 28 ,   af33 = 30 ,   af41 = 34 ,   af42 = 36 ,   af43 = 38 ,   voice_admit = 44 ,   ef = 46 }
	Differentiated Services Code Point — the top 6 bits of the IPv4/IPv6 traffic-class byte, per RFC 2474 / RFC 4594. More...
enum class	errc : esp_err_t {   invalid_state = 1 ,   invalid_argument = 2 ,   not_supported = 3 ,   timed_out = 4 ,   operation_would_block = 5 ,   in_progress = 6 ,   interrupted = 7 ,   address_in_use = 8 ,   address_not_available = 9 ,   connection_refused = 10 ,   connection_reset = 11 ,   connection_aborted = 12 ,   not_connected = 13 ,   already_connected = 14 ,   host_unreachable = 15 ,   network_unreachable = 16 ,   network_down = 17 ,   broken_pipe = 18 ,   message_too_long = 19 ,   too_many_files_open = 20 ,   name_resolution = 21 ,   name_not_found = 22 ,   name_temporary = 23 ,   name_no_data = 24 ,   io_error = 25 ,   wrong_protocol_type = 26 ,   unexpected_eof = 27 ,   netconn_buffer_error = 28 ,   netconn_routing = 29 ,   netconn_illegal_value = 30 ,   netconn_aborted = 31 ,   netconn_reset = 32 ,   netconn_closed = 33 ,   no_buffer_space = 34 }
	IP transport error codes. More...

Functions
std::error_code	make_error_code (errc e) noexcept
	Creates an error code from an idfxx::net::errc value.
endpoint	resolve_one (std::string_view host, port_number port, const resolver_options &opts={})
	Resolves a host and numeric port and returns the first matching endpoint.
result< endpoint >	try_resolve_one (std::string_view host, port_number port, const resolver_options &opts={})
	Resolves a host and numeric port and returns the first matching endpoint.
endpoint	resolve_one (std::string_view host, std::string_view service, const resolver_options &opts={})
	Resolves a host and service name and returns the first matching endpoint.
result< endpoint >	try_resolve_one (std::string_view host, std::string_view service, const resolver_options &opts={})
	Resolves a host and service name and returns the first matching endpoint.
template<typename F >
void	resolve_each (std::string_view host, port_number port, F &&f, const resolver_options &opts={})
	Visits each resolved endpoint for a host and numeric port without allocating.
template<typename F >
result< void >	try_resolve_each (std::string_view host, port_number port, F &&f, const resolver_options &opts={})
	Visits each resolved endpoint for a host and numeric port without allocating.
template<typename F >
void	resolve_each (std::string_view host, std::string_view service, F &&f, const resolver_options &opts={})
	Visits each resolved endpoint for a host and service name without allocating.
template<typename F >
result< void >	try_resolve_each (std::string_view host, std::string_view service, F &&f, const resolver_options &opts={})
	Visits each resolved endpoint for a host and service name without allocating.
std::vector< endpoint >	resolve (std::string_view host, port_number port, const resolver_options &opts={})
	Resolves a host and numeric port and collects every endpoint.
result< std::vector< endpoint > >	try_resolve (std::string_view host, port_number port, const resolver_options &opts={})
	Resolves a host and numeric port and collects every endpoint.
std::vector< endpoint >	resolve (std::string_view host, std::string_view service, const resolver_options &opts={})
	Resolves a host and service name and collects every endpoint.
result< std::vector< endpoint > >	try_resolve (std::string_view host, std::string_view service, const resolver_options &opts={})
	Resolves a host and service name and collects every endpoint.

Typedef Documentation

port_number

using idfxx::net::port_number = typedef uint16_t

Port number type for transport endpoints.

Definition at line 60 of file endpoint.hpp.

Enumeration Type Documentation

address_family

enum class idfxx::net::address_family : int

strong

Address family.

Where a "no preference" or "any family" semantic is needed (e.g. resolver hints), use std::optional<address_family> rather than a sentinel value.

Enumerator
ipv4	IPv4.
ipv6	IPv6.

Definition at line 37 of file endpoint.hpp.

direction

enum class idfxx::net::direction : int

strong

One direction of a bidirectional transport.

Used by half-shutdown operations to identify which side of the connection to close. To act on both directions, call the no-argument overload of the relevant method.

Enumerator
receive	The receive direction.
send	The send direction.

Definition at line 70 of file endpoint.hpp.

dscp

enum class idfxx::net::dscp : uint8_t

strong

Differentiated Services Code Point — the top 6 bits of the IPv4/IPv6 traffic-class byte, per RFC 2474 / RFC 4594.

Named values cover the standard per-hop behaviours (default, class selectors, assured-forwarding classes, expedited forwarding, voice-admit). Custom 6-bit values can be passed as static_cast<dscp>(n); only the low 6 bits are used.

Enumerator
default_	CS0 — best-effort (default).
cs1
cs2
cs3
cs4
cs5
cs6
cs7
af11
af12
af13
af21
af22
af23
af31
af32
af33
af41
af42
af43
voice_admit	Voice-admit (RFC 5865).
ef	Expedited forwarding (RFC 3246).

Definition at line 84 of file endpoint.hpp.

errc

enum class idfxx::net::errc : esp_err_t

strong

IP transport error codes.

The category maps each code to its corresponding std::errc synonym (via default_error_condition), so for example

ec == idfxx::net::errc::operation_would_block
ec == std::errc::operation_would_block

are both true for the same underlying error.

Enumerator
invalid_state	Operation invalid in current state.
invalid_argument	Invalid argument.
not_supported	Operation not supported.
timed_out	Operation timed out.
operation_would_block	Operation would block.
in_progress	Operation in progress.
interrupted	Operation interrupted by signal.
address_in_use	Address already in use.
address_not_available	Address not available on this host.
connection_refused	Connection refused by peer.
connection_reset	Connection reset by peer.
connection_aborted	Connection aborted.
not_connected	Socket not connected.
already_connected	Socket already connected.
host_unreachable	Host unreachable.
network_unreachable	Network unreachable.
network_down	Network is down.
broken_pipe	Broken pipe (write to closed peer).
message_too_long	Message too long for transport.
too_many_files_open	Too many open files / sockets.
name_resolution	Generic name resolution failure.
name_not_found	Host name not found (NXDOMAIN).
name_temporary	Temporary name resolution failure.
name_no_data	Name has no data of requested family.
io_error	Generic I/O error.
wrong_protocol_type	Operation does not match socket's family or protocol.
unexpected_eof	Stream ended before the requested data was received.
netconn_buffer_error	Netconn buffer error.
netconn_routing	Netconn routing error.
netconn_illegal_value	Illegal value passed to netconn.
netconn_aborted	Netconn connection aborted.
netconn_reset	Netconn connection reset.
netconn_closed	Netconn connection closed.
no_buffer_space	Out of buffer/PBUF memory on a data-path call (transient).

Definition at line 56 of file error.hpp.

ip_protocol

enum class idfxx::net::ip_protocol : uint8_t

strong

IP-layer protocol number, per IANA assigned protocol numbers.

Used by raw_socket to select the IP-layer protocol and by the resolver to restrict address records to a particular transport. Custom values (e.g. IPPROTO_GRE) can be passed as static_cast<ip_protocol>(n).

Enumerator
icmp	ICMP for IPv4.
igmp	IGMP.
tcp	TCP.
udp	UDP.
icmpv6	ICMP for IPv6.
udp_lite	UDP-Lite (RFC 3828).

Definition at line 50 of file endpoint.hpp.

Function Documentation

make_error_code()

std::error_code idfxx::net::make_error_code ( errc  e )

inlinenoexcept

Creates an error code from an idfxx::net::errc value.

Parameters

e	The error code enumerator.

Returns

The corresponding std::error_code.

Definition at line 160 of file error.hpp.

References idfxx::net_category().

resolve() [1/2]

std::vector< endpoint > idfxx::net::resolve	(	std::string_view	host,
		port_number	port,
		const resolver_options &	opts = {}
	)

Resolves a host and numeric port and collects every endpoint.

Prefer resolve_one for the common single-address case, or resolve_each to iterate candidates without allocating; this overload exists for callers that want the full result set in a container.

Parameters

host	Host name or numeric address.
port	Port number in host byte order.
opts	Resolver options.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error

on failure.

Returns

List of resolved endpoints (may be empty).

resolve() [2/2]

std::vector< endpoint > idfxx::net::resolve	(	std::string_view	host,
		std::string_view	service,
		const resolver_options &	opts = {}
	)

Resolves a host and service name and collects every endpoint.

Prefer resolve_one for the common single-address case, or resolve_each to iterate candidates without allocating; this overload exists for callers that want the full result set in a container.

Parameters

host	Host name or numeric address.
service	Service name (e.g. "http") or numeric port string.
opts	Resolver options.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error

on failure.

Returns

List of resolved endpoints.

resolve_each() [1/2]

template<typename F >

void idfxx::net::resolve_each	(	std::string_view	host,
		port_number	port,
		F &&	f,
		const resolver_options &	opts = {}
	)

Visits each resolved endpoint for a host and numeric port without allocating.

Template Parameters

F	Callable invoked as f(const endpoint&). If it returns void, every result is visited. If it returns bool, returning false stops the iteration early (e.g. once a connection attempt has succeeded).

Parameters

host	Host name or numeric address.
port	Port number in host byte order.
f	Visitor applied to each resolved endpoint.
opts	Resolver options.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error

on resolution failure. The visitor stopping early is not a failure.

idfxx::net::resolve_each("example.com", 80, [](const idfxx::net::endpoint& ep) {
    idfxx::log::info("app", "candidate {}", ep);
});

Definition at line 176 of file resolver.hpp.

resolve_each() [2/2]

template<typename F >

void idfxx::net::resolve_each	(	std::string_view	host,
		std::string_view	service,
		F &&	f,
		const resolver_options &	opts = {}
	)

Visits each resolved endpoint for a host and service name without allocating.

Template Parameters

F	Callable invoked as f(const endpoint&). If it returns void, every result is visited. If it returns bool, returning false stops the iteration early.

Parameters

host	Host name or numeric address.
service	Service name (e.g. "http") or numeric port string.
f	Visitor applied to each resolved endpoint.
opts	Resolver options.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error

on resolution failure. The visitor stopping early is not a failure.

Definition at line 220 of file resolver.hpp.

resolve_one() [1/2]

endpoint idfxx::net::resolve_one	(	std::string_view	host,
		port_number	port,
		const resolver_options &	opts = {}
	)

Resolves a host and numeric port and returns the first matching endpoint.

Parameters

host	Host name or numeric address.
port	Port number in host byte order.
opts	Resolver options.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error

if no endpoint is found or on other failure.

Returns

The first endpoint.

resolve_one() [2/2]

endpoint idfxx::net::resolve_one	(	std::string_view	host,
		std::string_view	service,
		const resolver_options &	opts = {}
	)

Resolves a host and service name and returns the first matching endpoint.

Parameters

host	Host name or numeric address.
service	Service name (e.g. "http") or numeric port string.
opts	Resolver options.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error

if no endpoint is found or on other failure.

Returns

The first endpoint.

try_resolve() [1/2]

result< std::vector< endpoint > > idfxx::net::try_resolve	(	std::string_view	host,
		port_number	port,
		const resolver_options &	opts = {}
	)

Resolves a host and numeric port and collects every endpoint.

Prefer try_resolve_one for the common single-address case, or try_resolve_each to iterate candidates without allocating; this overload exists for callers that want the full result set in a container.

Parameters

host	Host name or numeric address.
port	Port number in host byte order.
opts	Resolver options.

Returns

List of resolved endpoints (may be empty), or an error.

try_resolve() [2/2]

result< std::vector< endpoint > > idfxx::net::try_resolve	(	std::string_view	host,
		std::string_view	service,
		const resolver_options &	opts = {}
	)

Resolves a host and service name and collects every endpoint.

Prefer try_resolve_one for the common single-address case, or try_resolve_each to iterate candidates without allocating; this overload exists for callers that want the full result set in a container.

Parameters

host	Host name or numeric address.
service	Service name (e.g. "http") or numeric port string.
opts	Resolver options.

Returns

List of resolved endpoints, or an error.

try_resolve_each() [1/2]

template<typename F >

result< void > idfxx::net::try_resolve_each	(	std::string_view	host,
		port_number	port,
		F &&	f,
		const resolver_options &	opts = {}
	)

Visits each resolved endpoint for a host and numeric port without allocating.

Template Parameters

F	Callable invoked as f(const endpoint&). If it returns void, every result is visited. If it returns bool, returning false stops the iteration early (e.g. once a connection attempt has succeeded).

Parameters

host	Host name or numeric address.
port	Port number in host byte order.
f	Visitor applied to each resolved endpoint.
opts	Resolver options.

Returns

Success once resolution completes (whether or not the visitor stopped early), or a resolution error.

Definition at line 197 of file resolver.hpp.

try_resolve_each() [2/2]

template<typename F >

result< void > idfxx::net::try_resolve_each	(	std::string_view	host,
		std::string_view	service,
		F &&	f,
		const resolver_options &	opts = {}
	)

Visits each resolved endpoint for a host and service name without allocating.

Template Parameters

F	Callable invoked as f(const endpoint&). If it returns void, every result is visited. If it returns bool, returning false stops the iteration early.

Parameters

host	Host name or numeric address.
service	Service name (e.g. "http") or numeric port string.
f	Visitor applied to each resolved endpoint.
opts	Resolver options.

Returns

Success once resolution completes (whether or not the visitor stopped early), or a resolution error.

Definition at line 241 of file resolver.hpp.

try_resolve_one() [1/2]

result< endpoint > idfxx::net::try_resolve_one	(	std::string_view	host,
		port_number	port,
		const resolver_options &	opts = {}
	)

Resolves a host and numeric port and returns the first matching endpoint.

Parameters

host	Host name or numeric address.
port	Port number in host byte order.
opts	Resolver options.

Returns

The first endpoint, or an error such as errc::name_not_found.

try_resolve_one() [2/2]

result< endpoint > idfxx::net::try_resolve_one	(	std::string_view	host,
		std::string_view	service,
		const resolver_options &	opts = {}
	)

Resolves a host and service name and returns the first matching endpoint.

Parameters

host	Host name or numeric address.
service	Service name (e.g. "http") or numeric port string.
opts	Resolver options.

Returns

The first endpoint, or an error such as errc::name_not_found.