E-MailRelay

- Main Page
- Namespaces
- Classes
- Files

- File List
- File Members

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 ///
50 class GNet::Location
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
G::EpochTime
A subsecond-resolution timestamp based on a time_t.
Definition: gdatetime.h:39
GNet
Network classes.
Definition: gaddress.h:29
GNet::Address
The GNet::Address class encapsulates a TCP/UDP transport address.
Definition: gaddress.h:54
GNet::Location::socks
bool socks() const
Returns true if a socks location.
Definition: glocation.cpp:180
GNet::Location::displayString
std::string displayString() const
Returns a string representation for logging and debug.
Definition: glocation.cpp:169
GNet::Location
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
GNet::Location::dgram
bool dgram() const
Returns true if the name resolution should be specifically for datagram sockets.
Definition: glocation.cpp:131
GNet::Location::name
std::string name() const
Returns the remote canonical name.
Definition: glocation.cpp:164
GNet::Location::update
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
GNet::Location::address
Address address() const
Returns the remote address.
Definition: glocation.cpp:148
GNet::Location::socksFarHost
std::string socksFarHost() const
Returns the port for the socks far server.
Definition: glocation.cpp:190
GNet::Location::resolved
bool resolved() const
Returns true after update() has been called.
Definition: glocation.cpp:143
GNet::Location::service
std::string service() const
Returns the remote service name, as passed in to the constructor.
Definition: glocation.cpp:121
gdatetime.h
GNet::Location::socksFarPort
unsigned int socksFarPort() const
Returns the port number for the socks far server.
Definition: glocation.cpp:185
gexception.h
GNet::Location::family
int family() const
Returns the preferred name resolution address family, or AF_UNSPEC.
Definition: glocation.cpp:126
gaddress.h
GNet::Location::Location
Location(const std::string &host, const std::string &service, int family=AF_UNSPEC)
Constructor taking a host/service string.
Definition: glocation.cpp:32
GNet::Location::resolveTrivially
void resolveTrivially()
If host() and service() are already in address format then do a trivial update() so that the location...
Definition: glocation.cpp:136
GNet::Location::host
std::string host() const
Returns the remote host name, as passed in to the constructor.
Definition: glocation.cpp:116
GNet::Location::updateTime
G::EpochTime updateTime() const
Returns the time of the last update() or zero if never update()d.
Definition: glocation.cpp:175