UPnPsdk::CNetadapter Class Reference

Get information from local network adapters. More...

#include <netadapter.hpp>

Public Member Functions
UPnPsdk_API	CNetadapter (PNetadapter_platform a_na_platformPtr=std::make_shared< CNetadapter_platform >())
	Constructor.
UPnPsdk_API void	get_first ()
	Load a list of network adapters from the operating system and select its first entry.
UPnPsdk_API bool	get_next ()
	Select next entry from the network adapter list that was initial loaded with get_first().
UPnPsdk_API unsigned int	index () const
	Get index number from current selected list entry.
UPnPsdk_API std::string	name () const
	Get network adapter name from current selected list entry.
UPnPsdk_API void	sockaddr (SSockaddr &a_saddr) const
	Get socket address from current selected list entry.
UPnPsdk_API void	socknetmask (SSockaddr &a_snetmask) const
	Get socket address netmask from current selected list entry.
UPnPsdk_API unsigned int	bitmask () const
	Get prefix length from the ip address of the current selected local network adapter.
UPnPsdk_API bool	find_first (std::string_view a_name_or_addr="")
	Find local network adapter with given name or ip address.
UPnPsdk_API bool	find_first (const unsigned int a_index)
	Find first ip address on the local network adapter with given index number.
UPnPsdk_API bool	find_next ()
	Find next ip address from local network adapters.

Detailed Description

Get information from local network adapters.

// Example to get a link local address from a network adapter:
SSockaddr saObj;
CNetadapter nadaptObj;
try {
    nadaptObj.get_first();
    do {
        nadaptObj.sockaddr(saObj);
        if (saObj.ss.ss_family == AF_INET6 &&
            IN6_IS_ADDR_LINKLOCAL(&saObj.sin6.sin6_addr))
            break;
    } while (nadaptObj.get_next());
} catch (const std::exception& ex) { handle_error() }
 
if (saObj.ss.ss_family != AF_INET6 ||
    !IN6_IS_ADDR_LINKLOCAL(&saObj.sin6.sin6_addr))
    std::cout << "No local network adapter with link local address found.\n";
else
    std::cout << "Adapter " << nadaptObj.name() << " has lla " << saObj << '\n';

The operating system manages an internal list of the local network adapters. With this class you can get information about them. "Typically, nodes, not applications, automatically solve the source address selection. A node will choose the source address for a communication following some rules of best choice, per [RFC3484]." (REF: RFC4038 - IP Address Selection).

Definition at line 99 of file netadapter.hpp.

Constructor & Destructor Documentation

CNetadapter()

UPnPsdk::CNetadapter::CNetadapter

(

PNetadapter_platform

a_na_platformPtr = std::make_shared<CNetadapter_platform>()

)

Constructor.

Parameters

[in]

a_na_platformPtr

Inject the used di-service object that is by default the productive one but may also be a mocked object for Unit Tests. For example productive di-services are the objects to get local network adapter information on Unix platforms, or on Microsoft Windows platforms.

Definition at line 198 of file netadapter.cpp.

~CNetadapter()

UPnPsdk::CNetadapter::~CNetadapter ( )

virtual

Definition at line 203 of file netadapter.cpp.

Member Function Documentation

get_first()

void UPnPsdk::CNetadapter::get_first

(

)

Load a list of network adapters from the operating system and select its first entry.

Exceptions

std::runtime_error

Failed to get information from the network adapters: (detail information appended)

Definition at line 207 of file netadapter.cpp.

Here is the caller graph for this function:

get_next()

bool UPnPsdk::CNetadapter::get_next

(

)

Select next entry from the network adapter list that was initial loaded with get_first().

Returns

• true if next adapter in the list exists
• false otherwise

Definition at line 209 of file netadapter.cpp.

Here is the caller graph for this function:

index()

unsigned int UPnPsdk::CNetadapter::index

(

)

const

Get index number from current selected list entry.

This is the unique number of a network adapter as given by the operating system. It is the best way to identify a network adapter. 0 means the unspecified, unavailable adapter.

Returns

• 0 if the local network adapter does not exist. This should only be possible if you haven't successful selected an adapter before.
• otherwise index number of the selected adapter.

Definition at line 211 of file netadapter.cpp.

Here is the caller graph for this function:

name()

std::string UPnPsdk::CNetadapter::name

(

)

const

Get network adapter name from current selected list entry.

Returns

• "" (empty string) if the local network adapter does not exist. This should only be possible if you haven't successful selected an adapter before.
• otherwise name of the local network adapter like "lo", "wlan0", "Ethernet". etc.

