src/core/attribute.h
author Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
Sat, 04 Jul 2009 08:15:48 +0200
changeset 4654 2eaebe77d66b
parent 3190 51fe9001a679
permissions -rw-r--r--
Added tag ns-3.5 for changeset c975274c9707
     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  * ATTRIBUTE_HELPER_HEADER and 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 */