nl::Inet::IPAddress

#include <src/inet/IPAddress.h>

Internet protocol address.

Summary

The Nest Inet Layer uses objects of this class to represent Internet protocol addresses (independent of protocol version).

Public attributes

Addr[4]
uint32_t
Opaque word array to contain IP addresses (independent of protocol version)

Public static attributes

Any
The distinguished unspecified IP address object.

Public functions

GlobalId(void) const
uint64_t
Extract the 16-bit global network identifier of an IPv6 ULA address.
InterfaceId(void) const
uint64_t
Extract the IID of an IPv6 ULA address.
IsIPv4(void) const
bool
Test whether address is IPv4 compatible.
IsIPv4Broadcast(void) const
bool
Test whether address is IPv4 broadcast.
IsIPv4Multicast(void) const
bool
Test whether address is IPv4 multicast.
IsIPv6(void) const
bool
Test whether address is IPv6 compatible.
IsIPv6GlobalUnicast(void) const
bool
Test whether address is IPv6 global unicast address.
IsIPv6LinkLocal(void) const
bool
Test whether address is IPv6 link-local address (LL).
IsIPv6Multicast(void) const
bool
Test whether address is IPv6 multicast.
IsIPv6ULA(void) const
bool
Test whether address is IPv6 unique-local address (ULA).
IsMulticast(void) const
bool
Test whether address is IPv4 or IPv6 multicast.
Subnet(void) const
uint16_t
Extract the 16-bit subnet identifier of an IPv6 ULA address.
ToIPv4(void) const
Extract the IPv4 address as a platform data structure.
ToIPv4(void) const
struct in_addr
ToIPv6(void) const
ip6_addr_t
Extract the IPv6 address as a platform data structure.
ToIPv6(void) const
struct in6_addr
ToString(char *buf, uint32_t bufSize) const
char *
Emit the IP address in conventional text presentation format.
Type(void) const
IPAddressType
Extract the type of the IP address.
WriteAddress(uint8_t *& p) const
void
Emit the IP address in standard network representation.
operator!=(const IPAddress & other) const
bool
Compare this IP address with another for inequivalence.
operator=(const IPAddress & other)
Conventional assignment operator.
operator==(const IPAddress & other) const
bool
Compare this IP address with another for equivalence.

Public static functions

FromIPv4(const ip4_addr_t & addr)
FromIPv4(const struct in_addr & addr)
Inject the IPv4 address from a platform data structure.
FromIPv6(const ip6_addr_t & addr)
FromIPv6(const struct in6_addr & addr)
Inject the IPv6 address from a platform data structure.
FromSockAddr(const struct sockaddr & sockaddr)
Inject the IPv6 address from a POSIX struct sockaddr&
FromString(const char *str, IPAddress & output)
bool
Scan the IP address from its conventional presentation text.
FromString(const char *str, size_t strLen, IPAddress & output)
bool
Scan the IP address from its conventional presentation text.
MakeIPv4Broadcast(void)
Construct an IPv4 broadcast address.
MakeIPv6Multicast(uint8_t aFlags, uint8_t aScope, const uint8_t aGroupId[NL_INET_IPV6_MCAST_GROUP_LEN_IN_BYTES])
Construct an IPv6 multicast address from its parts.
MakeIPv6Multicast(uint8_t aFlags, uint8_t aScope, uint32_t aGroupId)
Construct an IPv6 multicast address from its parts.
MakeIPv6PrefixMulticast(uint8_t aScope, uint8_t aPrefixLength, const uint64_t & aPrefix, uint32_t aGroupId)
Construct a transient, prefix IPv6 multicast address from its parts.
MakeIPv6TransientMulticast(uint8_t aFlags, uint8_t aScope, const uint8_t aGroupId[NL_INET_IPV6_MCAST_GROUP_LEN_IN_BYTES])
Construct a transient IPv6 multicast address from its parts.
MakeIPv6WellKnownMulticast(uint8_t aScope, uint32_t aGroupId)
Construct a well-known IPv6 multicast address from its parts.
MakeLLA(uint64_t interfaceId)
Construct an IPv6 link-local address (LL) from its IID.
MakeULA(uint64_t globalId, uint16_t subnet, uint64_t interfaceId)
Construct an IPv6 unique-local address (ULA) from its parts.
ReadAddress(const uint8_t *& p, IPAddress & output)
void
Emit the IP address in standard network representation.

Public attributes

Addr

uint32_t Addr[4]

Opaque word array to contain IP addresses (independent of protocol version)

