netif.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
// Copyright 2026 Chris Leishman
 
#pragma once
 
#include <idfxx/chrono>
#include <idfxx/error>
#include <idfxx/event>
#include <idfxx/flags>
#include <idfxx/mac>
#include <idfxx/net>
 
#include <array>
#include <cstdint>
#include <optional>
#include <string>
#include <string_view>
#include <utility>
#include <vector>
 
typedef struct esp_netif_obj esp_netif_t;
 
namespace idfxx::netif {
 
// =============================================================================
// Forward declarations
// =============================================================================
 
class interface;
 
// =============================================================================
// Enumerations
// =============================================================================
 
enum class dhcp_option_id : int {
    // clang-format off
    subnet_mask                   = 1,   
    domain_name_server            = 6,   
    router_solicitation_address   = 32,  
    requested_ip_address          = 50,  
    ip_address_lease_time         = 51,  
    ip_request_retry_time         = 52,  
    vendor_class_identifier       = 60,  
    vendor_specific_info          = 43,  
    captiveportal_uri             = 114, 
    // clang-format on
};
 
enum class dns_type : int {
    // clang-format off
    main     = 0, 
    backup   = 1, 
    fallback = 2, 
    // clang-format on
};
 
enum class flag : uint32_t {
    // clang-format off
    dhcp_client             = 1u << 0, 
    dhcp_server             = 1u << 1, 
    autoup                  = 1u << 2, 
    garp                    = 1u << 3, 
    event_ip_modified       = 1u << 4, 
    is_ppp                  = 1u << 5, 
    is_bridge               = 1u << 6, 
    mldv6_report            = 1u << 7, 
    ipv6_autoconfig_enabled = 1u << 8, 
    // clang-format on
};
 
enum class ip_event_id : int32_t {
    // clang-format off
    sta_got_ip4         = 0, 
    sta_lost_ip4        = 1, 
    ap_sta_ip4_assigned = 2, 
    got_ip6            = 3, 
    eth_got_ip4         = 4, 
    eth_lost_ip4        = 5, 
    ppp_got_ip4         = 6, 
    ppp_lost_ip4        = 7, 
    // clang-format on
};
 
} // namespace idfxx::netif
 
template<>
inline constexpr bool idfxx::enable_flags_operators<idfxx::netif::flag> = true;
 
namespace idfxx::netif {
 
// =============================================================================
// Error handling
// =============================================================================
 
enum class errc : esp_err_t {
    // clang-format off
    invalid_params        = 0x5001, 
    if_not_ready          = 0x5002, 
    dhcpc_start_failed    = 0x5003, 
    dhcp_already_started  = 0x5004, 
    dhcp_already_stopped  = 0x5005, 
    no_mem                = 0x5006, 
    dhcp_not_stopped      = 0x5007, 
    driver_attach_failed  = 0x5008, 
    init_failed           = 0x5009, 
    dns_not_configured    = 0x500A, 
    mld6_failed           = 0x500B, 
    ipv6_addr_failed      = 0x500C, 
    dhcps_start_failed    = 0x500D, 
    tx_failed             = 0x500E, 
    // Backward-compatibility alias for the original spelling.
    ip6_addr_failed [[deprecated("use ipv6_addr_failed")]] = ipv6_addr_failed,
    // clang-format on
};
 
class error_category : public std::error_category {
public:
    [[nodiscard]] const char* name() const noexcept override final;
 
    [[nodiscard]] std::string message(int ec) const override final;
};
 
} // namespace idfxx::netif
 
namespace idfxx {
 
[[nodiscard]] const netif::error_category& netif_category() noexcept;
 
[[nodiscard]] std::unexpected<std::error_code> netif_error(esp_err_t e);
 
} // namespace idfxx
 
namespace idfxx::netif {
 
[[nodiscard]] inline std::error_code make_error_code(errc e) noexcept {
    return {std::to_underlying(e), netif_category()};
}
 
} // namespace idfxx::netif
 
