Network interface handle. More...

Public Member Functions
	~interface ()

	interface (const interface &)=delete

interface &	operator= (const interface &)=delete

	interface (interface &&other) noexcept
	Move constructs an interface, transferring ownership state.

interface &	operator= (interface &&other) noexcept
	Move assigns an interface, transferring ownership state.

esp_netif_t *	idf_handle () const noexcept
	Returns the underlying ESP-NETIF handle.

bool	is_up () const
	Checks if the network interface is up.

const char *	key () const
	Returns the interface key string.

const char *	description () const
	Returns the interface description string.

int	get_route_priority () const
	Returns the route priority of this interface.

void	set_route_priority (int priority)
	Sets the route priority of this interface.

flags< flag >	get_flags () const
	Returns the flags set on this interface.

idfxx::event< ip_event_id, ip4_event_data >	got_ip4_event () const
	Returns the typed "got IP" event for this interface.

idfxx::event< ip_event_id >	lost_ip4_event () const
	Returns the typed "lost IP" event for this interface.

mac_address	get_mac () const
	Returns the MAC address.

void	set_mac (const mac_address &mac)
	Sets the MAC address.

result< mac_address >	try_get_mac () const
	Returns the MAC address of this interface.

result< void >	try_set_mac (const mac_address &mac)
	Sets the MAC address of this interface.

std::string	get_hostname () const
	Returns the hostname.

void	set_hostname (std::string_view hostname)
	Sets the hostname.

result< std::string >	try_get_hostname () const
	Returns the hostname of this interface.

result< void >	try_set_hostname (std::string_view hostname)
	Sets the hostname of this interface.

net::ip4_info	get_ip4_info () const
	Returns the current IPv4 information of this interface.

void	set_ip4_info (const net::ip4_info &info)
	Sets the IPv4 information.

result< void >	try_set_ip4_info (const net::ip4_info &info)
	Sets the IPv4 information of this interface.

void	create_ip6_linklocal ()
	Creates an IPv6 link-local address for this interface.

net::ip6_addr	get_ip6_linklocal () const
	Returns the IPv6 link-local address.

net::ip6_addr	get_ip6_global () const
	Returns the IPv6 global address.

result< void >	try_create_ip6_linklocal ()
	Creates an IPv6 link-local address for this interface.

result< net::ip6_addr >	try_get_ip6_linklocal () const
	Returns the IPv6 link-local address of this interface.

result< net::ip6_addr >	try_get_ip6_global () const
	Returns the IPv6 global address of this interface.

std::vector< net::ip6_addr >	get_all_ip6 () const
	Returns all IPv6 addresses of this interface.

std::vector< net::ip6_addr >	get_all_preferred_ip6 () const
	Returns all preferred IPv6 addresses of this interface.

void	dhcp_client_start ()
	Starts the DHCP client on this interface.

void	dhcp_client_stop ()
	Stops the DHCP client on this interface.

result< void >	try_dhcp_client_start ()
	Starts the DHCP client on this interface.

result< void >	try_dhcp_client_stop ()
	Stops the DHCP client on this interface.

bool	is_dhcp_client_running () const
	Checks if the DHCP client is running on this interface.

void	dhcp_server_start ()
	Starts the DHCP server on this interface.

void	dhcp_server_stop ()
	Stops the DHCP server on this interface.

result< void >	try_dhcp_server_start ()
	Starts the DHCP server on this interface.

result< void >	try_dhcp_server_stop ()
	Stops the DHCP server on this interface.

bool	is_dhcp_server_running () const
	Checks if the DHCP server is running on this interface.

void	set_dns (dns_type type, const dns_info &info)
	Sets the DNS server information.

dns_info	get_dns (dns_type type) const
	Returns the DNS server information.

result< void >	try_set_dns (dns_type type, const dns_info &info)
	Sets the DNS server information for this interface.

result< dns_info >	try_get_dns (dns_type type) const
	Returns the DNS server information for this interface.

void	napt_enable (bool enable=true)
	Enables or disables NAPT on this interface.

result< void >	try_napt_enable (bool enable=true)
	Enables or disables NAPT (Network Address Port Translation) on this interface.

Static Public Member Functions
static interface	take (esp_netif_t *handle)
	Constructs an owning interface from an `esp_netif_t` handle.

static interface	wrap (esp_netif_t *handle)
	Constructs a non-owning interface from an `esp_netif_t` handle.

Detailed Description

Network interface handle.

Provides access to IP configuration, DHCP, DNS, hostname, and other interface properties.

An interface may be owning or non-owning. Owning interfaces (e.g. from idfxx::wifi::create_default_sta_netif()) stop any running DHCP client/server and release the underlying resource on destruction. Non-owning interfaces (e.g. from get_default() or find_by_key()) provide the same API but do not manage the lifetime — the caller must ensure the underlying interface outlives the wrapper.

