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
31namespace 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///
58{
59public:
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
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
The GNet::Address class encapsulates a TCP/UDP transport address.
Definition: gaddress.h:63
A 'future' shared-state class for asynchronous name resolution that holds parameters and results of a...
Result get()
Returns the resolved address after run() has completed.
bool error() const
Returns true if name resolution failed or no suitable address was returned.
std::string reason() const
Returns the reason for the error().
ResolverFuture(const std::string &host, const std::string &service, int family, const Resolver::Config &)
Constructor for resolving the given host and service names.
ResolverFuture & run() noexcept
Does the synchronous name resolution and stores the result.
~ResolverFuture()
Destructor.
A class for synchronous or asynchronous network name to address resolution.
Definition: gresolver.h:47
Network classes.
Definition: gdef.h:1243
STL namespace.
Result structure for GNet::ResolverFuture::get().
A configuration structure for GNet::Resolver.
Definition: gresolver.h:52