src/core/attribute.h
author Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
Sat, 04 Jul 2009 08:15:48 +0200
changeset 4654 2eaebe77d66b
parent 3190 51fe9001a679
permissions -rw-r--r--
Added tag ns-3.5 for changeset c975274c9707
mathieu@2581
     1
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
mathieu@2581
     2
/*
mathieu@2581
     3
 * Copyright (c) 2008 INRIA
mathieu@2581
     4
 *
mathieu@2581
     5
 * This program is free software; you can redistribute it and/or modify
mathieu@2581
     6
 * it under the terms of the GNU General Public License version 2 as
mathieu@2581
     7
 * published by the Free Software Foundation;
mathieu@2581
     8
 *
mathieu@2581
     9
 * This program is distributed in the hope that it will be useful,
mathieu@2581
    10
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
mathieu@2581
    11
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
mathieu@2581
    12
 * GNU General Public License for more details.
mathieu@2581
    13
 *
mathieu@2581
    14
 * You should have received a copy of the GNU General Public License
mathieu@2581
    15
 * along with this program; if not, write to the Free Software
mathieu@2581
    16
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
mathieu@2581
    17
 *
mathieu@2581
    18
 * Authors: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
mathieu@2581
    19
 */
mathieu@2438
    20
#ifndef ATTRIBUTE_H
mathieu@2438
    21
#define ATTRIBUTE_H
mathieu@2371
    22
mathieu@2371
    23
#include <string>
mathieu@2371
    24
#include <stdint.h>
mathieu@2374
    25
#include "ptr.h"
mathieu@2947
    26
#include "ref-count-base.h"
mathieu@2371
    27
mathieu@2371
    28
