Branch data Line data Source code
1 : : // Copyright (C) 2011 Internet Systems Consortium, Inc. ("ISC")
2 : : //
3 : : // Permission to use, copy, modify, and/or distribute this software for any
4 : : // purpose with or without fee is hereby granted, provided that the above
5 : : // copyright notice and this permission notice appear in all copies.
6 : : //
7 : : // THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
8 : : // REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
9 : : // AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
10 : : // INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
11 : : // LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
12 : : // OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
13 : : // PERFORMANCE OF THIS SOFTWARE.
14 : :
15 : : #ifndef __SERIAL_H
16 : : #define __SERIAL_H 1
17 : :
18 : : #include <stdint.h>
19 : : #include <iostream>
20 : :
21 : : namespace isc {
22 : : namespace dns {
23 : :
24 : : /// The maximum difference between two serial numbers. If the (plain uint32_t)
25 : : /// difference between two serials is greater than this number, the smaller one
26 : : /// is considered greater.
27 : : const uint32_t MAX_SERIAL_INCREMENT = 2147483647;
28 : :
29 : : /// Maximum value a serial can have, used in + operator.
30 : : const uint64_t MAX_SERIAL_VALUE = 4294967296ull;
31 : :
32 : : /// \brief This class defines DNS serial numbers and serial arithmetic.
33 : : ///
34 : : /// DNS Serial number are in essence unsigned 32-bits numbers, with one
35 : : /// catch; they should be compared using sequence space arithmetic.
36 : : /// So given that they are 32-bits; as soon as the difference between two
37 : : /// serial numbers is greater than 2147483647 (2^31 - 1), the lower number
38 : : /// (in plain comparison) is considered the higher one.
39 : : ///
40 : : /// In order to do this as transparently as possible, these numbers are
41 : : /// stored in the Serial class, which overrides the basic comparison operators.
42 : : ///
43 : : /// In this specific context, these operations are called 'serial number
44 : : /// arithmetic', and they are defined in RFC 1982.
45 : : ///
46 : : /// \note RFC 1982 defines everything based on the value SERIAL_BITS. Since
47 : : /// the serial number has a fixed length of 32 bits, the values we use are
48 : : /// hard-coded, and not computed based on variable bit lengths.
49 : : class Serial {
50 : : public:
51 : : /// \brief Constructor with value
52 : : ///
53 : : /// \param value The uint32_t value of the serial
54 : 2438 : explicit Serial(uint32_t value) : value_(value) {}
55 : :
56 : : /// \brief Copy constructor
57 : 13 : Serial(const Serial& other) : value_(other.getValue()) {}
58 : :
59 : : /// \brief Direct assignment from other Serial
60 : : ///
61 : : /// \param other The Serial to assign the value from
62 : 1233 : void operator=(const Serial& other) { value_ = other.getValue(); }
63 : :
64 : : /// \brief Direct assignment from value
65 : : ///
66 : : /// \param value the uint32_t value to assing
67 : : void operator=(uint32_t value) { value_ = value; }
68 : :
69 : : /// \brief Returns the uint32_t representation of this serial value
70 : : ///
71 : : /// \return The uint32_t value of this Serial
72 : 3492 : uint32_t getValue() const { return (value_); }
73 : :
74 : : /// \brief Returns true if the serial values are equal
75 : : ///
76 : : /// \return True if the values are equal
77 : : bool operator==(const Serial& other) const;
78 : :
79 : : /// \brief Returns true if the serial values are not equal
80 : : ///
81 : : /// \return True if the values are not equal
82 : : bool operator!=(const Serial& other) const;
83 : :
84 : : /// \brief Returns true if the serial value of this serial is smaller than
85 : : /// the other, according to serial arithmetic as described in RFC 1982
86 : : ///
87 : : /// \param other The Serial to compare to
88 : : ///
89 : : /// \return True if this is smaller than the given value
90 : : bool operator<(const Serial& other) const;
91 : :
92 : : /// \brief Returns true if the serial value of this serial is equal to or
93 : : /// smaller than the other, according to serial arithmetic as described
94 : : /// in RFC 1982
95 : : ///
96 : : /// \param other The Serial to compare to
97 : : ///
98 : : /// \return True if this is smaller than or equal to the given value
99 : : bool operator<=(const Serial& other) const;
100 : :
101 : : /// \brief Returns true if the serial value of this serial is greater than
102 : : /// the other, according to serial arithmetic as described in RFC 1982
103 : : ///
104 : : /// \param other The Serial to compare to
105 : : ///
106 : : /// \return True if this is greater than the given value
107 : : bool operator>(const Serial& other) const;
108 : :
109 : : /// \brief Returns true if the serial value of this serial is equal to or
110 : : /// greater than the other, according to serial arithmetic as described in
111 : : /// RFC 1982
112 : : ///
113 : : /// \param other The Serial to compare to
114 : : ///
115 : : /// \return True if this is greater than or equal to the given value
116 : : bool operator>=(const Serial& other) const;
117 : :
118 : : /// \brief Adds the given value to the serial number. If this would make
119 : : /// the number greater than 2^32-1, it is 'wrapped'.
120 : : /// \note According to the specification, an addition greater than
121 : : /// MAX_SERIAL_INCREMENT is undefined. We do NOT catch this error (so as not
122 : : /// to raise exceptions), but this behaviour remains undefined.
123 : : ///
124 : : /// \param other The Serial to add
125 : : ///
126 : : /// \return The result of the addition
127 : : Serial operator+(const Serial& other) const;
128 : :
129 : : /// \brief Adds the given value to the serial number. If this would make
130 : : /// the number greater than 2^32-1, it is 'wrapped'.
131 : : ///
132 : : /// \note According to the specification, an addition greater than
133 : : /// MAX_SERIAL_INCREMENT is undefined. We do NOT catch this error (so as not
134 : : /// to raise exceptions), but this behaviour remains undefined.
135 : : ///
136 : : /// \param other_val The uint32_t value to add
137 : : ///
138 : : /// \return The result of the addition
139 : : Serial operator+(uint32_t other_val) const;
140 : :
141 : : private:
142 : : uint32_t value_;
143 : : };
144 : :
145 : : /// \brief Helper operator for output streams, writes the value to the stream
146 : : ///
147 : : /// \param os The ostream to write to
148 : : /// \param serial The Serial to write
149 : : /// \return the output stream
150 : : std::ostream& operator<<(std::ostream& os, const Serial& serial);
151 : :
152 : : } // end namespace dns
153 : : } // end namespace isc
154 : :
155 : : #endif // __SERIAL_H
|
