00001 /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */ 00002 /* 00003 * Copyright (c) 2008 INRIA 00004 * 00005 * This program is free software; you can redistribute it and/or modify 00006 * it under the terms of the GNU General Public License version 2 as 00007 * published by the Free Software Foundation; 00008 * 00009 * This program is distributed in the hope that it will be useful, 00010 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00012 * GNU General Public License for more details. 00013 * 00014 * You should have received a copy of the GNU General Public License 00015 * along with this program; if not, write to the Free Software 00016 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 00017 * 00018 * Authors: Mathieu Lacage <mathieu.lacage@sophia.inria.fr> 00019 */ 00020 #ifndef ATTRIBUTE_H 00021 #define ATTRIBUTE_H 00022 00023 #include <string> 00024 #include <stdint.h> 00025 #include "ptr.h" 00026 #include "ref-count-base.h" 00027 00028 namespace ns3 { 00029 00030 class AttributeAccessor; 00031 class AttributeChecker; 00032 class Attribute; 00033 class ObjectBase; 00034 00035 /** 00036 * 00037 * \ingroup core 00038 * \defgroup attribute Attribute 00039 */ 00040 00041 /** 00042 * 00043 * \ingroup attribute 00044 * 00045 * \brief Hold a value for an Attribute. 00046 * 00047 * Instances of this class should always be wrapped into an Attribute object. 00048 * Most subclasses of this base class are implemented by the 00049 * ATTRIBUTE_HELPER_* macros. 00050 */ 00051 class AttributeValue : public RefCountBase 00052 { 00053 public: 00054 AttributeValue (); 00055 virtual ~AttributeValue (); 00056 00057 /** 00058 * \returns a deep copy of this class, wrapped into an Attribute object. 00059 */ 00060 virtual Ptr<AttributeValue> Copy (void) const = 0; 00061 /** 00062 * \param checker the checker associated to the attribute 00063 * \returns a string representation of this value. 00064 * 00065 * In most cases, this method will not make any use of the checker argument. 00066 * However, in a very limited set of cases, the checker argument is needed to 00067 * perform proper serialization. A nice example of code which needs it is 00068 * the EnumValue::SerializeToString code. 00069 */ 00070 virtual std::string SerializeToString (Ptr<const AttributeChecker> checker) const = 0; 00071 /** 00072 * \param value a string representation of the value 00073 * \param checker a pointer to the checker associated to the attribute. 00074 * \returns true if the input string was correctly-formatted and could be 00075 * successfully deserialized, false otherwise. 00076 * 00077 * Upon return of this function, this AttributeValue instance contains 00078 * the deserialized value. 00079 * In most cases, this method will not make any use of the checker argument. 00080 * However, in a very limited set of cases, the checker argument is needed to 00081 * perform proper serialization. A nice example of code which needs it is 00082 * the EnumValue::SerializeToString code. 00083 */ 00084 virtual bool DeserializeFromString (std::string value, Ptr<const AttributeChecker> checker) = 0; 00085 }; 00086 00087 /** 00088 * \brief allow setting and getting the value of an attribute. 00089 * 00090 * \ingroup attribute 00091 * 00092 * The goal of this class is to hide from the user how an attribute 00093 * is actually set or get to or from a class instance. Implementations 00094 * of this base class are usually provided through the MakeAccessorHelper 00095 * template functions, hidden behind an ATTRIBUTE_HELPER_* macro. 00096 */ 00097 class AttributeAccessor : public RefCountBase 00098 { 00099 public: 00100 AttributeAccessor (); 00101 virtual ~AttributeAccessor (); 00102 00103 /** 00104 * \param object the object instance to set the value in 00105 * \param value the value to set 00106 * \returns true if the value could be set successfully, false otherwise. 00107 * 00108 * This method expects that the caller has checked that the input value is 00109 * valid with AttributeChecker::Check. 00110 */ 00111 virtual bool Set (ObjectBase * object, const AttributeValue &value) const = 0; 00112 /** 00113 * \param object the object instance to get the value from 00114 * \param attribute a pointer to where the value should be set. 00115 * \returns true if the value could be read successfully, and 00116 * stored in the input value, false otherwise. 00117 * 00118 * This method expects that the caller has checked that the input value is 00119 * valid with AttributeChecker::Check. 00120 */ 00121 virtual bool Get (const ObjectBase * object, AttributeValue &attribute) const = 0; 00122 00123 /** 00124 * \return true if this accessor supports the Get operation, false 00125 * otherwise. 00126 */ 00127 virtual bool HasGetter (void) const = 0; 00128 /** 00129 * \return true if this accessor supports the Set operation, false 00130 * otherwise. 00131 */ 00132 virtual bool HasSetter (void) const = 0; 00133 }; 00134 00135 /** 00136 * \brief Represent the type of an attribute 00137 * 00138 * \ingroup attribute 00139 * 00140 * Each type of attribute has an associated unique AttributeChecker 00141 * subclass. The type of the subclass can be safely used by users 00142 * to infer the type of the associated attribute. i.e., we expect 00143 * binding authors to use the checker associated to an attribute 00144 * to detect the type of the associated attribute. 00145 * 00146 * Most subclasses of this base class are implemented by the 00147 * ATTRIBUTE_HELPER_HEADER and ATTRIBUTE_HELPER_CPP macros. 00148 */ 00149 class AttributeChecker : public RefCountBase 00150 { 00151 public: 00152 AttributeChecker (); 00153 virtual ~AttributeChecker (); 00154 /** 00155 * \param value a pointer to the value to check 00156 * \returns true if the input value is both of the right type 00157 * and if its value is within the requested range. Returns 00158 * false otherwise. 00159 */ 00160 virtual bool Check (const AttributeValue &value) const = 0; 00161 /** 00162 * \returns the c++ fully-qualified typename of the subclass 00163 * of the ns3::AttributeValue base class which is associated 00164 * to this checker. 00165 * 00166 * A typical return value here is FooValue where Foo is the name of the 00167 * type being wrapped. 00168 */ 00169 virtual std::string GetValueTypeName (void) const = 0; 00170 /** 00171 * \returns true if this checker has information about the underlying 00172 * C++ type, false otherwise. 00173 * 00174 * If this method returns false, the return value of the GetUnderlyingTypeInformation 00175 * method cannot be relied upon. 00176 */ 00177 virtual bool HasUnderlyingTypeInformation (void) const = 0; 00178 /** 00179 * \returns a human-readable representation of information about 00180 * the underlying C++ type. 00181 */ 00182 virtual std::string GetUnderlyingTypeInformation (void) const = 0; 00183 /** 00184 * \returns a new instance of an AttributeValue (wrapper in an Attribute 00185 * instance) which matches the type of the underlying attribute. 00186 * 00187 * This method is typically used to create a temporary variable prior 00188 * to calling Attribute::DeserializeFromString. 00189 */ 00190 virtual Ptr<AttributeValue> Create (void) const = 0; 00191 00192 virtual bool Copy (const AttributeValue &source, AttributeValue &destination) const = 0; 00193 00194 }; 00195 00196 /** 00197 * \brief A class for an empty attribute value 00198 * 00199 * \ingroup attribute 00200 */ 00201 class EmptyAttributeValue : public AttributeValue 00202 { 00203 public: 00204 EmptyAttributeValue (); 00205 private: 00206 virtual Ptr<AttributeValue> Copy (void) const; 00207 virtual std::string SerializeToString (Ptr<const AttributeChecker> checker) const; 00208 virtual bool DeserializeFromString (std::string value, Ptr<const AttributeChecker> checker); 00209 }; 00210 00211 } // namespace ns3 00212 00213 #endif /* ATTRIBUTE_H */