E-MailRelay
glocation.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 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 
29 namespace GNet
30 {
31  class Location ;
32  class Resolver ;
33 }
34 
35 /// \class GNet::Location
36 /// A class that holds a host/service name pair and the preferred address
37 /// family (if any), and also the results of a name-to-address lookup, ie. the
38 /// remote address and canonical host name. The actual name-to-address lookup
39 /// is done externally, and the results are deposited into the Location object
40 /// with update().
41 ///
42 /// One of the constructors allows an extended host/service format for
43 /// transparent SOCKS support: before the "@" separator is the host/service
44 /// pair passed verbatim to the socks server for it to resolve (see
45 /// socksFarHost()); after the "@" is the host/service pair for the
46 /// socks server itself, which we resolve and connect to (see host()).
47 ///
48 /// \see GNet::ClientPtr
49 ///
51 {
52 public:
53  G_EXCEPTION( InvalidFormat , "invalid host:service format" ) ;
54 
55  Location( const std::string & host , const std::string & service , int family = AF_UNSPEC ) ;
56  ///< Constructor taking a host/service string.
57 
58  Location( const std::string & socks_host , const std::string & socks_service ,
59  const std::string & far_host , const std::string & far_service ,
60  int family = AF_UNSPEC ) ;
61  ///< Constructor for socks. The first pair of parameters are for
62  ///< the socks server, and the second pair are for the target
63  ///< server.
64 
65  explicit Location( const std::string & location_string , int family = AF_UNSPEC ) ;
66  ///< Constructor taking a formatted host/service string.
67  ///< The format supports the extended format for socks as
68  ///< "far-host:far-service@socks-host:socks-service".
69  ///< Throws if incorrectly formatted.
70 
71  bool socks() const ;
72  ///< Returns true if a socks location.
73 
74  std::string host() const ;
75  ///< Returns the remote host name, as passed in to the constructor.
76 
77  std::string service() const ;
78  ///< Returns the remote service name, as passed in to the constructor.
79 
80  void resolveTrivially() ;
81  ///< If host() and service() are already in address format then do a trivial
82  ///< update() so that the location is immediately resolved(), albeit with an
83  ///< empty canonical name().
84 
85  void update( const Address & address , const std::string & canonical_name ) ;
86  ///< Updates the address and canonical name, typically after doing
87  ///< a name lookup on host() and service().
88 
89  int family() const ;
90  ///< Returns the preferred name resolution address family, or AF_UNSPEC.
91 
92  bool dgram() const ;
93  ///< Returns true if the name resolution should be specifically for datagram
94  ///< sockets.
95 
96  bool resolved() const ;
97  ///< Returns true after update() has been called.
98 
99  Address address() const ;
100  ///< Returns the remote address.
101 
102  std::string name() const ;
103  ///< Returns the remote canonical name. Returns the empty string if
104  ///< not available.
105 
106  std::string displayString() const ;
107  ///< Returns a string representation for logging and debug.
108 
109  G::EpochTime updateTime() const ;
110  ///< Returns the time of the last update() or zero if never update()d.
111 
112  unsigned int socksFarPort() const ;
113  ///< Returns the port number for the socks far server.
114  ///< Precondition: socks()
115 
116  std::string socksFarHost() const ;
117  ///< Returns the port for the socks far server.
118  ///< Precondition: socks()
119 
120 private:
121  static std::string head( const std::string & ) ;
122  static std::string tail( const std::string & ) ;
123  static bool socksified( const std::string & , std::string & , unsigned int & ) ;
124  static std::string sockless( const std::string & ) ;
125 
126 private:
127  std::string m_host ;
128  std::string m_service ;
129  bool m_address_valid ;
130  Address m_address ;
131  int m_family ;
132  bool m_dgram ;
133  std::string m_canonical_name ;
134  G::EpochTime m_update_time ;
135  bool m_socks ;
136  std::string m_socks_far_host ;
137  unsigned int m_socks_far_port ;
138 } ;
139 
140 namespace GNet
141 {
142  inline std::ostream & operator<<( std::ostream & stream , const Location & location )
143  {
144  return stream << location.displayString() ;
145  }
146 }
147 
148 #endif
A subsecond-resolution timestamp based on a time_t.
Definition: gdatetime.h:39
Network classes.
Definition: gaddress.h:29
The GNet::Address class encapsulates a TCP/UDP transport address.
Definition: gaddress.h:54
bool socks() const
Returns true if a socks location.
Definition: glocation.cpp:180
std::string displayString() const
Returns a string representation for logging and debug.
Definition: glocation.cpp:169
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
bool dgram() const
Returns true if the name resolution should be specifically for datagram sockets.
Definition: glocation.cpp:131
std::string name() const
Returns the remote canonical name.
Definition: glocation.cpp:164
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:153
Address address() const
Returns the remote address.
Definition: glocation.cpp:148
std::string socksFarHost() const
Returns the port for the socks far server.
Definition: glocation.cpp:190
bool resolved() const
Returns true after update() has been called.
Definition: glocation.cpp:143
std::string service() const
Returns the remote service name, as passed in to the constructor.
Definition: glocation.cpp:121
unsigned int socksFarPort() const
Returns the port number for the socks far server.
Definition: glocation.cpp:185
int family() const
Returns the preferred name resolution address family, or AF_UNSPEC.
Definition: glocation.cpp:126
Location(const std::string &host, const std::string &service, int family=AF_UNSPEC)
Constructor taking a host/service string.
Definition: glocation.cpp:32
void resolveTrivially()
If host() and service() are already in address format then do a trivial update() so that the location...
Definition: glocation.cpp:136
std::string host() const
Returns the remote host name, as passed in to the constructor.
Definition: glocation.cpp:116
G::EpochTime updateTime() const
Returns the time of the last update() or zero if never update()d.
Definition: glocation.cpp:175