Data Structures
class	BSDSocketImpl

class	Ipv4Allow
	IPv4 peers that may connect. An empty list allows every peer. More...

struct	Ipv4AllowEntry
	One allowed IPv4 network, network byte order, host bits cleared. More...

class	Ipv4Resolve
	One IPv4 literal or hostname. Must outlive a pending lookup. More...

class	LWIPRawCommon
	Non-virtual common base for LWIP raw TCP sockets. More...

class	LWIPRawImpl
	Connected socket implementation for LWIP raw TCP. More...

class	LWIPRawListenImpl
	Listening socket implementation for LWIP raw TCP. More...

class	LWIPRawUDPImpl
	UDP socket with receive support for LWIP raw API. More...

class	LWIPRawUDPSendImpl
	Send-only UDP socket implementation for LWIP raw API. More...

class	LwIPSocketImpl

class	TcpClientLink
	A reconnecting TCP stream driven from loop(). More...

class	TcpListener
	The server side of a bridged TCP link: owns the listen socket and the allow list, accepts one peer at a time and adopts it into a TcpClientLink, sharing that link's retry clock and connect port. More...

Typedefs
using	Socket = BSDSocketImpl

using	ListenSocket = BSDSocketImpl

using	UDPSendSocket = BSDSocketImpl

using	UDPSocket = BSDSocketImpl

Enumerations
enum class	ConnectPollResult : uint8_t { CONNECT_POLL_RESULT_PENDING , CONNECT_POLL_RESULT_CONNECTED , CONNECT_POLL_RESULT_ERROR }
	Outcome of polling a non-blocking connect(); see socket::poll_connect(). More...

Functions
std::unique_ptr< Socket >	socket (int domain, int type, int protocol)
	Create a socket of the given domain, type and protocol.

std::unique_ptr< Socket >	socket_loop_monitored (int domain, int type, int protocol)
	Create a socket and monitor it for data in the main loop.

	ESPHOME_LOG_TAG (TAG, "socket")

int	lwip_ip_to_sockaddr (sa_family_t family, const ip_addr_t ip, uint16_t port_host, struct sockaddr name, socklen_t *addrlen)
	Convert lwip ip_addr_t + host-order port to sockaddr, based on the socket's address family.

bool	sockaddr_to_lwip (const struct sockaddr addr, socklen_t addrlen, ip_addr_t ip, uint16_t *port)
	Convert sockaddr to lwip ip_addr_t and host-order port.

bool	sockaddr_to_lwip_bind (sa_family_t family, const struct sockaddr addr, socklen_t addrlen, ip_addr_t ip, uint16_t *port)
	sockaddr_to_lwip variant for bind: promotes AF_INET6 sockets to IPADDR_TYPE_ANY so they accept both IPv4 and IPv6 (dual-stack).

int	lwip_err_to_errno (err_t err)
	errno for a failed lwip call

std::unique_ptr< ListenSocket >	socket_listen (int domain, int type, int protocol)
	Create a listening socket of the given domain, type and protocol.

std::unique_ptr< ListenSocket >	socket_listen_loop_monitored (int domain, int type, int protocol)

std::unique_ptr< UDPSendSocket >	socket_udp_send (int domain, int protocol)
	Create a send-only UDP socket (socket_udp_send), a UDP socket with receive support (socket_udp), or a UDP socket monitored for data in the main loop (socket_udp_loop_monitored).

std::unique_ptr< UDPSocket >	socket_udp (int domain, int protocol)

bool	socket_ready (struct lwip_sock *cached_sock)
	Shared ready() helper using cached lwip_sock pointer for direct rcvevent read.

struct lwip_sock *	hook_fd_for_fast_select (int fd)
	Resolve an fd to its lwip_sock and install the netconn event-callback hook so the main loop is woken by FreeRTOS task notifications when data arrives.

bool	socket_ready_fd (int fd, bool loop_monitored)
	Shared ready() helper for fd-based socket implementations.

std::unique_ptr< Socket >	socket_ip (int type, int protocol)
	Create a socket in the newest available IP domain (IPv6 or IPv4) of the given type and protocol.

std::unique_ptr< UDPSocket >	socket_udp_loop_monitored (int domain, int protocol)

std::unique_ptr< UDPSendSocket >	socket_ip_udp_send (int protocol)
	socket_udp* variants using the newest available IP domain.

std::unique_ptr< UDPSocket >	socket_ip_udp (int protocol)

std::unique_ptr< UDPSocket >	socket_ip_udp_loop_monitored (int protocol)

std::unique_ptr< ListenSocket >	socket_ip_loop_monitored (int type, int protocol)

