E-MailRelay
glocation.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 glocation.h
19///
20
21#ifndef G_NET_LOCATION_H
22#define G_NET_LOCATION_H
23
24#include "gdef.h"
25#include "gaddress.h"
26#include "gdatetime.h"
27#include "gexception.h"
28#include <new>
29
30namespace GNet
31{
32 class Location ;
33 class Resolver ;
34}
35
36//| \class GNet::Location
37/// A class that represents the remote target for out-going client connections.
38/// It holds a host/service name pair and the preferred address family (if any)
39/// and also the results of a DNS lookup for the remote address.
40///
41/// The actual DNS lookup of host() and service() should be done externally,
42/// with the results deposited into the Location object with update().
43///
44/// An extended format is supported for transparent SOCKS connection: before
45/// the "@" separator is the host/port pair passed verbatim to the socks
46/// server for it to resolve; after the "@" is the host/service pair for
47/// the socks server itself, which should be resolved as normal.
48///
49/// URL-style square brackets can be used for IPv6 address, eg( "[::1]:1").
50///
51/// Local-domain socket addresses are supported, but obviously DNS lookups
52/// of host() and service() will never work, update() will reject them,
53/// and the socks code will not allow them as the 'far' address.
54///
55/// Synopsis:
56/// \code
57/// Location location( remote_server ) ;
58/// location.resolveTrivially() ;
59/// if( !location.resolved() )
60/// {
61/// Resolver resolver( location.host() , location.service() , location.family() ) ;
62/// if( resolver.resolve() )
63/// location.update( resolver.address() ) ;
64/// }
65/// \endcode
66///
67/// \see GNet::Client, GNet::Resolver
68///
70{
71public:
72 G_EXCEPTION( InvalidFormat , tx("invalid host:service format") )
73 G_EXCEPTION( InvalidFamily , tx("invalid address family") )
74
75 explicit Location( const std::string & spec , int family = AF_UNSPEC ) ;
76 ///< Constructor taking a formatted "host:service" string.
77 ///< The location specification allows an extended format for
78 ///< socks, as "far-host:far-port@socks-host:socks-service".
79 ///< Throws if incorrectly formatted. The optional 'family'
80 ///< parameter is made available to the resolver via
81 ///< the family() method.
82
83 static Location nosocks( const std::string & spec , int family = AF_UNSPEC ) ;
84 ///< Factory function for a remote location but not allowing
85 ///< the extended syntax for socks.
86
87 static Location socks( const std::string & socks_server , const std::string & far_server ) ;
88 ///< Factory function for a remote location explicitly
89 ///< accessed via socks.
90
91 std::string host() const ;
92 ///< Returns the remote host name derived from the constructor
93 ///< parameter.
94
95 std::string service() const ;
96 ///< Returns the remote service name derived from the constructor
97 ///< parameter.
98
99 int family() const ;
100 ///< Returns the preferred name resolution address family as
101 ///< passed to the constructor.
102
103 bool socks() const ;
104 ///< Returns true if a socks location.
105
106 bool resolveTrivially() ;
107 ///< If host() and service() are already in address format then do a trivial
108 ///< update() so that the location is immediately resolved(). Does
109 ///< nothing if already resolved(). Returns resolved().
110
111 void update( const Address & address ) ;
112 ///< Updates the address, typically after doing a name lookup on
113 ///< host() and service(). Throws if an invalid address family.
114
115 bool update( const Address & address , std::nothrow_t ) ;
116 ///< Updates the address, typically after doing a name lookup on
117 ///< host() and service(). Returns false if an invalid address
118 ///< family.
119
120 bool resolved() const ;
121 ///< Returns true after update() has been called or resolveTrivially()
122 ///< succeeded.
123
124 Address address() const ;
125 ///< Returns the remote address.
126
127 std::string displayString() const ;
128 ///< Returns a string representation for logging and debug.
129
130 G::SystemTime updateTime() const ;
131 ///< Returns the time of the last update() or zero if never update()d.
132
133 unsigned int socksFarPort() const ;
134 ///< Returns the port number for the socks far server.
135 ///< Precondition: socks()
136
137 std::string socksFarHost() const ;
138 ///< Returns the port for the socks far server.
139 ///< Precondition: socks()
140
141private:
142 Location( const std::string & socks , const std::string & far_ , int family ) ; // socks()
143 Location( const std::string & spec , int family , int ) ; // nosocks()
144 static std::string head( const std::string & ) ;
145 static std::string tail( const std::string & ) ;
146 static bool socksified( const std::string & , std::string & , std::string & ) ;
147 static std::string sockless( const std::string & ) ;
148
149private:
150 std::string m_host ;
151 std::string m_service ;
152 bool m_address_valid ;
153 Address m_address ;
154 int m_family ;
155 G::SystemTime m_update_time ;
156 bool m_using_socks ;
157 std::string m_socks_far_host ;
158 std::string m_socks_far_port ;
159} ;
160
161namespace GNet
162{
163 inline std::ostream & operator<<( std::ostream & stream , const Location & location )
164 {
165 return stream << location.displayString() ;
166 }
167}
168
169#endif
The GNet::Address class encapsulates a TCP/UDP transport address.
Definition: gaddress.h:63
A class that represents the remote target for out-going client connections.
Definition: glocation.h:70
int family() const
Returns the preferred name resolution address family as passed to the constructor.
Definition: glocation.cpp:132
bool resolved() const
Returns true after update() has been called or resolveTrivially() succeeded.
Definition: glocation.cpp:148
bool resolveTrivially()
If host() and service() are already in address format then do a trivial update() so that the location...
Definition: glocation.cpp:137
std::string displayString() const
Returns a string representation for logging and debug.
Definition: glocation.cpp:182
std::string socksFarHost() const
Returns the port for the socks far server.
Definition: glocation.cpp:217
G::SystemTime updateTime() const
Returns the time of the last update() or zero if never update()d.
Definition: glocation.cpp:200
bool socks() const
Returns true if a socks location.
Definition: glocation.cpp:206
std::string service() const
Returns the remote service name derived from the constructor parameter.
Definition: glocation.cpp:127
unsigned int socksFarPort() const
Returns the port number for the socks far server.
Definition: glocation.cpp:211
void update(const Address &address)
Updates the address, typically after doing a name lookup on host() and service().
Definition: glocation.cpp:158
Address address() const
Returns the remote address.
Definition: glocation.cpp:153
std::string host() const
Returns the remote host name derived from the constructor parameter.
Definition: glocation.cpp:122
Location(const std::string &spec, int family=AF_UNSPEC)
Constructor taking a formatted "host:service" string.
Definition: glocation.cpp:28
static Location nosocks(const std::string &spec, int family=AF_UNSPEC)
Factory function for a remote location but not allowing the extended syntax for socks.
Definition: glocation.cpp:77
Represents a unix-epoch time with microsecond resolution.
Definition: gdatetime.h:140
Network classes.
Definition: gdef.h:1243
constexpr const char * tx(const char *p) noexcept
A briefer alternative to G::gettext_noop().
Definition: ggettext.h:84