src/core/object-base.h
author Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
Sat, 04 Jul 2009 08:15:48 +0200
changeset 4654 2eaebe77d66b
parent 2966 0116649f03f8
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 OBJECT_BASE_H
    21 #define OBJECT_BASE_H
    22 
    23 #include "type-id.h"
    24 #include "callback.h"
    25 #include <string>
    26 
    27 /**
    28  * This macro should be invoked once for every class which
    29  * defines a new GetTypeId method.
    30  */
    31 #define NS_OBJECT_ENSURE_REGISTERED(type)       \
    32   static struct X##type##RegistrationClass      \
    33   {                                             \
    34     X##type##RegistrationClass () {             \
    35       ns3::TypeId tid = type::GetTypeId ();     \
    36       tid.GetParent ();                         \
    37     }                                           \
    38 } x_##type##RegistrationVariable
    39 
    40 namespace ns3 {
    41 
    42 class AttributeList;
    43 
    44 /**
    45  * \ingroup object
    46  *
    47  * \brief implement the ns-3 type and attribute system
    48  *
    49  * Every class which wants to integrate in the ns-3 type and attribute
    50  * system should derive from this base class. This base class provides:
    51  * - a way to associate an ns3::TypeId to each object instance
    52  * - a way to set and get the attributes registered in the ns3::TypeId.
    53  */
    54 class ObjectBase
    55 {
    56 public:
    57   static TypeId GetTypeId (void);
    58 
    59   virtual ~ObjectBase ();
    60 
    61   /**
    62    * \returns the TypeId associated to the most-derived type
    63    *          of this instance.
    64    *
    65    * This method is typically implemented by ns3::Object::GetInstanceTypeId
    66    * but some classes which derive from ns3::ObjectBase directly
    67    * have to implement it themselves.
    68    */
    69   virtual TypeId GetInstanceTypeId (void) const = 0;
    70 
    71   /**
    72    * \param name the name of the attribute to set
    73    * \param value the name of the attribute to set
    74    *
    75    * Set a single attribute. This cannot fail: if the input is invalid,
    76    * it will crash immediately.
    77    */
    78   void SetAttribute (std::string name, const AttributeValue &value);
    79   /**
    80    * \param name the name of the attribute to set
    81    * \param value the name of the attribute to set
    82    * \returns true if the requested attribute exists and could be set, 
    83    * false otherwise.
    84    */
    85   bool SetAttributeFailSafe (std::string name, const AttributeValue &value);
    86   /**
    87    * \param name the name of the attribute to read
    88    * \param value a reference to the value where the result should be stored.
    89    * \returns the attribute read.
    90    *
    91    * If the input attribute name does not exist, this method crashes.
    92    */
    93   void GetAttribute (std::string name, AttributeValue &value) const;
    94   /**
    95    * \param name the name of the attribute to read
    96    * \param attribute the attribute where the result value should be stored
    97    * \returns true if the requested attribute was found, false otherwise.
    98    *
    99    * If the input attribute name does not exist, this method crashes.
   100    */
   101   bool GetAttributeFailSafe (std::string name, AttributeValue &attribute) const;
   102 
   103   /**
   104    * \param name the name of the targetted trace source
   105    * \param context the trace context associated to the callback
   106    * \param cb the callback to connect to the trace source.
   107    *
   108    * The targetted trace source should be registered with TypeId::AddTraceSource.
   109    */
   110   bool TraceConnect (std::string name, std::string context, const CallbackBase &cb);
   111   /**
   112    * \param name the name of the targetted trace source
   113    * \param cb the callback to connect to the trace source.
   114    *
   115    * The targetted trace source should be registered with TypeId::AddTraceSource.
   116    */
   117   bool TraceConnectWithoutContext (std::string name, const CallbackBase &cb);
   118   /**
   119    * \param name the name of the targetted trace source
   120    * \param context the trace context associated to the callback
   121    * \param cb the callback to disconnect from the trace source.
   122    *
   123    * The targetted trace source should be registered with TypeId::AddTraceSource.
   124    */
   125   bool TraceDisconnect (std::string name, std::string context, const CallbackBase &cb);
   126   /**
   127    * \param name the name of the targetted trace source
   128    * \param cb the callback to disconnect from the trace source.
   129    *
   130    * The targetted trace source should be registered with TypeId::AddTraceSource.
   131    */
   132   bool TraceDisconnectWithoutContext (std::string name, const CallbackBase &cb);
   133 
   134 protected:
   135   /**
   136    * This method is invoked once all member attributes have been 
   137    * initialized. Subclasses can override this method to be notified
   138    * of this event but if they do this, they must chain up to their
   139    * parent's NotifyConstructionCompleted method.
   140    */
   141   virtual void NotifyConstructionCompleted (void);
   142   /**
   143    * \param attributes the attribute values used to initialize 
   144    *        the member variables of this object's instance.
   145    *
   146    * Invoked from subclasses to initialize all of their 
   147    * attribute members. This method will typically be invoked
   148    * automatically from ns3::CreateObject if your class derives
   149    * from ns3::Object. If you derive from ns3::ObjectBase directly,
   150    * you should make sure that you invoke this method from
   151    * your most-derived constructor.
   152    */
   153   void ConstructSelf (const AttributeList &attributes);
   154 
   155 private:
   156   bool DoSet (Ptr<const AttributeAccessor> spec,
   157               Ptr<const AttributeChecker> checker, 
   158               const AttributeValue &value);
   159 
   160 };
   161 
   162 } // namespace ns3
   163 
   164 #endif /* OBJECT_BASE_H */