socklen_t	set_sockaddr (struct sockaddr addr, socklen_t addrlen, const char ip_address, uint16_t port)
	Set a sockaddr to the specified address and port for the IP version used by socket_ip().

bool	sockaddr_to_ipv4 (const struct sockaddr addr, uint32_t out)
	Network order IPv4 of an AF_INET or v4 mapped AF_INET6 peer; false for anything else.

socklen_t	set_sockaddr (struct sockaddr *addr, socklen_t addrlen, const std::string &ip_address, uint16_t port)
	Convenience overload for std::string (backward compatible).

socklen_t	set_sockaddr_any (struct sockaddr *addr, socklen_t addrlen, uint16_t port)
	Set a sockaddr to the any address and specified port for the IP version used by socket_ip().

bool	join_multicast_group (UDPSocket sock, const char ip_address, uint32_t *if_index_out=nullptr)
	Join a multicast group on the given socket.

bool	set_ipv6_multicast_if (Socket *sock, uint32_t if_index_in=0)
	Configure the outgoing IPv6 multicast interface on the given socket.

ConnectPollResult	poll_connect (Socket &sock, int &err_out)
	Poll a connect() that returned EINPROGRESS.

size_t	format_sockaddr_to (const struct sockaddr *addr_ptr, socklen_t len, std::span< char, SOCKADDR_STR_LEN > buf)
	Format sockaddr into caller-provided buffer, returns length written (excluding null)

Variables
constexpr int	IP_DOMAIN = AF_INET6

Typedef Documentation

◆ ListenSocket

typedef LWIPRawListenImpl esphome::socket::ListenSocket = BSDSocketImpl

Definition at line 37 of file socket.h.

◆ Socket

typedef LWIPRawImpl esphome::socket::Socket = BSDSocketImpl

Definition at line 36 of file socket.h.

◆ UDPSendSocket

typedef LWIPRawUDPSendImpl esphome::socket::UDPSendSocket = BSDSocketImpl

Definition at line 38 of file socket.h.

◆ UDPSocket

typedef LWIPRawUDPImpl esphome::socket::UDPSocket = BSDSocketImpl

Definition at line 39 of file socket.h.

Enumeration Type Documentation

◆ ConnectPollResult

enum class esphome::socket::ConnectPollResult : uint8_t

strong

Outcome of polling a non-blocking connect(); see socket::poll_connect().

Enumerator
CONNECT_POLL_RESULT_PENDING
CONNECT_POLL_RESULT_CONNECTED
CONNECT_POLL_RESULT_ERROR

Definition at line 224 of file headers.h.

Function Documentation

◆ ESPHOME_LOG_TAG()

esphome::socket::ESPHOME_LOG_TAG	(	TAG	,
		"socket"	)

◆ format_sockaddr_to()

size_t esphome::socket::format_sockaddr_to	(	const struct sockaddr *	addr_ptr,
		socklen_t	len,
		std::span< char, SOCKADDR_STR_LEN >	buf )

Format sockaddr into caller-provided buffer, returns length written (excluding null)

◆ hook_fd_for_fast_select()

struct lwip_sock * esphome::socket::hook_fd_for_fast_select ( int fd )

inline

Resolve an fd to its lwip_sock and install the netconn event-callback hook so the main loop is woken by FreeRTOS task notifications when data arrives.

Shared between BSD and LwIP socket impls on the fast-select path. Returns the cached lwip_sock pointer (or nullptr if the fd does not map to a valid lwip_sock).

Definition at line 77 of file socket.h.

◆ join_multicast_group()

bool esphome::socket::join_multicast_group	(	UDPSocket *	sock,
		const char *	ip_address,
		uint32_t *	if_index_out = nullptr )

Join a multicast group on the given socket.

Parameters

sock	The socket to join on
ip_address	Null-terminated multicast address string (IPv4, or IPv6 except on LWIP_TCP)
if_index_out	If non-null, receives the interface index used (IPv4 always writes 0). For link-local IPv6 groups, the caller must also copy this into sin6_scope_id before bind() – POSIX requires it, LwIP ignores it.

Returns: true on success, false on failure (errno set)

◆ lwip_err_to_errno()

int esphome::socket::lwip_err_to_errno ( err_t err )

errno for a failed lwip call

Definition at line 93 of file lwip_raw_common_impl.cpp.

◆ lwip_ip_to_sockaddr()

int esphome::socket::lwip_ip_to_sockaddr	(	sa_family_t	family,
		const ip_addr_t *	ip,
		uint16_t	port_host,
		struct sockaddr *	name,
		socklen_t *	addrlen )

Convert lwip ip_addr_t + host-order port to sockaddr, based on the socket's address family.

