Overview

Identifiers for IP addresses and network interfaces.

#include "etcpal/inet.h"

Provides types representing internet addressing constructs. Many of these functions and types mimic those found in POSIX's arpa/inet.h, with some quality-of-life improvements. Several functions and macros are provided to inspect, compare and manipulate these types.

Data Structures
struct	EtcPalIpAddr
	An IP address. More...

struct	EtcPalSockAddr
	An IP address with associated interface and port. More...

struct	EtcPalMacAddr
	A MAC address. More...

struct	EtcPalNetintInfo
	A description of a single address assigned to a network interface. More...

struct	EtcPalMcastNetintId
	A set of identifying information for a network interface, for multicast purposes. More...

Macros
#define	ETCPAL_IPV6_BYTES 16
	The number of bytes in an IPv6 address.

#define	ETCPAL_MAC_BYTES 6
	The number of bytes in a MAC address.

#define	ETCPAL_MAC_CMP(mac1ptr, mac2ptr) memcmp((mac1ptr)->data, (mac2ptr)->data, ETCPAL_MAC_BYTES)
	Compare two EtcPalMacAddrs numerically. More...

#define	ETCPAL_MAC_IS_NULL(macptr) (memcmp((macptr)->data, kEtcPalNullMacAddr.data, ETCPAL_MAC_BYTES) == 0)
	Determine if a MAC address is null. More...

#define	ETCPAL_NETINTINFO_ID_LEN 64
	The maximum length of a network interface id.

#define	ETCPAL_NETINTINFO_FRIENDLY_NAME_LEN 64
	The maximum length of a user-friendly network interface name.

#define	ETCPAL_IP_STRING_BYTES 46
	Maximum length of the string representation of an IP address.

#define	ETCPAL_MAC_STRING_BYTES 18
	Maximum length of the string representation of a MAC address.

Typedefs
typedef struct EtcPalIpAddr	EtcPalIpAddr
	An IP address. More...

typedef struct EtcPalSockAddr	EtcPalSockAddr
	An IP address with associated interface and port. More...

typedef struct EtcPalMacAddr	EtcPalMacAddr
	A MAC address.

typedef struct EtcPalNetintInfo	EtcPalNetintInfo
	A description of a single address assigned to a network interface.

typedef struct EtcPalMcastNetintId	EtcPalMcastNetintId
	A set of identifying information for a network interface, for multicast purposes. More...

Enumerations
enum	etcpal_iptype_t { kEtcPalIpTypeInvalid , kEtcPalIpTypeV4 , kEtcPalIpTypeV6 }
	Used to identify the type of IP address contained in a EtcPalIpAddr. More...

Functions
bool	etcpal_ip_is_link_local (const EtcPalIpAddr *ip)
	Determine whether a EtcPalIpAddr contains a link-local address. More...

bool	etcpal_ip_is_loopback (const EtcPalIpAddr *ip)
	Determine whether a EtcPalIpAddr contains a loopback address. More...

bool	etcpal_ip_is_multicast (const EtcPalIpAddr *ip)
	Determine whether a EtcPalIpAddr contains a multicast address. More...

bool	etcpal_ip_is_wildcard (const EtcPalIpAddr *ip)
	Determine whether a EtcPalIpAddr contains a wildcard address. More...

void	etcpal_ip_set_wildcard (etcpal_iptype_t type, EtcPalIpAddr *ip)
	Initialize a EtcPalIpAddr with a wildcard address. More...

int	etcpal_ip_cmp (const EtcPalIpAddr ip1, const EtcPalIpAddr ip2)
	Compare two EtcPalIpAddrs. More...

bool	etcpal_ip_and_port_equal (const EtcPalSockAddr sock1, const EtcPalSockAddr sock2)
	Determine whether two instances of EtcPalSockAddr contain identical IP addresses and ports. More...

int	etcpal_netint_info_cmp (const EtcPalNetintInfo i1, const EtcPalNetintInfo i2)
	Compare two EtcPalNetintInfos. More...

unsigned int	etcpal_ip_mask_length (const EtcPalIpAddr *netmask)
	Get the length in bits of a netmask. More...

EtcPalIpAddr	etcpal_ip_mask_from_length (etcpal_iptype_t type, unsigned int mask_length)
	Create a netmask given a length in bits. More...

bool	etcpal_ip_network_portions_equal (const EtcPalIpAddr ip1, const EtcPalIpAddr ip2, const EtcPalIpAddr *netmask)
	Compare the network portions of two IP addresses using a netmask. More...

