netint (Network Interfaces)

Overview

C++ utilities for the netint (Network Interfaces) module.

Functions
etcpal::Expected< std::vector< etcpal::NetintInfo > >	GetInterfaces () noexcept
	Get a list of network interfaces on the system. More...
etcpal::Expected< std::vector< etcpal::NetintInfo > >	GetInterfacesForIndex (NetintIndex index) noexcept
	Get a list of network interfaces that have the index specified. More...
etcpal::Expected< etcpal::NetintInfo >	GetInterfaceWithIp (const IpAddr &ip) noexcept
	Get the network interface that has the specified IP address. More...
etcpal::Expected< NetintIndex >	GetDefaultInterface (etcpal::IpAddrType type) noexcept
	Get information about the default network interface. More...
etcpal::Expected< NetintIndex >	GetInterfaceForDest (const etcpal::IpAddr &dest) noexcept
	Get the network interface that the system will choose when routing an IP packet to the specified destination. More...
etcpal::Error	RefreshInterfaces () noexcept
	Refresh the list of network interfaces. More...
bool	IsUp (NetintIndex index) noexcept
	Determine whether a network interface is currently up and running. More...

Function Documentation

GetDefaultInterface()

etcpal::Expected<NetintIndex> etcpal::netint::GetDefaultInterface ( etcpal::IpAddrType  type )

inlinenoexcept

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.

Returns

The index of the default interface on success.

kEtcPalErrInvalid: Invalid argument provided.

kEtcPalErrNotInit: Module not initialized.

kEtcPalErrNotFound: No default interface found for this type.

GetInterfaceForDest()

etcpal::Expected<NetintIndex> etcpal::netint::GetInterfaceForDest ( const etcpal::IpAddr &  dest )

inlinenoexcept

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

Returns

The index of the chosen interface on success.

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.

GetInterfaces()

etcpal::Expected<std::vector<etcpal::NetintInfo> > etcpal::netint::GetInterfaces ( )

inlinenoexcept

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

The array of network interfaces on success.

kEtcPalErrInvalid: Invalid argument provided.

kEtcPalErrNotInit: Module not initialized.

kEtcPalErrNotFound: No system interfaces were found.

GetInterfacesForIndex()

etcpal::Expected<std::vector<etcpal::NetintInfo> > etcpal::netint::GetInterfacesForIndex ( NetintIndex  index )

inlinenoexcept

Get a list of network interfaces that have the index specified.

See Network Interface Indexes for more information.

Parameters

[in]

index

Index for which to get interfaces.

Returns

The array of matching network interfaces on success.

kEtcPalErrInvalid: Invalid argument provided.

kEtcPalErrNotInit: Module not initialized.

kEtcPalErrNotFound: No interfaces found for this index.

GetInterfaceWithIp()

etcpal::Expected<etcpal::NetintInfo> etcpal::netint::GetInterfaceWithIp ( const IpAddr &  ip )

inlinenoexcept

Get the network interface that has the specified IP address.

Parameters

[in]

ip

The IP address assigned to the desired interface.

Returns

Information for the matching interface if found.

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.

IsUp()

bool etcpal::netint::IsUp ( NetintIndex  index )

inlinenoexcept

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::RefreshInterfaces() is called.

Parameters

index

Index of the interface to check.

Returns

true: The interface indicated by index is up.

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

RefreshInterfaces()

etcpal::Error etcpal::netint::RefreshInterfaces ( )

inlinenoexcept

Refresh the list of network interfaces.

Rebuilds the cached array of network interfaces that is returned via the etcpal::netint::GetInterfaces() function.

Returns

kEtcPalErrOk: Interfaces refreshed.

Other error codes from the underlying platform are possible here.