auto sta_netif = idfxx::wifi::create_default_sta_netif(); // owning

auto hostname = sta_netif.get_hostname();

idfxx::wifi::create_default_sta_netif

netif::interface create_default_sta_netif()

Creates a default WiFi station network interface.

idfxx::result

std::expected< T, std::error_code > result

result type wrapping a value or error code.

Definition error.hpp:120

Definition at line 354 of file netif.hpp.

Constructor & Destructor Documentation

◆ ~interface()

idfxx::netif::interface::~interface ( )

◆ interface() [1/2]

idfxx::netif::interface::interface ( const interface & )

delete

◆ interface() [2/2]

idfxx::netif::interface::interface ( interface && other )

inlinenoexcept

Move constructs an interface, transferring ownership state.

Parameters

other The interface to move from. Left in a moved-from state.

Definition at line 386 of file netif.hpp.

Member Function Documentation

◆ create_ip6_linklocal()

void idfxx::netif::interface::create_ip6_linklocal ( )

inline

Creates an IPv6 link-local address for this interface.

Exceptions

std::system_error on failure.

Definition at line 567 of file netif.hpp.

References idfxx::unwrap().

◆ description()

const char * idfxx::netif::interface::description ( ) const

Returns the interface description string.

Returns: The interface description, or nullptr if not set.

◆ dhcp_client_start()

void idfxx::netif::interface::dhcp_client_start ( )

inline

Starts the DHCP client on this interface.

Exceptions

std::system_error on failure.

Definition at line 620 of file netif.hpp.

References idfxx::unwrap().

◆ dhcp_client_stop()

void idfxx::netif::interface::dhcp_client_stop ( )

inline

Stops the DHCP client on this interface.

Exceptions

std::system_error on failure.

Definition at line 624 of file netif.hpp.

References idfxx::unwrap().

◆ dhcp_server_start()

void idfxx::netif::interface::dhcp_server_start ( )

inline

Starts the DHCP server on this interface.

Exceptions

std::system_error on failure.

Definition at line 657 of file netif.hpp.

References idfxx::unwrap().

◆ dhcp_server_stop()

void idfxx::netif::interface::dhcp_server_stop ( )

inline

Stops the DHCP server on this interface.

Exceptions

std::system_error on failure.

Definition at line 661 of file netif.hpp.

References idfxx::unwrap().

◆ get_all_ip6()

std::vector< net::ip6_addr > idfxx::netif::interface::get_all_ip6 ( ) const

Returns all IPv6 addresses of this interface.

Returns: A vector of all IPv6 addresses.

◆ get_all_preferred_ip6()

std::vector< net::ip6_addr > idfxx::netif::interface::get_all_preferred_ip6 ( ) const

Returns all preferred IPv6 addresses of this interface.

Returns: A vector of preferred IPv6 addresses.

◆ get_dns()

dns_info idfxx::netif::interface::get_dns ( dns_type type ) const

inline

Returns the DNS server information.

Exceptions

std::system_error on failure.

Definition at line 699 of file netif.hpp.

References idfxx::unwrap().

◆ get_flags()

flags< flag > idfxx::netif::interface::get_flags ( ) const

Returns the flags set on this interface.

Returns: The interface flags.

◆ get_hostname()

std::string idfxx::netif::interface::get_hostname ( ) const

inline

Returns the hostname.

Exceptions

std::system_error on failure.

Definition at line 511 of file netif.hpp.

References idfxx::unwrap().

◆ get_ip4_info()

net::ip4_info idfxx::netif::interface::get_ip4_info ( ) const

Returns the current IPv4 information of this interface.

Returns: The IP info containing address, netmask, and gateway.

◆ get_ip6_global()

net::ip6_addr idfxx::netif::interface::get_ip6_global ( ) const

inline

Returns the IPv6 global address.

Exceptions

std::system_error on failure.

Definition at line 575 of file netif.hpp.

References idfxx::unwrap().

◆ get_ip6_linklocal()

net::ip6_addr idfxx::netif::interface::get_ip6_linklocal ( ) const

inline

Returns the IPv6 link-local address.

Exceptions

std::system_error on failure.

Definition at line 571 of file netif.hpp.

References idfxx::unwrap().

◆ get_mac()

mac_address idfxx::netif::interface::get_mac ( ) const

inline

Returns the MAC address.

Not supported on PPP interfaces.

Exceptions

std::system_error on failure.

Definition at line 478 of file netif.hpp.

References idfxx::unwrap().

◆ get_route_priority()

int idfxx::netif::interface::get_route_priority ( ) const

Returns the route priority of this interface.

Returns: The route priority value.

