src/core/type-id.h
author Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
Sat, 04 Jul 2009 08:15:48 +0200
changeset 4654 2eaebe77d66b
parent 3997 a66553c56a8f
permissions -rw-r--r--
Added tag ns-3.5 for changeset c975274c9707
mathieu@2671
     1
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
mathieu@2671
     2
/*
mathieu@2671
     3
 * Copyright (c) 2008 INRIA
mathieu@2671
     4
 *
mathieu@2671
     5
 * This program is free software; you can redistribute it and/or modify
mathieu@2671
     6
 * it under the terms of the GNU General Public License version 2 as
mathieu@2671
     7
 * published by the Free Software Foundation;
mathieu@2671
     8
 *
mathieu@2671
     9
 * This program is distributed in the hope that it will be useful,
mathieu@2671
    10
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
mathieu@2671
    11
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
mathieu@2671
    12
 * GNU General Public License for more details.
mathieu@2671
    13
 *
mathieu@2671
    14
 * You should have received a copy of the GNU General Public License
mathieu@2671
    15
 * along with this program; if not, write to the Free Software
mathieu@2671
    16
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
mathieu@2671
    17
 *
mathieu@2671
    18
 * Author: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
mathieu@2671
    19
 */
mathieu@2633
    20
#ifndef TYPE_ID_H
mathieu@2633
    21
#define TYPE_ID_H
mathieu@2633
    22
mathieu@2633
    23
#include "attribute.h"
mathieu@2633
    24
#include "attribute-accessor-helper.h"
mathieu@2633
    25
#include "attribute-helper.h"
mathieu@2633
    26
#include "callback.h"
mathieu@2633
    27
#include <string>
mathieu@2633
    28
#include <stdint.h>
mathieu@2633
    29
mathieu@2633
    30
