E-MailRelay

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