io_address.h 9.56 KB
Newer Older
1
// Copyright (C) 2010-2015  Internet Systems Consortium, Inc. ("ISC")
2
3
4
5
6
7
8
9
10
11
12
13
14
//
// Permission to use, copy, modify, and/or distribute this software for any
// purpose with or without fee is hereby granted, provided that the above
// copyright notice and this permission notice appear in all copies.
//
// THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
// AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
// OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
// PERFORMANCE OF THIS SOFTWARE.

15
16
#ifndef IO_ADDRESS_H
#define IO_ADDRESS_H 1
17
18
19
20
21

// IMPORTANT NOTE: only very few ASIO headers files can be included in
// this file.  In particular, asio.hpp should never be included here.
// See the description of the namespace below.
#include <unistd.h>             // for some network system calls
22
#include <stdint.h>             // for uint32_t
23
24
25
26
#include <asio/ip/address.hpp>

#include <functional>
#include <string>
27
#include <vector>
28
29
30

#include <exceptions/exceptions.h>

31
namespace isc {
32
33
namespace asiolink {

34
35
36
37
38
39
    /// Defines length of IPv6 address.
    const static size_t V6ADDRESS_LEN = 16;

    /// Defines length of IPv4 address.
    const static size_t V4ADDRESS_LEN = 4;

40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
/// \brief The \c IOAddress class represents an IP addresses (version
/// agnostic)
///
/// This class is a wrapper for the ASIO \c ip::address class.
class IOAddress {
public:
    ///
    /// \name Constructors and Destructor
    ///
    /// This class is copyable.  We use default versions of copy constructor
    /// and the assignment operator.
    /// We use the default destructor.
    //@{
    /// \brief Constructor from string.
    ///
    /// This constructor converts a textual representation of IPv4 and IPv6
    /// addresses into an IOAddress object.
    /// If \c address_str is not a valid representation of any type of
    /// address, an exception of class \c IOError will be thrown.
    /// This constructor allocates memory for the object, and if that fails
    /// a corresponding standard exception will be thrown.
    ///
    /// \param address_str Textual representation of address.
    IOAddress(const std::string& address_str);

    /// \brief Constructor from an ASIO \c ip::address object.
    ///
    /// This constructor is intended to be used within the wrapper
    /// implementation; user applications of the wrapper API won't use it.
    ///
    /// This constructor never throws an exception.
    ///
    /// \param asio_address The ASIO \c ip::address to be converted.
73
    IOAddress(const asio::ip::address& asio_address);
74
75
    //@}

Tomek Mrugalski's avatar
Tomek Mrugalski committed
76
77
78
79
80
81
82
83
84
    /// @brief Constructor for ip::address_v4 object.
    ///
    /// This constructor is intented to be used when constructing
    /// IPv4 address out of uint32_t type. Passed value must be in
    /// network byte order
    ///
    /// @param v4address IPv4 address represnted by uint32_t
    IOAddress(uint32_t v4address);

85
86
87
88
89
90
91
    /// \brief Convert the address to a string.
    ///
    /// This method is basically expected to be exception free, but
    /// generating the string will involve resource allocation,
    /// and if it fails the corresponding standard exception will be thrown.
    ///
    /// \return A string representation of the address.
92
    std::string toText() const;
93

94
95
96
    /// \brief Returns the address family
    ///
    /// \return AF_INET for IPv4 or AF_INET6 for IPv6.
97
    short getFamily() const;
98

99
100
101
102
103
104
105
106
107
108
109
110
111
    /// \brief Convenience function to check for an IPv4 address
    ///
    /// \return true if the address is a V4 address
    bool isV4() const {
        return (asio_address_.is_v4());
    }

    /// \brief Convenience function to check for an IPv6 address
    ///
    /// \return true if the address is a V6 address
    bool isV6() const {
        return (asio_address_.is_v6());
    }
112

113
114
115
116
117
118
119
120
121
122
    /// \brief checks whether and address is IPv6 and is link-local
    ///
    /// \return true if the address is IPv6 link-local, false otherwise
    bool isV6LinkLocal() const;

    /// \brief checks whether and address is IPv6 and is multicast
    ///
    /// \return true if the address is IPv6 multicast, false otherwise
    bool isV6Multicast() const;

123
124
125
126
127
128
    /// \brief Creates an address from over wire data.
    ///
    /// \param family AF_NET for IPv4 or AF_NET6 for IPv6.
    /// \param data pointer to first char of data
    ///
    /// \return Created IOAddress object
129
130
131
132
133
134
135
    static IOAddress fromBytes(short family, const uint8_t* data);

    /// \brief Return address as set of bytes
    ///
    /// \return Contents of the address as a set of bytes in network-byte
    ///         order.
    std::vector<uint8_t> toBytes() const;
136

137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
    /// \brief Compare addresses for equality
    ///
    /// \param other Address to compare against.
    ///
    /// \return true if addresses are equal, false if not.
    bool equals(const IOAddress& other) const {
        return (asio_address_ == other.asio_address_);
    }