namespace std {
template<>
struct is_error_code_enum<idfxx::netif::errc> : std::true_type {};
} // namespace std
 
namespace idfxx::netif {
 
// =============================================================================
// IP events
// =============================================================================
 
extern const event_base<ip_event_id> ip_events;
 
inline event_base<ip_event_id> idfxx_get_event_base(ip_event_id*) {
    return ip_events;
}
// =============================================================================
// Event data wrappers
// =============================================================================
 
struct ip4_event_data {
    net::ipv4_info ip4; 
    bool changed;       
    static ip4_event_data from_opaque(const void* event_data);
};
 
struct ip6_event_data {
    net::ipv6_addr ip; 
    int index;         
    static ip6_event_data from_opaque(const void* event_data);
};
 
struct ap_sta_ip4_assigned_event_data {
    net::ipv4_addr ip; 
    mac_address mac;   
    static ap_sta_ip4_assigned_event_data from_opaque(const void* event_data);
};
 
// =============================================================================
// Typed event constants
// =============================================================================
 
inline constexpr idfxx::event<ip_event_id, ip4_event_data> sta_got_ip4{ip_event_id::sta_got_ip4};
inline constexpr idfxx::event<ip_event_id> sta_lost_ip4{ip_event_id::sta_lost_ip4};
inline constexpr idfxx::event<ip_event_id, ap_sta_ip4_assigned_event_data> ap_sta_ip4_assigned{
    ip_event_id::ap_sta_ip4_assigned
};
inline constexpr idfxx::event<ip_event_id, ip6_event_data> got_ip6{ip_event_id::got_ip6};
inline constexpr idfxx::event<ip_event_id, ip4_event_data> eth_got_ip4{ip_event_id::eth_got_ip4};
inline constexpr idfxx::event<ip_event_id> eth_lost_ip4{ip_event_id::eth_lost_ip4};
inline constexpr idfxx::event<ip_event_id, ip4_event_data> ppp_got_ip4{ip_event_id::ppp_got_ip4};
inline constexpr idfxx::event<ip_event_id> ppp_lost_ip4{ip_event_id::ppp_lost_ip4};
 
// =============================================================================
// DNS info
// =============================================================================
 
struct dns_info {
    net::ipv4_addr ip; 
};
 
// =============================================================================
// interface
// =============================================================================
 
class interface {
public:
    static interface take(esp_netif_t* handle);
 
    static interface wrap(esp_netif_t* handle);
 
    ~interface();
 
    interface(const interface&) = delete;
    interface& operator=(const interface&) = delete;
 
    interface(interface&& other) noexcept
        : _handle(std::exchange(other._handle, nullptr))
        , _owning(other._owning) {}
 
    interface& operator=(interface&& other) noexcept;
 
    [[nodiscard]] esp_netif_t* idf_handle() const noexcept { return _handle; }
 
    // =========================================================================
    // Interface status
    // =========================================================================
 
    [[nodiscard]] bool is_up() const;
 
    [[nodiscard]] const char* key() const;
 
    [[nodiscard]] const char* description() const;
 
    [[nodiscard]] int get_route_priority() const;
 
    void set_route_priority(int priority);
 
    [[nodiscard]] flags<flag> get_flags() const;
 
    [[nodiscard]] idfxx::event<ip_event_id, ip4_event_data> got_ip4_event() const;
 
    [[nodiscard]] idfxx::event<ip_event_id> lost_ip4_event() const;
 
    // =========================================================================
    // MAC address
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] mac_address get_mac() const { return unwrap(try_get_mac()); }
 
    void set_mac(const mac_address& mac) { unwrap(try_set_mac(mac)); }
#endif
 
    [[nodiscard]] result<mac_address> try_get_mac() const;
 
    result<void> try_set_mac(const mac_address& mac);
 
