--- a/src/core/attribute.h Mon Mar 10 00:46:44 2008 +0100
+++ b/src/core/attribute.h Mon Mar 10 13:09:32 2008 -0700
@@ -31,6 +31,14 @@
class AttributeChecker;
class Attribute;
+/**
+ * \brief Hold a value for an Attribute.
+ *
+ * Instances of this class are usually created by Attribute::Create<> and
+ * should always be wrapped into an Attribute object.
+ * Most subclasses of this base class are implemented by the
+ * ATTRIBUTE_HELPER_* macros.
+ */
class AttributeValue
{
public:
@@ -39,14 +47,49 @@
AttributeValue &operator = (const AttributeValue &o);
virtual ~AttributeValue ();
+ /**
+ * \returns a deep copy of this class, wrapped into an Attribute object.
+ */
virtual Attribute Copy (void) const = 0;
+ /**
+ * \param checker the checker associated to the attribute
+ * \returns a string representation of this value.
+ *
+ * In most cases, this method will not make any use of the checker argument.
+ * However, in a very limited set of cases, the checker argument is needed to
+ * perform proper serialization. A nice example of code which needs it is
+ * the EnumValue::SerializeToString code.
+ */
virtual std::string SerializeToString (Ptr<const AttributeChecker> checker) const = 0;
+ /**
+ * \param value a string representation of the value
+ * \param checker a pointer to the checker associated to the attribute.
+ * \returns true if the input string was correctly-formatted and could be
+ * successfully deserialized, false otherwise.
+ *
+ * Upon return of this function, this AttributeValue instance contains
+ * the deserialized value.
+ * In most cases, this method will not make any use of the checker argument.
+ * However, in a very limited set of cases, the checker argument is needed to
+ * perform proper serialization. A nice example of code which needs it is
+ * the EnumValue::SerializeToString code.
+ */
virtual bool DeserializeFromString (std::string value, Ptr<const AttributeChecker> checker) = 0;
private:
friend class Attribute;
uint32_t m_count;
};
+/**
+ * \brief an opaque wrapper around a value to set or retrieved
+ * from an attribute.
+ *
+ * This class is really a smart pointer to an instance of AttributeValue.
+ * Of course, the question is "why not use a Ptr<AttributeValue>" ?. The
+ * answer is long and complicated but the crux of the issue is that if we
+ * do not reproduce the smart pointer code in this class, we cannot provide
+ * transparent handling of Ptr<T> values through the attribute system.
+ */
class Attribute
{
public:
@@ -55,20 +98,51 @@
Attribute &operator = (const Attribute &o);
~Attribute ();
+ /**
+ * Forward to AttributeValue::Copy
+ */
Attribute Copy (void) const;
+ /**
+ * Forward to AttributeValue::SerializeToString
+ */
std::string SerializeToString (Ptr<const AttributeChecker> checker) const;
+ /**
+ * Forward to AttributeValue::DeserializeFromString
+ */
bool DeserializeFromString (std::string value, Ptr<const AttributeChecker> checker);
+ /**
+ * \returns a new Attribute object which wraps an instance of the requested
+ * subclass of AttributeValue.
+ */
template <typename T>
static Attribute Create (void);
+ /**
+ * \param a1 a value to pass through to the constructor of the class T.
+ * \returns a new Attribute object which wraps an instance of the requested
+ * subclass of AttributeValue.
+ */
template <typename T, typename T1>
static Attribute Create (T1 a1);
+ /**
+ * This method performs a dynamic_cast on the underlying AttributeValue.
+ * This method is typically used to implement conversion operators
+ * from the type Attribute. In most cases, these conversion operators
+ * will be generated for you by the ATTRIBUTE_HELPER_* macros.
+ * \returns the casted pointer.
+ */
template <typename T>
T DynCast (void) const;
+ /**
+ * \param pointer a pointer to convert into an Attribute.
+ */
template <typename T>
Attribute (Ptr<T> pointer);
+ /**
+ * \returns a pointer converted from this Attribute instance.
+ */
template <typename T>
operator Ptr<T> ();
@@ -77,6 +151,14 @@
AttributeValue *m_value;
};
+/**
+ * \brief allow setting and getting the value of an attribute.
+ *
+ * The goal of this class is to hide from the user how an attribute
+ * is actually set or get to or from a class instance. Implementations
+ * of this base class are usually provided through the MakeAccessorHelper
+ * template functions, hidden behind an ATTRIBUTE_HELPER_* macro.
+ */
class AttributeAccessor : public ObjectBase
{
public:
@@ -88,15 +170,38 @@
/**
* \param object the object instance to set the value in
* \param value the value to set
- * \returns true if the value is valid and it could be set
- * successfully, false otherwise.
+ * \returns true if the value could be set successfully, false otherwise.
+ *
+ * This method expects that the caller has checked that the input value is
+ * valid with AttributeChecker::Check.
*/
virtual bool Set (ObjectBase * object, Attribute value) const = 0;
+ /**
+ * \param object the object instance to get the value from
+ * \param attribute a pointer to where the value should be set.
+ * \returns true if the value could be read successfully, and
+ * stored in the input value, false otherwise.
+ *
+ * This method expects that the caller has checked that the input value is
+ * valid with AttributeChecker::Check.
+ */
virtual bool Get (const ObjectBase * object, Attribute value) const = 0;
private:
mutable uint32_t m_count;
};
+/**
+ * \brief Represent the type of an attribute
+ *
+ * Each type of attribute has an associated unique AttributeChecker
+ * subclass. The type of the subclass can be safely used by users
+ * to infer the type of the associated attribute. i.e., we expect
+ * binding authors to use the checker associated to an attribute
+ * to detect the type of the associated attribute.
+ *
+ * Most subclasses of this base class are implemented by the
+ * ATTRIBUTE_HELPER_* macros.
+ */
class AttributeChecker : public ObjectBase
{
public:
@@ -104,7 +209,20 @@
void Ref (void) const;
void Unref (void) const;
virtual ~AttributeChecker ();
+ /**
+ * \param value a pointer to the value to check
+ * \returns true if the input value is both of the right type
+ * and if its value is within the requested range. Returns
+ * false otherwise.
+ */
virtual bool Check (Attribute value) const = 0;
+ /**
+ * \returns a new instance of an AttributeValue (wrapper in an Attribute
+ * instance) which matches the type of the underlying attribute.
+ *
+ * This method is typically used to create a temporary variable prior
+ * to calling Attribute::DeserializeFromString.
+ */
virtual Attribute Create (void) const = 0;
private:
mutable uint32_t m_count;