bool	ip_os_to_etcpal (const etcpal_os_ipaddr_t os_ip, EtcPalIpAddr ip)
	Convert a platform-specific IP address to an EtcPalIpAddr. More...

size_t	ip_etcpal_to_os (const EtcPalIpAddr ip, etcpal_os_ipaddr_t os_ip)
	Convert an EtcPalIpAddr to a platform-specific IP address. More...

bool	sockaddr_os_to_etcpal (const etcpal_os_sockaddr_t os_sa, EtcPalSockAddr sa)
	Convert a platform-specific socket address to an EtcPalSockAddr. More...

size_t	sockaddr_etcpal_to_os (const EtcPalSockAddr sa, etcpal_os_sockaddr_t os_sa)
	Convert an EtcPalSockAddr to a platform-specific socket address. More...

etcpal_error_t	etcpal_ip_to_string (const EtcPalIpAddr src, char dest)
	Convert IPv4 and IPv6 addresses from binary to text form. More...

etcpal_error_t	etcpal_string_to_ip (etcpal_iptype_t type, const char src, EtcPalIpAddr dest)
	Convert IPv4 and IPv6 addresses from text to binary form. More...

etcpal_error_t	etcpal_mac_to_string (const EtcPalMacAddr src, char dest)
	Create a string representation of a MAC address. More...

etcpal_error_t	etcpal_string_to_mac (const char src, EtcPalMacAddr dest)
	Create a MAC address from a string representation. More...

