From: Dima Volodin Date: Mon, 22 Aug 2011 12:14:11 +0000 (-0400) Subject: [1140] Documentation added to spf_99.{h,cc} and detail/txt_like.h X-Git-Tag: perftcpdns_before_epoll~37^2~21^2~12 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=affa93f31bbc9719ac4e2ccc0e44d9a09c2b6a3b;p=thirdparty%2Fkea.git [1140] Documentation added to spf_99.{h,cc} and detail/txt_like.h --- diff --git a/src/lib/dns/rdata/generic/detail/txt_like.h b/src/lib/dns/rdata/generic/detail/txt_like.h index 392a8ce593..cc36e9b83f 100644 --- a/src/lib/dns/rdata/generic/detail/txt_like.h +++ b/src/lib/dns/rdata/generic/detail/txt_like.h @@ -23,8 +23,24 @@ using namespace std; using namespace isc::util; +/// \brief \c rdata::TXTLikeImpl class represents the TXT-like RDATA for TXT +/// and SPF types. +/// +/// This class implements the basic interfaces inherited by the TXT and SPF +/// classes from the abstract \c rdata::Rdata class, and provides trivial +/// accessors to TXT-like RDATA. templateclass TXTLikeImpl { public: + /// \brief Constructor from wire-format data. + /// + /// \param buffer A buffer storing the wire format data. + /// \param rdata_len The length of the RDATA in bytes, normally expected + /// to be the value of the RDLENGTH field of the corresponding RR. + /// + /// Exceptions + /// + /// \c InvalidRdataLength is thrown if rdata_len exceeds the maximum. + /// \c DNSMessageFORMERR is thrown if the RR is misformed. TXTLikeImpl(InputBuffer& buffer, size_t rdata_len) { if (rdata_len > MAX_RDLENGTH) { isc_throw(InvalidRdataLength, "RDLENGTH too large: " << rdata_len); @@ -52,6 +68,14 @@ public: } while (rdata_len > 0); } + /// \brief Constructor from string. + /// + /// Exceptions + /// + /// \c CharStringTooLong is thrown if the parameter string length exceeds + /// maximum. + /// \c InvalidRdataText is thriwn if the method cannot process the + /// parameter data. explicit TXTLikeImpl(const std::string& txtstr) { // TBD: this is a simple, incomplete implementation that only supports // a single character-string. @@ -86,10 +110,17 @@ public: string_list_.push_back(data); } + /// \brief The copy constructor. + /// + /// Trivial for now, we could've used the default one. TXTLikeImpl(const TXTLikeImpl& other) : string_list_(other.string_list_) {} + /// \brief Render the TXT-like data in the wire format to an OutputBuffer + /// object. + /// + /// \param buffer An output buffer to store the wire data. void toWire(OutputBuffer& buffer) const { for (vector >::const_iterator it = @@ -101,6 +132,11 @@ public: } } + /// \brief Render the TXT-like data in the wire format to an + /// AbstractMessageRenderer object. + /// + /// \param buffer An output AbstractMessageRenderer to send the wire data + /// to. void toWire(AbstractMessageRenderer& renderer) const { for (vector >::const_iterator it = @@ -112,6 +148,9 @@ public: } } + /// \brief Convert the TXT-like data to a string. + /// + /// \return A \c string object that represents the TXT-like data. string toText() const { string s; @@ -134,6 +173,16 @@ public: return (s); } + /// \brief Compare two instances of \c TSIG RDATA. + /// + /// It is up to the caller to make sure that \c other is an object of the + /// same \c TXTLikeImpl class. + /// + /// \param other the right-hand operand to compare against. + /// \return < 0 if \c this would be sorted before \c other. + /// \return 0 if \c this is identical to \c other in terms of sorting + /// order. + /// \return > 0 if \c this would be sorted after \c other. int compare(const TXTLikeImpl& other) const { // This implementation is not efficient. Revisit this (TBD). diff --git a/src/lib/dns/rdata/generic/spf_99.cc b/src/lib/dns/rdata/generic/spf_99.cc index 492de98551..aa3e4a13a9 100644 --- a/src/lib/dns/rdata/generic/spf_99.cc +++ b/src/lib/dns/rdata/generic/spf_99.cc @@ -30,8 +30,17 @@ using namespace isc::util; // BEGIN_ISC_NAMESPACE // BEGIN_RDATA_NAMESPACE +/// This class implements the basic interfaces inherited from the abstract +/// \c rdata::Rdata class. The semantics of the class is provided by +/// a copy of instantiated TXTLikeImpl class common to both TXT and SPF. + #include +/// \brief The assignment operator +/// +/// It internally allocates a resource, and if it fails a corresponding +/// standard exception will be thrown. +/// This method never throws an exception otherwise. SPF& SPF::operator=(const SPF& source) { if (impl_ == source.impl_) { @@ -45,37 +54,72 @@ SPF::operator=(const SPF& source) { return (*this); } +/// \brief The destructor SPF::~SPF() { delete impl_; } +/// \brief Constructor from wire-format data. +/// +/// It internally allocates a resource, and if it fails a corresponding +/// standard exception will be thrown. SPF::SPF(InputBuffer& buffer, size_t rdata_len) : impl_(new SPFImpl(buffer, rdata_len)) {} +/// \brief Constructor from string. +/// +/// It internally allocates a resource, and if it fails a corresponding +/// standard exception will be thrown. SPF::SPF(const std::string& txtstr) : impl_(new SPFImpl(txtstr)) {} +/// \brief Copy constructor +/// +/// It internally allocates a resource, and if it fails a corresponding +/// standard exception will be thrown. SPF::SPF(const SPF& other) : Rdata(), impl_(new SPFImpl(*other.impl_)) {} +/// \brief Render the \c SPF in the wire format to a OutputBuffer object +/// +/// \return is the return of the corresponding implementation method. void SPF::toWire(OutputBuffer& buffer) const { impl_->toWire(buffer); } +/// \brief Render the \c SPF in the wire format to an AbstractMessageRenderer +/// object +/// +/// \return is the return of the corresponding implementation method. void SPF::toWire(AbstractMessageRenderer& renderer) const { impl_->toWire(renderer); } +/// \brief Convert the \c SPF to a string. +/// +/// \return is the return of the corresponding implementation method. string SPF::toText() const { return (impl_->toText()); } +/// \brief Compare two instances of \c SPF RDATA. +/// +/// This method compares \c this and the \c other \c SPF objects. +/// +/// This method is expected to be used in a polymorphic way, and the +/// parameter to compare against is therefore of the abstract \c Rdata class. +/// However, comparing two \c Rdata objects of different RR types +/// is meaningless, and \c other must point to a \c SPF object; +/// otherwise, the standard \c bad_cast exception will be thrown. +/// +/// \param other the right-hand operand to compare against. +/// \return is the return of the corresponding implementation method. int SPF::compare(const Rdata& other) const { const SPF& other_txt = dynamic_cast(other); diff --git a/src/lib/dns/rdata/generic/spf_99.h b/src/lib/dns/rdata/generic/spf_99.h index 956adb9d64..04ac99b08a 100644 --- a/src/lib/dns/rdata/generic/spf_99.h +++ b/src/lib/dns/rdata/generic/spf_99.h @@ -30,14 +30,40 @@ template class TXTLikeImpl; +/// \brief \c rdata::SPF class represents the SPF RDATA as defined %in +/// RFC4408. +/// +/// This class implements the basic interfaces inherited from the abstract +/// \c rdata::Rdata class. The semantics of the class is provided by +/// a copy of instantiated TXTLikeImpl class common to both TXT and SPF. class SPF : public Rdata { public: // BEGIN_COMMON_MEMBERS // END_COMMON_MEMBERS + /// \brief Assignment operator. + /// + /// It internally allocates a resource, and if it fails a corresponding + /// standard exception will be thrown. + /// This operator never throws an exception otherwise. + /// + /// This operator provides the strong exception guarantee: When an + /// exception is thrown the content of the assignment target will be + /// intact. SPF& operator=(const SPF& source); + + /// \brief The destructor. ~SPF(); + /// + /// Specialized methods + /// + + /// \brief Return a reference to the data strings + /// + /// This method never throws an exception. + const std::vector >& getString() const; + private: typedef TXTLikeImpl SPFImpl; SPFImpl* impl_;