netint (Network Interfaces)

Overview

A platform-neutral method for enumerating network interfaces.

#include "etcpal/netint.h"

WARNING: This module must be explicitly initialized before use. Initialize the module by calling etcpal_init() with the relevant feature mask:

etcpal_init(ETCPAL_FEATURE_NETINTS);

After initialization, an array of the set of network interfaces which were present on the system at initialization time is kept internally. This array can be retrieved using etcpal_netint_get_num_interfaces() and etcpal_netint_get_interfaces():

size_t num_netints = etcpal_netint_get_num_interfaces();
const EtcPalNetintInfo* netint_array = etcpal_netint_get_interfaces();
for (const EtcPalNetintInfo* netint = netint_array; netint < netint_array + num_netints; ++netint)
{
  // Record information or do something with each network interface in turn
}

The network interface array is sorted by interface index (see Network Interface Indexes); multiple IP addresses assigned to the same physical interface are separated into different entries. This means multiple entries in the array can have the same index.

The module also attempts to determine the interface used for the system's default route (the route used to get to an arbitrary internet destination) and calls that the "default interface", which can be retrieved using etcpal_netint_get_default_interface().

The routing information can also be used to determine which network interface will be used for a given IP address destination, which can be handy for multicasting.

EtcPalIpAddr dest;
etcpal_string_to_ip(kEtcPalIpTypeV4, "192.168.200.35", &dest);
 
unsigned int index;
etcpal_netint_get_interface_for_dest(&dest, &index); // Index now holds the interface that will be used

The list of network interfaces is cached and does not change at runtime, unless the etcpal_netint_refresh_interfaces() function is called.

Functions
size_t	etcpal_netint_get_num_interfaces (void)
	Get the number of network interfaces present on the system. More...
const EtcPalNetintInfo *	etcpal_netint_get_interfaces (void)
	Get a list of network interfaces on the system. More...
etcpal_error_t	etcpal_netint_get_interfaces_by_index (unsigned int index, const EtcPalNetintInfo **netint_arr, size_t *netint_arr_size)
	Get a set of network interface addresses that have the index specified. More...
etcpal_error_t	etcpal_netint_get_default_interface (etcpal_iptype_t type, unsigned int *netint_index)
	Get information about the default network interface. More...
etcpal_error_t	etcpal_netint_get_interface_for_dest (const EtcPalIpAddr *dest, unsigned int *netint_index)
	Get the network interface that the system will choose when routing an IP packet to the specified destination. More...
etcpal_error_t	etcpal_netint_refresh_interfaces (bool *list_changed)
	Refresh the list of network interfaces. More...
bool	etcpal_netint_is_up (unsigned int netint_index)
	Determine whether a network interface is currently up and running. More...

Function Documentation

etcpal_netint_get_default_interface()

etcpal_error_t etcpal_netint_get_default_interface	(	etcpal_iptype_t	type,
		unsigned int *	netint_index
	)

Get information about the default network interface.

For our purposes, the 'default' network interface is defined as the interface that is chosen for the default IP route. The default interface is given as an OS network interface index - see Network Interface Indexes for more information. Note that since network interfaces can have multiple IP addresses assigned, this index may be shared by many entries returned by etcpal_netint_get_interfaces().

Parameters

[in]	type	The IP protocol for which to get the default network interface, either kEtcPalIpTypeV4 or kEtcPalIpTypeV6. A separate default interface is maintained for each.
[out]	netint_index	Pointer to value to fill with the index of the default interface.

Returns

kEtcPalErrOk: netint was filled in.

kEtcPalErrInvalid: Invalid argument provided.

kEtcPalErrNotInit: Module not initialized.

kEtcPalErrNotFound: No default interface found for this type.

etcpal_netint_get_interface_for_dest()

etcpal_error_t etcpal_netint_get_interface_for_dest	(	const EtcPalIpAddr *	dest,
		unsigned int *	netint_index
	)

Get the network interface that the system will choose when routing an IP packet to the specified destination.

Parameters

[in]	dest	IP address of the destination.
[out]	netint_index	Pointer to value to fill in with the index of the chosen interface.

Returns

kEtcPalErrOk: Netint filled in successfully.

kEtcPalErrInvalid: Invalid argument provided.

kEtcPalErrNotInit: Module not initialized.

kEtcPalErrNoNetints: No network interfaces found on system.

kEtcPalErrNotFound: No route was able to be resolved to the destination.

etcpal_netint_get_interfaces()

const EtcPalNetintInfo* etcpal_netint_get_interfaces

(

void

)

Get a list of network interfaces on the system.

For NICs with multiple IP addresses assigned, this module separates each address into its own entry in the netint array. Because of this, multiple array entries could have the same value for the index, mac and id parameters.

Returns

Pointer to an array of network interfaces of length etcpal_netint_get_num_interfaces(), or NULL if there are no interfaces present or the module is not initialized.

etcpal_netint_get_interfaces_by_index()

etcpal_error_t etcpal_netint_get_interfaces_by_index	(	unsigned int	index,
		const EtcPalNetintInfo **	netint_arr,
		size_t *	netint_arr_size
	)

Get a set of network interface addresses that have the index specified.

See Network Interface Indexes for more information.

Parameters

[in]	index	Index for which to get interfaces.
[out]	netint_arr	Filled in on success with the array of matching interfaces.
[out]	netint_arr_size	Filled in on success with the size of the matching interface array.

Returns

kEtcPalErrOk: netint_arr and netint_arr_size were filled in.

kEtcPalErrInvalid: Invalid argument provided.

kEtcPalErrNotInit: Module not initialized.

kEtcPalErrNotFound: No interfaces found for this index.

etcpal_netint_get_num_interfaces()

size_t etcpal_netint_get_num_interfaces

(

void

)

Get the number of network interfaces present on the system.

Returns

Number of interfaces present.

etcpal_netint_is_up()

bool etcpal_netint_is_up

(

unsigned int

netint_index

)

Determine whether a network interface is currently up and running.

Note

On Windows, cached network interface information is used to determine this, so the result for a given index will not change until etcpal_netint_refresh_interfaces() is called.

Parameters

netint_index

Index of the interface to check.

Returns

true: The interface indicated by netint_index is up.

false: The interface indicated by netint_index is down, or netint_index is invalid.

etcpal_netint_refresh_interfaces()

etcpal_error_t etcpal_netint_refresh_interfaces

(

bool *

list_changed

)

Refresh the list of network interfaces.

Rebuilds the cached array of network interfaces that is returned via the etcpal_netint_get_interfaces() function. If the refresh operation results in a different list (there is a different number of network interfaces, or any interface has changed IP settings), *list_changed is set to true.

Parameters

[out]

list_changed

Set to true if the set of interfaces has changed in any way.

Returns

kEtcPalErrOk: Interfaces refreshed.

Other error codes from the underlying platform are possible here.