Address module

The address module contains all classes and free functions to manage network addresses. More...

Classes
class	UPnPsdk::CAddrinfo
	Get information from the operating system about an internet address. More...
class	UPnPsdk::CNetadapter
	Get information from local network adapters. More...
union	UPnPsdk::sockaddr_t
	Helpful union of the different socket address structures. More...
struct	UPnPsdk::SSockaddr
	Trivial ::sockaddr structures enhanced with methods. More...

Functions
uint8_t	UPnPsdk::netmask_to_bitmask (const ::sockaddr_storage *a_netmask)
	Get prefix bit number from a network address mask.
void	UPnPsdk::bitmask_to_netmask (const ::sockaddr_storage *a_saddr, const unsigned int a_prefixlength, SSockaddr &a_saddrObj)
	Get network address mask from address prefix bit number.
int	UPnPsdk::to_port (std::string_view a_port_str, in_port_t *const a_port_num=nullptr) noexcept
	Free function to check if a string represents a valid port number.
void	UPnPsdk::split_addr_port (std::string_view a_addr_str, std::string &a_addr, std::string &a_serv)
	Free function to split inet address and port(service)
UPnPsdk_API::std::ostream &	UPnPsdk::operator<< (::std::ostream &os, SSockaddr &saddr)
	output the netaddress
bool	UPnPsdk::anonymous_namespace{sockaddr.cpp}::sockaddrcmp (const ::sockaddr_storage *a_ss1, const ::sockaddr_storage *a_ss2) noexcept
	logical compare two sockaddr structures

Detailed Description

The address module contains all classes and free functions to manage network addresses.

References

• RFC 6724 - Default Address Selection for Internet Protocol Version 6 (IPv6)
• sockaddr structures as union
• Why do I get wrong pointer to a base class with a virtual constructor

---

Class Documentation

UPnPsdk::sockaddr_t

union UPnPsdk::sockaddr_t

Helpful union of the different socket address structures.

Never need to use type casts with pointer to different socket address structures. For details about using this helpful union have a look at sockaddr structures as union

Definition at line 34 of file sockaddr.hpp.

Class Members
::sockaddr_storage	ss
::sockaddr_un	sun
::sockaddr_in6	sin6
::sockaddr_in	sin
::sockaddr	sa

Function Documentation

netmask_to_bitmask()

uint8_t UPnPsdk::netmask_to_bitmask

(

const ::sockaddr_storage *

a_netmask

)

Get prefix bit number from a network address mask.

// Usage e.g.:
::sockaddr_storage saddr{};
try {
    std::cout << "bitmask is " << netmask_to_bitmask(&saddr) << '\n';
} catch (const std::runtime_error& ex) { handle_error() }

Returns the length, in bits, of the prefix or network part of the IP address, e.g. 64 from "[2001:db8::1]/64". A value of 255 is commonly used to represent an illegal value but this function throws an exception instead.

Returns

The length, in bits, of the prefix or network part of the IP address, 0..32 for IPv4, 0..128 for IPv6.

Exceptions

std::runtime_error

with an invalid netmask with an invalid address family.

Parameters

[in]

a_netmask

Pointer to a socket address structure containing the netmask.

Definition at line 14 of file netadapter.cpp.

Here is the caller graph for this function:

bitmask_to_netmask()

void UPnPsdk::bitmask_to_netmask	(	const ::sockaddr_storage *	a_saddr,
		const unsigned int	a_prefixlength,
		SSockaddr &	a_saddrObj
	)

Get network address mask from address prefix bit number.

// Usage e.g.:
::sockaddr_storage saddr{};
SSockaddr saObj;
try {
    bitmask_to_netmask(&saddr, 64, saObj);
} catch (const std::runtime_error& ex) { handle_error() }
std::cout << "netmask is " << saObj.netaddr() << '\n';

Exceptions

std::runtime_error

if the associated socket address a_saddr is not given. if the prefix length exceeds its maximum size (128 for IPv6, 32 for IPv4), with an invalid address family.

Parameters