TCP callers pass ntohs(pcb port) to preserve historical getpeername/getsockname output.

Definition at line 11 of file lwip_raw_common_impl.cpp.

◆ poll_connect()

ConnectPollResult esphome::socket::poll_connect	(	Socket &	sock,
		int &	err_out )

inline

Poll a connect() that returned EINPROGRESS.

On error, err_out is SO_ERROR (or errno) on fd implementations and the failure the callbacks recorded on raw lwip.

Definition at line 223 of file socket.h.

◆ set_ipv6_multicast_if()

bool esphome::socket::set_ipv6_multicast_if	(	Socket *	sock,
		uint32_t	if_index_in = 0 )

Configure the outgoing IPv6 multicast interface on the given socket.

Parameters

sock	The socket to configure
if_index_in	Non-zero: use this interface index directly. Zero (default): probe for the first eligible interface via foreach_eligible_ipv6_if(). On single-interface devices (typical for ESP32/ESP8266) this is always correct. On multi-homed hosts the "first eligible" interface is arbitrary; pass the desired index explicitly.

Returns: true on success, false on failure (errno set). A no-op returning true on LWIP_SOCKETS and Zephyr.

◆ set_sockaddr() [1/2]

socklen_t esphome::socket::set_sockaddr	(	struct sockaddr *	addr,
		socklen_t	addrlen,
		const char *	ip_address,
		uint16_t	port )

Set a sockaddr to the specified address and port for the IP version used by socket_ip().

Parameters

addr	Destination sockaddr structure
addrlen	Size of the addr buffer
ip_address	Null-terminated IP address string (IPv4 or IPv6)
port	Port number in host byte order

Returns: Size of the sockaddr structure used, or 0 on error

◆ set_sockaddr() [2/2]

socklen_t esphome::socket::set_sockaddr	(	struct sockaddr *	addr,
		socklen_t	addrlen,
		const std::string &	ip_address,
		uint16_t	port )

inline

Convenience overload for std::string (backward compatible).

Definition at line 192 of file socket.h.

◆ set_sockaddr_any()

socklen_t esphome::socket::set_sockaddr_any	(	struct sockaddr *	addr,
		socklen_t	addrlen,
		uint16_t	port )

Set a sockaddr to the any address and specified port for the IP version used by socket_ip().

◆ sockaddr_to_ipv4()

bool esphome::socket::sockaddr_to_ipv4	(	const struct sockaddr *	addr,
		uint32_t *	out )

Network order IPv4 of an AF_INET or v4 mapped AF_INET6 peer; false for anything else.

addr must hold the family's full struct.

◆ sockaddr_to_lwip()

bool esphome::socket::sockaddr_to_lwip	(	const struct sockaddr *	addr,
		socklen_t	addrlen,
		ip_addr_t *	ip,
		uint16_t *	port )

Convert sockaddr to lwip ip_addr_t and host-order port.

For IPv6, sets type to IPADDR_TYPE_V6 — correct for sendto destinations. Bind paths must use sockaddr_to_lwip_bind() instead.

Definition at line 50 of file lwip_raw_common_impl.cpp.

◆ sockaddr_to_lwip_bind()

bool esphome::socket::sockaddr_to_lwip_bind	(	sa_family_t	family,
		const struct sockaddr *	addr,
		socklen_t	addrlen,
		ip_addr_t *	ip,
		uint16_t *	port )

sockaddr_to_lwip variant for bind: promotes AF_INET6 sockets to IPADDR_TYPE_ANY so they accept both IPv4 and IPv6 (dual-stack).

Definition at line 82 of file lwip_raw_common_impl.cpp.

◆ socket()

std::unique_ptr< Socket > esphome::socket::socket	(	int	domain,
		int	type,
		int	protocol )

Create a socket of the given domain, type and protocol.

Definition at line 101 of file bsd_sockets_impl.cpp.

◆ socket_ip()

std::unique_ptr< Socket > esphome::socket::socket_ip	(	int	type,
		int	protocol )

Create a socket in the newest available IP domain (IPv6 or IPv4) of the given type and protocol.

Not registered with the main loop's select() - use socket_ip_loop_monitored() if you need that.

◆ socket_ip_loop_monitored()

std::unique_ptr< ListenSocket > esphome::socket::socket_ip_loop_monitored	(	int	type,
		int	protocol )

inline

Definition at line 175 of file socket.h.

◆ socket_ip_udp()

std::unique_ptr< UDPSocket > esphome::socket::socket_ip_udp ( int protocol )

inline

Definition at line 154 of file socket.h.

◆ socket_ip_udp_loop_monitored()

std::unique_ptr< UDPSocket > esphome::socket::socket_ip_udp_loop_monitored ( int protocol )