IPv6 address use all 128-bits split into four 32-bit network byte ordered unsigned integers. IPv4 addresses are V4COMPAT, i.e. the first three words are zero, and the fourth word contains the IPv4 address in network byte order.

Public static attributes

Any

IPAddress Any

The distinguished unspecified IP address object.

This object is used as a constant for equivalence comparisons. It must not be modified by users of the Nest Inet Layer.

Public functions

GlobalId

uint64_t GlobalId(
  void
) const 

Extract the 16-bit global network identifier of an IPv6 ULA address.

Use this method with an IPv6 unique-local address (ULA) to extract the global network identifier, which is the 40 bits immediately following the distinguished ULA network prefix, i.e. fd00::/8. In other words, the global network identifier is located in the five bytes from the 2nd 2nd through the 6th bytes in the address.

Details
Returns
40-bit global network identifier, or zero if the IP address is not an IPv6 unique-local address.

InterfaceId

uint64_t InterfaceId(
  void
) const 

Extract the IID of an IPv6 ULA address.

Use this method with an IPv6 unique-local address (ULA) to extract the identifier identifier (IID), which is the least significant 64 bits of the address.

Details
Returns
64-bit interface identifier, or zero if the IP address is not an IPv6 unique-local address.

IsIPv4

bool IsIPv4(
  void
) const 

Test whether address is IPv4 compatible.

Use this method to check if the address belongs to the IPv4 address family. Note well: the unspecified address is not an IPv4 address.

Details
Return Values
true
The address is IPv4 and not the unspecified address.
false
The address is IPv6 or the unspecified address.

IsIPv4Broadcast

bool IsIPv4Broadcast(
  void
) const 

Test whether address is IPv4 broadcast.

Use this method to check if the address is the special purpose IPv4 broadcast address.

Details
Return Values
true
Address is the IPv4 broadcast
false
Otherwise

IsIPv4Multicast

bool IsIPv4Multicast(
  void
) const 

Test whether address is IPv4 multicast.

Use this method to check if the address is an IPv4 multicast address.

Details
Return Values
true
Address is the IPv4 multicast
false
Otherwise

IsIPv6

bool IsIPv6(
  void
) const 

Test whether address is IPv6 compatible.

Use this method to check if the address belongs to the IPv6 address family. Note well: the unspecified address is not an IPv6 address.

Details
Return Values
true
The address is IPv6 and not the unspecified address.
false
The address is IPv4 or the unspecified address.

IsIPv6GlobalUnicast

bool IsIPv6GlobalUnicast(
  void
) const 

Test whether address is IPv6 global unicast address.

Use this method to check if the address belongs to the IPv6 address family and has the global unicast address prefix.

Details
Return Values
true
Address is IPv6 global unicast
false
Otherwise

IsIPv6LinkLocal

bool IsIPv6LinkLocal(
  void
) const 

Test whether address is IPv6 link-local address (LL).

Use this method to check if the address belongs to the IPv6 address family and has the reserved IPv6 link-local address prefix.

Details
Return Values
true
Address is IPv6 link-local
false
Otherwise

IsIPv6Multicast

bool IsIPv6Multicast(
  void
) const 

Test whether address is IPv6 multicast.

Use this method to check if the address belongs to the IPv6 address family and has the reserved IPv6 multicast address prefix.

Details
Return Values
true
Address is IPv6 multicast
false
Otherwise

IsIPv6ULA

bool IsIPv6ULA(
  void
) const 

Test whether address is IPv6 unique-local address (ULA).

Use this method to check if the address belongs to the IPv6 address family and has the reserved IPv6 unique-local address prefix.

Details
Return Values
true
Address is IPv6 unique-local
false
Otherwise

IsMulticast

bool IsMulticast(
  void
) const 

Test whether address is IPv4 or IPv6 multicast.

Use this method to check if the address belongs to the IPv4 or IPv6 address family and has the reserved IPv4 or IPv6 multicast address prefix.

Details
Return Values
true
Address is IPv4 or IPv6 multicast
false
Otherwise

Subnet

uint16_t Subnet(
  void
) const 

Extract the 16-bit subnet identifier of an IPv6 ULA address.

Use this method with an IPv6 unique-local address (ULA) to extract the subnet identifier, which is the least significant 16 bits of the network prefix. The network prefix is the most significant 64 bits of of the address. In other words, the subnet identifier is located in the 7th and 8th bytes of a 16-byte address.

Details
Returns
16-bit subnet identifier, or zero if the IP address is not an IPv6 unique-local address.

ToIPv4

ip4_addr_t ToIPv4(
  void
) const 

