E-MailRelay
gaddress.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 gaddress.h
19 ///
20 
21 #ifndef G_NET_ADDRESS__H
22 #define G_NET_ADDRESS__H
23 
24 #include "gdef.h"
25 #include "gstrings.h"
26 #include "gexception.h"
27 #include <string>
28 
29 namespace GNet
30 {
31  class Address ;
32  class Address4 ;
33  class Address6 ;
34  class AddressStorage ;
35  class AddressStorageImp ;
36  int inet_pton_imp( int f , const char * p , void * result ) ;
37  const char * inet_ntop_imp( int f , void * ap , char * buffer , size_t n ) ;
38 }
39 
40 /// \class GNet::Address
41 /// The GNet::Address class encapsulates a TCP/UDP transport address. The
42 /// address is exposed as a 'sockaddr' structure for low-level socket
43 /// operations.
44 ///
45 /// A double pimple pattern is used for the implementation; this class
46 /// instantiates either a GNet::Address4 implementation sub-object or a
47 /// GNet::Address6 sub-object depending on the address family, and forwards
48 /// its method calls directly to the one instantiated sub-object. In an
49 /// IPv4-only build the GNet::Address6 is forward-declared but not defined
50 /// and all methods are forwarded to the GNet::Address4 sub-object.
51 ///
52 /// \see GNet::Resolver
53 ///
55 {
56 public:
57  class Family /// A type-safe enumerator for IP address family.
58  {
59  public:
60  static Family ipv4() ;
61  static Family ipv6() ;
62  bool operator==( const Family & other ) const ;
63  bool operator!=( const Family & other ) const ;
64  private:
65  explicit Family( bool is4_ ) ;
66  bool is4 ;
67  } ;
68 
69  G_EXCEPTION( Error , "address error" ) ;
70  G_EXCEPTION( BadFamily , "unsupported address family" ) ;
71  G_EXCEPTION( BadString , "invalid address" ) ;
72 
73  static bool supports( Family ) ;
74  ///< Returns true if the implementation supports the given address family.
75 
76  Address( const Address & ) ;
77  ///< Copy constructor.
78 
79  explicit Address( const AddressStorage & ) ;
80  ///< Constructor taking a storage object.
81 
82  Address( const sockaddr * addr , socklen_t len ) ;
83  ///< Constructor using a given sockaddr. Throws an exception if an
84  ///< invalid structure. See also: validData()
85 
86  Address( Family , unsigned int port ) ;
87  ///< Constructor for a wildcard INADDR_ANY address with the given port
88  ///< number. Throws an exception if an invalid port number.
89  /// \see validPort()
90 
91  explicit Address( const std::string & display_string ) ;
92  ///< Constructor taking a string originally obtained from displayString().
93  ///< Throws an exception if an invalid string. See also validString().
94 
95  Address( const std::string & ip , unsigned int port ) ;
96  ///< Constructor taking an ip-address and a port number. Throws an
97  ///< exception if an invalid string.
98 
99  ~Address() ;
100  ///< Destructor.
101 
102  static Address defaultAddress() ;
103  ///< Returns a default address, being the IPv4 wildcard address
104  ///< with a zero port number.
105 
106  static Address loopback( Family , unsigned int port = 0U ) ;
107  ///< Returns a loopback address.
108 
109  void operator=( const Address & addr ) ;
110  ///< Assignment operator.
111 
112  const sockaddr * address() const ;
113  ///< Returns the sockaddr address. Typically used when making socket
114  ///< system calls. Never returns nullptr.
115 
116  sockaddr * address() ;
117  ///< This is a non-const version of address() for compiling on systems
118  ///< which are not properly const-clean.
119 
120  socklen_t length() const;
121  ///< Returns the size of the sockaddr address. See address().
122 
123  std::string displayString() const ;
124  ///< Returns a string which represents the transport address for
125  ///< debugging and diagnostics purposes.
126 
127  std::string hostPartString() const ;
128  ///< Returns a string which represents the network address for
129  ///< debugging and diagnostics purposes.
130 
131  unsigned int port() const;
132  ///< Returns port part of the address.
133 
134  int domain() const ;
135  ///< Returns the address 'domain', eg. PF_INET.
136 
137  unsigned long scopeId( unsigned long default_ = 0UL ) const ;
138  ///< Returns the scope-id. Returns the default if scope-ids are not
139  ///< supported by the underlying address type.
140 
141  static bool validPort( unsigned int n ) ;
142  ///< Returns true if the port number is within the valid range. This
143  ///< can be used to avoid exceptions from the relevant constructors.
144 
145  static bool validString( const std::string & display_string , std::string * reason = nullptr ) ;
146  ///< Returns true if the transport-address display string is valid.
147  ///< This can be used to avoid exceptions from the relevant constructor.
148 
149  static bool validStrings( const std::string & ip , const std::string & port_string , std::string * reason = nullptr ) ;
150  ///< Returns true if the combined network-address string and port string
151  ///< is valid. This can be used to avoid exceptions from the relevant
152  ///< constructor.
153 
154  static bool validData( const sockaddr * , socklen_t len ) ;
155  ///< Returns true if the sockaddr data is valid. This can be used
156  ///< to avoid exceptions from the relevant constructor.
157 
158  bool sameHostPart( const Address & other ) const ;
159  ///< Returns true if the two addresses have the same host part
160  ///< (ie. the network address, ignoring the port number).
161 
162  void setPort( unsigned int port ) ;
163  ///< Sets the port number. Throws an exception if an invalid
164  ///< port number (ie. too big).
165 
166  G::StringArray wildcards() const ;
167  ///< Returns an ordered list of wildcard strings that match this
168  ///< address. The fully-address-specific string (eg. "192.168.0.1")
169  ///< comes first, and the most general match-all wildcard like
170  ///< "*.*.*.*" or "128.0.0.0/1" comes last.
171 
172  bool isLoopback() const ;
173  ///< Returns true if this is a loopback address.
174 
175  bool isLocal( std::string & reason ) const ;
176  ///< Returns true if this seems to be a local address (for some
177  ///< definition of 'local'). Returns an explanation by reference
178  ///< otherwise.
179 
180  Family family() const ;
181  ///< Returns the address family.
182 
183  bool operator==( const Address & ) const ;
184  ///< Comparison operator.
185 
186  bool operator!=( const Address & ) const ;
187  ///< Comparison operator.
188 
189 private:
190  Address( Family , unsigned int , int ) ; // loopback()
191 
192 private:
193  Address4 * m_4imp ;
194  Address6 * m_6imp ;
195 } ;
196 
197 /// \class GNet::AddressStorage
198 /// A helper class for calling accept(), getsockname() and getpeername()
199 /// and hiding the definition of sockaddr_storage.
200 ///
202 {
203 public:
204  AddressStorage() ;
205  ///< Default constructor.
206 
207  ~AddressStorage() ;
208  ///< Destructor.
209 
210  sockaddr * p1() ;
211  ///< Returns the sockaddr pointer for accept()/getsockname()/getpeername()
212  ///< to write into.
213 
214  socklen_t * p2() ;
215  ///< Returns the length pointer for accept()/getsockname()/getpeername()
216  ///< to write into.
217 
218  const sockaddr * p() const ;
219  ///< Returns the pointer.
220 
221  socklen_t n() const ;
222  ///< Returns the length.
223 
224 private:
225  AddressStorage( const AddressStorage & ) ;
226  void operator=( const AddressStorage & ) ;
227 
228 private:
229  AddressStorageImp * m_imp ;
230 } ;
231 
232 inline GNet::Address::Family GNet::Address::Family::ipv4() { return Family(true) ; }
233 inline GNet::Address::Family GNet::Address::Family::ipv6() { return Family(false) ; }
234 inline bool GNet::Address::Family::operator==( const Family & other ) const { return is4 == other.is4 ; }
235 inline bool GNet::Address::Family::operator!=( const Family & other ) const { return is4 != other.is4 ; }
236 inline GNet::Address::Family::Family( bool is4_ ) : is4(is4_) {}
237 
238 #endif
static Address loopback(Family, unsigned int port=0U)
Returns a loopback address.
Family family() const
Returns the address family.
Network classes.
Definition: gaddress.h:29
static bool validData(const sockaddr *, socklen_t len)
Returns true if the sockaddr data is valid.
A helper class for calling accept(), getsockname() and getpeername() and hiding the definition of soc...
Definition: gaddress.h:201
The GNet::Address class encapsulates a TCP/UDP transport address.
Definition: gaddress.h:54
bool isLoopback() const
Returns true if this is a loopback address.
static bool validStrings(const std::string &ip, const std::string &port_string, std::string *reason=nullptr)
Returns true if the combined network-address string and port string is valid.
std::vector< std::string > StringArray
A std::vector of std::strings.
Definition: gstrings.h:33
socklen_t * p2()
Returns the length pointer for accept()/getsockname()/getpeername() to write into.
sockaddr * p1()
Returns the sockaddr pointer for accept()/getsockname()/getpeername() to write into.
A pimple-pattern implementation class used by GNet::AddressStorage.
const sockaddr * address() const
Returns the sockaddr address.
bool sameHostPart(const Address &other) const
Returns true if the two addresses have the same host part (ie.
unsigned int port() const
Returns port part of the address.
bool operator==(const Address &) const
Comparison operator.
const sockaddr * p() const
Returns the pointer.
A 'sockaddr' wrapper class for IPv4 addresses.
Definition: gaddress4.h:37
AddressStorage()
Default constructor.
static Address defaultAddress()
Returns a default address, being the IPv4 wildcard address with a zero port number.
G::StringArray wildcards() const
Returns an ordered list of wildcard strings that match this address.
socklen_t length() const
Returns the size of the sockaddr address. See address().
std::string hostPartString() const
Returns a string which represents the network address for debugging and diagnostics purposes...
unsigned long scopeId(unsigned long default_=0UL) const
Returns the scope-id.
static bool validString(const std::string &display_string, std::string *reason=nullptr)
Returns true if the transport-address display string is valid.
int domain() const
Returns the address 'domain', eg. PF_INET.
~Address()
Destructor.
~AddressStorage()
Destructor.
static bool validPort(unsigned int n)
Returns true if the port number is within the valid range.
A type-safe enumerator for IP address family.
Definition: gaddress.h:57
bool isLocal(std::string &reason) const
Returns true if this seems to be a local address (for some definition of 'local').
void operator=(const Address &addr)
Assignment operator.
Address(const Address &)
Copy constructor.
void setPort(unsigned int port)
Sets the port number.
socklen_t n() const
Returns the length.
static bool supports(Family)
Returns true if the implementation supports the given address family.
bool operator!=(const Address &) const
Comparison operator.
std::string displayString() const
Returns a string which represents the transport address for debugging and diagnostics purposes...
A 'sockaddr' wrapper class for IPv6 addresses.
Definition: gaddress6.h:37