Variables
const EtcPalMacAddr	kEtcPalNullMacAddr
	A null (all 0's) MAC address, used by ETCPAL_MAC_IS_NULL() for comparison.

EtcPalIpAddr macros
A set of macros for interacting with a EtcPalIpAddr. It is recommended to use these macros where possible rather than accessing the structure members directly; otherwise, it's easy to forget to fill in a field.
#define	ETCPAL_IP_INVALID_INIT_VALUES kEtcPalIpTypeInvalid, { 0 }
	A set of initializer values for an invalid EtcPalIpAddr. More...

#define	ETCPAL_IP_INVALID_INIT
	An initializer for an invalid EtcPalIpAddr. More...

#define	ETCPAL_IPV4_INIT_VALUES(v4_val) kEtcPalIpTypeV4, { .v4 = v4_val }
	A set of initializer values for an EtcPalIpAddr representing an IPv4 address. More...

#define	ETCPAL_IPV4_INIT(addr_val)
	An initializer for an EtcPalIpAddr representing an IPv4 address. More...

#define	ETCPAL_IPV6_INIT_VALUES(...)
	A set of initializer values for an EtcPalIpAddr representing an IPv6 address. More...

#define	ETCPAL_IPV6_INIT(...)
	An initializer for an EtcPalIpAddr representing an IPv6 address. More...

#define	ETCPAL_IP_IS_V4(etcpal_ip_ptr) ((etcpal_ip_ptr)->type == kEtcPalIpTypeV4)
	Determine whether a EtcPalIpAddr contains an IPv4 address. More...

#define	ETCPAL_IP_IS_V6(etcpal_ip_ptr) ((etcpal_ip_ptr)->type == kEtcPalIpTypeV6)
	Determine whether a EtcPalIpAddr contains an IPv6 address. More...

#define	ETCPAL_IP_IS_INVALID(etcpal_ip_ptr) ((etcpal_ip_ptr)->type == kEtcPalIpTypeInvalid)
	Determine whether a EtcPalIpAddr contains an invalid address. More...

#define	ETCPAL_IP_V4_ADDRESS(etcpal_ip_ptr) ((etcpal_ip_ptr)->addr.v4)
	Get the IPv4 address from a EtcPalIpAddr. More...

#define	ETCPAL_IP_V6_ADDRESS(etcpal_ip_ptr) ((etcpal_ip_ptr)->addr.v6.addr_buf)
	Get the IPv6 address from a EtcPalIpAddr. More...

#define	ETCPAL_IP_V6_SCOPE_ID(etcpal_ip_ptr) ((etcpal_ip_ptr)->addr.v6.scope_id)
	Get the IPv6 scope ID from an EtcPalIpAddr. More...

#define	ETCPAL_IP_SET_V4_ADDRESS(etcpal_ip_ptr, val)
	Set the IPv4 address in a EtcPalIpAddr. More...

#define	ETCPAL_IP_SET_V6_ADDRESS(etcpal_ip_ptr, addr_val) ETCPAL_IP_SET_V6_ADDRESS_WITH_SCOPE_ID(etcpal_ip_ptr, addr_val, 0u)
	Set the IPv6 address in a EtcPalIpAddr. More...

#define	ETCPAL_IP_SET_V6_ADDRESS_WITH_SCOPE_ID(etcpal_ip_ptr, addr_val, scope_id_val)
	Set an IPv6 address with an explicit scope ID in a EtcPalIpAddr. More...

#define	ETCPAL_IP_SET_INVALID(etcpal_ip_ptr) ((etcpal_ip_ptr)->type = kEtcPalIpTypeInvalid)
	Set the type field in a EtcPalIpAddr to indicate that it does not contain a valid address. More...

Macro Definition Documentation

◆ ETCPAL_IP_INVALID_INIT

#define ETCPAL_IP_INVALID_INIT

Value:

  {                               \
    ETCPAL_IP_INVALID_INIT_VALUES \
  }

An initializer for an invalid EtcPalIpAddr.

Usage:

EtcPalIpAddr invalid_ip = ETCPAL_IP_INVALID_INIT;

ETCPAL_IP_INVALID_INIT

#define ETCPAL_IP_INVALID_INIT

An initializer for an invalid EtcPalIpAddr.

Definition: inet.h:121

EtcPalIpAddr

An IP address.

Definition: inet.h:75

◆ ETCPAL_IP_INVALID_INIT_VALUES

#define ETCPAL_IP_INVALID_INIT_VALUES kEtcPalIpTypeInvalid, { 0 }

A set of initializer values for an invalid EtcPalIpAddr.

Usage:

EtcPalIpAddr invalid_ip = { ETCPAL_IP_INVALID_INIT_VALUES };

ETCPAL_IP_INVALID_INIT_VALUES

#define ETCPAL_IP_INVALID_INIT_VALUES

A set of initializer values for an invalid EtcPalIpAddr.

Definition: inet.h:110

To omit the enclosing brackets, use ETCPAL_IP_INVALID_INIT.

◆ ETCPAL_IP_IS_INVALID

#define ETCPAL_IP_IS_INVALID ( etcpal_ip_ptr ) ((etcpal_ip_ptr)->type == kEtcPalIpTypeInvalid)

Determine whether a EtcPalIpAddr contains an invalid address.

Parameters

etcpal_ip_ptr Pointer to a EtcPalIpAddr.

Returns: true (is invalid) or false (is not invalid).

◆ ETCPAL_IP_IS_V4

#define ETCPAL_IP_IS_V4 ( etcpal_ip_ptr ) ((etcpal_ip_ptr)->type == kEtcPalIpTypeV4)

Determine whether a EtcPalIpAddr contains an IPv4 address.

Parameters

etcpal_ip_ptr Pointer to a EtcPalIpAddr.

Returns: true (contains an IPv4 address) or false (does not contain an IPv4 address).

◆ ETCPAL_IP_IS_V6

#define ETCPAL_IP_IS_V6 ( etcpal_ip_ptr ) ((etcpal_ip_ptr)->type == kEtcPalIpTypeV6)

Determine whether a EtcPalIpAddr contains an IPv6 address.

Parameters

etcpal_ip_ptr Pointer to a EtcPalIpAddr.

Returns: true (contains an IPv6 address) or false (does not contain an IPv6 address).

◆ ETCPAL_IP_SET_INVALID

#define ETCPAL_IP_SET_INVALID ( etcpal_ip_ptr ) ((etcpal_ip_ptr)->type = kEtcPalIpTypeInvalid)

Set the type field in a EtcPalIpAddr to indicate that it does not contain a valid address.

Parameters

etcpal_ip_ptr Pointer to a EtcPalIpAddr.

◆ ETCPAL_IP_SET_V4_ADDRESS

#define ETCPAL_IP_SET_V4_ADDRESS	(	etcpal_ip_ptr,
		val
	)

Value:

  do                                                 \
  {                                                  \
    (etcpal_ip_ptr)->type    = kEtcPalIpTypeV4;      \
    (etcpal_ip_ptr)->addr.v4 = val;                  \
  } while (0)

Set the IPv4 address in a EtcPalIpAddr.

Also sets the type field to indicate that this EtcPalIpAddr contains an IPv4 address.

Parameters

etcpal_ip_ptr	Pointer to a EtcPalIpAddr.
val	IPv4 address to set (uint32_t).

◆ ETCPAL_IP_SET_V6_ADDRESS

#define ETCPAL_IP_SET_V6_ADDRESS	(	etcpal_ip_ptr,
		addr_val
	)	ETCPAL_IP_SET_V6_ADDRESS_WITH_SCOPE_ID(etcpal_ip_ptr, addr_val, 0u)

Set the IPv6 address in a EtcPalIpAddr.

