rrttl.h 9.2 KB

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