namespace ns3 {
mathieu@2633
    31
mathieu@2633
    32
class ObjectBase;
mathieu@2633
    33
class TraceSourceAccessor;
mathieu@2633
    34
mathieu@2633
    35
/**
mathieu@2633
    36
 * \brief a unique identifier for an interface.
mathieu@2633
    37
 *
mathieu@2633
    38
 * This class records a lot of meta-information about a 
mathieu@2633
    39
 * subclass of the Object base class:
mathieu@2633
    40
 *  - the base class of the subclass
mathieu@2633
    41
 *  - the set of accessible constructors in the subclass
mathieu@2633
    42
 *  - the set of 'attributes' accessible in the subclass
mathieu@2633
    43
 */
mathieu@2633
    44
class TypeId
mathieu@2633
    45
{
mathieu@2633
    46
public:
craigdo@3997
    47
  /**
craigdo@3997
    48
   * Flags describing when a given attribute can be read or written
craigdo@3997
    49
   */
mathieu@3368
    50
  enum AttributeFlag {
craigdo@3997
    51
    ATTR_GET = 1<<0, /**< The attribute can be read */
craigdo@3997
    52
    ATTR_SET = 1<<1, /**< The attribute can be written */
craigdo@3997
    53
    ATTR_CONSTRUCT = 1<<2, /**< The attribute can be written at construction-time */
craigdo@3997
    54
    ATTR_SGC = ATTR_GET | ATTR_SET | ATTR_CONSTRUCT, /** The attribute can be read, and written at any time */
mathieu@2633
    55
  };
mathieu@2633
    56
mathieu@2633
    57
  /**
mathieu@2633
    58
   * \param name the name of the requested TypeId
mathieu@2633
    59
   * \returns the unique id associated with the requested
mathieu@2633
    60
   *          name. 
mathieu@2633
    61
   *
mathieu@2633
    62
   * This method cannot fail: it will crash if the input 
mathieu@2633
    63
   * name is not a valid TypeId name.
mathieu@2633
    64
   */
mathieu@2633
    65
  static TypeId LookupByName (std::string name);
mathieu@2633
    66
  /**
mathieu@2633
    67
   * \param name the name of the requested TypeId
mathieu@2633
    68
   * \param tid a pointer to the TypeId instance where the 
mathieu@2633
    69
   *        result of this function should be stored.
mathieu@2633
    70
   * \returns true if the requested name was found, false otherwise.
mathieu@2633
    71
   */
mathieu@2633
    72
  static bool LookupByNameFailSafe (std::string name, TypeId *tid);
mathieu@2633
    73
mathieu@2633
    74
  /**
mathieu@2633
    75
   * \returns the number of TypeId instances registered.
mathieu@2633
    76
   */
mathieu@2633
    77
  static uint32_t GetRegisteredN (void);
mathieu@2633
    78
  /**
mathieu@2633
    79
   * \param i index
mathieu@2633
    80
   * \returns the TypeId instance whose index is i.
mathieu@2633
    81
   */
mathieu@2633
    82
  static TypeId GetRegistered (uint32_t i);
mathieu@2633
    83
mathieu@2633
    84
  /**
mathieu@2633
    85
   * \param name the name of the interface to construct.
mathieu@2633
    86
   *
mathieu@2633
    87
   * No two instances can share the same name. The name is expected to be
mathieu@2633
    88
   * the full c++ typename of associated c++ object.
mathieu@2633
    89
   */
raj@3531
    90
  explicit TypeId (const char * name);
mathieu@2633
    91
mathieu@2633
    92
  /**
mathieu@2633
    93
   * \returns the parent of this TypeId
mathieu@2633
    94
   *
mathieu@2633
    95
   * This method cannot fail. It will return itself
mathieu@2633
    96
   * if this TypeId has no parent. i.e., it is at the top
mathieu@2633
    97
   * of the TypeId hierarchy. Currently, this is the
mathieu@2633
    98
   * case for the TypeId associated to the Object class 
mathieu@2633
    99
   * only.
mathieu@2633
   100
   */
mathieu@2633
   101
  TypeId GetParent (void) const;
mathieu@2633
   102
mathieu@3070
   103
  bool HasParent (void) const;
mathieu@3070
   104
mathieu@2648
   105
  /**
mathieu@2648
   106
   * \param other a parent TypeId
mathieu@2648
   107
   * \returns true if the input TypeId is really a parent
mathieu@2648
   108
   *          of this TypeId, false otherwise.
mathieu@2648
   109
   *
mathieu@2648
   110
   * Calling this method is roughly similar to calling dynamic_cast
mathieu@2648
   111
   * except that you do not need object instances: you can do the check
mathieu@2648
   112
   * with TypeId instances instead.
mathieu@2648
   113
   */
mathieu@2641
   114
  bool IsChildOf (TypeId other) const;
mathieu@2641
   115
mathieu@2633
   116
  /**
mathieu@2633
   117
   * \returns the name of the group associated to this TypeId.
mathieu@2633
   118
   */
mathieu@2633
   119
  std::string GetGroupName (void) const;
mathieu@2633
   120
mathieu@2633
   121
  /**
mathieu@2633
   122
   * \returns the name of this interface.
mathieu@2633
   123
   */
mathieu@2633
   124
  std::string GetName (void) const;
mathieu@2633
   125
mathieu@2633
   126
  /**
mathieu@2633
   127
   * \returns true if this TypeId has a constructor
mathieu@2633
   128
   */
mathieu@2633
   129
  bool HasConstructor (void) const;
mathieu@2633
   130
mathieu@2633
   131
  /**
mathieu@2633
   132
   * \returns the number of attributes associated to this TypeId
mathieu@2633
   133
   */
mathieu@2693
   134
  uint32_t GetAttributeN (void) const;
mathieu@2633
   135
  /**
mathieu@2633
   136
   * \param i index into attribute array
mathieu@2633
   137
   * \returns the name associated to the attribute whose
mathieu@2633
   138
   *          index is i.
mathieu@2633
   139
   */
mathieu@2633
   140
  std::string GetAttributeName (uint32_t i) const;
mathieu@2648
   141
  /**
mathieu@2648
   142
   * \param i index into attribute array.
mathieu@2648
   143
   * \returns the help text associated to the attribute whose
mathieu@2648
   144
   *          index is i.
mathieu@2648
   145
   */
mathieu@2633
   146
  std::string GetAttributeHelp (uint32_t i) const;
mathieu@2633
   147
  /**
mathieu@2633
   148
   * \param i index into attribute array
mathieu@2633
   149
   * \returns the full name associated to the attribute whose
mathieu@2633
   150
   *          index is i.
mathieu@2633
   151
   */
mathieu@2633
   152
  std::string GetAttributeFullName (uint32_t i) const;
mathieu@2633
   153
mathieu@2648
   154
  /**
mathieu@2648
   155
   * \param i index into attribute array.
mathieu@2648
   156
   * \returns the value with which the associated attribute 
mathieu@2648
   157
   *          is initialized.
mathieu@2648
   158
   */
mathieu@2965
   159
  Ptr<const AttributeValue> GetAttributeInitialValue (uint32_t i) const;
mathieu@2648
   160
  /**
mathieu@2648
   161
   * \param i index into attribute array.
mathieu@2648
   162
   * \returns the flags associated to the requested attribute.
mathieu@2648
   163
   */
mathieu@2633
   164
  uint32_t GetAttributeFlags (uint32_t i) const;
mathieu@2648
   165
  /**
mathieu@2648
   166
   * \param i index into attribute array.
mathieu@2648
   167
   * \returns the checker associated to the requested attribute.
mathieu@2648
   168
   */
mathieu@2633
   169
  Ptr<const AttributeChecker> GetAttributeChecker (uint32_t i) const;
mathieu@2648
   170
  /**
mathieu@2648
   171
   * \param i index into attribute array.
mathieu@2648
   172
   * \returns the accessor associated to the requested attribute.
mathieu@2648
   173
   */
mathieu@2633
   174
  Ptr<const AttributeAccessor> GetAttributeAccessor (uint32_t i) const;
mathieu@2633
   175
mathieu@2648
   176
  /**
mathieu@2648
   177
   * \returns a callback which can be used to instanciate an object
mathieu@2648
   178
   *          of this type.
mathieu@2648
   179
   */
mathieu@2633
   180
  Callback<ObjectBase *> GetConstructor (void) const;
mathieu@2633
   181
mathieu@2648
   182
  /**
mathieu@2648
   183
   * \returns true if this TypeId should be hidden from the user, 
mathieu@2648
   184
   *          false otherwise.
mathieu@2648
   185
   */
mathieu@2633
   186
  bool MustHideFromDocumentation (void) const;
mathieu@2633
   187
mathieu@2648
   188
mathieu@2648
   189
  /**
mathieu@2648
   190
   * \returns the number of trace sources defined in this TypeId.
mathieu@2648
   191
   */
mathieu@2648
   192
  uint32_t GetTraceSourceN (void) const;
mathieu@2648
   193
  /**
mathieu@2648
   194
   * \param i index into trace source array.
mathieu@2648
   195
   * \returns the name of the requested trace source.
mathieu@2648
   196
   */
mathieu@2648
   197
  std::string GetTraceSourceName (uint32_t i) const;
mathieu@2648
   198
  /**
mathieu@2648
   199
   * \param i index into trace source array.
mathieu@2648
   200
   * \returns the help text of the requested trace source.
mathieu@2648
   201
   */
mathieu@2648
   202
  std::string GetTraceSourceHelp (uint32_t i) const;
mathieu@2648
   203
  /**
mathieu@2648
   204
   * \param i index into trace source array.
mathieu@2648
   205
   * \returns the accessor used to get access to the requested
mathieu@2648
   206
   *          trace source.
mathieu@2648
   207
   */
mathieu@2648
   208
  Ptr<const TraceSourceAccessor> GetTraceSourceAccessor (uint32_t i) const;
mathieu@2648
   209
mathieu@2648
   210
mathieu@2633
   211
  /**
mathieu@2633
   212
   * \param tid the TypeId of the base class.
mathieu@2633
   213
   * \return this TypeId instance.
mathieu@2633
   214
   *
mathieu@2633
   215
   * Record in this TypeId which TypeId is the TypeId
mathieu@2633
   216
   * of the base class of the subclass.
mathieu@2633
   217
   */
mathieu@2633
   218
  TypeId SetParent (TypeId tid);
mathieu@2633
   219
  /**
mathieu@2633
   220
   * \return this TypeId instance.
mathieu@2633
   221
   *
mathieu@2633
   222
   * Record in this TypeId which TypeId is the TypeId
mathieu@2633
   223
   * of the base class of the subclass.
mathieu@2633
   224
   */
mathieu@2633
   225
  template <typename T>
mathieu@2633
   226
  TypeId SetParent (void);
mathieu@2633
   227
mathieu@2633
   228
  /**
mathieu@2633
   229
   * \param groupName the name of the group this TypeId belongs to.
mathieu@2633
   230
   * \returns this TypeId instance.
mathieu@2633
   231
   *
mathieu@2633
   232
   * The group name is purely an advisory information used to 
mathieu@2633
   233
   * group together types according to a user-specific grouping
mathieu@2633
   234
   * scheme.
mathieu@2633
   235
   */
mathieu@2633
   236
  TypeId SetGroupName (std::string groupName);
mathieu@2633
   237
mathieu@2633
   238
  /**
mathieu@2633
   239
   * \returns this TypeId instance
mathieu@2633
   240
   *
mathieu@2633
   241
   * Record in this TypeId the fact that the default constructor
mathieu@2633
   242
   * is accessible.
mathieu@2633
   243
   */
mathieu@2633
   244
  template <typename T>
mathieu@2633
   245
  TypeId AddConstructor (void);
mathieu@2633
   246
mathieu@2633
   247
  /**
mathieu@2633
   248
   * \param name the name of the new attribute
mathieu@2633
   249
   * \param help some help text which describes the purpose of this
mathieu@2633
   250
   *        attribute.
mathieu@2633
   251
   * \param initialValue the initial value for this attribute.
mathieu@2633
   252
   * \param accessor an instance of the associated AttributeAccessor subclass.
mathieu@2633
   253
   * \param checker an instance of the associated AttributeChecker subclass.
mathieu@2633
   254
   * \returns this TypeId instance
mathieu@2633
   255
   *
mathieu@2633
   256
   * Record in this TypeId the fact that a new attribute exists.
mathieu@2633
   257
   */
mathieu@2633
   258
  TypeId AddAttribute (std::string name,
mathieu@2633
   259
                       std::string help, 
mathieu@2965
   260
                       const AttributeValue &initialValue,
mathieu@2633
   261
                       Ptr<const AttributeAccessor> accessor,
mathieu@2633
   262
                       Ptr<const AttributeChecker> checker);
mathieu@2633
   263
mathieu@2633
   264
  /**
mathieu@2633
   265
   * \param name the name of the new attribute
mathieu@2633
   266
   * \param help some help text which describes the purpose of this
mathieu@2633
   267
   *        attribute
mathieu@2633
   268
   * \param flags flags which describe how this attribute can be read and/or written.
mathieu@2633
   269
   * \param initialValue the initial value for this attribute.
mathieu@2633
   270
   * \param accessor an instance of the associated AttributeAccessor subclass.
mathieu@2633
   271
   * \param checker an instance of the associated AttributeChecker subclass.
mathieu@2633
   272
   * \returns this TypeId instance
mathieu@2633
   273
   *
mathieu@2633
   274
   * Record in this TypeId the fact that a new attribute exists.
mathieu@2633
   275
   */
mathieu@2633
   276
  TypeId AddAttribute (std::string name,
mathieu@2633
   277
                       std::string help, 
mathieu@2633
   278
                       uint32_t flags,
mathieu@2965
   279
                       const AttributeValue &initialValue,
mathieu@2633
   280
                       Ptr<const AttributeAccessor> accessor,
mathieu@2633
   281
                       Ptr<const AttributeChecker> checker);
mathieu@2633
   282
mathieu@2633
   283
  /**
mathieu@2633
   284
   * \param name the name of the new trace source
mathieu@2633
   285
   * \param help some help text which describes the purpose of this
mathieu@2633
   286
   *        trace source.
mathieu@2633
   287
   * \param accessor a pointer to a TraceSourceAccessor which can be
mathieu@2633
   288
   *        used to connect/disconnect sinks to this trace source.
mathieu@2633
   289
   * \returns this TypeId instance.
mathieu@2633
   290
   */
mathieu@2633
   291
  TypeId AddTraceSource (std::string name,
mathieu@2633
   292
                         std::string help,
mathieu@2633
   293
                         Ptr<const TraceSourceAccessor> accessor);
mathieu@2633
   294
mathieu@2633
   295
  TypeId HideFromDocumentation (void);
mathieu@2633
   296
mathieu@2633
   297
  /**
mathieu@2633
   298
   * \brief store together a set of attribute properties.
mathieu@2633
   299
   */
mathieu@2633
   300
  struct AttributeInfo {
mathieu@2633
   301
    // The accessor associated to the attribute.
mathieu@2633
   302
    Ptr<const AttributeAccessor> accessor;
mathieu@2633
   303
    // The initial value associated to the attribute.
mathieu@2965
   304
    Ptr<const AttributeValue> initialValue;
mathieu@2633
   305
    // The set of access control flags associated to the attribute.
mathieu@2633
   306
    uint32_t flags;
mathieu@2633
   307
    // The checker associated to the attribute.
mathieu@2633
   308
    Ptr<const AttributeChecker> checker;
mathieu@2633
   309
  };
mathieu@2633
   310
  /**
mathieu@2633
   311
   * \param name the name of the requested attribute
mathieu@2633
   312
   * \param info a pointer to the TypeId::AttributeInfo data structure
mathieu@2633
   313
   *        where the result value of this method will be stored.
mathieu@2633
   314
   * \returns true if the requested attribute could be found, false otherwise.
mathieu@2633
   315
   */
mathieu@2633
   316
  bool LookupAttributeByName (std::string name, struct AttributeInfo *info) const;
mathieu@2719
   317
  /**
mathieu@2719
   318
   * \param name the name of the requested trace source
mathieu@2719
   319
   * \returns the trace source accessor which can be used to connect and disconnect
mathieu@2719
   320
   *          trace sinks with the requested trace source on an object instance.
mathieu@2719
   321
   *
mathieu@2719
   322
   * If no matching trace source is found, this method returns zero.
mathieu@2719
   323
   */
mathieu@2633
   324
  Ptr<const TraceSourceAccessor> LookupTraceSourceByName (std::string name) const;
mathieu@2633
   325
mathieu@4251
   326
mathieu@4251
   327
  /**
mathieu@4251
   328
   * \param fullName the full name of the requested attribute
mathieu@4251
   329
   * \param info a pointer to the TypeId::AttributeInfo data structure
mathieu@4251
   330
   *        where the result value of this method will be stored.
mathieu@4251
   331
   * \returns the Accessor associated to the requested attribute
mathieu@4251
   332
   */
mathieu@4251
   333
  static bool LookupAttributeByFullName (std::string fullName, struct AttributeInfo *info);
mathieu@4251
   334
mathieu@2670
   335
  /**
mathieu@2670
   336
   * \returns the internal integer which uniquely identifies this
mathieu@2670
   337
   *          TypeId.
mathieu@2670
   338
   *
mathieu@2670
   339
   * This is really an internal method which users are not expected
mathieu@2670
   340
   * to use.
mathieu@2670
   341
   */
mathieu@2644
   342
  uint16_t GetUid (void) const;
mathieu@2670
   343
  /**
mathieu@2670
   344
   * \param tid the internal integer which uniquely identifies 
mathieu@2670
   345
   *        this TypeId.
mathieu@2670
   346
   *
mathieu@2670
   347
   * This method is even more internal than TypeId::GetUid. Use
mathieu@2670
   348
   * at your own risk and don't be surprised that it eats raw 
mathieu@2670
   349
   * babies on full-moon nights.
mathieu@2670
   350
   */
mathieu@2644
   351
  void SetUid (uint16_t tid);
mathieu@2633
   352
mathieu@2633
   353
  // construct an invalid TypeId.
mathieu@3870
   354
  inline TypeId ();
mathieu@3870
   355
  inline TypeId (const TypeId &o);
mathieu@3870
   356
  inline TypeId &operator = (const TypeId &o);
mathieu@3870
   357
  inline ~TypeId ();
mathieu@2633
   358
mathieu@2633
   359
private:
mathieu@2633
   360
  friend class AttributeList;
mathieu@2633
   361
  friend bool operator == (TypeId a, TypeId b);
mathieu@2633
   362
  friend bool operator != (TypeId a, TypeId b);
mathieu@2939
   363
  friend bool operator <  (TypeId a, TypeId b);
mathieu@2633
   364
mathieu@2633
   365
mathieu@2633
   366
  explicit TypeId (uint16_t tid);
mathieu@2633
   367
  void DoAddConstructor (Callback<ObjectBase *> callback);
mathieu@2633
   368
  
mathieu@2633
   369
  uint16_t m_tid;
mathieu@2633
   370
};
mathieu@2633
   371
mathieu@2633
   372
std::ostream & operator << (std::ostream &os, TypeId tid);
mathieu@2633
   373
std::istream & operator >> (std::istream &is, TypeId &tid);
mathieu@3871
   374
inline bool operator == (TypeId a, TypeId b);
mathieu@3871
   375
inline bool operator != (TypeId a, TypeId b);
mathieu@2939
   376
bool operator <  (TypeId a, TypeId b);
mathieu@2939
   377
mathieu@2969
   378
/**
mathieu@2969
   379
 * \class ns3::TypeIdValue
mathieu@2969
   380
 * \brief hold objects of type ns3::TypeId
mathieu@2969
   381
 */
mathieu@2969
   382
mathieu@2633
   383
mathieu@3094
   384
ATTRIBUTE_HELPER_HEADER (TypeId);
mathieu@2633
   385
mathieu@2633
   386
} // namespace ns3 
mathieu@2633
   387
