1 //
2 // ip/address.hpp
3 // ~~~~~~~~~~~~~~
4 //
5 // Copyright (c) 2003-2019 Christopher M. Kohlhoff (chris at kohlhoff dot com)
6 //
7 // Distributed under the Boost Software License, Version 1.0. (See accompanying
8 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
9 //
10 
11 #ifndef ASIO_IP_ADDRESS_HPP
12 #define ASIO_IP_ADDRESS_HPP
13 
14 #if defined(_MSC_VER) && (_MSC_VER >= 1200)
15 # pragma once
16 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
17 
18 #include "asio/detail/config.hpp"
19 #include <string>
20 #include "asio/detail/throw_exception.hpp"
21 #include "asio/detail/string_view.hpp"
22 #include "asio/detail/type_traits.hpp"
23 #include "asio/error_code.hpp"
24 #include "asio/ip/address_v4.hpp"
25 #include "asio/ip/address_v6.hpp"
26 #include "asio/ip/bad_address_cast.hpp"
27 
28 #if !defined(ASIO_NO_IOSTREAM)
29 # include <iosfwd>
30 #endif // !defined(ASIO_NO_IOSTREAM)
31 
32 #include "asio/detail/push_options.hpp"
33 
34 namespace asio {
35 namespace ip {
36 
37 /// Implements version-independent IP addresses.
38 /**
39  * The asio::ip::address class provides the ability to use either IP
40  * version 4 or version 6 addresses.
41  *
42  * @par Thread Safety
43  * @e Distinct @e objects: Safe.@n
44  * @e Shared @e objects: Unsafe.
45  */
46 class address
47 {
48 public:
49   /// Default constructor.
50   ASIO_DECL address() ASIO_NOEXCEPT;
51 
52   /// Construct an address from an IPv4 address.
53   ASIO_DECL address(
54       const asio::ip::address_v4& ipv4_address) ASIO_NOEXCEPT;
55 
56   /// Construct an address from an IPv6 address.
57   ASIO_DECL address(
58       const asio::ip::address_v6& ipv6_address) ASIO_NOEXCEPT;
59 
60   /// Copy constructor.
61   ASIO_DECL address(const address& other) ASIO_NOEXCEPT;
62 
63 #if defined(ASIO_HAS_MOVE)
64   /// Move constructor.
65   ASIO_DECL address(address&& other) ASIO_NOEXCEPT;
66 #endif // defined(ASIO_HAS_MOVE)
67 
68   /// Assign from another address.
69   ASIO_DECL address& operator=(const address& other) ASIO_NOEXCEPT;
70 
71 #if defined(ASIO_HAS_MOVE)
72   /// Move-assign from another address.
73   ASIO_DECL address& operator=(address&& other) ASIO_NOEXCEPT;
74 #endif // defined(ASIO_HAS_MOVE)
75 
76   /// Assign from an IPv4 address.
77   ASIO_DECL address& operator=(
78       const asio::ip::address_v4& ipv4_address) ASIO_NOEXCEPT;
79 
80   /// Assign from an IPv6 address.
81   ASIO_DECL address& operator=(
82       const asio::ip::address_v6& ipv6_address) ASIO_NOEXCEPT;
83 
84   /// Get whether the address is an IP version 4 address.
is_v4() const85   bool is_v4() const ASIO_NOEXCEPT
86   {
87     return type_ == ipv4;
88   }
89 
90   /// Get whether the address is an IP version 6 address.
is_v6() const91   bool is_v6() const ASIO_NOEXCEPT
92   {
93     return type_ == ipv6;
94   }
95 
96   /// Get the address as an IP version 4 address.
97   ASIO_DECL asio::ip::address_v4 to_v4() const;
98 
99   /// Get the address as an IP version 6 address.
100   ASIO_DECL asio::ip::address_v6 to_v6() const;
101 
102   /// Get the address as a string.
103   ASIO_DECL std::string to_string() const;
104 
105 #if !defined(ASIO_NO_DEPRECATED)
106   /// (Deprecated: Use other overload.) Get the address as a string.
107   ASIO_DECL std::string to_string(asio::error_code& ec) const;
108 
109   /// (Deprecated: Use make_address().) Create an address from an IPv4 address
110   /// string in dotted decimal form, or from an IPv6 address in hexadecimal
111   /// notation.
112   static address from_string(const char* str);
113 
114   /// (Deprecated: Use make_address().) Create an address from an IPv4 address
115   /// string in dotted decimal form, or from an IPv6 address in hexadecimal
116   /// notation.
117   static address from_string(const char* str, asio::error_code& ec);
118 
119   /// (Deprecated: Use make_address().) Create an address from an IPv4 address
120   /// string in dotted decimal form, or from an IPv6 address in hexadecimal
121   /// notation.
122   static address from_string(const std::string& str);
123 
124   /// (Deprecated: Use make_address().) Create an address from an IPv4 address
125   /// string in dotted decimal form, or from an IPv6 address in hexadecimal
126   /// notation.
127   static address from_string(
128       const std::string& str, asio::error_code& ec);
129 #endif // !defined(ASIO_NO_DEPRECATED)
130 
131   /// Determine whether the address is a loopback address.
132   ASIO_DECL bool is_loopback() const ASIO_NOEXCEPT;
133 
134   /// Determine whether the address is unspecified.
135   ASIO_DECL bool is_unspecified() const ASIO_NOEXCEPT;
136 
137   /// Determine whether the address is a multicast address.
138   ASIO_DECL bool is_multicast() const ASIO_NOEXCEPT;
139 
140   /// Compare two addresses for equality.
141   ASIO_DECL friend bool operator==(const address& a1,
142       const address& a2) ASIO_NOEXCEPT;
143 
144   /// Compare two addresses for inequality.
operator !=(const address & a1,const address & a2)145   friend bool operator!=(const address& a1,
146       const address& a2) ASIO_NOEXCEPT
147   {
148     return !(a1 == a2);
149   }
150 
151   /// Compare addresses for ordering.
152   ASIO_DECL friend bool operator<(const address& a1,
153       const address& a2) ASIO_NOEXCEPT;
154 
155   /// Compare addresses for ordering.
operator >(const address & a1,const address & a2)156   friend bool operator>(const address& a1,
157       const address& a2) ASIO_NOEXCEPT
158   {
159     return a2 < a1;
160   }
161 
162   /// Compare addresses for ordering.
operator <=(const address & a1,const address & a2)163   friend bool operator<=(const address& a1,
164       const address& a2) ASIO_NOEXCEPT
165   {
166     return !(a2 < a1);
167   }
168 
169   /// Compare addresses for ordering.
operator >=(const address & a1,const address & a2)170   friend bool operator>=(const address& a1,
171       const address& a2) ASIO_NOEXCEPT
172   {
173     return !(a1 < a2);
174   }
175 
176 private:
177   // The type of the address.
178   enum { ipv4, ipv6 } type_;
179 
180   // The underlying IPv4 address.
181   asio::ip::address_v4 ipv4_address_;
182 
183   // The underlying IPv6 address.
184   asio::ip::address_v6 ipv6_address_;
185 };
186 
187 /// Create an address from an IPv4 address string in dotted decimal form,
188 /// or from an IPv6 address in hexadecimal notation.
189 /**
190  * @relates address
191  */
192 ASIO_DECL address make_address(const char* str);
193 
194 /// Create an address from an IPv4 address string in dotted decimal form,
195 /// or from an IPv6 address in hexadecimal notation.
196 /**
197  * @relates address
198  */
199 ASIO_DECL address make_address(const char* str,
200     asio::error_code& ec) ASIO_NOEXCEPT;
201 
202 /// Create an address from an IPv4 address string in dotted decimal form,
203 /// or from an IPv6 address in hexadecimal notation.
204 /**
205  * @relates address
206  */
207 ASIO_DECL address make_address(const std::string& str);
208 
209 /// Create an address from an IPv4 address string in dotted decimal form,
210 /// or from an IPv6 address in hexadecimal notation.
211 /**
212  * @relates address
213  */
214 ASIO_DECL address make_address(const std::string& str,
215     asio::error_code& ec) ASIO_NOEXCEPT;
216 
217 #if defined(ASIO_HAS_STRING_VIEW) \
218   || defined(GENERATING_DOCUMENTATION)
219 
220 /// Create an address from an IPv4 address string in dotted decimal form,
221 /// or from an IPv6 address in hexadecimal notation.
222 /**
223  * @relates address
224  */
225 ASIO_DECL address make_address(string_view str);
226 
227 /// Create an address from an IPv4 address string in dotted decimal form,
228 /// or from an IPv6 address in hexadecimal notation.
229 /**
230  * @relates address
231  */
232 ASIO_DECL address make_address(string_view str,
233     asio::error_code& ec) ASIO_NOEXCEPT;
234 
235 #endif // defined(ASIO_HAS_STRING_VIEW)
236        //  || defined(GENERATING_DOCUMENTATION)
237 
238 #if !defined(ASIO_NO_IOSTREAM)
239 
240 /// Output an address as a string.
241 /**
242  * Used to output a human-readable string for a specified address.
243  *
244  * @param os The output stream to which the string will be written.
245  *
246  * @param addr The address to be written.
247  *
248  * @return The output stream.
249  *
250  * @relates asio::ip::address
251  */
252 template <typename Elem, typename Traits>
253 std::basic_ostream<Elem, Traits>& operator<<(
254     std::basic_ostream<Elem, Traits>& os, const address& addr);
255 
256 #endif // !defined(ASIO_NO_IOSTREAM)
257 
258 } // namespace ip
259 } // namespace asio
260 
261 #include "asio/detail/pop_options.hpp"
262 
263 #include "asio/ip/impl/address.hpp"
264 #if defined(ASIO_HEADER_ONLY)
265 # include "asio/ip/impl/address.ipp"
266 #endif // defined(ASIO_HEADER_ONLY)
267 
268 #endif // ASIO_IP_ADDRESS_HPP
269