E-MailRelay
gresolver.h
Go to the documentation of this file.
1//
2// Copyright (C) 2001-2024 Graeme Walker <graeme_walker@users.sourceforge.net>
3//
4// This program is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8//
9// This program is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12// GNU General Public License for more details.
13//
14// You should have received a copy of the GNU General Public License
15// along with this program. If not, see <http://www.gnu.org/licenses/>.
16// ===
17///
18/// \file gresolver.h
19///
20
21#ifndef G_NET_RESOLVER_H
22#define G_NET_RESOLVER_H
23
24#include "gdef.h"
25#include "glocation.h"
26#include "geventhandler.h"
27#include "geventstate.h"
28#include "gexception.h"
29#include "gaddress.h"
30#include <vector>
31#include <utility>
32#include <memory>
33
34namespace GNet
35{
36 class Resolver ;
37 class ResolverImp ;
38}
39
40//| \class GNet::Resolver
41/// A class for synchronous or asynchronous network name to address resolution.
42/// The implementation uses getaddrinfo() at its core, with std::thread used for
43/// asynchronous resolve requests, with hooks into the GNet::EventLoop via
44/// GNet::FutureEvent.
45///
47{
48public:
49 G_EXCEPTION( Error , tx("asynchronous resolver error") )
50 G_EXCEPTION( BusyError , tx("asynchronous resolver still busy") )
51 struct Config /// A configuration structure for GNet::Resolver.
52 {
53 Config() ;
54 bool with_canonical_name {false} ;
55 bool raw {false} ; // straight to getaddrinfo() with no "xn--<punycode>" conversion
56 bool datagram {false} ; // for datagram sockets
57 bool idn_flag {false} ; // use glibc's AI_IDN flag if available
58 bool test_slow {false} ; // run slow for testing
59 Config & set_with_canonical_name( bool = true ) noexcept ;
60 Config & set_raw( bool = true ) noexcept ;
61 Config & set_convert_to_punycode( bool = true ) noexcept ;
62 Config & set_datagram( bool = true ) noexcept ;
63 Config & set_idn_flag( bool = true ) noexcept ;
64 } ;
65 using AddressList = std::vector<Address> ;
66 struct Callback /// An interface used for GNet::Resolver callbacks.
67 {
68 virtual ~Callback() = default ;
69 ///< Destructor.
70
71 virtual void onResolved( std::string error , Location ) = 0 ;
72 ///< Called on completion of GNet::Resolver name resolution.
73 } ;
74
76 ///< Constructor taking a callback interface reference.
77 ///< The exception sink is called if an exception is thrown
78 ///< out of Callback::onResolved().
79
80 ~Resolver() ;
81 ///< Destructor. The results of any pending asynchronous resolve
82 ///< request are discarded asynchronously, although in extreme
83 ///< cases this destructor may block doing a thread join.
84
85 void start( const Location & , const Config & = {} ) ;
86 ///< Starts asynchronous name-to-address resolution.
87 ///< Precondition: async() && !busy()
88
89 static std::pair<std::string,std::string> resolve( Location & , const Config & ) ;
90 ///< Does synchronous name resolution. Fills in the address
91 ///< of the supplied Location structure. Returns
92 ///< an error string (empty on success) and the canonical
93 ///< name, if requested (see Config::with_canonical_name).
94
95 static std::string resolve( Location & ) ;
96 ///< Does synchronous name resolution. Fills in the address
97 ///< of the supplied Location structure. Returns an
98 ///< error string, empty on success.
99
100 static AddressList resolve( const std::string & host , const std::string & service , int family = AF_UNSPEC , const Config & = {} ) ;
101 ///< Does synchronous name resolution returning a list
102 ///< of addresses. Errors are not reported. The empty
103 ///< list is returned on error.
104
105 static bool async() ;
106 ///< Returns true if the resolver supports asynchronous operation.
107 ///< If it doesnt then start() will always throw.
108
109 bool busy() const ;
110 ///< Returns true if there is a pending resolve request.
111
112public:
113 Resolver( const Resolver & ) = delete ;
114 Resolver( Resolver && ) = delete ;
115 Resolver & operator=( const Resolver & ) = delete ;
116 Resolver & operator=( Resolver && ) = delete ;
117
118private:
119 friend class GNet::ResolverImp ;
120 void done( const std::string & , const Location & ) ;
121
122private:
123 Callback & m_callback ;
124 EventState m_es ;
125 std::unique_ptr<ResolverImp> m_imp ;
126} ;
127
128inline GNet::Resolver::Config & GNet::Resolver::Config::set_with_canonical_name( bool b ) noexcept { with_canonical_name = b ; return *this ; }
129inline GNet::Resolver::Config & GNet::Resolver::Config::set_raw( bool b ) noexcept { raw = b ; return *this ; }
130inline GNet::Resolver::Config & GNet::Resolver::Config::set_datagram( bool b ) noexcept { datagram = b ; return *this ; }
131inline GNet::Resolver::Config & GNet::Resolver::Config::set_idn_flag( bool b ) noexcept { idn_flag = b ; return *this ; }
132
133#endif
A lightweight object containing an ExceptionHandler pointer, optional ExceptionSource pointer and opt...
Definition: geventstate.h:131
A class that represents the remote target for out-going client connections.
Definition: glocation.h:70
A class for synchronous or asynchronous network name to address resolution.
Definition: gresolver.h:47
~Resolver()
Destructor.
Definition: gresolver.cpp:180
Resolver(Callback &, EventState)
Constructor taking a callback interface reference.
Definition: gresolver.cpp:173
static std::pair< std::string, std::string > resolve(Location &, const Config &)
Does synchronous name resolution.
Definition: gresolver.cpp:198
void start(const Location &, const Config &={})
Starts asynchronous name-to-address resolution.
Definition: gresolver.cpp:236
static bool async()
Returns true if the resolver supports asynchronous operation.
Definition: gresolver.cpp:260
bool busy() const
Returns true if there is a pending resolve request.
Definition: gresolver.cpp:255
Network classes.
Definition: gdef.h:1243
constexpr const char * tx(const char *p) noexcept
A briefer alternative to G::gettext_noop().
Definition: ggettext.h:84
An interface used for GNet::Resolver callbacks.
Definition: gresolver.h:67
virtual ~Callback()=default
Destructor.
virtual void onResolved(std::string error, Location)=0
Called on completion of GNet::Resolver name resolution.
A configuration structure for GNet::Resolver.
Definition: gresolver.h:52