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`	`IPAddress` 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`	`ip4_addr_t` 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)`	`IPAddress &` 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)`	`IPAddress`
`FromIPv4(const struct in_addr & addr)`	`IPAddress` Inject the IPv4 address from a platform data structure.
`FromIPv6(const ip6_addr_t & addr)`	`IPAddress`
`FromIPv6(const struct in6_addr & addr)`	`IPAddress` Inject the IPv6 address from a platform data structure.
`FromSockAddr(const struct sockaddr & sockaddr)`	`IPAddress` 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)`	`IPAddress` Construct an IPv4 broadcast address.
`MakeIPv6Multicast(uint8_t aFlags, uint8_t aScope, const uint8_t aGroupId[NL_INET_IPV6_MCAST_GROUP_LEN_IN_BYTES])`	`IPAddress` Construct an IPv6 multicast address from its parts.
`MakeIPv6Multicast(uint8_t aFlags, uint8_t aScope, uint32_t aGroupId)`	`IPAddress` Construct an IPv6 multicast address from its parts.
`MakeIPv6PrefixMulticast(uint8_t aScope, uint8_t aPrefixLength, const uint64_t & aPrefix, uint32_t aGroupId)`	`IPAddress` 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])`	`IPAddress` Construct a transient IPv6 multicast address from its parts.
`MakeIPv6WellKnownMulticast(uint8_t aScope, uint32_t aGroupId)`	`IPAddress` Construct a well-known IPv6 multicast address from its parts.
`MakeLLA(uint64_t interfaceId)`	`IPAddress` Construct an IPv6 link-local address (LL) from its IID.
`MakeULA(uint64_t globalId, uint16_t subnet, uint64_t interfaceId)`	`IPAddress` 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.