Extract the IPv4 address as a platform data structure.

Use ToIPv4() const to extract the content as an IPv4 address, if possible. IPv6 addresses and the unspecified address are extracted as 0.0.0.0.

The result is either of type struct in_addr (on POSIX) or ip4_addr_t (on LwIP).

Details
Returns
The encapsulated IPv4 address, or 0.0.0.0 if the address is either unspecified or not an IPv4 address.

ToIPv4

struct in_addr ToIPv4(
  void
) const 

ToIPv6

ip6_addr_t ToIPv6(
  void
) const 

Extract the IPv6 address as a platform data structure.

Use ToIPv6() const to extract the content as an IPv6 address, if possible. IPv4 addresses and the unspecified address are extracted as [::].

The result is either of type struct in6_addr (on POSIX) or ip6_addr_t (on LwIP).

Details
Returns
The encapsulated IPv4 address, or [::] if the address is either unspecified or not an IPv4 address.

ToIPv6

struct in6_addr ToIPv6(
  void
) const 

ToString

char * ToString(
  char *buf,
  uint32_t bufSize
) const 

Emit the IP address in conventional text presentation format.

Use ToString(char *buf, uint32_t bufSize) const to write the conventional text presentation form of the IP address to the memory located at buf and extending as much as bufSize bytes, including its NUL termination character.

Details
Parameters
[out] buf
The address of the emitted text.
[in] bufSize
The size of the buffer for the emitted text.

Note Well: not compliant with RFC 5952 on some platforms. Specifically, zero compression may not be applied according to section 4.2.

Details
Returns
The argument buf if no formatting error, or zero otherwise.

Type

IPAddressType Type(
  void
) const 

Extract the type of the IP address.

Use this method to return an value of the enumerated type IPAddressType to indicate the type of the IP address.

Details
Return Values
kIPAddressType_IPv4
The address is IPv4.
kIPAddressType_IPv6
The address is IPv6.
kIPAddressType_Any
The address is the unspecified address.

WriteAddress

void WriteAddress(
  uint8_t *& p
) const 

Emit the IP address in standard network representation.

Use WriteAddress(uint8_t *&p) to encode the IP address in the binary format defined by RFC 4291 for IPv6 addresses. IPv4 addresses are encoded according to section 2.5.5.1 "IPv4-Compatible IPv6 Address" (V4COMPAT).

Details
Parameters
[in,out] p
Reference to the cursor to use for writing.

operator!=

bool operator!=(
  const IPAddress & other
) const 

Compare this IP address with another for inequivalence.

Details
Parameters
[in] other
The address to compare.
Return Values
true
If equivalent to other
false
Otherwise

operator=

IPAddress & operator=(
  const IPAddress & other
)

Conventional assignment operator.

Details
Parameters
[in] other
The address to copy.
Returns
A reference to this object.

operator==

bool operator==(
  const IPAddress & other
) const 

Compare this IP address with another for equivalence.

Details
Parameters
[in] other
The address to compare.
Return Values
true
If equivalent to other
false
Otherwise

Public static functions

FromIPv4

IPAddress FromIPv4(
  const ip4_addr_t & addr
)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

FromIPv4

IPAddress FromIPv4(
  const struct in_addr & addr
)

Inject the IPv4 address from a platform data structure.

Use FromIPv4(const ip4_addr_t &addr) to inject addr as an IPv4 address.

The argument addr is either of type const struct in_addr& (on POSIX) or const ip4_addr_t& (on LwIP).

Details
Returns
The constructed IP address.

FromIPv6

IPAddress FromIPv6(
  const ip6_addr_t & addr
)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

FromIPv6

IPAddress FromIPv6(
  const struct in6_addr & addr
)

Inject the IPv6 address from a platform data structure.

Use FromIPv6(const ip6_addr_t &addr) to inject addr as an IPv6 address.

The argument addr is either of type const struct in6_addr& (on POSIX) or const ip6_addr_t& (on LwIP).

Details
Returns
The constructed IP address.

FromSockAddr

IPAddress FromSockAddr(
  const struct sockaddr & sockaddr
)

Inject the IPv6 address from a POSIX struct sockaddr&

Use FromSockAddr(const struct sockaddr& sockaddr) to inject sockaddr.sa_addr as an IPv6 address.

Details
Returns
The constructed IP address.

FromString

bool FromString(
  const char *str,
  IPAddress & output
)

Scan the IP address from its conventional presentation text.

Use FromString(const char *str, IPAddress& output) to overwrite an IP address by scanning the conventional text presentation located at str.