    // =========================================================================
    // Hostname
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] std::string get_hostname() const { return unwrap(try_get_hostname()); }
 
    void set_hostname(std::string_view hostname) { unwrap(try_set_hostname(hostname)); }
#endif
 
    [[nodiscard]] result<std::string> try_get_hostname() const;
 
    result<void> try_set_hostname(std::string_view hostname);
 
    // =========================================================================
    // IPv4
    // =========================================================================
 
    [[nodiscard]] net::ipv4_info get_ipv4_info() const;
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void set_ipv4_info(const net::ipv4_info& info) { unwrap(try_set_ipv4_info(info)); }
#endif
 
    result<void> try_set_ipv4_info(const net::ipv4_info& info);
 
    // Backward-compatibility forwarders for the original spellings.
    [[nodiscard, deprecated("use get_ipv4_info")]] net::ipv4_info get_ip4_info() const { return get_ipv4_info(); }
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[deprecated("use set_ipv4_info")]] void set_ip4_info(const net::ipv4_info& info) { set_ipv4_info(info); }
#endif
    [[deprecated("use try_set_ipv4_info")]] result<void> try_set_ip4_info(const net::ipv4_info& info) {
        return try_set_ipv4_info(info);
    }
 
    // =========================================================================
    // IPv6
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void create_ipv6_linklocal() { unwrap(try_create_ipv6_linklocal()); }
 
    [[nodiscard]] net::ipv6_addr get_ipv6_linklocal() const { return unwrap(try_get_ipv6_linklocal()); }
 
    [[nodiscard]] net::ipv6_addr get_ipv6_global() const { return unwrap(try_get_ipv6_global()); }
#endif
 
    result<void> try_create_ipv6_linklocal();
 
    [[nodiscard]] result<net::ipv6_addr> try_get_ipv6_linklocal() const;
 
    [[nodiscard]] result<net::ipv6_addr> try_get_ipv6_global() const;
 
    [[nodiscard]] std::vector<net::ipv6_addr> get_all_ipv6() const;
 
    [[nodiscard]] std::vector<net::ipv6_addr> get_all_preferred_ipv6() const;
 
    // Backward-compatibility forwarders for the original spellings.
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[deprecated("use create_ipv6_linklocal")]] void create_ip6_linklocal() { create_ipv6_linklocal(); }
    [[nodiscard, deprecated("use get_ipv6_linklocal")]] net::ipv6_addr get_ip6_linklocal() const {
        return get_ipv6_linklocal();
    }
    [[nodiscard, deprecated("use get_ipv6_global")]] net::ipv6_addr get_ip6_global() const { return get_ipv6_global(); }
#endif
    [[deprecated("use try_create_ipv6_linklocal")]] result<void> try_create_ip6_linklocal() {
        return try_create_ipv6_linklocal();
    }
    [[nodiscard, deprecated("use try_get_ipv6_linklocal")]] result<net::ipv6_addr> try_get_ip6_linklocal() const {
        return try_get_ipv6_linklocal();
    }
    [[nodiscard, deprecated("use try_get_ipv6_global")]] result<net::ipv6_addr> try_get_ip6_global() const {
        return try_get_ipv6_global();
    }
    [[nodiscard, deprecated("use get_all_ipv6")]] std::vector<net::ipv6_addr> get_all_ip6() const {
        return get_all_ipv6();
    }
    [[nodiscard, deprecated("use get_all_preferred_ipv6")]] std::vector<net::ipv6_addr> get_all_preferred_ip6() const {
        return get_all_preferred_ipv6();
    }
 
    // =========================================================================
    // DHCP client
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void dhcp_client_start() { unwrap(try_dhcp_client_start()); }
 
    void dhcp_client_stop() { unwrap(try_dhcp_client_stop()); }
