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