◆ got_ip4_event()

idfxx::event< ip_event_id, ip4_event_data > idfxx::netif::interface::got_ip4_event ( ) const

Returns the typed "got IP" event for this interface.

The returned event can be used to register a listener that fires when this interface acquires an IPv4 address, regardless of interface type.

Returns: The typed event with ip4_event_data data.

◆ idf_handle()

esp_netif_t * idfxx::netif::interface::idf_handle ( ) const

inlinenoexcept

Returns the underlying ESP-NETIF handle.

Returns: The raw ESP-NETIF handle.

Definition at line 403 of file netif.hpp.

◆ is_dhcp_client_running()

bool idfxx::netif::interface::is_dhcp_client_running ( ) const

Checks if the DHCP client is running on this interface.

Returns: True if the DHCP client is started.

◆ is_dhcp_server_running()

bool idfxx::netif::interface::is_dhcp_server_running ( ) const

Checks if the DHCP server is running on this interface.

Returns: True if the DHCP server is started.

◆ is_up()

bool idfxx::netif::interface::is_up ( ) const

Checks if the network interface is up.

Returns: True if the interface is up.

◆ key()

const char * idfxx::netif::interface::key ( ) const

Returns the interface key string.

Returns: The interface key, or nullptr if not set.

◆ lost_ip4_event()

idfxx::event< ip_event_id > idfxx::netif::interface::lost_ip4_event ( ) const

Returns the typed "lost IP" event for this interface.

The returned event can be used to register a listener that fires when this interface loses its IPv4 address, regardless of interface type.

Returns: The typed event (no data).

◆ napt_enable()

void idfxx::netif::interface::napt_enable ( bool enable = true )

inline

Enables or disables NAPT on this interface.

Exceptions

std::system_error on failure.

Definition at line 726 of file netif.hpp.

References idfxx::unwrap().

◆ operator=() [1/2]

interface & idfxx::netif::interface::operator= ( const interface & )

delete

◆ operator=() [2/2]

interface & idfxx::netif::interface::operator= ( interface && other )

noexcept

Move assigns an interface, transferring ownership state.

Parameters

other The interface to move from. Left in a moved-from state.

Returns: Reference to this.

◆ set_dns()

void idfxx::netif::interface::set_dns	(	dns_type	type,
		const dns_info &	info
	)

inline

Sets the DNS server information.

Exceptions

std::system_error on failure.

Definition at line 695 of file netif.hpp.

References idfxx::unwrap().

◆ set_hostname()

void idfxx::netif::interface::set_hostname ( std::string_view hostname )

inline

Sets the hostname.

Exceptions

std::system_error on failure.

Definition at line 515 of file netif.hpp.

References idfxx::unwrap().

◆ set_ip4_info()

void idfxx::netif::interface::set_ip4_info ( const net::ip4_info & info )

inline

Sets the IPv4 information.

Fails if DHCP is running.

Exceptions

std::system_error on failure.

Definition at line 547 of file netif.hpp.

References idfxx::unwrap().

◆ set_mac()

void idfxx::netif::interface::set_mac ( const mac_address & mac )

inline

Sets the MAC address.

Not supported on PPP interfaces.

Exceptions

std::system_error on failure.

Definition at line 482 of file netif.hpp.

References idfxx::unwrap().

◆ set_route_priority()

void idfxx::netif::interface::set_route_priority ( int priority )

Sets the route priority of this interface.

Parameters

priority The route priority value to set.

◆ take()

static interface idfxx::netif::interface::take ( esp_netif_t * handle )

static

Constructs an owning interface from an esp_netif_t handle.

Takes ownership of the handle and will destroy it on destruction. The handle must not be null.

Parameters

handle A non-null esp_netif_t handle.

◆ try_create_ip6_linklocal()

result< void > idfxx::netif::interface::try_create_ip6_linklocal ( )

Creates an IPv6 link-local address for this interface.

Returns: Result indicating success or an error code.

◆ try_dhcp_client_start()

result< void > idfxx::netif::interface::try_dhcp_client_start ( )

Starts the DHCP client on this interface.

Return values

dhcp_already_started if the DHCP client is already running.

Returns: Result indicating success or an error code.

◆ try_dhcp_client_stop()

result< void > idfxx::netif::interface::try_dhcp_client_stop ( )

Stops the DHCP client on this interface.

Return values

dhcp_already_stopped if the DHCP client is not running.

Returns: Result indicating success or an error code.

◆ try_dhcp_server_start()

result< void > idfxx::netif::interface::try_dhcp_server_start ( )

Starts the DHCP server on this interface.

Return values

dhcps_start_failed	if the DHCP server failed to start.
dhcp_already_started	if the DHCP server is already running.