namespace ns3 {
mathieu@2371
    29
mathieu@2436
    30
class AttributeAccessor;
mathieu@2427
    31
class AttributeChecker;
mathieu@2433
    32
class Attribute;
mathieu@2633
    33
class ObjectBase;
mathieu@2371
    34
mathieu@2583
    35
/**
tomh@3182
    36
 *
tomh@3182
    37
 * \ingroup core
tomh@3182
    38
 * \defgroup attribute Attribute
tomh@3182
    39
 */
tomh@3182
    40
tomh@3182
    41
/**
tomh@3182
    42
 *
tomh@3182
    43
 * \ingroup attribute
tomh@3182
    44
 *
mathieu@2583
    45
 * \brief Hold a value for an Attribute.
mathieu@2583
    46
 *
mathieu@2947
    47
 * Instances of this class should always be wrapped into an Attribute object.
mathieu@2583
    48
 * Most subclasses of this base class are implemented by the 
mathieu@2583
    49
 * ATTRIBUTE_HELPER_* macros.
mathieu@2583
    50
 */
mathieu@2947
    51
class AttributeValue : public RefCountBase
mathieu@2371
    52
{
mathieu@2371
    53
public:
mathieu@2437
    54
  AttributeValue ();
mathieu@2437
    55
  virtual ~AttributeValue ();
mathieu@2374
    56
mathieu@2583
    57
  /**
mathieu@2583
    58
   * \returns a deep copy of this class, wrapped into an Attribute object.
mathieu@2583
    59
   */
mathieu@2965
    60
  virtual Ptr<AttributeValue> Copy (void) const = 0;
mathieu@2583
    61
  /**
mathieu@2583
    62
   * \param checker the checker associated to the attribute
mathieu@2583
    63
   * \returns a string representation of this value.
mathieu@2583
    64
   *
mathieu@2583
    65
   * In most cases, this method will not make any use of the checker argument.
mathieu@2583
    66
   * However, in a very limited set of cases, the checker argument is needed to
mathieu@2583
    67
   * perform proper serialization. A nice example of code which needs it is
mathieu@2583
    68
   * the EnumValue::SerializeToString code.
mathieu@2583
    69
   */
mathieu@2427
    70
  virtual std::string SerializeToString (Ptr<const AttributeChecker> checker) const = 0;
mathieu@2583
    71
  /**
mathieu@2583
    72
   * \param value a string representation of the value
mathieu@2583
    73
   * \param checker a pointer to the checker associated to the attribute.
mathieu@2583
    74
   * \returns true if the input string was correctly-formatted and could be
mathieu@2583
    75
   *          successfully deserialized, false otherwise.
mathieu@2583
    76
   *
mathieu@2583
    77
   * Upon return of this function, this AttributeValue instance contains
mathieu@2583
    78
   * the deserialized value.
mathieu@2583
    79
   * In most cases, this method will not make any use of the checker argument.
mathieu@2583
    80
   * However, in a very limited set of cases, the checker argument is needed to
mathieu@2583
    81
   * perform proper serialization. A nice example of code which needs it is
mathieu@2583
    82
   * the EnumValue::SerializeToString code.
mathieu@2583
    83
   */
mathieu@2427
    84
  virtual bool DeserializeFromString (std::string value, Ptr<const AttributeChecker> checker) = 0;
mathieu@2374
    85
};
mathieu@2374
    86
mathieu@2583
    87
/**
mathieu@2583
    88
 * \brief allow setting and getting the value of an attribute.
mathieu@2583
    89
 *
tomh@3182
    90
 * \ingroup attribute
tomh@3182
    91
 *
mathieu@2583
    92
 * The goal of this class is to hide from the user how an attribute
mathieu@2583
    93
 * is actually set or get to or from a class instance. Implementations
mathieu@2583
    94
 * of this base class are usually provided through the MakeAccessorHelper
mathieu@2583
    95
 * template functions, hidden behind an ATTRIBUTE_HELPER_* macro.
mathieu@2583
    96
 */
mathieu@2948
    97
class AttributeAccessor : public RefCountBase
mathieu@2374
    98
{
mathieu@2374
    99
public:
mathieu@2436
   100
  AttributeAccessor ();
mathieu@2436
   101
  virtual ~AttributeAccessor ();
mathieu@2371
   102
mathieu@2374
   103
  /**
mathieu@2374
   104
   * \param object the object instance to set the value in
mathieu@2374
   105
   * \param value the value to set
mathieu@2583
   106
   * \returns true if the value could be set successfully, false otherwise.
mathieu@2583
   107
   *
mathieu@2583
   108
   * This method expects that the caller has checked that the input value is
mathieu@2583
   109
   * valid with AttributeChecker::Check.
mathieu@2374
   110
   */
mathieu@2965
   111
  virtual bool Set (ObjectBase * object, const AttributeValue &value) const = 0;
mathieu@2583
   112
  /**
mathieu@2583
   113
   * \param object the object instance to get the value from
mathieu@2583
   114
   * \param attribute a pointer to where the value should be set.
mathieu@2583
   115
   * \returns true if the value could be read successfully, and
mathieu@2583
   116
   *          stored in the input value, false otherwise.
mathieu@2583
   117
   *
mathieu@2583
   118
   * This method expects that the caller has checked that the input value is
mathieu@2583
   119
   * valid with AttributeChecker::Check.
mathieu@2583
   120
   */
mathieu@2965
   121
  virtual bool Get (const ObjectBase * object, AttributeValue &attribute) const = 0;
mathieu@2950
   122
mathieu@2950
   123
  /**
mathieu@2950
   124
   * \return true if this accessor supports the Get operation, false
mathieu@2950
   125
   *         otherwise.
mathieu@2950
   126
   */
mathieu@2950
   127
  virtual bool HasGetter (void) const = 0;
mathieu@2950
   128
  /**
mathieu@2950
   129
   * \return true if this accessor supports the Set operation, false
mathieu@2950
   130
   *         otherwise.
mathieu@2950
   131
   */
mathieu@2950
   132
  virtual bool HasSetter (void) const = 0;
mathieu@2427
   133
};
mathieu@2427
   134
mathieu@2583
   135
/**
mathieu@2583
   136
 * \brief Represent the type of an attribute
mathieu@2583
   137
 *
tomh@3182
   138
 * \ingroup attribute
tomh@3182
   139
 *
mathieu@2583
   140
 * Each type of attribute has an associated unique AttributeChecker
mathieu@2583
   141
 * subclass. The type of the subclass can be safely used by users
mathieu@2583
   142
 * to infer the type of the associated attribute. i.e., we expect
mathieu@2583
   143
 * binding authors to use the checker associated to an attribute
mathieu@2583
   144
 * to detect the type of the associated attribute.
mathieu@2583
   145
 *
mathieu@2583
   146
 * Most subclasses of this base class are implemented by the 
craigdo@3997
   147
 * ATTRIBUTE_HELPER_HEADER and ATTRIBUTE_HELPER_CPP macros.
mathieu@2583
   148
 */
mathieu@2948
   149
class AttributeChecker : public RefCountBase
mathieu@2427
   150
{
mathieu@2427
   151
public:
mathieu@2427
   152
  AttributeChecker ();
mathieu@2427
   153
  virtual ~AttributeChecker ();
mathieu@2583
   154
  /**
mathieu@2583
   155
   * \param value a pointer to the value to check
mathieu@2583
   156
   * \returns true if the input value is both of the right type
mathieu@2583
   157
   *          and if its value is within the requested range. Returns
mathieu@2583
   158
   *          false otherwise.
mathieu@2583
   159
   */
mathieu@2965
   160
  virtual bool Check (const AttributeValue &value) const = 0;
mathieu@2969
   161
  /**
mathieu@2969
   162
   * \returns the c++ fully-qualified typename of the subclass
mathieu@2969
   163
   *          of the ns3::AttributeValue base class which is associated
mathieu@2969
   164
   *          to this checker.
mathieu@2969
   165
   *
mathieu@2969
   166
   * A typical return value here is FooValue where Foo is the name of the
mathieu@2969
   167
   * type being wrapped.
mathieu@2969
   168
   */
mathieu@2969
   169
  virtual std::string GetValueTypeName (void) const = 0;
mathieu@2969
   170
  /**
mathieu@2969
   171
   * \returns true if this checker has information about the underlying
mathieu@2969
   172
   *          C++ type, false otherwise.
mathieu@2969
   173
   *
mathieu@2969
   174
   * If this method returns false, the return value of the GetUnderlyingTypeInformation
mathieu@2969
   175
   * method cannot be relied upon.
mathieu@2969
   176
   */
mathieu@2969
   177
  virtual bool HasUnderlyingTypeInformation (void) const = 0;
mathieu@2969
   178
  /**
mathieu@2969
   179
   * \returns a human-readable representation of information about
mathieu@2969
   180
   *          the underlying C++ type.
mathieu@2969
   181
   */
mathieu@2969
   182
  virtual std::string GetUnderlyingTypeInformation (void) const = 0;
mathieu@2583
   183
  /**
mathieu@2583
   184
   * \returns a new instance of an AttributeValue (wrapper in an Attribute 
mathieu@2583
   185
   *          instance) which matches the type of the underlying attribute.
mathieu@2583
   186
   *
mathieu@2583
   187
   * This method is typically used to create a temporary variable prior
mathieu@2583
   188
   * to calling Attribute::DeserializeFromString.
mathieu@2583
   189
   */
mathieu@2965
   190
  virtual Ptr<AttributeValue> Create (void) const = 0;
mathieu@2965
   191
mathieu@2965
   192
  virtual bool Copy (const AttributeValue &source, AttributeValue &destination) const = 0;
mathieu@2965
   193
mathieu@2965
   194
};
mathieu@2965
   195
tomh@3182
   196
/**
tomh@3182
   197
 * \brief A class for an empty attribute value
tomh@3182
   198
 *
tomh@3182
   199
 * \ingroup attribute
tomh@3182
   200
 */
mathieu@2965
   201
class EmptyAttributeValue : public AttributeValue
mathieu@2965
   202
{
mathieu@2965
   203
public:
mathieu@2965
   204
  EmptyAttributeValue ();
mathieu@2965
   205
private:
mathieu@2965
   206
  virtual Ptr<AttributeValue> Copy (void) const;
mathieu@2965
   207
  virtual std::string SerializeToString (Ptr<const AttributeChecker> checker) const;
mathieu@2965
   208
  virtual bool DeserializeFromString (std::string value, Ptr<const AttributeChecker> checker);
mathieu@2371
   209
};
mathieu@2371
   210
mathieu@2374
   211
} // namespace ns3
mathieu@2374
   212
mathieu@2438
   213
#endif /* ATTRIBUTE_H */