src/core/attribute.h
 author Mathieu Lacage Mon, 02 Jun 2008 10:30:24 -0700 changeset 3190 51fe9001a679 parent 3182 61fe7fe81ebd child 3997 a66553c56a8f permissions -rw-r--r--
add some doxygen, remove a couple of XXX
     1 /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */

     2 /*

     3  * Copyright (c) 2008 INRIA

     4  *

     5  * This program is free software; you can redistribute it and/or modify

     6  * it under the terms of the GNU General Public License version 2 as

     7  * published by the Free Software Foundation;

     8  *

     9  * This program is distributed in the hope that it will be useful,

    10  * but WITHOUT ANY WARRANTY; without even the implied warranty of

    11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

    12  * GNU General Public License for more details.

    13  *

    14  * You should have received a copy of the GNU General Public License

    15  * along with this program; if not, write to the Free Software

    16  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

    17  *

    18  * Authors: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>

    19  */

    20 #ifndef ATTRIBUTE_H

    21 #define ATTRIBUTE_H

    22

    23 #include <string>

    24 #include <stdint.h>

    25 #include "ptr.h"

    26 #include "ref-count-base.h"

    27

    28 namespace ns3 {

    29

    30 class AttributeAccessor;

    31 class AttributeChecker;

    32 class Attribute;

    33 class ObjectBase;

    34

    35 /**

    36  *

    37  * \ingroup core

    38  * \defgroup attribute Attribute

    39  */

    40

    41 /**

    42  *

    43  * \ingroup attribute

    44  *

    45  * \brief Hold a value for an Attribute.

    46  *

    47  * Instances of this class should always be wrapped into an Attribute object.

    48  * Most subclasses of this base class are implemented by the

    49  * ATTRIBUTE_HELPER_* macros.

    50  */

    51 class AttributeValue : public RefCountBase

    52 {

    53 public:

    54   AttributeValue ();

    55   virtual ~AttributeValue ();

    56

    57   /**

    58    * \returns a deep copy of this class, wrapped into an Attribute object.

    59    */

    60   virtual Ptr<AttributeValue> Copy (void) const = 0;

    61   /**

    62    * \param checker the checker associated to the attribute

    63    * \returns a string representation of this value.

    64    *

    65    * In most cases, this method will not make any use of the checker argument.

    66    * However, in a very limited set of cases, the checker argument is needed to

    67    * perform proper serialization. A nice example of code which needs it is

    68    * the EnumValue::SerializeToString code.

    69    */

    70   virtual std::string SerializeToString (Ptr<const AttributeChecker> checker) const = 0;

    71   /**

    72    * \param value a string representation of the value

    73    * \param checker a pointer to the checker associated to the attribute.

    74    * \returns true if the input string was correctly-formatted and could be

    75    *          successfully deserialized, false otherwise.

    76    *

    77    * Upon return of this function, this AttributeValue instance contains

    78    * the deserialized value.

    79    * In most cases, this method will not make any use of the checker argument.

    80    * However, in a very limited set of cases, the checker argument is needed to

    81    * perform proper serialization. A nice example of code which needs it is

    82    * the EnumValue::SerializeToString code.

    83    */

    84   virtual bool DeserializeFromString (std::string value, Ptr<const AttributeChecker> checker) = 0;

    85 };

    86

    87 /**

    88  * \brief allow setting and getting the value of an attribute.

    89  *

    90  * \ingroup attribute

    91  *

    92  * The goal of this class is to hide from the user how an attribute

    93  * is actually set or get to or from a class instance. Implementations

    94  * of this base class are usually provided through the MakeAccessorHelper

    95  * template functions, hidden behind an ATTRIBUTE_HELPER_* macro.

    96  */

    97 class AttributeAccessor : public RefCountBase

    98 {

    99 public:

   100   AttributeAccessor ();

   101   virtual ~AttributeAccessor ();

   102

   103   /**

   104    * \param object the object instance to set the value in

   105    * \param value the value to set

   106    * \returns true if the value could be set successfully, false otherwise.

   107    *

   108    * This method expects that the caller has checked that the input value is

   109    * valid with AttributeChecker::Check.

   110    */

   111   virtual bool Set (ObjectBase * object, const AttributeValue &value) const = 0;

   112   /**

   113    * \param object the object instance to get the value from

   114    * \param attribute a pointer to where the value should be set.

   115    * \returns true if the value could be read successfully, and

   116    *          stored in the input value, false otherwise.

   117    *

   118    * This method expects that the caller has checked that the input value is

   119    * valid with AttributeChecker::Check.

   120    */

   121   virtual bool Get (const ObjectBase * object, AttributeValue &attribute) const = 0;

   122

   123   /**

   124    * \return true if this accessor supports the Get operation, false

   125    *         otherwise.

   126    */

   127   virtual bool HasGetter (void) const = 0;

   128   /**

   129    * \return true if this accessor supports the Set operation, false

   130    *         otherwise.

   131    */

   132   virtual bool HasSetter (void) const = 0;

   133 };

   134

   135 /**

   136  * \brief Represent the type of an attribute

   137  *

   138  * \ingroup attribute

   139  *

   140  * Each type of attribute has an associated unique AttributeChecker

   141  * subclass. The type of the subclass can be safely used by users

   142  * to infer the type of the associated attribute. i.e., we expect

   143  * binding authors to use the checker associated to an attribute

   144  * to detect the type of the associated attribute.

   145  *

   146  * Most subclasses of this base class are implemented by the

   147  * \ref ATTRIBUTE_HELPER_HEADER and \ref ATTRIBUTE_HELPER_CPP macros.

   148  */

   149 class AttributeChecker : public RefCountBase

   150 {

   151 public:

   152   AttributeChecker ();

   153   virtual ~AttributeChecker ();

   154   /**

   155    * \param value a pointer to the value to check

   156    * \returns true if the input value is both of the right type

   157    *          and if its value is within the requested range. Returns

   158    *          false otherwise.

   159    */

   160   virtual bool Check (const AttributeValue &value) const = 0;

   161   /**

   162    * \returns the c++ fully-qualified typename of the subclass

   163    *          of the ns3::AttributeValue base class which is associated

   164    *          to this checker.

   165    *

   166    * A typical return value here is FooValue where Foo is the name of the

   167    * type being wrapped.

   168    */

   169   virtual std::string GetValueTypeName (void) const = 0;

   170   /**

   171    * \returns true if this checker has information about the underlying

   172    *          C++ type, false otherwise.

   173    *

   174    * If this method returns false, the return value of the GetUnderlyingTypeInformation

   175    * method cannot be relied upon.

   176    */

   177   virtual bool HasUnderlyingTypeInformation (void) const = 0;

   178   /**

   179    * \returns a human-readable representation of information about

   180    *          the underlying C++ type.

   181    */

   182   virtual std::string GetUnderlyingTypeInformation (void) const = 0;

   183   /**

   184    * \returns a new instance of an AttributeValue (wrapper in an Attribute

   185    *          instance) which matches the type of the underlying attribute.

   186    *

   187    * This method is typically used to create a temporary variable prior

   188    * to calling Attribute::DeserializeFromString.

   189    */

   190   virtual Ptr<AttributeValue> Create (void) const = 0;

   191

   192   virtual bool Copy (const AttributeValue &source, AttributeValue &destination) const = 0;

   193

   194 };

   195

   196 /**

   197  * \brief A class for an empty attribute value

   198  *

   199  * \ingroup attribute

   200  */

   201 class EmptyAttributeValue : public AttributeValue

   202 {

   203 public:

   204   EmptyAttributeValue ();

   205 private:

   206   virtual Ptr<AttributeValue> Copy (void) const;

   207   virtual std::string SerializeToString (Ptr<const AttributeChecker> checker) const;

   208   virtual bool DeserializeFromString (std::string value, Ptr<const AttributeChecker> checker);

   209 };

   210

   211 } // namespace ns3

   212

   213 #endif /* ATTRIBUTE_H */