Details
Parameters
[in] str
The address of the emitted text.
[out] output
The object to set to the scanned address.

Details
Return Values
true
The presentation format is valid
false
Otherwise

FromString

bool FromString(
  const char *str,
  size_t strLen,
  IPAddress & output
)

Scan the IP address from its conventional presentation text.

Use FromString(const char *str, size_t strLen, IPAddress& output) to overwrite an IP address by scanning the conventional text presentation located at str.

Details
Parameters
[in] str
A pointer to the text to be scanned.
[in] strLen
The length of the text to be scanned.
[out] output
The object to set to the scanned address.

Details
Return Values
true
The presentation format is valid
false
Otherwise

MakeIPv4Broadcast

IPAddress MakeIPv4Broadcast(
  void
)

Construct an IPv4 broadcast address.

Details
Returns
The constructed IP address.

MakeIPv6Multicast

IPAddress MakeIPv6Multicast(
  uint8_t aFlags,
  uint8_t aScope,
  const uint8_t aGroupId[NL_INET_IPV6_MCAST_GROUP_LEN_IN_BYTES]
)

Construct an IPv6 multicast address from its parts.

Use MakeIPv6Multicast(uint8_t flags, uint8_t scope, uint8_t groupId[14]) to construct an IPv6 multicast address with flags for routing scope scope and group identifier octets groupId.

Details
Returns
The constructed IP address.

MakeIPv6Multicast

IPAddress MakeIPv6Multicast(
  uint8_t aFlags,
  uint8_t aScope,
  uint32_t aGroupId
)

Construct an IPv6 multicast address from its parts.

Use MakeIPv6Multicast(uint8_t flags, uint8_t scope, uint32_t groupId) to construct an IPv6 multicast address with flags for routing scope scope and group identifier groupId.

Details
Returns
The constructed IP address.

MakeIPv6PrefixMulticast

IPAddress MakeIPv6PrefixMulticast(
  uint8_t aScope,
  uint8_t aPrefixLength,
  const uint64_t & aPrefix,
  uint32_t aGroupId
)

Construct a transient, prefix IPv6 multicast address from its parts.

Use MakeIPv6PrefixMulticast(uint8_t scope, uint8_t prefixlen, const uint64_t prefix, uint32_t groupId) to construct a transient, prefix IPv6 multicast address with for routing scope scope and group identifier octets groupId, qualified by the prefix prefix of length prefixlen bits.

Details
Returns
The constructed IP address.

MakeIPv6TransientMulticast

IPAddress MakeIPv6TransientMulticast(
  uint8_t aFlags,
  uint8_t aScope,
  const uint8_t aGroupId[NL_INET_IPV6_MCAST_GROUP_LEN_IN_BYTES]
)

Construct a transient IPv6 multicast address from its parts.

Use MakeIPv6TransientMulticast(uint8_t flags, uint8_t scope, uint8_t groupId[14]) to construct a transient IPv6 multicast address with flags for routing scope scope and group identifier octets groupId.

Details
Returns
The constructed IP address.

MakeIPv6WellKnownMulticast

IPAddress MakeIPv6WellKnownMulticast(
  uint8_t aScope,
  uint32_t aGroupId
)

Construct a well-known IPv6 multicast address from its parts.

Use MakeIPv6WellKnownMulticast(uint8_t scope, uint32_t groupId) to construct an IPv6 multicast address for routing scope scope and group identifier groupId.

Details
Returns
The constructed IP address.

MakeLLA

IPAddress MakeLLA(
  uint64_t interfaceId
)

Construct an IPv6 link-local address (LL) from its IID.

Use MakeLLA(uint64_t interfaceId) to construct an IPv6 link-local address (LL) with interface identifier interfaceId.

Details
Returns
The constructed IP address.

MakeULA

IPAddress MakeULA(
  uint64_t globalId,
  uint16_t subnet,
  uint64_t interfaceId
)

Construct an IPv6 unique-local address (ULA) from its parts.

Use MakeULA(uint64_t globalId, uint16_t subnet, uint64_t interfaceId) to construct a unique-local address (ULA) with global network identifier globalId, subnet identifier subnet and interface identifier (IID) interfaceId.

Details
Returns
The constructed IP address.

ReadAddress

void ReadAddress(
  const uint8_t *& p,
  IPAddress & output
)

Emit the IP address in standard network representation.

Use ReadAddress(uint8_t *&p, IPAddress &output) to decode the IP address at p to the object output.

Details
Parameters
[in,out] p
Reference to the cursor to use for reading.
[out] output
Object to receive decoded IP address.