[svn] commit: r2842 - /branches/trac311/src/lib/dns/edns.h
BIND 10 source code commits
bind10-changes at lists.isc.org
Sat Aug 28 05:58:10 UTC 2010
Author: jinmei
Date: Sat Aug 28 05:58:09 2010
New Revision: 2842
Log:
described EDNS constructors
Modified:
branches/trac311/src/lib/dns/edns.h
Modified: branches/trac311/src/lib/dns/edns.h
==============================================================================
--- branches/trac311/src/lib/dns/edns.h (original)
+++ branches/trac311/src/lib/dns/edns.h Sat Aug 28 05:58:09 2010
@@ -54,7 +54,7 @@
/// note: extended Rcode is handled in the Message class. We may want to
/// generalize this by passing the whole Message and letting the \c EDNS
/// object modify or refer to it based on the EDNS protocol. But it would
-/// couple the \c Message and \c EDNS more tightly. Right now, our decision
+/// couple the \c Message and \c EDNS more tightly. Right now, the decision
/// is to consider \c Rcode is a special case; if a future version of the EDNS
/// protocol introduces further relationship between the message and the EDNS,
/// we might reconsider the interface, probably with higher abstraction.
@@ -66,7 +66,7 @@
/// once we support EDNS options.
/// (Note to ourselves: the python binding assumes this class is copyable).
///
-///TBD: how to manage options is an open issue.
+/// TBD: how to manage options is an open issue.
class EDNS {
public:
///
@@ -76,13 +76,91 @@
/// and default destructors intentionally.
///
//@{
- /// By default, the highest supported version is assumed.
+ /// Constructor with the EDNS version.
+ /// An application would use this constructor to specify EDNS parameters
+ /// and/or options for outgoing DNS messages.
+ ///
+ /// All other parameters than the version number will be initialized to
+ /// reasonable defaults.
+ /// Specifically, the UDP buffer size is set to
+ /// \c Message::DEFAULT_MAX_UDPSIZE, and DNSSEC is assumed to be not
+ /// supported.
+ /// These parameters can be altered via setter methods of this class.
+ /// Note, however, that the version number cannot be changed once
+ /// constructed.
+ ///
+ /// The version number parameter can be omitted, in which case the highest
+ /// supported version in this implementation will be assumed.
+ /// When specified, if it is larger than the highest supported version,
+ /// an exception of class \c isc::InvalidParameter will be thrown.
+ ///
+ /// This constructor throws no other exception.
+ ///
+ /// \param version The version number of the EDNS to be constructed.
explicit EDNS(const uint8_t version = SUPPORTED_VERSION);
+ /// \brief Constructor from resource record (RR) parameters.
+ ///
+ /// This constructor is intended to be used to construct an EDNS object
+ /// from an OPT RR contained in an incoming DNS message.
+ ///
+ /// Unlike many other constructors for this purpose, this constructor
+ /// does not take the bare wire-format %data in the form of an
+ /// \c InputBuffer object. This is because parsing incoming EDNS is
+ /// highly context dependent and it's not feasible to handle it in a
+ /// completely polymorphic way. For example, a DNS message parser would
+ /// have to check an OPT RR appears at most once in the message, and if
+ /// it appears it should be in the additional section. So, the parser
+ /// needs to have an explicit check to see if an RR is of type OPT, and
+ /// then (if other conditions are met) construct a corresponding \c EDNS
+ /// object. At that point the parser would have already converted the
+ /// wire %data into corresponding objects of \c Name, \c RRClass,
+ /// \c RRType, etc, and it makes more sense to pass them directly to the
+ /// constructor.
+ ///
+ /// In practice, top level applications rarely need to use this
+ /// constructor directly. It should normally suffice to have a higher
+ /// level class such as \c Message do that job.
+ ///
+ /// This constructor checks the passed parameters to see if they are
+ /// valid in terms of the EDNS protocol specification.
+ /// \c name must be the root name ("."); otherwise, an exception of
+ /// class \c DNSMessageFORMERR will be thrown.
+ /// \c rrtype must specify the OPT RR type; otherwise, an exception of
+ /// class \c isc::InvalidParameter will be thrown.
+ /// The ENDS version number is extracted from \c rrttl. If it is larger
+ /// than the higher supported version, an exception of class
+ /// \c DNSMessageBADVERS will be thrown. Note that this is different from
+ /// the case of the same error in the other constructor.
+ /// This is intentional, so that the application can transparently convert
+ /// the exception to a response RCODE according to the protocol
+ /// specification.
+ ///
+ /// In this initial implementation does not support EDNS options at all,
+ /// and \c rdata is simply ignored. Future versions will support
+ /// options, and may throw exceptions while validating the given parameter.
+ ///
+ /// Note: since no other type than OPT for \c rrtype is allowed, this
+ /// parameter could actually have been omitted. But it is intentionally
+ /// included as a parameter so that invalid usage of the construction
+ /// can be detected. As noted above the caller should normally have
+ /// the corresponding \c RRType object at the time of call to this
+ /// constructor, so the overhead of having the additional parameter
+ /// should be marginal.
+ ///
+ /// \param name The owner name of the OPT RR. This must be the root name.
+ /// \param rrclass The RR class of the OPT RR.
+ /// \param rrtype This must specify the OPT RR type.
+ /// \param rrttl The TTL of the OPT RR.
+ /// \param rdata The RDATA of the OPT RR.
EDNS(const Name& name, const RRClass& rrclass, const RRType& rrtype,
const RRTTL& ttl, const rdata::Rdata& rdata);
//@}
+ ///
+ /// \name Getter and Setter Methods
+ ///
+ //@{
/// \brief Returns the version of EDNS.
uint8_t getVersion() const { return (version_); }
@@ -102,26 +180,34 @@
/// \brief Return whether the message sender indicates DNSSEC is supported.
///
- /// \return TBD
+ /// \return true if the
bool isDNSSECSupported() const { return (dnssec_ok_); }
/// \brief Specify whether DNSSEC is supported in the message.
void setDNSSECSupported(const bool on) { dnssec_ok_ = on; }
-
- // In the current implementation the return value is either 0 or 1, but
- // the return type is <code>unsigned int</code> to be consistent with
- // RRset::toWire(). In any case the caller shouldn't assume these are
- // only possible return values from this method.
+ //@}
+
+ ///
+ /// \name Converter Methods
+ ///
+ //@{
+ /// \brief
+ ///
+ /// In the current implementation the return value is either 0 or 1, but
+ /// the return type is <code>unsigned int</code> to be consistent with
+ /// RRset::toWire(). In any case the caller shouldn't assume these are
+ /// only possible return values from this method.
unsigned int toWire(MessageRenderer& renderer,
const uint8_t extended_rcode) const;
unsigned int toWire(OutputBuffer& buffer,
const uint8_t extended_rcode) const;
- /// TBD
+ /// \brief Convert the EDNS to a string.
std::string toText() const;
-
- // TBD: currently not implemented. We'll eventually need something like
- // this.
+ //@}
+
+ // TBD: This method is currently not implemented. We'll eventually need
+ // something like this.
//void addOption();
private:
@@ -153,6 +239,7 @@
const RRType& rrtype, const RRTTL& ttl,
const rdata::Rdata& rdata, uint8_t& extended_rcode);
+/// \brief
std::ostream& operator<<(std::ostream& os, const EDNS& edns);
}
}
More information about the bind10-changes
mailing list