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
mathieu@2718
     1
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
mathieu@2718
     2
/*
mathieu@2718
     3
 * Copyright (c) 2008 INRIA
mathieu@2718
     4
 *
mathieu@2718
     5
 * This program is free software; you can redistribute it and/or modify
mathieu@2718
     6
 * it under the terms of the GNU General Public License version 2 as
mathieu@2718
     7
 * published by the Free Software Foundation;
mathieu@2718
     8
 *
mathieu@2718
     9
 * This program is distributed in the hope that it will be useful,
mathieu@2718
    10
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
mathieu@2718
    11
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
mathieu@2718
    12
 * GNU General Public License for more details.
mathieu@2718
    13
 *
mathieu@2718
    14
 * You should have received a copy of the GNU General Public License
mathieu@2718
    15
 * along with this program; if not, write to the Free Software
mathieu@2718
    16
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
mathieu@2718
    17
 *
mathieu@2718
    18
 * Authors: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
mathieu@2718
    19
 */
mathieu@2370
    20
#ifndef OBJECT_BASE_H
mathieu@2370
    21
#define OBJECT_BASE_H
mathieu@2370
    22
mathieu@2633
    23
#include "type-id.h"
mathieu@2637
    24
#include "callback.h"
mathieu@2637
    25
#include <string>
mathieu@2633
    26
mathieu@2633
    27
/**
mathieu@2633
    28
 * This macro should be invoked once for every class which
mathieu@2633
    29
 * defines a new GetTypeId method.
mathieu@2633
    30
 */
mathieu@2633
    31
#define NS_OBJECT_ENSURE_REGISTERED(type)       \
mathieu@2633
    32
  static struct X##type##RegistrationClass      \
mathieu@2633
    33
  {                                             \
mathieu@2633
    34
    X##type##RegistrationClass () {             \
mathieu@2633
    35
      ns3::TypeId tid = type::GetTypeId ();     \
mathieu@2633
    36
      tid.GetParent ();                         \
mathieu@2633
    37
    }                                           \
mathieu@2633
    38
} x_##type##RegistrationVariable
mathieu@2633
    39
mathieu@2370
    40