Returns: Result indicating success or an error code.

◆ try_dhcp_server_stop()

result< void > idfxx::netif::interface::try_dhcp_server_stop ( )

Stops the DHCP server on this interface.

Return values

dhcp_already_stopped if the DHCP server is not running.

Returns: Result indicating success or an error code.

◆ try_get_dns()

result< dns_info > idfxx::netif::interface::try_get_dns ( dns_type type ) const

Returns the DNS server information for this interface.

Parameters

type	The DNS server type to query.

Returns: Result containing the DNS info, or an error code.

◆ try_get_hostname()

result< std::string > idfxx::netif::interface::try_get_hostname ( ) const

Returns the hostname of this interface.

Returns: Result containing the hostname, or an error code.

◆ try_get_ip6_global()

result< net::ip6_addr > idfxx::netif::interface::try_get_ip6_global ( ) const

Returns the IPv6 global address of this interface.

Returns: Result containing the IPv6 global address, or an error code.

◆ try_get_ip6_linklocal()

result< net::ip6_addr > idfxx::netif::interface::try_get_ip6_linklocal ( ) const

Returns the IPv6 link-local address of this interface.

Returns: Result containing the IPv6 link-local address, or an error code.

◆ try_get_mac()

result< mac_address > idfxx::netif::interface::try_get_mac ( ) const

Returns the MAC address of this interface.

Not supported on point-to-point (PPP) interfaces.

Returns: Result containing the MAC address, or an error code.

◆ try_napt_enable()

result< void > idfxx::netif::interface::try_napt_enable ( bool enable = true )

Enables or disables NAPT (Network Address Port Translation) on this interface.

Parameters

enable True to enable NAPT, false to disable.

Returns: Result indicating success or an error code.

◆ try_set_dns()

result< void > idfxx::netif::interface::try_set_dns	(	dns_type	type,
		const dns_info &	info
	)

Sets the DNS server information for this interface.

Parameters

type	The DNS server type (main, backup, or fallback).
info	The DNS server information.

Returns: Result indicating success or an error code.

◆ try_set_hostname()

result< void > idfxx::netif::interface::try_set_hostname ( std::string_view hostname )

Sets the hostname of this interface.

Parameters

hostname The hostname to set.

Returns: Result indicating success or an error code.

◆ try_set_ip4_info()

result< void > idfxx::netif::interface::try_set_ip4_info ( const net::ip4_info & info )

Sets the IPv4 information of this interface.

Fails if the DHCP client or server is running on this interface.

Parameters

info	The IP info to set.

Returns: Result indicating success or an error code.

◆ try_set_mac()

result< void > idfxx::netif::interface::try_set_mac ( const mac_address & mac )

Sets the MAC address of this interface.

Not supported on point-to-point (PPP) interfaces.

Parameters

mac	The MAC address to set.

Returns: Result indicating success or an error code.

◆ wrap()

static interface idfxx::netif::interface::wrap ( esp_netif_t * handle )

static

Constructs a non-owning interface from an esp_netif_t handle.

Does not take ownership. The caller must ensure the handle remains valid for the lifetime of this object.

Parameters

handle A non-null esp_netif_t handle.

References idfxx::wrap().

The documentation for this class was generated from the following file:

idfxx_netif/include/idfxx/netif.hpp

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~interface()

◆ interface() [1/2]

◆ interface() [2/2]

Member Function Documentation

◆ create_ip6_linklocal()

◆ description()

◆ dhcp_client_start()

◆ dhcp_client_stop()

◆ dhcp_server_start()

◆ dhcp_server_stop()

◆ get_all_ip6()

◆ get_all_preferred_ip6()

◆ get_dns()

◆ get_flags()

◆ get_hostname()

◆ get_ip4_info()

◆ get_ip6_global()

◆ get_ip6_linklocal()

◆ get_mac()

◆ get_route_priority()

◆ got_ip4_event()

◆ idf_handle()

◆ is_dhcp_client_running()

◆ is_dhcp_server_running()

◆ is_up()

◆ key()

◆ lost_ip4_event()

◆ napt_enable()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ set_dns()

◆ set_hostname()

◆ set_ip4_info()

◆ set_mac()

◆ set_route_priority()

◆ take()

◆ try_create_ip6_linklocal()

◆ try_dhcp_client_start()

◆ try_dhcp_client_stop()

◆ try_dhcp_server_start()

◆ try_dhcp_server_stop()

◆ try_get_dns()

◆ try_get_hostname()

◆ try_get_ip6_global()

◆ try_get_ip6_linklocal()

◆ try_get_mac()

◆ try_napt_enable()

◆ try_set_dns()

◆ try_set_hostname()

◆ try_set_ip4_info()

◆ try_set_mac()

◆ wrap()