socket.h

Go to the documentation of this file.

#pragma once
#include <memory>
#include <span>
#include <string>
 
#include "esphome/core/optional.h"
#include "headers.h"
 
#ifdef USE_LWIP_FAST_SELECT
#include "esphome/core/lwip_fast_select.h"
#endif
 
#if defined(USE_SOCKET_IMPL_LWIP_TCP) || defined(USE_SOCKET_IMPL_LWIP_SOCKETS) || defined(USE_SOCKET_IMPL_BSD_SOCKETS)
 
// Include only the active implementation's header.
// SOCKADDR_STR_LEN is defined in headers.h.
#ifdef USE_SOCKET_IMPL_BSD_SOCKETS
#include "bsd_sockets_impl.h"
#elif defined(USE_SOCKET_IMPL_LWIP_SOCKETS)
#include "lwip_sockets_impl.h"
#elif defined(USE_SOCKET_IMPL_LWIP_TCP)
#include "lwip_raw_tcp_impl.h"
#include "lwip_raw_udp_impl.h"
#endif
 
namespace esphome::socket {
 
// Type aliases — only one implementation is active per build.
// Socket is the concrete type for connected sockets.
// ListenSocket is the concrete type for listening/server sockets.
// UDPSocket is the concrete type for UDP sockets (send + receive).
// UDPSendSocket is the concrete type for send-only UDP sockets.
// On BSD and LWIP_SOCKETS, all aliases resolve to the same type.
// On LWIP_TCP, they are different types (no virtual dispatch between them).
#ifdef USE_SOCKET_IMPL_BSD_SOCKETS
using Socket = BSDSocketImpl;
using ListenSocket = BSDSocketImpl;
using UDPSendSocket = BSDSocketImpl;
using UDPSocket = BSDSocketImpl;
#elif defined(USE_SOCKET_IMPL_LWIP_SOCKETS)
using Socket = LwIPSocketImpl;
using ListenSocket = LwIPSocketImpl;
using UDPSendSocket = LwIPSocketImpl;
using UDPSocket = LwIPSocketImpl;
#elif defined(USE_SOCKET_IMPL_LWIP_TCP)
using Socket = LWIPRawImpl;
using ListenSocket = LWIPRawListenImpl;
using UDPSendSocket = LWIPRawUDPSendImpl;
using UDPSocket = LWIPRawUDPImpl;
#endif
 
// Domain used by the socket_ip_* helpers: newest available IP domain.
#if USE_NETWORK_IPV6
inline constexpr int IP_DOMAIN = AF_INET6;
#else
inline constexpr int IP_DOMAIN = AF_INET;
#endif
 
// IPv6 sockets with multicast membership; the raw lwIP implementation has no IPv6 membership support.
#if USE_NETWORK_IPV6 && (defined(USE_SOCKET_IMPL_BSD_SOCKETS) || defined(USE_SOCKET_IMPL_LWIP_SOCKETS))
#define USE_SOCKET_IPV6
#endif
 
#ifdef USE_LWIP_FAST_SELECT
inline bool socket_ready(struct lwip_sock *cached_sock) {
  return cached_sock == nullptr || esphome_lwip_socket_has_data(cached_sock);
}
 
inline struct lwip_sock *hook_fd_for_fast_select(int fd) {
  struct lwip_sock *sock = esphome_lwip_get_sock(fd);
  if (sock != nullptr) {
    esphome_lwip_hook_socket(sock);
  }
  return sock;
}
#elif defined(USE_HOST) || defined(USE_ZEPHYR)
bool socket_ready_fd(int fd, bool loop_monitored);
#endif  // USE_LWIP_FAST_SELECT
 
// Inline ready() — defined here because it depends on socket_ready/socket_ready_fd
// declared above, while the impl headers are included before those declarations.
//
// Contract (applies to ALL socket implementations — each platform implements
// ready() differently, but this contract holds regardless of the mechanism):
// ready() checks if the socket has buffered data ready to read. When it returns
// true, the caller MUST read until it would block (EAGAIN/EWOULDBLOCK), or until
// read() returns 0 to indicate EOF / connection closed, or track that it stopped
// early and retry without calling ready(). The next call to ready() will only
// report new data correctly if all callers fulfill this contract. Failing to
// drain the socket may cause ready() to return false while data remains readable.
//
// In practice each socket is owned by a single component, so this contract is
// straightforward to fulfill — but the owning component must be aware of it,
// especially if it limits how many messages it processes per loop iteration.
#if defined(USE_SOCKET_IMPL_BSD_SOCKETS) || defined(USE_SOCKET_IMPL_LWIP_SOCKETS)
inline bool Socket::ready() const {
#ifdef USE_LWIP_FAST_SELECT
  return socket_ready(this->cached_sock_);
#else
  return socket_ready_fd(this->fd_, this->loop_monitored_);
#endif
}
#endif
 
std::unique_ptr<Socket> socket(int domain, int type, int protocol);
std::unique_ptr<Socket> socket_ip(int type, int protocol);
 
std::unique_ptr<Socket> socket_loop_monitored(int domain, int type, int protocol);
 
#ifdef USE_SOCKET_IMPL_LWIP_TCP
std::unique_ptr<UDPSendSocket> socket_udp_send(int domain, int protocol);
std::unique_ptr<UDPSocket> socket_udp(int domain, int protocol);
// Wake is built into the recv callback, so monitoring needs nothing extra.
inline std::unique_ptr<UDPSocket> socket_udp_loop_monitored(int domain, int protocol) {
  return socket_udp(domain, protocol);
}
#else
inline std::unique_ptr<UDPSendSocket> socket_udp_send(int domain, int protocol) {
  return esphome::socket::socket(domain, SOCK_DGRAM, protocol);
}
inline std::unique_ptr<UDPSocket> socket_udp(int domain, int protocol) {
  return esphome::socket::socket(domain, SOCK_DGRAM, protocol);
}
// Registers the socket with the Application's select() loop.
inline std::unique_ptr<UDPSocket> socket_udp_loop_monitored(int domain, int protocol) {
  return socket_loop_monitored(domain, SOCK_DGRAM, protocol);
}
#endif
 
inline std::unique_ptr<UDPSendSocket> socket_ip_udp_send(int protocol) { return socket_udp_send(IP_DOMAIN, protocol); }
inline std::unique_ptr<UDPSocket> socket_ip_udp(int protocol) { return socket_udp(IP_DOMAIN, protocol); }
inline std::unique_ptr<UDPSocket> socket_ip_udp_loop_monitored(int protocol) {
  return socket_udp_loop_monitored(IP_DOMAIN, protocol);
}
 
#ifdef USE_SOCKET_IMPL_LWIP_TCP
// LWIP_TCP has separate Socket/ListenSocket types — needs distinct factory functions.
std::unique_ptr<ListenSocket> socket_listen(int domain, int type, int protocol);
std::unique_ptr<ListenSocket> socket_listen_loop_monitored(int domain, int type, int protocol);
#else
// BSD and LWIP_SOCKETS: Socket == ListenSocket, so listen variants just delegate.
inline std::unique_ptr<ListenSocket> socket_listen(int domain, int type, int protocol) {
  return socket(domain, type, protocol);
}
inline std::unique_ptr<ListenSocket> socket_listen_loop_monitored(int domain, int type, int protocol) {
  return socket_loop_monitored(domain, type, protocol);
}
#endif
inline std::unique_ptr<ListenSocket> socket_ip_loop_monitored(int type, int protocol) {
  return socket_listen_loop_monitored(IP_DOMAIN, type, protocol);
}
 
socklen_t set_sockaddr(struct sockaddr *addr, socklen_t addrlen, const char *ip_address, uint16_t port);
 
bool sockaddr_to_ipv4(const struct sockaddr *addr, uint32_t *out);
 
inline socklen_t set_sockaddr(struct sockaddr *addr, socklen_t addrlen, const std::string &ip_address, uint16_t port) {
  return set_sockaddr(addr, addrlen, ip_address.c_str(), port);
}
 
socklen_t set_sockaddr_any(struct sockaddr *addr, socklen_t addrlen, uint16_t port);
 
bool join_multicast_group(UDPSocket *sock, const char *ip_address, uint32_t *if_index_out = nullptr);
 
#if defined(USE_SOCKET_IMPL_BSD_SOCKETS) || defined(USE_SOCKET_IMPL_LWIP_SOCKETS)
#if USE_NETWORK_IPV6
bool set_ipv6_multicast_if(Socket *sock, uint32_t if_index_in = 0);
#endif  // USE_NETWORK_IPV6
#endif  // USE_SOCKET_IMPL_BSD_SOCKETS || USE_SOCKET_IMPL_LWIP_SOCKETS
 
#ifdef USE_SOCKET_IMPL_LWIP_TCP
inline ConnectPollResult poll_connect(Socket &sock, int &err_out) { return sock.poll_connect(err_out); }
#else
ConnectPollResult poll_connect(Socket &sock, int &err_out);
#endif
 
size_t format_sockaddr_to(const struct sockaddr *addr_ptr, socklen_t len, std::span<char, SOCKADDR_STR_LEN> buf);
 
}  // namespace esphome::socket
#endif