Also sets the type field to indicate that this EtcPalIpAddr contains an IPv6 address.

Parameters

etcpal_ip_ptr	Pointer to a EtcPalIpAddr.
addr_val	IPv6 address to set (uint8_t[]). Must be at least of length ETCPAL_IPV6_BYTES. Gets copied into the struct.

◆ ETCPAL_IP_SET_V6_ADDRESS_WITH_SCOPE_ID

#define ETCPAL_IP_SET_V6_ADDRESS_WITH_SCOPE_ID	(	etcpal_ip_ptr,
		addr_val,
		scope_id_val
	)

Value:

  do                                                                                  \
  {                                                                                   \
    (etcpal_ip_ptr)->type = kEtcPalIpTypeV6;                                          \
    memcpy((etcpal_ip_ptr)->addr.v6.addr_buf, (addr_val), ETCPAL_IPV6_BYTES);         \
    (etcpal_ip_ptr)->addr.v6.scope_id = (scope_id_val);                               \
  } while (0)

Set an IPv6 address with an explicit scope ID in a EtcPalIpAddr.

Also sets the type field to indicate that this EtcPalIpAddr contains an IPv6 address.

Parameters

etcpal_ip_ptr	Pointer to a EtcPalIpAddr.
addr_val	IPv6 address to set (uint8_t[]). Must be at least of length ETCPAL_IPV6_BYTES. Gets copied into the struct.
scope_id_val	IPv6 scope ID to set.

◆ ETCPAL_IP_V4_ADDRESS

#define ETCPAL_IP_V4_ADDRESS ( etcpal_ip_ptr ) ((etcpal_ip_ptr)->addr.v4)

Get the IPv4 address from a EtcPalIpAddr.

It is recommended to first use ETCPAL_IP_IS_V4() to make sure this EtcPalIpAddr contains a valid IPv4 address.

Parameters

etcpal_ip_ptr Pointer to a EtcPalIpAddr.

Returns: The IPv4 address (uint32_t).

◆ ETCPAL_IP_V6_ADDRESS

#define ETCPAL_IP_V6_ADDRESS ( etcpal_ip_ptr ) ((etcpal_ip_ptr)->addr.v6.addr_buf)

Get the IPv6 address from a EtcPalIpAddr.

It is recommended to first use ETCPAL_IP_IS_V6() to make sure this EtcPalIpAddr contains a valid IPv6 address.

Parameters

etcpal_ip_ptr Pointer to a EtcPalIpAddr.

Returns: The IPv6 address (uint8_t[]).

◆ ETCPAL_IP_V6_SCOPE_ID

#define ETCPAL_IP_V6_SCOPE_ID ( etcpal_ip_ptr ) ((etcpal_ip_ptr)->addr.v6.scope_id)

Get the IPv6 scope ID from an EtcPalIpAddr.

See Network Interface Indexes for more information. It is recommended to first use ETCPAL_IP_IS_V6() to make sure this EtcPalIpAddr contains a valid IPv6 address.

Parameters

etcpal_ip_ptr Pointer to a EtcPalIpAddr.

Returns: The IPv6 scope ID (unsigned int).

◆ ETCPAL_IPV4_INIT

#define ETCPAL_IPV4_INIT ( addr_val )

Value:

  {                                   \
    ETCPAL_IPV4_INIT_VALUES(addr_val) \
  }

An initializer for an EtcPalIpAddr representing an IPv4 address.

Usage:

EtcPalIpAddr v4 = ETCPAL_IPV4_INIT(0xc0a80101); // 192.168.1.1

ETCPAL_IPV4_INIT

#define ETCPAL_IPV4_INIT(addr_val)

An initializer for an EtcPalIpAddr representing an IPv4 address.

Definition: inet.h:151

Note: Using this macro requires support for C99 designated initializers in your compiler.

◆ ETCPAL_IPV4_INIT_VALUES

#define ETCPAL_IPV4_INIT_VALUES ( v4_val ) kEtcPalIpTypeV4, { .v4 = v4_val }

A set of initializer values for an EtcPalIpAddr representing an IPv4 address.

Usage:

EtcPalIpAddr v4 = { ETCPAL_IPV4_INIT_VALUES(0xc0a80101) }; // 192.168.1.1

ETCPAL_IPV4_INIT_VALUES

#define ETCPAL_IPV4_INIT_VALUES(v4_val)

A set of initializer values for an EtcPalIpAddr representing an IPv4 address.

Definition: inet.h:138

Note: Using this macro requires support for C99 designated initializers in your compiler.

