UPnPsdk::CAddrinfo Class Reference

Get information from the operating system about an internet address. More...

#include <addrinfo.hpp>

Public Member Functions
	CAddrinfo (std::string_view a_node, std::string_view a_service, const int a_flags=0, const int a_socktype=SOCK_STREAM)
	Constructor for getting an address information with service name.
	CAddrinfo (std::string_view a_node, const int a_flags=0, const int a_socktype=SOCK_STREAM)
	Constructor for getting an address information from only an internet address.
Getter
const ::addrinfo *	operator-> () const noexcept
	Read access to members of the addrinfo structure
bool	get_first ()
	Get the first entry of an address info from the operating system.
bool	get_next () noexcept
	Get next available address information.
void	sockaddr (SSockaddr &a_saddr)
	Get the socket address from current selcted address information.
const std::string &	what () const
	Get cached error message.

Detailed Description

Get information from the operating system about an internet address.

An empty node returns information of the loopback interface, but either node or service, but not both, may be empty. With setting everything unspecified, except service, we get all available combinations with loopback interfaces but different on platforms. a_socktype specifies the preferred socket type SOCK_STREAM or SOCK_DGRAM. Specifying 0 for this argument indicates that socket addresses of any socket type can be returned. For example:

CAddrinfo ai("", 0, 0); // same as
CAddrinfo ai("", "0", 0, 0);

may find
"[::1]" (SOCK_STREAM), "[::1]" (SOCK_DGRAM),
"127.0.0.1" (SOCK_STREAM), "127.0.0.1" (SOCK_DGRAM).

To get default SOCK_STREAM loopback interfaces just use:

CAddrinfo ai("");

May find, where find_first() should be preferred what ever it finds:
find_first() -> "[::1]"
find_next() -> "127.0.0.1"

To get address information for passive listening on all local network adapters with default SOCK_STREAM, a_node must be empty, but not a_service and a_flags must be set at least to AI_PASSIVE, for example:

CAddrinfo ai("", AI_PASSIVE | AI_NUMERICHOST); // same as
CAddrinfo ai("", "0", AI_PASSIVE | AI_NUMERICHOST);

Of course you can set a specific port (a_service) other than 0.

Definition at line 55 of file addrinfo.hpp.

Constructor & Destructor Documentation

CAddrinfo() [1/2]

UPnPsdk::CAddrinfo::CAddrinfo	(	std::string_view	a_node,
		std::string_view	a_service,
		const int	a_flags = 0,
		const int	a_socktype = SOCK_STREAM
	)

Constructor for getting an address information with service name.

Parameters

[in]	a_node	Name or address string of a node, e.g. "example.com" or "[2001.db8::1]".
[in]	a_service	Service name resp. port can also be a port number string, e.g. "https" or "443".
[in]	a_flags	Optional: flags that can be "or-ed", e.g. AI_PASSIVE | AI_NUMERICHOST. Details at getaddrinfo — Linux manual page or getaddrinfo — Microsoft Learn
[in]	a_socktype	Optional: can be SOCK_STREAM, SOCK_DGRAM, or 0 (any possible socket type).

Definition at line 28 of file addrinfo.cpp.

CAddrinfo() [2/2]

UPnPsdk::CAddrinfo::CAddrinfo	(	std::string_view	a_node,
		const int	a_flags = 0,
		const int	a_socktype = SOCK_STREAM
	)

Constructor for getting an address information from only an internet address.

Parameters

[in]	a_node	Name or address string of a node, e.g. "example.com:50001" or "[2001.db8::1]:50002" or "2001.db8::2".
[in]	a_flags	Optional: flags that can be "or-ed", e.g. AI_PASSIVE | AI_NUMERICHOST. Details at getaddrinfo — Linux manual page or getaddrinfo — Microsoft Learn
[in]	a_socktype	Optional: can be SOCK_STREAM, SOCK_DGRAM, or 0 (any possible socket type).

Definition at line 44 of file addrinfo.cpp.

Member Function Documentation

operator->()

const ::addrinfo * UPnPsdk::CAddrinfo::operator-> ( ) const

noexcept

Read access to members of the addrinfo structure

// Usage e.g.:
CAddrinfo aiObj("localhost", "50001", AF_UNSPEC, SOCK_STREAM);
if (!aiObj.get_first())
    handle_error();
if (aiObj->ai_socktype == SOCK_DGRAM) {} // is SOCK_STREAM here
if (aiObj->ai_family == AF_INET6) { handle_ipv6(); };

The operating system returns the information in a structure that you can read to get all details.

Definition at line 81 of file addrinfo.cpp.

get_first()

bool UPnPsdk::CAddrinfo::get_first

(

)

Get the first entry of an address info from the operating system.

// Usage e.g.:
CAddrinfo ai("[2001:db8::1]", "50050", AF_UNSPEC, SOCK_STREAM, AI_NUMERICHOST);
// or
CAddrinfo ai("[2001:db8::1]:50050");
if (!ai.get_first()) {
    std::cerr << ai.what() << '\n';
    handle_failed_address_info();
}
normal_execution();

Note

It is important to careful check the error situation because loading information depends on the real environment that we cannot control. Name resolution may fail because to be unspecified, DNS server may be temporary down, etc.

Usually this getter is called one time after constructing the object. This gets an address information from the operating system that may also use its internal name resolver inclusive contacting external DNS server. If you use the flag AI_NUMERICHOST with the constructor then a possible expensive name resolution to DNS server is suppressed.

If you have iterated address information entries with CAddrinfo::get_next() and want to restart you can do it with call CAddrinfo::get_first() again. It will read the information from the operating system again and could be used to monitor changes of address information. But note that this is quite expensive because always memory is freed and new allocated for the information list so doing this in a busy loop is not very useful.

Returns

true if address information is available
false otherwise

Todo:

Manage to use WSAEAFNOSUPPORT for EAI_ADDRFAMILY that isn't defined on win32.

Definition at line 89 of file addrinfo.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

get_next()

bool UPnPsdk::CAddrinfo::get_next ( )

noexcept

Get next available address information.

// Usage e.g.:
CAddrinfo aiObj("localhost");
if (!aiObj.get_first())
    handle_error();
do {
    int af = aiObj->ai_family;
    std::cout << "AF=" << af << "\n";
} while (aiObj.get_next()); // handle next addrinfo

If more than one address information is available this is used to switch to the next addrinfo.

Returns

true if address information is available
false otherwise

Definition at line 202 of file addrinfo.cpp.

sockaddr()

void UPnPsdk::CAddrinfo::sockaddr

(

SSockaddr &

a_saddr

)

Get the socket address from current selcted address information.

Parameters

[out]

a_saddr

Reference to a socket address structure that will be filled with the address information. If no information is available (e.g. CAddrinfo::get_first() wasn't called) an unspecified socket address is returned (netaddr "", netaddrp ":0").

Definition at line 216 of file addrinfo.cpp.

what()

const std::string & UPnPsdk::CAddrinfo::what

(

)

const

Get cached error message.

// Usage e.g.:
CAddrinfo ai("[2001:db8::1]:50050");
if (!ai.get_first()) {
    std::cerr << ai.what() << '\n';
    handle_failed_address_info();
}

It should be noted that are different error messages returned by different platforms.

Definition at line 226 of file addrinfo.cpp.

Here is the caller graph for this function:

---

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

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