Line data Source code
1 : //
2 : // Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)
3 : // Copyright (c) 2022 Alan de Freitas (alandefreitas@gmail.com)
4 : //
5 : // Distributed under the Boost Software License, Version 1.0. (See accompanying
6 : // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
7 : //
8 : // Official repository: https://github.com/boostorg/url
9 : //
10 :
11 : #ifndef BOOST_URL_IPV4_ADDRESS_HPP
12 : #define BOOST_URL_IPV4_ADDRESS_HPP
13 :
14 : #include <boost/url/detail/config.hpp>
15 : #include <boost/url/error.hpp>
16 : #include <boost/url/error_types.hpp>
17 : #include <boost/core/detail/string_view.hpp>
18 : #include <boost/url/grammar/string_token.hpp>
19 : #include <string>
20 : #include <array>
21 : #include <cstdint>
22 : #include <iosfwd>
23 :
24 : namespace boost {
25 : namespace urls {
26 :
27 : /** An IP version 4 style address.
28 :
29 : Objects of this type are used to construct,
30 : parse, and manipulate IP version 6 addresses.
31 :
32 : @par BNF
33 : @code
34 : IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet
35 :
36 : dec-octet = DIGIT ; 0-9
37 : / %x31-39 DIGIT ; 10-99
38 : / "1" 2DIGIT ; 100-199
39 : / "2" %x30-34 DIGIT ; 200-249
40 : / "25" %x30-35 ; 250-255
41 : @endcode
42 :
43 : @par Specification
44 : @li <a href="https://en.wikipedia.org/wiki/IPv4"
45 : >IPv4 (Wikipedia)</a>
46 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2"
47 : >3.2.2. Host (rfc3986)</a>
48 :
49 : @see
50 : @ref parse_ipv4_address,
51 : @ref ipv6_address.
52 : */
53 : class ipv4_address
54 : {
55 : public:
56 : /** The number of characters in the longest possible IPv4 string.
57 :
58 : The longest ipv4 address string is "255.255.255.255".
59 : */
60 : static
61 : constexpr
62 : std::size_t max_str_len = 15;
63 :
64 : /** The type used to represent an address as an unsigned integer
65 : */
66 : using uint_type =
67 : std::uint_least32_t;
68 :
69 : /** The type used to represent an address as an array of bytes
70 : */
71 : using bytes_type =
72 : std::array<unsigned char, 4>;
73 :
74 : /** Constructor.
75 : */
76 77 : ipv4_address() = default;
77 :
78 : /** Constructor.
79 : */
80 : ipv4_address(
81 : ipv4_address const&) = default;
82 :
83 : /** Copy Assignment.
84 : */
85 : ipv4_address&
86 : operator=(
87 : ipv4_address const&) = default;
88 :
89 : //
90 : //---
91 : //
92 :
93 : /** Construct from an unsigned integer.
94 :
95 : This function constructs an address from
96 : the unsigned integer `u`, where the most
97 : significant byte forms the first octet
98 : of the resulting address.
99 :
100 : @param u The integer to construct from.
101 : */
102 : BOOST_URL_DECL
103 : explicit
104 : ipv4_address(
105 : uint_type u) noexcept;
106 :
107 : /** Construct from an array of bytes.
108 :
109 : This function constructs an address
110 : from the array in `bytes`, which is
111 : interpreted in big-endian.
112 :
113 : @param bytes The value to construct from.
114 : */
115 : BOOST_URL_DECL
116 : explicit
117 : ipv4_address(
118 : bytes_type const& bytes) noexcept;
119 :
120 : /** Construct from a string.
121 :
122 : This function constructs an address from
123 : the string `s`, which must contain a valid
124 : IPv4 address string or else an exception
125 : is thrown.
126 :
127 : @note For a non-throwing parse function,
128 : use @ref parse_ipv4_address.
129 :
130 : @par Exception Safety
131 : Exceptions thrown on invalid input.
132 :
133 : @throw system_error
134 : The input failed to parse correctly.
135 :
136 : @param s The string to parse.
137 :
138 : @par Specification
139 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2"
140 : >3.2.2. Host (rfc3986)</a>
141 :
142 : @see
143 : @ref parse_ipv4_address.
144 : */
145 : BOOST_URL_DECL
146 : explicit
147 : ipv4_address(
148 : core::string_view s);
149 :
150 : /** Return the address as bytes, in network byte order.
151 : */
152 : BOOST_URL_DECL
153 : bytes_type
154 : to_bytes() const noexcept;
155 :
156 : /** Return the address as an unsigned integer.
157 : */
158 : BOOST_URL_DECL
159 : uint_type
160 : to_uint() const noexcept;
161 :
162 : /** Return the address as a string in dotted decimal format
163 :
164 : When called with no arguments, the
165 : return type is `std::string`.
166 : Otherwise, the return type and style
167 : of output is determined by which string
168 : token is passed.
169 :
170 : @par Example
171 : @code
172 : assert( ipv4_address(0x01020304).to_string() == "1.2.3.4" );
173 : @endcode
174 :
175 : @par Complexity
176 : Constant.
177 :
178 : @par Exception Safety
179 : Strong guarantee.
180 : Calls to allocate may throw.
181 : String tokens may throw exceptions.
182 :
183 : @return The return type of the string token.
184 : If the token parameter is omitted, then
185 : a new `std::string` is returned.
186 : Otherwise, the function return type
187 : is the result type of the token.
188 :
189 : @param token An optional string token.
190 :
191 : @par Specification
192 : @li <a href="https://datatracker.ietf.org/doc/html/rfc4291#section-2.2">
193 : 2.2. Text Representation of Addresses (rfc4291)</a>
194 : */
195 : template<BOOST_URL_STRTOK_TPARAM>
196 : BOOST_URL_STRTOK_RETURN
197 2 : to_string(
198 : BOOST_URL_STRTOK_ARG(token)) const
199 : {
200 2 : to_string_impl(token);
201 2 : return token.result();
202 : }
203 :
204 : /** Write a dotted decimal string representing the address to a buffer
205 :
206 : The resulting buffer is not null-terminated.
207 :
208 : @throw std::length_error `dest_size < ipv4_address::max_str_len`
209 :
210 : @return The formatted string
211 :
212 : @param dest The buffer in which to write,
213 : which must have at least `dest_size` space.
214 :
215 : @param dest_size The size of the output buffer.
216 : */
217 : BOOST_URL_DECL
218 : core::string_view
219 : to_buffer(
220 : char* dest,
221 : std::size_t dest_size) const;
222 :
223 : /** Return true if the address is a loopback address
224 : */
225 : BOOST_URL_DECL
226 : bool
227 : is_loopback() const noexcept;
228 :
229 : /** Return true if the address is unspecified
230 : */
231 : BOOST_URL_DECL
232 : bool
233 : is_unspecified() const noexcept;
234 :
235 : /** Return true if the address is a multicast address
236 : */
237 : BOOST_URL_DECL
238 : bool
239 : is_multicast() const noexcept;
240 :
241 : /** Return true if two addresses are equal
242 : */
243 : friend
244 : bool
245 57 : operator==(
246 : ipv4_address const& a1,
247 : ipv4_address const& a2) noexcept
248 : {
249 57 : return a1.addr_ == a2.addr_;
250 : }
251 :
252 : /** Return true if two addresses are not equal
253 : */
254 : friend
255 : bool
256 3 : operator!=(
257 : ipv4_address const& a1,
258 : ipv4_address const& a2) noexcept
259 : {
260 3 : return a1.addr_ != a2.addr_;
261 : }
262 :
263 : /** Return an address object that represents any address
264 : */
265 : static
266 : ipv4_address
267 3 : any() noexcept
268 : {
269 3 : return ipv4_address();
270 : }
271 :
272 : /** Return an address object that represents the loopback address
273 : */
274 : static
275 : ipv4_address
276 3 : loopback() noexcept
277 : {
278 3 : return ipv4_address(0x7F000001);
279 : }
280 :
281 : /** Return an address object that represents the broadcast address
282 : */
283 : static
284 : ipv4_address
285 3 : broadcast() noexcept
286 : {
287 3 : return ipv4_address(0xFFFFFFFF);
288 : }
289 :
290 : // hidden friend
291 : friend
292 : std::ostream&
293 1 : operator<<(
294 : std::ostream& os,
295 : ipv4_address const& addr)
296 : {
297 : char buf[ipv4_address::max_str_len];
298 1 : os << addr.to_buffer(buf, sizeof(buf));
299 1 : return os;
300 : }
301 :
302 : private:
303 : friend class ipv6_address;
304 :
305 : BOOST_URL_DECL
306 : std::size_t
307 : print_impl(
308 : char* dest) const noexcept;
309 :
310 : BOOST_URL_DECL
311 : void
312 : to_string_impl(
313 : string_token::arg& t) const;
314 :
315 : uint_type addr_ = 0;
316 : };
317 :
318 : /** Format the address to an output stream.
319 :
320 : IPv4 addresses written to output streams
321 : are written in their dotted decimal format.
322 :
323 : @param os The output stream.
324 :
325 : @param addr The address to format.
326 : */
327 : std::ostream&
328 : operator<<(
329 : std::ostream& os,
330 : ipv4_address const& addr);
331 :
332 : //------------------------------------------------
333 :
334 : /** Return an IPv4 address from an IP address string in dotted decimal form
335 : */
336 : BOOST_URL_DECL
337 : system::result<ipv4_address>
338 : parse_ipv4_address(
339 : core::string_view s) noexcept;
340 :
341 : } // urls
342 : } // boost
343 :
344 : #endif
|
