# idfxx_net
Type-safe IP transport API (BSD sockets + Netconn) for ESP-IDF.
π **[Full API Documentation](https://cleishm.github.io/idfxx/group__idfxx__net.html)**
## Features
- Transport-specific RAII socket types β `stream_socket` (TCP), `datagram_socket` (UDP),
`raw_socket` (raw IP)
- `listener` for accepting TCP connections, producing connected `stream_socket` instances
- Single `endpoint` value type for IPv4/IPv6 address-port pairs with parsing and formatting
- DNS resolver: `resolve_one` for the first match, `resolve_each` to iterate candidates without
allocating, and `resolve` for the full `std::vector<endpoint>`
- Named socket option setters and getters with type-safe enums
- Synchronous-with-timeout `connect_for` and `accept_for`
- `stream_socket` and `netconn::stream_channel` model `idfxx::byte_source` via `read` / `try_read`,
so code that consumes a byte stream can read a TCP connection directly
- IPv4 and IPv6 multicast membership (`join_multicast_v4` / `join_multicast_v6`, etc.)
- Lower-level Netconn API (`netconn::stream_channel`, `netconn::datagram_channel`,
`netconn::raw_channel`, `netconn::listener`, `netconn::buffer`) for zero-copy receive
- Compile-time separation of transport-level options β `set_broadcast` exists only on
`datagram_socket` and `set_no_delay` only on `stream_socket`, so applying one to the wrong
transport is a compile error. Family-specific calls (e.g. the `_v4` / `_v6` multicast helpers) are
runtime-checked and return `errc::wrong_protocol_type` on a mismatch.
- Domain-specific error codes that compare equal to standard `std::errc` synonyms
## Requirements
- ESP-IDF 5.5 or later
- C++23 compiler
- A configured network interface (typically via `idfxx_wifi` or `idfxx_eth`)
## Installation
### ESP-IDF Component Manager
Add to your project's `idf_component.yml`:
```yaml
dependencies:
idfxx_net:
version: "^3.0.0"
```
Or add `idfxx_net` to the `REQUIRES` list in your component's `CMakeLists.txt`.
## Usage
### TCP echo server
```cpp
#include <idfxx/log>
#include <idfxx/net/listener>
#include <idfxx/net/stream_socket>
void echo_server() {
using namespace idfxx::net;
listener a(8080);
idfxx::log::info("echo", "listening on {}", a.local_endpoint().value());
while (true) {
auto [client, peer] = a.accept_with_peer();
idfxx::log::info("echo", "accepted {}", peer);
std::array<std::byte, 512> buf;
while (true) {
auto data = client.recv(buf);
if (data.empty()) break;
client.send_all(data);
}
}
}
```
### TCP client with resolver
```cpp
#include <idfxx/log>
#include <idfxx/net/stream_socket>
// The (host, port) constructor resolves the host and tries each returned
// endpoint in turn, returning the first that connects (same as the
// connect_to(host, port) factory). It blocks and throws on failure.
idfxx::net::stream_socket sock("example.com", 80, {.no_delay = true});
sock.set_recv_timeout(std::chrono::seconds(5));
constexpr std::string_view req = "GET / HTTP/1.0\r\nHost: example.com\r\n\r\n";
sock.send_all(req);
std::array<std::byte, 1024> buf;
while (true) {
auto data = sock.recv(buf);
if (data.empty()) break;
idfxx::log::info("client", "got {} bytes", data.size());
}
```
### Reading a TCP stream as a byte source
`read` receives into a byte buffer and returns the byte count, with 0 once the peer has closed the
connection, so a stream socket or channel can be passed to anything written against
`idfxx::byte_source`:
```cpp
#include <idfxx/net/stream_socket>
idfxx::net::stream_socket sock("example.com", 80);
sock.send_all("GET / HTTP/1.0\r\nHost: example.com\r\n\r\n");
std::array<uint8_t, 512> buf;
while (size_t n = sock.read(buf)) {
// process idfxx::byte_view{buf}.first(n)...
}
```
### UDP datagram receiver
```cpp
#include <idfxx/log>
#include <idfxx/net/datagram_socket>
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);
idfxx::log::info("udp", "received {} bytes from {}{}", dg.data.size(), dg.from,
dg.truncated ? " (truncated)" : "");
```
### Result-based API
If `CONFIG_COMPILER_CXX_EXCEPTIONS` is *not* enabled, use the `try_*` methods:
```cpp
#include <idfxx/net/listener>
auto a = idfxx::net::listener::make(8080);
if (!a) {
// handle error
return;
}
auto client = a->try_accept();
if (!client) {
// handle error
return;
}
// use *client (idfxx::net::stream_socket)
```
### Netconn (advanced)
```cpp
#include <idfxx/net/netconn/listener>
#include <idfxx/net/netconn/buffer>
#include <idfxx/net/netconn/stream_channel>
namespace nc = idfxx::net::netconn;
nc::listener srv(8080); // bind + listen in one step
while (true) {
nc::stream_channel client = srv.accept();
while (true) {
nc::buffer buf = client.recv();
if (!buf.is_open()) break; // graceful peer close
for (auto data : buf.segments()) { // idfxx::byte_view per segment
// process data without copying
}
}
}
```
## API Overview
The component provides two API styles:
- **Exception-based API** (requires `CONFIG_COMPILER_CXX_EXCEPTIONS`) β methods throw
`std::system_error` on error
- **Result-based API** (always available) β methods prefixed with `try_*` return `result<T>`
Byte buffers are passed as `idfxx::byte_view` (data to send) and `idfxx::byte_span`
(buffers to receive into), so arrays, vectors and spans of `std::byte` or `uint8_t` all work
directly, as does a `{ptr, len}` pair. `recv` returns a `byte_span` of the bytes received,
at the start of the caller's buffer, and `recv_from` returns the same view in `datagram::data`.
Stream `send` / `send_all` also accept a `std::string_view`.
### Endpoint
`endpoint` carries an IPv4 or IPv6 address paired with a port. Construct from an address and port,
parse a string with `endpoint::parse`, or format with `to_string` / `std::format`.
### Stream Socket
`stream_socket` is the TCP socket type. It is the type returned by `listener::accept` and is
constructed directly for outbound client connections. TCP-only options (`set_no_delay`,
`set_keep_alive`, `set_keep_idle`/`_interval`/`_count`) live on this type.
Connect-on-construct: `connect_to(endpoint)` connects to a known peer; `connect_to(host, port)`
resolves a name and tries each candidate until one connects; the `_for` variants (`connect_to_for`,
`connect_for`) bound the attempt by a timeout. Each factory has a throwing constructor twin.
Key operations: `bind`, `connect`, `connect_for`, `send`, `recv`, `send_all`, `recv_exact`, `read`,
`shutdown`, `wait_readable`, `wait_writable`.
`read(buf)` / `try_read(buf)` receive into an `idfxx::byte_span` and return the number of
bytes received (`size_t` / `result<size_t>`), 0 once the peer has closed the connection (further
reads then fail with `errc::not_connected`); errors, including receive timeouts, are those of
`recv`. They make `stream_socket` an `idfxx::byte_source`.
### Datagram Socket
`datagram_socket` is the UDP socket type. Use `send_to` / `recv_from` for explicit per-message
addressing, or call `connect` to set a default peer for `send` / `recv`. UDP-only options
(`set_broadcast`, multicast membership) are on this type. Multicast helpers come in `_v4` / `_v6`
variants β calling the wrong variant for the socket's family returns `errc::wrong_protocol_type`.
### Raw Socket
`raw_socket` is for raw IP traffic. The IP-layer protocol is set at construction (e.g.
`ip_protocol::icmp`). I/O mirrors `datagram_socket`: `send_to` / `recv_from` for connectionless use,
`send` / `recv` after `connect`.
### Listener
`listener` binds and listens on a TCP address. `accept`, `accept_with_peer`, and
`accept_for(timeout)` return connected `stream_socket` instances.
### Resolver
`resolve_one` / `try_resolve_one` return the first matching `endpoint` β the common case.
`resolve_each` / `try_resolve_each` visit each candidate without allocating; the visitor may return
`bool` to stop early (e.g. once a connection attempt succeeds). `resolve` / `try_resolve` collect
the full set into a `std::vector<endpoint>`. Each accepts either a numeric `port` or a `service`
name.
### Netconn
The `idfxx::net::netconn` namespace mirrors the BSD socket types with a lower-level zero-copy
receive API:
- `netconn::stream_channel` β TCP
- `netconn::datagram_channel` β UDP
- `netconn::raw_channel` β raw IP
- `netconn::listener` β TCP listener; `accept` / `accept_with_peer` produce `stream_channel`s
- `netconn::buffer` β received buffer handle
Every channel exposes `local_endpoint()`; connected `stream_channel` and `datagram_channel` add
`peer_endpoint()` / `try_peer_endpoint()`.
`stream_channel` also has `read(buf)` / `try_read(buf)`, with the same semantics as on
`stream_socket` except that reads after the peer has closed keep returning 0, making it an
`idfxx::byte_source`.
## Error Handling
The `idfxx::net::errc` enum covers transport-layer errors. The error category maps each code to its
`std::errc` synonym (via `default_error_condition`), so callers can compare against either form:
```cpp
auto r = sock.try_send(buf);
if (!r) {
if (r.error() == idfxx::net::errc::operation_would_block ||
r.error() == std::errc::operation_would_block) {
// Non-blocking socket with no buffer space: retry later.
}
}
```
Error codes are organized into two groups:
- Socket-level errors (`operation_would_block`, `timed_out`, `connection_refused`, `address_in_use`,
`name_not_found`, `wrong_protocol_type`, β¦)
- Netconn-level errors (`netconn_aborted`, `netconn_reset`, `netconn_closed`, β¦)
`errc::wrong_protocol_type` is returned when a family-specific operation is called on a socket of a
different family (e.g. `set_multicast_interface_v4` on an IPv6 datagram socket).
## Important Notes
- **Thread safety**: a `close()` from one task while another is blocked in `recv`/`send` is
supported (the blocked task receives an error). For portability, prefer `shutdown()` first. Two
concurrent reads or writes on the same socket are not supported.
- **Move-only**: all socket and connection types are move-only. A moved-from object may only be
destroyed, move-assigned, or queried via `is_open()` (which returns `false`) and `idf_handle()`
(which returns the closed sentinel, `-1` for sockets or `nullptr` for netconn types); calling any
other method on a moved-from object is undefined behavior.
- **`idf_handle()`**: the raw descriptor / `netconn*` accessors are for observation and interop
only. Do not close, free, or change the blocking mode of the returned handle β doing so
desynchronizes the wrapper's invariants.
- **DNS**: by default a single address is returned per query. Enable
`CONFIG_LWIP_USE_ESP_GETADDRINFO` to receive multiple records.
- **Timeouts vs. non-blocking mode**: on a blocking socket, an expired receive or send timeout
(`set_recv_timeout` / `set_send_timeout`, which on a `listener` bounds `accept`) fails the call
with `errc::timed_out`. A non-blocking socket with no data, buffer space, or pending connection
fails immediately with `errc::operation_would_block` instead.
- **Timeout resolution**: receive and send timeouts have millisecond resolution; finer-grained
`chrono` durations are rounded up.
- **Stream receive**: `recv` with an empty buffer returns an empty view at once without receiving;
pass a non-empty buffer to detect the peer closing the connection. If `recv_exact` fails part-way
(for example on a timeout), an unspecified number of bytes have been consumed and the position in
the stream is no longer known.
- **Interface names**: `bind_to_device` enforces an interface-name length limit; longer names return
`errc::invalid_argument`.
- **Netconn**: prefer the BSD socket API for most uses; the Netconn types exist for cases needing
zero-copy receive or finer send-flag control.
- **PBUF exhaustion**: under sustained load lwIP may exhaust its packet buffer pool. Send/receive
paths surface this as `errc::no_buffer_space` (equivalent to `std::errc::no_buffer_space`);
callers should treat it as transient and retry after a short backoff or after draining peer
traffic.
## Hardware tests
Multicast send/receive on Wi-Fi, `bind_to_device` across multiple netifs, and TCP keepalive timing
require physical hardware and are gated behind a `[hw]` Unity tag β they are excluded from QEMU CI
runs.
## License
Apache License 2.0 - see [LICENSE](LICENSE) for details.
57caa7b2aabd577aa3ac24211bda868e980767b0
idf.py add-dependency "cleishm/idfxx_net^3.0.0"