|
idfxx 1.0.0
Modern C++23 components for ESP-IDF
|
A TCP stream socket. More...
Classes | |
| struct | config |
| Stream socket configuration. More... | |
Public Member Functions | |
| stream_socket () | |
| Creates a new TCP socket with default configuration (IPv4, blocking). | |
| stream_socket (address_family fam) | |
| Creates a new TCP socket of the given address family. | |
| stream_socket (const config &cfg) | |
| Creates a new TCP socket with the given configuration. | |
| stream_socket (const endpoint &peer) | |
| Creates a TCP socket and synchronously connects to the peer. | |
| stream_socket (const endpoint &peer, const config &cfg) | |
| Creates a TCP socket with the given configuration and connects to the peer. | |
| stream_socket (std::string_view host, port_number port) | |
Resolves host : port and connects to the first reachable endpoint, using default socket configuration. | |
| stream_socket (std::string_view host, port_number port, const config &cfg, const resolver_options &opts={}) | |
Resolves host : port and connects to the first reachable endpoint. | |
| template<typename Rep , typename Period > | |
| stream_socket (std::string_view host, port_number port, const std::chrono::duration< Rep, Period > &timeout) | |
Resolves host : port and connects to the first reachable endpoint, using default socket configuration and a per-candidate timeout. | |
| template<typename Rep , typename Period > | |
| stream_socket (std::string_view host, port_number port, const std::chrono::duration< Rep, Period > &timeout, const config &cfg, const resolver_options &opts={}) | |
Resolves host : port and connects to the first reachable endpoint, bounding each per-candidate attempt by timeout. | |
| template<typename Rep , typename Period > | |
| void | connect_for (const endpoint &peer, const std::chrono::duration< Rep, Period > &timeout) |
| Connects the socket with a bounded timeout. | |
| template<typename Rep , typename Period > | |
| result< void > | try_connect_for (const endpoint &peer, const std::chrono::duration< Rep, Period > &timeout) |
| Connects the socket with a bounded timeout. | |
| size_t | send (std::span< const std::byte > buf) |
| Sends bytes on the connected socket. | |
| result< size_t > | try_send (std::span< const std::byte > buf) |
| Sends bytes on the connected socket. | |
| size_t | send (std::string_view buf) |
| Sends a string view on the connected socket. | |
| result< size_t > | try_send (std::string_view buf) |
| Sends a string view on the connected socket. | |
| void | send_all (std::span< const std::byte > buf) |
Sends buf in full, retrying on partial sends. | |
| result< void > | try_send_all (std::span< const std::byte > buf) |
Sends buf in full, retrying on partial sends. | |
| void | send_all (std::string_view buf) |
| Sends a string view in full, retrying on partial sends. | |
| result< void > | try_send_all (std::string_view buf) |
| Sends a string view in full, retrying on partial sends. | |
| void | recv_exact (std::span< std::byte > buf) |
Receives until buf is filled, treating premature close as an error. | |
| result< void > | try_recv_exact (std::span< std::byte > buf) |
Receives until buf is filled, treating premature close as an error. | |
| void | shutdown () |
| Shuts down both directions on the socket. | |
| result< void > | try_shutdown () |
| Shuts down both directions on the socket. | |
| void | shutdown (direction dir) |
| Shuts down one direction on the socket (half-close). | |
| result< void > | try_shutdown (direction dir) |
| Shuts down one direction on the socket (half-close). | |
| void | set_no_delay (bool on) noexcept |
| Toggles whether Nagle's algorithm is disabled — when on, small writes are sent immediately rather than being coalesced. | |
| void | set_keep_alive (bool on) noexcept |
| Toggles TCP keep-alive — periodic probes on idle connections to detect dead peers. | |
| template<typename Rep , typename Period > | |
| void | set_keep_idle (const std::chrono::duration< Rep, Period > &t) noexcept |
| Sets the time the connection must be idle before keep-alive probes start. | |
| template<typename Rep , typename Period > | |
| void | set_keep_interval (const std::chrono::duration< Rep, Period > &t) noexcept |
| Sets the interval between successive keep-alive probes. | |
| void | set_keep_count (uint32_t count) noexcept |
| Sets the maximum number of unacknowledged keep-alive probes before the connection is dropped. | |
| bool | get_no_delay () const noexcept |
| Returns whether Nagle's algorithm is currently disabled on this socket. | |
| bool | get_keep_alive () const noexcept |
| Returns whether TCP keep-alive is currently enabled on this socket. | |
Static Public Member Functions | |
| static result< stream_socket > | make () |
| Creates a new TCP socket with default configuration (IPv4, blocking). | |
| static result< stream_socket > | make (address_family fam) |
| Creates a new TCP socket of the given address family. | |
| static result< stream_socket > | make (const config &cfg) |
| Creates a new TCP socket with the given configuration. | |
| static result< stream_socket > | connect_to (const endpoint &peer) |
| Creates a TCP socket and synchronously connects to the peer. | |
| static result< stream_socket > | connect_to (const endpoint &peer, const config &cfg) |
| Creates a TCP socket with the given configuration and connects to the peer. | |
| static result< stream_socket > | connect_to (std::string_view host, port_number port) |
Resolves host : port and connects to the first reachable endpoint, using default socket configuration. | |
| static result< stream_socket > | connect_to (std::string_view host, port_number port, const config &cfg, const resolver_options &opts={}) |
Resolves host : port and connects to the first reachable endpoint. | |
| template<typename Rep , typename Period > | |
| static result< stream_socket > | connect_to_for (std::string_view host, port_number port, const std::chrono::duration< Rep, Period > &timeout) |
Resolves host : port and connects to the first reachable endpoint, using default socket configuration and a per-candidate timeout. | |
| template<typename Rep , typename Period > | |
| static result< stream_socket > | connect_to_for (std::string_view host, port_number port, const std::chrono::duration< Rep, Period > &timeout, const config &cfg, const resolver_options &opts={}) |
Resolves host : port and connects to the first reachable endpoint, bounding each per-candidate attempt by timeout. | |
Friends | |
| class | listener |
A TCP stream socket.
Use idfxx::net::listener to accept inbound connections; this class is for outbound client connections and for the per-connection socket returned by the listener.
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() (which returns false); calling any other method on it is undefined behavior. The destructor closes the socket if open.
The class is [[nodiscard]]: a connect-on-construct temporary that is discarded (e.g. stream_socket{peer}; as a statement) warns, since the connection it just opened would be immediately closed.
Definition at line 58 of file stream_socket.hpp.
| idfxx::net::stream_socket::stream_socket | ( | ) |
Creates a new TCP socket with default configuration (IPv4, blocking).
CONFIG_COMPILER_CXX_EXCEPTIONS is enabled. | std::system_error | on failure. |
|
explicit |
Creates a new TCP socket of the given address family.
| fam | Address family. |
CONFIG_COMPILER_CXX_EXCEPTIONS is enabled. | std::system_error | on failure. |
Creates a new TCP socket with the given configuration.
| cfg | Socket configuration. |
CONFIG_COMPILER_CXX_EXCEPTIONS is enabled. | std::system_error | on failure. |
Creates a TCP socket and synchronously connects to the peer.
Address family is taken from the peer endpoint.
std::system_error on a transient network failure (refused, unreachable, …). For a result-based or timed connect, use the connect_to / connect_to_for factories instead.| peer | Remote endpoint to connect to. |
CONFIG_COMPILER_CXX_EXCEPTIONS is enabled. | std::system_error | on failure. |
Creates a TCP socket with the given configuration and connects to the peer.
Address family is taken from the peer endpoint and overrides cfg.family.
std::system_error on a transient network failure.| peer | Remote endpoint to connect to. |
| cfg | Socket configuration. |
CONFIG_COMPILER_CXX_EXCEPTIONS is enabled. | std::system_error | on failure. |
|
explicit |
Resolves host : port and connects to the first reachable endpoint, using default socket configuration.
Equivalent to connect_to(host, port, {}, {}). See the four-argument overload for the full semantics.
std::system_error on resolution failure or a transient network failure. For a result-based or timed connect, use the connect_to / connect_to_for factories instead.| host | Host name or numeric address. |
| port | Port number in host byte order. |
CONFIG_COMPILER_CXX_EXCEPTIONS is enabled. | std::system_error | on resolution failure or if every candidate fails to connect. |
|
explicit |
Resolves host : port and connects to the first reachable endpoint.
Endpoints are tried in resolution order. The first successful connection wins; if every candidate fails, the last connect error is reported. If resolution succeeds but yields no candidates, throws errc::name_not_found.
std::system_error on resolution failure or a transient network failure.| host | Host name or numeric address. |
| port | Port number in host byte order. |
| cfg | Socket configuration (cfg.family is overridden per candidate). |
| opts | Resolver options. |
CONFIG_COMPILER_CXX_EXCEPTIONS is enabled. | std::system_error | on resolution failure or if every candidate fails to connect. |
|
explicit |
Resolves host : port and connects to the first reachable endpoint, using default socket configuration and a per-candidate timeout.
Equivalent to connect_to_for(host, port, timeout, {}, {}). See the five-argument overload for the full semantics.
std::system_error on resolution failure or a transient network failure. For a result-based connect, use the connect_to_for factory instead.| Rep | Duration representation. |
| Period | Duration period. |
| host | Host name or numeric address. |
| port | Port number in host byte order. |
| timeout | Per-attempt timeout. Sub-millisecond resolutions are rounded up. |
CONFIG_COMPILER_CXX_EXCEPTIONS is enabled. | std::system_error | on resolution failure or if every candidate fails to connect. |
Definition at line 700 of file stream_socket.hpp.
|
inlineexplicit |
Resolves host : port and connects to the first reachable endpoint, bounding each per-candidate attempt by timeout.
The timeout is applied per candidate, not as a total deadline — total time may reach N × timeout if every candidate hangs to the limit.
std::system_error on resolution failure or a transient network failure.| Rep | Duration representation. |
| Period | Duration period. |
| host | Host name or numeric address. |
| port | Port number in host byte order. |
| timeout | Per-attempt timeout. Sub-millisecond resolutions are rounded up. |
| cfg | Socket configuration (cfg.family is overridden per candidate). |
| opts | Resolver options. |
CONFIG_COMPILER_CXX_EXCEPTIONS is enabled. | std::system_error | on resolution failure or if every candidate fails to connect. |
Definition at line 346 of file stream_socket.hpp.
|
inline |
Connects the socket with a bounded timeout.
| peer | Remote endpoint to connect to. |
| timeout | Maximum time to wait for the handshake. Sub-millisecond resolutions are rounded up. |
CONFIG_COMPILER_CXX_EXCEPTIONS is enabled. | std::system_error | if the timeout fires or on other failure. |
Definition at line 416 of file stream_socket.hpp.
References idfxx::timeout, and idfxx::unwrap().
|
static |
Creates a TCP socket and synchronously connects to the peer.
| peer | Remote endpoint to connect to. |
|
static |
Creates a TCP socket with the given configuration and connects to the peer.
| peer | Remote endpoint to connect to. |
| cfg | Socket configuration. |
|
static |
Resolves host : port and connects to the first reachable endpoint, using default socket configuration.
The std::string_view host selects this resolving overload; pass an endpoint to connect directly without resolution.
Equivalent to connect_to(host, port, {}, {}). See the four-argument overload for the full semantics.
| host | Host name or numeric address. |
| port | Port number in host byte order. |
|
static |
Resolves host : port and connects to the first reachable endpoint.
Endpoints are tried in resolution order. The first successful connection wins; if every candidate fails, the last connect error is returned. If resolution succeeds but yields no candidates, returns errc::name_not_found.
| host | Host name or numeric address. |
| port | Port number in host byte order. |
| cfg | Socket configuration (cfg.family is overridden per candidate). |
| opts | Resolver options. |
|
static |
Resolves host : port and connects to the first reachable endpoint, using default socket configuration and a per-candidate timeout.
Equivalent to connect_to_for(host, port, timeout, {}, {}). See the five-argument overload for the full semantics.
| Rep | Duration representation. |
| Period | Duration period. |
| host | Host name or numeric address. |
| port | Port number in host byte order. |
| timeout | Per-attempt timeout. Sub-millisecond resolutions are rounded up. |
errc::timed_out. Definition at line 690 of file stream_socket.hpp.
References connect_to_for(), and idfxx::timeout.
Referenced by connect_to_for().
|
inlinestatic |
Resolves host : port and connects to the first reachable endpoint, bounding each per-candidate attempt by timeout.
The timeout is applied per candidate, not as a total deadline — total time may reach N × timeout if every candidate hangs to the limit. If every candidate fails (with errc::timed_out or otherwise), the last error is returned.
| Rep | Duration representation. |
| Period | Duration period. |
| host | Host name or numeric address. |
| port | Port number in host byte order. |
| timeout | Per-attempt timeout. Sub-millisecond resolutions are rounded up. |
| cfg | Socket configuration (cfg.family is overridden per candidate). |
| opts | Resolver options. |
errc::timed_out. Definition at line 392 of file stream_socket.hpp.
|
noexcept |
Returns whether TCP keep-alive is currently enabled on this socket.
Reads back the POSIX SO_KEEPALIVE option.
|
noexcept |
Returns whether Nagle's algorithm is currently disabled on this socket.
Reads back the POSIX TCP_NODELAY option.
|
static |
Creates a new TCP socket with default configuration (IPv4, blocking).
|
static |
Creates a new TCP socket of the given address family.
| fam | Address family. |
|
static |
Creates a new TCP socket with the given configuration.
| cfg | Socket configuration. |
|
inline |
Receives until buf is filled, treating premature close as an error.
| buf | Buffer to fill exactly. |
CONFIG_COMPILER_CXX_EXCEPTIONS is enabled. | std::system_error | if the peer closes early or on other failure. |
Definition at line 538 of file stream_socket.hpp.
References idfxx::unwrap().
Sends bytes on the connected socket.
May send fewer bytes than requested. See send_all for a helper that retries until the buffer is fully drained.
| buf | Data to send. |
CONFIG_COMPILER_CXX_EXCEPTIONS is enabled. | std::system_error | on failure. |
Definition at line 454 of file stream_socket.hpp.
References idfxx::unwrap().
|
inline |
Sends a string view on the connected socket.
| buf | Data to send. |
CONFIG_COMPILER_CXX_EXCEPTIONS is enabled. | std::system_error | on failure. |
Definition at line 476 of file stream_socket.hpp.
References idfxx::unwrap().
Sends buf in full, retrying on partial sends.
| buf | Data to send. |
CONFIG_COMPILER_CXX_EXCEPTIONS is enabled. | std::system_error | on failure. |
Definition at line 496 of file stream_socket.hpp.
References idfxx::unwrap().
|
inline |
Sends a string view in full, retrying on partial sends.
| buf | Data to send. |
CONFIG_COMPILER_CXX_EXCEPTIONS is enabled. | std::system_error | on failure. |
Definition at line 516 of file stream_socket.hpp.
References idfxx::unwrap().
Toggles TCP keep-alive — periodic probes on idle connections to detect dead peers.
Equivalent to the POSIX SO_KEEPALIVE socket option.
| on | Whether to enable keep-alive. |
Sets the maximum number of unacknowledged keep-alive probes before the connection is dropped.
Equivalent to the POSIX TCP_KEEPCNT option.
| count | Maximum probe count. |
|
inlinenoexcept |
Sets the time the connection must be idle before keep-alive probes start.
Equivalent to the POSIX TCP_KEEPIDLE option. Sub-second resolutions are rounded up.
| t | Idle time. |
Definition at line 626 of file stream_socket.hpp.
|
inlinenoexcept |
Sets the interval between successive keep-alive probes.
Equivalent to the POSIX TCP_KEEPINTVL option. Sub-second resolutions are rounded up.
| t | Interval between probes. |
Definition at line 637 of file stream_socket.hpp.
Toggles whether Nagle's algorithm is disabled — when on, small writes are sent immediately rather than being coalesced.
Equivalent to the POSIX TCP_NODELAY socket option.
| on | Whether to disable Nagle's algorithm. |
|
inline |
Shuts down both directions on the socket.
CONFIG_COMPILER_CXX_EXCEPTIONS is enabled. | std::system_error | on failure. |
Definition at line 559 of file stream_socket.hpp.
References idfxx::unwrap().
Shuts down one direction on the socket (half-close).
The two directions are independent: after shutdown(direction::send) the peer sees end-of-stream but local recv keeps returning any data the peer sends until it closes; after shutdown(direction::receive) further local reads return end-of-stream while sends still succeed.
| dir | Direction to shut down. |
CONFIG_COMPILER_CXX_EXCEPTIONS is enabled. | std::system_error | on failure. |
Definition at line 583 of file stream_socket.hpp.
References idfxx::unwrap().
|
inline |
Connects the socket with a bounded timeout.
Returns once the connection is established, the timeout elapses, or the connection attempt fails.
| peer | Remote endpoint to connect to. |
| timeout | Maximum time to wait for the handshake. Sub-millisecond resolutions are rounded up. |
errc::timed_out. Definition at line 434 of file stream_socket.hpp.
References idfxx::timeout.
Receives until buf is filled, treating premature close as an error.
| buf | Buffer to fill exactly. |
errc::unexpected_eof if the peer closed before buf was fully received). Sends bytes on the connected socket.
| buf | Data to send. |
Sends a string view on the connected socket.
| buf | Data to send. |
Sends buf in full, retrying on partial sends.
| buf | Data to send. |
Sends a string view in full, retrying on partial sends.
| buf | Data to send. |
Shuts down both directions on the socket.
Shuts down one direction on the socket (half-close).
The two directions are independent: after shutdown(direction::send) the peer sees end-of-stream but local recv keeps returning any data the peer sends until it closes; after shutdown(direction::receive) further local reads return end-of-stream while sends still succeed.
| dir | Direction to shut down. |
Definition at line 664 of file stream_socket.hpp.