cosmos::AddressInfoList Class Reference

Resolve DNS names and provide the resulting list of AddressInfos. More...

#include <AddressInfoList.hxx>

Public Member Functions
void	resolve (const SysString node, const SysString service)
	Resolve addresses for the given node/service name combination.
void	clear ()
	Clear a previously stored resolve result.
auto &	hints ()
	Access the stored AddressHints to modify the resolve behaviour.
void	setHints (const AddressHints &hints)
	Set a new AddressHints structure for modifying the resolve behaviour.
bool	valid () const
	Returns whether currently a valid resolve result is stored.
AddressInfoIterator	begin () const
AddressInfoIterator	end () const

Protected Attributes
AddressHints	m_hints
struct addrinfo *	m_addrs = nullptr

Detailed Description

Resolve DNS names and provide the resulting list of AddressInfos.

This type allows to resolve internet host names and service names into SocketAddress types suitable for binding a socket on or for connecting a socket to.

This API is restricted to IP based protocols. By default it reports socket addresses for all available combinations socket families (SocketFamily::INET and SocketFamily::INET6) and socket types (e.g. SocketType::STREAM and SocketType::DGRAM). To filter the result list the AddressHints structure is used which can be set via setHints() or manipulated in-place using hints(). The default flags for AddressHints are {AddressHints::Flag::V4_MAPPED, AddressHints::Flag::ADDR_CONFIG}. This matches the default behaviour of getaddrinfo() with no hints provided.

To iterate over the result list the AddressInfoIterator type is provided. A simple range based for loop does the trick for iterating over all results.

Definition at line 29 of file AddressInfoList.hxx.

Constructor & Destructor Documentation

~AddressInfoList()

cosmos::AddressInfoList::~AddressInfoList ( )

inline

Definition at line 32 of file AddressInfoList.hxx.

                           {
                clear();
        }

Member Function Documentation

begin()

AddressInfoIterator cosmos::AddressInfoList::begin ( ) const

inline

Definition at line 95 of file AddressInfoList.hxx.

                                          {
                return AddressInfoIterator{reinterpret_cast<const AddressInfo*>(m_addrs)};
        }

clear()

void cosmos::AddressInfoList::clear

(

)

Clear a previously stored resolve result.

Definition at line 21 of file AddressInfoList.cxx.

                            {
        if (m_addrs) {
                ::freeaddrinfo(m_addrs);
                m_addrs = nullptr;
        }
}

end()

AddressInfoIterator cosmos::AddressInfoList::end ( ) const

inline

Definition at line 99 of file AddressInfoList.hxx.

                                        {
                return AddressInfoIterator{nullptr};
        }

hints()

auto & cosmos::AddressInfoList::hints ( )

inline

Access the stored AddressHints to modify the resolve behaviour.

Changes to the AddressHints will only become effective for the next call to resolve().

Definition at line 74 of file AddressInfoList.hxx.

                      {
                return m_hints;
        }

resolve()

void cosmos::AddressInfoList::resolve	(	const SysString	node,
		const SysString	service )

Resolve addresses for the given node/service name combination.

The given node name is either an internet host name to be resolved, or a numerical IP address. If AddressHints::Flag::NUMERIC_HOST is set then it is always expected to be a numerical IP address string.

If node is empty and AddressHints::Flag::PASSIVE is set then an address suitable for binding (listening) on is returned.

If node is empty and AddressHints::Fag::PASSIVE is not set then an address based on the loopback device suitable for communication on the localhost is returned.

The given service is either an IP service name as found in /etc/services, or a numerical IP port number. If AddressHints::Flag::NUMERIC_SERVICE is set then it is always expected to be a numerical port string.

If service is empty then the returned socket addresses will have no port portion set.

Either node or service may be specified as empty, but not both.

If resolving the requested parameters fails then a specialized ResolveError exception is thrown to describe the error.

Definition at line 7 of file AddressInfoList.cxx.

                                                                           {
        clear();
 
        const auto res = ::getaddrinfo(
                   node.empty() ? nullptr :    node.raw(),
                service.empty() ? nullptr : service.raw(),
                &m_hints, &m_addrs
        );
 
        if (res != 0) {
                cosmos_throw(ResolveError(ResolveError::Code{res}));
        }
}

setHints()

void cosmos::AddressInfoList::setHints ( const AddressHints & hints )

inline

Set a new AddressHints structure for modifying the resolve behaviour.

See also

hints()

Definition at line 82 of file AddressInfoList.hxx.

                                                 {
                m_hints = hints;
        }

valid()

bool cosmos::AddressInfoList::valid ( ) const

inline

Returns whether currently a valid resolve result is stored.

If there is no resolve result then begin() equals end() and iterating over the list yields no elements.

Definition at line 91 of file AddressInfoList.hxx.

                           {
                return m_addrs != nullptr;
        }

Member Data Documentation

m_addrs

struct addrinfo* cosmos::AddressInfoList::m_addrs = nullptr

protected

Definition at line 106 of file AddressInfoList.hxx.

m_hints

AddressHints cosmos::AddressInfoList::m_hints

protected

Definition at line 105 of file AddressInfoList.hxx.

---

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

• include/net/AddressInfoList.hxx
• src/net/AddressInfoList.cxx