E-MailRelay
gresolver.h
Go to the documentation of this file.
1 //
2 // Copyright (C) 2001-2018 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 "gexception.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, and with hooks into the GNet::EventLoop.
41 ///
43 {
44 public:
45  typedef std::vector<Address> AddressList ;
46  G_EXCEPTION( Error , "asynchronous resolver error" ) ;
47  G_EXCEPTION( BusyError , "asynchronous resolver still busy" ) ;
48  struct Callback /// An interface used for GNet::Resolver callbacks.
49  {
50  virtual ~Callback() ;
51  virtual void onResolved( std::string error , Location ) = 0 ;
52  ///< Called on completion of GNet::Resolver name resolution.
53  } ;
54 
56  ///< Constructor taking a callback interface reference.
57  ///< The exception handler's onException() method is called if
58  ///< an exception is thrown out of Callback::onResolved().
59 
60  ~Resolver() ;
61  ///< Destructor. The results of any pending asynchronous resolve
62  ///< request are discarded asynchronously, although in extreme
63  ///< cases this destructor may block doing a thread join.
64 
65  void start( const Location & ) ;
66  ///< Starts asynchronous name-to-address resolution.
67  ///< Precondition: async() && !busy()
68 
69  static std::string resolve( Location & ) ;
70  ///< Does synchronous name resolution. Fills in the name
71  ///< and address fields of the supplied Location structure.
72  ///< The returned error string is zero length on success.
73 
74  static AddressList resolve( const std::string & host , const std::string & service , int family = AF_UNSPEC , bool dgram = false ) ;
75  ///< Does synchronous name resolution returning a list
76  ///< of addresses. Errors are not reported. The empty
77  ///< list is returned on error.
78 
79  static bool async() ;
80  ///< Returns true if the resolver supports asynchronous operation.
81  ///< If it doesnt then start() will always throw.
82 
83  bool busy() const ;
84  ///< Returns true if there is a pending resolve request.
85 
86 private:
87  void operator=( const Resolver & ) ; // not implemented
88  Resolver( const Resolver & ) ; // not implemented
89  friend class GNet::ResolverImp ;
90  void done( std::string , Location ) ;
91 
92 private:
93  Callback & m_callback ;
94  ExceptionHandler & m_eh ;
95  unique_ptr<ResolverImp> m_imp ;
96 } ;
97 
98 #endif
~Resolver()
Destructor.
Definition: gresolver.cpp:165
void start(const Location &)
Starts asynchronous name-to-address resolution.
Definition: gresolver.cpp:210
Network classes.
Definition: gaddress.h:29
A class for synchronous or asynchronous network name to address resolution.
Definition: gresolver.h:42
An interface used for GNet::Resolver callbacks.
Definition: gresolver.h:48
An abstract interface for handling exceptions thrown out of event-loop callbacks (socket events...
A class that holds a host/service name pair and the preferred address family (if any), and also the results of a name-to-address lookup, ie.
Definition: glocation.h:50
virtual void onResolved(std::string error, Location)=0
Called on completion of GNet::Resolver name resolution.
static bool async()
Returns true if the resolver supports asynchronous operation.
Definition: gresolver.cpp:232
bool busy() const
Returns true if there is a pending resolve request.
Definition: gresolver.cpp:227
static std::string resolve(Location &)
Does synchronous name resolution.
Definition: gresolver.cpp:177
Resolver(Callback &, ExceptionHandler &)
Constructor taking a callback interface reference.
Definition: gresolver.cpp:158
A private "pimple" implementation class used by GNet::Resolver to do asynchronous name resolution...
Definition: gresolver.cpp:38