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 * Author: Mathieu Lacage <mathieu.lacage@sophia.inria.fr> 00019 */ 00020 #ifndef TYPE_ID_H 00021 #define TYPE_ID_H 00022 00023 #include "attribute.h" 00024 #include "attribute-accessor-helper.h" 00025 #include "attribute-helper.h" 00026 #include "callback.h" 00027 #include <string> 00028 #include <stdint.h> 00029 00030 namespace ns3 { 00031 00032 class ObjectBase; 00033 class TraceSourceAccessor; 00034 00035 /** 00036 * \brief a unique identifier for an interface. 00037 * 00038 * This class records a lot of meta-information about a 00039 * subclass of the Object base class: 00040 * - the base class of the subclass 00041 * - the set of accessible constructors in the subclass 00042 * - the set of 'attributes' accessible in the subclass 00043 */ 00044 class TypeId 00045 { 00046 public: 00047 /** 00048 * Flags describing when a given attribute can be read or written 00049 */ 00050 enum AttributeFlag { 00051 ATTR_GET = 1<<0, /**< The attribute can be read */ 00052 ATTR_SET = 1<<1, /**< The attribute can be written */ 00053 ATTR_CONSTRUCT = 1<<2, /**< The attribute can be written at construction-time */ 00054 ATTR_SGC = ATTR_GET | ATTR_SET | ATTR_CONSTRUCT, /** The attribute can be read, and written at any time */ 00055 }; 00056 00057 /** 00058 * \param name the name of the requested TypeId 00059 * \returns the unique id associated with the requested 00060 * name. 00061 * 00062 * This method cannot fail: it will crash if the input 00063 * name is not a valid TypeId name. 00064 */ 00065 static TypeId LookupByName (std::string name); 00066 /** 00067 * \param name the name of the requested TypeId 00068 * \param tid a pointer to the TypeId instance where the 00069 * result of this function should be stored. 00070 * \returns true if the requested name was found, false otherwise. 00071 */ 00072 static bool LookupByNameFailSafe (std::string name, TypeId *tid); 00073 00074 /** 00075 * \returns the number of TypeId instances registered. 00076 */ 00077 static uint32_t GetRegisteredN (void); 00078 /** 00079 * \param i index 00080 * \returns the TypeId instance whose index is i. 00081 */ 00082 static TypeId GetRegistered (uint32_t i); 00083 00084 /** 00085 * \param name the name of the interface to construct. 00086 * 00087 * No two instances can share the same name. The name is expected to be 00088 * the full c++ typename of associated c++ object. 00089 */ 00090 explicit TypeId (const char * name); 00091 00092 /** 00093 * \returns the parent of this TypeId 00094 * 00095 * This method cannot fail. It will return itself 00096 * if this TypeId has no parent. i.e., it is at the top 00097 * of the TypeId hierarchy. Currently, this is the 00098 * case for the TypeId associated to the Object class 00099 * only. 00100 */ 00101 TypeId GetParent (void) const; 00102 00103 bool HasParent (void) const; 00104 00105 /** 00106 * \param other a parent TypeId 00107 * \returns true if the input TypeId is really a parent 00108 * of this TypeId, false otherwise. 00109 * 00110 * Calling this method is roughly similar to calling dynamic_cast 00111 * except that you do not need object instances: you can do the check 00112 * with TypeId instances instead. 00113 */ 00114 bool IsChildOf (TypeId other) const; 00115 00116 /** 00117 * \returns the name of the group associated to this TypeId. 00118 */ 00119 std::string GetGroupName (void) const; 00120 00121 /** 00122 * \returns the name of this interface. 00123 */ 00124 std::string GetName (void) const; 00125 00126 /** 00127 * \returns true if this TypeId has a constructor 00128 */ 00129 bool HasConstructor (void) const; 00130 00131 /** 00132 * \returns the number of attributes associated to this TypeId 00133 */ 00134 uint32_t GetAttributeN (void) const; 00135 /** 00136 * \param i index into attribute array 00137 * \returns the name associated to the attribute whose 00138 * index is i. 00139 */ 00140 std::string GetAttributeName (uint32_t i) const; 00141 /** 00142 * \param i index into attribute array. 00143 * \returns the help text associated to the attribute whose 00144 * index is i. 00145 */ 00146 std::string GetAttributeHelp (uint32_t i) const; 00147 /** 00148 * \param i index into attribute array 00149 * \returns the full name associated to the attribute whose 00150 * index is i. 00151 */ 00152 std::string GetAttributeFullName (uint32_t i) const; 00153 00154 /** 00155 * \param i index into attribute array. 00156 * \returns the value with which the associated attribute 00157 * is initialized. 00158 */ 00159 Ptr<const AttributeValue> GetAttributeInitialValue (uint32_t i) const; 00160 /** 00161 * \param i index into attribute array. 00162 * \returns the flags associated to the requested attribute. 00163 */ 00164 uint32_t GetAttributeFlags (uint32_t i) const; 00165 /** 00166 * \param i index into attribute array. 00167 * \returns the checker associated to the requested attribute. 00168 */ 00169 Ptr<const AttributeChecker> GetAttributeChecker (uint32_t i) const; 00170 /** 00171 * \param i index into attribute array. 00172 * \returns the accessor associated to the requested attribute. 00173 */ 00174 Ptr<const AttributeAccessor> GetAttributeAccessor (uint32_t i) const; 00175 00176 /** 00177 * \returns a callback which can be used to instanciate an object 00178 * of this type. 00179 */ 00180 Callback<ObjectBase *> GetConstructor (void) const; 00181 00182 /** 00183 * \returns true if this TypeId should be hidden from the user, 00184 * false otherwise. 00185 */ 00186 bool MustHideFromDocumentation (void) const; 00187 00188 00189 /** 00190 * \returns the number of trace sources defined in this TypeId. 00191 */ 00192 uint32_t GetTraceSourceN (void) const; 00193 /** 00194 * \param i index into trace source array. 00195 * \returns the name of the requested trace source. 00196 */ 00197 std::string GetTraceSourceName (uint32_t i) const; 00198 /** 00199 * \param i index into trace source array. 00200 * \returns the help text of the requested trace source. 00201 */ 00202 std::string GetTraceSourceHelp (uint32_t i) const; 00203 /** 00204 * \param i index into trace source array. 00205 * \returns the accessor used to get access to the requested 00206 * trace source. 00207 */ 00208 Ptr<const TraceSourceAccessor> GetTraceSourceAccessor (uint32_t i) const; 00209 00210 00211 /** 00212 * \param tid the TypeId of the base class. 00213 * \return this TypeId instance. 00214 * 00215 * Record in this TypeId which TypeId is the TypeId 00216 * of the base class of the subclass. 00217 */ 00218 TypeId SetParent (TypeId tid); 00219 /** 00220 * \return this TypeId instance. 00221 * 00222 * Record in this TypeId which TypeId is the TypeId 00223 * of the base class of the subclass. 00224 */ 00225 template <typename T> 00226 TypeId SetParent (void); 00227 00228 /** 00229 * \param groupName the name of the group this TypeId belongs to. 00230 * \returns this TypeId instance. 00231 * 00232 * The group name is purely an advisory information used to 00233 * group together types according to a user-specific grouping 00234 * scheme. 00235 */ 00236 TypeId SetGroupName (std::string groupName); 00237 00238 /** 00239 * \returns this TypeId instance 00240 * 00241 * Record in this TypeId the fact that the default constructor 00242 * is accessible. 00243 */ 00244 template <typename T> 00245 TypeId AddConstructor (void); 00246 00247 /** 00248 * \param name the name of the new attribute 00249 * \param help some help text which describes the purpose of this 00250 * attribute. 00251 * \param initialValue the initial value for this attribute. 00252 * \param accessor an instance of the associated AttributeAccessor subclass. 00253 * \param checker an instance of the associated AttributeChecker subclass. 00254 * \returns this TypeId instance 00255 * 00256 * Record in this TypeId the fact that a new attribute exists. 00257 */ 00258 TypeId AddAttribute (std::string name, 00259 std::string help, 00260 const AttributeValue &initialValue, 00261 Ptr<const AttributeAccessor> accessor, 00262 Ptr<const AttributeChecker> checker); 00263 00264 /** 00265 * \param name the name of the new attribute 00266 * \param help some help text which describes the purpose of this 00267 * attribute 00268 * \param flags flags which describe how this attribute can be read and/or written. 00269 * \param initialValue the initial value for this attribute. 00270 * \param accessor an instance of the associated AttributeAccessor subclass. 00271 * \param checker an instance of the associated AttributeChecker subclass. 00272 * \returns this TypeId instance 00273 * 00274 * Record in this TypeId the fact that a new attribute exists. 00275 */ 00276 TypeId AddAttribute (std::string name, 00277 std::string help, 00278 uint32_t flags, 00279 const AttributeValue &initialValue, 00280 Ptr<const AttributeAccessor> accessor, 00281 Ptr<const AttributeChecker> checker); 00282 00283 /** 00284 * \param name the name of the new trace source 00285 * \param help some help text which describes the purpose of this 00286 * trace source. 00287 * \param accessor a pointer to a TraceSourceAccessor which can be 00288 * used to connect/disconnect sinks to this trace source. 00289 * \returns this TypeId instance. 00290 */ 00291 TypeId AddTraceSource (std::string name, 00292 std::string help, 00293 Ptr<const TraceSourceAccessor> accessor); 00294 00295 TypeId HideFromDocumentation (void); 00296 00297 /** 00298 * \brief store together a set of attribute properties. 00299 */ 00300 struct AttributeInfo { 00301 // The accessor associated to the attribute. 00302 Ptr<const AttributeAccessor> accessor; 00303 // The initial value associated to the attribute. 00304 Ptr<const AttributeValue> initialValue; 00305 // The set of access control flags associated to the attribute. 00306 uint32_t flags; 00307 // The checker associated to the attribute. 00308 Ptr<const AttributeChecker> checker; 00309 }; 00310 /** 00311 * \param name the name of the requested attribute 00312 * \param info a pointer to the TypeId::AttributeInfo data structure 00313 * where the result value of this method will be stored. 00314 * \returns true if the requested attribute could be found, false otherwise. 00315 */ 00316 bool LookupAttributeByName (std::string name, struct AttributeInfo *info) const; 00317 /** 00318 * \param name the name of the requested trace source 00319 * \returns the trace source accessor which can be used to connect and disconnect 00320 * trace sinks with the requested trace source on an object instance. 00321 * 00322 * If no matching trace source is found, this method returns zero. 00323 */ 00324 Ptr<const TraceSourceAccessor> LookupTraceSourceByName (std::string name) const; 00325 00326 /** 00327 * \returns the internal integer which uniquely identifies this 00328 * TypeId. 00329 * 00330 * This is really an internal method which users are not expected 00331 * to use. 00332 */ 00333 uint16_t GetUid (void) const; 00334 /** 00335 * \param tid the internal integer which uniquely identifies 00336 * this TypeId. 00337 * 00338 * This method is even more internal than TypeId::GetUid. Use 00339 * at your own risk and don't be surprised that it eats raw 00340 * babies on full-moon nights. 00341 */ 00342 void SetUid (uint16_t tid); 00343 00344 // construct an invalid TypeId. 00345 inline TypeId (); 00346 inline TypeId (const TypeId &o); 00347 inline TypeId &operator = (const TypeId &o); 00348 inline ~TypeId (); 00349 00350 private: 00351 friend class AttributeList; 00352 friend bool operator == (TypeId a, TypeId b); 00353 friend bool operator != (TypeId a, TypeId b); 00354 friend bool operator < (TypeId a, TypeId b); 00355 00356 00357 /** 00358 * \param fullName the full name of the requested attribute 00359 * \param info a pointer to the TypeId::AttributeInfo data structure 00360 * where the result value of this method will be stored. 00361 * \returns the Accessor associated to the requested attribute 00362 */ 00363 static bool LookupAttributeByFullName (std::string fullName, struct AttributeInfo *info); 00364 00365 explicit TypeId (uint16_t tid); 00366 void DoAddConstructor (Callback<ObjectBase *> callback); 00367 00368 uint16_t m_tid; 00369 }; 00370 00371 std::ostream & operator << (std::ostream &os, TypeId tid); 00372 std::istream & operator >> (std::istream &is, TypeId &tid); 00373 inline bool operator == (TypeId a, TypeId b); 00374 inline bool operator != (TypeId a, TypeId b); 00375 bool operator < (TypeId a, TypeId b); 00376 00377 /** 00378 * \class ns3::TypeIdValue 00379 * \brief hold objects of type ns3::TypeId 00380 */ 00381 00382 00383 ATTRIBUTE_HELPER_HEADER (TypeId); 00384 00385 } // namespace ns3 00386 00387 namespace ns3 { 00388 00389 TypeId::TypeId () 00390 : m_tid (0) {} 00391 TypeId::TypeId (const TypeId &o) 00392 : m_tid (o.m_tid) {} 00393 TypeId &TypeId::operator = (const TypeId &o) 00394 { 00395 m_tid = o.m_tid; 00396 return *this; 00397 } 00398 TypeId::~TypeId () 00399 {} 00400 inline bool operator == (TypeId a, TypeId b) 00401 { 00402 return a.m_tid == b.m_tid; 00403 } 00404 00405 inline bool operator != (TypeId a, TypeId b) 00406 { 00407 return a.m_tid != b.m_tid; 00408 } 00409 00410 00411 /************************************************************************* 00412 * The TypeId implementation which depends on templates 00413 *************************************************************************/ 00414 00415 template <typename T> 00416 TypeId 00417 TypeId::SetParent (void) 00418 { 00419 return SetParent (T::GetTypeId ()); 00420 } 00421 00422 template <typename T> 00423 TypeId 00424 TypeId::AddConstructor (void) 00425 { 00426 struct Maker { 00427 static ObjectBase * Create () { 00428 ObjectBase * base = new T (); 00429 return base; 00430 } 00431 }; 00432 Callback<ObjectBase *> cb = MakeCallback (&Maker::Create); 00433 DoAddConstructor (cb); 00434 return *this; 00435 } 00436 00437 } // namespace ns3 00438 00439 #endif /* TYPE_ID_H */