E-MailRelay

gresolverfuture.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 gresolverfuture.h
19///
20
21#ifndef G_NET_RESOLVER_FUTURE_H
22#define G_NET_RESOLVER_FUTURE_H
23
24#include "gdef.h"
25#include "gaddress.h"
26#include "gresolver.h"
27#include <utility>
28#include <vector>
29#include <string>
30
31 namespace GNet
32{
33 class ResolverFuture ;
34}
35
36//| \class GNet::ResolverFuture
37/// A 'future' shared-state class for asynchronous name resolution that
38/// holds parameters and results of a call to getaddrinfo(), as performed
39/// by the run() method.
40///
41/// The run() method can be called from a worker thread and the results
42/// collected by the main thread using get() once the worker thread has
43/// signalled that it has finished. The signalling mechanism is outside
44/// the scope of this class (see GNet::FutureEvent).
45///
46/// Eg:
47/// \code
48///
49/// ResolverFuture f( "example.com" , "smtp" , AF_INET , false ) ;
50/// std::thread t( &ResolverFuture::run , f ) ;
51/// ...
52/// t.join() ;
53/// Address a = f.get().first ;
54/// if( f.error() ) throw std::runtime_error( f.reason() ) ;
55/// \endcode
56///
57 class GNet::ResolverFuture
58{
59 public:
60 struct Result /// Result structure for GNet::ResolverFuture::get().
61 {
62 Address address ;
63 std::string canonicalName ; // if requested
64 } ;
65 using List = std::vector<Address> ;
66
67 ResolverFuture( const std::string & host , const std::string & service ,
68 int family , const Resolver::Config & ) ;
69 ///< Constructor for resolving the given host and service names.
70
71 ~ResolverFuture() ;
72 ///< Destructor.
73
74 ResolverFuture & run() noexcept ;
75 ///< Does the synchronous name resolution and stores the result.
76 ///< Returns *this.
77
78 Result get() ;
79 ///< Returns the resolved address after run() has completed.
80 ///< Returns a default address if an error().
81
82 void get( List & ) ;
83 ///< Returns by reference the resolved addresses after run() has
84 ///< completed by appending to the given list. Appends nothing
85 ///< if an error().
86
87 bool error() const ;
88 ///< Returns true if name resolution failed or no suitable
89 ///< address was returned. Use after get().
90
91 std::string reason() const ;
92 ///< Returns the reason for the error().
93 ///< Precondition: error()
94
95public:
96 ResolverFuture( const ResolverFuture & ) = delete ;
97 ResolverFuture( ResolverFuture && ) = delete ;
98 ResolverFuture & operator=( const ResolverFuture & ) = delete ;
99 ResolverFuture & operator=( ResolverFuture && ) = delete ;
100
101private:
102 static std::string encode( const std::string & , bool ) ;
103 std::string failure() const ;
104 bool fetch( List & ) const ;
105 bool fetch( Result & ) const ;
106 bool failed() const ;
107 std::string none() const ;
108 std::string ipvx() const ;
109
110private:
111 Resolver::Config m_config ;
112 bool m_numeric_service ;
113 std::string m_host ;
114 const char * m_host_p ;
115 std::string m_service ;
116 const char * m_service_p ;
117 int m_family ;
118 struct addrinfo m_ai_hint {} ;
119 int m_rc {0} ;
120 struct addrinfo * m_ai {nullptr} ;
121 std::string m_reason ;
122} ;
123
124#endif
GNet::Address
The GNet::Address class encapsulates a TCP/UDP transport address.
Definition: gaddress.h:63
GNet::ResolverFuture
A 'future' shared-state class for asynchronous name resolution that holds parameters and results of a...
Definition: gresolverfuture.h:58
GNet::ResolverFuture::get
Result get()
Returns the resolved address after run() has completed.
Definition: gresolverfuture.cpp:149
GNet::ResolverFuture::error
bool error() const
Returns true if name resolution failed or no suitable address was returned.
Definition: gresolverfuture.cpp:159
GNet::ResolverFuture::reason
std::string reason() const
Returns the reason for the error().
Definition: gresolverfuture.cpp:164
GNet::ResolverFuture::ResolverFuture
ResolverFuture(const std::string &host, const std::string &service, int family, const Resolver::Config &)
Constructor for resolving the given host and service names.
Definition: gresolverfuture.cpp:32
GNet::ResolverFuture::run
ResolverFuture & run() noexcept
Does the synchronous name resolution and stores the result.
Definition: gresolverfuture.cpp:70
GNet::ResolverFuture::~ResolverFuture
~ResolverFuture()
Destructor.
Definition: gresolverfuture.cpp:54
GNet::Resolver
A class for synchronous or asynchronous network name to address resolution.
Definition: gresolver.h:47
gaddress.h
gresolver.h
GNet
Network classes.
Definition: gdef.h:1243
std
STL namespace.
GNet::ResolverFuture::Result
Result structure for GNet::ResolverFuture::get().
Definition: gresolverfuture.h:61
GNet::Resolver::Config
A configuration structure for GNet::Resolver.
Definition: gresolver.h:52