namespace ns3 {
mathieu@2370
    41
mathieu@2965
    42
class AttributeList;
mathieu@2965
    43
mathieu@2370
    44
/**
tomh@3182
    45
 * \ingroup object
tomh@3182
    46
 *
mathieu@2719
    47
 * \brief implement the ns-3 type and attribute system
mathieu@2719
    48
 *
mathieu@2719
    49
 * Every class which wants to integrate in the ns-3 type and attribute
mathieu@2719
    50
 * system should derive from this base class. This base class provides:
mathieu@2719
    51
 * - a way to associate an ns3::TypeId to each object instance
mathieu@2719
    52
 * - a way to set and get the attributes registered in the ns3::TypeId.
mathieu@2370
    53
 */
mathieu@2370
    54
class ObjectBase
mathieu@2370
    55
{
mathieu@2370
    56
public:
mathieu@2637
    57
  static TypeId GetTypeId (void);
mathieu@2637
    58
mathieu@2370
    59
  virtual ~ObjectBase ();
mathieu@2716
    60
mathieu@2716
    61
  /**
mathieu@2716
    62
   * \returns the TypeId associated to the most-derived type
mathieu@2716
    63
   *          of this instance.
mathieu@2716
    64
   *
mathieu@2716
    65
   * This method is typically implemented by ns3::Object::GetInstanceTypeId
mathieu@2716
    66
   * but some classes which derive from ns3::ObjectBase directly
mathieu@2716
    67
   * have to implement it themselves.
mathieu@2716
    68
   */
mathieu@2634
    69
  virtual TypeId GetInstanceTypeId (void) const = 0;
mathieu@2637
    70
mathieu@2637
    71
  /**
mathieu@2637
    72
   * \param name the name of the attribute to set
mathieu@2637
    73
   * \param value the name of the attribute to set
mathieu@2637
    74
   *
mathieu@2637
    75
   * Set a single attribute. This cannot fail: if the input is invalid,
mathieu@2637
    76
   * it will crash immediately.
mathieu@2637
    77
   */
mathieu@2965
    78
  void SetAttribute (std::string name, const AttributeValue &value);
mathieu@2637
    79
  /**
mathieu@2637
    80
   * \param name the name of the attribute to set
mathieu@2637
    81
   * \param value the name of the attribute to set
mathieu@2637
    82
   * \returns true if the requested attribute exists and could be set, 
mathieu@2637
    83
   * false otherwise.
mathieu@2637
    84
   */
mathieu@2965
    85
  bool SetAttributeFailSafe (std::string name, const AttributeValue &value);
mathieu@2637
    86
  /**
mathieu@2637
    87
   * \param name the name of the attribute to read
mathieu@2966
    88
   * \param value a reference to the value where the result should be stored.
mathieu@2637
    89
   * \returns the attribute read.
mathieu@2637
    90
   *
mathieu@2637
    91
   * If the input attribute name does not exist, this method crashes.
mathieu@2637
    92
   */
mathieu@2965
    93
  void GetAttribute (std::string name, AttributeValue &value) const;
mathieu@2716
    94
  /**
mathieu@2716
    95
   * \param name the name of the attribute to read
mathieu@2716
    96
   * \param attribute the attribute where the result value should be stored
mathieu@2716
    97
   * \returns true if the requested attribute was found, false otherwise.
mathieu@2716
    98
   *
mathieu@2716
    99
   * If the input attribute name does not exist, this method crashes.
mathieu@2716
   100
   */
mathieu@2965
   101
  bool GetAttributeFailSafe (std::string name, AttributeValue &attribute) const;
mathieu@2716
   102
mathieu@2718
   103
  /**
mathieu@2718
   104
   * \param name the name of the targetted trace source
mathieu@2718
   105
   * \param context the trace context associated to the callback
mathieu@2718
   106
   * \param cb the callback to connect to the trace source.
mathieu@2718
   107
   *
mathieu@2718
   108
   * The targetted trace source should be registered with TypeId::AddTraceSource.
mathieu@2718
   109
   */
mathieu@2718
   110
  bool TraceConnect (std::string name, std::string context, const CallbackBase &cb);
mathieu@2718
   111
  /**
mathieu@2718
   112
   * \param name the name of the targetted trace source
mathieu@2718
   113
   * \param cb the callback to connect to the trace source.
mathieu@2718
   114
   *
mathieu@2718
   115
   * The targetted trace source should be registered with TypeId::AddTraceSource.
mathieu@2718
   116
   */
mathieu@2637
   117
  bool TraceConnectWithoutContext (std::string name, const CallbackBase &cb);
mathieu@2718
   118
  /**
mathieu@2718
   119
   * \param name the name of the targetted trace source
mathieu@2718
   120
   * \param context the trace context associated to the callback
mathieu@2718
   121
   * \param cb the callback to disconnect from the trace source.
mathieu@2718
   122
   *
mathieu@2718
   123
   * The targetted trace source should be registered with TypeId::AddTraceSource.
mathieu@2718
   124
   */
mathieu@2718
   125
  bool TraceDisconnect (std::string name, std::string context, const CallbackBase &cb);
mathieu@2718
   126
  /**
mathieu@2718
   127
   * \param name the name of the targetted trace source
mathieu@2718
   128
   * \param cb the callback to disconnect from the trace source.
mathieu@2718
   129
   *
mathieu@2718
   130
   * The targetted trace source should be registered with TypeId::AddTraceSource.
mathieu@2718
   131
   */
mathieu@2637
   132
  bool TraceDisconnectWithoutContext (std::string name, const CallbackBase &cb);
mathieu@2637
   133
mathieu@2637
   134
protected:
mathieu@2718
   135
  /**
mathieu@2718
   136
   * This method is invoked once all member attributes have been 
mathieu@2718
   137
   * initialized. Subclasses can override this method to be notified
mathieu@2718
   138
   * of this event but if they do this, they must chain up to their
mathieu@2718
   139
   * parent's NotifyConstructionCompleted method.
mathieu@2718
   140
   */
mathieu@2637
   141
  virtual void NotifyConstructionCompleted (void);
mathieu@2637
   142
  /**
mathieu@2637
   143
   * \param attributes the attribute values used to initialize 
mathieu@2637
   144
   *        the member variables of this object's instance.
mathieu@2637
   145
   *
mathieu@2637
   146
   * Invoked from subclasses to initialize all of their 
mathieu@2718
   147
   * attribute members. This method will typically be invoked
mathieu@2718
   148
   * automatically from ns3::CreateObject if your class derives
mathieu@2718
   149
   * from ns3::Object. If you derive from ns3::ObjectBase directly,
mathieu@2718
   150
   * you should make sure that you invoke this method from
mathieu@2718
   151
   * your most-derived constructor.
mathieu@2637
   152
   */
mathieu@2637
   153
  void ConstructSelf (const AttributeList &attributes);
mathieu@2637
   154
mathieu@2637
   155
private:
mathieu@2965
   156
  bool DoSet (Ptr<const AttributeAccessor> spec,
mathieu@2965
   157
              Ptr<const AttributeChecker> checker, 
mathieu@2965
   158
              const AttributeValue &value);
mathieu@2637
   159
mathieu@2370
   160
};
mathieu@2370
   161
mathieu@2370
   162
} // namespace ns3
mathieu@2370
   163
mathieu@2370
   164
#endif /* OBJECT_BASE_H */