To omit the enclosing brackets, use ETCPAL_IPV4_INIT().

◆ ETCPAL_IPV6_INIT

#define ETCPAL_IPV6_INIT ( ... )

Value:

  {                                      \
    ETCPAL_IPV6_INIT_VALUES(__VA_ARGS__) \
  }

An initializer for an EtcPalIpAddr representing an IPv6 address.

Usage:

// 2001:db8::1234:5678
EtcPalIpAddr v6 = ETCPAL_IPV6_INIT(0x20, 0x01, 0x0d, 0xb8, 0x00, 0x00, 0x00, 0x00,
                                   0x00, 0x00, 0x00, 0x00, 0x12, 0x34, 0x56, 0x78);

Any number of initializer values can be used (the remaining IPv6 bytes will be initialized to 0).

Note: Using this macro requires support for variadic macros and C99 designated initializers in your compiler.

◆ ETCPAL_IPV6_INIT_VALUES

#define ETCPAL_IPV6_INIT_VALUES ( ... )

Value:

  kEtcPalIpTypeV6,                                    \
  {                                                   \
    .v6 = {.addr_buf = {__VA_ARGS__}, .scope_id = 0 } \
  }

A set of initializer values for an EtcPalIpAddr representing an IPv6 address.

Usage:

// 2001:db8::1234:5678
EtcPalIpAddr v6 = {
  ETCPAL_IPV6_INIT_VALUES(0x20, 0x01, 0x0d, 0xb8, 0x00, 0x00, 0x00, 0x00,
                          0x00, 0x00, 0x00, 0x00, 0x12, 0x34, 0x56, 0x78)
};

Any number of initializer values can be used (the remaining IPv6 bytes will be initialized to 0). To omit the enclosing brackets, use ETCPAL_IPV6_INIT().

Note: Using this macro requires support for variadic macros and C99 designated initializers in your compiler.

◆ ETCPAL_MAC_CMP

#define ETCPAL_MAC_CMP	(	mac1ptr,
		mac2ptr
	)	memcmp((mac1ptr)->data, (mac2ptr)->data, ETCPAL_MAC_BYTES)

Compare two EtcPalMacAddrs numerically.

Parameters

[in]	mac1ptr	Pointer to first EtcPalMacAddr to compare.
[in]	mac2ptr	Pointer to second EtcPalMacAddr to compare.

Returns: < 0: mac1 < mac2; 0: mac1 == mac2; > 0: mac1 > mac2

◆ ETCPAL_MAC_IS_NULL

#define ETCPAL_MAC_IS_NULL ( macptr ) (memcmp((macptr)->data, kEtcPalNullMacAddr.data, ETCPAL_MAC_BYTES) == 0)

Determine if a MAC address is null.

A MAC address is said to be 'null' when it is made up of all 0's.

Parameters

macptr Pointer to EtcPalMacAddr to null-check.

Returns: true (MAC address is null) or false (MAC address is not null).

Typedef Documentation

◆ EtcPalIpAddr

typedef struct EtcPalIpAddr EtcPalIpAddr

An IP address.

Can hold either an IPv4 or IPv6 address. Do not manipulate the members directly; use the macros defined in this module to access them. IPv4 addresses are in host byte order. IPv6 addresses also contain a scope ID, which is also sometimes referred to as a zone index (RFC 4007), to help disambiguate link-local addresses, among other uses. In most cases, this field can be left at its default value, which is set by the ETCPAL_IP_SET_V6_ADDRESS() macro.

◆ EtcPalMcastNetintId

typedef struct EtcPalMcastNetintId EtcPalMcastNetintId

A set of identifying information for a network interface, for multicast purposes.

The primary key for a network interface is simply a combination of the interface index and the IP protocol used. The interface IP address is not required for this.

◆ EtcPalSockAddr

typedef struct EtcPalSockAddr EtcPalSockAddr

An IP address with associated interface and port.

Ports are in host byte order.

Enumeration Type Documentation

◆ etcpal_iptype_t

enum etcpal_iptype_t

Used to identify the type of IP address contained in a EtcPalIpAddr.

Enumerator
kEtcPalIpTypeInvalid	This EtcPalIpAddr is not valid.
kEtcPalIpTypeV4	This EtcPalIpAddr contains an IPv4 address.
kEtcPalIpTypeV6	This EtcPalIpAddr contains an IPv6 address.

Function Documentation

◆ etcpal_ip_and_port_equal()

bool etcpal_ip_and_port_equal	(	const EtcPalSockAddr *	sock1,
		const EtcPalSockAddr *	sock2
	)

