Branch data Line data Source code
1 : : // Copyright (C) 2010 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 __RRTTL_H
16 : : #define __RRTTL_H 1
17 : :
18 : : #include <stdint.h>
19 : :
20 : : #include <exceptions/exceptions.h>
21 : :
22 : : namespace isc {
23 : : namespace util {
24 : : class InputBuffer;
25 : : class OutputBuffer;
26 : : }
27 : :
28 : : namespace dns {
29 : :
30 : : // forward declarations
31 : : class AbstractMessageRenderer;
32 : :
33 : : ///
34 : : /// \brief A standard DNS module exception that is thrown if an RRTTL object
35 : : /// is being constructed from an unrecognized string.
36 : : ///
37 : 13 : class InvalidRRTTL : public Exception {
38 : : public:
39 : : InvalidRRTTL(const char* file, size_t line, const char* what) :
40 [ + - ]: 13 : isc::Exception(file, line, what) {}
41 : : };
42 : :
43 : : ///
44 : : /// \brief A standard DNS module exception that is thrown if an RRTTL object
45 : : /// is being constructed from a incomplete (too short) wire-format data.
46 : : ///
47 : 2 : class IncompleteRRTTL : public Exception {
48 : : public:
49 : : IncompleteRRTTL(const char* file, size_t line, const char* what) :
50 [ + - ]: 2 : isc::Exception(file, line, what) {}
51 : : };
52 : :
53 : : ///
54 : : /// The \c RRTTL class encapsulates TTLs used in DNS resource records.
55 : : ///
56 : : /// This is a straightforward class; an \c RRTTL object simply maintains a
57 : : /// 32-bit unsigned integer corresponding to the TTL value. The main purpose
58 : : /// of this class is to provide convenient interfaces to convert a textual
59 : : /// representation into the integer TTL value and vice versa, and to handle
60 : : /// wire-format representations.
61 : 0 : class RRTTL {
62 : : public:
63 : : ///
64 : : /// \name Constructors and Destructor
65 : : ///
66 : : /// Note: We use the default copy constructor and the default copy
67 : : /// assignment operator intentionally.
68 : : //@{
69 : : /// Constructor from an integer TTL value.
70 : : ///
71 : : /// This constructor never throws an exception.
72 : : ///
73 : : /// \param ttlval An 32-bit integer of the RRTTL.
74 : 5302 : explicit RRTTL(uint32_t ttlval) : ttlval_(ttlval) {}
75 : : /// Constructor from a string.
76 : : ///
77 : : /// This version of the implementation only accepts decimal TTL values in
78 : : /// seconds.
79 : : /// In a near future version, we'll extend it so that we can accept more
80 : : /// convenient ones such as "2H" or "1D".
81 : : ///
82 : : /// If the given string is not recognized as a valid representation of
83 : : /// an RR TTL, an exception of class \c InvalidRRTTL will be thrown.
84 : : ///
85 : : /// \param ttlstr A string representation of the \c RRTTL
86 : : explicit RRTTL(const std::string& ttlstr);
87 : : /// Constructor from wire-format data.
88 : : ///
89 : : /// The \c buffer parameter normally stores a complete DNS message
90 : : /// containing the RRTTL to be constructed. The current read position of
91 : : /// the buffer points to the head of the type.
92 : : ///
93 : : /// If the given data does not large enough to contain a 16-bit integer,
94 : : /// an exception of class \c IncompleteRRTTL will be thrown.
95 : : ///
96 : : /// \param buffer A buffer storing the wire format data.
97 : : explicit RRTTL(isc::util::InputBuffer& buffer);
98 : : ///
99 : : //@}
100 : :
101 : : ///
102 : : /// \name Converter methods
103 : : ///
104 : : //@{
105 : : /// \brief Convert the \c RRTTL to a string.
106 : : ///
107 : : /// This version of implementation simply converts the TTL value into the
108 : : /// numeric textual representation. We may introduce more human-readable
109 : : /// format depending on the context in future versions.
110 : : ///
111 : : /// If resource allocation in rendering process fails, a corresponding
112 : : /// standard exception will be thrown.
113 : : ///
114 : : /// \return A string representation of the \c RRTTL.
115 : : const std::string toText() const;
116 : : /// \brief Render the \c RRTTL in the wire format.
117 : : ///
118 : : /// This method renders the TTL value in network byte order via \c renderer,
119 : : /// which encapsulates output buffer and other rendering contexts.
120 : : ///
121 : : /// If resource allocation in rendering process fails, a corresponding
122 : : /// standard exception will be thrown.
123 : : ///
124 : : /// \param renderer DNS message rendering context that encapsulates the
125 : : /// output buffer in which the RRTTL is to be stored.
126 : : void toWire(AbstractMessageRenderer& renderer) const;
127 : : /// \brief Render the \c RRTTL in the wire format.
128 : : ///
129 : : /// This method renders the TTL value in network byte order into the
130 : : /// \c buffer.
131 : : ///
132 : : /// If resource allocation in rendering process fails, a corresponding
133 : : /// standard exception will be thrown.
134 : : ///
135 : : /// \param buffer An output buffer to store the wire data.
136 : : void toWire(isc::util::OutputBuffer& buffer) const;
137 : : //@}
138 : :
139 : : ///
140 : : /// \name Getter Methods
141 : : ///
142 : : //@{
143 : : /// \brief Returns the TTL value as a 32-bit unsigned integer.
144 : : ///
145 : : /// This method never throws an exception.
146 : : ///
147 : : /// \return An 32-bit integer corresponding to the RRTTL.
148 : 1033 : uint32_t getValue() const { return (ttlval_); }
149 : : //@}
150 : :
151 : : ///
152 : : /// \name Comparison methods
153 : : ///
154 : : /// Comparison between two \c RRTTL objects is performed in a
155 : : /// straightforward way, that is, comparing the corresponding TTL values
156 : : /// (which is the result of the \c getValue() method) as 32-bit unsigned
157 : : /// integers.
158 : : //@{
159 : : /// \brief Return true iff two RRTTLs are equal.
160 : : ///
161 : : /// This method never throws an exception.
162 : : ///
163 : : /// \param other the \c RRTTL object to compare against.
164 : : bool equals(const RRTTL& other) const
165 : 1 : { return (ttlval_ == other.ttlval_); }
166 : : /// \brief Same as \c equals().
167 : : bool operator==(const RRTTL& other) const
168 : 1891 : { return (ttlval_ == other.ttlval_); }
169 : : /// \brief Return true iff two RRTTLs are not equal.
170 : : ///
171 : : /// This method never throws an exception.
172 : : ///
173 : : /// \param other the \c RRTTL object to compare against.
174 : : bool nequals(const RRTTL& other) const
175 : 1 : { return (ttlval_ != other.ttlval_); }
176 : : /// \brief Same as \c nequals().
177 : : bool operator!=(const RRTTL& other) const
178 : 1321 : { return (ttlval_ != other.ttlval_); }
179 : : /// \brief Less-than or equal comparison for RRTTL against \c other.
180 : : ///
181 : : /// This method never throws an exception.
182 : : ///
183 : : /// \param other the \c RRTTL object to compare against.
184 : : /// \return true if \c this RRTTL is less than or equal to the \c other;
185 : : /// otherwise false.
186 : : bool leq(const RRTTL& other) const
187 : 3 : { return (ttlval_ <= other.ttlval_); }
188 : :
189 : : /// Same as \c leq()
190 : : bool operator<=(const RRTTL& other) const
191 : 3 : { return (ttlval_ <= other.ttlval_); }
192 : :
193 : : /// \brief Greater-than or equal comparison for RRTTL against \c other.
194 : : ///
195 : : /// This method never throws an exception.
196 : : ///
197 : : /// \param other the \c RRTTL object to compare against.
198 : : /// \return true if \c this RRTTL is greater than or equal to the \c other;
199 : : /// otherwise false.
200 : : bool geq(const RRTTL& other) const
201 : 3 : { return (ttlval_ >= other.ttlval_); }
202 : :
203 : : /// Same as \c geq()
204 : : bool operator>=(const RRTTL& other) const
205 : 3 : { return (ttlval_ >= other.ttlval_); }
206 : :
207 : : /// \brief Less-than comparison for RRTTL against \c other.
208 : : ///
209 : : /// This method never throws an exception.
210 : : ///
211 : : /// \param other the \c RRTTL object to compare against.
212 : : /// \return true if \c this RRTTL is less than the \c other;
213 : : /// otherwise false.
214 : : bool lthan(const RRTTL& other) const
215 : 3 : { return (ttlval_ < other.ttlval_); }
216 : :
217 : : /// Same as \c lthan()
218 : : bool operator<(const RRTTL& other) const
219 : 209 : { return (ttlval_ < other.ttlval_); }
220 : :
221 : : /// \brief Greater-than comparison for RRTTL against \c other.
222 : : ///
223 : : /// This method never throws an exception.
224 : : ///
225 : : /// \param other the \c RRTTL object to compare against.
226 : : /// \return true if \c this RRTTL is greater than the \c other;
227 : : /// otherwise false.
228 : : bool gthan(const RRTTL& other) const
229 : 3 : { return (ttlval_ > other.ttlval_); }
230 : :
231 : : /// Same as \c gthan()
232 : : bool operator>(const RRTTL& other) const
233 : 3 : { return (ttlval_ > other.ttlval_); }
234 : : //@}
235 : :
236 : : private:
237 : : uint32_t ttlval_;
238 : : };
239 : :
240 : : ///
241 : : /// \brief Insert the \c RRTTL as a string into stream.
242 : : ///
243 : : /// This method convert the \c rrttl into a string and inserts it into the
244 : : /// output stream \c os.
245 : : ///
246 : : /// This function overloads the global operator<< to behave as described in
247 : : /// ostream::operator<< but applied to \c RRTTL objects.
248 : : ///
249 : : /// \param os A \c std::ostream object on which the insertion operation is
250 : : /// performed.
251 : : /// \param rrttl The \c RRTTL object output by the operation.
252 : : /// \return A reference to the same \c std::ostream object referenced by
253 : : /// parameter \c os after the insertion operation.
254 : : std::ostream&
255 : : operator<<(std::ostream& os, const RRTTL& rrttl);
256 : : }
257 : : }
258 : : #endif // __RRTTL_H
259 : :
260 : : // Local Variables:
261 : : // mode: c++
262 : : // End:
|