    /// \brief Compare addresses for equality
    ///
    /// \param other Address to compare against.
    ///
    /// \return true if addresses are equal, false if not.
    bool operator==(const IOAddress& other) const {
        return equals(other);
    }

155
    /// \brief Compare addresses for inequality
156
157
158
159
160
161
162
163
    ///
    /// \param other Address to compare against.
    ///
    /// \return false if addresses are equal, true if not.
    bool nequals(const IOAddress& other) const {
        return (!equals(other));
    }

164
165
166
167
168
169
170
171
172
173
    /// \brief Checks if one address is smaller than the other
    ///
    /// \param other Address to compare against.
    ///
    /// \return true if this address is smaller than the other address.
    ///
    /// It is useful for comparing which address is bigger.
    /// Operations within one protocol family are obvious.
    /// Comparisons between v4 and v6 will allways return v4
    /// being smaller. This follows boost::asio::ip implementation
Tomek Mrugalski's avatar
Tomek Mrugalski committed
174
175
176
177
178
179
180
    bool lessThan(const IOAddress& other) const {
        if (this->getFamily() == other.getFamily()) {
            if (this->getFamily() == AF_INET6) {
                return (this->asio_address_.to_v6() < other.asio_address_.to_v6());
            } else {
                return (this->asio_address_.to_v4() < other.asio_address_.to_v4());
            }
181
        }
Tomek Mrugalski's avatar
Tomek Mrugalski committed
182
        return (this->getFamily() < other.getFamily());
183
184
    }

185
186
187
188
189
190
191
192
193
    /// \brief Checks if one address is smaller or equal than the other
    ///
    /// \param other Address to compare against.
    ///
    /// \return true if this address is smaller than the other address.
    bool smallerEqual(const IOAddress& other) const {
        if (equals(other)) {
            return (true);
        }
Tomek Mrugalski's avatar
Tomek Mrugalski committed
194
        return (lessThan(other));
195
196
    }

197
198
199
200
    /// \brief Checks if one address is smaller than the other
    ///
    /// \param other Address to compare against.
    ///
201
    /// See \ref lessThan method for details.
202
    bool operator<(const IOAddress& other) const {
Tomek Mrugalski's avatar
Tomek Mrugalski committed
203
        return (lessThan(other));
204
205
206
207
208
209
    }

    /// \brief Checks if one address is smaller or equal than the other
    ///
    /// \param other Address to compare against.
    ///
210
    /// See \ref smallerEqual method for details.
211
212
    bool operator<=(const IOAddress& other) const {
        return (smallerEqual(other));
213
214
215
    }

    /// \brief Compare addresses for inequality
216
217
218
219
220
221
222
223
    ///
    /// \param other Address to compare against.
    ///
    /// \return false if addresses are equal, true if not.
    bool operator!=(const IOAddress& other) const {
        return (nequals(other));
    }

224
225
226
227
228
229
230
231
232
233
234
235
236
237
    /// @brief Subtracts one address from another (a - b)
    ///
    /// Treats addresses as integers and subtracts them. For example:
    /// 192.0.2.5 - 192.0.2.0 = 0.0.0.5
    /// fe80::abcd - fe80:: = ::abcd
    ///
    /// This operation is essential for calculating the number of
    /// leases in a pool, where we need to calculate (max - min).
    /// @throw BadValue if addresses are of different family
    /// @param a address to be subtracted from
    /// @param b address to be subtracted
    /// @return IOAddress object that represents the difference
    static IOAddress subtract(const IOAddress& a, const IOAddress& b);

238
239
240
241
242
243
244
245
246
247
    /// @brief Returns an address increased by one
    ///
    /// This method works for both IPv4 and IPv6 addresses. For example,
    /// increase 192.0.2.255 will become 192.0.3.0.
    ///
    /// @param addr address to be increased
    /// @return address increased by one
    static IOAddress
    increaseAddress(const IOAddress& addr);

248
249
250
251
252
253
254
255
    /// \brief Converts IPv4 address to uint32_t
    ///
    /// Will throw BadValue exception if that is not IPv4
    /// address.
    ///
    /// \return uint32_t that represents IPv4 address in
    ///         network byte order
    operator uint32_t () const;
256

257
258
259
260
private:
    asio::ip::address asio_address_;
};

261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
/// \brief Insert the IOAddress as a string into stream.
///
/// This method converts the \c address into a string and inserts it
/// into the output stream \c os.
///
/// This function overloads the global operator<< to behave as described
/// in ostream::operator<< but applied to \c IOAddress objects.
///
/// \param os A \c std::ostream object on which the insertion operation is
/// performed.
/// \param address The \c IOAddress object output by the operation.
/// \return A reference to the same \c std::ostream object referenced by
/// parameter \c os after the insertion operation.
std::ostream&
operator<<(std::ostream& os, const IOAddress& address);

277
278
} // namespace asiolink
} // namespace isc
279
#endif // IO_ADDRESS_H