Determine whether two instances of EtcPalSockAddr contain identical IP addresses and ports.

Parameters

[in]	sock1	First EtcPalSockAddr to compare.
[in]	sock2	Second EtcPalSockAddr to compare.

Returns: true: the IP address and port are identical.; false: the IP address and port are not identical.

◆ etcpal_ip_cmp()

int etcpal_ip_cmp	(	const EtcPalIpAddr *	ip1,
		const EtcPalIpAddr *	ip2
	)

Compare two EtcPalIpAddrs.

Rules for comparison:

All Invalid addresses are considered to be equal to each other and < all IPv4 and IPv6 addresses
All IPv4 addresses are considered to be < all IPv6 addresses
For two IPv4 or IPv6 addresses, the numerical address value is compared

Parameters

[in]	ip1	First EtcPalIpAddr to compare.
[in]	ip2	Second EtcPalIpAddr to compare.

Returns: < 0: ip1 < ip2; 0: ip1 == ip2; > 0: ip1 > ip2

◆ etcpal_ip_is_link_local()

bool etcpal_ip_is_link_local ( const EtcPalIpAddr * ip )

Determine whether a EtcPalIpAddr contains a link-local address.

Works for both IPv4 and IPv6 addresses.

Parameters

[in] ip Address to check.

Returns: true: ip contains a link-local address.; false: ip does not contain a link-local address.

◆ etcpal_ip_is_loopback()

bool etcpal_ip_is_loopback ( const EtcPalIpAddr * ip )

Determine whether a EtcPalIpAddr contains a loopback address.

Works for both IPv4 and IPv6 addresses.

Parameters

[in] ip Address to check.

Returns: true: ip contains a loopback address.; false: ip does not contain a loopback address.

◆ etcpal_ip_is_multicast()

bool etcpal_ip_is_multicast ( const EtcPalIpAddr * ip )

Determine whether a EtcPalIpAddr contains a multicast address.

Works for both IPv4 and IPv6 addresses.

Parameters

[in] ip Address to check.

Returns: true: ip contains a multicast address.; false: ip does not contain a multicast address.

◆ etcpal_ip_is_wildcard()

bool etcpal_ip_is_wildcard ( const EtcPalIpAddr * ip )

Determine whether a EtcPalIpAddr contains a wildcard address.

Works for both IPv4 and IPv6 addresses. The wildcard address is used as an argument to etcpal_bind() to indicate that a socket should be bound to all available network interfaces. It should not be used as a placeholder or invalid address - use ETCPAL_IP_SET_INVALID() and ETCPAL_IP_IS_INVALID() for that.

Parameters

[in] ip Address to check.

Returns: true: ip contains a wildcard address.; false: ip does not contain a wildcard address.

◆ etcpal_ip_mask_from_length()

EtcPalIpAddr etcpal_ip_mask_from_length	(	etcpal_iptype_t	type,
		unsigned int	mask_length
	)

Create a netmask given a length in bits.

Creates either an IPv4 or IPv6 netmask, setting the most-significant mask_length bits.

For example: type = kEtcPalIpTypeV4; mask_length = 16; result = 255.255.0.0 type = kEtcPalIpTypeV6; mask_length = 64; result = ffff:ffff:ffff:ffff::

Parameters

[in]	type	Type of netmask to create, either IPv4 or IPv6.
[in]	mask_length	Length in bits of the mask, counting from the MSB.

Returns: EtcPalIpAddr containing the netmask.

◆ etcpal_ip_mask_length()

unsigned int etcpal_ip_mask_length ( const EtcPalIpAddr * netmask )

Get the length in bits of a netmask.

Counts the number of set ('1') bits in the netmask, starting from the MSB. Works for both IPv4 and IPv6 netmasks.

For example: netmask = 255.255.0.0 (0xffff0000); result = 16 netmask = ffff:ffff:ffff:ffff::; result = 64

Parameters

[in] netmask Netmask to count.

Returns: Number of set bits in the netmask.

◆ etcpal_ip_network_portions_equal()

bool etcpal_ip_network_portions_equal	(	const EtcPalIpAddr *	ip1,
		const EtcPalIpAddr *	ip2,
		const EtcPalIpAddr *	netmask
	)

Compare the network portions of two IP addresses using a netmask.

Returns true if the network portions of the IP addresses match. The host portions are disregarded.

Some examples: ip1 = 192.168.0.1; ip2 = 192.168.0.2; netmask = 255.255.0.0 (/16); result = true ip1 = 192.168.0.1; ip2 = 192.168.1.1; netmask = 255.255.255.0 (/24); result = false ip1 = 2001:db8::1; ip2 = 2001:db8::2; netmask = ffff:ffff:ffff:ffff:: (/64); result = true ip1 = 2001:db8:1::1; ip2 = 2001:db8:2::1; netmask = ffff:ffff:ffff:ffff:: (/64); result = false