inline

Definition at line 155 of file socket.h.

◆ socket_ip_udp_send()

std::unique_ptr< UDPSendSocket > esphome::socket::socket_ip_udp_send ( int protocol )

inline

socket_udp* variants using the newest available IP domain.

Definition at line 153 of file socket.h.

◆ socket_listen()

std::unique_ptr< ListenSocket > esphome::socket::socket_listen	(	int	domain,
		int	type,
		int	protocol )

inline

Create a listening socket of the given domain, type and protocol.

Create a listening socket and monitor it for data in the main loop. Create a listening socket in the newest available IP domain and monitor it.

Definition at line 892 of file lwip_raw_tcp_impl.cpp.

◆ socket_listen_loop_monitored()

std::unique_ptr< ListenSocket > esphome::socket::socket_listen_loop_monitored	(	int	domain,
		int	type,
		int	protocol )

inline

Definition at line 907 of file lwip_raw_tcp_impl.cpp.

◆ socket_loop_monitored()

std::unique_ptr< Socket > esphome::socket::socket_loop_monitored	(	int	domain,
		int	type,
		int	protocol )

Create a socket and monitor it for data in the main loop.

Like socket() but also registers the socket with the Application's select() loop. WARNING: These functions are NOT thread-safe. They must only be called from the main loop as they register the socket file descriptor with the global Application instance. NOTE: On ESP platforms, FD_SETSIZE is typically 10, limiting the number of monitored sockets. File descriptors >= FD_SETSIZE will not be monitored and will log an error.

Definition at line 105 of file bsd_sockets_impl.cpp.

◆ socket_ready()

bool esphome::socket::socket_ready ( struct lwip_sock * cached_sock )

inline

Shared ready() helper using cached lwip_sock pointer for direct rcvevent read.

cached_sock == nullptr means the socket is not monitored (monitor_loop was false, fd was invalid, or esphome_lwip_get_sock() failed) — in that case return true so the caller attempts the read and handles blocking itself.

Definition at line 69 of file socket.h.

◆ socket_ready_fd()

bool esphome::socket::socket_ready_fd	(	int	fd,
		bool	loop_monitored )

Shared ready() helper for fd-based socket implementations.

Checks if the Application's select() loop has marked this fd as ready.

◆ socket_udp()

std::unique_ptr< UDPSocket > esphome::socket::socket_udp	(	int	domain,
		int	protocol )

inline

Definition at line 317 of file lwip_raw_udp_impl.cpp.

◆ socket_udp_loop_monitored()

std::unique_ptr< UDPSocket > esphome::socket::socket_udp_loop_monitored	(	int	domain,
		int	protocol )

inline

Definition at line 136 of file socket.h.

◆ socket_udp_send()

std::unique_ptr< UDPSendSocket > esphome::socket::socket_udp_send	(	int	domain,
		int	protocol )

inline

Create a send-only UDP socket (socket_udp_send), a UDP socket with receive support (socket_udp), or a UDP socket monitored for data in the main loop (socket_udp_loop_monitored).

Definition at line 306 of file lwip_raw_udp_impl.cpp.

Variable Documentation

◆ IP_DOMAIN

int esphome::socket::IP_DOMAIN = AF_INET6

inlineconstexpr

Definition at line 54 of file socket.h.

Data Structures

Typedefs

Enumerations

Functions

Variables

Typedef Documentation

◆ ListenSocket

◆ Socket

◆ UDPSendSocket

◆ UDPSocket

Enumeration Type Documentation

◆ ConnectPollResult

Function Documentation

◆ ESPHOME_LOG_TAG()

◆ format_sockaddr_to()

◆ hook_fd_for_fast_select()

◆ join_multicast_group()

◆ lwip_err_to_errno()

◆ lwip_ip_to_sockaddr()

◆ poll_connect()

◆ set_ipv6_multicast_if()

◆ set_sockaddr() [1/2]

◆ set_sockaddr() [2/2]

◆ set_sockaddr_any()

◆ sockaddr_to_ipv4()

◆ sockaddr_to_lwip()

◆ sockaddr_to_lwip_bind()

◆ socket()

◆ socket_ip()

◆ socket_ip_loop_monitored()

◆ socket_ip_udp()

◆ socket_ip_udp_loop_monitored()

◆ socket_ip_udp_send()

◆ socket_listen()

◆ socket_listen_loop_monitored()

◆ socket_loop_monitored()

◆ socket_ready()

◆ socket_ready_fd()

◆ socket_udp()

◆ socket_udp_loop_monitored()

◆ socket_udp_send()

Variable Documentation

◆ IP_DOMAIN