EtcPal  0.4.1
ETC Platform Abstraction Layer (EtcPal)
View other versions:
inet (Internet Addressing)

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...
 
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:

#define ETCPAL_IP_INVALID_INIT
An initializer for an invalid EtcPalIpAddr.
Definition: inet.h:121
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:

#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_ptrPointer 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_ptrPointer 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_ptrPointer 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_ptrPointer 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)
@ kEtcPalIpTypeV4
This EtcPalIpAddr contains an IPv4 address.
Definition: inet.h:57

Set the IPv4 address in a EtcPalIpAddr.

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

Parameters
etcpal_ip_ptrPointer to a EtcPalIpAddr.
valIPv4 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_ptrPointer to a EtcPalIpAddr.
addr_valIPv6 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)
#define ETCPAL_IPV6_BYTES
The number of bytes in an IPv6 address.
Definition: inet.h:63
@ kEtcPalIpTypeV6
This EtcPalIpAddr contains an IPv6 address.
Definition: inet.h:59

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_ptrPointer to a EtcPalIpAddr.
addr_valIPv6 address to set (uint8_t[]). Must be at least of length ETCPAL_IPV6_BYTES. Gets copied into the struct.
scope_id_valIPv6 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_ptrPointer 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_ptrPointer 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_ptrPointer 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
#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
#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);
#define ETCPAL_IPV6_INIT(...)
An initializer for an EtcPalIpAddr representing an IPv6 address.
Definition: inet.h:195

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:
{ \
.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
ETCPAL_IPV6_INIT_VALUES(0x20, 0x01, 0x0d, 0xb8, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x12, 0x34, 0x56, 0x78)
};
#define ETCPAL_IPV6_INIT_VALUES(...)
A set of initializer values for an EtcPalIpAddr representing an IPv6 address.
Definition: inet.h:174

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]mac1ptrPointer to first EtcPalMacAddr to compare.
[in]mac2ptrPointer 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
macptrPointer 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

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

An IP address with associated interface and port.

Ports are in host byte order.

Enumeration Type Documentation

◆ 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]sock1First EtcPalSockAddr to compare.
[in]sock2Second 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]ip1First EtcPalIpAddr to compare.
[in]ip2Second 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]ipAddress 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]ipAddress 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]ipAddress 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]ipAddress 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]typeType of netmask to create, either IPv4 or IPv6.
[in]mask_lengthLength 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]netmaskNetmask 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]ip1First EtcPalIpAddr to compare.
[in]ip2Second EtcPalIpAddr to compare.
[in]netmaskThe 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]typeType of wildcard to create, either IPv4 or IPv6.
[out]ipAddress 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]srcAddress to convert to string form.
[out]destFilled 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]srcMAC address to convert to a string.
[out]destCharacter 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_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]typeType of string-represented IP address pointed to by src.
[in]srcCharacter string containing a string-represented IP address.
[out]destFilled 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]srcThe null-terminated string to convert.
[out]destMAC 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]ipThe EtcPalIpAddr to convert from.
[out]os_ipFilled 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_ipPlatform-specific IP address to convert from.
[out]ipFilled 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]saThe EtcPalSockAddr to convert from.
[out]os_saFilled 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_saPlatform-specific socket address to convert from.
[out]saFilled in on success with the EtcPalSockAddr.
Returns
true on success, false if an invalid argument was provided.