#endif
 
    result<void> try_dhcp_client_start();
 
    result<void> try_dhcp_client_stop();
 
    [[nodiscard]] bool is_dhcp_client_running() const;
 
    // =========================================================================
    // DHCP server
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void dhcp_server_start() { unwrap(try_dhcp_server_start()); }
 
    void dhcp_server_stop() { unwrap(try_dhcp_server_stop()); }
#endif
 
    result<void> try_dhcp_server_start();
 
    result<void> try_dhcp_server_stop();
 
    [[nodiscard]] bool is_dhcp_server_running() const;
 
    // =========================================================================
    // DNS
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void set_dns(dns_type type, const dns_info& info) { unwrap(try_set_dns(type, info)); }
 
    [[nodiscard]] dns_info get_dns(dns_type type) const { return unwrap(try_get_dns(type)); }
#endif
 
    result<void> try_set_dns(dns_type type, const dns_info& info);
 
    [[nodiscard]] result<dns_info> try_get_dns(dns_type type) const;
 
    // =========================================================================
    // NAPT
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void napt_enable(bool enable = true) { unwrap(try_napt_enable(enable)); }
#endif
 
    result<void> try_napt_enable(bool enable = true);
 
private:
    interface(esp_netif_t* handle, bool owning) noexcept
        : _handle(handle)
        , _owning(owning) {}
 
    esp_netif_t* _handle = nullptr;
    bool _owning = true;
};
 
// =============================================================================
// Subsystem lifecycle
// =============================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
void init();
 
void deinit();
#endif
 
result<void> try_init();
 
result<void> try_deinit();
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
inline void init() {
    unwrap(try_init());
}
inline void deinit() {
    unwrap(try_deinit());
}
#endif
 
// =============================================================================
// Discovery
// =============================================================================
 
[[nodiscard]] size_t get_nr_of_ifs();
 
[[nodiscard]] std::optional<interface> get_default();
 
void set_default(interface& iface);
 
[[nodiscard]] std::optional<interface> find_by_key(const char* key);
 
// =============================================================================
// SNTP sub-namespace
// =============================================================================
 
namespace sntp {
 
struct config {
    bool smooth_sync = false;                              
    bool server_from_dhcp = false;                         
    bool wait_for_sync = true;                             
    bool start = true;                                     
    bool renew_servers_after_new_ip = false;               
    ip_event_id renew_event_id = ip_event_id::sta_got_ip4; 
    std::vector<std::string> servers;                      
};
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
void init(const config& cfg);
 
void start();
#endif
 
result<void> try_init(const config& cfg);
 
result<void> try_start();
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
inline void init(const config& cfg) {
    unwrap(try_init(cfg));
}
inline void start() {
    unwrap(try_start());
}
#endif
 
void deinit();
 
namespace detail {
[[nodiscard]] bool sync_wait_ms(std::chrono::milliseconds timeout);
} // namespace detail
template<typename Rep, typename Period>
[[nodiscard]] bool sync_wait(const std::chrono::duration<Rep, Period>& timeout) {
    return detail::sync_wait_ms(std::chrono::duration_cast<std::chrono::milliseconds>(timeout));
}
 
} // namespace sntp
 
} // namespace idfxx::netif
 
// =============================================================================
// String conversions (in idfxx namespace)
// =============================================================================
 
namespace idfxx {
 
[[nodiscard]] std::string to_string(netif::dns_type t);
 
} // namespace idfxx
 
#include "sdkconfig.h"
#ifdef CONFIG_IDFXX_STD_FORMAT
#include <algorithm>
#include <format>
namespace std {
 
template<>
struct formatter<idfxx::netif::dns_type> {
    constexpr auto parse(format_parse_context& ctx) { return ctx.begin(); }
 
    template<typename FormatContext>
    auto format(idfxx::netif::dns_type t, FormatContext& ctx) const {
        auto str = idfxx::to_string(t);
        return std::copy(str.begin(), str.end(), ctx.out());
    }
};
 
} // namespace std
#endif // CONFIG_IDFXX_STD_FORMAT