mathieu@2638
   388
namespace ns3 {
mathieu@2638
   389
mathieu@3870
   390
TypeId::TypeId ()
mathieu@3870
   391
  : m_tid (0) {}
mathieu@3870
   392
TypeId::TypeId (const TypeId &o)
mathieu@3870
   393
  : m_tid (o.m_tid) {}
mathieu@3870
   394
TypeId &TypeId::operator = (const TypeId &o)
mathieu@3870
   395
{
mathieu@3870
   396
  m_tid = o.m_tid;
mathieu@3870
   397
  return *this;
mathieu@3870
   398
}
mathieu@3870
   399
TypeId::~TypeId ()
mathieu@3870
   400
{}
mathieu@3871
   401
inline bool operator == (TypeId a, TypeId b)
mathieu@3871
   402
{
mathieu@3871
   403
  return a.m_tid == b.m_tid;
mathieu@3871
   404
}
mathieu@3871
   405
mathieu@3871
   406
inline bool operator != (TypeId a, TypeId b)
mathieu@3871
   407
{
mathieu@3871
   408
  return a.m_tid != b.m_tid;
mathieu@3871
   409
}
mathieu@3870
   410
mathieu@3870
   411
mathieu@2638
   412
/*************************************************************************
mathieu@2638
   413
 *   The TypeId implementation which depends on templates
mathieu@2638
   414
 *************************************************************************/
mathieu@2638
   415
mathieu@2638
   416
template <typename T>
mathieu@2638
   417
TypeId 
mathieu@2638
   418
TypeId::SetParent (void)
mathieu@2638
   419
{
mathieu@2638
   420
  return SetParent (T::GetTypeId ());
mathieu@2638
   421
}
mathieu@2638
   422
mathieu@2638
   423
template <typename T>
mathieu@2638
   424
TypeId 
mathieu@2638
   425
TypeId::AddConstructor (void)
mathieu@2638
   426
{
mathieu@2638
   427
  struct Maker {
mathieu@2638
   428
    static ObjectBase * Create () {
mathieu@2638
   429
      ObjectBase * base = new T ();
mathieu@2638
   430
      return base;
mathieu@2638
   431
    }
mathieu@2638
   432
  };
mathieu@2638
   433
  Callback<ObjectBase *> cb = MakeCallback (&Maker::Create);
mathieu@2638
   434
  DoAddConstructor (cb);
mathieu@2638
   435
  return *this;
mathieu@2638
   436
}
mathieu@2638
   437
mathieu@2638
   438
} // namespace ns3
mathieu@2638
   439
mathieu@2633
   440
#endif /* TYPE_ID_H */