Definition at line 213 of file netadapter.cpp.

Here is the caller graph for this function:

sockaddr()

void UPnPsdk::CNetadapter::sockaddr

(

SSockaddr &

a_saddr

)

const

Get socket address from current selected list entry.

Parameters

[in,out]

a_saddr

Reference to a socket address object that will be filled with the socket address from the current selected network adapter list entry.

Definition at line 215 of file netadapter.cpp.

Here is the caller graph for this function:

socknetmask()

void UPnPsdk::CNetadapter::socknetmask

(

SSockaddr &

a_snetmask

)

const

Get socket address netmask from current selected list entry.

This netmask belongs to the adapters network address that is current selected.

Parameters

[in,out]

a_snetmask

Reference to a socket address object that will be filled with the socket address netmask from the current selected network adapter list entry.

Definition at line 219 of file netadapter.cpp.

Here is the caller graph for this function:

bitmask()

unsigned int UPnPsdk::CNetadapter::bitmask

(

)

const

Get prefix length from the ip address of the current selected local network adapter.

Returns

Prefix length of the ip address from the current selected local network adapter.

Definition at line 223 of file netadapter.cpp.

Here is the caller graph for this function:

find_first() [1/2]

bool UPnPsdk::CNetadapter::find_first

(

std::string_view

a_name_or_addr = ""

)

Find local network adapter with given name or ip address.

// Usage e.g.:
CNetadapter nadaptObj;
try {
    nadaptObj.get_first();
} catch(xcp) { handle_error(); };
if (nadaptObj.find_first()) {
    SSockaddr saObj;
    nadaptObj.sockaddr(saObj);
    std::cout << "used local address is " << saObj << '\n';
 }
if (nadaptObj.find_first("[2001.db8::1:0:2]"))
    std::cout << "adapter name is " << nadaptObj.name() << '\n';

You have to get_first() entry from the internal network adapter list to load it. Then you can try to find_first() a local ip address from the loaded internal list. With no argument the operating system presents one as best choise. Due to _RFC 4038, 5.4.1 - IP_Address Selection, specifying the source address is not typically required.

If found, the ip address is selected so that you can get all its properties. With find_next() you can get following ip addresses.

If finding fails (find_first() == false) no selection is modified. Before starting lookup, the first local ip address was selected with get_first(). This is still selected but has mostly no useful meaning in the current context. You should not expect empty values.

find_first() and find_next() ignore loopback addresses by default. If you want them you must select them (see Parameters below). It is possible that you don't find the loopback adapter, e.g. find_first("lo"), or find_first(1), if it only has loopback addresses. You can use find_first("[::1]"), find_first("127.0.0.1"), or find_first("loopback") to also get the associated adapter info. "loopback" is preferred because using IP-version is not intended.

Returns

• true if adapter with given name or ip address was found
• false otherwise

Parameters

[in]

a_name_or_addr

no argument will select best local ip address by the operating system "loopback" (all lower case) will select the best loopback address local network adapter name (like "lo", "eth0", "Ethernet", etc.). This restricts find_next() to point only to next ip addresses of the selected adapter. an ip address.

Definition at line 234 of file netadapter.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

find_first() [2/2]

bool UPnPsdk::CNetadapter::find_first

(

const unsigned int

a_index

)

Find first ip address on the local network adapter with given index number.

Example at find_first(std::string_view). Of course you have to use an index number.

You have to get_first() entry of the internal network adapter list to load it. Then you can try to find_first(a_index) adapter from the loaded internal list. If found, the adapter is selected so that all its properties can be retrieved.

Returns

• true if adapter with given index number was found
• false otherwise

Parameters

[in]

a_index

Index number of the local network adapter.

Definition at line 314 of file netadapter.cpp.

Here is the call graph for this function:

find_next()

bool UPnPsdk::CNetadapter::find_next

(

)

Find next ip address from local network adapters.

Before using this method you have to use get_first() to load the internal network adapter list from the operating system and then use find_first() to specify and select the first wanted ip address. With this method you can find following ip addresses. When pre-selecting an adapter, e.g. find_first("eth0"), or find_first(index), find_next() will only select following ip addresses on this adapter. For more details have a look at find_first(std::string_view).

Returns

• true if the next item (ip address) was found
• false otherwise, or if you haven't used get_first() and find_first()

Definition at line 336 of file netadapter.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

---

The documentation for this class was generated from the following files:

• UPnPsdk/include/UPnPsdk/netadapter.hpp
• UPnPsdk/src/net/netadapter.cpp