Parameters

[in]	ip1	First EtcPalIpAddr to compare.
[in]	ip2	Second EtcPalIpAddr to compare.
[in]	netmask	The netmask to use for the comparison. This mask is used to determine the network portion of each address. The etcpal_ip_mask_from_length() function can be used to turn a mask or prefix bit length into a mask.

Returns: true: The network portions of the IP addresses are equal.; false: The network portions are not equal.

◆ etcpal_ip_set_wildcard()

void etcpal_ip_set_wildcard	(	etcpal_iptype_t	type,
		EtcPalIpAddr *	ip
	)

Initialize a EtcPalIpAddr with a wildcard address.

Works for both IPv4 and IPv6 addresses. The wildcard address is used as an argument to etcpal_bind() to indicate that a socket should be bound to all available network interfaces. It should not be used as a placeholder or invalid address - use ETCPAL_IP_SET_INVALID() and ETCPAL_IP_IS_INVALID() for that.

Parameters

[in]	type	Type of wildcard to create, either IPv4 or IPv6.
[out]	ip	Address in which to store the wildcard value.

◆ etcpal_ip_to_string()

etcpal_error_t etcpal_ip_to_string	(	const EtcPalIpAddr *	src,
		char *	dest
	)

Convert IPv4 and IPv6 addresses from binary to text form.

This function uses each platform's inet_ntop() function under the hood.

Parameters

[in]	src	Address to convert to string form.
[out]	dest	Filled in on success with the string-represented address. To avoid undefined behavior, this buffer must be at least of size ETCPAL_IP_STRING_BYTES.

Returns: kEtcPalErrOk: Success.; kEtcPalErrInvalid: Invalid parameter.; kEtcPalErrSys: System call failed.

◆ etcpal_mac_to_string()

etcpal_error_t etcpal_mac_to_string	(	const EtcPalMacAddr *	src,
		char *	dest
	)

Create a string representation of a MAC address.

The resulting string will be of the form xx:xx:xx:xx:xx:xx (lowercase is used for hexadecimal letters per common convention).

Parameters

[in]	src	MAC address to convert to a string.
[out]	dest	Character buffer to which to write the resulting string. Must be at least of size ETCPAL_MAC_STRING_BYTES.

Returns: kEtcPalErrOk: Conversion successful.; kEtcPalErrInvalid: Invalid argument.

◆ etcpal_netint_info_cmp()

int etcpal_netint_info_cmp	(	const EtcPalNetintInfo *	i1,
		const EtcPalNetintInfo *	i2
	)

Compare two EtcPalNetintInfos.

Parameters

[in]	i1	First EtcPalNetintInfo to compare.
[in]	i2	Second EtcPalNetintInfo to compare.

Returns: < 0: i1 < i2; 0: i1 == i2; > 0: i1 > i2

◆ etcpal_string_to_ip()

etcpal_error_t etcpal_string_to_ip	(	etcpal_iptype_t	type,
		const char *	src,
		EtcPalIpAddr *	dest
	)

Convert IPv4 and IPv6 addresses from text to binary form.

This function uses each platform's inet_pton() function under the hood.

Parameters

[in]	type	Type of string-represented IP address pointed to by src.
[in]	src	Character string containing a string-represented IP address.
[out]	dest	Filled in on success with the address.

Returns: kEtcPalErrOk: Success.; kEtcPalErrInvalid: Invalid parameter.; kEtcPalErrSys: System call failed.

◆ etcpal_string_to_mac()

etcpal_error_t etcpal_string_to_mac	(	const char *	src,
		EtcPalMacAddr *	dest
	)

Create a MAC address from a string representation.

Parses a string-represented MAC address and fills in an EtcPalMacAddr structure with the result. The input should be of the form: xx:xx:xx:xx:xx:xx, or xxxxxxxxxxxx (hexadecimal letters can be in upper- or lowercase).

Parameters

[in]	src	The null-terminated string to convert.
[out]	dest	MAC address structure to fill in with the parse result.

Returns: kEtcPalErrOk: Parse successful.; kEtcPalErrInvalid: Parse failed or invalid argument.

◆ ip_etcpal_to_os()

size_t ip_etcpal_to_os	(	const EtcPalIpAddr *	ip,
		etcpal_os_ipaddr_t *	os_ip
	)