[in]	a_saddr	Pointer to a structure containing the socket address the netmask is associated.
[in]	a_prefixlength	IPv6 or IPv4 address prefix length as number of set bits as given e.g. with 64 in [2001:db8::1]/64.
[out]	a_saddrObj	Reference to a socket address object that will be filled with the netmask.

Definition at line 108 of file netadapter.cpp.

to_port()

int UPnPsdk::to_port ( std::string_view  a_port_str, in_port_t *const  a_port_num = nullptr  )

noexcept

Free function to check if a string represents a valid port number.

// Usage e.g.:
in_port_t port{};
switch (to_port("65535", &port) {
case -1:
    std::cout << "Invalid port number string.\n";
    break;
case 0:
    std::cout << "Valid port number: " << std::to_string(port) << '\n';
    break;
case 1:
    std::cout << Valid number but out of scope 0..65535 for ports.\n";
    break;
}
 
if (to_port("65536") != 0) { // do nothing with port }

Returns

On success: 0
A binary port number in host byte order is returned in a_port_num, so you can use it in your application without conversion. If you want to store it in a netaddr structure you must use htons(). An empty input string returns 0.
On error:

• -1 A valid port number was not found.
•  1 Valid numeric value found but out of scope, not in range 0..65535.

Todo:

Update on MacOS to Clang compiler that supports std::from_chars(). See below TODO.

Parameters

[in]	a_port_str	String that may represent a port number.
[in,out]	a_port_num	Optional: if given, pointer to a variable that will be filled with the binary port number in host byte order.

Definition at line 89 of file sockaddr.cpp.

Here is the caller graph for this function:

split_addr_port()

void UPnPsdk::split_addr_port	(	std::string_view	a_addr_str,
		std::string &	a_addr,
		std::string &	a_serv
	)

Free function to split inet address and port(service)

// Usage e.g., not a complete list:
std::string addr, serv;
split_addr_port("[2001:db8::1]:50001", addr, serv);
split_addr_port("2001:DB8::1", addr, serv);
split_addr_port("127.0.0.1:0", addr, serv);
split_addr_port("127.0.0.1", addr, serv);
split_addr_port(":50002", addr, serv);
split_addr_port("example.COM:50003", addr, serv);
split_addr_port("example.com:HTTPS", addr, serv);
split_addr_port("[::FFff:142.250.185.99]:ssh", addr, serv);

This is a function for special use to prepare input for system call ::getaddrinfo(). Its results returned in a_addr and a_serv are only useful for ::getaddrinfo() and are not meant for general usage. For example returned IPv6 addresses never have brackets because ::getaddrinfo() does not accept them, port numbers are limited to 65535 because ::getaddrinfo() accepts also greater numbers with overrun to 65535 + 1 = 0.

Parameters

[in]	a_addr_str	Any string. If it can be interpreted as an ip-address or -name with or without port number or name, its parts will be retured.
[in,out]	a_addr	Reference of a string that will be filled with the ip address part. This can also be a alphanumeric name like "example.com"
[in,out]	a_serv	Reference of a string that will be filled with the port part.

Definition at line 185 of file sockaddr.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

operator<<()

UPnPsdk_API::std::ostream & UPnPsdk::operator<<	(	::std::ostream &	os,
		SSockaddr &	saddr
	)

output the netaddress

// Usage e.g.:
SSockaddr saObj;
saObj = "[2001:db8::1]:56789";
std::cout << saObj << "\n"; // output "[2001:db8::1]:56789"

sockaddrcmp()

bool UPnPsdk::anonymous_namespace{sockaddr.cpp}::sockaddrcmp ( const ::sockaddr_storage *  a_ss1, const ::sockaddr_storage *  a_ss2  )

noexcept

logical compare two sockaddr structures

To have logical equal socket addresses I compare the address family, the ip address, the scope, and the port.

Returns

true if socket addresses are logical equal
false otherwise

Definition at line 32 of file sockaddr.cpp.

Here is the call graph for this function:

Here is the caller graph for this function: