netint (Network Interfaces)

Overview

A platform-neutral, thread-safe 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_interfaces() and refreshed using etcpal_netint_refresh_interfaces(). Here is the best way to retrieve the interfaces if a refresh could happen on a different thread at any time:

size_t num_netints = 4;  // Start with estimate which eventually has the actual number written to it
EtcPalNetintInfo* netints = calloc(num_netints, sizeof(EtcPalNetintInfo));
while(netints && etcpal_netint_get_interfaces(netints, &num_netints) == kEtcPalErrBufSize)
{
  EtcPalNetintInfo* new_netints = realloc(netints, num_netints * sizeof(EtcPalNetintInfo));
  if (new_netints)
  {
    netints = new_netints;
  }
  else
  {
    free(netints);
    netints = NULL;
  }
}
 
for (const EtcPalNetintInfo* netint = netints; netint && (netint < netints + num_netints); ++netint)
{
  // Record information or do something with each network interface in turn
}
 
free(netints);

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 will only change if the etcpal_netint_refresh_interfaces() function is called. These functions are all thread-safe, so the interfaces can be refreshed on one thread while other queries are made on another thread.

Functions
etcpal_error_t	etcpal_netint_get_interfaces (EtcPalNetintInfo *netints, size_t *num_netints)
	Get a list of network interfaces on the system (or just the number of interfaces). More...
etcpal_error_t	etcpal_netint_get_interfaces_for_index (unsigned int netint_index, EtcPalNetintInfo *netints, size_t *num_netints)
	Get a list of network interfaces (or just the number of interfaces) that have the index specified. More...
etcpal_error_t	etcpal_netint_get_interface_with_ip (const EtcPalIpAddr *ip, EtcPalNetintInfo *netint)
	Get the network interface that has the specified IP address. 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 ()
	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_interface_with_ip()

etcpal_error_t etcpal_netint_get_interface_with_ip	(	const EtcPalIpAddr *	ip,
		EtcPalNetintInfo *	netint
	)

Get the network interface that has the specified IP address.

Parameters

[in]	ip	The IP address assigned to the desired interface.
[out]	netint	If an interface with the specified IP assigned is found, its information will be filled in here.

Returns

kEtcPalErrOk: netint was filled in with a matching interface's information.

kEtcPalErrInvalid: Invalid argument provided.

kEtcPalErrNotInit: Module not initialized.

kEtcPalErrNotFound: No interfaces found for this IP address.

kEtcPalErrSys: Multiple interfaces were configured at the same IP address, which means the system is misconfigured.

etcpal_netint_get_interfaces()

etcpal_error_t etcpal_netint_get_interfaces	(	EtcPalNetintInfo *	netints,
		size_t *	num_netints
	)

Get a list of network interfaces on the system (or just the number of interfaces).

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.

Parameters

[out]	netints	Application-provided array to be filled in on success with the array of network interfaces. This can be set to NULL if only interested in the number of interfaces.
[in,out]	num_netints	Initialize this with the size of the netints array (0 if it's NULL). Filled in on success with the number of network interfaces on the system (reallocate the netints array if this ends up being larger). Cannot be a NULL pointer.

Returns

kEtcPalErrOk: netints and num_netints were filled in with all system interfaces.

kEtcPalErrInvalid: Invalid argument provided.

kEtcPalErrNotInit: Module not initialized.

kEtcPalErrBufSize: The netints array was not large enough to hold all of the network interfaces. See the value of num_netints to determine how large the array needs to be.

kEtcPalErrNotFound: No system interfaces were found.

etcpal_netint_get_interfaces_for_index()

etcpal_error_t etcpal_netint_get_interfaces_for_index	(	unsigned int	netint_index,
		EtcPalNetintInfo *	netints,
		size_t *	num_netints
	)

Get a list of network interfaces (or just the number of interfaces) that have the index specified.

See Network Interface Indexes for more information.

Parameters

[in]	index	Index for which to get interfaces.
[out]	netints	Application-provided array to be filled in on success with the array of network interfaces. This can be set to NULL if only interested in the number of interfaces.
[in,out]	num_netints	Initialize this with the size of the netints array (0 if it's NULL). Filled in on success with the number of network interfaces that match the index (reallocate the netints array if this ends up being larger). Cannot be NULL.

Returns

kEtcPalErrOk: netints and num_netints were filled in with all matching interfaces.

kEtcPalErrInvalid: Invalid argument provided.

kEtcPalErrNotInit: Module not initialized.

kEtcPalErrBufSize: The netints array was not large enough to hold all of the network interfaces. See the value of num_netints to determine how large the array needs to be.

kEtcPalErrNotFound: No interfaces found for this index.

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

(

)

Refresh the list of network interfaces.

Rebuilds the cached array of network interfaces that is returned via the etcpal_netint_get_interfaces() function.

Returns

kEtcPalErrOk: Interfaces refreshed.

Other error codes from the underlying platform are possible here.