E-MailRelay
gresolver.h
Go to the documentation of this file.
1//
2// Copyright (C) 2001-2023 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 "gexceptionsink.h"
28#include "gexception.h"
29#include "gaddress.h"
30#include <vector>
31#include <memory>
32
33namespace GNet
34{
35 class Resolver ;
36 class ResolverImp ;
37}
38
39//| \class GNet::Resolver
40/// A class for synchronous or asynchronous network name to address resolution.
41/// The implementation uses getaddrinfo() at its core, with std::thread used for
42/// asynchronous resolve requests, with hooks into the GNet::EventLoop via
43/// GNet::FutureEvent.
44///
46{
47public:
48 G_EXCEPTION( Error , tx("asynchronous resolver error") ) ;
49 G_EXCEPTION( BusyError , tx("asynchronous resolver still busy") ) ;
50 using AddressList = std::vector<Address> ;
51 struct Callback /// An interface used for GNet::Resolver callbacks.
52 {
53 virtual ~Callback() = default ;
54 ///< Destructor.
55
56 virtual void onResolved( std::string error , Location ) = 0 ;
57 ///< Called on completion of GNet::Resolver name resolution.
58 } ;
59
61 ///< Constructor taking a callback interface reference.
62 ///< The exception sink is called if an exception is thrown
63 ///< out of Callback::onResolved().
64
65 ~Resolver() ;
66 ///< Destructor. The results of any pending asynchronous resolve
67 ///< request are discarded asynchronously, although in extreme
68 ///< cases this destructor may block doing a thread join.
69
70 void start( const Location & ) ;
71 ///< Starts asynchronous name-to-address resolution.
72 ///< Precondition: async() && !busy()
73
74 static std::string resolve( Location & ) ;
75 ///< Does synchronous name resolution. Fills in the name
76 ///< and address fields of the supplied Location structure.
77 ///< The returned error string is zero length on success.
78
79 static AddressList resolve( const std::string & host , const std::string & service , int family = AF_UNSPEC , bool dgram = false ) ;
80 ///< Does synchronous name resolution returning a list
81 ///< of addresses. Errors are not reported. The empty
82 ///< list is returned on error.
83
84 static bool async() ;
85 ///< Returns true if the resolver supports asynchronous operation.
86 ///< If it doesnt then start() will always throw.
87
88 bool busy() const ;
89 ///< Returns true if there is a pending resolve request.
90
91public:
92 Resolver( const Resolver & ) = delete ;
93 Resolver( Resolver && ) = delete ;
94 Resolver & operator=( const Resolver & ) = delete ;
95 Resolver & operator=( Resolver && ) = delete ;
96
97private:
98 friend class GNet::ResolverImp ;
99 void done( const std::string & , const Location & ) ;
100
101private:
102 Callback & m_callback ;
103 ExceptionSink m_es ;
104 std::unique_ptr<ResolverImp> m_imp ;
105} ;
106
107#endif
A tuple containing an ExceptionHandler interface pointer and a bound 'exception source' pointer.
A class that represents the remote target for out-going client connections.
Definition: glocation.h:71
A class for synchronous or asynchronous network name to address resolution.
Definition: gresolver.h:46
static std::string resolve(Location &)
Does synchronous name resolution.
Definition: gresolver.cpp:194
~Resolver()
Destructor.
Definition: gresolver.cpp:181
Resolver(Callback &, ExceptionSink)
Constructor taking a callback interface reference.
Definition: gresolver.cpp:174
static bool async()
Returns true if the resolver supports asynchronous operation.
Definition: gresolver.cpp:257
void start(const Location &)
Starts asynchronous name-to-address resolution.
Definition: gresolver.cpp:233
bool busy() const
Returns true if there is a pending resolve request.
Definition: gresolver.cpp:252
Network classes.
Definition: gdef.h:1144
constexpr const char * tx(const char *p)
A briefer alternative to G::gettext_noop().
Definition: ggettext.h:84
An interface used for GNet::Resolver callbacks.
Definition: gresolver.h:52
virtual ~Callback()=default
Destructor.
virtual void onResolved(std::string error, Location)=0
Called on completion of GNet::Resolver name resolution.