Convert an EtcPalIpAddr to a platform-specific IP address.

Most of the time etcpal_os_ipaddr_t is defined as a struct sockaddr. Since most platforms use struct sockaddr (which holds an IP address, port, and additional information) in functions which only require IP addresses, this function will fill in only part of the etcpal_os_ipaddr_t (the address family, address, and for IPv6, the scope ID).

Parameters

[in]	ip	The EtcPalIpAddr to convert from.
[out]	os_ip	Filled in on success with the platform-specific IP address.

Returns: On success, the size of os_ip, for convenience. Returns 0 if an invalid argument was provided.

◆ ip_os_to_etcpal()

bool ip_os_to_etcpal	(	const etcpal_os_ipaddr_t *	os_ip,
		EtcPalIpAddr *	ip
	)

Convert a platform-specific IP address to an EtcPalIpAddr.

Most of the time etcpal_os_ipaddr_t is defined as a struct sockaddr. Since most platforms use struct sockaddr (which holds an IP address, port, and additional information) in functions which only require IP addresses, this function will discard some information, including any port value in the sockaddr.

Parameters

[in]	os_ip	Platform-specific IP address to convert from.
[out]	ip	Filled in on success with the EtcPalIpAddr.

Returns: true on success, false if an invalid argument was provided.

◆ sockaddr_etcpal_to_os()

size_t sockaddr_etcpal_to_os	(	const EtcPalSockAddr *	sa,
		etcpal_os_sockaddr_t *	os_sa
	)

Convert an EtcPalSockAddr to a platform-specific socket address.

On most platforms, etcpal_os_sockaddr_t is defined to struct sockaddr.

Parameters

[in]	sa	The EtcPalSockAddr to convert from.
[out]	os_sa	Filled in on success with the platform-specific socket address.

Returns: On success, the size of os_sa, for convenience. Returns 0 if an invalid argument was provided.

◆ sockaddr_os_to_etcpal()

bool sockaddr_os_to_etcpal	(	const etcpal_os_sockaddr_t *	os_sa,
		EtcPalSockAddr *	sa
	)

Convert a platform-specific socket address to an EtcPalSockAddr.

On most platforms, etcpal_os_sockaddr_t is defined to struct sockaddr.

Parameters

[in]	os_sa	Platform-specific socket address to convert from.
[out]	sa	Filled in on success with the EtcPalSockAddr.

Returns: true on success, false if an invalid argument was provided.

Overview

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

EtcPalIpAddr macros

Macro Definition Documentation

◆ ETCPAL_IP_INVALID_INIT

◆ ETCPAL_IP_INVALID_INIT_VALUES

◆ ETCPAL_IP_IS_INVALID

◆ ETCPAL_IP_IS_V4

◆ ETCPAL_IP_IS_V6

◆ ETCPAL_IP_SET_INVALID

◆ ETCPAL_IP_SET_V4_ADDRESS

◆ ETCPAL_IP_SET_V6_ADDRESS

◆ ETCPAL_IP_SET_V6_ADDRESS_WITH_SCOPE_ID

◆ ETCPAL_IP_V4_ADDRESS

◆ ETCPAL_IP_V6_ADDRESS

◆ ETCPAL_IP_V6_SCOPE_ID

◆ ETCPAL_IPV4_INIT

◆ ETCPAL_IPV4_INIT_VALUES

◆ ETCPAL_IPV6_INIT

◆ ETCPAL_IPV6_INIT_VALUES

◆ ETCPAL_MAC_CMP

◆ ETCPAL_MAC_IS_NULL

Typedef Documentation

◆ EtcPalIpAddr

◆ EtcPalMcastNetintId

◆ EtcPalSockAddr

Enumeration Type Documentation

◆ etcpal_iptype_t

Function Documentation

◆ etcpal_ip_and_port_equal()

◆ etcpal_ip_cmp()

◆ etcpal_ip_is_link_local()

◆ etcpal_ip_is_loopback()

◆ etcpal_ip_is_multicast()

◆ etcpal_ip_is_wildcard()

◆ etcpal_ip_mask_from_length()

◆ etcpal_ip_mask_length()

◆ etcpal_ip_network_portions_equal()

◆ etcpal_ip_set_wildcard()

◆ etcpal_ip_to_string()

◆ etcpal_mac_to_string()

◆ etcpal_netint_info_cmp()

◆ etcpal_string_to_ip()

◆ etcpal_string_to_mac()

◆ ip_etcpal_to_os()

◆ ip_os_to_etcpal()

◆ sockaddr_etcpal_to_os()

◆ sockaddr_os_to_etcpal()