nl::Inet::InterfaceAddressIterator

#include <src/inet/InetInterface.h>

Iterator for the list of system network interface IP addresses.

Summary

Use objects of this class to iterate the list of system network interface interface IP addresses.

Methods on an individual instance of this class are not thread-safe; however separate instances may be used simultaneously by multiple threads.

On multi-threaded LwIP systems, instances are thread-safe relative to other threads accessing the global LwIP state provided that: 1) other threads hold the LwIP core lock while mutating the list of netifs; and 2) netif object themselves are never destroyed.

On sockets-based systems, iteration is always stable in the face of changes to the underlying system's interfaces and/or addresses.

On LwIP systems, iteration is stable except in the case where the interface associated with the current address is removed, in which case iteration may end prematurely.

Constructors and Destructors
InterfaceAddressIterator(void)
Constructs an InterfaceAddressIterator object.
~InterfaceAddressIterator(void)
Destroys an InterfaceAddressIterator object.

Public functions
GetAddress(void)
Get the current interface address.
GetAddressWithPrefix(IPPrefix & addrWithPrefix)
void
Returns an IPPrefix containing the address and prefix length for the current address.
GetIPv6PrefixLength(void)
uint8_t
Deprecated alias for GetPrefixLength(void)
GetInterface(void)
InterfaceId
Deprecated alias for GetInterfaceId(void)
GetInterfaceId(void)
InterfaceId
Returns the network interface id associated with the current interface address.
GetInterfaceName(char *nameBuf, size_t nameBufSize)
Get the name of the network interface associated with the current interface address.
GetPrefixLength(void)
uint8_t
Gets the network prefix associated with the current interface address.
HasBroadcastAddress(void)
bool
Returns whether the network interface associated with the current interface address has an IPv4 broadcast address.
HasCurrent(void)
bool
IsUp(void)
bool
Returns whether the network interface associated with the current interface address is up.
Next(void)
bool
Advance the iterator to the next interface address.
SupportsMulticast(void)
bool
Returns whether the network interface associated with the current interface address supports multicast.

Public functions

GetAddress

IPAddress GetAddress(
  void
)

Get the current interface address.

Details
Returns
the current interface address or IPAddress::Any if the iterator is positioned beyond the end of the address list.

GetAddressWithPrefix

void GetAddressWithPrefix(
  IPPrefix & addrWithPrefix
)

Returns an IPPrefix containing the address and prefix length for the current address.

GetIPv6PrefixLength

uint8_t GetIPv6PrefixLength(
  void
)

Deprecated alias for GetPrefixLength(void)

GetInterface

InterfaceId GetInterface(
  void
)

Deprecated alias for GetInterfaceId(void)

GetInterfaceId

InterfaceId GetInterfaceId(
  void
)

Returns the network interface id associated with the current interface address.

Details
Returns
the interface id or INET_NULL_INTERFACEID if the iterator is positioned beyond the end of the address list.

GetInterfaceName

INET_ERROR GetInterfaceName(
  char *nameBuf,
  size_t nameBufSize
)

Get the name of the network interface associated with the current interface address. 

Writes the name of the network interface as \c NUL terminated text string
at \c nameBuf.

Details
Parameters
[in] nameBuf
region of memory to write the interface name
[in] nameBufSize
size of the region denoted by nameBuf
Return Values
INET_NO_ERROR
successful result, interface name written
INET_ERROR_NO_MEMORY
name is too large to be written in buffer
INET_ERROR_INCORRECT_STATE
the iterator is not currently positioned on an interface address
other
another system or platform error

GetPrefixLength

uint8_t GetPrefixLength(
  void
)

Gets the network prefix associated with the current interface address. 

On LwIP, this method simply returns the hard-coded constant 64.

Note Well: the standard subnet prefix on all links other than PPP
links is 64 bits. On PPP links and some non-broadcast multipoint access
links, the convention is either 127 bits or 128 bits, but it might be
something else. On most platforms, the system's interface address
structure can represent arbitrary prefix lengths between 0 and 128.

Details
Returns
the network prefix (in bits) or 0 if the iterator is positioned beyond the end of the address list.

HasBroadcastAddress

bool HasBroadcastAddress(
  void
)

Returns whether the network interface associated with the current interface address has an IPv4 broadcast address.

Details
Returns
true if the interface has a broadcast address, false if not, or if the iterator is not positioned on an interface address.

HasCurrent

bool HasCurrent(
  void
)

InterfaceAddressIterator

 InterfaceAddressIterator(
  void
)

Constructs an InterfaceAddressIterator object.

Starts the iterator at the first network address. On some platforms, this constructor may allocate resources recycled by the destructor.

IsUp

bool IsUp(
  void
)

Returns whether the network interface associated with the current interface address is up.

Details
Returns
true if current network interface is up, false if not, or if the iterator is not positioned on an interface address.

Next

bool Next(
  void
)

Advance the iterator to the next interface address. 

Advances the iterator to the next interface address or to a position
beyond the end of the address list.

On LwIP, this method is thread-safe provided that: 1) other threads hold
the LwIP core lock while mutating the netif list; and 2) netif objects
themselves are never destroyed.  Additionally, iteration on LwIP systems
will terminate early if the current interface is removed from the list.

Details
Returns
false if advanced beyond the end, else true.

SupportsMulticast

bool SupportsMulticast(
  void
)

Returns whether the network interface associated with the current interface address supports multicast.

Details
Returns
true if multicast is supported, false if not, or if the iterator is not positioned on an interface address.

~InterfaceAddressIterator

 ~InterfaceAddressIterator(
  void
)

Destroys an InterfaceAddressIterator object.

Recycles any resources allocated by the constructor.